Skip to content

skill · phase: ideation

AIDLC Entry Point

This skill is the front door to the AIDLC framework. When invoked, show the user where their lifecycle work stands and let them choose what to do next. Everything needed is in .aidlc/ — the CLI is not required at runtime.

Pre-condition: First Activation

If .aidlc/context/ does not exist or contains no .md files, defer to the aidlc-first-activation skill first, then return to the user's original request.

Step 1 — Read State

{{glossary:instance}} {{glossary:claim}} {{glossary:template}}

  1. List the directories under .aidlc/state/. Each directory is a lifecycle instance.
  2. For each instance, read instance.yaml (current phase, template, scope, claim) and the phase-<name>.yaml files to compute completion (complete artifacts ÷ total required artifacts).
  3. Read .aidlc/config.yaml for project defaults (scope, template) if present.
  4. Count roadmap items per status directory under .aidlc/roadmap/ (inbox, backlog, in-progress, done, hold) — count files, and read frontmatter only if a title is needed. Never read item bodies. Status is the directory; there is no status field to read.
  5. Count pending questions — the question files matching .aidlc/state/*/*-questions.md and .aidlc/questions/*.md that contain at least one blank [Answer]: tag. Grep for the tag; do not read the question bodies. This is the only read that opens a question file at menu time.
  6. Check <git-common-dir>/aidlc/retro-pending/ (resolve via git rev-parse --git-common-dir) for pending-retrospective markers. Each marker adds a menu entry: Run retrospective for <instance> (routes to the aidlc-retrospective skill). A marker whose instance has no state dir and no registry entry is stale — remove it and note the cleanup in one line.

Do not read artifact bodies or transition history to build the menu — the compact state files are enough.

Step 2 — Present the Menu

Compose a short menu from the state. Include only the options that make sense:

  • Continue <instance> — one entry per incomplete instance, showing current phase and completion percentage. Most recently updated first.
  • Start something new — always.
  • Capture a roadmap item — always.
  • Answer pending questions — when the pending-question count is above zero; show it and where they are (e.g. "2 questions waiting — my-feature, constitution update"). List this first among the roadmap and question entries: an unanswered question is work already blocked.
  • Triage the inbox — when inbox/ is non-empty; show the count (e.g. "3 items awaiting triage"). List this above Browse — an untriaged submission is somebody waiting on a decision.
  • Browse / promote the roadmap — when any status directory outside hold/ is non-empty; show counts per status (e.g. "3 inbox, 5 backlog, 1 in progress, 12 done").
  • Show status — when at least one instance exists.
  • Review an artifact — when at least one instance has a completed artifact.
  • Help / getting started — always.

Present the options as a numbered list (or the platform's native selection prompt) and wait for a choice. If the user's message already states what they want (e.g. "continue my-feature"), skip the menu and route directly.

If .aidlc/state/ is empty or missing, offer just three options: start something new, capture a roadmap item, or help.

Step 3 — Route

Choice Action
Continue an instance Follow the aidlc-continue skill
Start something new Run the concurrency gate (below), then ask what they are building, pick a template (see aidlc-getting-started), and create the instance per "Creating an Instance" in aidlc-overview
Capture a roadmap item Follow the aidlc-roadmap skill (capture flow)
Answer pending questions Open the question file, re-render its open questions per the Question Protocol in aidlc-overview, record each answer in the file, then fold them into the artifact they were gathered for
Triage the inbox Follow the aidlc-roadmap skill (triage flow)
Browse / promote the roadmap Follow the aidlc-roadmap skill (browse/promote flow)
Show status Summarize each instance from its state files — name, template, current phase, completion %, and whether it looks stalled. When the roadmap is non-empty, append the per-status counts (e.g. "roadmap: 3 inbox, 5 backlog, 12 done")
Review an artifact Follow the aidlc-review skill
Help / getting started Follow the aidlc-getting-started skill

Concurrency Gate (before "Start something new")

Two sessions sharing one checkout collide on git, not on state: creating a branch in-place yanks the other session off its branch. Before creating anything, check whether another live session holds a claim:

  1. Read the claim files under <git-common-dir>/aidlc/claims/ (resolve via git rev-parse --git-common-dir; legacy fallback: claim: in each instance.yaml). A claim is live when renewed_at/claimed_at is within claim_timeout_minutes (config, default 60) and it is not this session's own claim.
  2. A live claim only blocks when it shares this working directory. The question is not "is another session live?" but "does another session share my working directory?" — a session in its own worktree, on its own branch, cannot yank you off yours or stage your files. A claim's directory is its worktree_path when it has one, and the primary checkout when that field is absent. A worktree_path naming a directory that no longer exists is a claim on the primary checkout again.
  3. A live claim that does not share this working directory: say so in one line and proceed with no gate. Knowing another instance is in flight is useful even when it cannot interfere; silence would be worse.
  4. Not a git repo, or no live claim sharing this working directory → proceed normally, no gate.
  5. A live claim sharing this working directory → present exactly three options and proceed with none until one is chosen:
    1. Start in a separate worktree (recommended) — git worktree add -b <prefix>/<YYYYMMDD>-<name> <worktree_dir>/<repo>-<name> main (prefix per template: bugfix→fix, micro-task/spike→chore, else feat; worktree_dir from the concurrency: config block, default ../). Do all further work for the new instance inside that worktree; set AIDLC_WORKTREE=1 before firing on-instance-start actions so the branch action no-ops. CLI shortcut: aidlc start <template> --name <name> --worktree.
    2. Stop — come back when the other instance is done.
    3. Continue in this checkout, no code changes — record branch: null in the new instance.yaml; entering Implementation stays blocked until a branch exists. CLI shortcut: aidlc start <template> --name <name> --no-code.
  6. concurrency.mode: forbid in config replaces the menu with a hard stop while another session is live — any live session, sharing this working directory or not. Someone choosing a hard stop is choosing it for reasons this gate should not second-guess.

Rules

  • Building the menu is read-only — never mutate state while composing it. Claims are taken by the routed skill (see aidlc-continue).
  • Keep the menu short; do not explain the whole framework unless the user asks for help.