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 following the design; agent per task: .aidlc/resources/rules/task-agents.md
  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?

Whether a request is a lifecycle instance or an operational skill, and what to do when an operation turns out to need a new capability. The rule is in .aidlc/resources/rules/lifecycle-or-skill.md.

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

Creating an instance by hand when the aidlc start CLI is not available. The rule is in .aidlc/resources/rules/creating-an-instance.md.

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 a blocking: true action fails on on-phase-exit, do not move; on on-phase-enter or on-instance-complete, keep the move. Non-blocking: carry on.
  6. Report every action you ran and its outcome — never run configured automation silently.

Question Protocol

When and how to ask the user: .aidlc/resources/rules/question-protocol.md. With nobody there: .aidlc/resources/rules/unattended.md. Before departing from what was agreed: .aidlc/resources/rules/departures.md.

Ending a Phase or a Review

How to end a turn: decisions asked, fixes offered together, and one next command. The rule is in .aidlc/resources/rules/next-steps.md.

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.

Safe for the instance is not the same as free for the person, so two rules bind every item an instance writes, exactly as they bind the capture flow:

  • Merge first. If an open item already owns the area, append a dated ## Received from <instance> section to that item instead of writing a new one.
  • No item enters inbox/ without its six-line executive summary (the labels are in aidlc-roadmap). Write it from what you know; Not yet decided. is a valid value for any label, an absent section is not. An item nobody can triage from the top of the file is not a captured idea, it is a decision deferred onto somebody else.

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
  • Why AIDLC works as it does: aidlc explain lists topics, aidlc explain <topic> prints one

The always-read rule

Which guidance layers to read on entering a phase, and when to reach for the full lessons.md. The rule is in .aidlc/resources/rules/always-read.md.

The constitution rule

What to do before shaping work when .aidlc/context/constitution.md exists. The rule is in .aidlc/resources/rules/constitution.md.

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

Why a phase boundary is where a fresh session starts, and what to re-read after one. The rule is in .aidlc/resources/rules/context.md.

The rules

The always-read rule

This file is the only 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 file is the only 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.

The context rule

This file is the only 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.

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 in aidlc-overview). 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.

The departure rule

What was agreed is what gets built. Changing it is the owner's call, never the agent's.

What a departure is

A change that narrows, widens or replaces what one of three sources says:

  • an acceptance criterion or a scope boundary in requirements.md;
  • the roadmap item the instance came from (roadmap-item.md);
  • a person's recorded answer in a question file — an [Answer]: not marked (unattended default).

A choice those sources leave open is not a departure: internal names, file layout, the order of work, how something is tested. Decide it and record it as usual; do not ask.

Example: the user picked the Cockpit layout, and building the one-column Stream instead, because Cockpit is harder, is a departure. Calling the module cockpit.ts or dashboard.ts is not.

What to do

Stop before the change is written — in design, before it reaches design.md; in implementation, before the code. Ask through the Question Protocol (.aidlc/resources/rules/question-protocol.md) in that phase's question file. Quote the source and what it says, and make keeping what was agreed one of the options.

A change the person accepts that alters a completed requirements.md goes through an amendment (Amending a Completed Phase, in the requirements skill), never a silent edit.

Unattended

With AIDLC_UNATTENDED=1, build what was agreed, even when another option looks better. A run that cannot is the departs-from-agreed hard stop in .aidlc/resources/rules/unattended.md, never a logged deviation.

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.

The next-steps rule

This file is the only statement of the rule. The phase skills and the review skill point here instead of restating it.

Never end a phase or a review on a state. "26 findings", "gate failed" and "phase in progress" tell the user where things are and leave them to work out the path. End instead with what they must decide, what you can fix, and one command.

When it applies

  • At the end of a phase, once its exit criteria are met or it cannot go further without the user.
  • At the end of a review, after the findings file is written.
  • After an aidlc gate or aidlc transition failure you are reporting.

Sort what is still open

Put every open item — finding, gap, failed criterion — into exactly one of two groups:

  1. Needs your decision. Different answers would change an artifact, the scope, or the product: which principal is refused, whether production behaviour changes, what an edge case should return. Ask these through the Question Protocol (.aidlc/resources/rules/question-protocol.md) — in place when the options fit one line, in .aidlc/state/<instance>/<phase>-questions.md when they need context. Name the item each question came from.
  2. I can fix these. One correct answer exists and you can apply it: a wrong rule id, a stale sentence, an over-broad permission, a missing test, a task out of order. List them, one line each, and offer to apply them all in one step. Do not ask about each one separately.

An item you cannot place is a decision. Do not quietly fix something that was the user's to choose.

When both groups are empty, say so in one line.

End with one next command

Close the turn with exactly one next step. It names a command the user can run as written — the real instance name, the real phase or artifact — or, when decisions are open, says to answer them first.

  • Decisions are open → answer them first; no command yet.
  • Fixes are offered and not yet applied → the fixes, then the command below.
  • The phase's exit criteria are met → aidlc transition <instance>. That is the step that marks the phase complete; aidlc gate only checks, and fails on an open phase until it runs.
  • A review finished with no open critical finding → aidlc transition <instance> for the phase the artifact belongs to.
  • The instance's last phase is done → the retrospective (aidlc-retrospective).

If the CLI printed a Next steps: block, use it — it names the fix for each failure it reported.

What this rule does not do

It changes what you report, not what you write. It adds no writer of phase-<name>.yaml or transitions.log: the Completion section of each skill still says how the phase is closed.

Question Protocol

Ask 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. Building something other than what was agreed is always asked: .aidlc/resources/rules/departures.md.

Before asking, check the sources: .aidlc/config.yaml, the roadmap item, the starting prompt, the answers already recorded in this instance, and the code. If one answers it, do not ask: write the answer into the artifact it was for, citing path:line or path. A question whose recommendation could only quote one of them is already answered. Ask when they disagree or none decides; an earlier answer is not re-asked — ask only the narrow follow-up.

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.
  • What it is — what the thing being decided is and what it does, in plain words, shown on one concrete example with names, values or dates. Required on every question: the person answering owns the decision but was not in your research, and does not carry the vocabulary you just read. For an everyday concept this is one sentence; its length scales, its presence does not.
  • 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. Schema terms, mechanism names and citations belong here, not in the options.
  • Two to four options, each defined by its observable effect — who sees what, what gets rejected, what gets flagged — with its consequence spelled out. Say what would happen, not how it would be built.
  • 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.

When several questions in one file share a concept, open the file with one shared primer that explains it, and have every question reuse the same running example rather than inventing a new one. The reader learns the example once and then sees each option applied to it.

The example shows what would really happen. One simplified until it changes the answer misleads as badly as jargon does, and it is harder to spot.

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: 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 here 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.

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

Unattended (AIDLC_UNATTENDED=1) is the one exception, and it is not an assumption: take the recommended option, write it into [Answer]: followed by (unattended default), and log it — or, when that option falls in a hard-stop class, stop. Both per .aidlc/resources/rules/unattended.md.

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.

The task-agents rule

This file is the only statement of the rule; the implementation skill points here.

One agent per task hands each task in tasks.md to a fresh agent, then has a second fresh agent review it. The agent that wrote the code does not decide it is done. It is off unless chosen.

When it is offered

Only for an instance with a task-bearing tasks.md, and only where the platform's entry for the skill says sub-agents are available — a line at the top of the loaded skill file. Without it, every task runs in the session.

Choosing, once per instance

One session — every task runs here; cheapest, and later tasks inherit earlier context. One agent per task — roughly twice the tokens.

Recommend per task_agents in .aidlc/config.yaml: One agent per task if per-task, else One session. The starting prompt or roadmap-item.md asking for the other wins. An [Answer]: already recorded is followed, never re-asked. Unattended, take the recommendation as the open-question default — so autopilot follows the repo.

Do not ask when task_agents is set, the prompt or roadmap-item.md names a mode, or an [Answer]: is recorded: take that mode, name it and its source in one line and in code-complete.md, and start. Otherwise ask, before the first task, through the Question Protocol (.aidlc/resources/rules/question-protocol.md) in .aidlc/state/<instance>/implementation-questions.md.

The loop, task by task

Take open tasks in number order. For each one:

  1. Record where it starts. BASE=$(git rev-parse HEAD).

  2. Implement, in a fresh agent. Give it only: the task line; the text of each criterion it cites, from requirements.md; the design.md sections it names; .aidlc/context/style-guide.md; the files it touches. Tell it:

    • change no test file that already exists unless the task's own text says to — add new tests instead;
    • do not edit requirements.md or tasks.md;
    • do not commit and do not tick the checkbox;
    • reply with the files it changed.

  3. Review, in a second fresh agent that edits nothing. Use aidlc-reviewer, which cannot edit files (Claude Code: subagent_type; Codex: spawn_agent); where it is not loaded, tell a fresh agent to edit nothing. First run git add --intent-to-add ., so new files show in the diff unstaged. Then give the reviewer the same task line and criteria text, the output of git diff $BASE, and the output of this command, run by you:

    git diff --name-status --diff-filter=MDR $BASE -- '*test*' '*spec*' .aidlc/state/<instance>/requirements.md .aidlc/state/<instance>/tasks.md

    It lists every test or spec file, and the two files that define done, that existed at BASE and was modified, deleted or renamed. Adding a test is never a flag. Tell the reviewer:

    • judge the diff against each cited criterion — met, or not and why;
    • every listed file is flagged; it fails the task unless the task's own text calls for that change — a loosened assertion, a skipped test or a narrowed criterion is what this catches;
    • reply PASS or REJECT, the reasons, and the flagged files with a verdict on each.

  4. On REJECT, a new implementing agent, given the reviewer's reasons, fixes what is on disk; review again from the same BASE. After a second REJECT, stop handing the task out: finish it in this session and review it once more, or defer it in place with a dated reason.

  5. On PASS, tick the task's checkbox and commit the task — one commit per task, on the instance branch.

Waves

Adjacent open tasks carrying the same (wave: <n>) may be handed out at once, each to its own implementing agent, in this one checkout — never in separate worktrees. BASE is where the wave starts. Each task still gets its own reviewer, told which files its implementer reported, to judge within the shared diff; run the listing command once and give every reviewer its output. Commit task by task as each passes, staging only the files its implementer reported. A task failing twice holds up no other: it is finished in the session afterwards.

The record

Add a ## Task reviews section to code-complete.md, one line per task:

- T5: REJECT → PASS — attempts 2 — flagged: test/parser.test.ts (task asks to update it)
- T6: finished in session — attempts 2 — flagged: none

The unattended rule

This file is the only statement of the rule. Skills point here instead of restating it, so there is no second copy to drift.

Unattended mode is on exactly when the environment variable AIDLC_UNATTENDED is 1 (printenv AIDLC_UNATTENDED). Otherwise every skill behaves as written. Nobody answers in this mode, so every place a skill would stop for a person has one outcome:

  • Default and log — take the named default, log it, carry on.
  • Decide and log — choose inside the item's scope, log a typed entry, carry on.
  • Hard stop — log it, park the item, release the claim, end the session.
  • Release boundary — the normal end of an unattended run. Not a hard stop, and the item is not parked.
  • Review boundary — a planned stop for a person's review, part way through. Not a hard stop, and the item is not parked.

A situation no stop below covers is decided and logged when its choice lies inside the roadmap item's "What success looks like". Outside it, or in a hard-stop class, it is a hard stop: guessing about scope is what this mode exists to prevent.

The log

Append one entry per default, decision or hard stop to .aidlc/state/<instance>/unattended-stops.md: a ## <n>. <title> — <slug> heading, then Source: (skill and section, or rule), Instruction: (the exact text), Decided: (the default, the choice, or "hard stop"), Type: (default for a listed stop or a hard stop; for a decision, interpretation — how an unclear requirement was read, deviation — a design detail not followed that changes no scope and no chosen option, never a departure, or open-question — needs a person), Why: (why it is safe, or which hard-stop class). A Question Protocol answer also carries (unattended default) in its [Answer]: — how a reviewer finds every choice nobody made. An open-question builds the option easiest to undo, says how to switch, and still reaches a pull request, which autopilot does not merge until a person has answered.

Waiting for a command

Unattended, the end of the turn is the end of the session, and a command still running dies with it. Run a long command in the foreground, or poll it inside the turn until it ends. Never end the turn while it runs, or to wait for a wakeup or a notification.

This binds unattended agents. The one exception is the attended session watching an autopilot run (aidlc-autopilot): it ends its turn to wait for aidlc autopilot wait --pending.

Hard stop

Always a hard stop:

  1. Crossing a prohibition in .aidlc/context/constitution.md.
  2. Deleting or overwriting data this session did not create.
  3. Changing authentication, secrets, permissions or CI tokens, or handling real credentials.
  4. Growing scope beyond the roadmap item's "What success looks like".

To stop:

  1. Append the log entry.
  2. Run aidlc roadmap park <instance> --reason "<slug>: <one line>".
  3. Run aidlc release <instance>.
  4. End the session. Commit nothing more; try no other route to the same outcome.

The release boundary

When testing completes, write the deployment record's release plan and end the session. Do not push, open a pull request, merge or release: whatever runs the agent owns those, and two actors on one release lane is how two releases collided on 2026-10-01.

The review boundary

AIDLC_PAUSE_AFTER (printenv AIDLC_PAUSE_AFTER) is a comma-separated list of phase names, set by whatever runs the agent. Empty or unset names none, and every phase boundary is the phase-end-turn default: carry on.

When it names the phase that just completed, that boundary is a review boundary. A person reads the artifact and approves it; the run carries the work on afterwards, in a later session. So:

  1. Append the log entry.
  2. Commit on the instance branch. Never push, open a pull request, merge or release.
  3. Run aidlc release <instance> — a review can outlast the claim's 60-minute staleness, and the next session must not find a claim it has to override.
  4. End the session. Do not park the item: it is waiting, not failed.

The phase is still completed and transitioned first, so the next session resumes from the next phase.

Every known stop

Each bullet begins with its one outcome; a condition after it is part of the rule.

  • entry-menu — default and log: route to what the prompt names.
  • instance-name-taken — hard stop: another session's work or an abandoned start, indistinguishable from here.
  • template-choice — default and log: what the item or prompt names, else defaults: in .aidlc/config.yaml.
  • worktree-hand-off — default and log: when the prompt says to continue, continue in the worktree.
  • roadmap-move-uncommitted — default and log: leave it uncommitted; the caller commits.
  • roadmap-item-unlinked — default and log: use aidlc start --roadmap-item; never move the item by hand.
  • requirements-input — default and log: read roadmap-item.md; with neither it nor an ideation artifact, hard stop.
  • open-question — default and log: the recommended option, marked (unattended default); if it is a hard-stop class, hard stop — never another option.
  • requirements-confirmation — hard stop when the requirements exceed the roadmap item; inside it, nothing is confirmed or logged.
  • design-confirmation — hard stop when the design exceeds the roadmap item; inside it, nothing is confirmed or logged.
  • phase-end-turn — default and log: continue into the next phase, unless AIDLC_PAUSE_AFTER names the phase just completed, which is a review boundary.
  • review-boundary — review boundary: AIDLC_PAUSE_AFTER names the phase just completed.
  • fresh-session — default and log: continue; the runner decides where sessions start.
  • own-change-revert — default and log: reverting this session's own change, after keeping a copy.
  • generated-output-discard — hard stop: discarding output this session did not write.
  • sensitive-operation — hard stop: deletions, infrastructure, permissions, credentials — except own-change-revert.
  • shared-state-prune — default and log: it removes only entries whose worktree is gone and branch merged or deleted; log the names it prints.
  • commit-incrementally — default and log: on the instance branch only; never main, never push.
  • testing-security — hard stop: production-like environments, real credentials, destructive operations.
  • platform-unknown — default and log: carry on; the runner sets AIDLC_AGENT.
  • release-boundary — release boundary: completing testing.
  • departs-from-agreed — hard stop: design or implementation cannot keep to what was agreed (.aidlc/resources/rules/departures.md); keeping to it is no stop.
  • caused-by — hard stop: the bugfix caused_by question; only a person names which instance caused a bug.