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 in aidlc-overview)
  • .aidlc/context/style-guide.md

Then the source files that task touches. See The context rule in aidlc-overview.

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 in aidlc-overview for which layers those are and when to reach for the full lessons.md. Apply their rules during implementation.
  3. 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.
  4. Write code. Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
  5. Handle sensitive operations. Before executing any of the following, describe the action and wait for explicit user confirmation:
    • File deletions or destructive operations
    • Infrastructure changes (provisioning, configuration)
    • Permission or access control modifications
    • Credential or secret handling
  6. Commit incrementally. Produce working code at each step; avoid large uncommittable diffs.
  7. 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.
  8. 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

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.

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.