/executing

name: executing
description: Autonomous task implementation workflow — implement, test, review, commit for each task in the frontier

Executing Skill

This skill guides the per-task implementation cycle during `/forge execute`. For each task in the frontier, you follow a structured workflow: read the spec, implement, test, review, commit, and update state. The Stop hook drives task-to-task progression; this skill handles the work within a single task.

Inputs

You will receive:

• **Task ID and name**: From the frontier (e.g., `T003: Registration endpoint + tests`)
• **Spec file path**: Location of the spec with acceptance criteria (e.g., `.forge/specs/spec-auth.md`)
• **Depth**: `quick`, `standard`, or `thorough`
• **Capabilities**: From `.forge/capabilities.json` (optional, informs tool choices)
• **Repo config**: From `.forge/config.json` (which repo to work in, conventions to follow)

Procedure

Step 1: Read Context

1. **Read current state** from `.forge/state.md` — check what task you are on, what is already done, any in-flight work or key decisions from prior tasks. 2. **Read the frontier** from `.forge/plans/{spec}-frontier.md` — find your current task, understand its dependencies, and what comes after. 3. **Read the spec** from `.forge/specs/spec-{domain}.md` — find the R-numbered requirements and acceptance criteria that this task must satisfy. Identify the exact checkboxes you need to check off. 4. **Read capabilities** from `.forge/capabilities.json` if it exists — check for available MCP servers (Context7 for docs, Playwright for E2E, MongoDB for data inspection) and skills (TDD, systematic debugging, code review). 5. **Cited-docs pass (forge-self-fixes R009).** Before moving to Step 2, list every external document the spec references and read each one. Run:

   node scripts/forge-tools.cjs list-cited-docs --spec .forge/specs/spec-{domain}.md --repo-root .

The CLI returns a JSON array of `{ line, path }` for absolute, home-relative, and sibling-repo paths. For each returned path, use `Read` to open the document before writing any implementation code. If a path does not resolve, log a warning to state.md decisions and continue — do NOT fabricate values that were supposed to come from the cited doc. This closes the gap from the 2026-04-21 forge-landing run where the executor fabricated benchmark numbers instead of reading the source doc the spec had cited.

Step 2: Prepare the Workspace

1. **Multi-repo**: If the task has a `repo:` tag, `cd` into the correct repo directory (from `.forge/config.json` repos). Read that repo's CLAUDE.md or coding conventions file first. 2. **Single-repo**: Stay in the current directory. Read CLAUDE.md if it exists. 3. **Conventions**: Note the project's coding style, naming conventions, import patterns, test framework, and commit message format. Follow them exactly. 4. **UI-task detection (forge-self-fixes R003).** Run the classifier to decide whether this task needs the design-skill routing:

   node scripts/forge-tools.cjs task-classify \
     --task-id T00N \
     --spec .forge/specs/spec-{domain}.md \
     --capabilities .forge/capabilities.json

The output shape is `{ ui:boolean, brand:string|null, reasons:[...] }`. If `ui` is true you MUST, before writing any component code in Step 3:

• Invoke `Skill("frontend-design")` once for general design-quality guidance, AND
• If `brand` is non-null, also invoke the brand-specific skill: `Skill("brand-guidelines")` for Anthropic, or reference the awesome-design-md catalog for other named brands.
• If a `DESIGN.md` exists at repo root, read it first and cite specific tokens in your component code rather than picking tokens from memory.

This is the execution-side counterpart to the R002 DESIGN.md gate in the brainstorming skill. The brainstorm skill wrote the tokens; the executor reads them. The 2026-04-21 forge-landing regression was an executor that wrote an "Anthropic-aesthetic" landing page without either step, so the tokens shipped as approximations. This block closes that loop.

Step 3: Implement the Task

The implementation approach depends on the depth level and available capabilities:

Depth: Thorough (or TDD skill available)

1. **Write failing tests first.** Based on the acceptance criteria, write test cases that define the expected behavior. Run them to confirm they fail. 2. **Implement the feature** to make the tests pass. Write the minimum code needed. 3. **Run all tests** (not just the new ones) to ensure nothing is broken. 4. **Refactor** if needed — clean up while tests are green.

Depth: Standard

1. **Implement the feature** based on the acceptance criteria. 2. **Write tests** after implementation — cover happy paths and key error cases from the acceptance criteria. 3. **Run all tests** to confirm everything passes.

Depth: Quick

1. **Implement the feature** based on the acceptance criteria. 2. **Run existing tests** if there is an existing test suite. Do not write new tests unless the project requires it. 3. If no test suite exists, manually verify the implementation satisfies the acceptance criteria.

Implementation Guidelines

• **Read before writing.** Before creating new files, search for existing patterns in the codebase. Follow established conventions (file structure, naming, imports, error handling).
• **One concern per file.** Do not stuff unrelated logic into existing files.
• **Error handling.** Implement error cases from the acceptance criteria, not just the happy path.
• **No stubs.** Every function must have a real implementation. Do not leave `// TODO` or `throw new Error('not implemented')`.
• **No over-engineering.** Implement exactly what the spec requires. If the acceptance criteria do not ask for it, do not build it.

Step 4: Run Tests and Fix Failures (Inner Loop)

After implementation, run the test suite:

1. Run the relevant test command for the project (de