Implement Task

implement-task

Implement changes so they are correct, reviewable, and maintainable. Optimize for small safe increments, clear ownership, explicit validation, and low future change cost.

Treat PLAN.md as a contract. Do not improvise around it silently.

Read first

• ../references/task-packet-contract.md
• ../references/persistent-artifacts-contract.md
• ../references/review-phases-contract.md
• ../references/compatibility-policy.md
• ../references/ownership-and-reuse-policy.md
• ../references/final-state-authoring-policy.md
• ../references/initiative-workflow-contract.md when implementing an initiative child packet
• ../../references/communication-mode.md
• relevant tracked AGENTS.md chain
• applicable AGENTS.override.md only if local execution constraints matter
• current task packet: INDEX.md, PLAN.md, AMENDMENTS.md, ARTIFACT_CANDIDATES.md

Implementation workflow

1. Establish scope before coding.

• Confirm the task, desired behavior, constraints, and nearby boundaries.
• Refuse to start without PLAN.md.
• Prefer root-cause fixes over surface patches when the cause is clear and local.

1. Repair packet drift before coding.

• If AMENDMENTS.md or ARTIFACT_CANDIDATES.md is missing, create the missing placeholder before continuing.
• Note the packet repair in INDEX.md.

1. Identify the true change surface.

• Find the owner modules, contracts, state transitions, persistence paths, tests, and tracked AGENTS.md constraints that define the behavior.
• Distinguish direct edits from incidental neighbors.
• Distinguish internal boundaries from real external contracts relative to the service.
• Avoid changing unrelated code unless it is a tiny blocker in the same area.

1. Apply ownership-and-reuse policy.

• Identify the existing owner for each important behavior or invariant before adding code.
• Prefer reusing, extending, or slightly refactoring that owner over creating a parallel helper/service/adapter/store/module/type.
• If existing code is close but awkward, do a small tidy-first refactor that makes reuse possible.
• Do not keep old and new same-purpose implementations alive together.
• If a genuinely new boundary is required, make the non-overlapping responsibility explicit in code and packet notes.

1. Apply the compatibility policy.

• Backward compatibility is prohibited by default.
• Do not add aliases, shims, dual support, fallback behavior, or compatibility wrappers unless the human explicitly required compatibility.
• If the change touches a real external boundary and compatibility requirements are unresolved, stop and ask the human explicitly before proceeding.
• For internal-only changes, do not ask and do not preserve compatibility.

1. Implement the chosen target state directly.

• Move canonical code/docs/contracts toward the steady-state design described in the plan.
• Remove superseded vocabulary and same-purpose residue inside owner artifacts instead of layering new semantics on top of old names.
• If a real external boundary requires temporary compatibility behavior, keep the steady-state owner and current contract obvious.

1. Implement in reviewable increments.

• Follow the plan strictly.
• Keep the system coherent after each step where possible.
• Prefer centralizing risky logic rather than spreading coordinated edits across helpers.
• Separate structural refactors from behavior changes unless combining them is clearly safer.

1. Preserve maintainability while coding.

• Keep ownership obvious.
• Minimize new sources of truth.
• Avoid hidden cross-file contracts when a local explicit contract will do.
• Write code so a human can find, understand, and change it later without reconstructing half the project.
• Keep canonical owner artifacts in one vocabulary and one state model.

1. Validate deliberately.

• Start with the smallest test or check that proves the changed behavior.
• Expand validation as confidence grows.
• If the risky path is retry/restart/cancel/recovery, validate that path directly rather than relying on happy-path tests.

1. Hand off cleanly.

• Keep AMENDMENTS.md, ARTIFACT_CANDIDATES.md, and INDEX.md current enough that both review phases can start cold.
• Record durable residue candidates when they appear.
• Commit the implementation pass before reporting back to the lead.
• Never write tracked AGENTS.md or AGENTS.override.md directly.

Plan adherence rule

• Never silently deviate from the agreed plan.
• Unauthorized backward-compatibility work counts as plan drift unless the plan or later human amendment required it explicitly.
• A new same-purpose entity that the plan did not explicitly justify also counts as plan drift.
• Leaving canonical code/docs/contracts in a visible old-plus-new hybrid shape also counts as plan drift when the target design is already known.
• If implementation reveals a blocker, contradiction, or new fact that makes the plan unsafe or impossible, stop execution.
• Report:
• the exact reason the plan can no longer be followed
• the available options
• pros and cons of each option
• how each option changes the plan
• Let the human choose.
• After the human decides, update AMENDMENTS.md before continuing implementation.

Suboptimal plan rule

• If the plan seems workable but suboptimal, do not silently improve it during implementation.
• Stay on plan.
• Leave a REVIEW_NOTE: at the relevant implementation point describing the better option and why it may be preferable.
• Treat REVIEW_NOTE as advisory only; it does not authorize changing scope or design.

Implementation principles

• Make the safest next edit obvious.
• Prefer local reasoning over clever indirection.
• Keep risky logic centralized.
• Leave the code easier to review than before.
• Make canonical owner artifacts read like the current system, not like notes about an in-progress migration.
• Avoid plans-in-code that only make sense if someone already knows the backstory.
• Prefer tidy-first reuse over greenfield duplication.
• Keep one authoritative implementation path per important behavior whenever possible.

When to slow down

Pause and think harder when:

• the task changes persistence or state ownership
• restart, retry, cancellation, or recovery semantics are involved
• the change introduces a second source of truth
• the easy fix requires scattered coordinated edits
• a test passes, but does not actually prove the risky behavior
• the real code shape disagrees with the plan
• a better design appears mid-implementation but was not approved in the plan
• you are about to add a new same-purpose entity because the current owner is inconvenient to reuse

Initiative child packets

For initiative-created child packets:

• stop immediately if PLAN.md still says Status: not_authored
• mutate code plus child packet artifacts only
• route parent initiative truth changes through sync-initiative, not ad hoc edits during coding
• keep Parent Initiative, Imported Context, dependencies, and optional CONTRACT_DECISION.md visible while implementing

Communication

Honor active caveman mode for user-facing replies per ../../references/communication-mode.md. Keep durable artifacts normal unless the human asks otherwise. Drop caveman for safety/clarity when needed, then resume.

Stateful implementation

For queues, workers, orchestration, durable tasks, async services, or other lifecycle-heavy code, explicitly preserve:

• valid state transitions
• consistent writer/reader behavior
• idempotent or intentionally controlled side effects
• truthful status and recovery behavior

Human maintainability rule

Implement so a human can later:

• find the owner logic quickly
• understand the contract without archaeological digging
• make a safe change with low context load
• know which tests prove the behavior
• change one owner instead of coordinating multiple same-purpose implementations

Review-fix loop

Treat routed review findings as executable work, not FYI.

When the lead routes P#, PS#, or M# findings back to you:

• start the fix pass immediately in the same turn unless a human decision is required
• do not stop after acknowledgement, status restatement, or repeating the findings back
• do not wait for an extra proceed if the requested fixes are within the approved plan or recorded amendments
• only pause before editing when the finding exposes true plan contradiction, missing decision authority, or unresolved external-compatibility requirements
• after the fix pass, rerun the smallest validation that proves the finding is resolved, update packet artifacts, commit that fix pass, then report results

If a finding is unclear, sharpen it fast and then keep moving. Do not normalize a review loop into ack -> wait.

Commit-before-report rule

For implementation work that changed the workspace:

• make a focused git commit before reporting back to the requester
• do this for the initial implementation pass and after every review-fix cycle
• use a Conventional Commit message that matches the actual change
• include the commit hash and subject in the handoff
• if no files changed because you are blocked or only asking a question, do not make a dummy commit; report the blocker instead

Requester-response rule

Always report the result back to the requesting side.

• If the lead/orchestrator requested the implementation or review-fix pass, reply back to the lead/orchestrator.
• If a human directly requested the implementation or steering in this pane, reply back in this pane.
• Local pane output, scratch notes, or status text without an explicit reply to the requester does not count as completion.

Review alignment

Code so the eventual reviews can cleanly answer:

• what changed
• why it changed here
• what proves it works
• whether maintainability improved or degraded
• whether any durable residue should be distilled later into tracked AGENTS.md
• whether ownership stayed single and obvious

Output shape

Default implementation handoff should leave behind:

• updated code
• actual validation run
• packet updates needed for review
• key remaining risks or limits

Avoid

• broad opportunistic refactors during a focused task
• scattering one behavior across many files without strong reason
• introducing hidden contracts when explicit ones are possible
• relying on tests that do not cover the risky path
• works for now fixes that obviously raise future maintenance cost
• silent plan drift
• self-approving design changes during implementation
• adding backward-compatibility scaffolding by default
• asking about backward compatibility for internal-only changes
• introducing a parallel same-purpose helper/service/adapter/store/module/type instead of tidying and reusing the current owner
• writing tracked AGENTS.md directly
• writing AGENTS.override.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: siarhei-belavus
• Source: siarhei-belavus/agent-public
• License: MIT

Install and usage instructions live in the source repository linked above.