Spec Loop Implementation Flow

Use this skill after implementation approval for an approved chat-only or task-file task.

If no approved active task exists, return to spec-loop-plan-task/SKILL.md.

Core rules

• Keep the approved active task as the source of truth.
• Do not create a second implementation artifact or silently rewrite

the task to match the code.

• If important open decisions appear and they could materially change

scope, constraints, design, or test specification, use spec-loop-clarify-task/SKILL.md before continuing.

• Chat-only implementation is allowed only while confirmed task state

can safely remain in chat. If resolved decisions kept only in chat would risk loss through compaction or context loss, promote to the task-file path before continuing.

• This skill governs only the approved current increment until it

reaches review.

• If the User introduces additional executable work outside that

increment, return it to spec-loop-plan-task/SKILL.md for route selection and any renewed implementation approval.

• Before presenting work as ready, perform the Implementation notes

check.

• If another implementation-related skill conflicts with this skill or

the governing spec-loop-plan-task bundle, stop and ask the User which rules should govern.

Read and path selection

• Read spec-loop-plan-task/SKILL.md and the files it requires.
• Choose the active path:
• task-file path = an approved task file controls the current

increment

• chat-only path = an approved canonical chat-only task in chat

controls the current increment

• Then read:
• implementation-flow-guidance.md
• the matching path companion for the active path:
• chat-only-path-guidance.md
• task-file-path-guidance.md

Keep using the approved active task as the source of truth. Edit the active task file or canonical chat-only task only when the shared core and the active path companion allow it.

implementation-flow-guidance.md defines the route rules, when canonical task sections may change, the meaning of review, Implementation notes, and the completion checklist.

The path companion defines the active path mechanics, including chat-only recovery or promotion or the task-file move into review.

If the current increment is unclear, do not use this skill. Return to spec-loop-plan-task/SKILL.md.

Chat-only path guidance for spec-loop-implementation-flow

This file applies only on the chat-only planning path during implementation.

Use it with the shared core in implementation-flow-guidance.md. It says how the shared implementation-flow rules work on the chat-only path.

Basic facts:

• one active chat-only task at a time;
• no chat-only subtasks;
• no chat-only diagrams; and
• the current canonical chat-only task lives in chat.

If the work is no longer simple enough for chat, or confirmed clarification decisions kept only in chat would risk loss through compaction or context loss, promote it to the task-file path before continuing executable work.

0. Authorized canonical chat updates

On the chat-only path, the task in chat is the approved task for this work and the post-implementation record. Do not use chat-only revisions as a scratchpad or silently rewrite the task to match the code.

Use Task changes: as the default canonical revision format during implementation.

The most recent full chat-only task plus later Task changes: blocks is the current task state.

Only these chat-only revisions are allowed:

• emit Task changes: with changed sections only, following

spec-loop-plan-task/chat-only-path-guidance.md, when the shared core allows that change;

• emit Task changes: that records Implementation notes at the

mandatory checkpoint when relevant notes content exists;

• re-emit a fresh full current chat-only task with title, identifier,

and all current sections when the User asks for it, when reconstruction confidence is not high enough to continue safely, or when promotion needs a trustworthy full baseline; and

• perform minimal mechanical cleanup strictly incidental to one of the

allowed revisions above.

Any other chat-only revision during implementation needs explicit User approval.

If the agent finds that it already made an unauthorized chat-only revision during implementation, it must stop and disclose the exact revision in chat. It must make no further chat-only revisions except those explicitly approved by the User or otherwise allowed by this guidance, and must then follow the applicable shared route before continuing.

Omitted sections in Task changes: mean unchanged. If the User asks for the full current task, if a change cannot be expressed clearly as a change list, or if the task can no longer be reconstructed safely, re-emit a fresh full current chat-only task instead.

1. Chat-only actions for the shared routes

Use the shared route semantics from implementation-flow-guidance.md. This file gives the chat-only actions for those routes.

For shared route B. Pause the affected implementation and ask targeted User questions:

• use this route only while final clarification state can safely

remain in chat; if not, switch to route C; and

• after a clarification that still fits inside the approved design,

emit Task changes: with only the minimal affected canonical sections before continuing.

For shared route C. Return to PLAN and seek renewed approval:

• also use that route when chat-only simplicity no longer holds,

including when more than one active task is needed, diagrams would materially help, reliable canonical reconstruction cannot be maintained safely in chat, or final clarification decisions kept only in chat would risk loss through compaction or context loss;

• if reconstruction confidence is insufficient, first re-emit a fresh

full current chat-only task in chat;

• if the chat-only path must be promoted, reconstruct the task file

from the current canonical chat-only task state;

• then use spec-loop-prepare-implementation-approval/SKILL.md

and regain normal task-file implementation approval before continuing executable work.

For shared route D. Seek post-implementation User approval of an implemented deviation:

• if the User approves keeping the deviation, emit Task changes:

with only the minimal affected canonical sections before continuing the shared completion checkpoint.

2. Chat-only Implementation notes expression

When the shared core requires Implementation notes on the chat-only path, record them in a canonical Task changes: block unless you already need a full recovery re-emit.

If Implementation notes has content, include the complete Implementation notes section in that canonical revision, not only selected lines from it.

Example chat-only revision when notes are relevant:

Task changes:

- **Implementation notes:**
  - **Tradeoffs:**
    - Kept duplicate detection in the service layer instead of the
      repository so duplicate handling stays testable without
      persistence-coupled error mapping.

3. Chat-only expression of review

When the shared completion checklist passes, express review on the chat-only path by:

• emitting Task changes: for any canonical task changes;
• when Implementation notes has content, including the complete

Implementation notes section in that canonical revision; and

• only then presenting the implemented work in chat as ready for User

review.

If there are no canonical task changes and Implementation notes has no content, no Task changes: block is required.

There is no chat-only folder or subtask-status move.

Implementation-flow guidance for spec-loop-implementation-flow

This file is the shared implementation-flow core.

Use it with exactly one path companion chosen by SKILL.md:

• chat-only-path-guidance.md
• task-file-path-guidance.md

This core owns:

• implementation-time routes;
• authority to change canonical task sections;
• the meaning of review;
• Implementation notes; and
• the completion checkpoint.

The path companion adds only path-specific mechanics for recording or expressing those shared rules.

1. Shared ownership and source of truth

• Read this file with exactly one path companion.
• The path companion does not override this file.
• The approved active task remains the source of truth.
• Do not create a second implementation artifact or silently rewrite

the task to match the code.

• When this file requires recording a canonical change,

Implementation notes, or review, use the path companion to decide how to express it.

Implementation-start checklist:

• stay inside the approved current increment;
• return new executable work outside that increment to PLAN;
• do not make executable edits outside the approved design boundary

unless this guidance or the User explicitly authorizes them;

• if Implementation notes are later needed, use only the fixed

subheadings Interpretations, Tradeoffs, and Open questions;

• do not write Implementation notes as a chronological worklog,

test log, user clarification history, or scratchpad; and

• treat Manual tests as optional human-review hints, not as

blockers for review.

2. Allowed implementation-time routes

Only these routes are allowed when implementation reaches a decision point.

A. Continue implementation

Use this route when implementation stays inside the approved design boundary and no blocking ambiguity remains.

Adding tests beyond Test specification is allowed as long as those tests stay within the approved increment.

B. Pause the affected area and clarify

Use this route when implementation reveals a business-logic ambiguity or another issue that cannot be resolved safely from the approved task alone, but no redesign is yet known.

• Pause only the affected implementation area.
• Explain the exact reason for the pause.
• Clarification may take more than one step.
• Use the path companion to decide whether interim canonical task

updates are required to preserve confirmed state.

When the relevant clarification result is confirmed, update the minimal affected canonical section or sections as the path companion requires. If the clarification still fits inside the approved design, the user's confirmed clarification plus that canonical update is sufficient authority to continue. No separate go-ahead step is required.

C. Return to PLAN and seek renewed approval

Use this route when the discovered issue or clarification changes the approved contract or needs redesign.

Return to PLAN when the change affects any of the following:

• approved scope;
• business behavior or scenario contract;
• approved Glossary meaning, shared domain terms, or glossary usage

constraints;

• when no explicit project glossary exists, current domain language

derived from Research and the existing codebase;

• constraints or non-goals;
• new or renamed planned top-level production types;
• new or renamed planned structural elements with externally relevant

meaning;

• new cross-class boundaries;
• new externally meaningful identifiers;
• serialized, persisted, or configuration contracts; or
• dependency decisions not already approved.

When this route applies, return to spec-loop-plan-task. Use the path companion for the next path-specific steps before more executable work continues.

D. Seek post-implementation approval of an implemented deviation

Use this route when the completion comparison shows that the implementation violates the approved task content.

• Describe the deviation exactly.
• Do not rewrite canonical task sections before the user responds.
• If the user approves keeping the deviation, update only the minimal

affected canonical section or sections needed to reflect that approval, then continue the completion checkpoint.

• Do not use this route to approve a deviation that changes approved

Scenario meaning, approved Glossary meaning, shared domain terms, glossary usage constraints, or — when no explicit project glossary exists — current domain language derived from Research and the existing codebase. Use route C instead.

• That explicit post-implementation approval is sufficient authority

only for deviations that stay outside those route-C domain-language boundaries.

• If the user refuses, revise the implementation to match the approved

task before review.

After such approval, return to PLAN only if the user explicitly asks for replanning, redesign, or further changes beyond approving the implemented result.

E. Reach review

Use this route when the work is implemented, required automated verification and project-level checks have passed, and it is ready for user review.

Reaching review means the current implemented state matches the approved task and has passed the automated tests that implement the Test specification plus any required project-level checks at that checkpoint. Optional Manual tests listed as human-review hints need not be performed before review. The path companion defines how that state is expressed.

After route E is expressed, this skill is done for that increment. Later executable follow-up returns to spec-loop-plan-task.

3. Canonical task updates during implementation

Change canonical task sections only when explicit authority exists. Do not silently normalize the task to the code.

Only these sources may override earlier canonical task wording or decisions:

• an explicit user clarification statement; or
• explicit post-implementation user approval of keeping an implemented

deviation.

Update only the minimal affected canonical section or sections. Do not rewrite canonical task sections for:

• ordinary internal implementation choices;
• unapproved implementation deviations; or
• history that belongs in Implementation notes.

After implementation starts, extend Research only with newly revealed relevant facts about the original pre-implementation state. Later Research entries should say when they amend earlier findings. Do not use canonical Research to record repository states created during the current increment. Any edit that makes Research reflect state created by work on this task is forbidden.

Patch other changed canonical sections to current truth when explicit authority exists, including Scenario, Glossary, Constraints, Design, and Test specification as applicable.

When project glossary file work happens during implementation, use it only to record approved task Glossary meaning. If no explicit project glossary exists and the approved task does not require creating one, keep glossary meaning in the task artifact rather than inventing a project glossary edit.

Record the authorized change as the path companion requires.

Keep accepted clarifications and approved deviations in canonical task sections rather than logging that conversation history in Implementation notes.

4. Implementation notes

Implementation notes is not part of the canonical task definition. It is checked only at the post-implementation checkpoint.

Use it when it might help later review or development. If present, it describes the current implementation state, not the target state in canonical sections. It records implementation-time decisions and reasons above code level.

It is not a live worklog during active coding. After implementation and verification, and before reaching review, preparing or proposing a commit, or otherwise implying implementation closure, perform the mandatory Implementation notes check.

If relevant Interpretations, Tradeoffs, or Open questions exist, record them. If none exist, omit the section.

Use these fixed subheadings when notes are present:

• Interpretations
• Tradeoffs
• Open questions

Omit empty subheadings instead of placeholders.

Meaning of the subheadings:

• Interpretations = ambiguity resolved without changing the approved

contract;

• Tradeoffs = meaningful alternatives considered and why the chosen

path won; and

• Open questions = explicit non-blocking deferred decisions.

Record policy:

• keep Implementation notes as a durable implementation record, not a

scratchpad;

• record only the model's own implementation-time interpretations,

trade-offs, and open questions;

• do not use it for user clarification history, review feedback, or

general conversation history;

• do not require chronological ordering;
• after each implementation phase, update Implementation notes to

match the current implementation state and remove superseded notes; and

• during later review or planning phases, keep Implementation notes

aligned to the current implementation state rather than rewriting it to match the current target.

Open questions may remain only when all of the following are true:

• they do not block the current increment;
• they are explicitly left deferred; and
• they do not prevent the work from reaching review.

If an implementation question blocks the current increment, do not leave it unresolved in Implementation notes. Clarify it in chat. If an explicit user clarification can be kept without returning to PLAN, update the affected canonical section or sections instead of recording that clarification in Implementation notes.

5. Completion checkpoint

Compare the implementation with the approved task and its verification expectations.

For each finding:

• if it is an implementation-side interpretation, trade-off, or open

question that does not violate the approved task content and matters to later review or development, record it in Implementation notes;

• if it shows that the implementation violates the approved task

content, follow route D before changing canonical task sections or reaching review;

• otherwise, if it reveals blocking uncertainty, needs explicit user

clarification, or affects the route-C boundaries, raise it in chat and do not reach review.

Before reaching review, ensure that:

• the approved scope for the current increment is implemented;
• Scenario, Glossary, Constraints, Design, and `Test

specification` are implemented as applicable for that increment;

• any canonical task-section changes have explicit authority from an

explicit user clarification or explicit post-implementation user approval of keeping an implemented deviation;

• automated tests that implement Test specification and any required

project-level checks pass, unless the user waived them;

• any Manual tests listed as optional human-review hints are not

treated as blockers for review, and are not claimed as performed unless they were actually performed;

• if Scenario or Glossary is present, implementation and

verification still match their approved behavior and domain-language contract;

• if task Glossary is present, Design, Test specification, and

any project glossary file changes still match its approved terms;

• required glossary work is complete, including any planned project

glossary creation or update;

• the mandatory Implementation notes check has been performed;
• when relevant Implementation notes content exists,

Implementation notes is recorded;

• when Implementation notes is present, it matches the current

implementation state and outdated notes have been removed;

• any remaining Open questions are non-blocking and explicitly left

deferred; and

• no obvious leftovers remain, such as TODOs, placeholders, example

names, temporary comments, or unused imports.

If any check fails, do not reach review. Complete the missing work or follow the appropriate route from Section 2.

6. Interaction with other task skills

spec-loop-plan-task owns workflow routing, trivial/non-trivial classification, chat-only path maintenance before implementation approval, taskless eligibility, and approval gates.

spec-loop-prepare-implementation-approval owns pre-implementation Task-file readiness and approval-seeking preparation.

After approval, this shared core plus the active path companion govern:

• implementation-time route handling;
• authorized canonical updates;
• Implementation notes;
• the path-specific expression of review; and
• any needed chat-only recovery or promotion.

Do not replace the planning or approval-preparation skills. Reuse them when implementation uncovers a change that needs renewed planning or approval under route C outside the post-implementation approval case handled by route D.

When additional executable work appears outside the approved current increment before route E, do not continue in implementation mode by inertia. Return it to spec-loop-plan-task for route selection before more executable work continues.

Task-file Path Guidance for spec-loop-implementation-flow

This file applies only on the Task-file path during implementation.

Use it with the shared core in implementation-flow-guidance.md and the task-file mechanics in spec-loop-plan-task/task-file-path-guidance.md. It defines only the task-file implementation-time delta.

Task-file lifecycle, subtask, and folder ownership remain in the Task-file Path Guidance.

When a task file has or may have subtasks, apply the subtask heading/status search rule from spec-loop-plan-task/task-file-path-guidance.md before selecting the active subtask, claiming lifecycle status, or making lifecycle changes.

Do not treat the active subtask as self-sufficient. Before implementation or implementation-time clarification from a subtask, read the relevant task-level sections and diagrams needed to understand it correctly.

0. Authorized task-file updates

On the task-file path during implementation flow, the active task file is an approved, reviewer-facing artifact plus a controlled post-implementation record. Do not treat it as a general scratchpad or silently normalize it to the code.

Only these task-file edits are allowed:

• add or update Implementation notes at the mandatory checkpoint;
• update canonical task sections only when the shared core gives

explicit authority for that change;

• perform the explicitly allowed lifecycle transition, including the

minimal status or folder edits required by the Task-file Path Guidance; and

• perform minimal mechanical cleanup strictly incidental to one of the

allowed edits above, such as wrapping, indentation, spacing, or nearby list-formatting cleanup required to keep the file readable and well-formed.

Any other task-file edit during implementation flow requires explicit User approval.

If the agent discovers that it has already made an unauthorized Task-file edit during implementation flow, it must stop and disclose in chat the exact unauthorized edit. It must make no further Task-file edits except those explicitly approved by the User or otherwise authorized by this guidance, and must then follow the applicable shared route before continuing.

1. Task-file actions for the shared routes

Use the shared route semantics from implementation-flow-guidance.md. This file gives the task-file actions for those routes.

For shared route B. Pause the affected implementation and ask targeted User questions:

• during route-B clarification, update only the minimal affected

canonical sections in the active task file at clean checkpoints needed to preserve final clarification state;

• do not ask the User to review those sync edits separately during

clarification; and

• if unresolved questions remain after a sync and the clarification

still fits inside the approved design, continue clarification from the updated task file.

For shared route C. Return to PLAN and seek renewed approval:

• revise the task file as needed;
• use spec-loop-prepare-implementation-approval/SKILL.md again

before resuming implementation.

For shared route D. Seek post-implementation User approval of an implemented deviation:

• if the User approves keeping the deviation, update only the minimal

affected canonical sections in the active task file before continuing the shared completion checkpoint.

2. Task-file Implementation notes expression

When the shared core requires recording Implementation notes on the Task-file path, use this placement:

• without subtasks: task level;
• with subtasks: the active implementation subtask, unless a genuine

task-level note is needed.

Example task-file content when notes are relevant:

• Implementation notes:
• Interpretations:
• Treated repeated invite submission as idempotent because the

approved task required retry-safe behavior but did not define duplicate handling precisely.

• Tradeoffs:
• Kept duplicate detection in the service layer instead of the

repository so duplicate handling stays testable without persistence-coupled error mapping.

• Open questions:
• Bulk invite behavior is out of scope for the current increment,

so one deferred decision remains: should bulk invite flow use the same idempotency rule as single invite submission?

3. Task-file expression of review

When the shared completion checklist passes, express review on the Task-file path using the Task-file Path Guidance lifecycle rules.

• Without subtasks: move the task from in-progress to review.
• With subtasks: move the current subtask from in-progress to

review.

• When that subtask move leaves no more task-level or subtask-level

work expected and every subtask is either review or done, move the overall task to review too.

• Do not move the overall task to review yet if more task-level work

is still expected or another subtask is still backlog or in-progress.