Skip to content

jupes/agent-forge-harness / .agents/skills/forge-implement

forge-implement

Unverified

Execute a Forge plan's Beads checkpoints with TDD and verification. Use for /forge-implement or the pipeline's implementation phase.

forge-implement

Phase 3 of 4 in the Forge pipeline (research → plan → implement → ship). Input is the plan and Beads graph from [[forge-plan]]; output is working, tested, committed code — built in observable increments.

In an attended run, show each checkpoint and wait for its demo gate. In an explicitly unattended run, follow .claude/workflows/forge-auto.md instead; record the same checkpoint evidence without inserting human gates.

Prerequisites

bun run forge:phase-gate implement --slug <slug>    # verifies the plan artifact exists
cat plans/drafts/<slug>.md                          # the build sequence + checkpoints
bd ready                                             # the tasks created in the plan phase

Beads must be reachable. If bd errors (e.g. Dolt server down), stop and fix it (bd dolt start) — do not proceed without issue tracking.

--smith <name>: when the run was started with it, add --smith <name> to every forge:phase-gate call in this skill. The phase gate refuses a name that is not configured and records the smith on the run as its executor. It does not change the model of the session doing the work (.claude/workflows/forge.md, --smith).

Process

1. Claim the first task

bd update <task-id> --claim     # sets assignee + status=in_progress (atomic, idempotent)
bd comments add <task-id> "worklog: starting implement (forge)"

Work tasks in dependency order. One task in progress at a time.

Stay inside the task's file map. The ## Files section of the task's description lists the globs this task may touch (the plan phase wrote it: .claude/skills/forge-plan/SKILL.md). Read it as it is stored:

bd show <task-id> --json | bun run scripts/scheduler/filemap-cli.ts - --bd-json   # prints the task's globs

Do not read the map off plain bd show <task-id>: that renders the description as Markdown, and a glob that holds * comes out garbled (scripts/forge/**/*.ts is printed as **scripts/forge/****/*.ts).

Edit only files those globs match. The map is what the task said it would touch, and the review of this phase reads the diff against it. Nothing reserves files from it yet; it is kept honest now so that file reservations can be taken from it later.

When the work needs a file outside the map, do not edit it silently and do not stop either. Say so, then go on:

bd comments add <task-id> "worklog: outside the file map: <path> — <why this task has to touch it>"

Add the path to the task's ## Files section too, and name it when you show the checkpoint. Work on the description as it was written, never on what plain bd show printed. Save the stored one to a file, add the line, check the file, then store it:

bd show <task-id> --json | bun -e 'try { const issue = JSON.parse(await Bun.stdin.text()); await Bun.write(process.argv[1], [issue].flat()[0].description); } catch (error) { console.error(String(error)); process.exit(1); }' .tmp/work/<task-id>-description.md
# edit .tmp/work/<task-id>-description.md: one more line under "## Files"
bun run scripts/scheduler/filemap-cli.ts .tmp/work/<task-id>-description.md      # exit 0: the map is usable
bd update <task-id> --body-file .tmp/work/<task-id>-description.md

A task whose description has no ## Files section has no map to hold to (the first command of this section says no Files section): say that in the first worklog: comment.

Keep Beads current as you work (do not batch all updates to the end):

  • --claim moves the task open → in_progress — claim it before writing code, not after.
  • Add a worklog: comment at each checkpoint and at any notable decision or pivot, so the issue reflects real progress: bd comments add <task-id> "worklog: checkpoint A green — <demo cmd>".
  • If a task gets stuck on something external, set bd update <task-id> --status blocked and add a deps: comment naming the blocker; file a new Beads issue for the blocker rather than going quiet.

2. Red-green-refactor per the TDD skill

For each behavior in the plan's TDD Strategy, follow .claude/skills/tdd/SKILL.md vertically:

RED:   write ONE test for the next behavior → it fails
GREEN: write the minimal code to pass → it passes
  • One test at a time. Only enough code to pass the current test. No speculative features.
  • Start with the tracer-bullet behavior to prove the path end-to-end.
  • After the checkpoint's tests are green, refactor (extract duplication, deepen modules) and re-run tests. Never refactor while red.

Run bun run typecheck after each step and fix immediately.

3. Stop at the checkpoint — show the user

When a checkpoint's tests are green and typecheck passes, pause and give the user something to run. This is the heart of the phase:

✅ Checkpoint <A> complete: <what now works>

See it yourself:
  <exact command> — e.g. `bun test <path>` or `bun run dev` → http://localhost:5173/<route>
Expected: <what they should observe>

Commit: <sha> — <message>
  • If the checkpoint has a runnable surface, give the exact command/URL and the expected result.
  • If the plan marked the checkpoint (no live demo), say so and point to the passing tests as the evidence instead.
  • In an attended run, ask whether to continue to the next checkpoint. Do not start the next checkpoint until the user has had the chance to look (under /forgemaster this gate is explicit).

4. Commit and close per checkpoint

git add <specific files for this checkpoint>
git commit -m "feat(<scope>): <checkpoint summary>

Refs: <task-id>"

# Close the task only with test evidence
bd comments add <task-id> "worklog: <behaviors> green; demo: <command>; tested: yes"
bd close <task-id>

Each closed task should map to something the user saw run. Commit tests alongside code (the quality gate requires test files in recent commits).

5. Loop

Repeat steps 1–4 for each task/checkpoint. Inspect every ID in the plan's Beads Issue Map, including blocked and in-progress tasks; an empty ready queue does not prove completion.

6. Phase quality gate + hand off

bun run typecheck
bun run lint
bun test
git status --porcelain          # should be empty
bun run forge:phase-gate implement --slug <slug> --write --bead <task-id>    # records implement complete

<task-id> is the issue the run was started from (a task, a bug or a chore), else the last task this phase closed. The command prints data.correlation.pointer: the ship step runs the quality gate with it, so that gate result is tied to this run and that task (.claude/workflows/forge.md, Which bead a phase names).

Report the checkpoints completed and the tasks closed, then point to /forge-ship <slug> (or /forgemaster continues).

Hard Stops

  • A checkpoint balloons past its planned scope (>8 files or >~200 lines), or keeps leaving its file map: pause and report; consider splitting the Beads task before continuing.
  • A behavior cannot be tested through the public interface: revisit the interface design with the user (see .claude/skills/tdd/interface-design.md) rather than testing implementation details.
  • Quality gate fails twice after fixes: stop, file a Beads bug, escalate.

Exit Criteria

  • Every plan checkpoint reached green and was demoed (or marked (no live demo) with tests).
  • Every plan Beads task closed with test evidence.
  • typecheck + lint + tests pass; working tree clean.
  • Forge state advanced to implement complete.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 318kUpdated Claude CodeCodexUnverifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 117kUpdated Claude CodeCodexUnverifiedInstall