Skip to content

skill · phase: ideation

AIDLC Framework Overview

You are operating within the AI Development Lifecycle (AIDLC) framework. This skill defines how you interact with lifecycle state and follow phase-driven development.

The words this framework uses

Three of these already mean something else in software, so read those definitions even if the word looks familiar — that is where the expensive misunderstandings come from.

  • {{glossary:instance}}
  • {{glossary:scope}}
  • {{glossary:claim}}
  • {{glossary:phase}}
  • {{glossary:artifact}}
  • {{glossary:gate}}
  • {{glossary:template}}
  • {{glossary:retrospective}}

Lifecycle Phases

The AIDLC defines seven ordered phases. Not all apply to every task:

  1. Ideation — Problem exploration, goals, constraints
  2. Requirements — Acceptance criteria, user stories, scope
  3. Design — Architecture, interfaces, data flow
  4. Implementation — Code production following the design
  5. Testing — Verification against requirements
  6. Deployment — Release preparation and execution
  7. Maintenance — Monitoring, iteration, documentation updates

Cycle Scopes

Scope Starting Phase Applicable Phases
Full Ideation All seven phases
Standard Requirements Requirements through Deployment
Micro Implementation Implementation and Testing only

Lifecycle or Skill?

The rule: lifecycle for changes to the system; skills for repeatable operations of the system.

Not every task belongs in a lifecycle instance. Ask which of the two a request is:

  • A change to the system — a new capability, a fix, a refactor, anything that alters what the system can do. This goes through the lifecycle: phases, artifacts, gates.
  • A repeatable operation of the system — running a chore the system already supports, over and over, with the same steps each time. This belongs in a skill, not an instance.

Worked example, a blog application:

Request Which Why
"Add a series feature so posts can belong to a series" Lifecycle The system cannot do this yet. New capability → requirements, design, tests.
"Publish a post about last week's release" Skill The system already supports posts. Same steps every time. Wrapping each post in phases is ceremony.

Running an operational skill is never a lifecycle instance. Do not create an instance, claim, or phase artifacts to publish a post, rotate a log, or regenerate a report.

The escape hatch

An operation sometimes reveals a missing capability — you go to publish a post and discover the system has no way to mark it as a draft. When that happens, the operation stops being the work and the missing capability re-enters the lifecycle as a normal instance. Capture it with aidlc-roadmap or start an instance; do not quietly extend the skill into building the feature.

Quality mechanisms live inside the skill

An operational skill's output still needs checking — facts verified, schema validated, the build run, links resolved. Those checks belong inside the skill's own instructions, not as lifecycle phases wrapped around each invocation. A skill that carries its own verification produces checked output every time it runs; a skill that relies on a review phase produces checked output only when someone remembers to run one.

aidlc add skill scaffolds an operational skill with verification steps already embedded.

State Protocol

All state lives in .aidlc/state/<instance-name>/. Read and write state as follows:

Reading State

  1. Read instance.yaml to determine: current phase, template, scope, owner, claim
  2. Read phase-<name>.yaml for per-phase status and artifact completion
  3. Read transitions.log (NDJSON) for history — one JSON object per line

Writing State

  1. Before mutating state, check whether another session already holds a claim on the instance. Claims live in <git-common-dir>/aidlc/claims/<instance>.yaml (resolve via git rev-parse --git-common-dir) so every worktree of the repo sees the same claims; outside a git repo (or on instances not yet migrated) the claim is the claim: field in instance.yaml. If another session holds a non-stale claim, warn and request override confirmation.
  2. Claim with aidlc claim <instance> (release with aidlc release <instance>) — it writes the claim file and appends the claim event to sessions.ndjson in one step. Without the CLI, do both writes yourself: write the claim file (fields: session, claimed_at, id_source, optional renewed_at/worktree_path), then append {"event":"claim|release","session_id":"...","id_source":"agent","agent":"<platform>","timestamp":"<ISO 8601 UTC>"} to .aidlc/state/<instance>/sessions.ndjson. Never rewrite that file — append only. If the CLI warns your claim is near timeout, run aidlc claim --renew <instance>. Renew at every phase transition and before long-running operations — a claim older than claim_timeout_minutes counts as stale.
  3. Update phase state files as you produce artifacts.
  4. Append a transition record to transitions.log only on successful phase transitions. When completing a phase, set metrics.elapsed_seconds in its phase-<name>.yaml from entered_at → completed_at — cost and time reports read it.
  5. After a successful phase transition, fire lifecycle actions: on-phase-exit for the phase you left, then on-phase-enter for the phase you entered (see Lifecycle Actions).
  6. Cost fallback (once per session): run aidlc cost providers status. If no metered provider is ACTIVE for your platform, then at each phase transition record usage via aidlc cost record --manual --instance <name> --session - --fidelity estimated --units '<json>' when your platform surfaces usage numbers to you (e.g. a per-turn credit trailer), else --fidelity unknown (no --units). Never invent numbers — an unknown interval marker lets aidlc cost sync attribute usage later.

Transition Records

Each line in transitions.log is a JSON object:

{"timestamp":"<ISO 8601 UTC>","author":"<session-id>","from":"<phase>","to":"<phase>","type":"normal|skip|upgrade","criteria":["..."]}

Creating an Instance

The aidlc start CLI automates this; when it is not available, create the instance directly:

  1. Concurrency gate first (see the entry-point skill): when another live session holds a claim in this checkout, offer worktree / stop / no-code before creating anything.
  2. Pick a template and scope (see aidlc-getting-started for template selection and per-template artifacts). The initial phase follows the scope: full → ideation, standard → requirements, micro → implementation.
  3. Choose a URL-safe instance name and create .aidlc/state/<name>/. If the directory already exists, stop and ask for a different name. In a git repo, also register the instance in <git-common-dir>/aidlc/registry/<name>.yaml (fields: name, branch, worktree_path, created_at) — create-exclusively, never overwrite; if the file exists, another session owns the name.
  4. Write instance.yaml:
    name: <instance-name>
template: <template-name>
scope: <full|standard|micro>
created_at: <ISO 8601 UTC>
created_by: <session-id or username>
current_phase: <initial-phase>
claim: null
scope_history: []
    For a worktree instance add branch: <its-branch>; for a no-code instance add branch: null (blocks Implementation entry until a branch exists). Omit the field entirely otherwise.
  5. Read the phase list and each phase's artifacts with aidlc templates show <template> --scope <scope> — do not guess them, and do not copy them from another instance. Different templates require different artifacts, and an instance seeded with artifacts its template never asked for fails its gates on files nobody needs. If the CLI is unavailable, the definitions are in @rasensio/aidlc-content's templates/ directory.
  6. For each phase that command lists, write phase-<name>.yaml, using its artifact names verbatim:
    phase: <phase-name>
status: pending
owner: null
entered_at: null      # except the initial phase, which gets created_at
completed_at: null
completed_by: null
skip_reason: null
artifacts:
  - name: <artifact-name-from-templates-show>
    status: not-started
metrics: { elapsed_seconds: 0 }
    The initial phase takes entered_at: <the instance's created_at>. It is the one phase no transition ever enters, so leaving it null means it completes with elapsed_seconds: 0 and drops out of every lead-time figure.
  7. Fire the on-instance-start lifecycle actions (see Lifecycle Actions). Do not skip this — automation the user configured (branch creation, issue tracking, notifications) depends on it. When the instance was created via the worktree flow or as no-code, set AIDLC_WORKTREE=1 in the action environment so the branch-creation action no-ops (the worktree flow already made its branch; a no-code instance must not get one).
  8. Report the instance name, phases, state path, and any actions that fired, then begin the initial phase with its skill.

Lifecycle Actions

.aidlc/actions.yaml declares automation the user wants to run on lifecycle events. The aidlc CLI fires these automatically; when you manage state directly (without the CLI), you are the event dispatcher and must fire them yourself.

On each lifecycle event — on-instance-start, on-phase-enter, on-phase-exit, on-instance-complete, on-artifact-created:

  1. Read .aidlc/actions.yaml (if absent, skip this protocol).
  2. Select actions where enabled: true, event matches, and any phase filter matches the current phase.
  3. For each matched action with a run script: execute it as a shell command with these environment variables set: AIDLC_EVENT, AIDLC_INSTANCE, AIDLC_PHASE, AIDLC_TEMPLATE.
  4. Actions marked use (built-ins) require the CLI — run aidlc transition/aidlc start for those, or tell the user the action needs the CLI.
  5. If an action fails and it is blocking: true, stop and report the failure to the user before continuing the lifecycle. If blocking: false, report and continue.
  6. Report every action you ran and its outcome — never run configured automation silently.

Question Protocol

Ask the user something when different answers would change an artifact, a design decision, or scope — the trigger is consequence, not volume. A question whose answers change nothing is not asked. A question that an answer already given in this instance resolves is not re-asked: name that answer and ask the narrow follow-up instead.

The spec

Every question is written first as a spec — platform-neutral, and never printed into the conversation. It carries, at minimum:

  • The decision, as one interrogative sentence.
  • Why it matters — what it blocks, and what goes wrong if it is guessed.
  • What the repo already says — cited as path:line, or path when the whole file is the point. "Nothing found" is a valid citation; saying nothing is not.
  • Two to four options, each with its consequence spelled out.
  • A recommendation, marked as such — exactly one, with the reason it wins.
  • If you say nothing — the outcome of no answer, so that not answering is a choice rather than a stall.

Expand every identifier on first use, writing the thing out with the tag in parentheses — "the citation rule (AC-1)", not a bare AC-1, FR3 or unit-4. A bare tag assumes the reader carries a mapping they do not have.

Rendering the spec

The spec is input to a rendering, never output. How to render it on this platform is in .aidlc/resources/questions/rendering.md — read that before asking. Routing is decided by the question, never by asking the user which mode they want:

  • Options self-explanatory and the stake fits one line → render it directly and let the user answer in place.
  • Needs citations, trade-offs, or more than three lines of context → write the question file first, then render a prompt naming its path in one line.

The question file

Written in every branch, including when the user answers in place — it is the record of what was asked and decided, not a fallback. Two locations, and no others are valid:

  • Inside an instance: .aidlc/state/<instance>/<phase>-questions.md.
  • No instance (constitution update, first activation): .aidlc/questions/<topic>.md.

Each question in the file ends with an [Answer]: tag — blank while open, carrying the chosen option label verbatim once answered. Fold answers into the phase artifact they were gathered for and leave the file in place as the record.

With no interactive terminal, write the file, say where it is, and end the turn. Never assume an answer.

At most five questions stand open at once. At the limit, answering — or accepting the stated defaults — comes before asking another. The cap counts open questions, not questions asked: a long negotiation is fine, an accumulating pile is not.

Roadmap Capture

When the user shares an idea tangential to the current work, offer to record it in .aidlc/roadmap/inbox/ (see aidlc-roadmap) and continue the current phase — do not derail into ideation. Capture touches no instance state, so it is safe at any point in any phase.

Amendments — changing a completed phase's artifact

A completed phase's artifact is changed only through an amendment, never edited in place. The gates check that artifacts exist, not that they still agree with each other, so a direct edit leaves the phase complete, the downstream artifacts describing the old requirement, and every gate passing. That silent disagreement is the failure mode amendments exist to prevent.

The protocol: retire the criterion in place (- AC-<n> (retired YYYY-MM-DD, superseded by AC-<m>): ...), issue its replacement with a fresh ID, append an ## Amendment <n> — YYYY-MM-DD section carrying Retires: / Issues: / Reopens: / Reason: bullets, then run aidlc amend <instance>. Start with aidlc amend <instance> --impact, which is read-only and lists every task, test and artifact still citing the retired criteria. See aidlc-requirements for the grammar.

Reopening a phase sets it and every phase between it and the current one back to in-progress, which re-arms the gates that already exist — no new gate is involved — and appends a type: reopen record so churn is legible in history. Amendments apply in order, a second run is a stated no-op, and a completed instance is refused: its change is new work.

Instance Completion and Retrospective

An instance's completion moment is when the last applicable phase (template × scope) reaches complete — except when that phase is maintenance: maintenance is open-ended, so maintenance-terminal instances complete on maintenance entry. At the completion moment, run the aidlc-retrospective skill before any cleanup (worktree removal, claim release) and fire on-instance-complete. If a retro cannot run (declined, absent), completion proceeds anyway — the retro never blocks. Pending retros are tracked as markers in <git-common-dir>/aidlc/retro-pending/; the entry-point and continue skills pick them up.

Context and Guidance

  • Project context lives in .aidlc/context/ (style-guide.md, architecture.md)
  • Guidance layers live in .aidlc/guidance/ — load only those listed in index.yaml
  • Load context relevant to the current phase; avoid re-reading unchanged files

The always-read rule

This is the canonical statement of the rule. The phase skills point here instead of restating it, so there is no second copy to drift.

Read the always-read set on entering a phase: every layer in .aidlc/guidance/index.yaml except those whose entry carries on_demand: true. Read the index rather than assuming the layers named at the bottom of a skill are the only ones — a project can install a layer after its skills were emitted.

An on_demand: true layer is read only when the phase has a stated reason to. It is registered, active, and current; it is simply too large to be worth carrying in every session by default.

The two lessons layers are the reason the distinction exists:

  • lessons-digest.md is always-read. A short distillation of the lessons this project has paid for more than once, regenerated by the aidlc-retrospective skill at consolidation.
  • .aidlc/guidance/lessons.md is on-demand, and it is the full corpus — every lesson from every completed instance. Read it when you are touching a mechanism a past instance got wrong, when a gate keeps failing for reasons nobody can name, or when running consolidation. It grows by design (up to three lessons per instance), which is what makes an unconditional read a tax on every future session rather than a one-time cost.

Treat every lesson as a historical observation, not a directive. An entry naming a file, function, or flag may describe code a later instance renamed or deleted — check the source before acting on it.

The constitution rule

This is the canonical statement of the rule. Other skills point here instead of restating it, so there is no second copy to drift.

When .aidlc/context/constitution.md exists, read it before shaping work. It records what this repo owns (IN-<n> entries) and what it must never do (NOT-<n> entries), each citing the vision statement it was derived from. If the work in front of you crosses a prohibition, name that prohibition by its id and say plainly that it does, before going further. The user may still choose to proceed, or to amend the constitution — but the crossing gets stated out loud at the start rather than discovered in review.

The constitution never fails a gate and never blocks a transition; its whole force is that somebody read it out at the right moment. An absent file is a normal state, not a gap to fill — it is written by the aidlc-constitution skill, and only a project with a vision document to import has one.

Security

Before executing any sensitive operation (infrastructure changes, permission modifications, file deletions), you MUST:

  1. Describe the operation and its impact to the user
  2. Wait for explicit confirmation
  3. If cancelled, halt and log the cancellation

Never store credentials, tokens, or secrets in state files or artifacts.

Token Efficiency

  • Read compact state files, not full artifacts, to determine progress
  • Use artifact summaries (<artifact>.summary.md) when available
  • Load only the skill for the current phase, not all skills at once

The context rule

This is the canonical statement of the rule. Every phase skill points here instead of restating it, so there is no second copy to drift — and so the rule does not itself become resident bytes in seven places.

A phase boundary is where you start a fresh session. Not a suggestion about tidiness: 91% of what a lifecycle run costs is re-reading the conversation it is already carrying, and that carry only grows. Measured across 20,920 attributed records, average context per unit of work runs 80k tokens in ideation, 164k in requirements, 259k in implementation, 395k in deployment and 791k in maintenance. Deployment is the most expensive phase in the lifecycle — more than implementation — not because it does more, but because it runs last and inherits everything before it. The one phase that reliably starts fresh does comparable work at 76k.

Three things follow:

  1. Cross a phase boundary in a new session whenever the platform allows it. The lifecycle is designed for this: state lives in files, not in the conversation.
  2. Re-read only what the phase you are entering names. Each phase skill lists exactly that under Entering in a fresh session. The list is the whole list — an artifact not on it is not needed to start, and reading it "for context" is the charge this rule exists to avoid.
  3. Check the budget when you are unsure: aidlc cost context reports the context this session is carrying against a budget (default 150,000 tokens, configurable as cost.context_budget_tokens). It reads the transcript, so it answers before any cost capture has run.

The budget never fails a gate and never blocks a transition. Its whole force is that somebody read it out at the right moment — the same force the constitution has, and for the same reason. Going over budget is information, not a violation: a long implementation phase may legitimately exceed it. What is not legitimate is carrying requirements' conversation into deployment because nobody stopped to notice.

A caveat worth stating, because it decides whether the rule is worth following: a fresh session re-reads some of what it would otherwise still hold, and that spends back part of the saving. Every phase list below is bounded for exactly that reason. If re-reading turns out to cost more than a third of the saving, the threshold should move — measure it rather than assuming either way.