---
name: single-agent-start
description: Start single-agent TDD execution loop
summary: "Claims the next task, writes a failing test, implements until it passes, refactors, runs quality gates, commits, and repeats — following the implementation playbook."
phase: "build"
order: 1510
dependencies: [implementation-playbook]
outputs: []
conditional: null
stateless: true
category: pipeline
knowledge-base: [tdd-execution-loop, task-claiming-strategy]
reads: [coding-standards, tdd, git-workflow]
---

## Purpose
Start the single-agent TDD execution loop. This is the primary entry point
for implementation work when one agent works through the task list
sequentially. The agent claims the next available task, writes failing tests,
implements until green, creates a PR, and repeats until all tasks are
complete.

## Inputs
- CLAUDE.md (required) — project conventions, key commands, workflow
- docs/implementation-playbook.md (required if exists) — primary task execution reference with wave assignments and per-task context
- docs/implementation-plan.md (fallback) — task list when no playbook exists
- docs/onboarding-guide.md (optional) — project context for orientation
- docs/coding-standards.md (required) — code conventions, naming, patterns
- docs/tdd-standards.md (required) — test categories, mocking strategy, test file locations
- docs/project-structure.md (required) — where files live
- tests/acceptance/ (optional) — TDD test skeletons for red-green-refactor starting points
- tests/evals/ (optional) — project eval checks for quality gates
- tasks/lessons.md (optional) — previous lessons learned to avoid repeating mistakes
- .beads/ (conditional) — Beads task tracking if configured

## Expected Outputs
- Implemented features with passing tests
- Pull requests for each completed task
- Updated task status in playbook/plan or Beads

## Quality Criteria
- (mvp) Pre-flight checks pass before starting any implementation work
- (mvp) Each task follows red-green-refactor TDD cycle
- (mvp) All quality gates pass before PR creation (make check + make eval if available)
- (mvp) Task status is updated after each completion
- (deep) Test skeletons from tests/acceptance/ are used as starting points when available
- (deep) lessons.md is consulted before each task for relevant anti-patterns
- (deep) Before starting each task, agent consults tasks/lessons.md and documents which lesson was applied
- (deep) PR description includes implementation summary, assumptions, and files modified

## Methodology Scaling
- **deep**: Full pre-flight verification, read onboarding guide, consult lessons.md
  before each task, use test skeletons, run evals, detailed PR descriptions with
  implementation notes and assumptions.
- **mvp**: Quick git/dependency check, read playbook or plan, pick next task,
  TDD loop, make check, create PR. Skip onboarding guide review and detailed
  PR annotations.
- **custom:depth(1-5)**:
  - Depth 1: git status check, TDD loop, make check.
  - Depth 2: add dependency check and test suite health verification before starting.
  - Depth 3: add lessons.md review and test skeleton usage.
  - Depth 4: add onboarding guide, eval gates, detailed PR descriptions.
  - Depth 5: full pre-flight suite, all quality gates, cross-reference with upstream docs.

## Mode Detection
This is a stateless execution command. No document is created or updated.
- Always operates in EXECUTE MODE.
- If work is already in progress (feature branch exists, uncommitted changes),
  redirect to `/scaffold:single-agent-resume` instead.

## Update Mode Specifics
Not applicable — this is a stateless execution command that does not produce
a persistent document.

## Instructions

### Pre-Flight Verification

Before writing any code, verify the environment is ready:

1. **Git state check**
   - `git status` — working tree should be clean (no uncommitted changes)
   - `git branch --show-current` — should be on `main` or a fresh branch
   - If on a feature branch with changes, stop and suggest `/scaffold:single-agent-resume` instead

2. **Dependency check**
   - Run the install command from CLAUDE.md Key Commands (e.g., `npm install`, `pip install`, `bundle install`)
   - Confirm dependencies are current

3. **Test suite health**
   - Run the project's check command from CLAUDE.md Key Commands (e.g., `make check`)
   - If tests fail before you start, fix them first or flag to the user

4. **Project orientation**
   - Read `CLAUDE.md` for project conventions and key commands
   - Read `docs/onboarding-guide.md` if it exists (first session orientation)
   - Read `tasks/lessons.md` for relevant anti-patterns and gotchas

### Beads Detection

Check if `.beads/` directory exists.

**If Beads is configured:**
- Atomically claim the next ready task: `TASK=$(bd ready --claim --json | jq -r '.id')`
  - This sets `assignee=$BEADS_ACTOR` (or your git user.name) and `status=in_progress` in a single round-trip — no race window vs other agents.
  - If you need a specific task by ID instead, use `bd update <id> --claim`.
  - If `bd ready --claim` returns no task, you're done — exit the loop.
- Implement following the TDD workflow below
- After PR is merged, run `bd close <id>`
- Repeat (`bd ready --claim --json`) until no tasks remain

**Without Beads:**
1. Read `docs/implementation-playbook.md` as the primary task execution reference.
   Fall back to `docs/implementation-plan.md` when no playbook is present.
2. Pick the first uncompleted task that has no unfinished dependencies.
3. Implement following the TDD workflow below.
4. Mark the task complete in the plan/playbook.
5. Repeat in dependency order until all tasks are done.

### TDD Execution Loop

For each task:

1. **Claim the task**
   - Create a feature branch: `git checkout -b <type>/<description>` (e.g., `feat/add-auth`)
   - If Beads: branch as `bd-<id>/<desc>`

2. **Red phase — write failing tests**
   - Check `docs/story-tests-map.md` (if it exists) to find test skeletons that correspond to this task's user stories
   - Check `tests/acceptance/` for existing test skeletons that correspond to the task
   - If skeletons exist, use them as your starting point
   - Otherwise, write test cases from the task's acceptance criteria
   - Run the test suite — confirm the new tests FAIL (red)

3. **Green phase — implement**
   - Write the minimum code to make the failing tests pass
   - Follow conventions from `docs/coding-standards.md`
   - Follow file placement from `docs/project-structure.md`
   - Run tests after each meaningful change — stop when green

4. **Refactor phase — clean up**
   - Refactor for clarity, DRY, and convention compliance
   - Run the full test suite — confirm everything still passes

5. **Quality gates**
   - Run `make check` (or equivalent from CLAUDE.md Key Commands)
   - If `tests/evals/` exists, run `make eval` (or equivalent eval command)
   - Fix any failures before proceeding

6. **Pre-push local code review (when requested or required)**
   - If the user says to review before committing or pushing, or the project's workflow requires a local multi-model gate before `git push`, run `scaffold run review-code`
   - This reviews the local delivery candidate without requiring a PR
   - Surface auth failures immediately and retry after recovery
   - If recovery is not possible, document reduced review coverage and continue with the available channels
   - Fix any findings at or above `fix_threshold` before proceeding

7. **Create PR**
   - If Beads is configured, run the PR-readiness checklist first:
     ```bash
     if [ -d .beads ]; then
       bd preflight
     fi
     ```
     Fix any issues `bd preflight` flags before proceeding. (Note: do NOT use `[ -d .beads ] && bd preflight` — that returns exit-1 when `.beads/` is absent and breaks any caller running under `set -e`.)
   - Push the branch: `git push -u origin HEAD`
   - Create a pull request: `gh pr create`
   - Include in the PR description: what was implemented, key decisions, files changed
   - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md

8. **Run code reviews (MANDATORY)**
   - Run the review-pr tool: `scaffold run review-pr` (CLI) or `/scaffold:review-pr` (plugin)
   - This runs the three MMR CLI channels on the PR diff plus the Superpowers code-reviewer agent as a complementary 4th channel reconciled through `mmr reconcile`:
     1. **Codex CLI**: `codex exec --skip-git-repo-check -s read-only --ephemeral "REVIEW_PROMPT" 2>/dev/null`
     2. **Gemini CLI**: `NO_BROWSER=true gemini -p "REVIEW_PROMPT" --output-format json --approval-mode yolo 2>/dev/null`
     3. **Claude CLI**: `claude -p "REVIEW_PROMPT" --output-format json 2>/dev/null`
     4. **Superpowers code-reviewer** (4th channel): dispatch `superpowers:code-reviewer` subagent with BASE_SHA and HEAD_SHA
   - Verify auth before each CLI (`mmr config test` pre-flights all three at once)
   - All four channels should execute. Missing Codex or Gemini → MMR runs a compensating Claude pass in its place (degraded-pass verdict). Missing Claude CLI → review proceeds without compensation.
   - Fix any findings at or above `fix_threshold` before proceeding
   - Do NOT move to the next task until the review completes

9. **Update status**
   - If Beads: task status is managed via `bd` commands
   - Without Beads: mark the task as complete in the plan/playbook

### Recovery Procedures

**Tests fail before starting:**
- Run the test suite and read the output carefully
- If failures are in existing tests (not your changes), fix them first
- If failures are environment-related, run the install/setup commands from CLAUDE.md

**Merge conflicts on PR:**
- `git fetch origin && git rebase origin/main`
- Resolve conflicts, re-run tests, force-push the branch

**Quality gate failures after implementation:**
- Read the failure output — most failures have clear fix instructions
- Fix lint/format issues first (often auto-fixable)
- Fix test failures next
- Re-run the full gate before pushing

**Stuck on a task:**
- Re-read the task description, acceptance criteria, and any linked docs
- Check `tasks/lessons.md` for similar past issues
- If truly blocked, note the blocker and move to the next unblocked task

### Process Rules

1. **TDD is not optional** — Write failing tests before implementation. No exceptions.
2. **One task at a time** — Complete the current task fully before starting the next.
3. **Quality gates before PR** — Never create a PR with failing checks.
4. **Honor pre-push review when requested** — If the user or project workflow asks for pre-push multi-model review, run `scaffold run review-code` after quality gates and before `git push`.
5. **Code review before next task** — After creating a PR, run `scaffold run review-pr`: three CLI channels (Codex CLI, Gemini CLI, Claude CLI) via MMR plus the Superpowers code-reviewer agent as a complementary 4th channel. Fix all findings at or above `fix_threshold` before moving on.
6. **Update status immediately** — Mark tasks complete as soon as review passes.
7. **Consult lessons.md** — Check for relevant anti-patterns before each task.
8. **Follow CLAUDE.md** — It is the authority on project conventions and commands.

---

## After This Step

When this step is complete (all tasks done or session ending), tell the user:

---
**Execution session complete** — Tasks implemented with passing tests and PRs created.

**Session summary:**
- Tasks completed: [list task IDs/titles]
- PRs created: [list PR numbers]
- Remaining tasks: [count or "none"]

**If resuming later:** Run `/scaffold:single-agent-resume` to pick up where you left off.

**If all tasks are done:**
- Review `tasks/lessons.md` and add any patterns learned during implementation.
- Consider running `/scaffold:version-bump` for a release.

**Pipeline reference:** `/scaffold:prompt-pipeline`

---
