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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.
10. 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.