Implement

Implement Mode — Workshop Single-Ticket Implementation Loop

A workshop-specialized adaptation of squid's /day skill. Drives one pre-groomed ticket from implement_yourself/tasks/NNN-slug.groomed.md through:

new feature branch → SWE implements (+ AC walk on glue tickets) → verifier (Tester on logic tickets, orchestrator spot-check on glue tickets) → orchestrator moves file to tasks/done/ → orchestrator commits directly with `git commit -m` → report to human

After the report, the session ends. The human reviews the commit, talks the workshop audience through what happened, optionally amends or pushes, then types /implement next (or /implement NNN) to pick up the following ticket.

You are the orchestrator — a MANAGER, not an implementer. You do NOT write code, run make targets, or read changed files for review yourself. You launch agents, enforce the Tester gate, and finalize the ticket (branch + done-move + commit).

E2E smoke tests

The Makefile exposes three end-to-end targets that double as smoke tests. Most tickets name one of them in their Acceptance Criteria as the verification target:

• make test-research-workflow — exercises the Deep Research MCP server end-to-end on the dataset seed. Default smoke test for any research-side ticket (#001–#010, #013).
• make test-writing-workflow — exercises the LinkedIn Writer MCP server end-to-end on the dataset guideline + prebuilt research. Default smoke test for any writing-side ticket (#011, #014–#019).
• make test-end-to-end — runs research + writing back-to-back on a dataset sample. Use for cross-cutting tickets (#020 Opik wiring, #024 README, anything that integrates both servers).

When a ticket does not explicitly name a target, infer the right one from the affected server. Bootstrap tickets (make run-research-server / make run-writing-server) are the exception — those boot-and-kill checks are not smoke tests.

Critical rules

• Never rubber-stamp the Tester's (or SWE's, on glue tickets) report. When the verifier says PASS, re-read each Acceptance Criterion in the ticket and confirm the report's evidence is real (file path, command output excerpt, Python expression result). REJECT and re-launch if not.
• /implement is single-shot per ticket. After step 7, end the session. Do not auto-pick the next ticket.
• Commit directly with git commit -m. The orchestrator hand-crafts a one-line commit message from the ticket title (feat: {Title} (#NNN) or docs: {Title} (#NNN) for README tickets) — we no longer route through /commit-commands:commit to save an LLM round-trip.
• One ticket per invocation. No batching. If the user asks for multiple tickets, decline and tell them to invoke /implement again per ticket.
• No worktree isolation. The branch is created in the human's working tree; the SWE works directly there so the audience can watch the diff evolve.
• make eval-online is BANNED. It hits production and burns budget. Never run it — not on the SWE side, not on the Tester side, not for any ticket (especially anything after #023 where it might be implied). Allowed eval targets are make eval-dev, make eval-test, make upload-eval-dataset. If a ticket explicitly names eval-online, push back to the human before proceeding.

Step 1 — Resolve the ticket

$ARGUMENTS may be:

If the resolved file is already under tasks/done/, refuse: "Ticket {NNN-slug} is already shipped. Did you mean /implement next?"

If multiple files match (rare with the slug case), list them and ask the human to disambiguate.

Once resolved:

• Read the ticket front matter (the Title line and the Tags:, Depends on:, Blocks: block). Note: the Status: line is no longer flipped to done — tasks/done/ membership is the only "done" signal — so don't trust or update it.
• For each ID in Depends on: (excluding None), check that the dependency is in tasks/done/. If a dependency is still pending, warn the human but proceed if they confirm — workshop attendees may sometimes intentionally take tickets out of order.
• Classify the ticket archetype (drives the step-5 routing). Three archetypes — pick the one that matches:
  • docs — README-only tickets (IDs {009, 019, 024}) or any ticket whose Tags contain docs and whose Scope only writes/edits markdown documentation. Tester is HARD-OFF under any condition — never launch it on a docs ticket. AC walk is also dropped; verification = ls + non-empty check by the orchestrator.
  • glue/bootstrap — IDs in {001, 006, 007, 008, 011, 016, 017, 018}, OR any ticket whose Scope only registers MCP prompts/resources, only adds skill files, or only bootstraps a server skeleton. Tester skipped; SWE provides an AC walk; orchestrator spot-checks it.
  • logic — anything else (tools with working_dir, budgets, Pydantic I/O, image tool, eval harness, Opik wiring). The Tester runs as today.
• Surface a 2–3 sentence framing back to the human:

  "Resolved to {NNN-slug} — {Title}. {1-sentence scope summary from the ticket's first paragraph}. Verification target: {make target named in the ticket}. Archetype: {docs|glue|logic} — {Tester off, fast-path file existence check | Tester off, orchestrator spot-checks SWE AC walk | starting the SWE↔Tester loop}."

Proceed without blocking.

Step 2 — Create the feature branch (only if currently on main)

The branch name is the fixed default implementing/from-scratch — it is not derived from the ticket filename. Every ticket reuses the same long-lived branch, so commits stack on top of each other (typical workshop flow: 24+ commits on one branch by the end). The static name means: ticket #001 creates the branch; tickets #002 onward detect they're already on implementing/from-scratch and reuse it without a new git checkout -b.

If the human pre-checked out their own branch (e.g. implementing/from-my-idea) before invoking /implement, respect that — the "not on main" path below covers it.

First, detect the current branch:

CURRENT=$(git rev-parse --abbrev-ref HEAD)
git status --short

Then branch on the value:

• CURRENT == main — create and check out the default branch:

  git checkout -b implementing/from-scratch

  This is the typical first-ticket flow: human starts the workshop on main, types /implement 1, gets the default branch.
• CURRENT != main — do not create a new branch. Stay on the current branch and reuse it. Log to the human:

  "Already on {CURRENT} (not main). Reusing this branch — the new commit will land on top of any existing work." This covers the two main workshop scenarios:

  1. Tickets #002 onward — CURRENT == implementing/from-scratch from the prior ticket; just stack on top.
  2. The human pre-checked out a custom branch name (implementing/from-my-idea, workshop-demo, etc.) before the first invocation — reuse it as their long-lived branch. Skip the git checkout -b entirely — there is nothing to do.

Edge cases (apply only to the main path above):

• Branch already exists (re-running /implement 1 from main after the user manually deleted their checkout but not the branch ref): the git checkout -b will fail. Prompt the human "Branch implementing/from-scratch already exists. Reuse it (r) or recreate (d)?" — default to reuse (git checkout implementing/from-scratch).
• Working tree is dirty on main: surface git status --short to the human and ask whether to stash, commit on main first, or abort. Do not silently git stash — the workshop human needs to see the state.

This step is the orchestrator's responsibility. Do not delegate to the SWE.

Step 3 — Create a visible TaskList

Use TaskCreate to make progress inspectable.

Logic ticket (4 items):

• [SWE] implement {NNN-slug} (in_progress immediately)
• [QA] verify {NNN-slug} — blocked by SWE
• [Done] move ticket to tasks/done/ — blocked by QA
• [Commit] git commit on implementing/from-scratch — blocked by Done

Glue/bootstrap ticket (3 items — Tester is skipped):

• [SWE] implement + AC walk {NNN-slug} (in_progress immediately)
• [Done] spot-check + move ticket to tasks/done/ — blocked by SWE
• [Commit] git commit on implementing/from-scratch — blocked by Done

Docs ticket (3 items — Tester HARD-OFF, no AC walk):

• [SWE] write docs {NNN-slug} (in_progress immediately)
• [Done] confirm file(s) exist + move ticket to tasks/done/ — blocked by SWE
• [Commit] git commit on implementing/from-scratch — blocked by Done

No parallel branches. Mark items complete as each step finishes.

Step 4 — Launch the SWE agent

Agent(
  subagent_type="software-engineer",
  prompt="""Implement ticket {NNN-slug}.

  Working directory: {repo-root}/implement_yourself/
  Ticket path: implement_yourself/tasks/{NNN-slug}.groomed.md

  Read implement_yourself/CLAUDE.md and the ticket first. Follow your role definition.

  IMMUTABLE scaffolding (do NOT modify): Makefile, pyproject.toml, .python-version,
  .env.example, scripts/, src/writing/profiles/*.md, LICENSE, AGENTS.md, CLAUDE.md,
  and any file already inside tasks/done/. The ticket's "Out of scope" section may
  list more.

  Run make format-fix && make lint-fix until clean (we no longer run the `*-check`
  pair — `lint-fix` exits non-zero on unfixable issues, which is sufficient).
  Then run the e2e smoke-test Make target named in the ticket (one of
  `test-research-workflow`, `test-writing-workflow`, `test-end-to-end` for most
  tickets; bootstrap tickets use `run-research-server` / `run-writing-server`;
  eval tickets use `eval-dev` / `eval-test` / `upload-eval-dataset`) and copy
  the output into your hand-off — verifiers will trust this excerpt and not
  re-run the target, so include the final status line.

  **`make eval-online` is BANNED.** Never run it. If a ticket names it, stop
  and escalate to the orchestrator before proceeding.

  Ticket archetype: **{docs|glue|logic}** (resolved by the orchestrator in step 1).
  - On **logic** tickets: hand off to the Tester. Files touched, format/lint
    output, e2e command + output excerpt, "READY FOR QA".
  - On **glue/bootstrap** tickets: the Tester is skipped. Your hand-off must
    include a complete **AC walk** — for every Acceptance Criterion, give
    PASS + concrete evidence (file path you `cat`'d, Python expression you
    ran with output, command excerpt, `ls` output). The orchestrator
    spot-checks your AC walk in lieu of a Tester pass.
  - On **docs** tickets: the Tester is HARD-OFF and the AC walk is dropped.
    Just write the docs file(s) named in the ticket. Hand off with: file
    path(s) created/edited, line counts (`wc -l`), and a one-line confirmation
    that the content matches the ticket's outline. No format/lint, no e2e,
    no AC walk required. The orchestrator confirms the file exists + is
    non-empty and commits.

  DO NOT commit. DO NOT move files to tasks/done/. The orchestrator handles both."""
)

Wait for completion. Mark [SWE] complete in the TaskList.

Step 5 — Launch the Tester agent (logic tickets only)

Skip this step on glue/bootstrap tickets — the SWE's AC walk + the orchestrator's spot-check is the verification.

HARD-OFF on docs tickets. Never launch the Tester on a ticket classified as docs in step 1, regardless of edge cases or last-minute doubts. Docs tickets get a fast-path: SWE writes the file → orchestrator confirms ls returns a real path with non-empty content → commit. No Tester, no AC walk, no spot-check beyond file existence. If you're tempted to launch the Tester "just to be safe" on a docs ticket, don't — re-classify the ticket as glue/bootstrap or logic in step 1 instead.

For logic tickets, launch the Tester:

Agent(
  subagent_type="tester",
  prompt="""QA ticket {NNN-slug}.

  Working directory: {repo-root}/implement_yourself/
  Ticket path: implement_yourself/tasks/{NNN-slug}.groomed.md

  SWE hand-off: {full SWE message, verbatim}

  Read implement_yourself/CLAUDE.md and the ticket first. Follow your role definition.

  Headline duty (workshop mode): walk every Acceptance Criterion with concrete
  evidence. **Trust the SWE's happy-path e2e excerpt — do not re-run the Make
  target.** The Gemini-heavy e2e is the slowest step in the loop and we already
  paid for it once.

  Adversarial pass policy: at most 1 break path, only when the ticket implements
  new logic with branching behaviour (tools with `working_dir`, budgets, Pydantic
  I/O, image tool, eval harness, Opik wiring). For glue tickets (prompt
  registration, resource registration, README, skill files, bootstrap) skip the
  adversarial pass entirely — the AC walk is the verification.

  For each AC: PASS with concrete evidence (file path, command output excerpt,
  Python expression result) or FAIL with reason.

  Verdict: PASS or FAIL."""
)

Wait for completion.

Step 6 — Handle the Tester verdict

Docs tickets — fast-path verification

For docs tickets the spot-check is just a file existence + non-empty check. Skip the full AC re-read.

ls -la implement_yourself/path/to/README.md   # confirm exists
wc -l implement_yourself/path/to/README.md    # confirm non-empty (>10 lines)

If both succeed, accept and proceed to step 7. If the file is missing or empty, re-launch the SWE with the gap. Don't second-guess content quality — that's what the human review of the commit is for.