executing-one-shot

name	executing-one-shot
description	Use for executing implementation plans

Executing an Implementation Plan

Execute an implementation plan. The goal here is very high quality code, architecture, and design. Split the implementation plan into no more than 5 steps. Flesh out each step as if you were passing it to a junior developer. If the plan is too big or too ill defined to effectively accomplish your task in 5 steps or less with a very high bar of quality immediately exit. Report why with some recommendations on how to improve the plan.

Core principle: Read one step → execute implementation → write tests → code review → move to next step.

REQUIRED SKILL: requesting-code-review - The review loop (dispatch, fix, re-review until zero issues)

Overview

When NOT to use:

• No implementation plan exists yet (use writing-implementation-plans first)

MANDATORY: Dispatching subagents

Before dispatching any subagent:

• Briefly explain (2-3 sentences) what you're asking the agent to do
• State which step this covers
• Ensure the subagent has all required context

When the subagent returns: The user cannot see subagent output unless you show them. If it seems important or relevant print out a summary or, if small enough, the entire output for the user. A key deciding factor of whether or not to show the user subagent is if the output is important, but will not show up in the ending implementation artifact (and thus will not be seen by the user). Take note not to waste tokens or processing time outputting minutae or irrelevant details that the user will either not care about or see eventually when they review the code.

REQUIRED: Implementation Plan Path

DO NOT GUESS. If the user has not provided a path to an implementation plan, you MUST ask for it.

Use AskUserQuestion:

Question: "Which implementation plan should I execute?"
Options:
  - [list the newest plan files you find in docs/plans/]
  - "Let me provide the path"

If docs/plans/ doesn't exist or is empty, ask the user to provide the path directly.

Never assume, infer, or guess which plan to execute. The user must explicitly tell you.

The Process

1. Create Phase-Level Task List

Think deeply about what's being asked of you. The final result of this implementation should be SIMPLE, CLEAN, and ELEGANT. Code should be easy to read, very maintainable, easily testable, and deeply thought through. Code should never be written for the sake of writing it, every LoC should have a strong purpose. Always bias towards refactoring or removing code before implementing net new. Do not implement one off solutions, make things as general as reasonable. If you do need to implement net new code think in terms of building blocks instead of purpose specific, tightly coupled glue code. Implement for the future as well as right now, never code yourself into a corner, ensure code architecture is extensible and flexible, and do your best to leave the codebase better than how you found it.

MANDATORY: Your implementation taks list should be optimally ordered so that not only are the steps logical and increasing in complexity, first creating foundational building blocks or required underlying logic, but also so that context is managed as effeciently as possible. If there is a step you can do independently, or something you can implement that you will later treat as a black box, order those steps earlier so that they can be summarized or removed from context for later steps.

Use TaskCreate to create three task entries per step (or TodoWrite in older Claude Code versions). The first task entry per step should be implementation, the second should be testing and verification, the third should be code review:

- [ ] Step 1a: Implement base types
- [ ] Step 1b: Write tests
- [ ] Step 1c: Code review
- [ ] Step 2a: Implement hot path
- [ ] Step 2b: Write tests
- [ ] Step 2c: Code review
...

Why absolute paths in task entries: After compaction, context may be summarized. The absolute path in the task entry ensures you always know exactly which file to read.

Why include the title: Gives visibility into what each phase covers without loading full content.

2. Execute

For each step, follow this cycle:

2a. Implement the task

Mark "Step Na: Implementation" as in_progress and dispatch task-implementer to begin.

<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Implementing Step X, Task Y: [description]</parameter>
<parameter name="prompt">

... fleshed out prompt goes here ...

</parameter>
</invoke>

2b. Write tests and verify correctness

Mark "Step Nb: Tests and Verification" as in_progress and dispatch task-implementer to begin.

<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Writing tests for Step X, Task Y: [description]</parameter>
<parameter name="prompt">

... fleshed out prompt goes here ...

</parameter>
</invoke>

2c. Code Review for Step

Mark "Step Nc: Code review" as in_progress.

MANDATORY: Use the requesting-code-review skill for the review loop.

Context to provide:

• WHAT_WAS_IMPLEMENTED: Summary of all tasks in this phase
• PLAN_OR_REQUIREMENTS: All tasks from this phase
• BASE_SHA: commit before phase started
• HEAD_SHA: current commit

If code reviewer returns a context limit error:

The phase changed too much for a single review. Chunk the review:

1. Identify the midpoint of tasks in the phase
2. Run code review for first half of tasks (commits for tasks 1 through N/2)
3. Fix any issues found
4. Run code review for second half of tasks (commits for tasks N/2+1 through N)
5. Fix any issues found

When issues are found, dispatch task-implementer with the feedback:

<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Fixing review issues for Step X</parameter>
<parameter name="prompt">
  Fix issues from code review for Step X.

  Original prompt: [implementation step prompt]

  Code reviewer found these issues:
  [list all issues - Critical, Important, and Minor]

  Read the phase file to understand the tasks and context.

  Your job is to:
  1. Understand root cause of each issue
  2. Apply fixes systematically (Critical → Important → Minor)
  3. Verify with tests/build/lint
  4. Commit your fixes
  5. Report back with evidence

  Fix ALL issues — including every Minor issue. The goal is ZERO issues on re-review.
  Minor issues are not optional. Do not skip them.
</parameter>
</invoke>

After task-implementer completes the fixes, re-review per the requesting-code-review skill. Continue loop until zero issues.

Plan execution policy (stricter than general code review):

• ALL issues must be fixed (Critical, Important, AND Minor)
• Ignore APPROVED/BLOCKED status - count issues only
• Three-strike rule: If same issues persist after three review cycles, stop and report the issue

Minor issues are NOT optional. Do not rationalize skipping them with "they're just style issues" or "we can fix those later." The reviewer flagged them for a reason. Fix every single one.

Exit condition: Zero issues in all categories — including Minor.

Mark "Step Nc: Code review" as complete.

MANDATORY: After finishing the code review section of each task intelligently compact your context. The goal here is to constantly prune context overtime, not neccessarily completely rebuild it. NOT PRUNING ANY CONTEXT IS A FAILURE THAT SHOULD BE REPORTED TO THE USER. Even if you prune 5% of context, that is desireable. Since you are an advanced LLM you should have some idea of what you have left to do in this session, use that intelligence to understand what is neccessary in your context for the future and what isn't.

Common Thought Patterns When Smart Compacting - STOP

Do	Because
"I'm done interacting with that 3rd party dependency. I can summarize anything related."	You should have properly sequenced the implementation steps to ensure that dealing with this 3rd party dep is contained to only one implementation step.
"There's a lot of tool calls here, I can remove any that didn't lead to a change"	There's no reason to keep tool calls or their results around if they don't inform you why or how you did something important.
"I'm done working on this piece of code, I should keep it around since it'll be called later"	As you build your implementation core pieces of code will be needed to inform your future work

Don't	Because
"This core code file is taking up a lot of context, pruning it will be an easy win and I can re-read it later"	Re-reading files wastes context. If you are unsure about the future use of a large file summarize it as an AST index to aid future content reads
"I have to prune something, but everything is valuable"	This is never true, unless you have planned and executed everything perfectly.
"I can reason about this central concept from the beginning in the future, no need to keep it around"	Anything core to your implementation, planning process, or reasoning for why you're doing something should be kept

3. Move to Next Step

Repeat step 2 (2a → 2b → 2c) for each remaining step.

4. Update Project Context

After all phases complete, invoke a subagent to review changes and update README.md and AGENTS.md files if needed.

<invoke name="Task">
<parameter name="subagent_type">one-shot:task-implementer</parameter>
<parameter name="description">Updating project context after implementation</parameter>
<parameter name="prompt">
  Review what changed during this implementation and update README.md and AGENTS.md files if contracts or structure changed.

  Base commit: <commit SHA at start of first phase>
  Current HEAD: <current commit>
  Working directory: <directory>

  1. Diff against base to see what changed
  2. Identify contract/API/structure changes
  3. Update any files that might aid in future development
  4. Commit documentation updates

  Report back with what was updated (or that no updates were needed).
</parameter>
</invoke>

If subagent reports updates: Review the changes, then proceed to final review. If subagent reports no updates needed: Proceed to final review.

5. Complete Development

After implementation is complete:

• Provide a report to the human operator

  • For each step:
    • How many tasks were implemented
    • How many review cycles were needed
    • Any compromises made (there should be NO compromises, but if any were made). Examples:
      • "I couldn't run the integration tests, so I continued on"
      • "I couldn't generate the client because the dev environment was down"
      • Note that these are PARTIAL FAILURE CASES and explain to the user what the user must do now.
    • Were any code-review issues left outstanding at any point?

• Push the branch to remote origin.

Common Rationalizations - STOP

Excuse	Reality
"I'll review after each task to catch issues early"	No. Review once per step. Task-level review wastes context.
"Context error on review, I'll skip the review"	No. Chunk the review into halves. Never skip review.
"Minor issues can wait"	No. Fix ALL issues including Minor.