iusztinpaul/designing-real-world-ai-agents-workshop/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:

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