@delete101020/aidlc 4.0.0

package/README.md

@@ -0,0 +1,684 @@
+# @delete101020/aidlc
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-97ca00)](https://github.com/delete101020/ai-native-sdlc/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/@delete101020/aidlc)](https://www.npmjs.com/package/@delete101020/aidlc)
+
+Terminal CLI for AIDLC — drives Claude through pipelines you declare in
+`.aidlc/workspace.yaml`. Manages the workspace, executes runs end-to-end via
+the `claude` CLI, and shares state with the VS Code extension over the
+filesystem (no daemon, no IPC).
+
+**Claude only.** The CLI shells out to `claude --print --append-system-prompt
+<skill>`. No Anthropic SDK calls, no other model runners.
+
+### New in 0.8
+
+`aidlc globals install` now also installs the **artifact annotation** tooling under
+`~/.claude` — a zero-dependency Markdown→HTML renderer, a vendored
+[annotron](https://www.npmjs.com/package/annotron) review editor (no global install), a
+per-epic **memory** tool, and the `/annotate-artifact` + `/epic-context` skills. Review epic
+artifacts in a browser and apply feedback back to the Markdown — from a plain terminal +
+Claude Code, no VS Code required. Optional `aidlc globals memory-hook enable` auto-loads an
+epic's memory whenever a prompt mentions it. See the [`globals`](#globals--built-in-workflow-agents--skills-under-claude) command.
+
+## Install
+
+The CLI of **AIDLC Native**, a fork of [`aidlc-io/aidlc`](https://github.com/aidlc-io/aidlc)
+(not affiliated with the upstream author). The package is scoped because the
+upstream owns `aidlc` on npm; the command it installs is still `aidlc`:
+
+```sh
+npm install -g @delete101020/aidlc
+aidlc --version
+```
+
+If the upstream `aidlc` package is installed globally, `npm uninstall -g aidlc`
+first — both provide the `aidlc` command.
+
+To run unreleased changes, build it from the repo:
+
+```sh
+pnpm install                                 # at repo root
+pnpm -r compile
+cd packages/cli && pnpm bundle && npm link   # makes `aidlc` available globally
+aidlc --version                              # 3.5.1
+```
+
+`npm link` points at the working tree, so a later `pnpm bundle` is enough to
+pick up changes — no reinstall.
+
+## Prerequisites
+
+- **Node.js ≥ 18**
+- **`claude` CLI** on PATH — install from https://github.com/anthropics/claude-code
+- **Authentication** — any mode Claude Code supports: `claude login`, `ANTHROPIC_API_KEY`,
+  AWS Bedrock (`CLAUDE_CODE_USE_BEDROCK=1` + AWS profile/credentials), Google Vertex
+  (`CLAUDE_CODE_USE_VERTEX=1`), or a gateway `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL`
+
+Run `aidlc doctor` to verify all of the above.
+
+## Five-minute walkthrough
+
+```sh
+# 1. New workspace from scratch
+mkdir my-pipeline && cd my-pipeline
+aidlc init
+aidlc doctor                                 # confirm claude is wired up
+
+# 2. Drop in a built-in preset (or build manually with skill/agent/pipeline add)
+aidlc preset apply code-review
+aidlc list                                   # see the agents, skills, pipeline you got
+
+# 3. Kick off a run and let Claude do the work
+aidlc run start review-pipeline --context diff=$(git diff HEAD~1)
+aidlc run exec <runId>                       # streams claude output, advances on success
+```
+
+## Command reference
+
+Global flags available on every subcommand:
+
+| Flag | Default | Purpose |
+|---|---|---|
+| `-w, --workspace <path>` | `cwd` | Workspace root (containing `.aidlc/`). Also reads `AIDLC_WORKSPACE` env. |
+| `-q, --quiet` | off | Suppress decorative progress output (errors and `--json` still print). |
+
+### `guide` — getting-started reference
+
+```
+aidlc guide
+```
+
+Prints a static, no-LLM getting-started card (prerequisites → bootstrap →
+build config → run → watch). Works before any workspace or `claude` exists.
+
+### `ask` — ask Claude about AIDLC
+
+```
+aidlc ask "how do I start a run?"
+aidlc ask how do I set up the code-review preset
+```
+
+Asks the local `claude` CLI a question about AIDLC — what it is, how to set it
+up, and which command does what — grounded in a built-in reference so answers
+stay accurate. Needs `claude` on PATH (run `aidlc doctor` to verify); works even
+before a workspace is initialized.
+
+### `init` — bootstrap a workspace
+
+```
+aidlc init [--name "Workspace Name"]
+```
+
+Creates `.aidlc/workspace.yaml` (commented starter), `.aidlc/skills/`, `.aidlc/runs/`.
+Idempotent — skips anything that already exists.
+
+### `doctor` — health check
+
+```
+aidlc doctor [--json]
+```
+
+Verifies `workspace.yaml` parses + Zod-validates, `claude` binary is on PATH,
+authentication works, all skill paths exist, custom runner files exist, and
+run-state JSON files are parseable. Exit 1 on any failure (including skill /
+runner / runtime checks). `--json` emits every section as
+`{ ok, failures, sections }` — a parseable CI preflight.
+
+### `mcp` — give another CLI the ast-graph server
+
+```
+aidlc mcp status
+aidlc mcp register [--runner codex] [--dry-run]
+```
+
+The VS Code extension registers the `ast-graph` MCP server with Claude
+automatically, project-scoped. Codex keeps MCP servers in `~/.codex/config.toml`,
+which is per-user: registering there points every Codex session on the machine
+at this workspace's graph, so it stays an explicit command. `register` copies
+the binary and db path out of the registration Claude already has — run
+**AIDLC Native: Rescan AST Graph** in VS Code once first.
+
+### `validate` — schema + cross-reference check
+
+```
+aidlc validate [--strict] [--json]
+```
+
+Stricter than the `doctor` workspace section: enumerates every Zod issue with
+its `path[]` for editor jump-to-line. Also reports dangling cross-references
+(a pipeline step naming an undefined agent, an agent listing a missing skill, a
+recipe pointing at an unknown pipeline/step) as warnings. Pass `--strict` to
+exit non-zero on those too — handy as a CI gate. `--json` emits the structured
+result (`{ ok, configPath, counts, refIssues }`).
+
+### `list` — print workspace contents
+
+```
+aidlc list [--json]
+```
+
+Pretty table by default, structured JSON for piping into `jq`.
+
+---
+
+### Skills
+
+```
+aidlc skill add --id <id> --template <name>            # bundled template (5 available)
+aidlc skill add --id <id> --path .aidlc/skills/my.md   # reference your own .md
+aidlc skill list [--json] [--templates]                # `--templates` lists the 5 built-ins
+aidlc skill show <id>                                  # prints the rendered .md content
+aidlc skill remove <id>                                # removes from yaml (does NOT delete .md)
+```
+
+Built-in templates: `hello-world`, `code-reviewer`, `test-converter`,
+`doc-writer`, `release-notes`. Run `aidlc skill list --templates` for a one-line
+description of each.
+
+### Agents
+
+```
+aidlc agent add --id <id> --name <n> --skill <skillId>
+                [--model claude-sonnet-4-5]
+                [--capabilities files,github,jira]
+                [--description "…"]
+                [--runner default|codex|custom] [--runner-path .aidlc/runners/foo.js]
+aidlc agent list [--json]
+aidlc agent show <id>
+aidlc agent remove <id>
+aidlc agent run <id> [--message "…"] [--context k=v,…] [--dry-run]
+```
+
+`agent run` is one-shot — spawns `claude` with the agent's skill + your
+message, streams to stdout, no run state created. Useful for quick checks and
+piping into shell scripts.
+
+**Runners.** `default` shells out to `claude`; `codex` shells out to
+`codex exec`; `custom` loads your own `runner_path` module. AIDLC composes the
+same three layers — persona, project instructions, skills — into whichever
+prompt that harness needs, so the phase is the same work either way. What
+differs is what the harness supplies by itself: Claude Code reads `CLAUDE.md`
+and gets it once, Codex is handed `AGENTS.md` (or `CLAUDE.md` when the repo has
+no `AGENTS.md`) inline. `aidlc doctor` prints the resolved layers per agent.
+
+Two things do *not* carry across on their own — a tier alias and a price — and
+both are settled in one place, the optional `providers:` block:
+
+```yaml
+providers:
+  codex:
+    model_aliases:
+      sonnet: gpt-5-codex                              # tier → concrete model
+    rates:
+      "*": { input_per_mtok: 1.25, output_per_mtok: 10.0 }   # USD per 1M tokens
+```
+
+`model_aliases` translates a `model:` value for one runner. Without it, a Claude
+tier alias (`opus` / `sonnet` / `haiku`) resolves to no `--model` at all and the
+provider CLI applies its own default. AIDLC ships **no** built-in tier map: saying
+`sonnet` equals some other vendor's model is a claim about your work that only you
+can make, and a guessed model id fails the run outright.
+
+`rates` prices the tokens a CLI reports, for the providers that report tokens
+rather than dollars (Codex does; Claude Code reports a measured
+`total_cost_usd`, which always wins). AIDLC ships **no** built-in prices either —
+a stale rate produces a plausible total instead of failing loudly, and your real
+rate depends on your account. Without rates, a Codex step still sums as $0 and
+`aidlc doctor` names it.
+
+Either way the number is labelled: a total containing an estimate prints as
+`≥ ~$2.5000 (includes estimates from declared rates)`, and one missing a step
+entirely says `1 step reported no cost`.
+
+### Pipelines
+
+```
+aidlc pipeline add --id <id> --steps agent1,agent2,agent3
+                   [--human-review]                        # mark all steps as gated
+                   [--produces "p1.md:p2.md,p3.md"]        # colon between steps, comma between artifacts
+                   [--on-failure stop|continue]
+aidlc pipeline list [--json]
+aidlc pipeline show <id>                                   # numbered step graph
+aidlc pipeline remove <id>
+aidlc pipeline recipes                                     # list task-type recipes (bugfix, refactor, …)
+aidlc pipeline classify "<brief>"                          # which recipe fits this task
+aidlc pipeline generate                                    # assemble a pipeline from a recipe
+aidlc recipe init                                          # back-fill built-in recipes into older workspaces
+```
+
+### Presets
+
+```
+aidlc preset list [--json]                # shows built-ins and saved snapshots
+aidlc preset apply <name>                 # merges into current workspace (no overwrite)
+aidlc preset save <name>                  # snapshot current workspace to .aidlc/presets/<name>.json
+```
+
+Built-in presets: `code-review`, `release-notes`, `sdlc` (full 9-phase SDLC
+pipeline ported from the legacy AIDLC).
+
+### Epics
+
+Mirrors the extension's "Epic Pipeline" panel — reads each epic's `state.json`
+under whatever `state.root` your `workspace.yaml` declares (default
+`docs/epics/`).
+
+```
+aidlc epic list [--status pending|in_progress|done|failed] [--json]
+aidlc epic status <id> [--json]                 # phase-by-phase view
+aidlc epic show <id>                            # alias for status
+aidlc epic start <id> --brief "…" [--llm]       # classify the brief → recipe → assembled pipeline
+aidlc epic start <id> --recipe <recipeId>       # or pick the recipe yourself
+aidlc epic start <id> --pipeline <pipelineId>   # or use an existing pipeline as-is
+```
+
+`epic start` mirrors the extension's smart **Start Epic**: `--brief` classifies
+the requirement into a task-type recipe (heuristic by default, `--llm` for
+model-backed classification) and assembles a right-sized pipeline.
+
+In v2 an **epic** is a domain entity persisted on disk (one folder per epic
+with a `state.json`); it's distinct from a pipeline **run**. An epic can exist
+without a run, and a run can exist without an epic — `epic` reads the former,
+`run` / `status` read the latter.
+
+---
+
+### `maintain` — stage 6, the AI-Native return path
+
+Every other stage is entered by a person already looking at the screen. This one
+is entered by an alert, so it has a door a webhook forwarder, a cron job or a
+shell script can open.
+
+```
+aidlc maintain --signal signal.json          # register the signal as an incident epic
+aidlc maintain --signal -                    # …or read it from stdin
+aidlc maintain follow-up <incidentEpic>      # open the work the diagnosis found
+```
+
+A **signal** is five fields, and the schema is the contract — not the transport.
+A human pasting JSON, a Sentry webhook and an OTel threshold rule all fill the
+same shape, so adding a source later is an adapter, never a schema change:
+
+```json
+{
+  "source": "sentry",
+  "observedAt": "2026-08-30T02:14:00Z",
+  "symptom": "Checkout returns 500 for saved cards",
+  "scope": "~40 users/hour, EU region only",
+  "evidence": "TypeError: cannot read property token of undefined"
+}
+```
+
+`maintain` scaffolds an epic named after the symptom (`INC-CHECKOUT-RETURNS-500`,
+readable on purpose — the id ends up in a branch name and every later reference)
+and writes the payload to `<epic>/signal.json`, where the `native-maintain` skill
+looks for it. Then `/maintain <epic>` in Claude produces `incident.md`.
+
+The split into two commands is not ceremony. Whether a signal deserves five
+stages is a judgment made against the code, and it belongs to the Operator agent
+that runs *between* the two calls — not to the flag that woke it up. When the
+diagnosis does call for work, `follow-up` scaffolds the next epic with its
+`intent.md` already written, reading the signal back from the incident epic:
+
+```
+aidlc maintain follow-up INC-CHECKOUT-RETURNS-500 \
+  --problem "Customers with a saved card cannot complete a purchase." \
+  --who-hurts "Returning EU shoppers paying with a stored card." \
+  --done "A saved-card checkout succeeds under the failing condition." \
+  --question "Did this start with the 2026-08-29 deploy?"
+```
+
+Anything you leave out is written into the artifact as an explicit open question
+rather than filled with a plausible sentence — a gap a human can see gets
+answered, a fabricated line gets believed. The new epic starts at **stage 1
+behind its human gate**: an intent written by an agent at 3am from a single alert
+is exactly the kind of document that deserves a person's eyes. Pass
+`--intent <file>` to supply the markdown yourself, `--json` for machine callers.
+
+Requires the recipes the AI-Native preset ships (`aidlc preset apply ai-native`).
+
+---
+
+### `analyze` — import requirements
+
+Analyzes a requirements source and scaffolds a task breakdown folder
+(`docs/task-breakdowns/REQ-NNN/`). Supports Jira, GitHub Issues, Linear,
+Redmine, or a local file/URL. Runs interactively when options are omitted;
+fully non-interactive with `--source`/`--platform`/`--parent`. Works without a
+`workspace.yaml`.
+
+```
+aidlc analyze                                              # interactive wizard
+aidlc analyze --platform jira --parent PROJ-100 -y        # Jira epic, skip confirm
+aidlc analyze --source ./requirements.csv --platform redmine --brief
+```
+
+Options:
+
+| Flag | Description |
+|------|-------------|
+| `--source <path-or-url>` | Requirements file path or URL |
+| `--text <text>` | Inline requirements text |
+| `--platform <jira\|github\|linear\|redmine\|local>` | Source platform |
+| `--parent <ref>` | Parent epic/issue ref (Jira epic key, GitHub `owner/repo`, etc.) |
+| `--brief` | Brief task list (titles + 1-line desc, skip ACs/points) |
+| `--instruction <text>` | Custom guidance for task creation |
+| `--id <runId>` | Use this run ID instead of auto-generated REQ-NNN |
+| `-y, --yes` | Skip confirmation prompt |
+
+Outputs a `docs/task-breakdowns/REQ-NNN/` folder with the scaffolded breakdown.
+
+---
+
+### `run` — pipeline lifecycle
+
+These wrap `@aidlc/core`'s `PipelineRunner` and write atomically through
+`RunStateStore`. The VS Code sidebar updates within ~200ms.
+
+```
+aidlc run start <pipelineId> [--id <runId>] [--context k=v ...] [--context-file <path>]
+aidlc run mark-done <runId>             # validates produces paths, advances or awaits review
+aidlc run approve   <runId> [--comment "…"]
+aidlc run reject    <runId> --reason "…"
+aidlc run rerun     <runId> [--feedback "…"]
+aidlc run request-update <runId> <step> [--feedback "…"]  # reopen an already-approved step for changes
+aidlc run delete    <runId> [--force]
+aidlc run open      <runId> [--path]    # prints state.json content (or just file path)
+aidlc run exec      <runId> [--until <step>] [--auto-approve] [--require-complete] [--json] [--dry-run]
+aidlc run verify    <runId> [--json]    # re-checks recorded artifacts still exist + pass produces_contains
+aidlc run report    <runId> [--format md|json] [--output <file>]  # shareable run history (Markdown/JSON)
+```
+
+**Exit codes for `run exec`** (so CI can branch): `0` completed (or stopped at
+`--until`, or `--dry-run`), `2` paused on a gate (awaiting review / rejected /
+budget), `1` error. `--require-complete` maps any non-completed outcome to `1`.
+`--json` prints a final summary object to stdout (claude's stream goes to stderr).
+See [AUTOMATION.md](AUTOMATION.md) for the full headless guide +
+a GitHub Action recipe.
+
+**`run verify`** is a read-only post-run drift check: a `completed` run still
+claims its artifacts exist, but someone may have since deleted or gutted one.
+It re-validates every step's recorded `artifactsProduced` (existence + the same
+`produces_contains` markers the gate applied) and exits non-zero when any step
+has drifted — handy as a CI post-check.
+
+**`run report`** renders the run history (steps, revisions, durations, reject
+reasons, approve comments, cost when reported) as Markdown to paste into a PR
+description or status update. `--format json` dumps the raw state instead.
+
+**`run exec`** is the unique unlock: it spawns `claude` for the current step,
+streams stdout to your terminal, validates the produced artifacts, and advances
+to the next step automatically. Steps declaring `auto_review: true` have their
+`auto_review_runner` validator executed headlessly between produce-validation
+and approval — a `pass` advances the step, a `reject` stops with a rerun hint.
+With `--auto-approve` it also clears `human_review` gates without pausing — a
+single command then drives the entire pipeline end-to-end.
+
+**`run request-update`** reopens an already-approved step (bumps its revision,
+resets downstream steps), mirroring the extension's "Request update" action.
+
+`run start` defaults `runId` to `<pipelineId>-<timestamp>` if `--id` is omitted.
+
+#### Cost guard (`budget`)
+
+Because `run exec --auto-approve` can drive a whole pipeline unattended (and a
+self-fixing agent loop can quietly escalate spend), a pipeline may declare an
+optional cost ceiling. After each step the autopilot sums the per-step LLM cost
+and stops once a ceiling is crossed. Manual `mark-done` is never gated.
+
+A step's cost is one of three things, and the guard treats them differently:
+
+| | Where it comes from | Counts toward the ceiling |
+|---|---|---|
+| **measured** | the CLI reported dollars (`claude`) | yes |
+| **estimated** | tokens × your `providers.<runner>.rates` | yes, and it says so |
+| **blind** | the CLI reported neither | no — it sums as $0 |
+
+An estimate is counted because the alternative is a provider with no ceiling at
+all. It is never presented as measured: the running line reads
+`budget: ≥ $2.5000 / $5.00 ($2.2500 estimated; 1 step reported no cost)`.
+
+```yaml
+pipelines:
+  - id: my-pipeline
+    budget:
+      max_usd: 5.00           # hard ceiling on cumulative cost for the run
+      max_usd_per_step: 1.50  # optional — a single pricey step trips it too
+      on_exceed: pause        # pause (default) → stop the loop; fail → exit non-zero
+    steps: [...]
+```
+
+On `pause` the loop stops and you can raise the budget or resume; on `fail` it
+exits non-zero (handy in CI).
+
+### `step` — direct step control
+
+The `run` commands operate on the current step. `step` operates on **any**
+step regardless of pipeline order, for when reality doesn't match the
+pipeline (work done outside the tool, phases that don't apply this time,
+hopping back to redo something).
+
+```
+aidlc step start  <runId> <step>          # → awaiting_work, moves pointer (demotes the old current step to pending)
+aidlc step done   <runId> <step> [--reason "…"]   # → approved (no produces validation)
+aidlc step skip   <runId> <step>          # → approved with skip note
+aidlc step reset  <runId> <step>          # → pending (no cascade)
+aidlc step set    <runId> <step> <status> # raw — any of: pending | awaiting_work | awaiting_review | approved | rejected
+aidlc step jump   <runId> <step>          # moves pointer + auto-approves earlier pending steps
+```
+
+`<step>` accepts a 0-based index (`0`, `1`, `2`) or an agent id (`reviewer`,
+`planner`) — whichever is easier in context.
+
+`step done` and `step skip` only advance the pointer when the step they touch
+is the **current** step; touching an earlier step won't drag the pointer
+backward.
+
+### `status` — list runs / inspect one
+
+```
+aidlc status                              # all runs in .aidlc/runs/
+aidlc status <runId>                      # detailed view of one run
+aidlc status [runId] --json               # raw RunState JSON
+```
+
+### `watch` — live re-render of run state
+
+Uses `chokidar` on `.aidlc/runs/*.json` with a 150ms debounce. Clears the
+visible terminal area on every redraw (preserves scrollback so you can scroll
+up to past frames).
+
+```
+aidlc watch                               # multi-run table, all runs
+aidlc watch <runId>                       # single-run focus mode (step pipeline)
+```
+
+### `tail` — stream state transitions
+
+Same chokidar watch as `watch`, but emits one timestamped line per detected
+change instead of redrawing a table. Useful for CI logs or piping.
+
+```
+aidlc tail                                # all runs
+aidlc tail <runId>                        # one run
+aidlc tail [runId] --json                 # one NDJSON event per transition (pipe into jq / a notifier)
+```
+
+`--json` events: `seed`, `run_new`, `run_status`, `pointer`, `step_status`,
+`step_revision`, `run_gone` — each with `ts` and `runId`.
+
+Output shape:
+
+```
+[16:42:01] ABC-123 step 0 awaiting_work → approved
+[16:42:01] ABC-123 pointer 0 → 1
+[16:42:01] ABC-123 step 1 pending → awaiting_work
+```
+
+### `dashboard` — browser UI with action buttons
+
+Single-process HTTP server, no build step. Same data as `watch`; adds
+click-to-approve / reject / rerun buttons. Updates push via SSE so the page
+refreshes within ~100ms when files change.
+
+```
+aidlc dashboard                           # http://127.0.0.1:8787
+aidlc dashboard --port 3000
+aidlc dashboard --host 0.0.0.0            # expose on LAN (use with care)
+```
+
+Endpoints (handy for scripts): `GET /api/runs`, `GET /api/runs/:id`,
+`POST /api/action`, `GET /events` (SSE).
+
+### `monitor` — agent observability via agents-observe
+
+Checks the [agents-observe](https://github.com/simple10/agents-observe) plugin
+install, pins a stable data dir in `~/.claude/settings.json` (so the DB survives
+plugin upgrades), and prints live server status.
+
+```
+aidlc monitor                             # status check + pin data dir
+aidlc monitor --start                     # also launch the server if it's down
+aidlc monitor --open                      # open the dashboard in your browser
+aidlc monitor --json                      # machine-readable status (no writes)
+aidlc monitor --dry-run                   # show the settings.json change, don't write
+```
+
+When the plugin isn't installed, `--start` offers to **auto-install** it (with
+confirmation) instead of only printing manual steps; `monitor` also
+distinguishes a plugin that is installed-but-failed-to-load from a healthy one.
+`--start` uses Docker when available, otherwise falls back to the plugin's
+**local** runtime (no Docker required) — in local mode the terminal becomes the
+server's log window, and `npm install` is pinned to the public npm registry so
+it never inherits a private registry default. The extension's **Start Monitor**
+button runs `aidlc monitor --start`.
+
+### `globals` — built-in workflow agents + skills under `~/.claude/`
+
+Built-in workflows (e.g. the SDLC pipeline) ship agent + skill markdown that
+gets installed under `~/.claude/agents` and `~/.claude/skills` so their skill
+paths resolve. `preset apply sdlc` installs them implicitly; this command group
+manages them explicitly — including `uninstall`, which the extension exposes but
+the CLI previously couldn't do.
+
+```
+aidlc globals status [--json]      # which built-in workflows are installed globally
+aidlc globals install [ids...]     # install (default: the standard workflows)
+aidlc globals uninstall [ids...]   # remove AIDLC-marked global files (run before removing the extension)
+```
+
+`aidlc globals install` also lays down the **artifact annotation tooling** — the
+zero-dependency Markdown→HTML renderer, a vendored [annotron](https://www.npmjs.com/package/annotron)
+(no global install), the per-epic memory tool, and the `/annotate-artifact` +
+`/epic-context` skills — under `~/.claude`. That makes the browser annotation loop
+and epic memory work from a plain terminal + Claude Code, no VS Code required. It
+never edits your `settings.json` (add `Edit(docs/epics/**)` yourself if you want the
+loop to run without per-write confirmation).
+
+`uninstall` only removes files AIDLC wrote (marker-guarded) and preserves files
+still needed by other globally-installed workflows.
+
+## Recipes
+
+### Drive a complete SDLC pipeline end-to-end
+
+```sh
+aidlc preset apply sdlc
+aidlc run start sdlc-pipeline --id ABC-123 --context epic=ABC-123
+aidlc run exec ABC-123 --auto-approve     # claude works through every phase
+```
+
+### Manually mark a phase done that you completed outside AIDLC
+
+```sh
+aidlc step done <runId> implement --reason "merged via PR #42"
+aidlc run exec <runId>                    # resumes from the next step
+```
+
+### Restart a single phase without cascading
+
+```sh
+aidlc step reset <runId> review
+aidlc step start <runId> review            # → awaiting_work
+aidlc run exec <runId>
+```
+
+### One-shot ask, no run state
+
+```sh
+aidlc agent run reviewer --message "Review the diff in /tmp/patch.diff"
+```
+
+### Pipe runs into another tool
+
+```sh
+aidlc list --json | jq '.pipelines[].id'
+aidlc status <runId> --json | jq '.steps[] | select(.status=="rejected")'
+aidlc epic list --json | jq '.[] | select(.status=="in_progress") | .id'
+```
+
+### Live monitor while a long pipeline runs
+
+```sh
+# Terminal 1 — kick off the run, then walk away
+aidlc run start sdlc-pipeline --id ABC-123 --context epic=ABC-123
+aidlc run exec ABC-123 --auto-approve
+
+# Terminal 2 — live table
+aidlc watch
+
+# Terminal 3 — transition log for grep / save
+aidlc tail | tee run-log.txt
+```
+
+### Open the browser dashboard
+
+```sh
+aidlc dashboard
+# then open http://127.0.0.1:8787
+# click any run → approve / reject / rerun directly from the page
+```
+
+## Filesystem layout
+
+The CLI never holds in-memory state — everything lives in your workspace:
+
+```
+my-project/
+├── .aidlc/
+│   ├── workspace.yaml          # agents, skills, pipelines (Zod validated)
+│   ├── skills/                 # custom skill .md files
+│   │   └── code-reviewer.md
+│   ├── runs/                   # one JSON per run
+│   │   └── ABC-123.json        # full RunState (steps, status, context)
+│   └── presets/                # saved workspace snapshots
+│       └── my-preset.json
+└── docs/                       # produces paths from your pipelines land here
+    └── …
+```
+
+Runs and presets are local-only — gitignore `.aidlc/runs/` and
+`.aidlc/presets/` if you want, the rest is meant to be committed.
+
+## Troubleshooting
+
+| Problem | Likely fix |
+|---|---|
+| `aidlc doctor` says "Not authenticated" | Use any Claude Code auth mode: `claude login`, `ANTHROPIC_API_KEY`, AWS Bedrock (`CLAUDE_CODE_USE_BEDROCK=1` + AWS profile/creds), Vertex (`CLAUDE_CODE_USE_VERTEX=1`), or `ANTHROPIC_AUTH_TOKEN`. doctor now detects all of these. |
+| `aidlc run exec` fails with "missing artifacts" | The agent didn't produce the files declared in `pipeline.steps[].produces`. Check the paths or fix the agent's skill. |
+| `aidlc run start` rejects the runId | RunIds must match `^[A-Za-z0-9][A-Za-z0-9._-]*$`. No spaces, no leading dashes. |
+| Pipeline step appears as a string in YAML, but I edited it as an object | Both forms are valid. The CLI writes string form when there's no metadata, object form when there's `human_review` or `produces`. |
+| A phase on `runner: codex` answers without the graph | Its MCP server is per-user and separate from Claude's. Run `aidlc mcp register --runner codex`, then `aidlc mcp status` to confirm. |
+| Custom runner not loading | `runner_path` must be `.js` / `.cjs` / `.mjs` (no TypeScript yet). Run `aidlc doctor` to check the file resolves. |
+
+## Credit
+
+Built on [`aidlc-io/aidlc`](https://github.com/aidlc-io/aidlc) by
+[hueanmy](https://github.com/hueanmy). If it saves you time,
+[sponsor the original author](https://github.com/sponsors/hueanmy) ❤️.
+
+## License
+
+MIT — the original copyright line is kept; this fork's changes are added under
+the same terms.