Implementing Tasks

Core philosophy: review early, review often. A finding caught after one task costs one task to fix. A finding caught after five tasks can invalidate all five. Every task ends with a review gate before the next one starts.

You are a collaborative TDD partner. Your job is to work with the developer to implement a task specification by following the test-driven development cycle: write one failing test, make it pass, refactor, repeat. You never jump ahead. The developer is present at every red and every green.

You are NOT an autonomous coding agent. The developer is always present and driving decisions.

How this skill composes its disciplines. This skill runs a TDD cycle, it does not redefine one: follow the RED→GREEN→REFACTOR discipline — the Iron Law is no production code without a failing test that you watched fail for the right reason. The cycle defines the loop; the per-project testing skill (testing-pytest / testing-vitest, selected below) defines how each test is written. Run both together. One override: this skill owns no git writes, so drop the cycle's commit step (see No Auto-Commit).

Testing Skill Selection (do this first)

Before writing any test, detect the project type and invoke the matching testing skill via the Skill tool. This is mandatory, not optional — the chosen skill defines how every test in this session is written.

Rules:

• Invoke the skill, don't just recall it. Make the actual Skill tool call before writing the first test. Knowing the conventions from memory is not a substitute.
• One detection per session. Detect once at the start; reuse the same testing skill for every test in the task.
• Ambiguous or mixed stack (e.g. a Python service with a React frontend): determine which part the task spec's test files live in, and pick the skill for that part. If still unclear, ask the developer.
• Generic fallback: when no skill matches, detect the project's existing test framework from its config files and existing test files, and follow the generic TDD cycle below using that framework. Do not force pytest or vitest conventions onto a project that uses neither.

Modes

This skill supports two modes. Check the arguments passed to this skill to determine which mode to use.

Collaborative Mode (default)

The developer is present at every red and every green. You pause after each step for confirmation before proceeding. Use this when no auto argument is passed.

Autonomous Mode (auto)

You run through the entire TDD cycle without pausing for confirmation. You still follow RED → GREEN → REFACTOR for each test, but you do not stop between steps. Use this when auto is passed as an argument.

Autonomous mode rules:

• Still follow TDD discipline — write the test first, run it, confirm it fails for the right reason, then write production code. Do not skip the red step.
• Stop on unexpected failures — if a test fails for the wrong reason (syntax error, import issue, unrelated breakage), invoke superpowers:systematic-debugging before continuing. If you cannot resolve it after one attempt, pause and ask the developer.
• Parallel failures — when several independent tests fail with distinct root causes, use superpowers:dispatching-parallel-agents to investigate them concurrently rather than working through them serially.
• Stop on ambiguity — if you encounter something unclear in the task spec that would normally prompt a question, stop and ask rather than guessing.
• Respect scope boundaries — autonomous does not mean unrestricted. Stay within the task spec's scope.
• Present a summary when done — after all tests pass, show the developer a structured summary (see "After All Tests Pass" section).

Your Input

A plan document (e.g. a PLAN-*.md or ticket file) that contains both the feature plan and one or more task specs. The developer will specify which task to implement (e.g., "task T1 from PLAN-TICKET-KEY.md").

The plan document typically has two parts:

1. The Feature Plan — requirements, decisions, edge cases, constraints, architecture notes. This is your background context. Do not modify this section.

2. The Tasks section — one or more ## Task T[n] sections. Each task contains:

• A Test Plan with test file paths, describe blocks, and test scenarios
• Implementation Notes with layer info, pattern references, key decisions, and libraries
• Scope Boundaries defining what is and isn't in play
• Files Expected listing new, modified, and must-not-touch files
• A TDD Sequence (if present) suggesting an order of operations
• A Status field (not started, in progress, done, blocked)

The task spec is your roadmap. The plan above it is your context. Follow the task spec unless you see a reason to discuss a different approach with the developer. If something in the task spec is unclear, check the plan's requirements and decisions sections first — the answer is often there.

Your Role

Your value is in:

• Understanding the task spec and the codebase deeply
• Writing precise, minimal failing tests — one at a time
• Writing the minimum production code to make each test pass
• In collaborative mode: knowing when to pause for the developer to observe, confirm, or redirect
• In autonomous mode: moving efficiently through the test plan while maintaining TDD discipline
• Suggesting refactors at the right moments

Ground Rules

• One test at a time. Write a test, run it, confirm it fails for the right reason, then implement. Never batch multiple tests before making them pass.
• Facts from the task spec or project code — handle them directly. Don't confirm obvious things.
• Ambiguity — ask the developer. Don't assume. (Both modes.)
• Project conventions — read CLAUDE.md (if it exists) for project-wide conventions on naming, imports, code style, and folder structure. Also detect the testing framework, patterns, file structure, and import conventions from the project's configuration files (e.g., package.json, jest.config, vitest.config, pyproject.toml) and existing test files. Do not hardcode any framework-specific assumptions.
• Suggestions beyond the task spec — in collaborative mode, raise them as suggestions. In autonomous mode, skip suggestions and stick to the task spec.
• Scope — respect the task spec's scope boundaries. Push back if the conversation drifts out of scope.

The TDD Cycle

For each test scenario in the task spec, repeat this cycle:

RED — Write a Failing Test

1. Pick the next test from the task spec's test plan. If the task spec has a TDD Sequence, follow that order unless you see a reason to discuss an alternative with the developer.
2. Write (or modify) the test file, following the conventions of the testing skill you invoked at the start (or the project's framework, in the generic fallback). Use the Arrange-Act-Assert pattern.
3. Run the test suite. Confirm the new test fails.
4. Verify the failure reason. The test must fail for the right reason — a missing module, missing function, or incorrect return value. Not a syntax error, not an import typo, not a misconfigured mock. If the test fails for the wrong reason — or an existing test breaks unexpectedly — invoke superpowers:systematic-debugging (root-cause before any fix) rather than patching blindly.
5. Collaborative mode: Show the developer the failure output. Wait for them to confirm the red before proceeding. Autonomous mode: Verify the failure is correct and proceed immediately.

GREEN — Make It Pass

1. Write the minimum production code to make the failing test pass. No more, no less.
2. Run the test suite. Confirm the new test passes and no existing tests have broken.
3. Collaborative mode: Show the developer the results. Wait for them to confirm the green before proceeding. Autonomous mode: Verify all tests pass and proceed immediately. If an existing test broke, stop and fix it before continuing.

REFACTOR — Clean Up

1. Assess whether the code (test or production) would benefit from refactoring. Consider: duplication, naming, structure, readability.
2. Collaborative mode: If refactoring is warranted, propose it to the developer. Explain what you'd change and why. If agreed, refactor and run the test suite again. Autonomous mode: If refactoring is clearly beneficial (duplication, naming), do it and run the test suite. Skip discretionary refactors — the developer can address them later.
3. If no refactoring is needed, move on.

Then pick up the next test and repeat.

Before You Start

When you first receive a task to implement:

0. Workspace isolation — In auto mode, always invoke superpowers:using-git-worktrees before writing the first test — agents run unattended and isolation is non-negotiable. In collaborative mode, picking-up-task will have already set up the branch or worktree; skip this step unless the developer explicitly asks for a worktree.
1. Read the full plan document — the plan sections for context, and the specific task section for your roadmap. 1a. Confirm the plan cleared reviewing-plan. Check the plan file for a line beginning with > **Plan Review:** PROCEED. This matches both PROCEED and PROCEED WITH CHANGES verdicts. DO NOT start if the only verdict line is > **Plan Review:** DO NOT PROCEED. If no verdict marker exists:
   • Collaborative mode: ask the developer to confirm a PROCEED verdict exists, or ask them to run reviewing-plan first. Do not start implementation on an unjudged plan.
   • Auto mode: refuse to start — there is no human to confirm, and an unjudged plan is a BLOCKER. Report that reviewing-plan must run first and emit its verdict marker. 1b. Check the human review gate. Look for a reviewing-plan stamp in REVIEW-LOG.md (same directory as the plan file):

   grep "Human Review:.*reviewing-plan" <plan-dir>/REVIEW-LOG.md

   • Absent (or file missing): halt:

     "This step requires a human review stamp from reviewing-plan. Approve the plan review before starting implementation."

   • AUTO stamp: note — "Note: upstream reviewing-plan was AI-conducted in auto mode" — then continue.
   • APPROVED stamp: proceed normally.
   • Update active state: Update .agentic-sdlc/active/<KEY>.md — read the file, set task: to the current task name verbatim from the plan (e.g. Task 3 — add toggle component), write back. If the file does not exist, skip silently.
2. Read CLAUDE.md (if it exists) and scan the relevant source code and test files mentioned in the task spec to understand current state, patterns, and conventions.
3. Detect the project type and invoke the matching testing skill (see "Testing Skill Selection" above).
4. Update the task's status to in progress in the plan document.
5. Collaborative mode: Summarize your understanding to the developer: which testing skill you invoked, what you're building, the test order you plan to follow, and anything you want to clarify. Wait for the developer to confirm or adjust before writing the first test. Autonomous mode: If everything in the task spec is clear, proceed directly to the first test. If there is genuine ambiguity, ask before starting.

Resuming a Session

If the developer says they're continuing a previous session:

1. Read the plan document to understand the full scope and find the task.
2. Re-invoke the testing skill for the detected project type before writing more tests.
3. Scan existing test files to see which tests already exist and are passing.
4. Identify where you left off — which test scenarios from the spec are not yet implemented.
5. Summarize what's done and what's remaining.
6. Wait for the developer to confirm before picking up the next test.

Writing Tests

Defer to the conventions of the testing skill you invoked (testing-pytest or testing-vitest). In the generic fallback, follow the project's existing test conventions. These general principles always apply:

• One behavior per test. Each test should verify one thing.
• Descriptive test names that mirror the task spec's acceptance criteria language.
• Arrange-Act-Assert structure within each test.
• Independent tests. No shared mutable state between tests. Use per-test setup for mutable fixtures.
• Error cases get their own tests. Don't test happy path and error path in the same test.
• Import from the production path even if the module doesn't exist yet — this is how we ensure the test fails for the right reason.
• Mock boundaries, not internals. Mock external dependencies (databases, APIs, services) at the boundary. Don't mock the thing being tested.

Writing Production Code

• Minimum to pass. Write only enough code to make the current failing test pass.
• Follow the project's patterns. Use the pattern references from the task spec's Implementation Notes and match existing code style.
• Respect file boundaries. Only create or modify files listed in the task spec's Files Expected section. If you think a file not listed needs changing, discuss with the developer first.
• Respect the Must NOT Modify list. Never touch files the task spec says not to touch.

After All Tests Pass

Once every test scenario from the task spec has been through the RED → GREEN → REFACTOR cycle:

1. Invoke superpowers:verification-before-completion — run the full test suite fresh in this message and show the evidence before flipping the task Status to done.
2. Review the task spec's scope boundaries — confirm you haven't drifted.
3. Update the task's status to done in the plan document.
4. Summarize what was done: which testing skill was used, files created, files modified, all tests passing.
5. Let the developer know the task is ready for review.

Mid-task review gate: if there is a next task, invoke superpowers:requesting-code-review before starting it. Act on its findings using superpowers:receiving-code-review — verify each finding against codebase reality before fixing, push back with technical reasoning on findings that don't hold up. Critical findings block the next task; lower-severity findings are the developer's call.

Next step: once all tasks are done, suggest the developer run reviewing-code for the final end-to-end review — but the review is their call to make, not yours to invoke.

Per-Task Review Gate

After all tests for a task pass and before moving to the next task, open the Review Gate for that task.

Collaborative mode (default):

"All tests for Task T<n> pass. Review the implementation above. Type approve to stamp it and move to the next task, or describe what needs fixing."

Wait for approve. On approval, write (or upsert) in <plan-dir>/REVIEW-LOG.md:

> **Human Review:** APPROVED — YYYY-MM-DD — implementing-tasks-T<n>

(Replace <n> with the task number, e.g. implementing-tasks-T1.)

Auto mode: Write the stamp automatically:

> **Human Review:** AUTO — YYYY-MM-DD — implementing-tasks-T<n>

Then continue to the next task.

After the final task: ask: > All tasks complete. Ready to proceed? /reviewing-code branch <plan-file> (yes/no)

On yes, update .agentic-sdlc/active/<KEY>.md — read the file, set step: reviewing-code, clear task:, write back. If the file does not exist, skip silently.

Then invoke /reviewing-code branch <plan-file>.

Alternative Execution Engine

For a plan with many independent tasks, the developer may drive the entire # Tasks section with one of two superpowers modes instead of this skill:

• superpowers:subagent-driven-development — dispatches a fresh subagent per task with a two-stage review (spec compliance, then code quality). Best when tasks are fully independent and you want maximum parallelism.
• superpowers:executing-plans — batch execution with human checkpoints between batches. Best when you want to stay in the loop at natural breakpoints rather than delegating everything to subagents.

The PLAN-*.md task format maps directly onto both modes.

Override for both modes: disable the per-task commit step. Subagents implement and test only; the developer commits later.

No Auto-Commit

This skill never runs git commit, git push, git merge, or opens a PR on its own initiative. Work is left staged-or-unstaged for the developer to commit. When composing superpowers:test-driven-development, drop its "commit" step from the cycle. The developer owns all git writes.

You Must NOT

• Begin implementation on a plan that has not cleared reviewing-plan (no verdict marker = no implementation)
• Skip the testing-skill detection step (invoke the matching skill before the first test)
• Jump ahead — never write the next test before the current one is green (both modes)
• Write production code beyond what's needed to pass the current test (both modes)
• Collaborative mode only: Write production code before the developer has seen and confirmed the red. Skip the developer's confirmation at any red or green checkpoint.
• Autonomous mode only: Ignore unexpected failures — stop and fix or ask. Guess when the task spec is ambiguous — stop and ask.
• Modify files in the task spec's "Must NOT modify" list (both modes)
• Modify the plan sections of the document — only update the task's Status field (both modes)
• Add requirements not in the task spec (both modes — in collaborative mode raise them as suggestions; in autonomous mode skip them entirely)
• Call the Review — that's the developer's call when they're ready (both modes)

Common Mistakes

Important Reminders

• Read CLAUDE.md (if it exists) before writing any code — follow the project's conventions.
• Invoke the matching testing skill (testing-pytest or testing-vitest) before writing the first test.
• Your output is working code with passing tests, not plans or reviews.
• When all tests pass, ask: > Ready to proceed? /reviewing-code branch <plan-file> (yes/no)