executing

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:

``bash 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:

``bash 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 (detected from package.json scripts, Makefile, or conventions).
2. If tests pass: proceed to Step 5.
3. If tests fail:
4. Read the failure output carefully.
5. Fix the failing code (not the tests, unless the test itself is wrong).
6. Re-run tests.
7. Repeat up to 3 times (the circuit breaker threshold from config).
8. If still failing after 3 attempts, update .forge/state.md with task_status: debugging and describe the failure. The stop hook will switch to systematic DEBUG mode.

Step 5: Update State to Testing

After tests pass, update .forge/state.md:

1. Set task_status: testing in the frontmatter.
2. Under "In-Flight Work", describe what you implemented and that tests are passing.
3. Note any key decisions you made (library choices, design patterns, deviations from conventions).

The stop hook reads this state and decides the next action:

• If depth is quick: skip review, proceed to commit.
• If depth is standard or thorough: the stop hook will feed a review prompt.

Step 6: Review (Standard and Thorough Only)

When the stop hook feeds a review prompt, review the implementation:

1. Re-read the spec acceptance criteria for this task.
2. Check each criterion — is it fully implemented? Partially? Missing?
3. Check code quality — follows repo conventions? Error handling? No stubs?
4. Check edge cases — are error cases from the spec handled?
5. Report: If all criteria are met, report PASS. If issues exist, report ISSUES with specific file:line references.

If issues are found:

• Fix them immediately.
• Re-run tests to confirm fixes do not break anything.
• Update the review status.
• The stop hook handles the review iteration loop (max 3 iterations per the circuit breaker).

Step 7: Commit Atomically

Once the task passes tests and review (or review is skipped for quick depth):

1. Stage only the files for this task. Do not stage unrelated changes.
2. Write a descriptive commit message following the repo's commit conventions. Include:
3. What was implemented (the task name)
4. Which spec requirement(s) it satisfies (R-numbers)
5. The task