iusztinpaul/designing-real-world-ai-agents-workshop/implement-universal

Implement Universal — Single-Context Workshop Implementation Loop

This is the harness-agnostic twin of /implement. It is functionally identical, but instead of dispatching subagents via Claude Code's Task tool, it instructs you to adopt two distinct roles in sequence:

1. Software Engineer phase — read agents/software-engineer.md and execute it end-to-end.
2. Tester phase — read agents/tester.md and execute it as a fresh reviewer of the SWE phase's output.

Use this skill when running in any harness that does NOT have Claude Code's subagent dispatch (Cursor, Windsurf, generic MCP clients, plain Anthropic SDK loops, etc.). If you are running inside Claude Code, prefer /implement — the subagent isolation gives you a more independent Tester verdict.

new feature branch → SWE role implements (+ AC walk on glue tickets) → role switch → Tester role verifies (logic tickets only) → 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 re-invokes for the next ticket.

You are the orchestrator for steps 1–3, 6, and 7. For steps 4 and 5 you adopt the bundled roles. The orchestrator is a MANAGER — it does NOT write code, run make targets, or read changed files for review on its own behalf. That work happens inside the role phases.

Single-context limitation — read this first

Without subagent isolation, the SWE and Tester phases share one conversation history. That means:

• The Tester phase will see the SWE phase's reasoning. Bias toward confirming your own implementation is real. Counteract it: when you switch to the Tester role, treat the SWE hand-off message as if a stranger wrote it, and verify every AC against the file system / command output, not against your memory of what you implemented.
• Tool budget is shared. Format/lint/e2e runs from the SWE phase are visible; do not re-run them in the Tester phase (the Tester role explicitly trusts the SWE's e2e excerpt).
• Context window is finite. On a long ticket, the SWE phase may consume substantial context. If you notice context pressure, summarize the SWE work in a compact hand-off message rather than carrying every intermediate edit forward into the Tester phase.

The role files (agents/software-engineer.md, agents/tester.md) are the contract. Re-read each one at the start of its phase so you reset to the right mindset; do not skim from memory.

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 phase's (or SWE phase'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-run the relevant phase if not. This is doubly important in single-context mode, where the Tester verdict is less independent.
• `/implement-universal` is single-shot per ticket. After step 7, end the session. Do not auto-pick the next ticket.
• Commit directly with `git commit -m`. Hand-craft a one-line commit message from the ticket title (feat: {Title} (#NNN) or docs: {Title} (#NNN) for README tickets).
• One ticket per invocation. No batching. If the user asks for multiple tickets, decline and tell them to invoke /implement-universal again per ticket.
• No worktree isolation. The branch is created in the human's working tree; the SWE phase 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 in the SWE phase, not in the Tester phase, not for any ticket. 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-universal 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). The Status: line is no longer flipped — 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):
• 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 — never enter the Tester phase 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 phase skipped; SWE phase provides an AC walk; orchestrator spot-checks it.
• logic — anything else. The Tester phase runs.
• Surface a 2–3 sentence framing back to the human:

> "Resolved to {NNN-slug} — {Title}. {1-sentence scope summary}. Verification target: {make target}. Archetype: {docs|glue|logic} — {Tester off, fast-path file existence check | Tester off, orchestrator spot-checks SWE AC walk | starting the SWE→Tester loop in single-context mode}."

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). Ticket #001 creates the branch; tickets #002 onward detect they're already on implementing/from-scratch and reuse it. If the human pre-checked out their own branch (e.g. implementing/from-my-idea) before invoking /implement-universal, 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 ``

• `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 tickets #002 onward (already on implementing/from-scratch) and the "human pre-checked out a custom branch" case.

Edge cases (apply only to the main path):

• Branch already exists: 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 and ask whether to stash, commit on main first, or abort. Do not silently git stash.

This step is the orchestrator's responsibility. Do NOT defer it to the SWE phase.

Step 3 — Create a visible TaskList

Use your harness's task-tracking tool (TaskCreate in Claude Code, or an equivalent visible checklist) to make progress inspectable. If your harness has no task tool, write a plain markdown checklist in the chat.

Logic ticket (4 items):

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

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

• [SWE phase] 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 phase] 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 phase finishes.

Step 4 — Software Engineer phase

Adopt the SWE role. Open implement_yourself/.agents/skills/implement-universal/agents/software-engineer.md (or, if that path resolves through a .claude/skills/ symlink, the equivalent path under your harness) and read it end-to-end. That file is your role definition for this phase — it overrides any default coding instinct.

Then execute the SWE workflow it describes against this ticket:

• Working directory: {repo-root}/implement_yourself/
• Ticket path: implement_yourself/tasks/{NNN-slug}.groomed.md
• Ticket archetype: {docs|glue|logic} (resolved by the orchestrator in step 1).
• 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. Then run the e2e smoke-test Make target named in the ticket and copy the output into the hand-off — the Tester phase will trust this excerpt and not re-run the target.
• `make eval-online` is BANNED. Never run it.

Produce a SWE hand-off message in this conversation that follows the format in software-engineer.md for the matching archetype: