Skip to content

skill · phase: implementation

Implementation Phase

Purpose

Produce working code that satisfies the design and requirements. Follow project conventions discovered in context docs.

Entry Criteria

{{glossary:scope}}

  • Design phase complete (Full/Standard scope) OR instance created with Micro scope (task description + criteria exist)
  • The instance is claimed by this session

Entering in a fresh session

Read only:

  • instance.yaml
  • tasks.md — the next unchecked task is where work resumes
  • design.md — the sections the next task cites, not the whole document once tasks are under way
  • requirements.md — the acceptance criteria the next task claims
  • the always-read guidance layers named in .aidlc/guidance/index.yaml (see The always-read rule (.aidlc/resources/rules/always-read.md))
  • .aidlc/context/style-guide.md
  • implementation-questions.md, when it exists — whether tasks go to one agent each

Then the source files that task touches. See The context rule (.aidlc/resources/rules/context.md).

Required Artifacts

  • Source code changes implementing the feature or fix
  • Updated or new tests (handed off to Testing phase for verification)

Instructions

{{glossary:gate}}

  1. Load context. Read .aidlc/context/style-guide.md and .aidlc/context/architecture.md if they exist. Match the project's established patterns. If the project has a knowledge graph (.aidlc/knowledge/ exists), also run aidlc knowledge context --scope phase --phase implementation and query it (aidlc knowledge query <term>) before re-exploring code it already describes — as an index into the source, never a substitute for reading it. Open the file before calling anything the graph names; an entry can outlive the symbol it describes.

  2. Load guidance. Read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule (.aidlc/resources/rules/always-read.md) for which layers those are and when to reach for the full lessons.md. Apply their rules during implementation.

  3. Check that the planning artifacts agree. Before the first task, run aidlc cross-check <instance> and show the user the list. It reads requirements.md, design.md and tasks.md side by side and prints one line per gap — a criterion no task cites, a task citing no criterion, a criterion design never mentions — each naming both artifacts and the ID. It is a report: it writes nothing and never blocks, and acting on a gap is the user's call. A gap in tasks.md is fixed in place, since its phase is still open here; a gap in a completed requirements.md or design.md is fixed through an amendment (Amending a Completed Phase, in the requirements skill), never by editing it silently. Unattended (AIDLC_UNATTENDED=1): record the list in code-complete.md and carry on.

  4. Execute the task breakdown. When the instance has a tasks.md (produced in Design for full/quick-feature scope), read it and execute tasks in order: complete a task, then mark its checkbox [x] as part of the same work unit — never batch checkbox updates for later. A task that should not be done is deferred in place (- [>] T<n>: <title> (deferred YYYY-MM-DD: <reason>)) with a dated reason, never skipped silently or deleted; the implementation→testing gate blocks on open tasks. For bugfix scope, create the optional tasks.md at implementation start when the fix spans more than one commit-sized unit. For Micro scope, reference the task description and acceptance criteria directly — no task file.

    One agent per task. Where the platform's entry for this skill says sub-agents are available and the instance has a task-bearing tasks.md, offer it before the first task — or take the mode task_agents, the prompt, the roadmap item or a recorded answer already names — exactly as The task-agents rule (.aidlc/resources/rules/task-agents.md) says. Chosen, it replaces the task-by-task work above: each task goes to a fresh agent, a second agent reviews it, and the box is ticked only after that review passes. Not offered, or not chosen, run every task in this session as before.

  5. Write code. Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns). Code that would build other than what was agreed is asked before it is written, as The departure rule (.aidlc/resources/rules/departures.md) says.

  6. Handle sensitive operations. Before executing any of the following, describe the action and wait for explicit user confirmation (unattended, AIDLC_UNATTENDED=1: each is a hard stop except reverting this session's own changes, per .aidlc/resources/rules/unattended.md):

    • File deletions or destructive operations
    • Infrastructure changes (provisioning, configuration)
    • Permission or access control modifications
    • Credential or secret handling

  7. Commit incrementally, one task per commit where you can. Produce working code at each step; avoid large uncommittable diffs. End every commit made for a task with a git trailer naming it — Task: <instance>/T<n> on its own line in the last paragraph of the message, one line per task when a commit spans two. The trailer is what lets aidlc revert <instance> --task T<n> find that task's commits later and undo them in one step, after showing the plan; a commit without it is invisible to the command.

  8. Update the knowledge graph. After modifying code, record what changed with aidlc knowledge add / relate / update: new or restructured modules, decisions taken, debt introduced or paid down. Keep the graph in sync with the code you just changed.

  9. Update state. As implementation artifacts are produced, mark them in phase-implementation.yaml.

Exit Criteria

  • All acceptance criteria from requirements are addressed in code
  • Code follows project style (naming, formatting, patterns from context docs)
  • No unresolved TODOs or placeholder implementations remain for required functionality
  • Guidance layer rules have been applied (security defaults, accessibility, API conventions)

Guidance

{{context:style-guide}} {{context:architecture}} {{guidance:secure-defaults}} {{guidance:accessibility}} {{guidance:api-conventions}}

Security Confirmation

Unattended (AIDLC_UNATTENDED=1): nobody can confirm, so everything this section asks to confirm is a hard stop, per .aidlc/resources/rules/unattended.md.

Before proceeding with any sensitive operation during implementation:

  1. Describe what the operation does and what it affects
  2. State whether it is reversible
  3. Wait for explicit user acknowledgment
  4. If the user cancels, halt execution and log the cancellation with a timestamp in state

Never store credentials, API keys, tokens, or passwords in source code or state files. Use placeholder syntax for secrets (e.g., ${SECRET_NAME}).

Completion

When exit criteria are met, update phase-implementation.yaml status to complete and append a transition record to transitions.log.

Then end the turn as The next-steps rule (.aidlc/resources/rules/next-steps.md) says.

Changing a completed phase's artifact. Do it only through an amendment — append an ## Amendment <n> — YYYY-MM-DD section to requirements.md with Retires:, Issues:, Reopens: and Reason: bullets, then run aidlc amend <instance> (start with --impact to see what still cites the retired criteria). Editing the artifact directly leaves every gate passing while the requirements and the code disagree.