From 4d9412cbe4ef3a7b3852d842f0e4f1e82b74c718 Mon Sep 17 00:00:00 2001 From: "aidd-bot[bot]" <290648294+aidd-bot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 04:50:19 +0000 Subject: [PATCH 01/44] chore: release main (#405) Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com> --- plugins/aidd-ui/CHANGELOG.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/plugins/aidd-ui/CHANGELOG.md b/plugins/aidd-ui/CHANGELOG.md index 4c711514..d3745adb 100644 --- a/plugins/aidd-ui/CHANGELOG.md +++ b/plugins/aidd-ui/CHANGELOG.md @@ -8,6 +8,20 @@ * **framework:** read action files before running, across all skills ([#389](https://github.com/ai-driven-dev/framework/issues/389)) ([9d592a6](https://github.com/ai-driven-dev/framework/commit/9d592a6d8c1ca3d0ac8f8aaf54e30e7186a8eb48)) +### Miscellaneous + +* release main ([#392](https://github.com/ai-driven-dev/framework/issues/392)) ([484928c](https://github.com/ai-driven-dev/framework/commit/484928c8429999194cbe163782099b26c89e4105)) +* release main ([#393](https://github.com/ai-driven-dev/framework/issues/393)) ([426c604](https://github.com/ai-driven-dev/framework/commit/426c604dba9f5f1c586ade768e55c90f914a4562)) +* release main ([#404](https://github.com/ai-driven-dev/framework/issues/404)) ([5f6d84f](https://github.com/ai-driven-dev/framework/commit/5f6d84f3a7cad604c45ee7b4831c77f7cf281717)) + +## [0.1.0-alpha.0](https://github.com/ai-driven-dev/framework/compare/aidd-ui-v0.1.0-alpha.0...aidd-ui-v0.1.0-alpha.0) (2026-07-07) + + +### Features + +* **framework:** read action files before running, across all skills ([#389](https://github.com/ai-driven-dev/framework/issues/389)) ([9d592a6](https://github.com/ai-driven-dev/framework/commit/9d592a6d8c1ca3d0ac8f8aaf54e30e7186a8eb48)) + + ### Miscellaneous * release main ([#392](https://github.com/ai-driven-dev/framework/issues/392)) ([484928c](https://github.com/ai-driven-dev/framework/commit/484928c8429999194cbe163782099b26c89e4105)) From 943bbd2957f7e1c87c1497dd8c88b209e9960033 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Mon, 6 Jul 2026 07:14:02 +0200 Subject: [PATCH 02/44] ci(framework): stop release-please re-tagging aidd-ui (#394) Remove the aidd-ui package from release-please-config.json. Its release-as: 0.1.0-alpha.0 pin forced the same version on every run, so any change touching aidd-ui made release-please retry the existing aidd-ui-v0.1.0-alpha.0 tag and fail (Validation Failed: already_exists). Dropping it from the config freezes aidd-ui at its current alpha while it is still a scaffold; re-add it with proper prerelease handling when it is ready to version. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 --- release-please-config.json | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/release-please-config.json b/release-please-config.json index 1d887fb4..256c699f 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -82,17 +82,6 @@ "jsonpath": "$.version" } ] - }, - "plugins/aidd-ui": { - "package-name": "aidd-ui", - "release-as": "0.1.0-alpha.0", - "extra-files": [ - { - "type": "json", - "path": ".claude-plugin/plugin.json", - "jsonpath": "$.version" - } - ] } } } From 42a31205b5c76d852fb103fe8d102982d7706e56 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Mon, 6 Jul 2026 07:16:23 +0200 Subject: [PATCH 03/44] ci(framework): drop the aidd-ui release-as pin, keep it consistent Restore the aidd-ui package block in release-please-config.json so it matches the other seven plugins (package-name + extra-files), but without the release-as: 0.1.0-alpha.0 pin. The pin forced the same version every run, retrying the existing aidd-ui-v0.1.0-alpha.0 tag and failing (already_exists). Supersedes the block removal in #394: aidd-ui stays release-managed like its siblings; the next change bumps it to a fresh version instead of colliding. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt --- release-please-config.json | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/release-please-config.json b/release-please-config.json index 256c699f..85d6d3ac 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -82,6 +82,16 @@ "jsonpath": "$.version" } ] + }, + "plugins/aidd-ui": { + "package-name": "aidd-ui", + "extra-files": [ + { + "type": "json", + "path": ".claude-plugin/plugin.json", + "jsonpath": "$.version" + } + ] } } } From 34a7ae5f82bb3f24cb8774172b5a24c4740e6472 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 8 Jul 2026 05:32:41 +0200 Subject: [PATCH 04/44] feat(aidd-context): rework onboard into a noob-first guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reshape the onboard report from a status dashboard into a noob-first guide: one plain state sentence, one recommended action with its key, the rest on demand behind [?]. Emoji-anchored state kept, glyphs cut to ✅/⚠️/❌, tiers phrased as plain clauses, labels made explicit (tech stack, project knowledge saved, knowledge loaded by the AI). Restore three behaviors the earlier linter rebuild dropped: - session ledger (kills the re-nag for off-disk completions) - plan-status hedge driving the build-to-ship pin - capability map documented as the fixed catalogue (light tradeoff) Fix the dev-flow pin to read only the current branch's PR, never a repo-wide open PR or review queue. Rework the idle menu into three plain umbrellas (start new work / improve the project / customize the AI) plus explore. Add a recap reply, a return-to-onboard affordance on GUIDED handoff, and a framing line so the interactive nature is announced. Conform to the skill-authoring contract (R1-R13). Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- .../aidd-context/skills/00-onboard/SKILL.md | 12 +++--- .../skills/00-onboard/actions/01-scan.md | 12 ++++-- .../skills/00-onboard/actions/02-report.md | 17 ++++---- .../skills/00-onboard/actions/03-run.md | 8 ++-- .../skills/00-onboard/assets/report.md | 42 ++++++++----------- .../skills/00-onboard/references/checks.md | 36 ++++++++++++---- .../skills/00-onboard/references/run-tiers.md | 19 +++++++-- 8 files changed, 88 insertions(+), 60 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index f19f7334..9ed6b3be 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -51,7 +51,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [README.md](skills/00-onboard/README.md) | - | | `references` | [checks.md](skills/00-onboard/references/checks.md) | - | | `references` | [run-tiers.md](skills/00-onboard/references/run-tiers.md) | - | -| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Scan an AIDD project into a diagnostic of what is set up and missing, then run the recommended next commands in order. Use when the user asks where to start, what to do next, how the project stands, or to onboard onto AIDD. Not for listing every installed surface.` | +| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface.` | #### `skills/01-bootstrap` diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 59ab1e93..a13de7aa 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,20 +1,20 @@ --- name: 00-onboard -description: Scan an AIDD project into a diagnostic of what is set up and missing, then run the recommended next commands in order. Use when the user asks where to start, what to do next, how the project stands, or to onboard onto AIDD. Not for listing every installed surface. +description: Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface. argument-hint: scan | report | run --- # Onboard -Scans the current project against the AIDD framework, reports what is present, drifting, or missing as an explicit checklist, hands back a single ordered list of the commands to run next, and runs them on request. +Scans the current project against the AIDD framework, tells the user in plain words where it stands, points to the single clearest next action, and runs it on request. ## Actions | # | Action | Role | Input | | --- | -------- | ---------------------------------------------------------------------------------------- | ---------------- | | 01 | `scan` | Read the project once, silently, into a snapshot: every check in `checks.md`, status per zone | project root | -| 02 | `report` | Render the loud diagnostic plus one ordered command list, foundations then dev flow | the 01 snapshot | -| 03 | `run` | Run the user's pick per its tier, `OK` walks the whole list pausing at each GUIDED step, then re-scan | the user's reply | +| 02 | `report` | Lead with one plain state sentence and one recommended action a first-timer can act on, dashboard demoted | the 01 snapshot | +| 03 | `run` | Run the user's pick per its tier, `OK` walks the pending steps pausing at each interactive one, then re-scan | the user's reply | Run `01 → 02 → 03`, then loop back to `01` after each run until the user stops. Run each action's `## Test` before the next. Before running an action, read its file in `actions/`, not only the table or assets. @@ -29,13 +29,11 @@ Run `01 → 02 → 03`, then loop back to `01` after each run until the user sto ## Transversal rules -- Report, do not lecture. State status as glyphs, never a raw label or snapshot. A plain-language explanation of a step appears only when the user asks for it. +- Guide, do not lecture or dump. Lead with where the project stands and the single clearest next action, and keep the rest on demand. The render shape is `assets/report.md`. - Name real commands only. Never name a command whose skill `01` did not find installed; name a missing one as a gap by function. - Never run a GUIDED step unattended, and never test a plugin version against a registry. - Re-scan after a run, never trust a stale status. Wait for an explicit reply before running anything. -Detail lives in the references: the check catalogue and ranking in `checks.md`, the run tiers and `OK` walk in `run-tiers.md`, the render shape and glyphs in `assets/report.md`. - ## External data - `../02-project-memory/references/memory-block.md`: the canonical `` block shape the form-drift check compares against. diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index afea78a6..c95d49e6 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -8,22 +8,26 @@ The project root, the current working directory. ## Output -A silent snapshot, never printed: the status (`✓ ⚠ ✗` or not-applicable) of every check in `@../references/checks.md`, the installed AIDD plugins and skills each with its description, and the project name and purpose from the brief when memory is synced. +A silent snapshot, never printed: the status (`✓ ⚠ ✗`) of every check in `@../references/checks.md`, the installed AIDD plugins and skills each with its description, and the project name and purpose from the brief when memory is synced. ## Process 1. **Check.** Evaluate every check in `@../references/checks.md` by its own met and drift rules: a met fact (disk, or a cheap VCS read where the row says so) sets `✓`, a missing artifact sets `✗`, and only the row's stated drift case sets `⚠`. Scope each check to the paths the row names, never an installed-plugin tree. -2. **Drift.** For the context block, compare the AI context file's `` block against the canonical shape. +2. **Ledger.** Apply the Done rule in `@../references/checks.md`: a step the session ledger recorded run or left this session counts done, so it drops out even when disk cannot prove it. +3. **Hedge.** Read the plan's `status:` frontmatter to pin the build-to-ship stage per the zone-3 hedge in `@../references/checks.md`. +4. **Drift.** For the context block, compare the AI context file's `` block against the canonical shape. ```md @../../02-project-memory/references/memory-block.md ``` -3. **List.** Gather the enabled AIDD plugins and skills, each with its description, via the tool's native discovery. This is what `02` resolves each command against. -4. **Hold.** Keep the snapshot in context, read this fully only once a session, and hand to `02-report`. Print nothing. +5. **List.** Gather the enabled AIDD plugins and skills, each with its description, via the tool's native discovery. This is what `02` resolves each command against. +6. **Hold.** Keep the snapshot in context and hand to `02-report`. Print nothing. Refresh the disk and VCS facts only on change, not every loop. Re-read the session ledger on every scan, so a step recorded since the last scan drops out. ## Test - Zero user-visible output: no snapshot, no checklist, no status appears. - The snapshot carries a status for every check in `checks.md` and the installed skills with descriptions. +- A step the session ledger recorded run or left is absent from the snapshot's actionable set. +- Plan `status: in-progress` pins Build alone; `implemented` or an open PR pins Review then Ship. - No report or command is emitted by this action. diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-report.md b/plugins/aidd-context/skills/00-onboard/actions/02-report.md index 943cafe4..b488ae86 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-report.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-report.md @@ -1,6 +1,6 @@ # 02 - Report -Show the loud diagnostic and one ordered command list. Concrete, scannable, no lecture. +Lead with one plain state sentence and one recommended action a first-timer can act on, everything else demoted. ## Input @@ -10,17 +10,18 @@ The snapshot from `01-scan` (statuses + installed skills), held in context, not 1. **Resolve.** For each check, resolve its canonical command in `@../references/checks.md` against the installed skills from `01`. A match keeps the command. No match names a gap by function, never an invented command. 2. **Order.** Rank the recommended list per the `## Ranking` policy in `@../references/checks.md`. -3. **Tag.** Give each recommended line its tier badge from `@../references/checks.md`: `⚡ auto`, `💬 guided`, or `🖐 manual`. -4. **Render.** Fill `@../assets/report.md`, following its glyph vocabularies, collapse, and footer rules. +3. **Tag.** Phrase each step's tier as the natural-language clause `@../assets/report.md` maps to the row's tier in `@../references/checks.md`, never a glyph badge. +4. **Render.** Fill `@../assets/report.md`, following its state, dashboard, next, key, and idle-menu rules. 5. **Wait.** Offer the report and wait for a reply. Never auto-advance. Hand the reply to `03-run`. ## Output -The rendered report per `@../assets/report.md`: emoji section headers, a foundations checklist, an optional context-artifacts row, a dev-flow track, one ordered `Do this next` list of command plus tier badge plus plain purpose, and a one-line footer. No internal names or raw statuses beyond the glyphs. +The rendered report per `@../assets/report.md`: a framing line on the first report of the session, a `🔍` state sentence, the `🏗️ Foundations` and `🚦 Progress` dashboard rows, and a `👉 Next` recommendation naming the top step in plain words with its `[1]` key plus a compact options line. Command ids and tier clauses live only in the `[?]` detail, never in this default view. ## Test -- Foundations render above dev flow; every recommended line carries a concrete installed command, a tier badge, and a plain purpose, or is a gap named by function. -- Context artifacts stay info only, collapsed to "none yet" when all absent, never in `Do this next`. -- Nothing uninstalled is named as a command. -- The footer is present, one line, and states what `OK` does in this state. +- The first report of the session opens with the framing line; a re-scan later in the same session drops it. +- The state sentence reads the project's standing in plain words; Progress marks the current stage in `[brackets]`, never `📍/◦/➖`. +- `Next` names the single top-ranked step with key `[1]`; the compact options line uses bracketed keys (`[2]`, `[OK]`, `[?]`); no command id or tier clause appears in the default view. +- When nothing is pending, `Next` is the idle menu (`start new work [1]`, then `improve the project [2] · customize the AI [3] · explore [?]`); umbrella slots re-render a member sub-list on pick, and no `[OK]` is offered. +- Every offered step resolves to a concrete installed command or is a gap named by function. diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-run.md b/plugins/aidd-context/skills/00-onboard/actions/03-run.md index 6e34f3e3..98f86b65 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-run.md @@ -4,15 +4,16 @@ Carry out the user's reply per its tier, then loop back to scanning. ## Input -- The user's reply from `02-report`: `OK`, a step number, an explain request, or stop. +- The user's reply from `02-report`: a step number (`[1]`…), `OK`, `?`, an explain request, a recap request, or stop. - The resolved command per line, or a gap when no installed skill fits. - The snapshot from `01-scan`, held in context. ## Process -1. **Route.** Carry out the reply per `@../references/run-tiers.md`: `OK` walks the list, a number runs one step, explain and stop stay read-only. +1. **Route.** Carry out the reply per `@../references/run-tiers.md`: `OK` walks the pending steps, a number runs one step (or re-renders an idle-menu umbrella's member sub-list), `?` expands the full detail, and `?`, explain, recap, and stop stay read-only. 2. **Guard.** Run or name only skills `01` found installed. A gap never invokes a skill: offer explain or stop. Never run a MANUAL step, only show it. -3. **Loop.** After any step or the `OK` walk runs, re-scan (`→ 01`) and re-render so a resolved `✗` flips to `✓`. A read-only reply does not re-scan. +3. **Record.** Note each handled step in the session ledger per the Done rule in `@../references/checks.md`: a step run, a MANUAL step shown and left, or one the user skips. The next scan then drops it even when disk cannot prove it. +4. **Loop.** After any step or the `OK` walk runs, re-scan (`→ 01`) and re-render so a resolved `✗` flips to `✓`. A read-only reply does not re-scan. ## Output @@ -23,3 +24,4 @@ One outcome per `@../references/run-tiers.md`, always ending with the refreshed - `OK` walks the whole list, runs AUTO steps unattended, and pauses at each GUIDED step for input rather than running it unattended. - A MANUAL step is shown, never run; a gap invokes nothing. - After a step or the `OK` walk runs, the re-scan flips resolved statuses; a read-only reply does not re-scan. +- After a MANUAL step is shown and left, or a step is skipped, the re-scan does not re-recommend it. diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index e7a595c2..d136765b 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -1,34 +1,28 @@ - + -🔍 — AIDD checkup + -🏗️ Foundations - ... -🧩 Context artifacts (optional) - <✓/✗ per artifact, inline> +🔍 -🚦 Dev flow - +🏗️ Foundations +🚦 Progress -✨ Do this next - 1. - ... - - ↳ " · "explain project" (only when memory is filled) · stop> +👉 Next: [1] + diff --git a/plugins/aidd-context/skills/00-onboard/references/checks.md b/plugins/aidd-context/skills/00-onboard/references/checks.md index 34d5f304..7f79c030 100644 --- a/plugins/aidd-context/skills/00-onboard/references/checks.md +++ b/plugins/aidd-context/skills/00-onboard/references/checks.md @@ -4,6 +4,8 @@ Every check `01-scan` captures and `02-report` renders, in report order. Four zo Each row carries: the **met** rule (a disk fact = `✓`), the **drift** rule (`⚠`, missing or off-format), the **deliverable** named to the user, the canonical **command**, and the **tier** (see `run-tiers.md`). A command resolves to the installed skill by its id, or is named a gap by function when that skill is not installed. +This catalogue **is** the capability map. A newly installed plugin's capability enters `Do this next` only when a row is added here, a deliberate light tradeoff over dynamic discovery. + ## Ranking The order of the `Do this next` list, the single home for this policy: @@ -11,18 +13,32 @@ The order of the `Do this next` list, the single home for this policy: 1. Unmet zone-1 foundations, in table order. 2. The earliest unmet dev-flow step. 3. Any health tool whose signal fired. +4. When 1-3 are all clear (foundations met, no dev-flow step pending, no health signal), the **idle menu**: three plain umbrellas plus explore, never a flat list of cryptic generators. + +The idle menu is: + +| Slot | Umbrella | Opens (on pick, a sub-list of the installed members) | +| ---- | ------------------- | ------------------------------------------------------------------------------------- | +| 1 | start new work | `aidd-dev:00-sdlc` (or `aidd-pm:04-spec` when absent), a feature from idea to shipped | +| 2 | improve the project | `aidd-dev:04-audit`, `aidd-dev:06-test`, `aidd-dev:07-refactor` | +| 3 | customize the AI | the zone-2 generators for the **missing** artifacts (rule, skill, agent, command, hook), each named in plain words | +| ? | explore | `aidd-context:11-explore` and any capability not in slots 1-3 (learn, PM, and the rest) | -While any zone-1 foundation is unmet, hold the dev-flow and health steps back, so a bare repo lists only its setup steps. Zone-2 artifacts never enter this list; surface one only when the user picks it. +Slots 2 and 3 are umbrellas: picking one re-renders its member sub-list to pick from, picking a member runs it. Slot 1 runs directly. Only surface a member that `01` found installed; drop an umbrella with no installed member. + +While any zone-1 foundation is unmet, hold the dev-flow, health, and idle-menu steps back, so a bare repo lists only its setup steps. The idle menu opens only at rank 4, never alongside a pending dev-flow step: a project mid-work stays focused on its one next step, an idle project gets the open menu instead of a dead end. + +**Done rule (session ledger).** A step is done when a disk signal proves it OR the session ledger recorded it run or left this session. A done step never re-enters `Do this next`. This is the single home for the rule: `01` reads it, `03` writes it, no file. It kills the re-nag for off-disk completions a disk scan cannot see (a read-only review, a MANUAL step left for the user, an explicit skip). ## Zone 1: AIDD context (foundations) | Check | Met (`✓`) | Drift (`⚠`) | Deliverable | Command | Tier | | ------------- | ----------------------------------------------- | -------------------------------------------------------- | ---------------- | -------------------------- | ------ | -| architecture | `aidd_docs/INSTALL.md` exists | — | stack design | `aidd-context:01-bootstrap` | GUIDED | -| memory bank | `aidd_docs/memory/` exists with real content | files empty or placeholder | project memory | `aidd-context:02-project-memory` | GUIDED | -| context block | `` block present in the AI context file, on the canonical shape | block present but off the canonical shape, see external data (absent block or no context file is `✗`, not `⚠`) | memory wiring | `aidd-context:02-project-memory` | GUIDED | +| architecture | `aidd_docs/INSTALL.md` exists, or the repo is already established (source code or a synced memory bank present) | — | tech stack | `aidd-context:01-bootstrap` | GUIDED | +| memory bank | `aidd_docs/memory/` exists with real content | files empty or placeholder | project knowledge saved | `aidd-context:02-project-memory` | GUIDED | +| context block | `` block present in the AI context file, on the canonical shape | block present but off the canonical shape, see external data (absent block or no context file is `✗`, not `⚠`) | knowledge loaded by the AI | `aidd-context:02-project-memory` | GUIDED | -Architecture is only `❌` on a truly greenfield repo: no source code **and** no synced memory bank. An established project (code present, or the memory bank already synced) has moved past stack design, so the check is **not applicable** (`➖`), not a loud `❌`, and never recommends bootstrap. Keys on files on disk, not commit history. +Architecture is `❌` only on a truly greenfield repo: no source code **and** no synced memory bank, so the user is told to design a stack. An established project (code present, or the memory bank already synced) has its stack in place, so it is `✅`, never a loud `❌` and never a bootstrap recommendation. Keys on files on disk, not commit history. ## Zone 2: Context-gen artifacts (foundations, optional) @@ -36,7 +52,7 @@ Scoped to **project-level** artifacts only, under the tool's own config root (`. | hooks | a `hooks` entry in the tool's settings | hooks | `aidd-context:08-hook-generate` | GUIDED | | commands | a project command under `.claude/commands/` (or peer) | commands | `aidd-context:07-command-generate` | GUIDED | -These are optional and **info only**: show their status in the checklist, never a loud `✗`. Ranking (above) keeps them out of `Do this next` and the `OK` walk. +These are optional, never a loud `✗`. They surface only under the idle menu's `customize the AI` umbrella (rank 4, slot 3), each **missing** one a member named in plain words (`a coding rule the AI follows`, `a reusable workflow`, `a specialized assistant`, …); the ones already present are not offered. They are choices, not a chain: the `OK` walk covers ranks 1-3 only, the idle menu is pick-by-number. ## Zone 3: Dev flow @@ -49,11 +65,13 @@ The per-work sequence, in order. Each step resolves to an installed skill by fun | plan | a `plan.md` under `aidd_docs/` | `aidd-dev:01-plan` | GUIDED | | build | code present against the plan | `aidd-dev:02-implement` | GUIDED | | review | build looks done, nothing reviewed | `aidd-dev:05-review` | AUTO | -| ship | an open PR, or merged and unreleased | `aidd-vcs:02-pull-request` | MANUAL | +| ship | current branch has an open PR, or is merged and unreleased | `aidd-vcs:02-pull-request` | MANUAL | + +Stages are cumulative. A downstream artifact implies the upstream stages are met, so a project with a plan starts the flow at build, not clarify. -Stages are cumulative. A downstream artifact implies the upstream stages are met, so a project with a plan starts the flow at build, not clarify. Build never proves review or ship, so surface both when code looks done and let the user pick. +The plan's `status:` frontmatter hedges the build-to-ship pin, so review is never skipped nor premature: `in-progress` pins Build alone; `implemented` or an open PR pins Review then Ship, Review first; an unreadable or absent status pins Build then Review. -`clarify` and `track` have no direct disk signal; they are the place only when no downstream artifact exists, never a loud default. `review` and `ship` read cheap VCS state (an open PR), not a pure disk fact. +`clarify` and `track` have no direct disk signal; they are the place only when no downstream artifact exists, never a loud default. `review` and `ship` read cheap VCS state, current branch only: the PR/MR whose head is this branch, via the project's VCS tool. Ignore repo-wide open PRs and review queues — another branch's PR is another dev's work, never the pin. ## Zone 4: Health (tools, not steps) diff --git a/plugins/aidd-context/skills/00-onboard/references/run-tiers.md b/plugins/aidd-context/skills/00-onboard/references/run-tiers.md index a03e6905..4a3e8d8e 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run-tiers.md +++ b/plugins/aidd-context/skills/00-onboard/references/run-tiers.md @@ -1,17 +1,23 @@ # Run tiers -How `03-run` carries out the user's pick. Every step in `checks.md` carries one tier. Only ever run or name a skill that `01` found installed. +How `03-run` carries out the user's pick. Every step in `checks.md` carries one default tier (see the note below). Only ever run or name a skill that `01` found installed. ## The three tiers | Tier | What it is | How onboard runs it | | ------ | ------------------------------------------- | -------------------------------------------------------------------------- | | AUTO | Non-interactive, safe to spawn and walk away | Invoke the resolved skill, let it run to completion, then move on | -| GUIDED | Interactive, drives its own Q&A | Launch the resolved skill in this session, let the user drive it, resume when it returns | +| GUIDED | Interactive, drives its own Q&A | Launch the resolved skill in this session, let the user drive it, resume when it returns. State the return path on handoff (see Returning) | | MANUAL | Side-effecting or outward-facing | Show the exact command, do not run it, move on and leave it for the user | The run mechanism is per step, not one size. An AUTO step may invoke its skill directly or fan out to `aidd-dev:10-todo`; onboard follows the command the check names, never forces a single orchestrator. +**The tier is a default, not a fixed skill property.** Many skills run either way depending on how they are invoked (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`). Each step in `checks.md` carries the tier that fits its default use, and the report phrases it as a plain clause telling the user what happens if they just run it. The user can override per invocation: ask to run a GUIDED step unattended, or an AUTO step interactively, and onboard invokes the skill in that mode when the skill supports it. + +## Returning to onboard + +Handing off a GUIDED step launches another skill, which may not return control on its own. So on every handoff, tell the user one line: re-run onboard to come back and continue (the deterministic path is the slash command for this skill). The re-run re-scans, and the session ledger drops the step just handed off, so the user resumes where they left off rather than repeating it. + ## The `OK` walk When the user replies `OK` to the report, walk the ordered list top to bottom, one step at a time: @@ -23,16 +29,21 @@ When the user replies `OK` to the report, walk the ordered list top to bottom, o `OK` drives the whole list, not just a prefix. It pauses at each GUIDED step for the user's input and resumes after, so a greenfield project's setup chain runs end to end from one `OK`. State up front how many steps the walk covers and which need input. +The idle menu (checks.md rank 4) is the exception: it is a set of choices, not a chain, so `OK` never walks it. When the list is only the idle menu, there is nothing for `OK` to run; the user picks one item by number. + ## Other replies | Reply | What happens | | --------------- | --------------------------------------------------------------------------------------------- | -| a step number | Run that one step per its tier | +| a step number | Run that step per its tier. If the number is an idle-menu umbrella (`improve the project`, `customize the AI`), re-render its installed member sub-list to pick from instead of running | +| `?` | Expand the full detail (each step's command id and tier clause, the per-check foundation reasons, the read-only extras), read-only, then re-offer | +| skip a step | Record it left in the session ledger (checks.md Done rule); it does not re-fire next scan | | explain a step | Describe the step and its command in two or three plain lines, then re-offer. Never runs a skill | | explain project | Summarize the project from its memory bank, read-only, then re-offer. Only when memory is filled | +| recap | Summarize this session's conversation (what was worked on, decided, still pending), read-only, then re-offer. Only when a prior conversation exists this session, never on a first-message onboard | | stop | One-line close, end the loop | | a gap | The step has no installed skill. Say it needs a plugin, by function only. Offer explain or stop | ## Loop -After any step runs, re-scan (`→ 01`) and re-render the report so a resolved `✗` flips to `✓`. A read-only reply (explain, stop) does not re-scan. Wait for an explicit reply before running anything. +After any step runs, re-scan (`→ 01`) and re-render the report so a resolved `✗` flips to `✓`. A read-only reply (`?`, explain, explain project, recap, stop) and an umbrella pick (which only re-renders a sub-list) do not re-scan. Wait for an explicit reply before running anything. From 8c49eaceb67e628c9d848abeb96d1ef54ca23b4e Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 05:51:17 +0200 Subject: [PATCH 05/44] docs(aidd-context): plan the onboard tutorial rebuild MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 5-phase plan for reworking onboard into a token-optimized guided tutorial: granular conditional-load file tree, 4-action chain (scan → assess → present → run), state-aware foundations, leaner router format, updated skill-authoring contract. Colleague-approved mockup gallery included. Co-Authored-By: Claude Opus 4.8 --- .../onboard-mockups.html | 376 ++++++++++++++++++ .../phase-1.md | 59 +++ .../phase-2.md | 53 +++ .../phase-3.md | 73 ++++ .../phase-4.md | 84 ++++ .../phase-5.md | 51 +++ .../plan.md | 40 ++ 7 files changed, 736 insertions(+) create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/onboard-mockups.html create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/onboard-mockups.html b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/onboard-mockups.html new file mode 100644 index 00000000..debbd052 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/onboard-mockups.html @@ -0,0 +1,376 @@ +AIDD Onboard — Tutorial Mockups + + +
+
+
AIDD · onboard skill
+

Onboard as a guided tutorial

+

Every screen the reworked onboard shows a user, from a bare repo to shipping a feature. It announces itself, shows the project's AIDD setup up front, then walks the official flow one step at a time. Mockups for review — not final wording.

+
+ ✓ present & wired + ⚠ present, not wired — carries a fix + ✗ required, missing + [k] reply key +
+
+ +
+
01

Existing project · adopting AIDD

the common case — code already here, so memory comes first

+
+ +
+
existing repo · launch
+
 █████╗ ██╗██████╗ ██████╗
+██╔══██╗██║██╔══██╗██╔══██╗
+███████║██║██║  ██║██║  ██║
+██╔══██║██║██║  ██║██║  ██║
+██║  ██║██║██████╔╝██████╔╝
+╚═╝  ╚═╝╚═╝╚═════╝ ╚═════╝ 
+ AI-Driven Development
+
+👋  I'll walk you through AIDD step by step — nothing runs until you reply.
+
+Your AIDD setup:
+  AI tools   claude ⚠
+  Plugins    aidd-context · pm · refine · dev · vcs   ✓
+  Memory     ✗ not set up yet
+
+You already have code — AIDD just has no memory of it yet.
+
+⚠  Let's teach the AI about your project first. Every command relies on it.
+   → Type [1] to generate your project memory.   see the flow [m]
+
+ +
+
foundations · step 1 of 2
+
Foundations — step 1 of 2
+
+  project memory     scan your existing code into a memory bank the AI reads
+                     (architecture, testing, conventions — so commands don't guess)
+
+👉  Type [1] to start.   what's this [?]
+
+No "design the stack" step — your stack already exists, so it's skipped.
+
+ +
+
foundations · step 2 of 2
+
✓  Project memory saved.
+
+Foundations — step 2 of 2
+
+  connect it to the AI     wire the memory into claude's context file (CLAUDE.md)
+                           so it loads automatically every session
+
+👉  Type [1] to start.   skip [s]
+
+ +
+
+ +
+
02

Brand-new project · greenfield

empty repo — design the stack first, then memory

+
+ +
+
greenfield · launch
+
 █████╗ ██╗██████╗ ██████╗
+██╔══██╗██║██╔══██╗██╔══██╗
+███████║██║██║  ██║██║  ██║
+██╔══██║██║██║  ██║██║  ██║
+██║  ██║██║██████╔╝██████╔╝
+╚═╝  ╚═╝╚═╝╚═════╝ ╚═════╝ 
+ AI-Driven Development
+
+👋  I'll walk you through AIDD step by step — nothing runs until you reply.
+
+Your AIDD setup:
+  AI tools   claude ⚠   codex ⚠
+  Plugins    aidd-context · pm · refine · dev · vcs   ✓
+  Memory     ✗ not set up yet
+
+⚠  Your AI tools have no project memory yet.
+   → Type [1] to set up the foundations.   see the flow [m]
+
+ +
+
foundations · step 1 of 3
+
Foundations — step 1 of 3
+
+  design your tech stack     pick your technologies & architecture
+                             (saved to INSTALL.md — everything builds on it)
+
+👉  Type [1] to start (asks you a few questions).   skip [s] · what's this [?]
+
+ +
+
foundations · step 2 of 3
+
✓  Tech stack set.
+
+Foundations — step 2 of 3
+
+  save project knowledge     generate the memory files the AI reads
+                             (so commands work with real context, not guesses)
+
+👉  Type [1] to start.   skip [s]
+
+ +
+
foundations · step 3 of 3
+
✓  Project knowledge saved.
+
+Foundations — step 3 of 3
+
+  connect it to the AI       wire the memory into each AI tool's context file
+                             (CLAUDE.md, AGENTS.md — so it loads automatically)
+
+👉  Type [1] to start.   skip [s]
+
+ +
+
+ +
+
03

Coming back to build

foundations ready — the official flow

+
+ +
+
established · welcome back · the flow
+
 █████╗ ██╗██████╗ ██████╗
+██╔══██╗██║██╔══██╗██╔══██╗
+███████║██║██║  ██║██║  ██║
+██╔══██║██║██║  ██║██║  ██║
+██║  ██║██║██████╔╝██████╔╝
+╚═╝  ╚═╝╚═╝╚═════╝ ╚═════╝ 
+ AI-Driven Development
+
+👋  Welcome back.
+
+Your AIDD setup:
+  AI tools   claude ✓
+  Plugins    aidd-context · pm · refine · dev · vcs   ✓
+  Memory     aidd_docs/ · 8 files synced   ✓
+
+All set. Build your next feature — the AIDD flow:
+
+  brainstorm      turn a vague idea into something precise
+      │
+  spec            the contract of what to build          (optional)
+      │
+  plan            break it into phases
+      │
+  implement       build it, phase by phase
+      │
+  assert          check it behaves
+      │
+  review          verdict before shipping
+      │
+  commit          save the work
+      │
+  pull request    ship it
+
+Run it:
+   [1]  Walk it with me — one step at a time, I explain each.
+   [2]  Let SDLC drive the whole flow from one request.
+   map [m] · explore all commands [?] · stop [x]
+
+ +
+
walk · step 1 of 8
+
Your first feature — step 1 of 8: Brainstorm.
+
+  What:  turn your rough idea into something precise enough to build.
+  Why:   a fuzzy idea makes every next step guess.
+
+👉  Type [1] to start.   whole flow [m] · skip to spec [s]
+
+ +
+
walk · step 4 of 8
+
Feature flow — step 4 of 8: Implement.   (brainstorm ✓ · spec ✓ · plan ✓)
+
+  What:  build the plan, phase by phase.
+  Why:   small verified phases beat one big leap.
+
+👉  Type [1] to start.   whole flow [m] · back [<]
+
+ +
+
map · the flow at a glance
+
AIDD feature flow:
+
+  brainstorm → spec* → plan → implement → assert → review → commit → PR
+  (* optional)
+
+  back [<]
+
+ +
+

The map view is the same canonical sequence shown as a standalone cookbook — one source, two doors.

+
+ +
+
04

Where you are, mid-work

the flow tracks your progress

+
+ +
+
building · unsaved changes
+
🔍  Healthy — unsaved changes in progress.
+
+  Flow:  brainstorm ✓ · spec ✓ · plan ✓ · [implement] · assert · review · commit · PR
+
+👉  Next: finish your changes   [1]
+    review them [2] · both [OK] · more [?]
+
+ +
+
ready to review
+
🔍  Healthy — changes ready to review.
+
+  Flow:  brainstorm ✓ · spec ✓ · plan ✓ · implement ✓ · assert ✓ · [review] · commit · PR
+
+👉  Next: review your changes   [1]
+    ship them [2] · both [OK] · more [?]
+
+ +
+
ready to ship
+
🔍  Healthy — reviewed, ready to ship.
+
+  Flow:  brainstorm ✓ · … · review ✓ · commit ✓ · [pull request]
+
+👉  Next: open a pull request   [1]   (you run this one yourself)
+    more [?]
+
+ +
+
+ +
+
05

Warnings that carry a fix

every ⚠ says what's wrong and the next action

+
+ +
+
tool installed, not wired
+
👋  Welcome back.
+
+Your AIDD setup:
+  AI tools   claude ✓   codex ⚠
+  Plugins    aidd-context · pm · refine · dev · vcs   ✓
+  Memory     aidd_docs/ · 8 files synced   ✓
+
+⚠  codex is installed but its memory isn't wired (no AGENTS.md).
+   → Type [1] to wire it.   build a feature instead [m]
+
+ +
+
memory block drifted
+
👋  Welcome back.
+
+Your AIDD setup:
+  AI tools   claude ⚠
+  Plugins    aidd-context · pm · refine · dev · vcs   ✓
+  Memory     aidd_docs/ · 8 files synced   ✓
+
+⚠  claude's memory block drifted from the canonical shape.
+   → Type [1] to re-wire it.
+
+ +
+
healthy, but no tests
+
🔍  Healthy — but no tests yet.
+
+  Flow:  ready for new work.
+
+⚠  This project has no tests, so changes aren't protected.
+   → Next: add tests   [1]
+      start new work [2] · improve the project [3] · explore [?]
+
+ +
+
+ +
+
06

Detail on demand

[?] opens the full view — ids, tiers, reasons

+
+ +
+
[?] expanded
+
Details —
+
+  1. finish your changes   aidd-dev:02-implement   (it will ask you a few questions)
+  2. review your changes   aidd-dev:05-review      (runs on its own)
+
+  AI tools   claude ✓
+  Plugins    aidd-context · pm · refine · dev · vcs   ✓
+  Memory     aidd_docs/ · 8 files synced   ✓
+
+  explain <n> · recap · stop · back [<]
+
+ +
+
+ +
+

Reworked onboard · greenfield → foundations → build a feature. The state block (AI tools / plugins / memory) sits up front on every entry screen. Detection roots: .claude .codex .cursor .opencode .github/copilot-instructions.md .github/{instructions,agents,skills,prompts}. Unused tools are omitted, never crossed out.

+
+
diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md new file mode 100644 index 00000000..145973e5 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md @@ -0,0 +1,59 @@ +--- +status: pending +--- + + + +# Instruction: Update the skill-authoring contract + +## Architecture projection + +> Tree of the final files. ✅ create · ✏️ modify · ❌ delete + +```txt +plugins/aidd-context/skills/04-skill-generate/references/ +└── ✏️ skill-authoring.md # relax R3, add conditional-load + notation rules +``` + +## Tasks to do + +### `1)` Relax the one-level reference rule + +> References may nest so a step loads only what it needs. + +1. Rewrite R3: references MAY sit in sub-folders (`references//`); a reference still never `@`-chains another reference. +2. State the load-locality rule: split a file from another ONLY when some execution path needs one without the other; co-loaded content stays one file. + +### `2)` Add the notation rule + +> Sanction terse notation and diagrams. + +1. Add a rule: reference/action bodies use telegraphic notation (tables, `→` for linear chains, fragments), never at the cost of a load-bearing condition. +2. Add: use a Mermaid diagram only for branching logic, not for a linear chain. + +### `3)` Define the router (SKILL.md) format + +> A leaner, self-evident action format — no field to interpret. + +1. Frontmatter: official keys only (`name`, `description`, `argument-hint`); forbid an invented `kind`-style flag. +2. Body: a tiny `# Title`, then the chaining shown as a one-line arrow schema for a pipeline (`a → b → c ↺`) or the line `Pick one per request.` for a menu; no separate flow prose. +3. Actions table columns `# | Action | Does`, `Does` verb-led and telegraphic; drop the restated intro sentence and the `Input` column (it lives in each action's `## Input`). +4. Move "read an action's file just before running it" to a standing contract rule, not repeated per skill. + +### `4)` Reconcile the rest of the contract + +> Keep R1-R13 coherent after the edits. + +1. Re-read R13 (includes) against nested paths; adjust wording so an action cites a nested reference by its full `@`. +2. Confirm no other rule contradicts nesting; renumber or note scope if needed. + +## Test acceptance criteria + + + +| Task | Acceptance criteria | +| ---- | ----------------------------------------------------------------------------------- | +| 1 | R3 permits a `references//file.md` and still bans reference-to-reference `@`-chains. | +| 2 | The contract names the telegraphic-notation rule and the Mermaid-only-for-branching rule. | +| 3 | The router format is specified: tiny title, arrow-schema for a pipeline or "pick one" for a menu, verb-led `Does`, no intro sentence, no `Input` column, no invented frontmatter flag. | +| 4 | No rule in the contract contradicts nested references; R13 covers nested `@` citation. | diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md new file mode 100644 index 00000000..6b6effcc --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md @@ -0,0 +1,53 @@ +--- +status: pending +--- + + + +# Instruction: Scan action + state refs + +## Architecture projection + +> Tree of the final files. ✅ create · ✏️ modify · ❌ delete + +```txt +plugins/aidd-context/skills/00-onboard/ +├── actions/ +│ └── ✏️ 01-scan.md # loads state/ refs conditionally, adds AI-tools detection +└── references/ + ├── ✅ state/zones.md # the check catalogue per zone (from checks.md) + ├── ✅ state/detection.md # AI-tool roots + per-tool wiring status + ├── ✅ state/done-rule.md # session ledger / re-nag kill (from checks.md) + ├── ✅ state/hedge.md # plan-status build-to-ship pin (from checks.md) + └── ❌ checks.md # content split into state/ and order/ (order/ in phase 3) +``` + +## Tasks to do + +### `1)` Carve the state references out of checks.md + +> Tiny files, one concern each. + +1. `state/zones.md`: the zone checks as a terse table (met/drift rule, deliverable, command, tier); keep the state-aware architecture rule (established => tech stack ✓, greenfield => ❌). +2. `state/detection.md`: roots `.claude .codex .cursor .opencode .github/copilot-instructions.md .github/{instructions,agents,skills,prompts}` => tool; per-tool wiring = its context file carries the memory block. Glyphs: `✓` used+wired · `⚠` used, not wired · `✗` required missing. Unused optional tools omitted. +3. `state/done-rule.md`: a step is done when disk proves it OR the session ledger recorded it run/left; 01 reads, 03 writes; no file. +4. `state/hedge.md`: plan `status:` => `in-progress` pins Build alone, `implemented`/open-PR pins Review-then-Ship, unreadable pins Build-then-Review. + +### `2)` Rewrite 01-scan to load state refs conditionally + +> Pay only for what the scan needs. + +1. Load `state/zones.md` and `state/detection.md` every scan; `state/hedge.md` only when a plan exists; re-read `state/done-rule.md`'s ledger every scan. +2. Add the detection step: resolve each AI-tool root to a tool and its wiring status. +3. Keep cross-branch scoping: only the current branch's PR sets the dev-flow pin. + +## Test acceptance criteria + + + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------------- | +| 1 | Each `state/*.md` holds exactly one concern and no `@`-chain to another reference. | +| 2 | The snapshot carries per-tool detection (`✓/⚠/✗`) with unused tools absent, not crossed. | +| 2 | A plan `status: in-progress` yields Build-alone; a repo-wide PR on another branch sets no pin. | +| 2 | A step recorded in the session ledger is absent from the next scan's actionable set. | diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md new file mode 100644 index 00000000..4424c7a5 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md @@ -0,0 +1,73 @@ +--- +status: pending +--- + + + +# Instruction: Assess + run actions + +## Architecture projection + +> Tree of the final files. ✅ create · ✏️ modify · ❌ delete + +```txt +plugins/aidd-context/skills/00-onboard/ +├── actions/ +│ ├── ✅ 02-assess.md # snapshot => decision (state class, ranked next, chosen screen) +│ ├── ✅ 04-run.md # renamed from 03-run.md, executes the reply +│ └── ❌ 03-run.md +└── references/ + ├── ✅ order/ranking.md # next-action order (from checks.md) + ├── ✅ order/idle-menu.md # 3 umbrellas + explore (from checks.md) + ├── ✅ order/screen-map.md # Mermaid: state => which screen + ├── ✅ run/replies.md # key routing (from run-tiers.md) + ├── ✅ run/tiers.md # auto/guided/manual + default-overridable (from run-tiers.md) + ├── ✅ run/return.md # return-to-onboard on GUIDED handoff (from run-tiers.md) + └── ❌ run-tiers.md # content split into run/ +``` + +## User Journey + +```mermaid +flowchart TD + SN[01 scan snapshot] --> AS[02 assess] + AS --> PR[03 present] + PR --> RP{reply} + RP -->|number| RUN[04 run: step or umbrella] + RP -->|OK| WALK[04 run: walk pending] + RP -->|?/back| PR + RP -->|recap/explain/stop| RO[read-only] + RUN --> SN + WALK --> SN +``` + +## Tasks to do + +### `1)` Build the assess action + order refs + +> Turn the raw snapshot into one decision. + +1. `order/ranking.md`: 1 unmet foundation, 2 earliest dev-flow step, 3 fired health tool, 4 idle menu; hold 2-4 while a foundation is unmet. +2. `order/idle-menu.md`: umbrellas `start new work [1]` · `improve the project [2]` · `customize the AI [3]` · `explore [?]`; an umbrella pick re-renders its installed members. +3. `order/screen-map.md`: a Mermaid `stateDiagram` mapping state (greenfield / existing / drift / idle / mid-work) to the screen to render. +4. `02-assess.md`: read the `01-scan` snapshot, load `order/`, output the decision (state class, ranked next-action, chosen screen); hand to `03-present`. No rendering here. + +### `2)` Carve the run refs + build 04-run + +> Execute a reply, delegate the how. + +1. `run/replies.md`: keys `[n] [OK] [?] recap explain skip stop`, each's effect; read-only vs re-scan; `[?]`/`back` re-render via `03-present` without re-assessing. +2. `run/tiers.md`: AUTO/GUIDED/MANUAL semantics; tier is a default, overridable when the skill supports the other mode. +3. `run/return.md`: on a GUIDED handoff, tell the user to re-run onboard to return; the ledger drops the handed-off step. +4. Rename `03-run.md` => `04-run.md`: load `run/replies.md` always, `run/tiers.md` only when running a step, `run/return.md` only on a GUIDED handoff; write the ledger per `state/done-rule.md` after each handled step. + +## Test acceptance criteria + + + +| Task | Acceptance criteria | +| ---- | --------------------------------------------------------------------------------------- | +| 1 | `02-assess` outputs a decision and renders nothing; `screen-map.md` is a Mermaid diagram. | +| 1 | Ranking holds dev-flow/health/idle while a foundation is unmet; an umbrella pick re-renders a member sub-list. | +| 2 | `[?]`/`back` re-render via `03-present` with no re-scan and no re-assess. | +| 2 | A GUIDED handoff emits the return-to-onboard line; the re-scan does not re-recommend the handed-off step. | diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md new file mode 100644 index 00000000..c8085d32 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md @@ -0,0 +1,84 @@ +--- +status: pending +--- + + + +# Instruction: Present action (tutorial render) + +## Architecture projection + +> Tree of the final files. ✅ create · ✏️ modify · ❌ delete + +```txt +plugins/aidd-context/skills/00-onboard/ +├── actions/ +│ ├── ✅ 03-present.md # renamed from 02-report.md, renders the screen assess chose +│ └── ❌ 02-report.md +├── references/ +│ └── ✅ flow.md # 8-step curriculum + 2 foundation paths, source of [map] +└── assets/ + ├── ✏️ report.md # the screen shapes (state block, foundations, flow, next, [?], warnings) + └── ✅ banner.txt # AIDD ASCII banner, injected +``` + +## Wireframe + + + +```txt +The confirmed screens are the mockup gallery: ./onboard-mockups.html +(18 screens, 6 sections, colleague-approved). Render to match it. Canonical examples: + + █████╗ ██╗██████╗ ██████╗ <- banner.txt + AI-Driven Development + +👋 Welcome back. + +Your AIDD setup: + AI tools claude ✓ codex ⚠ + Plugins aidd-context · pm · refine · dev · vcs ✓ + Memory aidd_docs/ · 8 files synced ✓ + +⚠ codex is installed but its memory isn't wired (no AGENTS.md). + → Type [1] to wire it. + +--- flow (walk vs SDLC) --- + brainstorm → spec* → plan → implement → assert → review → commit → PR + [1] Walk it with me [2] Let SDLC drive it map [m] · [?] +``` + +## Tasks to do + +### `1)` Write the curriculum reference + +> The teaching content, on-demand only. + +1. `flow.md`: the 8 steps (brainstorm, spec*, plan, implement, assert, review, commit, PR) each with a one-line what/why; the vertical annotated layout (tutorial) and the horizontal compact layout (`[map]`). +2. Add the two foundation paths: existing => memory-first (2 steps, bootstrap skipped); greenfield => stack, memory, wire (3 steps). + +### `2)` Author the render shapes + +> Rich screens, terse rules. + +1. `assets/banner.txt`: the AIDD ASCII banner as a plain injected block. +2. `assets/report.md`: the state block (glyph semantics + warning-carries-a-fix line), the framing line (first report only), foundations-step screen, the flow screen, the `Next` line with keys, the `[?]` detail. Keep load-bearing rules; examples live in `flow.md`, banner in `banner.txt`. + +### `3)` Rewrite 03-present + +> Render the screen assess chose, delegate the shape. + +1. Rename `02-report.md` => `03-present.md`; render the screen named in the `02-assess` decision, filling `assets/report.md`. +2. Load `banner.txt` only on entry screens; `flow.md` only on flow/walk screens. +3. Every `⚠` renders with its plain cause and a fix action; unused tools omitted. + +## Test acceptance criteria + + + +| Task | Acceptance criteria | +| ---- | ----------------------------------------------------------------------------------------- | +| 1 | `flow.md` lists all 8 steps with what/why and both layouts; both foundation paths present. | +| 2 | A rendered `⚠` line names the cause and offers a keyed fix; the framing line shows only on the first report. | +| 3 | An existing repo renders memory as foundation step 1 of 2; a greenfield renders the stack first. | +| 3 | The banner appears on entry screens only; a warning screen loads no `flow.md`. | diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md new file mode 100644 index 00000000..6cdbb564 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md @@ -0,0 +1,51 @@ +--- +status: pending +--- + + + +# Instruction: Router, description, docs, budget + +## Architecture projection + +> Tree of the final files. ✅ create · ✏️ modify · ❌ delete + +```txt +plugins/aidd-context/skills/00-onboard/ +├── ✏️ SKILL.md # router: short description, action table (scan|present|run), refs/assets, principles +└── ✏️ README.md # human doc, tutorial framing +plugins/aidd-context/ +└── ✏️ CATALOG.md # auto-synced by the pre-commit hook +``` + +## Tasks to do + +### `1)` Rewrite the router + +> Lean SKILL.md; the only always-on cost is the description. + +1. Description: verb-led, `Use when` triggers led by "onboard me", `Not for` clause; target <= ~65 tokens. +2. Body in the phase-1 router format: tiny `# Onboard` title, the pipeline schema `scan → assess → present → run ↺`, then the `# | Action | Does` table with verb-led telegraphic `Does`. No intro sentence, no `Input` column. +3. List the nested references and assets; transversal rules as principles only, no render detail; `argument-hint: scan | assess | present | run`. + +### `2)` Update the human doc + +1. README: reframe onboard as a guided tutorial (banner, state block, flow, walk-or-SDLC); it is not model-loaded, so no token budget applies. + +### `3)` Verify the token budget and links + +> Prove the economy, not assert it. + +1. Measure: description tokens (always-on) and the model-loaded total; record the before/after delta against the noob-first checkpoint. +2. Run the markdown-link check across the skill; every nested `@` resolves. + +## Test acceptance criteria + + + +| Task | Acceptance criteria | +| ---- | --------------------------------------------------------------------------------------- | +| 1 | SKILL.md is a pure router in the phase-1 format (tiny title, `scan → assess → present → run ↺` schema, verb-led `Does`, no intro/`Input`); the description is <= ~65 tokens and leads triggers with "onboard me". | +| 2 | README describes the tutorial flow and names no token rule for itself. | +| 3 | The measured model-loaded total is recorded with its delta; the link check reports zero broken links. | +| regress | Cross-branch PR scoping, session ledger, state-aware foundations, plan-status hedge, tier default+override, framing line, warnings-carry-a-fix, recap reply, and return-to-onboard all still hold end-to-end. | diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md new file mode 100644 index 00000000..a325f169 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md @@ -0,0 +1,40 @@ +--- +objective: "onboard is rebuilt as a token-optimized guided tutorial over a granular, conditional-load file tree that teaches the AIDD flow, every current behavior preserved, and the skill-authoring contract updated to sanction the new structure." +status: pending +--- + + + +# Plan: Onboard tutorial rebuild + +## Overview + +| Field | Value | +| ---------- | ----------------------------------------------------------------------------------------- | +| **Goal** | Turn onboard from a status dashboard into a didactic, token-lean tutorial teaching the AIDD flow. | +| **Source** | This conversation's agreed design; mockup gallery [`onboard-mockups.html`](./onboard-mockups.html) (colleague-approved). | + +## Phases + +| # | Phase | File | +| --- | ---------------------------------- | ---------------------------- | +| 1 | Update the skill-authoring contract | [`phase-1.md`](./phase-1.md) | +| 2 | Scan action + state refs | [`phase-2.md`](./phase-2.md) | +| 3 | Assess + run actions (order/ + run/) | [`phase-3.md`](./phase-3.md) | +| 4 | Present action (tutorial render) | [`phase-4.md`](./phase-4.md) | +| 5 | Router, description, docs, budget | [`phase-5.md`](./phase-5.md) | + +## Decisions + + + +| Decision | Why | +| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| Stay Markdown; no JSON/XML format swap | Measured (tiktoken): XML +16..29%, JSON content-dependent (+12% tabular). Format is a trap. | +| Two token surfaces: always-on = description only; everything else on-demand | The description loads for every skill each session; the body/refs load only when used. | +| Split files only along conditional-load boundaries | Split A from B only if a path needs A without B; co-loaded content stays one file. | +| State-aware foundations order: existing repo => memory first (bootstrap skipped); greenfield => stack, memory, wire | Memory feeds on the project; empty repo has nothing to memorize, so the stack comes first. | +| Update `skill-generate/references/skill-authoring.md` to allow nested references | The granular tree needs `references/state|order|run/`, which today's R3 forbids. | +| Tutorial verbosity (banner, curriculum) lives in on-demand assets/refs, never in SKILL.md | Keeps the always-on and router surfaces lean while the tutorial stays rich. | +| Four actions, one per responsibility and file group: scan (state/), assess (order/), present (assets/+flow), run (run/) | `[?]`/`back` re-renders via present without re-deciding, so present is a real boundary from assess. | +| Router format: tiny title, an arrow schema (`a → b ↺` pipeline) or "pick one" (menu), verb-led telegraphic `Does`; drop the intro, the `Input` column, and any invented frontmatter flag | The mode reads itself with no field to interpret; official frontmatter keys only. | From a0ca10567602f978ac2bbf1a413b82759f0dff21 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 05:51:18 +0200 Subject: [PATCH 06/44] refactor(aidd-context): nested refs + leaner router format in skill-authoring Phase 1 of the onboard rebuild. Relax R3 to allow nested reference sub-folders with a load-locality rule; reconcile R13 (import vs pointer, nested paths); add R14 (telegraphic notation, mermaid only for branching); specify the router format (tiny title, arrow/pick-one chaining schema, verb-led Does, no intro/Input column, official frontmatter keys only). Co-Authored-By: Claude Opus 4.8 --- .../04-skill-generate/references/skill-authoring.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index 1919a548..8cf9a5f9 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -4,9 +4,9 @@ The contract every generated skill must satisfy. These rules govern the CLIENT s ## Rules -- **R1.** SKILL.md is a pure router: description + action table + transversal rules. Zero business logic. +- **R1.** SKILL.md is a pure router: a tiny title, the chaining schema, the action table, and transversal rules (see `## SKILL.md`). Zero business logic. - **R2.** One skill = one domain. A tool domain uses a singular noun (`slack`). An activity domain uses an action verb (`review`). See `## Naming`. -- **R3.** References one level deep. A reference never `@`-chains another reference. +- **R3.** References may nest in sub-folders (`references//`) so a step loads only what it needs. A reference still never `@`-chains another reference. Split a file from another only when some execution path needs one without the other; content that always co-loads stays one file. - **R4.** SKILL.md <= 500 lines. If exceeded, split into references. - **R5.** `description` states what + when. Third person, no XML. Conventions: - **Two lines max, straight to the point.** Target ~240 characters; never more than a short paragraph. Length serves recall, not completeness. The hard ceiling is 1024 chars, not a goal. @@ -23,7 +23,8 @@ The contract every generated skill must satisfy. These rules govern the CLIENT s - **R10.** Generated skills are English only (frontmatter, body, actions, references, assets), regardless of conversation language. - **R11.** One idea per sentence. Split a sentence that runs past one line. Exceptions: the single-line `description` and table rows. - **R12.** One file = one artifact. A reference or asset holds a single coherent thing: one checklist, one template, one criteria set. When a file accumulates several independently reusable artifacts, split them so each is cited and reused alone. Prefer this split over bundling, even when the combined file is short. -- **R13.** Includes are explicit and scoped. Cite an include with its `@` alone inside a fenced ``` block, never inline in prose. Naming: a global include (imported from SKILL.md, used skill-wide) takes no prefix; an include used by only one action is prefixed with that action's slug (e.g. `research-checklist.md`). SKILL.md lists only the global includes; an action-specific include is cited only from its own action. +- **R13.** Includes are explicit and scoped. An **import** (content pulled into context) is cited with its `@` alone inside a fenced ``` block. A **pointer** (read-this-reference in a step) may cite `@` inline in prose. Either uses the reference's full path, including a nested `references//file.md`. Naming: a global include (imported from SKILL.md, used skill-wide) takes no prefix; an include used by only one action is prefixed with that action's slug (e.g. `research-checklist.md`). SKILL.md lists only the global includes; an action-specific include is cited only from its own action. +- **R14.** Bodies use telegraphic notation: tables, `→` for a linear chain, fragments over sentences, no filler. Never at the cost of a load-bearing condition. A branch, edge case, or if/then stays precise. Use a Mermaid diagram only for branching logic, never for a linear chain. ## Action anatomy @@ -48,7 +49,11 @@ The router: YAML frontmatter + markdown body. - `description`: per R5. - `argument-hint` when supported or in plugin source and the skill has two or more actions: action names only, joined with ` | `, matching the files in `actions/`. Omit it for one-action skills. - A manual-only flag makes the skill user-only. The exact frontmatter key is per tool. -- Body: pure router. The action table maps each `#` and slug to a role and input. State the flow (a sequential chain or a trigger-to-action map). Self-skips stated explicitly. +- Frontmatter carries official keys only (`name`, `description`, `argument-hint`, the host manual-only flag). Never invent a flag the model must interpret; the body carries mode, not a made-up key. +- Body order: a tiny `# Title`, the chaining schema, the action table, then the transversal rules. No restated intro sentence; the `description` already states the what. + - **Chaining schema.** A pipeline shows a one-line arrow schema, `a → b → c ↺` (`↺` marks a loop back). A menu shows the line `Pick one per request.` and no schema. The mode reads itself; no field states it. + - **Action table.** Columns `# | Action | Does`; `Does` is verb-led and telegraphic (verb + object). A menu drops the `#` column. No `Input` column: an action's input lives in its own `## Input`. +- Standing rule for every skill: read an action's file just before running it, not only the router table. Stated here once, never repeated in a SKILL.md body. The `name` field is NOT the invocation token. The host builds the address from the plugin and folder, each in its own scheme. A colon or prefix in `name` breaks loading on some hosts. In prose, refer to a skill as `plugin:folder`, never `plugin:folder:action`. From 0c03742050c0741c615fd1386862f44024b41db9 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 05:55:43 +0200 Subject: [PATCH 07/44] feat(aidd-context): onboard state layer (scan + state refs) Phase 2. Split the state catalogue into tiny conditional-load refs: state/zones.md (foundations, dev flow, health), state/detection.md (AI-tool roots + per-tool wiring), state/done-rule.md (session ledger), state/hedge.md (plan-status pin). Rewrite 01-scan to load them per step and detect AI tools + wiring. checks.md kept until phase 3 extracts order/. Co-Authored-By: Claude Opus 4.8 --- .../phase-1.md | 2 +- .../phase-2.md | 2 +- .../plan.md | 2 +- .../skills/00-onboard/actions/01-scan.md | 22 ++++----- .../00-onboard/references/state/detection.md | 26 ++++++++++ .../00-onboard/references/state/done-rule.md | 7 +++ .../00-onboard/references/state/hedge.md | 9 ++++ .../00-onboard/references/state/zones.md | 49 +++++++++++++++++++ 8 files changed, 105 insertions(+), 14 deletions(-) create mode 100644 plugins/aidd-context/skills/00-onboard/references/state/detection.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/state/done-rule.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/state/hedge.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/state/zones.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md index 145973e5..1ab7b6c6 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md index 6b6effcc..5c60f11c 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md index a325f169..fc4968b1 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md @@ -1,6 +1,6 @@ --- objective: "onboard is rebuilt as a token-optimized guided tutorial over a granular, conditional-load file tree that teaches the AIDD flow, every current behavior preserved, and the skill-authoring contract updated to sanction the new structure." -status: pending +status: in-progress --- diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index c95d49e6..dc0f1ba2 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -1,6 +1,6 @@ # 01 - Scan -Read the project once, silently, into a reusable snapshot. No questions, no writes, no visible output. +Read the project once, silently, into a snapshot. No questions, no writes, no visible output. ## Input @@ -8,26 +8,26 @@ The project root, the current working directory. ## Output -A silent snapshot, never printed: the status (`✓ ⚠ ✗`) of every check in `@../references/checks.md`, the installed AIDD plugins and skills each with its description, and the project name and purpose from the brief when memory is synced. +A silent snapshot, never printed: the status (`✓ ⚠ ✗`) of every check in `@../references/state/zones.md`, the detected AI tools each with its wiring glyph, the installed AIDD plugins and skills each with its description, and the project name and purpose from the brief when memory is synced. ## Process -1. **Check.** Evaluate every check in `@../references/checks.md` by its own met and drift rules: a met fact (disk, or a cheap VCS read where the row says so) sets `✓`, a missing artifact sets `✗`, and only the row's stated drift case sets `⚠`. Scope each check to the paths the row names, never an installed-plugin tree. -2. **Ledger.** Apply the Done rule in `@../references/checks.md`: a step the session ledger recorded run or left this session counts done, so it drops out even when disk cannot prove it. -3. **Hedge.** Read the plan's `status:` frontmatter to pin the build-to-ship stage per the zone-3 hedge in `@../references/checks.md`. -4. **Drift.** For the context block, compare the AI context file's `` block against the canonical shape. +1. **Zones.** Evaluate every check in `@../references/state/zones.md` by its met and drift rules. Scope each to the paths the row names, never an installed-plugin tree. Read VCS state for the current branch only. +2. **Detect.** Resolve the AI-tool roots and per-tool wiring per `@../references/state/detection.md`. +3. **Ledger.** Apply the Done rule in `@../references/state/done-rule.md`: a step the session ledger recorded run or left drops out even when disk cannot prove it. Re-read the ledger every scan. +4. **Hedge.** Only when a plan exists, read its `status:` and pin the build-to-ship stage per `@../references/state/hedge.md`. +5. **Drift.** For memory wiring, compare each used tool's context block against the canonical shape. ```md @../../02-project-memory/references/memory-block.md ``` -5. **List.** Gather the enabled AIDD plugins and skills, each with its description, via the tool's native discovery. This is what `02` resolves each command against. -6. **Hold.** Keep the snapshot in context and hand to `02-report`. Print nothing. Refresh the disk and VCS facts only on change, not every loop. Re-read the session ledger on every scan, so a step recorded since the last scan drops out. +6. **List.** Gather the enabled AIDD plugins and skills, each with its description, via the tool's native discovery. +7. **Hold.** Keep the snapshot in context and hand to `02-assess`. Print nothing. Refresh disk and VCS facts only on change, not every loop. ## Test - Zero user-visible output: no snapshot, no checklist, no status appears. -- The snapshot carries a status for every check in `checks.md` and the installed skills with descriptions. +- The snapshot carries a status for every check in `zones.md`, plus detected AI tools with a `✓`/`⚠` wiring glyph and unused tools absent. - A step the session ledger recorded run or left is absent from the snapshot's actionable set. -- Plan `status: in-progress` pins Build alone; `implemented` or an open PR pins Review then Ship. -- No report or command is emitted by this action. +- A repo-wide PR on another branch sets no pin; only the current branch's PR does. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md new file mode 100644 index 00000000..daa00269 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -0,0 +1,26 @@ +# AI tool detection + +`01-scan` reads this to fill the state block's AI-tools line. + +## Root => tool + +| Tool | Root present | +| -------- | ------------------------------------------------------------------------------------- | +| claude | `.claude/` or `CLAUDE.md` | +| codex | `.codex/` or `AGENTS.md` | +| cursor | `.cursor/` or `.cursorrules` | +| opencode | `.opencode/` | +| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | + +## Wiring status per detected tool + +Wired = the tool's own context file carries the `` block on canonical shape (claude => `CLAUDE.md`, codex => `AGENTS.md`, cursor => `.cursor/rules/`, and so on per tool). + +| Glyph | Means | +| ----- | --------------------------- | +| `✓` | used AND memory wired | +| `⚠` | used, memory not wired | + +- Render a **detected** tool only. An unused optional tool is omitted, never crossed with `✗`. +- A `⚠` always carries its cause and fix in the render, e.g. "codex installed, no `AGENTS.md` block => wire it". +- `✗` belongs to a required foundation that is missing (memory absent), not to a tool row. See `zones.md`. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md new file mode 100644 index 00000000..fe39b20a --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md @@ -0,0 +1,7 @@ +# Done rule (session ledger) + +A step is done when a disk signal proves it OR the session ledger recorded it run or left this session. A done step never re-enters the next-action list. + +- Single home for this rule: `01-scan` reads it, `04-run` writes it. No file, in-context session state. +- Kills the re-nag for off-disk completions a disk scan cannot see: a read-only review, a MANUAL step left for the user, an explicit skip. +- `01-scan` re-reads the ledger every scan, so a step recorded since the last scan drops out. Disk and VCS facts refresh on change, not every loop. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md new file mode 100644 index 00000000..153e3178 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md @@ -0,0 +1,9 @@ +# Plan-status hedge + +The plan's `status:` frontmatter refines the build-to-ship pin, so review is never skipped nor premature. `01-scan` reads it only when a plan exists. + +| Plan `status:` | Pin | +| ----------------------- | ---------------------------- | +| `in-progress` | Implement alone | +| `implemented`, or an open PR | Review, then commit/ship (Review first) | +| unreadable or absent | Implement, then Review | diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md new file mode 100644 index 00000000..108c3dff --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -0,0 +1,49 @@ +# State zones + +Disk/VCS checks that place the project. `01-scan` reads this. Glyphs: `✓` met · `⚠` drift · `✗` missing. + +## Foundations + +State-aware order: existing repo (code present) => memory first, bootstrap skipped. Greenfield empty => stack, then memory, then wire. + +| Check | Met `✓` | Drift `⚠` | Deliverable | Command | +| ------------- | -------------------------------------------------------------- | ---------------------------------- | ------------------------- | -------------------------------- | +| tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | +| project memory| `aidd_docs/memory/` has real content | files empty or placeholder | project knowledge saved | `aidd-context:02-project-memory` | +| memory wiring | `` block on canonical shape in each used tool's context file | block present but off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | + +- tech stack is `✗` only on a truly greenfield repo (no code AND no synced memory). Established => `✓`, never bootstrap. +- memory wiring: an absent block or no context file is `✗`, not `⚠`. `01-scan` loads the canonical block shape to judge drift. + +## Dev flow + +The official feature flow, cumulative: a downstream artifact implies the upstream stages are met. + +```txt +brainstorm → spec* → plan → implement → assert → review → commit → PR (spec optional) +``` + +| Stage | The pin sits here when | +| ---------- | -------------------------------------------------- | +| brainstorm | no spec, plan, or code yet (idea only) | +| spec | a spec under `aidd_docs/`, nothing downstream | +| plan | a `plan.md` under `aidd_docs/`, no code against it | +| implement | code present against the plan | +| assert | code done, coding assertions not yet green | +| review | code done, current branch's PR awaits review | +| commit | reviewed, uncommitted or unpushed | +| PR | current branch has an open PR | + +- `review` and `PR` read cheap VCS state, **current branch only**: the PR whose head is this branch. Ignore repo-wide open PRs and review queues — another branch's PR is another dev's work, never the pin. +- `brainstorm` and `spec` have no hard disk signal; they are the pin only when no downstream artifact exists. +- The plan's `status:` refines the pin: see `hedge.md`. + +## Health + +Beside-the-flow tools, surfaced only when their signal fires. Scan project source only; exclude templates, fixtures, examples, generated output, and any installed-plugin tree. + +| Signal | Fires when | Command | +| ----------- | ----------------------------------------- | ------------------- | +| no tests | no real test files | `aidd-dev:06-test` | +| bug markers | `TODO`/`FIXME` or reported errors in source | `aidd-dev:08-debug` | +| messy code | a file far longer or deeper than siblings | `aidd-dev:04-audit` | From 43c66727840feefb93c351a082d4a5ca3af0baab Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 06:00:31 +0200 Subject: [PATCH 08/44] feat(aidd-context): onboard assess + run actions with order/ + run/ refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 3. Add 02-assess (snapshot => decision: state class, ranked next, chosen screen) over order/{ranking, idle-menu, screen-map(mermaid)}. Rename 03-run => 04-run over run/{replies, tiers, return}. Rename 02-report => 03-present (body rewritten in phase 4). Delete run-tiers.md (content moved to run/). Four actions: scan → assess → present → run. Co-Authored-By: Claude Opus 4.8 --- .../phase-3.md | 2 +- plugins/aidd-context/CATALOG.md | 6 +-- .../aidd-context/skills/00-onboard/README.md | 2 +- .../aidd-context/skills/00-onboard/SKILL.md | 2 +- .../skills/00-onboard/actions/02-assess.md | 25 ++++++++++ .../actions/{02-report.md => 03-present.md} | 0 .../skills/00-onboard/actions/03-run.md | 27 ---------- .../skills/00-onboard/actions/04-run.md | 24 +++++++++ .../00-onboard/references/order/idle-menu.md | 14 ++++++ .../00-onboard/references/order/ranking.md | 10 ++++ .../00-onboard/references/order/screen-map.md | 20 ++++++++ .../skills/00-onboard/references/run-tiers.md | 49 ------------------- .../00-onboard/references/run/replies.md | 18 +++++++ .../00-onboard/references/run/return.md | 3 ++ .../skills/00-onboard/references/run/tiers.md | 13 +++++ 15 files changed, 133 insertions(+), 82 deletions(-) create mode 100644 plugins/aidd-context/skills/00-onboard/actions/02-assess.md rename plugins/aidd-context/skills/00-onboard/actions/{02-report.md => 03-present.md} (100%) delete mode 100644 plugins/aidd-context/skills/00-onboard/actions/03-run.md create mode 100644 plugins/aidd-context/skills/00-onboard/actions/04-run.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/order/ranking.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/order/screen-map.md delete mode 100644 plugins/aidd-context/skills/00-onboard/references/run-tiers.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/run/replies.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/run/return.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/run/tiers.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md index 4424c7a5..a430c1b5 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 9ed6b3be..4a387ae0 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -45,12 +45,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-scan.md](skills/00-onboard/actions/01-scan.md) | - | -| `actions` | [02-report.md](skills/00-onboard/actions/02-report.md) | - | -| `actions` | [03-run.md](skills/00-onboard/actions/03-run.md) | - | +| `actions` | [02-assess.md](skills/00-onboard/actions/02-assess.md) | - | +| `actions` | [03-present.md](skills/00-onboard/actions/03-present.md) | - | +| `actions` | [04-run.md](skills/00-onboard/actions/04-run.md) | - | | `assets` | [report.md](skills/00-onboard/assets/report.md) | - | | `-` | [README.md](skills/00-onboard/README.md) | - | | `references` | [checks.md](skills/00-onboard/references/checks.md) | - | -| `references` | [run-tiers.md](skills/00-onboard/references/run-tiers.md) | - | | `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface.` | #### `skills/01-bootstrap` diff --git a/plugins/aidd-context/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md index 0ecc2e53..1e3f353c 100644 --- a/plugins/aidd-context/skills/00-onboard/README.md +++ b/plugins/aidd-context/skills/00-onboard/README.md @@ -36,4 +36,4 @@ Only the `aidd-context` plugin installed and enabled, and a working directory ro ## Details -See [`SKILL.md`](SKILL.md) for the action contract and [`actions/`](actions/) for the three actions. The catalogue lives in [`references/checks.md`](references/checks.md) (the four zones and their checks) and [`references/run-tiers.md`](references/run-tiers.md) (the tiers and the `OK` chain); the report shape is [`assets/report.md`](assets/report.md). +See [`SKILL.md`](SKILL.md) for the action contract and [`actions/`](actions/) for the four actions. The references live under [`references/`](references/) (state, order, run, and the flow curriculum); the render shape is [`assets/report.md`](assets/report.md). diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index a13de7aa..4f211b1e 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,7 +1,7 @@ --- name: 00-onboard description: Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface. -argument-hint: scan | report | run +argument-hint: scan | assess | present | run --- # Onboard diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md new file mode 100644 index 00000000..cd996d6c --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -0,0 +1,25 @@ +# 02 - Assess + +Turn the scan snapshot into one decision: state class, ranked next action, chosen screen. Render nothing. + +## Input + +The snapshot from `01-scan`, held in context. + +## Output + +A decision handed to `03-present`: the state class, the top-ranked next action (or the idle menu), and the screen to render. Nothing is printed. + +## Process + +1. **Classify.** Map the snapshot to a state class per `@../references/order/screen-map.md`. +2. **Rank.** Pick the top next action per `@../references/order/ranking.md`. When idle, build the menu per `@../references/order/idle-menu.md`. +3. **Resolve.** Resolve each offered command against the installed skills from `01`; name a gap by function when the skill is absent, never invent one. +4. **Hand.** Pass the decision to `03-present`. Render nothing here. + +## Test + +- The action outputs a decision and renders nothing. +- Ranking holds the dev-flow, health, and idle steps back while a foundation is unmet. +- An idle decision names the three umbrellas plus explore, each umbrella carrying its installed members. +- No uninstalled command is named; an absent one is a gap by function. diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-report.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md similarity index 100% rename from plugins/aidd-context/skills/00-onboard/actions/02-report.md rename to plugins/aidd-context/skills/00-onboard/actions/03-present.md diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-run.md b/plugins/aidd-context/skills/00-onboard/actions/03-run.md deleted file mode 100644 index 98f86b65..00000000 --- a/plugins/aidd-context/skills/00-onboard/actions/03-run.md +++ /dev/null @@ -1,27 +0,0 @@ -# 03 - Run - -Carry out the user's reply per its tier, then loop back to scanning. - -## Input - -- The user's reply from `02-report`: a step number (`[1]`…), `OK`, `?`, an explain request, a recap request, or stop. -- The resolved command per line, or a gap when no installed skill fits. -- The snapshot from `01-scan`, held in context. - -## Process - -1. **Route.** Carry out the reply per `@../references/run-tiers.md`: `OK` walks the pending steps, a number runs one step (or re-renders an idle-menu umbrella's member sub-list), `?` expands the full detail, and `?`, explain, recap, and stop stay read-only. -2. **Guard.** Run or name only skills `01` found installed. A gap never invokes a skill: offer explain or stop. Never run a MANUAL step, only show it. -3. **Record.** Note each handled step in the session ledger per the Done rule in `@../references/checks.md`: a step run, a MANUAL step shown and left, or one the user skips. The next scan then drops it even when disk cannot prove it. -4. **Loop.** After any step or the `OK` walk runs, re-scan (`→ 01`) and re-render so a resolved `✗` flips to `✓`. A read-only reply does not re-scan. - -## Output - -One outcome per `@../references/run-tiers.md`, always ending with the refreshed report or a clean stop. - -## Test - -- `OK` walks the whole list, runs AUTO steps unattended, and pauses at each GUIDED step for input rather than running it unattended. -- A MANUAL step is shown, never run; a gap invokes nothing. -- After a step or the `OK` walk runs, the re-scan flips resolved statuses; a read-only reply does not re-scan. -- After a MANUAL step is shown and left, or a step is skipped, the re-scan does not re-recommend it. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md new file mode 100644 index 00000000..03a54eb9 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -0,0 +1,24 @@ +# 04 - Run + +Carry out the user's reply, then loop back to scanning. + +## Input + +- The reply from `03-present`: a number, `OK`, `?`, `back`, `recap`, `explain`, `skip`, or `stop`. +- The decision from `02-assess`: the resolved commands, or a gap when no installed skill fits. + +## Process + +1. **Route.** Carry out the reply per `@../references/run/replies.md`. +2. **Guard.** Run or name only skills `01` found installed. A gap invokes nothing: offer explain or stop. Never run a MANUAL step, only show it. +3. **Tier.** When running a step, apply `@../references/run/tiers.md`; the tier is a default, overridable when the skill supports the other mode. +4. **Return.** On a GUIDED handoff, emit the return line per `@../references/run/return.md`. +5. **Record.** Note each handled step in the session ledger per `@../references/state/done-rule.md`. +6. **Loop.** After a step or the `OK` walk runs, re-scan (`→ 01`). A read-only reply or an umbrella pick does not re-scan. + +## Test + +- `OK` walks the pending steps, runs AUTO unattended, and pauses at each GUIDED for input. +- A MANUAL step is shown, never run; a gap invokes nothing. +- `?`/`back` re-render via `03-present` with no re-scan and no re-assess. +- A GUIDED handoff emits the return line; the re-scan does not re-recommend the handed-off step. diff --git a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md new file mode 100644 index 00000000..7f07bd7f --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md @@ -0,0 +1,14 @@ +# Idle menu + +When ranks 1-3 are clear, `02-assess` offers three umbrellas plus explore. + +| Slot | Umbrella | Opens (installed members) | +| ---- | ------------------- | ----------------------------------------------------------------------------------------- | +| 1 | start new work | `aidd-dev:00-sdlc` (or `aidd-pm:04-spec`) — a feature from idea to shipped | +| 2 | improve the project | `aidd-dev:04-audit` · `aidd-dev:06-test` · `aidd-dev:07-refactor` | +| 3 | customize the AI | the **missing** context-gen generators, each in plain words: a coding rule (`aidd-context:05-rule-generate`), a reusable workflow (`aidd-context:04-skill-generate`), a specialized assistant (`aidd-context:06-agent-generate`), a slash command (`aidd-context:07-command-generate`), an automated action (`aidd-context:08-hook-generate`) | +| ? | explore | `aidd-context:11-explore` and anything not in slots 1-3 | + +- Slots 2 and 3 are umbrellas: a pick re-renders the installed member sub-list; a member pick runs it. Slot 1 runs directly. +- Surface an installed member only; drop an umbrella with no member. +- Choices, not a chain: `OK` never walks the idle menu. diff --git a/plugins/aidd-context/skills/00-onboard/references/order/ranking.md b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md new file mode 100644 index 00000000..d8660748 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md @@ -0,0 +1,10 @@ +# Next-action order + +`02-assess` ranks the next action from the snapshot. First match wins. + +1. Unmet foundation, in `zones.md` order (memory first for an existing repo, stack first for greenfield). +2. Earliest unmet dev-flow stage, hedged by `state/hedge.md`. +3. A fired health tool. +4. Idle menu (see `idle-menu.md`) — only when 1-3 are all clear. + +While any foundation is unmet, hold 2-4 back: a bare repo lists only its setup steps. diff --git a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md new file mode 100644 index 00000000..61127f38 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -0,0 +1,20 @@ +# Screen map + +`02-assess` picks the screen from the state class. + +```mermaid +stateDiagram-v2 + [*] --> greenfield: no code, no memory + [*] --> existing: code present, memory missing + [*] --> drift: a foundation is ⚠ + [*] --> midwork: a dev-flow step pending + [*] --> idle: all clear +``` + +| State class | Screen | +| ----------- | -------------------------------------------------------------- | +| greenfield | welcome + foundations, **stack first** (3 steps) | +| existing | welcome + foundations, **memory first** (2 steps, stack skipped) | +| drift | welcome + the warning-with-fix | +| midwork | where-you-are on the flow + the next step | +| idle | welcome + the flow (walk or SDLC), or the idle menu | diff --git a/plugins/aidd-context/skills/00-onboard/references/run-tiers.md b/plugins/aidd-context/skills/00-onboard/references/run-tiers.md deleted file mode 100644 index 4a3e8d8e..00000000 --- a/plugins/aidd-context/skills/00-onboard/references/run-tiers.md +++ /dev/null @@ -1,49 +0,0 @@ -# Run tiers - -How `03-run` carries out the user's pick. Every step in `checks.md` carries one default tier (see the note below). Only ever run or name a skill that `01` found installed. - -## The three tiers - -| Tier | What it is | How onboard runs it | -| ------ | ------------------------------------------- | -------------------------------------------------------------------------- | -| AUTO | Non-interactive, safe to spawn and walk away | Invoke the resolved skill, let it run to completion, then move on | -| GUIDED | Interactive, drives its own Q&A | Launch the resolved skill in this session, let the user drive it, resume when it returns. State the return path on handoff (see Returning) | -| MANUAL | Side-effecting or outward-facing | Show the exact command, do not run it, move on and leave it for the user | - -The run mechanism is per step, not one size. An AUTO step may invoke its skill directly or fan out to `aidd-dev:10-todo`; onboard follows the command the check names, never forces a single orchestrator. - -**The tier is a default, not a fixed skill property.** Many skills run either way depending on how they are invoked (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`). Each step in `checks.md` carries the tier that fits its default use, and the report phrases it as a plain clause telling the user what happens if they just run it. The user can override per invocation: ask to run a GUIDED step unattended, or an AUTO step interactively, and onboard invokes the skill in that mode when the skill supports it. - -## Returning to onboard - -Handing off a GUIDED step launches another skill, which may not return control on its own. So on every handoff, tell the user one line: re-run onboard to come back and continue (the deterministic path is the slash command for this skill). The re-run re-scans, and the session ledger drops the step just handed off, so the user resumes where they left off rather than repeating it. - -## The `OK` walk - -When the user replies `OK` to the report, walk the ordered list top to bottom, one step at a time: - -1. **AUTO step:** run it to completion, then continue to the next. -2. **GUIDED step:** launch it and hand control to the user. When it returns, continue to the next. -3. **MANUAL step:** show the command, run nothing, note it is left for the user, continue. -4. After the walk, re-scan (`→ 01`) and render the refreshed report. - -`OK` drives the whole list, not just a prefix. It pauses at each GUIDED step for the user's input and resumes after, so a greenfield project's setup chain runs end to end from one `OK`. State up front how many steps the walk covers and which need input. - -The idle menu (checks.md rank 4) is the exception: it is a set of choices, not a chain, so `OK` never walks it. When the list is only the idle menu, there is nothing for `OK` to run; the user picks one item by number. - -## Other replies - -| Reply | What happens | -| --------------- | --------------------------------------------------------------------------------------------- | -| a step number | Run that step per its tier. If the number is an idle-menu umbrella (`improve the project`, `customize the AI`), re-render its installed member sub-list to pick from instead of running | -| `?` | Expand the full detail (each step's command id and tier clause, the per-check foundation reasons, the read-only extras), read-only, then re-offer | -| skip a step | Record it left in the session ledger (checks.md Done rule); it does not re-fire next scan | -| explain a step | Describe the step and its command in two or three plain lines, then re-offer. Never runs a skill | -| explain project | Summarize the project from its memory bank, read-only, then re-offer. Only when memory is filled | -| recap | Summarize this session's conversation (what was worked on, decided, still pending), read-only, then re-offer. Only when a prior conversation exists this session, never on a first-message onboard | -| stop | One-line close, end the loop | -| a gap | The step has no installed skill. Say it needs a plugin, by function only. Offer explain or stop | - -## Loop - -After any step runs, re-scan (`→ 01`) and re-render the report so a resolved `✗` flips to `✓`. A read-only reply (`?`, explain, explain project, recap, stop) and an umbrella pick (which only re-renders a sub-list) do not re-scan. Wait for an explicit reply before running anything. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/replies.md b/plugins/aidd-context/skills/00-onboard/references/run/replies.md new file mode 100644 index 00000000..d4f4164b --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -0,0 +1,18 @@ +# Replies + +`04-run` routes the user's reply. + +| Reply | Effect | +| ------------- | --------------------------------------------------------------------------------- | +| a number `[n]`| run that step per its tier; an idle-menu umbrella re-renders its member sub-list instead | +| `OK` | walk the pending steps (ranks 1-3) in order; never the idle menu | +| `?` | expand the full detail (command ids, tier clauses, per-check reasons); read-only | +| `back` / `<` | re-render the prior screen via `03-present`; read-only, no re-scan | +| `recap` | summarize this session's conversation; read-only; only when a prior conversation exists | +| `explain ` | describe a step in two or three plain lines; read-only | +| `skip` | record the step left in the ledger; it does not re-fire | +| `stop` | one-line close, end the loop | +| a gap | no installed skill; say it needs a plugin, by function; offer explain or stop | + +- Read-only replies (`?`, `back`, `recap`, `explain`, `stop`) and umbrella picks do not re-scan. +- After a step or the `OK` walk runs, re-scan (`→ 01`) and re-render. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/return.md b/plugins/aidd-context/skills/00-onboard/references/run/return.md new file mode 100644 index 00000000..c567061b --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/run/return.md @@ -0,0 +1,3 @@ +# Return to onboard + +Handing off a GUIDED step launches another skill, which may not return control on its own. So on every handoff, tell the user one line: re-run onboard to come back and continue (the deterministic path is this skill's slash command). The re-run re-scans; the session ledger drops the handed-off step, so the user resumes where they left off rather than repeating it. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md new file mode 100644 index 00000000..99888d4a --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md @@ -0,0 +1,13 @@ +# Tiers + +How `04-run` carries out a step. The tier is a default, overridable. + +| Tier | What | How onboard runs it | +| ------ | ----------------------- | ---------------------------------------------------------- | +| AUTO | non-interactive | invoke, run to completion, continue | +| GUIDED | interactive Q&A | launch, hand to the user, resume on return (see `return.md`) | +| MANUAL | side-effecting, outward | show the command, run nothing, leave it for the user | + +- Rendered as a plain clause, never a glyph: AUTO `(runs on its own)`, GUIDED `(it will ask you a few questions)`, MANUAL `(you run this one yourself)`. +- The tier is the step's default. A skill that runs either way (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`) runs the other way when the user asks and the skill supports it. +- The `OK` walk: AUTO runs to completion, GUIDED pauses for input then resumes, MANUAL is shown and left. State up front how many steps it covers and which need input. From 1419a42d6b55743f2d3003b028416b4dd6b25129 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 06:05:26 +0200 Subject: [PATCH 09/44] feat(aidd-context): onboard tutorial presentation (present + report + flow + banner) Phase 4. Rewrite 03-present to render the screen 02-assess chose, injecting banner.txt on entry screens and loading flow.md on flow/walk screens. New flow.md (8-step curriculum, two state-aware foundation paths, vertical + map layouts). New banner.txt (AIDD ASCII). Rewrite report.md into the screen shapes (state block with warning-carries-a-fix, foundations step, where-you-are, [?] detail). Delete checks.md, now fully split into state/ and order/. Co-Authored-By: Claude Opus 4.8 --- .../phase-4.md | 2 +- plugins/aidd-context/CATALOG.md | 3 +- .../skills/00-onboard/actions/03-present.md | 30 +++---- .../skills/00-onboard/assets/banner.txt | 7 ++ .../skills/00-onboard/assets/report.md | 88 ++++++++++++++----- .../skills/00-onboard/references/checks.md | 86 ------------------ .../skills/00-onboard/references/flow.md | 64 ++++++++++++++ 7 files changed, 156 insertions(+), 124 deletions(-) create mode 100644 plugins/aidd-context/skills/00-onboard/assets/banner.txt delete mode 100644 plugins/aidd-context/skills/00-onboard/references/checks.md create mode 100644 plugins/aidd-context/skills/00-onboard/references/flow.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md index c8085d32..19a8ad6a 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 4a387ae0..bb487d2c 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -48,9 +48,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-assess.md](skills/00-onboard/actions/02-assess.md) | - | | `actions` | [03-present.md](skills/00-onboard/actions/03-present.md) | - | | `actions` | [04-run.md](skills/00-onboard/actions/04-run.md) | - | +| `assets` | [banner.txt](skills/00-onboard/assets/banner.txt) | - | | `assets` | [report.md](skills/00-onboard/assets/report.md) | - | | `-` | [README.md](skills/00-onboard/README.md) | - | -| `references` | [checks.md](skills/00-onboard/references/checks.md) | - | +| `references` | [flow.md](skills/00-onboard/references/flow.md) | - | | `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface.` | #### `skills/01-bootstrap` diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index b488ae86..8fd1f49e 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -1,27 +1,25 @@ -# 02 - Report +# 03 - Present -Lead with one plain state sentence and one recommended action a first-timer can act on, everything else demoted. +Render the screen `02-assess` chose. Fill the shape, keep detail on demand. ## Input -The snapshot from `01-scan` (statuses + installed skills), held in context, not printed. +The decision from `02-assess`: the state class, the screen to render, and the ranked action or idle menu. -## Process +## Output -1. **Resolve.** For each check, resolve its canonical command in `@../references/checks.md` against the installed skills from `01`. A match keeps the command. No match names a gap by function, never an invented command. -2. **Order.** Rank the recommended list per the `## Ranking` policy in `@../references/checks.md`. -3. **Tag.** Phrase each step's tier as the natural-language clause `@../assets/report.md` maps to the row's tier in `@../references/checks.md`, never a glyph badge. -4. **Render.** Fill `@../assets/report.md`, following its state, dashboard, next, key, and idle-menu rules. -5. **Wait.** Offer the report and wait for a reply. Never auto-advance. Hand the reply to `03-run`. +The rendered screen per `@../assets/report.md`, offered to the user. The reply goes to `04-run`. -## Output +## Process -The rendered report per `@../assets/report.md`: a framing line on the first report of the session, a `🔍` state sentence, the `🏗️ Foundations` and `🚦 Progress` dashboard rows, and a `👉 Next` recommendation naming the top step in plain words with its `[1]` key plus a compact options line. Command ids and tier clauses live only in the `[?]` detail, never in this default view. +1. **Shape.** Fill the screen the decision names, from `@../assets/report.md`. +2. **Inject.** On an entry screen, inject the banner from `@../assets/banner.txt`. On a flow or walk screen, load `@../references/flow.md`. +3. **Warn.** Render every `⚠️` with its plain cause and a keyed fix; omit unused tools; command ids and tier clauses stay under `[?]`. +4. **Wait.** Offer the screen and wait for a reply. Never auto-advance. Hand the reply to `04-run`. ## Test -- The first report of the session opens with the framing line; a re-scan later in the same session drops it. -- The state sentence reads the project's standing in plain words; Progress marks the current stage in `[brackets]`, never `📍/◦/➖`. -- `Next` names the single top-ranked step with key `[1]`; the compact options line uses bracketed keys (`[2]`, `[OK]`, `[?]`); no command id or tier clause appears in the default view. -- When nothing is pending, `Next` is the idle menu (`start new work [1]`, then `improve the project [2] · customize the AI [3] · explore [?]`); umbrella slots re-render a member sub-list on pick, and no `[OK]` is offered. -- Every offered step resolves to a concrete installed command or is a gap named by function. +- The framing line shows on the first report of the session only; a later re-scan drops it. +- An existing repo renders memory as foundation step 1 of 2; a greenfield renders the stack first. +- The banner appears on entry screens only; a warning-only screen loads no `flow.md`. +- Every `⚠️` names its cause and offers a keyed fix; no command id or tier clause appears outside `[?]`. diff --git a/plugins/aidd-context/skills/00-onboard/assets/banner.txt b/plugins/aidd-context/skills/00-onboard/assets/banner.txt new file mode 100644 index 00000000..cf2ee097 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/assets/banner.txt @@ -0,0 +1,7 @@ + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index d136765b..eb9eae72 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -1,28 +1,76 @@ - + - + -🔍 +## Entry screen (greenfield · existing · idle · drift) -🏗️ Foundations -🚦 Progress +```txt + -👉 Next: [1] - +👋 - +- Framing shows on the first report of the session only, then drops on re-scans. +- The banner is injected from `banner.txt` on entry screens only. +- Idle: the flow (from `flow.md`) and `[1] Walk it with me · [2] Let SDLC drive it`, or the idle menu when the user opens it. + +## Foundations step + +```txt +Foundations — step of + + + () + +👉 Type [1] to start. skip [s] · what's this [?] +``` + +- `` is 2 for an existing repo (memory first, stack skipped) or 3 for greenfield, per `flow.md`. + +## Where you are (mid-work) + +```txt +🔍 + + Flow: + +👉 Next: [1] + +``` + +## Warnings that carry a fix + +A `⚠️` never stands alone. Render its plain cause, then the fix as a keyed action: + +```txt +⚠️ + → Type [1] to . +``` + +## [?] detail + +On `[?]`, expand the decision: each step's command id and tier clause, the per-check foundation reasons, and the read-only extras. + +```txt +Details — + 1. () + ... + + explain · recap · stop · back [<] +``` + +- `recap` only when a prior conversation exists; `explain project` only when memory is filled. diff --git a/plugins/aidd-context/skills/00-onboard/references/checks.md b/plugins/aidd-context/skills/00-onboard/references/checks.md deleted file mode 100644 index 7f79c030..00000000 --- a/plugins/aidd-context/skills/00-onboard/references/checks.md +++ /dev/null @@ -1,86 +0,0 @@ -# Diagnostic catalogue - -Every check `01-scan` captures and `02-report` renders, in report order. Four zones. Foundations first, then dev flow, then health. - -Each row carries: the **met** rule (a disk fact = `✓`), the **drift** rule (`⚠`, missing or off-format), the **deliverable** named to the user, the canonical **command**, and the **tier** (see `run-tiers.md`). A command resolves to the installed skill by its id, or is named a gap by function when that skill is not installed. - -This catalogue **is** the capability map. A newly installed plugin's capability enters `Do this next` only when a row is added here, a deliberate light tradeoff over dynamic discovery. - -## Ranking - -The order of the `Do this next` list, the single home for this policy: - -1. Unmet zone-1 foundations, in table order. -2. The earliest unmet dev-flow step. -3. Any health tool whose signal fired. -4. When 1-3 are all clear (foundations met, no dev-flow step pending, no health signal), the **idle menu**: three plain umbrellas plus explore, never a flat list of cryptic generators. - -The idle menu is: - -| Slot | Umbrella | Opens (on pick, a sub-list of the installed members) | -| ---- | ------------------- | ------------------------------------------------------------------------------------- | -| 1 | start new work | `aidd-dev:00-sdlc` (or `aidd-pm:04-spec` when absent), a feature from idea to shipped | -| 2 | improve the project | `aidd-dev:04-audit`, `aidd-dev:06-test`, `aidd-dev:07-refactor` | -| 3 | customize the AI | the zone-2 generators for the **missing** artifacts (rule, skill, agent, command, hook), each named in plain words | -| ? | explore | `aidd-context:11-explore` and any capability not in slots 1-3 (learn, PM, and the rest) | - -Slots 2 and 3 are umbrellas: picking one re-renders its member sub-list to pick from, picking a member runs it. Slot 1 runs directly. Only surface a member that `01` found installed; drop an umbrella with no installed member. - -While any zone-1 foundation is unmet, hold the dev-flow, health, and idle-menu steps back, so a bare repo lists only its setup steps. The idle menu opens only at rank 4, never alongside a pending dev-flow step: a project mid-work stays focused on its one next step, an idle project gets the open menu instead of a dead end. - -**Done rule (session ledger).** A step is done when a disk signal proves it OR the session ledger recorded it run or left this session. A done step never re-enters `Do this next`. This is the single home for the rule: `01` reads it, `03` writes it, no file. It kills the re-nag for off-disk completions a disk scan cannot see (a read-only review, a MANUAL step left for the user, an explicit skip). - -## Zone 1: AIDD context (foundations) - -| Check | Met (`✓`) | Drift (`⚠`) | Deliverable | Command | Tier | -| ------------- | ----------------------------------------------- | -------------------------------------------------------- | ---------------- | -------------------------- | ------ | -| architecture | `aidd_docs/INSTALL.md` exists, or the repo is already established (source code or a synced memory bank present) | — | tech stack | `aidd-context:01-bootstrap` | GUIDED | -| memory bank | `aidd_docs/memory/` exists with real content | files empty or placeholder | project knowledge saved | `aidd-context:02-project-memory` | GUIDED | -| context block | `` block present in the AI context file, on the canonical shape | block present but off the canonical shape, see external data (absent block or no context file is `✗`, not `⚠`) | knowledge loaded by the AI | `aidd-context:02-project-memory` | GUIDED | - -Architecture is `❌` only on a truly greenfield repo: no source code **and** no synced memory bank, so the user is told to design a stack. An established project (code present, or the memory bank already synced) has its stack in place, so it is `✅`, never a loud `❌` and never a bootstrap recommendation. Keys on files on disk, not commit history. - -## Zone 2: Context-gen artifacts (foundations, optional) - -Scoped to **project-level** artifacts only, under the tool's own config root (`.claude/`, `.cursor/`, `.github/`, `AGENTS.md`). Never count a plugin's shipped source: an artifact under `plugins/*/` or any installed-plugin directory is the framework's product, not this project's context, and does not meet these checks. - -| Check | Met (`✓`) | Deliverable | Command | Tier | -| -------- | -------------------------------------------------- | ----------- | --------------------------- | ------ | -| rules | a project rule file present | rules | `aidd-context:05-rule-generate` | GUIDED | -| agents | a project agent under `.claude/agents/` (or peer) | agents | `aidd-context:06-agent-generate` | GUIDED | -| skills | a project skill under `.claude/skills/` (or peer) | skills | `aidd-context:04-skill-generate` | GUIDED | -| hooks | a `hooks` entry in the tool's settings | hooks | `aidd-context:08-hook-generate` | GUIDED | -| commands | a project command under `.claude/commands/` (or peer) | commands | `aidd-context:07-command-generate` | GUIDED | - -These are optional, never a loud `✗`. They surface only under the idle menu's `customize the AI` umbrella (rank 4, slot 3), each **missing** one a member named in plain words (`a coding rule the AI follows`, `a reusable workflow`, `a specialized assistant`, …); the ones already present are not offered. They are choices, not a chain: the `OK` walk covers ranks 1-3 only, the idle menu is pick-by-number. - -## Zone 3: Dev flow - -The per-work sequence, in order. Each step resolves to an installed skill by function; the commands below are the canonical resolution. - -| Step | Present when | Command (canonical) | Tier | -| ------- | ----------------------------------- | ---------------------------------- | ------ | -| clarify | a spec or refined need under `aidd_docs/` | `aidd-pm:04-spec` | GUIDED | -| track | a tracked item exists | `aidd-pm:02-user-stories` | GUIDED | -| plan | a `plan.md` under `aidd_docs/` | `aidd-dev:01-plan` | GUIDED | -| build | code present against the plan | `aidd-dev:02-implement` | GUIDED | -| review | build looks done, nothing reviewed | `aidd-dev:05-review` | AUTO | -| ship | current branch has an open PR, or is merged and unreleased | `aidd-vcs:02-pull-request` | MANUAL | - -Stages are cumulative. A downstream artifact implies the upstream stages are met, so a project with a plan starts the flow at build, not clarify. - -The plan's `status:` frontmatter hedges the build-to-ship pin, so review is never skipped nor premature: `in-progress` pins Build alone; `implemented` or an open PR pins Review then Ship, Review first; an unreadable or absent status pins Build then Review. - -`clarify` and `track` have no direct disk signal; they are the place only when no downstream artifact exists, never a loud default. `review` and `ship` read cheap VCS state, current branch only: the PR/MR whose head is this branch, via the project's VCS tool. Ignore repo-wide open PRs and review queues — another branch's PR is another dev's work, never the pin. - -## Zone 4: Health (tools, not steps) - -A fired health tool enters `Do this next` ranked **after** the earliest dev-flow step, never above it, and never while a zone-1 foundation is unmet (the held-back rule in `## Ranking` applies to health too). It is a beside-the-flow tool, never the ordered default. Scan **project source only**. Exclude templates, fixtures, examples, generated output, and any installed-plugin tree (`plugins/*/`, `.claude/plugins/`, `node_modules/`); a marker inside example or template content is not a real marker. - -| Signal | Met when | Deliverable | Command | Tier | -| ----------------- | ------------------------------------- | ----------- | ------------------- | ---- | -| no tests | no real test files | add tests | `aidd-dev:06-test` | GUIDED | -| bug markers | `TODO` / `FIXME` or reported errors in project source | debug | `aidd-dev:08-debug` | GUIDED | -| messy code sample | a file far longer or deeper than siblings | audit | `aidd-dev:04-audit` | AUTO | - -Reading memory-file contents to judge drift and a single bounded code sample are the only sanctioned non-cheap reads. diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md new file mode 100644 index 00000000..b420ca73 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -0,0 +1,64 @@ +# The AIDD flow curriculum + +`03-present` loads this on a flow or walk screen. It teaches the feature flow and the two foundation paths. It is also the source of the `[map]` view. + +## Foundations, two paths + +The order is state-aware. + +- **Existing project** (code present) — memory first, the stack is skipped: + 1. `project memory` — scan the existing code into a memory bank the AI reads. + 2. `connect it to the AI` — wire the memory into each used tool's context file. +- **Greenfield** (empty repo) — stack first: + 1. `design tech stack` — pick the technologies and architecture. + 2. `project memory` — record what the project is. + 3. `connect it to the AI` — wire the memory in. + +## Feature flow, the eight steps + +Each step, one line of what and why. `spec` is optional. + +| Step | What | Why | +| ------------ | ---------------------------------------- | --------------------------------------- | +| brainstorm | turn a vague idea into something precise | a fuzzy idea makes every next step guess | +| spec* | write the contract of what to build | one agreed definition, no drift | +| plan | break it into phases | small units that ship and verify | +| implement | build it, phase by phase | verified phases beat one big leap | +| assert | check it behaves | catch breakage before review | +| review | a verdict before shipping | ship or iterate, decided | +| commit | save the work | an atomic, reversible record | +| pull request | ship it | open it for merge | + +## Layouts + +**Vertical, annotated** — the tutorial screen: + +```txt + brainstorm turn a vague idea into something precise + │ + spec the contract of what to build (optional) + │ + plan break it into phases + │ + implement build it, phase by phase + │ + assert check it behaves + │ + review verdict before shipping + │ + commit save the work + │ + pull request ship it +``` + +**Horizontal, compact** — the `[map]` view: + +```txt +brainstorm → spec* → plan → implement → assert → review → commit → PR +(* optional) +``` + +## Run it + +- `[1]` walk it with me — one step at a time, each explained. +- `[2]` let `aidd-dev:00-sdlc` drive the whole flow from one request. From ce670ff87cb8b5cc612bdd27326d53b3f58302eb Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 06:07:41 +0200 Subject: [PATCH 10/44] feat(aidd-context): lean onboard router + tutorial README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 5. Rewrite SKILL.md in the new router format (tiny title, 'scan → assess → present → run ↺' schema, verb-led Does, no intro or Input column): 567 → 296 tok. Reframe README as a guided tutorial. Token budget (tiktoken cl100k, proxy): always-on description 66 tok; model-loaded corpus 5672 tok (-249 vs the noob-first checkpoint). The real win is conditional loading — each action pays its own layer (scan ~1280, assess ~620, run ~620) instead of the old checks.md (2068) + run-tiers (1033) co-loaded monolith. Co-Authored-By: Claude Opus 4.8 --- .../phase-5.md | 2 +- .../aidd-context/skills/00-onboard/README.md | 29 ++++++++++------- .../aidd-context/skills/00-onboard/SKILL.md | 32 ++++++------------- 3 files changed, 27 insertions(+), 36 deletions(-) diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md index 6cdbb564..d411fdd1 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md @@ -1,5 +1,5 @@ --- -status: pending +status: done --- diff --git a/plugins/aidd-context/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md index 1e3f353c..f36e032d 100644 --- a/plugins/aidd-context/skills/00-onboard/README.md +++ b/plugins/aidd-context/skills/00-onboard/README.md @@ -2,12 +2,12 @@ # 00 - Onboard -A linter for an AIDD project. It scans the working directory against the framework, reports what is present, drifting, or missing as an explicit `✅ ⚠️ ❌` checklist, and hands back a single ordered list of the exact commands to run next. Reply `OK` and it walks the whole list for you, pausing at each step that needs your input. +A guided tutorial for an AIDD project. It announces itself, shows your AIDD setup up front (AI tools, plugins, memory), then walks you through the framework one step at a time: lay the foundations, then build a feature through the official flow. Nothing runs until you reply. ## When to use -- "Where do I start?" / "Onboard me to this project." -- "What should I do next?" +- "Onboard me to this project." / "Get me started." +- "Where do I start?" / "What should I do next?" - "How does this project stand against AIDD?" - After a partial setup, to see what is still missing. @@ -18,22 +18,27 @@ A linter for an AIDD project. It scans the working directory against the framewo ## Flow -Three actions, in a loop: +Four actions in a loop: `scan → assess → present → run ↺`. -1. `scan`: **silently** read the project once into a snapshot of every check across four zones. Prints nothing. -2. `report`: render the loud diagnostic plus one ordered command list, foundations first, then the dev flow, each line naming a concrete installed command and its run tier. -3. `run`: carry out the reply. `OK` walks the whole list, running the unattended steps and pausing at each interactive one; a number runs one step; then re-scan and refresh. +1. `scan`: silently read the project into a snapshot — the checks, the detected AI tools and their wiring, the installed skills. Prints nothing. +2. `assess`: turn the snapshot into one decision — the state, the single next action, and the screen to show. +3. `present`: render that screen and wait for your reply. +4. `run`: carry out the reply, then loop back to `scan`. -It scans four zones: AIDD context (memory, the `` block, architecture), context-gen artifacts (rules, agents, skills, hooks, commands), the dev flow (code, tests, spec or plan, PR), and health (bug markers, messy code). A check is met by a disk fact and flagged `⚠` on form drift. It never checks a plugin version against a registry. +## What it shows -## Run tiers +- **Your AIDD setup.** AI tools (detected from `.claude`, `.codex`, `.cursor`, `.opencode`, `.github` config), the installed plugins, and the memory bank — each with `✅` set, `⚠️` present-but-not-wired (carries a fix), or `❌` required-but-missing. Unused tools are simply omitted. +- **Foundations, state-aware.** An existing project starts with project memory (the stack already exists). A greenfield project designs the stack first. +- **The feature flow.** `brainstorm → spec* → plan → implement → assert → review → commit → PR`. Walk it one command at a time, or hand the whole thing to `aidd-dev:00-sdlc`. -Each recommended step is one of three: **AUTO** (spawn and run to completion), **GUIDED** (an interactive skill onboard launches and hands to you), or **MANUAL** (a side-effecting command it shows but never runs). `OK` walks all three in order, running AUTO steps, pausing at each GUIDED step for your input, and leaving MANUAL commands for you to run. +## Replies + +Reply with a bracketed key: a number `[1]` to run a step, `[OK]` to walk the pending steps, `[m]` for the flow map, `[?]` for detail, `recap`, `explain `, or `stop`. A step that launches an interactive skill tells you to re-run onboard to come back. ## Requires -Only the `aidd-context` plugin installed and enabled, and a working directory rooted in the target project. The `aidd_docs/` memory bank is **not** required: on a project without it, the first recommendation is to set it up. Onboard is the entry point, so it works before anything else exists. +Only the `aidd-context` plugin installed and enabled, and a working directory in the target project. The memory bank is not required — on a project without it, the first step is to set it up. Onboard is the entry point, so it works before anything else exists. ## Details -See [`SKILL.md`](SKILL.md) for the action contract and [`actions/`](actions/) for the four actions. The references live under [`references/`](references/) (state, order, run, and the flow curriculum); the render shape is [`assets/report.md`](assets/report.md). +See [`SKILL.md`](SKILL.md) for the router and [`actions/`](actions/) for the four actions. The references live under [`references/`](references/) (`state/`, `order/`, `run/`, and the flow curriculum); the screen shapes are [`assets/report.md`](assets/report.md) with the banner in [`assets/banner.txt`](assets/banner.txt). diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 4f211b1e..9d26b46f 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -6,34 +6,20 @@ argument-hint: scan | assess | present | run # Onboard -Scans the current project against the AIDD framework, tells the user in plain words where it stands, points to the single clearest next action, and runs it on request. +scan → assess → present → run ↺ ## Actions -| # | Action | Role | Input | -| --- | -------- | ---------------------------------------------------------------------------------------- | ---------------- | -| 01 | `scan` | Read the project once, silently, into a snapshot: every check in `checks.md`, status per zone | project root | -| 02 | `report` | Lead with one plain state sentence and one recommended action a first-timer can act on, dashboard demoted | the 01 snapshot | -| 03 | `run` | Run the user's pick per its tier, `OK` walks the pending steps pausing at each interactive one, then re-scan | the user's reply | - -Run `01 → 02 → 03`, then loop back to `01` after each run until the user stops. Run each action's `## Test` before the next. Before running an action, read its file in `actions/`, not only the table or assets. - -## References - -- `references/checks.md`: the diagnostic catalogue, four zones ordered, each check with its met rule, drift rule, deliverable, command, and run tier. -- `references/run-tiers.md`: the AUTO, GUIDED, and MANUAL run tiers, how `OK` chains them, the loop, and explain-on-demand. - -## Assets - -- `assets/report.md`: the report shape action 02 renders. +| # | Action | Does | +| -- | ------- | --------------------------------------------- | +| 01 | scan | reads project state into a snapshot | +| 02 | assess | picks the state, the next action, and the screen | +| 03 | present | renders the screen, waits for a reply | +| 04 | run | runs the reply, then loops to scan | ## Transversal rules -- Guide, do not lecture or dump. Lead with where the project stands and the single clearest next action, and keep the rest on demand. The render shape is `assets/report.md`. -- Name real commands only. Never name a command whose skill `01` did not find installed; name a missing one as a gap by function. +- Guide, do not lecture or dump. Lead with where the project stands and the single clearest next action; keep the rest on demand. +- Name real commands only. A command whose skill `01` did not find installed is a gap named by function, never invented. - Never run a GUIDED step unattended, and never test a plugin version against a registry. - Re-scan after a run, never trust a stale status. Wait for an explicit reply before running anything. - -## External data - -- `../02-project-memory/references/memory-block.md`: the canonical `` block shape the form-drift check compares against. From 1952d5d231f4ce7948b9835d0f2552df86b96b0b Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 06:08:04 +0200 Subject: [PATCH 11/44] chore(aidd-context): mark onboard tutorial rebuild implemented All five phases done, link check green. Co-Authored-By: Claude Opus 4.8 --- .../tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md index fc4968b1..204cc9a3 100644 --- a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/plan.md @@ -1,6 +1,6 @@ --- objective: "onboard is rebuilt as a token-optimized guided tutorial over a granular, conditional-load file tree that teaches the AIDD flow, every current behavior preserved, and the skill-authoring contract updated to sanction the new structure." -status: in-progress +status: implemented --- From 30f66f3328af403cd78b8aed457381b517c89c2c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 06:16:09 +0200 Subject: [PATCH 12/44] fix(aidd-context): resolve onboard review findings Single-home the glyph semantics (state refs describe status in words; display legend stays in report.md), split disk-detectable dev-flow pins from inferred ones in zones.md, and point report.md's tier clause to run/tiers.md instead of restating it. review.md verdict now approve. Co-Authored-By: Claude Opus 4.8 --- .../review.md | 61 +++++++++++++++++++ .../skills/00-onboard/assets/report.md | 2 +- .../00-onboard/references/state/detection.md | 13 ++-- .../00-onboard/references/state/zones.md | 10 +-- 4 files changed, 71 insertions(+), 15 deletions(-) create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/review.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/review.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/review.md new file mode 100644 index 00000000..354696ae --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/review.md @@ -0,0 +1,61 @@ +# Review: Onboard tutorial rebuild + +- **Verdict**: approve +- **Diff**: `eee269d...HEAD` +- **Axes run**: code, functional, relevancy +- **Date**: 2026_07_09 +- **Findings**: 0 critical, 0 warning, 0 minor (review-round findings resolved below) + +## Phases + +### Phase 1 — Update the skill-authoring contract + +- [x] R3 permits `references//file.md` and still bans ref→ref `@`-chains — `skill-authoring.md:9` +- [x] Contract names telegraphic-notation and mermaid-only-for-branching — `skill-authoring.md:28` (R14) +- [x] Router format specified (tiny title, arrow/pick-one schema, verb-led Does, no intro/Input, official frontmatter only) — `skill-authoring.md:50` +- [x] No rule contradicts nesting; R13 covers nested `@` — `skill-authoring.md:26` + +### Phase 2 — Scan action + state refs + +- [x] Each `state/*.md` one concern, no ref→ref `@`-chain — `references/state/` +- [x] Snapshot carries per-tool `✓/⚠`, unused tools absent — `01-scan.md:19`, `state/detection.md` +- [x] Plan `in-progress` pins Implement-alone; repo-wide PR on another branch sets no pin — `state/hedge.md`, `state/zones.md:14` +- [x] Ledger-recorded step absent next scan — `state/done-rule.md`, `01-scan.md:16` + +### Phase 3 — Assess + run actions + +- [x] `02-assess` outputs a decision, renders nothing; `screen-map.md` is mermaid — `actions/02-assess.md`, `order/screen-map.md` +- [x] Ranking holds dev-flow/health/idle while a foundation unmet; umbrella pick re-renders — `order/ranking.md`, `order/idle-menu.md` +- [x] `?`/`back` re-render via present, no re-scan/assess — `run/replies.md`, `04-run.md` +- [x] GUIDED handoff emits the return line — `run/return.md`, `04-run.md:14` + +### Phase 4 — Present action + +- [x] `flow.md` lists 8 steps with what/why, both layouts, both foundation paths — `references/flow.md` +- [x] `⚠️` renders cause + keyed fix; framing first report only — `assets/report.md:38`, `03-present.md` +- [x] Existing repo memory step 1 of 2; greenfield stack first — `flow.md`, `order/screen-map.md` +- [x] Banner on entry screens only; warning screen no `flow.md` — `03-present.md:11` + +### Phase 5 — Router, description, docs, budget + +- [x] SKILL.md pure router in the new format; description leads "onboard me" — `SKILL.md` (66 tok, at the ~65 target) +- [x] README describes the tutorial, no token rule for itself — `README.md` +- [x] Measured total recorded with delta; link check zero broken — commit `963c661` + +## Findings + +| Sev | Kind | Phase | Location | Issue | Outcome | +| --- | ---- | ----- | -------- | ----- | ------- | +| 🟡 | conform | 4 | `state/detection.md`, `state/zones.md`, `assets/report.md` | Glyph semantics defined three times in two vocabularies; breaks R6 one-home | fixed — state refs describe status in words; the display glyph legend single-homed in `report.md` | +| 🟡 | fit | 2 | `state/zones.md` | Dev-flow stages `brainstorm`/`assert`/`commit` have no cheap disk signal, yet presented as detectable | fixed — `zones.md` splits disk-detectable from inferred pins | +| 🟢 | rot | 3 | `run/tiers.md`, `assets/report.md` | Tier→clause mapping duplicated | fixed — `report.md` points to `run/tiers.md` | +| 🟢 | code | 4 | `assets/report.md` | where-you-are screen uses `🔍`/`Flow:` | no_change_needed — matches the approved mockup (state screens use `🔍`, welcome uses `👋` by design) | + +## Verification + +| Metric | Value | +| ------------- | ---------------------------------------------------------------------------- | +| Verified | 100% (17/17) | +| Files checked | SKILL.md, README.md, actions/*, references/state/*, references/order/*, references/run/*, references/flow.md, assets/report.md, assets/banner.txt, skill-authoring.md | +| Unchecked | none (description at 66 tok is within the `~65` target, not-applicable) | +| Unplanned | CATALOG.md regenerated by the summarize-plugin-catalogs hook (expected); parasitic `aidd_docs/plans` deletions restored, not in any commit | diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index eb9eae72..b6a29dd6 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -3,7 +3,7 @@ ## Entry screen (greenfield · existing · idle · drift) diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index daa00269..ee025f42 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -14,13 +14,8 @@ ## Wiring status per detected tool -Wired = the tool's own context file carries the `` block on canonical shape (claude => `CLAUDE.md`, codex => `AGENTS.md`, cursor => `.cursor/rules/`, and so on per tool). +Wired = the tool's own context file carries the `` block on canonical shape (claude => `CLAUDE.md`, codex => `AGENTS.md`, cursor => `.cursor/rules/`, and so on per tool). Each detected tool is either **wired** or **used, not wired**. The render maps that to a glyph (legend in `assets/report.md`). -| Glyph | Means | -| ----- | --------------------------- | -| `✓` | used AND memory wired | -| `⚠` | used, memory not wired | - -- Render a **detected** tool only. An unused optional tool is omitted, never crossed with `✗`. -- A `⚠` always carries its cause and fix in the render, e.g. "codex installed, no `AGENTS.md` block => wire it". -- `✗` belongs to a required foundation that is missing (memory absent), not to a tool row. See `zones.md`. +- Render a **detected** tool only. An unused optional tool is omitted, never crossed. +- A not-wired tool always carries its cause and fix in the render, e.g. "codex installed, no `AGENTS.md` block => wire it". +- A missing required foundation (memory absent) is a foundation status, not a tool row. See `zones.md`. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md index 108c3dff..1c75c22b 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/zones.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -1,18 +1,18 @@ # State zones -Disk/VCS checks that place the project. `01-scan` reads this. Glyphs: `✓` met · `⚠` drift · `✗` missing. +Disk/VCS checks that place the project. `01-scan` reads this. Each check is met, drift (present but off canonical shape), or missing. The render maps those to glyphs; the display legend lives in `assets/report.md`. ## Foundations State-aware order: existing repo (code present) => memory first, bootstrap skipped. Greenfield empty => stack, then memory, then wire. -| Check | Met `✓` | Drift `⚠` | Deliverable | Command | +| Check | Met when | Drift when | Deliverable | Command | | ------------- | -------------------------------------------------------------- | ---------------------------------- | ------------------------- | -------------------------------- | | tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | | project memory| `aidd_docs/memory/` has real content | files empty or placeholder | project knowledge saved | `aidd-context:02-project-memory` | | memory wiring | `` block on canonical shape in each used tool's context file | block present but off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | -- tech stack is `✗` only on a truly greenfield repo (no code AND no synced memory). Established => `✓`, never bootstrap. +- tech stack is missing only on a truly greenfield repo (no code AND no synced memory). Established => met, never bootstrap. - memory wiring: an absent block or no context file is `✗`, not `⚠`. `01-scan` loads the canonical block shape to judge drift. ## Dev flow @@ -34,8 +34,8 @@ brainstorm → spec* → plan → implement → assert → review → commit → | commit | reviewed, uncommitted or unpushed | | PR | current branch has an open PR | -- `review` and `PR` read cheap VCS state, **current branch only**: the PR whose head is this branch. Ignore repo-wide open PRs and review queues — another branch's PR is another dev's work, never the pin. -- `brainstorm` and `spec` have no hard disk signal; they are the pin only when no downstream artifact exists. +- Disk/VCS-detectable pins: `spec`, `plan`, `implement`, `review`, `PR`. `review` and `PR` read cheap VCS state, **current branch only**: the PR whose head is this branch. Ignore repo-wide open PRs and review queues — another branch's PR is another dev's work, never the pin. +- Inferred pins, no cheap signal: `brainstorm`, `assert`, `commit`. Do not disk-pin them. `brainstorm` is the pin only when no downstream artifact exists; `assert` and `commit` are placed by the plan-status hedge and the cumulative state, not detected directly. - The plan's `status:` refines the pin: see `hedge.md`. ## Health From 3d1203c599de22463f3878f5560ea3e84e690049 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 06:57:23 +0200 Subject: [PATCH 13/44] refactor(aidd-context): compress onboard references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cut flow.md duplication (the step table was repeated as a vertical code block; present renders the table now): 562 → 324 tok. Telegraph the prose notes and drop the duplicated flow map in zones.md (769 → 649), and tighten idle-menu, detection, tiers. No condition lost. References corpus 3211 → 2678; model-loaded total 5921 → 5255 (-11% vs the noob-first checkpoint). Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/references/flow.md | 73 +++++-------------- .../00-onboard/references/order/idle-menu.md | 18 ++--- .../skills/00-onboard/references/run/tiers.md | 4 +- .../00-onboard/references/state/detection.md | 8 +- .../00-onboard/references/state/zones.md | 60 +++++++-------- 5 files changed, 62 insertions(+), 101 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md index b420ca73..fc63e4c6 100644 --- a/plugins/aidd-context/skills/00-onboard/references/flow.md +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -1,64 +1,29 @@ -# The AIDD flow curriculum +# AIDD flow curriculum -`03-present` loads this on a flow or walk screen. It teaches the feature flow and the two foundation paths. It is also the source of the `[map]` view. +`03-present` loads this on a flow or walk screen. Source of the `[map]` view. -## Foundations, two paths +## Foundations (state-aware) -The order is state-aware. +- Existing (code present): memory first, stack skipped. `project memory` → `connect to the AI`. +- Greenfield (empty): `design tech stack` → `project memory` → `connect to the AI`. -- **Existing project** (code present) — memory first, the stack is skipped: - 1. `project memory` — scan the existing code into a memory bank the AI reads. - 2. `connect it to the AI` — wire the memory into each used tool's context file. -- **Greenfield** (empty repo) — stack first: - 1. `design tech stack` — pick the technologies and architecture. - 2. `project memory` — record what the project is. - 3. `connect it to the AI` — wire the memory in. +## Feature flow — 8 steps (`spec` optional) -## Feature flow, the eight steps +`03-present` renders this table as the vertical annotated screen; the `[map]` is the compact line below. -Each step, one line of what and why. `spec` is optional. +| Step | What | Why | +| ------------ | --------------------------- | ------------------------------ | +| brainstorm | vague idea → precise | fuzzy idea makes every step guess | +| spec* | the contract of what to build | one agreed definition, no drift | +| plan | break into phases | small units that ship + verify | +| implement | build phase by phase | verified phases beat one leap | +| assert | check it behaves | catch breakage before review | +| review | verdict before shipping | ship or iterate, decided | +| commit | save the work | atomic, reversible record | +| pull request | ship it | open for merge | -| Step | What | Why | -| ------------ | ---------------------------------------- | --------------------------------------- | -| brainstorm | turn a vague idea into something precise | a fuzzy idea makes every next step guess | -| spec* | write the contract of what to build | one agreed definition, no drift | -| plan | break it into phases | small units that ship and verify | -| implement | build it, phase by phase | verified phases beat one big leap | -| assert | check it behaves | catch breakage before review | -| review | a verdict before shipping | ship or iterate, decided | -| commit | save the work | an atomic, reversible record | -| pull request | ship it | open it for merge | - -## Layouts - -**Vertical, annotated** — the tutorial screen: - -```txt - brainstorm turn a vague idea into something precise - │ - spec the contract of what to build (optional) - │ - plan break it into phases - │ - implement build it, phase by phase - │ - assert check it behaves - │ - review verdict before shipping - │ - commit save the work - │ - pull request ship it -``` - -**Horizontal, compact** — the `[map]` view: - -```txt -brainstorm → spec* → plan → implement → assert → review → commit → PR -(* optional) -``` +`[map]`: `brainstorm → spec* → plan → implement → assert → review → commit → PR` ## Run it -- `[1]` walk it with me — one step at a time, each explained. -- `[2]` let `aidd-dev:00-sdlc` drive the whole flow from one request. +`[1]` walk with me, step by step · `[2]` hand the whole flow to `aidd-dev:00-sdlc` diff --git a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md index 7f07bd7f..57d4bddf 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md @@ -1,14 +1,14 @@ # Idle menu -When ranks 1-3 are clear, `02-assess` offers three umbrellas plus explore. +Ranks 1-3 clear => `02-assess` offers three umbrellas plus explore. -| Slot | Umbrella | Opens (installed members) | -| ---- | ------------------- | ----------------------------------------------------------------------------------------- | -| 1 | start new work | `aidd-dev:00-sdlc` (or `aidd-pm:04-spec`) — a feature from idea to shipped | -| 2 | improve the project | `aidd-dev:04-audit` · `aidd-dev:06-test` · `aidd-dev:07-refactor` | -| 3 | customize the AI | the **missing** context-gen generators, each in plain words: a coding rule (`aidd-context:05-rule-generate`), a reusable workflow (`aidd-context:04-skill-generate`), a specialized assistant (`aidd-context:06-agent-generate`), a slash command (`aidd-context:07-command-generate`), an automated action (`aidd-context:08-hook-generate`) | -| ? | explore | `aidd-context:11-explore` and anything not in slots 1-3 | +| Slot | Umbrella | Opens (installed members) | +| ---- | ------------------- | -------------------------------------------------------------------- | +| 1 | start new work | `aidd-dev:00-sdlc` (or `aidd-pm:04-spec`) | +| 2 | improve the project | `aidd-dev:` `04-audit` · `06-test` · `07-refactor` | +| 3 | customize the AI | the **missing** `aidd-context:` generators: rule `05-rule-generate`, workflow `04-skill-generate`, agent `06-agent-generate`, command `07-command-generate`, hook `08-hook-generate` | +| ? | explore | `aidd-context:11-explore` + anything not in 1-3 | -- Slots 2 and 3 are umbrellas: a pick re-renders the installed member sub-list; a member pick runs it. Slot 1 runs directly. -- Surface an installed member only; drop an umbrella with no member. +- Slots 2-3 are umbrellas: a pick re-renders the member sub-list, a member pick runs. Slot 1 runs directly. +- Installed members only; drop an empty umbrella. - Choices, not a chain: `OK` never walks the idle menu. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md index 99888d4a..901b9e41 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md @@ -9,5 +9,5 @@ How `04-run` carries out a step. The tier is a default, overridable. | MANUAL | side-effecting, outward | show the command, run nothing, leave it for the user | - Rendered as a plain clause, never a glyph: AUTO `(runs on its own)`, GUIDED `(it will ask you a few questions)`, MANUAL `(you run this one yourself)`. -- The tier is the step's default. A skill that runs either way (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`) runs the other way when the user asks and the skill supports it. -- The `OK` walk: AUTO runs to completion, GUIDED pauses for input then resumes, MANUAL is shown and left. State up front how many steps it covers and which need input. +- The tier is a default. A dual-mode skill (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`) runs the other way when the user asks and the skill supports it. +- `OK` walk: AUTO to completion, GUIDED pauses then resumes, MANUAL shown and left. State up front how many steps and which need input. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index ee025f42..dd68960d 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -14,8 +14,8 @@ ## Wiring status per detected tool -Wired = the tool's own context file carries the `` block on canonical shape (claude => `CLAUDE.md`, codex => `AGENTS.md`, cursor => `.cursor/rules/`, and so on per tool). Each detected tool is either **wired** or **used, not wired**. The render maps that to a glyph (legend in `assets/report.md`). +Wired = the tool's context file carries the `` block on canonical shape (claude `CLAUDE.md`, codex `AGENTS.md`, cursor `.cursor/rules/`, ...). A detected tool is **wired** or **used, not wired**; the render maps that to a glyph (legend in `assets/report.md`). -- Render a **detected** tool only. An unused optional tool is omitted, never crossed. -- A not-wired tool always carries its cause and fix in the render, e.g. "codex installed, no `AGENTS.md` block => wire it". -- A missing required foundation (memory absent) is a foundation status, not a tool row. See `zones.md`. +- Detected tools only; an unused optional tool is omitted, never crossed. +- A not-wired tool carries its cause + fix in the render, e.g. "codex, no `AGENTS.md` => wire it". +- Missing memory is a foundation status, not a tool row (see `zones.md`). diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md index 1c75c22b..1d3f6771 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/zones.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -1,49 +1,45 @@ # State zones -Disk/VCS checks that place the project. `01-scan` reads this. Each check is met, drift (present but off canonical shape), or missing. The render maps those to glyphs; the display legend lives in `assets/report.md`. +Disk/VCS checks that place the project. `01-scan` reads this. Each check is met, drift (present, off canonical shape), or missing. Render glyphs: see `assets/report.md`. ## Foundations -State-aware order: existing repo (code present) => memory first, bootstrap skipped. Greenfield empty => stack, then memory, then wire. +State-aware order: existing repo (code) => memory first, stack skipped. Greenfield empty => stack → memory → wire. -| Check | Met when | Drift when | Deliverable | Command | -| ------------- | -------------------------------------------------------------- | ---------------------------------- | ------------------------- | -------------------------------- | -| tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | -| project memory| `aidd_docs/memory/` has real content | files empty or placeholder | project knowledge saved | `aidd-context:02-project-memory` | -| memory wiring | `` block on canonical shape in each used tool's context file | block present but off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | +| Check | Met when | Drift when | Deliverable | Command | +| -------------- | ------------------------------------------------------------- | ----------------------- | ------------------------- | -------------------------------- | +| tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | +| project memory | `aidd_docs/memory/` has real content | files empty/placeholder | project knowledge saved | `aidd-context:02-project-memory` | +| memory wiring | `` block on canonical shape in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | -- tech stack is missing only on a truly greenfield repo (no code AND no synced memory). Established => met, never bootstrap. -- memory wiring: an absent block or no context file is `✗`, not `⚠`. `01-scan` loads the canonical block shape to judge drift. +- tech stack missing only on greenfield (no code AND no synced memory); established = met, never bootstrap. +- memory wiring: absent block or no context file = missing, not drift. `01-scan` loads the canonical shape to judge drift. ## Dev flow -The official feature flow, cumulative: a downstream artifact implies the upstream stages are met. +Cumulative: a downstream artifact implies the upstream stages met. -```txt -brainstorm → spec* → plan → implement → assert → review → commit → PR (spec optional) -``` +| Stage | Pin sits here when | +| ---------- | ------------------------------------------- | +| brainstorm | no spec/plan/code (idea only) | +| spec | spec under `aidd_docs/`, nothing downstream | +| plan | `plan.md`, no code against it | +| implement | code against the plan | +| assert | code done, assertions not green | +| review | code done, current branch PR awaits review | +| commit | reviewed, uncommitted/unpushed | +| PR | current branch has an open PR | -| Stage | The pin sits here when | -| ---------- | -------------------------------------------------- | -| brainstorm | no spec, plan, or code yet (idea only) | -| spec | a spec under `aidd_docs/`, nothing downstream | -| plan | a `plan.md` under `aidd_docs/`, no code against it | -| implement | code present against the plan | -| assert | code done, coding assertions not yet green | -| review | code done, current branch's PR awaits review | -| commit | reviewed, uncommitted or unpushed | -| PR | current branch has an open PR | - -- Disk/VCS-detectable pins: `spec`, `plan`, `implement`, `review`, `PR`. `review` and `PR` read cheap VCS state, **current branch only**: the PR whose head is this branch. Ignore repo-wide open PRs and review queues — another branch's PR is another dev's work, never the pin. -- Inferred pins, no cheap signal: `brainstorm`, `assert`, `commit`. Do not disk-pin them. `brainstorm` is the pin only when no downstream artifact exists; `assert` and `commit` are placed by the plan-status hedge and the cumulative state, not detected directly. -- The plan's `status:` refines the pin: see `hedge.md`. +- Disk/VCS-detectable: `spec`, `plan`, `implement`, `review`, `PR`. `review`/`PR` read VCS **current branch only** — ignore repo-wide PRs and review queues (another branch = another dev, never the pin). +- Inferred, no cheap signal: `brainstorm`, `assert`, `commit`. Placed by the hedge + cumulative state, not disk-pinned. +- Plan `status:` refines the pin: see `hedge.md`. ## Health -Beside-the-flow tools, surfaced only when their signal fires. Scan project source only; exclude templates, fixtures, examples, generated output, and any installed-plugin tree. +Beside-the-flow tools, surfaced only when their signal fires. Scan project source only; exclude templates, fixtures, examples, generated output, installed-plugin trees. -| Signal | Fires when | Command | -| ----------- | ----------------------------------------- | ------------------- | -| no tests | no real test files | `aidd-dev:06-test` | +| Signal | Fires when | Command | +| ----------- | ------------------------------------------- | ------------------- | +| no tests | no real test files | `aidd-dev:06-test` | | bug markers | `TODO`/`FIXME` or reported errors in source | `aidd-dev:08-debug` | -| messy code | a file far longer or deeper than siblings | `aidd-dev:04-audit` | +| messy code | a file far longer/deeper than siblings | `aidd-dev:04-audit` | From 944ab242ce3f375a7050b02fcb18e82cc0109e97 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Thu, 9 Jul 2026 11:55:36 +0200 Subject: [PATCH 14/44] fix(aidd-context): resolve checker findings on onboard Add the mandatory ## Output section to 04-run (R8 action anatomy; the other three actions had it). Stop the README from restating the glyph legend that report.md single-homes (describe status in words). Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/README.md | 4 ++-- plugins/aidd-context/skills/00-onboard/actions/04-run.md | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md index f36e032d..7cd5fc28 100644 --- a/plugins/aidd-context/skills/00-onboard/README.md +++ b/plugins/aidd-context/skills/00-onboard/README.md @@ -23,11 +23,11 @@ Four actions in a loop: `scan → assess → present → run ↺`. 1. `scan`: silently read the project into a snapshot — the checks, the detected AI tools and their wiring, the installed skills. Prints nothing. 2. `assess`: turn the snapshot into one decision — the state, the single next action, and the screen to show. 3. `present`: render that screen and wait for your reply. -4. `run`: carry out the reply, then loop back to `scan`. +4. `run`: carry out the reply. A run or handoff re-scans and loops; a read-only reply (`?`, `back`, `recap`, `explain`) reuses the snapshot; `stop` ends. ## What it shows -- **Your AIDD setup.** AI tools (detected from `.claude`, `.codex`, `.cursor`, `.opencode`, `.github` config), the installed plugins, and the memory bank — each with `✅` set, `⚠️` present-but-not-wired (carries a fix), or `❌` required-but-missing. Unused tools are simply omitted. +- **Your AIDD setup.** AI tools (detected from `.claude`, `.codex`, `.cursor`, `.opencode`, `.github` config), the installed plugins, and the memory bank — each shown as set, present-but-not-wired (with its fix), or required-but-missing. Unused tools are simply omitted. - **Foundations, state-aware.** An existing project starts with project memory (the stack already exists). A greenfield project designs the stack first. - **The feature flow.** `brainstorm → spec* → plan → implement → assert → review → commit → PR`. Walk it one command at a time, or hand the whole thing to `aidd-dev:00-sdlc`. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 03a54eb9..abe1409a 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -7,6 +7,10 @@ Carry out the user's reply, then loop back to scanning. - The reply from `03-present`: a number, `OK`, `?`, `back`, `recap`, `explain`, `skip`, or `stop`. - The decision from `02-assess`: the resolved commands, or a gap when no installed skill fits. +## Output + +The reply carried out: the step run (or a MANUAL step shown and left), the session ledger updated, and a re-scan (`→ 01`) unless the reply was read-only or an umbrella pick. + ## Process 1. **Route.** Carry out the reply per `@../references/run/replies.md`. From 478c52b48d4bda50b302ab392fff80f61e0789cc Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:11:30 +0200 Subject: [PATCH 15/44] refactor(aidd-context): tighter onboard description Lead with 'Guide a project through AIDD' instead of the awkward 'onboard onto an AIDD project'; drop near-duplicate triggers. 66 -> 49 always-on tokens. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- plugins/aidd-context/skills/00-onboard/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index bb487d2c..7654846c 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -52,7 +52,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [report.md](skills/00-onboard/assets/report.md) | - | | `-` | [README.md](skills/00-onboard/README.md) | - | | `references` | [flow.md](skills/00-onboard/references/flow.md) | - | -| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface.` | +| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Guide a project through AIDD, scanning what is set up and missing, then pointing to the single next action. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface.` | #### `skills/01-bootstrap` diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 9d26b46f..8318ae95 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,6 +1,6 @@ --- name: 00-onboard -description: Onboard onto an AIDD project by scanning what is set up and missing, then guiding the single next action to run. Use when the user says onboard me, onboard this project, get me started, where do I start, what should I do next, or how does this project stand. Not for listing every installed surface. +description: Guide a project through AIDD, scanning what is set up and missing, then pointing to the single next action. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. argument-hint: scan | assess | present | run --- From 01836be593554db975db7badd9bb0cc5781278df Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:13:48 +0200 Subject: [PATCH 16/44] refactor(aidd-context): onboard description frames the journey Describe the journey (first setup to shipping a feature) rather than restating the scan/assess mechanism the actions already own. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- plugins/aidd-context/skills/00-onboard/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 7654846c..b042936f 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -52,7 +52,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [report.md](skills/00-onboard/assets/report.md) | - | | `-` | [README.md](skills/00-onboard/README.md) | - | | `references` | [flow.md](skills/00-onboard/references/flow.md) | - | -| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Guide a project through AIDD, scanning what is set up and missing, then pointing to the single next action. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface.` | +| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface.` | #### `skills/01-bootstrap` diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 8318ae95..04f3bc1f 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,6 +1,6 @@ --- name: 00-onboard -description: Guide a project through AIDD, scanning what is set up and missing, then pointing to the single next action. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. argument-hint: scan | assess | present | run --- From 79afe2e219e0b0795cd4ad521e2407a967a46d78 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:17:07 +0200 Subject: [PATCH 17/44] =?UTF-8?q?refactor(aidd-context):=20router=20loop?= =?UTF-8?q?=20as=20an=20explicit=20mermaid,=20not=20the=20ambiguous=20?= =?UTF-8?q?=E2=86=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'scan → assess → present → run ↺' glyph is ambiguous about where the loop returns. Show the cycle as a mermaid flowchart so the LLM reads the run → scan edge unambiguously. Update the contract: a pipeline schema is arrows for a straight run or a mermaid when the flow loops (a cycle is not linear, so R14 permits it). Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/SKILL.md | 5 ++++- .../skills/04-skill-generate/references/skill-authoring.md | 4 ++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 04f3bc1f..1c6429cb 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -6,7 +6,10 @@ argument-hint: scan | assess | present | run # Onboard -scan → assess → present → run ↺ +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` ## Actions diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index 8cf9a5f9..515e77ee 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -24,7 +24,7 @@ The contract every generated skill must satisfy. These rules govern the CLIENT s - **R11.** One idea per sentence. Split a sentence that runs past one line. Exceptions: the single-line `description` and table rows. - **R12.** One file = one artifact. A reference or asset holds a single coherent thing: one checklist, one template, one criteria set. When a file accumulates several independently reusable artifacts, split them so each is cited and reused alone. Prefer this split over bundling, even when the combined file is short. - **R13.** Includes are explicit and scoped. An **import** (content pulled into context) is cited with its `@` alone inside a fenced ``` block. A **pointer** (read-this-reference in a step) may cite `@` inline in prose. Either uses the reference's full path, including a nested `references//file.md`. Naming: a global include (imported from SKILL.md, used skill-wide) takes no prefix; an include used by only one action is prefixed with that action's slug (e.g. `research-checklist.md`). SKILL.md lists only the global includes; an action-specific include is cited only from its own action. -- **R14.** Bodies use telegraphic notation: tables, `→` for a linear chain, fragments over sentences, no filler. Never at the cost of a load-bearing condition. A branch, edge case, or if/then stays precise. Use a Mermaid diagram only for branching logic, never for a linear chain. +- **R14.** Bodies use telegraphic notation: tables, `→` for a linear chain, fragments over sentences, no filler. Never at the cost of a load-bearing condition. A branch, edge case, or if/then stays precise. Use a Mermaid diagram for branching or looping logic, never for a straight linear chain. ## Action anatomy @@ -51,7 +51,7 @@ The router: YAML frontmatter + markdown body. - A manual-only flag makes the skill user-only. The exact frontmatter key is per tool. - Frontmatter carries official keys only (`name`, `description`, `argument-hint`, the host manual-only flag). Never invent a flag the model must interpret; the body carries mode, not a made-up key. - Body order: a tiny `# Title`, the chaining schema, the action table, then the transversal rules. No restated intro sentence; the `description` already states the what. - - **Chaining schema.** A pipeline shows a one-line arrow schema, `a → b → c ↺` (`↺` marks a loop back). A menu shows the line `Pick one per request.` and no schema. The mode reads itself; no field states it. + - **Chaining schema.** A pipeline shows its chain: a one-line arrow schema `a → b → c` for a straight run, or a small Mermaid flowchart when the flow loops back (a cycle is not a linear chain, so R14 permits Mermaid here). A menu shows the line `Pick one per request.` and no schema. The mode reads itself; no field states it. - **Action table.** Columns `# | Action | Does`; `Does` is verb-led and telegraphic (verb + object). A menu drops the `#` column. No `Input` column: an action's input lives in its own `## Input`. - Standing rule for every skill: read an action's file just before running it, not only the router table. Stated here once, never repeated in a SKILL.md body. From a87df55d18ed738fd0d12983f6fa1a5931c1b5cd Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:27:08 +0200 Subject: [PATCH 18/44] refactor(aidd-context): terser onboard action table Verb + object per action (read the project / decide the next step / show the screen / act on the reply); the action files carry the detail. Includes the reviewed transversal rules. Co-Authored-By: Claude Opus 4.8 --- .../aidd-context/skills/00-onboard/SKILL.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 1c6429cb..e72ece8b 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -13,16 +13,18 @@ flowchart LR ## Actions -| # | Action | Does | -| -- | ------- | --------------------------------------------- | -| 01 | scan | reads project state into a snapshot | -| 02 | assess | picks the state, the next action, and the screen | -| 03 | present | renders the screen, waits for a reply | -| 04 | run | runs the reply, then loops to scan | +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | ## Transversal rules -- Guide, do not lecture or dump. Lead with where the project stands and the single clearest next action; keep the rest on demand. -- Name real commands only. A command whose skill `01` did not find installed is a gap named by function, never invented. -- Never run a GUIDED step unattended, and never test a plugin version against a registry. -- Re-scan after a run, never trust a stale status. Wait for an explicit reply before running anything. +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. From 0c74e05bd4c94eedc7a5967012c489c48fc4330a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:31:55 +0200 Subject: [PATCH 19/44] refactor(aidd-context): lean onboard action files Trim each action to essentials: a rule-free title line, a one-line Output, one-line Process steps (detail lives in the refs, cases as sub-bullets), and challenged one-sentence Test points. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/actions/01-scan.md | 27 +++++++++---------- .../skills/00-onboard/actions/02-assess.md | 22 +++++++-------- .../skills/00-onboard/actions/03-present.md | 24 +++++++++-------- .../skills/00-onboard/actions/04-run.md | 20 +++++++------- 4 files changed, 47 insertions(+), 46 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index dc0f1ba2..3c14e44b 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -1,33 +1,32 @@ # 01 - Scan -Read the project once, silently, into a snapshot. No questions, no writes, no visible output. +Read the project into a snapshot. ## Input -The project root, the current working directory. +The project root. ## Output -A silent snapshot, never printed: the status (`✓ ⚠ ✗`) of every check in `@../references/state/zones.md`, the detected AI tools each with its wiring glyph, the installed AIDD plugins and skills each with its description, and the project name and purpose from the brief when memory is synced. +One silent snapshot: check statuses, detected AI tools with wiring, installed skills, and the project brief when memory is synced. ## Process -1. **Zones.** Evaluate every check in `@../references/state/zones.md` by its met and drift rules. Scope each to the paths the row names, never an installed-plugin tree. Read VCS state for the current branch only. -2. **Detect.** Resolve the AI-tool roots and per-tool wiring per `@../references/state/detection.md`. -3. **Ledger.** Apply the Done rule in `@../references/state/done-rule.md`: a step the session ledger recorded run or left drops out even when disk cannot prove it. Re-read the ledger every scan. -4. **Hedge.** Only when a plan exists, read its `status:` and pin the build-to-ship stage per `@../references/state/hedge.md`. -5. **Drift.** For memory wiring, compare each used tool's context block against the canonical shape. +1. **Zones.** Evaluate the checks per `@../references/state/zones.md`. +2. **Detect.** Resolve AI tools and wiring per `@../references/state/detection.md`. +3. **Ledger.** Drop done steps per `@../references/state/done-rule.md`. +4. **Hedge.** If a plan exists, pin the build-to-ship stage per `@../references/state/hedge.md`. +5. **Drift.** Judge memory wiring against the canonical block: ```md @../../02-project-memory/references/memory-block.md ``` -6. **List.** Gather the enabled AIDD plugins and skills, each with its description, via the tool's native discovery. -7. **Hold.** Keep the snapshot in context and hand to `02-assess`. Print nothing. Refresh disk and VCS facts only on change, not every loop. +6. **List.** Gather installed AIDD plugins and skills via native discovery. +7. **Hold.** Hand the snapshot to `02-assess`, printing nothing. ## Test -- Zero user-visible output: no snapshot, no checklist, no status appears. -- The snapshot carries a status for every check in `zones.md`, plus detected AI tools with a `✓`/`⚠` wiring glyph and unused tools absent. -- A step the session ledger recorded run or left is absent from the snapshot's actionable set. -- A repo-wide PR on another branch sets no pin; only the current branch's PR does. +- Scan prints nothing. +- The snapshot carries a status per check, the detected AI tools with wiring, and the installed skills. +- A ledgered step and a cross-branch PR never enter the snapshot's actionable set. diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md index cd996d6c..b6e643cc 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -1,25 +1,25 @@ # 02 - Assess -Turn the scan snapshot into one decision: state class, ranked next action, chosen screen. Render nothing. +Turn the snapshot into one decision. ## Input -The snapshot from `01-scan`, held in context. +The snapshot from `01-scan`. ## Output -A decision handed to `03-present`: the state class, the top-ranked next action (or the idle menu), and the screen to render. Nothing is printed. +A decision for `03-present`: state class, top next action or idle menu, and the screen. ## Process -1. **Classify.** Map the snapshot to a state class per `@../references/order/screen-map.md`. -2. **Rank.** Pick the top next action per `@../references/order/ranking.md`. When idle, build the menu per `@../references/order/idle-menu.md`. -3. **Resolve.** Resolve each offered command against the installed skills from `01`; name a gap by function when the skill is absent, never invent one. -4. **Hand.** Pass the decision to `03-present`. Render nothing here. +1. **Classify.** State class per `@../references/order/screen-map.md`. +2. **Rank.** Top next action per `@../references/order/ranking.md`. + - Idle: build the menu per `@../references/order/idle-menu.md`. +3. **Resolve.** Match each command to an installed skill; an absent one is a gap by function. +4. **Hand.** Pass the decision to `03-present`. ## Test -- The action outputs a decision and renders nothing. -- Ranking holds the dev-flow, health, and idle steps back while a foundation is unmet. -- An idle decision names the three umbrellas plus explore, each umbrella carrying its installed members. -- No uninstalled command is named; an absent one is a gap by function. +- Assess renders nothing. +- Dev-flow, health, and idle stay back while a foundation is unmet. +- An idle decision offers the three umbrellas plus explore. diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 8fd1f49e..ddae21e2 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -1,25 +1,27 @@ # 03 - Present -Render the screen `02-assess` chose. Fill the shape, keep detail on demand. +Render the screen `02-assess` chose. ## Input -The decision from `02-assess`: the state class, the screen to render, and the ranked action or idle menu. +The decision from `02-assess`. ## Output -The rendered screen per `@../assets/report.md`, offered to the user. The reply goes to `04-run`. +The rendered screen per `@../assets/report.md`; the reply goes to `04-run`. ## Process -1. **Shape.** Fill the screen the decision names, from `@../assets/report.md`. -2. **Inject.** On an entry screen, inject the banner from `@../assets/banner.txt`. On a flow or walk screen, load `@../references/flow.md`. -3. **Warn.** Render every `⚠️` with its plain cause and a keyed fix; omit unused tools; command ids and tier clauses stay under `[?]`. -4. **Wait.** Offer the screen and wait for a reply. Never auto-advance. Hand the reply to `04-run`. +1. **Shape.** Fill the chosen screen from `@../assets/report.md`. +2. **Inject.** + - Entry screen: the banner from `@../assets/banner.txt`. + - Flow or walk screen: the curriculum from `@../references/flow.md`. +3. **Warn.** Render each `⚠️` with its cause and a keyed fix; ids and tier clauses stay under `[?]`. +4. **Wait.** Offer the screen, hand the reply to `04-run`. ## Test -- The framing line shows on the first report of the session only; a later re-scan drops it. -- An existing repo renders memory as foundation step 1 of 2; a greenfield renders the stack first. -- The banner appears on entry screens only; a warning-only screen loads no `flow.md`. -- Every `⚠️` names its cause and offers a keyed fix; no command id or tier clause appears outside `[?]`. +- The framing line shows on the first report of the session only. +- Existing repo renders memory as step 1 of 2; greenfield renders the stack first. +- The banner shows on entry screens only. +- Each `⚠️` carries a keyed fix; ids and tier clauses appear only under `[?]`. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index abe1409a..7541845c 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -1,28 +1,28 @@ # 04 - Run -Carry out the user's reply, then loop back to scanning. +Carry out the reply. ## Input - The reply from `03-present`: a number, `OK`, `?`, `back`, `recap`, `explain`, `skip`, or `stop`. -- The decision from `02-assess`: the resolved commands, or a gap when no installed skill fits. +- The decision from `02-assess`: the resolved commands, or a gap. ## Output -The reply carried out: the step run (or a MANUAL step shown and left), the session ledger updated, and a re-scan (`→ 01`) unless the reply was read-only or an umbrella pick. +The reply carried out and the ledger updated; a re-scan unless the reply was read-only. ## Process 1. **Route.** Carry out the reply per `@../references/run/replies.md`. -2. **Guard.** Run or name only skills `01` found installed. A gap invokes nothing: offer explain or stop. Never run a MANUAL step, only show it. -3. **Tier.** When running a step, apply `@../references/run/tiers.md`; the tier is a default, overridable when the skill supports the other mode. +2. **Guard.** Run only installed skills; a gap invokes nothing; a MANUAL step is shown, not run. +3. **Tier.** Running a step, apply `@../references/run/tiers.md`; the tier is a default, overridable. 4. **Return.** On a GUIDED handoff, emit the return line per `@../references/run/return.md`. -5. **Record.** Note each handled step in the session ledger per `@../references/state/done-rule.md`. -6. **Loop.** After a step or the `OK` walk runs, re-scan (`→ 01`). A read-only reply or an umbrella pick does not re-scan. +5. **Record.** Write the handled step to the ledger per `@../references/state/done-rule.md`. +6. **Loop.** After a run or `OK` walk, re-scan; a read-only reply or umbrella pick does not. ## Test -- `OK` walks the pending steps, runs AUTO unattended, and pauses at each GUIDED for input. +- `OK` runs AUTO unattended and pauses at each GUIDED. - A MANUAL step is shown, never run; a gap invokes nothing. -- `?`/`back` re-render via `03-present` with no re-scan and no re-assess. -- A GUIDED handoff emits the return line; the re-scan does not re-recommend the handed-off step. +- `?`/`back` re-render via `03-present` with no re-scan. +- A GUIDED handoff emits the return line. From 7eb8b2642d114ef015b07478c466653be5b15083 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:43:48 +0200 Subject: [PATCH 20/44] refactor(aidd-context): make onboard standalone Drop the cross-skill import of 02-project-memory's memory-block.md. Memory-wiring drift is judged in the Zones step against a self-contained rule in zones.md (the standard aidd_project_memory block that imports the memory files), so onboard no longer reaches into another skill's files. Co-Authored-By: Claude Opus 4.8 --- .../aidd-context/skills/00-onboard/actions/01-scan.md | 10 ++-------- .../skills/00-onboard/references/state/zones.md | 2 +- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index 3c14e44b..6ed8ebc1 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -16,14 +16,8 @@ One silent snapshot: check statuses, detected AI tools with wiring, installed sk 2. **Detect.** Resolve AI tools and wiring per `@../references/state/detection.md`. 3. **Ledger.** Drop done steps per `@../references/state/done-rule.md`. 4. **Hedge.** If a plan exists, pin the build-to-ship stage per `@../references/state/hedge.md`. -5. **Drift.** Judge memory wiring against the canonical block: - - ```md - @../../02-project-memory/references/memory-block.md - ``` - -6. **List.** Gather installed AIDD plugins and skills via native discovery. -7. **Hold.** Hand the snapshot to `02-assess`, printing nothing. +5. **List.** Gather installed AIDD plugins and skills via native discovery. +6. **Hold.** Hand the snapshot to `02-assess`, printing nothing. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md index 1d3f6771..b64f9d53 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/zones.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -13,7 +13,7 @@ State-aware order: existing repo (code) => memory first, stack skipped. Greenfie | memory wiring | `` block on canonical shape in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | - tech stack missing only on greenfield (no code AND no synced memory); established = met, never bootstrap. -- memory wiring: absent block or no context file = missing, not drift. `01-scan` loads the canonical shape to judge drift. +- memory wiring: absent block or no context file = missing (not drift); drift = the block is present but not the standard `` block that imports the memory files. ## Dev flow From 95e23eaaf02625c326f13d0d21b291666894a83a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 05:56:54 +0200 Subject: [PATCH 21/44] refactor(aidd-context): name action outputs, drop restated step, kill semicolons MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Output names the produced artifact (snapshot / decision / screen) instead of enumerating its contents with a colon. Drop 03-present's Warn step — report.md already owns the warning-and-fix rules that Shape applies. Split every semicolon run-on into sub-bullets or separate lines. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/actions/01-scan.md | 2 +- .../skills/00-onboard/actions/02-assess.md | 4 ++-- .../skills/00-onboard/actions/03-present.md | 10 +++++----- .../skills/00-onboard/actions/04-run.md | 14 +++++++++----- 4 files changed, 17 insertions(+), 13 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index 6ed8ebc1..cc8ee778 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -8,7 +8,7 @@ The project root. ## Output -One silent snapshot: check statuses, detected AI tools with wiring, installed skills, and the project brief when memory is synced. +The project snapshot, printed nowhere, for `02-assess`. ## Process diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md index b6e643cc..b83352f0 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -8,14 +8,14 @@ The snapshot from `01-scan`. ## Output -A decision for `03-present`: state class, top next action or idle menu, and the screen. +The decision for `03-present`. ## Process 1. **Classify.** State class per `@../references/order/screen-map.md`. 2. **Rank.** Top next action per `@../references/order/ranking.md`. - Idle: build the menu per `@../references/order/idle-menu.md`. -3. **Resolve.** Match each command to an installed skill; an absent one is a gap by function. +3. **Resolve.** Match each command to an installed skill, or name a gap by function when absent. 4. **Hand.** Pass the decision to `03-present`. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index ddae21e2..4e5fd16f 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -8,7 +8,7 @@ The decision from `02-assess`. ## Output -The rendered screen per `@../assets/report.md`; the reply goes to `04-run`. +The rendered screen, and the reply for `04-run`. ## Process @@ -16,12 +16,12 @@ The rendered screen per `@../assets/report.md`; the reply goes to `04-run`. 2. **Inject.** - Entry screen: the banner from `@../assets/banner.txt`. - Flow or walk screen: the curriculum from `@../references/flow.md`. -3. **Warn.** Render each `⚠️` with its cause and a keyed fix; ids and tier clauses stay under `[?]`. -4. **Wait.** Offer the screen, hand the reply to `04-run`. +3. **Wait.** Offer the screen, hand the reply to `04-run`. ## Test - The framing line shows on the first report of the session only. -- Existing repo renders memory as step 1 of 2; greenfield renders the stack first. +- An existing repo renders memory as step 1 of 2. +- A greenfield repo renders the stack first. - The banner shows on entry screens only. -- Each `⚠️` carries a keyed fix; ids and tier clauses appear only under `[?]`. +- Each `⚠️` carries a keyed fix, its id and tier clause only under `[?]`. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 7541845c..26887d38 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -9,20 +9,24 @@ Carry out the reply. ## Output -The reply carried out and the ledger updated; a re-scan unless the reply was read-only. +The reply carried out and the ledger updated, then a re-scan unless the reply was read-only. ## Process 1. **Route.** Carry out the reply per `@../references/run/replies.md`. -2. **Guard.** Run only installed skills; a gap invokes nothing; a MANUAL step is shown, not run. -3. **Tier.** Running a step, apply `@../references/run/tiers.md`; the tier is a default, overridable. +2. **Guard.** + - Run only installed skills. + - A gap invokes nothing. + - A MANUAL step is shown, not run. +3. **Tier.** Running a step, apply `@../references/run/tiers.md`. The tier is a default, overridable. 4. **Return.** On a GUIDED handoff, emit the return line per `@../references/run/return.md`. 5. **Record.** Write the handled step to the ledger per `@../references/state/done-rule.md`. -6. **Loop.** After a run or `OK` walk, re-scan; a read-only reply or umbrella pick does not. +6. **Loop.** After a run or `OK` walk, re-scan. A read-only reply or umbrella pick does not. ## Test - `OK` runs AUTO unattended and pauses at each GUIDED. -- A MANUAL step is shown, never run; a gap invokes nothing. +- A MANUAL step is shown, never run. +- A gap invokes nothing. - `?`/`back` re-render via `03-present` with no re-scan. - A GUIDED handoff emits the return line. From 0696d12f351abc1c837fb425fcc66bf2606bd27b Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 06:01:56 +0200 Subject: [PATCH 22/44] refactor(aidd-context): actions stop naming sibling actions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The router mermaid owns the scan → assess → present → run chain, so each action's Input/Output/handoff no longer restates its neighbour. Inputs and outputs name the artifact (snapshot, decision, screen), not the producer or consumer. Drop the reply enumeration from 04-run input (replies.md owns it) and 02-assess's pure-handoff step. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/01-scan.md | 4 ++-- plugins/aidd-context/skills/00-onboard/actions/02-assess.md | 5 ++--- .../aidd-context/skills/00-onboard/actions/03-present.md | 6 +++--- plugins/aidd-context/skills/00-onboard/actions/04-run.md | 4 ++-- 4 files changed, 9 insertions(+), 10 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index cc8ee778..d2ff8e81 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -8,7 +8,7 @@ The project root. ## Output -The project snapshot, printed nowhere, for `02-assess`. +The project snapshot, printed nowhere. ## Process @@ -17,7 +17,7 @@ The project snapshot, printed nowhere, for `02-assess`. 3. **Ledger.** Drop done steps per `@../references/state/done-rule.md`. 4. **Hedge.** If a plan exists, pin the build-to-ship stage per `@../references/state/hedge.md`. 5. **List.** Gather installed AIDD plugins and skills via native discovery. -6. **Hold.** Hand the snapshot to `02-assess`, printing nothing. +6. **Hold.** Keep the snapshot in context. Print nothing. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md index b83352f0..6aae67b5 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -4,11 +4,11 @@ Turn the snapshot into one decision. ## Input -The snapshot from `01-scan`. +The project snapshot. ## Output -The decision for `03-present`. +The decision, ready to render. ## Process @@ -16,7 +16,6 @@ The decision for `03-present`. 2. **Rank.** Top next action per `@../references/order/ranking.md`. - Idle: build the menu per `@../references/order/idle-menu.md`. 3. **Resolve.** Match each command to an installed skill, or name a gap by function when absent. -4. **Hand.** Pass the decision to `03-present`. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 4e5fd16f..622d3c6a 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -4,11 +4,11 @@ Render the screen `02-assess` chose. ## Input -The decision from `02-assess`. +The current decision. ## Output -The rendered screen, and the reply for `04-run`. +The rendered screen, and the user's reply. ## Process @@ -16,7 +16,7 @@ The rendered screen, and the reply for `04-run`. 2. **Inject.** - Entry screen: the banner from `@../assets/banner.txt`. - Flow or walk screen: the curriculum from `@../references/flow.md`. -3. **Wait.** Offer the screen, hand the reply to `04-run`. +3. **Wait.** Offer the screen, take the reply. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 26887d38..3c2a549a 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -4,8 +4,8 @@ Carry out the reply. ## Input -- The reply from `03-present`: a number, `OK`, `?`, `back`, `recap`, `explain`, `skip`, or `stop`. -- The decision from `02-assess`: the resolved commands, or a gap. +- The user's reply, per `@../references/run/replies.md`. +- The current decision, its resolved commands or a gap. ## Output From d40605bd5500f1eb44502991056cfe01a9604fca Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 06:05:19 +0200 Subject: [PATCH 23/44] refactor(aidd-context): slim the report.md screen asset Trim the legend comment (glyph single-home + inline pointers to replies.md/tiers.md), shorten placeholder hints, and replace the notes that restated flow.md/replies.md with pointers. Five screen shapes kept, mapping the screen-map state classes. 776 -> 590 tok. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/assets/report.md | 55 +++++++++---------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index b6a29dd6..2f2f3969 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -1,76 +1,73 @@ -## Entry screen (greenfield · existing · idle · drift) +## Entry screen — greenfield · existing · idle · drift ```txt - + -👋 +👋 Your AIDD setup: - AI tools - Plugins ✅ - Memory + AI tools + Plugins ✅ + Memory - + -👉 [1] - · see the flow [m] +👉 [1] + · flow [m] ``` -- Framing shows on the first report of the session only, then drops on re-scans. -- The banner is injected from `banner.txt` on entry screens only. -- Idle: the flow (from `flow.md`) and `[1] Walk it with me · [2] Let SDLC drive it`, or the idle menu when the user opens it. +Idle adds the flow and `[1] walk · [2] SDLC`, per `flow.md`. ## Foundations step ```txt Foundations — step of - - () + + () 👉 Type [1] to start. skip [s] · what's this [?] ``` -- `` is 2 for an existing repo (memory first, stack skipped) or 3 for greenfield, per `flow.md`. +`` and the step order come from `flow.md` (2 for existing, 3 for greenfield). -## Where you are (mid-work) +## Where you are — mid-work ```txt -🔍 +🔍 - Flow: + Flow: -👉 Next: [1] +👉 Next: [1] ``` -## Warnings that carry a fix +## Warning line -A `⚠️` never stands alone. Render its plain cause, then the fix as a keyed action: +A `⚠️` never stands alone — its plain cause, then a keyed fix: ```txt -⚠️ +⚠️ → Type [1] to . ``` ## [?] detail -On `[?]`, expand the decision: each step's command id and tier clause, the per-check foundation reasons, and the read-only extras. +Expands the decision: each step's command id and tier clause, the per-check foundation reasons, the read-only extras. ```txt Details — 1. () - ... - + explain · recap · stop · back [<] ``` -- `recap` only when a prior conversation exists; `explain project` only when memory is filled. +`recap` only when a prior conversation exists, `explain project` only when memory is filled. From cb4ef1146673c4b48b8554c25acb1c3bf313eb54 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 06:21:50 +0200 Subject: [PATCH 24/44] refactor(aidd-context): report.md is pure shapes, rules move to 03-present An asset holds the shape to fill, not rules and not action names. Strip report.md to the five screen templates. Move the render rules (framing first-only, glyph meanings, warning-carries-fix, ids/tier under [?]) into 03-present, where the renderer owns them. report.md 590 -> 351 tok. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/actions/03-present.md | 9 ++++--- .../skills/00-onboard/assets/report.md | 26 ++++--------------- 2 files changed, 10 insertions(+), 25 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 622d3c6a..5c04838c 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -1,6 +1,6 @@ # 03 - Present -Render the screen `02-assess` chose. +Render the screen the decision names. ## Input @@ -13,9 +13,10 @@ The rendered screen, and the user's reply. ## Process 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. -2. **Inject.** - - Entry screen: the banner from `@../assets/banner.txt`. - - Flow or walk screen: the curriculum from `@../references/flow.md`. + - Framing line on the first report of the session only. + - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. Each `⚠️` shows its cause and a keyed fix. + - Command ids and tier clauses only under `[?]`. +2. **Inject.** Entry screen takes `@../assets/banner.txt`. Flow or walk screen loads `@../references/flow.md`. 3. **Wait.** Offer the screen, take the reply. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index 2f2f3969..99046fa2 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -1,15 +1,9 @@ - + - - -## Entry screen — greenfield · existing · idle · drift +## Entry — greenfield · existing · idle · drift ```txt - + 👋 @@ -18,27 +12,23 @@ Your AIDD setup: Plugins ✅ Memory - + 👉 [1] · flow [m] ``` -Idle adds the flow and `[1] walk · [2] SDLC`, per `flow.md`. - ## Foundations step ```txt Foundations — step of - + () 👉 Type [1] to start. skip [s] · what's this [?] ``` -`` and the step order come from `flow.md` (2 for existing, 3 for greenfield). - ## Where you are — mid-work ```txt @@ -52,8 +42,6 @@ Foundations — step of ## Warning line -A `⚠️` never stands alone — its plain cause, then a keyed fix: - ```txt ⚠️ → Type [1] to . @@ -61,13 +49,9 @@ A `⚠️` never stands alone — its plain cause, then a keyed fix: ## [?] detail -Expands the decision: each step's command id and tier clause, the per-check foundation reasons, the read-only extras. - ```txt Details — 1. () explain · recap · stop · back [<] ``` - -`recap` only when a prior conversation exists, `explain project` only when memory is filled. From 4402cc34b3fe27fbe4d38f4f9b555c9b8fd6214d Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 06:28:58 +0200 Subject: [PATCH 25/44] refactor(aidd-context): references hold data, not action coupling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the 'action reads/does this' opener from every reference — the action already declares which ref it reads, so naming the consumer back is duplication. Remove the read/write and when-a-plan-exists conditions that the actions own, fix a stale glyph-legend pointer, and clear the remaining semicolons. References are the looked-up data now, nothing more. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/references/flow.md | 4 ++-- .../00-onboard/references/order/idle-menu.md | 4 ++-- .../00-onboard/references/order/ranking.md | 2 +- .../00-onboard/references/order/screen-map.md | 2 +- .../00-onboard/references/run/replies.md | 22 +++++++++---------- .../00-onboard/references/run/return.md | 2 +- .../skills/00-onboard/references/run/tiers.md | 2 +- .../00-onboard/references/state/detection.md | 6 ++--- .../00-onboard/references/state/done-rule.md | 5 ++--- .../00-onboard/references/state/hedge.md | 2 +- .../00-onboard/references/state/zones.md | 8 +++---- 11 files changed, 29 insertions(+), 30 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md index fc63e4c6..a28ac50b 100644 --- a/plugins/aidd-context/skills/00-onboard/references/flow.md +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -1,6 +1,6 @@ # AIDD flow curriculum -`03-present` loads this on a flow or walk screen. Source of the `[map]` view. +The feature flow curriculum. Source of the `[map]` view. ## Foundations (state-aware) @@ -9,7 +9,7 @@ ## Feature flow — 8 steps (`spec` optional) -`03-present` renders this table as the vertical annotated screen; the `[map]` is the compact line below. +This table is the vertical annotated screen. The compact `[map]` is the line below. | Step | What | Why | | ------------ | --------------------------- | ------------------------------ | diff --git a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md index 57d4bddf..51899305 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md @@ -1,6 +1,6 @@ # Idle menu -Ranks 1-3 clear => `02-assess` offers three umbrellas plus explore. +When ranks 1-3 are clear, the idle menu: three umbrellas plus explore. | Slot | Umbrella | Opens (installed members) | | ---- | ------------------- | -------------------------------------------------------------------- | @@ -10,5 +10,5 @@ Ranks 1-3 clear => `02-assess` offers three umbrellas plus explore. | ? | explore | `aidd-context:11-explore` + anything not in 1-3 | - Slots 2-3 are umbrellas: a pick re-renders the member sub-list, a member pick runs. Slot 1 runs directly. -- Installed members only; drop an empty umbrella. +- Installed members only. Drop an empty umbrella. - Choices, not a chain: `OK` never walks the idle menu. diff --git a/plugins/aidd-context/skills/00-onboard/references/order/ranking.md b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md index d8660748..c5ec2108 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/ranking.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md @@ -1,6 +1,6 @@ # Next-action order -`02-assess` ranks the next action from the snapshot. First match wins. +The next-action order. First match wins. 1. Unmet foundation, in `zones.md` order (memory first for an existing repo, stack first for greenfield). 2. Earliest unmet dev-flow stage, hedged by `state/hedge.md`. diff --git a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md index 61127f38..16368feb 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -1,6 +1,6 @@ # Screen map -`02-assess` picks the screen from the state class. +The state class picks the screen. ```mermaid stateDiagram-v2 diff --git a/plugins/aidd-context/skills/00-onboard/references/run/replies.md b/plugins/aidd-context/skills/00-onboard/references/run/replies.md index d4f4164b..b1f6f7ef 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/replies.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -1,18 +1,18 @@ # Replies -`04-run` routes the user's reply. +The user's reply and its effect. | Reply | Effect | | ------------- | --------------------------------------------------------------------------------- | -| a number `[n]`| run that step per its tier; an idle-menu umbrella re-renders its member sub-list instead | -| `OK` | walk the pending steps (ranks 1-3) in order; never the idle menu | -| `?` | expand the full detail (command ids, tier clauses, per-check reasons); read-only | -| `back` / `<` | re-render the prior screen via `03-present`; read-only, no re-scan | -| `recap` | summarize this session's conversation; read-only; only when a prior conversation exists | -| `explain ` | describe a step in two or three plain lines; read-only | -| `skip` | record the step left in the ledger; it does not re-fire | -| `stop` | one-line close, end the loop | -| a gap | no installed skill; say it needs a plugin, by function; offer explain or stop | +| a number `[n]`| run that step per its tier, or re-render an idle-menu umbrella's members | +| `OK` | walk the pending steps (ranks 1-3) in order, never the idle menu | +| `?` | expand the full detail (command ids, tier clauses, per-check reasons), read-only | +| `back` / `<` | re-render the prior screen, read-only, no re-scan | +| `recap` | summarize this session's conversation, read-only, only when a prior conversation exists | +| `explain ` | describe a step in two or three plain lines, read-only | +| `skip` | record the step left in the ledger, it does not re-fire | +| `stop` | one-line close, end the loop | +| a gap | no installed skill, say it needs a plugin by function, offer explain or stop | - Read-only replies (`?`, `back`, `recap`, `explain`, `stop`) and umbrella picks do not re-scan. -- After a step or the `OK` walk runs, re-scan (`→ 01`) and re-render. +- After a step or the `OK` walk runs, re-scan and re-render. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/return.md b/plugins/aidd-context/skills/00-onboard/references/run/return.md index c567061b..8c528276 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/return.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/return.md @@ -1,3 +1,3 @@ # Return to onboard -Handing off a GUIDED step launches another skill, which may not return control on its own. So on every handoff, tell the user one line: re-run onboard to come back and continue (the deterministic path is this skill's slash command). The re-run re-scans; the session ledger drops the handed-off step, so the user resumes where they left off rather than repeating it. +A GUIDED handoff launches another skill, which may not return control. So on every handoff, tell the user one line: re-run onboard to come back and continue (the sure path is this skill's slash command). The re-run re-scans, and the ledger drops the handed-off step, so the user resumes rather than repeats. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md index 901b9e41..a00fe1ab 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md @@ -1,6 +1,6 @@ # Tiers -How `04-run` carries out a step. The tier is a default, overridable. +How a step runs. The tier is a default, overridable. | Tier | What | How onboard runs it | | ------ | ----------------------- | ---------------------------------------------------------- | diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index dd68960d..d2cbf0c8 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -1,6 +1,6 @@ # AI tool detection -`01-scan` reads this to fill the state block's AI-tools line. +AI-tool roots and per-tool wiring, for the state block's AI-tools line. ## Root => tool @@ -14,8 +14,8 @@ ## Wiring status per detected tool -Wired = the tool's context file carries the `` block on canonical shape (claude `CLAUDE.md`, codex `AGENTS.md`, cursor `.cursor/rules/`, ...). A detected tool is **wired** or **used, not wired**; the render maps that to a glyph (legend in `assets/report.md`). +Wired = the tool's context file carries the `` block on canonical shape (claude `CLAUDE.md`, codex `AGENTS.md`, cursor `.cursor/rules/`, ...). A detected tool is **wired** or **used, not wired**. -- Detected tools only; an unused optional tool is omitted, never crossed. +- Detected tools only. An unused optional tool is omitted, never crossed. - A not-wired tool carries its cause + fix in the render, e.g. "codex, no `AGENTS.md` => wire it". - Missing memory is a foundation status, not a tool row (see `zones.md`). diff --git a/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md index fe39b20a..8753fa33 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md @@ -1,7 +1,6 @@ # Done rule (session ledger) -A step is done when a disk signal proves it OR the session ledger recorded it run or left this session. A done step never re-enters the next-action list. +A step is done when a disk signal proves it OR the session ledger recorded it run or left this session. A done step never re-enters the next-action list. In-context session state, no file. -- Single home for this rule: `01-scan` reads it, `04-run` writes it. No file, in-context session state. - Kills the re-nag for off-disk completions a disk scan cannot see: a read-only review, a MANUAL step left for the user, an explicit skip. -- `01-scan` re-reads the ledger every scan, so a step recorded since the last scan drops out. Disk and VCS facts refresh on change, not every loop. +- The ledger is re-read every scan, so a step recorded since the last scan drops out. Disk and VCS facts refresh on change, not every loop. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md index 153e3178..052bbf91 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md @@ -1,6 +1,6 @@ # Plan-status hedge -The plan's `status:` frontmatter refines the build-to-ship pin, so review is never skipped nor premature. `01-scan` reads it only when a plan exists. +The plan's `status:` frontmatter refines the build-to-ship pin, so review is never skipped nor premature. | Plan `status:` | Pin | | ----------------------- | ---------------------------- | diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md index b64f9d53..1f1d5aa2 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/zones.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -1,6 +1,6 @@ # State zones -Disk/VCS checks that place the project. `01-scan` reads this. Each check is met, drift (present, off canonical shape), or missing. Render glyphs: see `assets/report.md`. +Disk/VCS checks that place the project. Each check is met, drift (present, off canonical shape), or missing. ## Foundations @@ -12,8 +12,8 @@ State-aware order: existing repo (code) => memory first, stack skipped. Greenfie | project memory | `aidd_docs/memory/` has real content | files empty/placeholder | project knowledge saved | `aidd-context:02-project-memory` | | memory wiring | `` block on canonical shape in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | -- tech stack missing only on greenfield (no code AND no synced memory); established = met, never bootstrap. -- memory wiring: absent block or no context file = missing (not drift); drift = the block is present but not the standard `` block that imports the memory files. +- tech stack missing only on greenfield (no code AND no synced memory). Established = met, never bootstrap. +- memory wiring: absent block or no context file = missing, not drift. Drift = the block present but not the standard `` block that imports the memory files. ## Dev flow @@ -36,7 +36,7 @@ Cumulative: a downstream artifact implies the upstream stages met. ## Health -Beside-the-flow tools, surfaced only when their signal fires. Scan project source only; exclude templates, fixtures, examples, generated output, installed-plugin trees. +Beside-the-flow tools, surfaced only when their signal fires. Scan project source only, excluding templates, fixtures, examples, generated output, and installed-plugin trees. | Signal | Fires when | Command | | ----------- | ------------------------------------------- | ------------------- | From 5a713544b391ba1684b8159c2e552f9424b95e32 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 06:47:29 +0200 Subject: [PATCH 26/44] fix(aidd-context): resolve checker findings on the onboard slim pass Restore the explain-project reply (dropped, not relocated) with its memory-filled guard. Drop the render instruction from detection.md (03-present owns rendering). Align 04-run Output with its Process by exempting umbrella picks from the re-scan too. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/04-run.md | 2 +- plugins/aidd-context/skills/00-onboard/assets/banner.txt | 2 +- plugins/aidd-context/skills/00-onboard/assets/report.md | 2 +- plugins/aidd-context/skills/00-onboard/references/flow.md | 4 +++- .../aidd-context/skills/00-onboard/references/run/replies.md | 1 + .../skills/00-onboard/references/state/detection.md | 2 +- 6 files changed, 8 insertions(+), 5 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 3c2a549a..120ffa35 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -9,7 +9,7 @@ Carry out the reply. ## Output -The reply carried out and the ledger updated, then a re-scan unless the reply was read-only. +The reply carried out and the ledger updated, then a re-scan unless the reply was read-only or an umbrella pick. ## Process diff --git a/plugins/aidd-context/skills/00-onboard/assets/banner.txt b/plugins/aidd-context/skills/00-onboard/assets/banner.txt index cf2ee097..42283623 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/banner.txt +++ b/plugins/aidd-context/skills/00-onboard/assets/banner.txt @@ -4,4 +4,4 @@ ██╔══██║██║██║ ██║██║ ██║ ██║ ██║██║██████╔╝██████╔╝ ╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ - AI-Driven Development + AI-Driven Development 🇫🇷 diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index 99046fa2..6ae69fb2 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -53,5 +53,5 @@ Foundations — step of Details — 1. () - explain · recap · stop · back [<] + explain · explain project · recap · stop · back [<] ``` diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md index a28ac50b..241ec2f9 100644 --- a/plugins/aidd-context/skills/00-onboard/references/flow.md +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -7,7 +7,7 @@ The feature flow curriculum. Source of the `[map]` view. - Existing (code present): memory first, stack skipped. `project memory` → `connect to the AI`. - Greenfield (empty): `design tech stack` → `project memory` → `connect to the AI`. -## Feature flow — 8 steps (`spec` optional) +## Feature flow — 8 steps This table is the vertical annotated screen. The compact `[map]` is the line below. @@ -24,6 +24,8 @@ This table is the vertical annotated screen. The compact `[map]` is the line bel `[map]`: `brainstorm → spec* → plan → implement → assert → review → commit → PR` +`*`: is optional + ## Run it `[1]` walk with me, step by step · `[2]` hand the whole flow to `aidd-dev:00-sdlc` diff --git a/plugins/aidd-context/skills/00-onboard/references/run/replies.md b/plugins/aidd-context/skills/00-onboard/references/run/replies.md index b1f6f7ef..9c0328c1 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/replies.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -10,6 +10,7 @@ The user's reply and its effect. | `back` / `<` | re-render the prior screen, read-only, no re-scan | | `recap` | summarize this session's conversation, read-only, only when a prior conversation exists | | `explain ` | describe a step in two or three plain lines, read-only | +| `explain project` | summarize the project from its memory bank, read-only, only when memory is filled | | `skip` | record the step left in the ledger, it does not re-fire | | `stop` | one-line close, end the loop | | a gap | no installed skill, say it needs a plugin by function, offer explain or stop | diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index d2cbf0c8..67d2f14e 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -17,5 +17,5 @@ AI-tool roots and per-tool wiring, for the state block's AI-tools line. Wired = the tool's context file carries the `` block on canonical shape (claude `CLAUDE.md`, codex `AGENTS.md`, cursor `.cursor/rules/`, ...). A detected tool is **wired** or **used, not wired**. - Detected tools only. An unused optional tool is omitted, never crossed. -- A not-wired tool carries its cause + fix in the render, e.g. "codex, no `AGENTS.md` => wire it". +- A not-wired tool needs its memory wired, e.g. "codex, no `AGENTS.md`". - Missing memory is a foundation status, not a tool row (see `zones.md`). From eaddb89d0f56bdd3d12e806355da6f1ba5fdc540 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 07:03:41 +0200 Subject: [PATCH 27/44] fix(aidd-context): correct + slim onboard references from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit detection: detect a tool by its own dir only (.claude/.codex/.cursor/ .opencode) — AGENTS.md is a shared wiring target many tools read, not a codex signal. hedge: cover all five plan statuses (pending, in-progress, implemented, reviewed, blocked) plus open-PR. idle-menu: new work is sdlc or brainstorm, not spec. screen-map: one class/when/screen table, drop the redundant mermaid. zones: keep detectable pins in the table, inferred stages in a note; trim noise. return + done-rule: slimmed, purpose-first. Co-Authored-By: Claude Opus 4.8 --- .../00-onboard/references/order/idle-menu.md | 2 +- .../00-onboard/references/order/screen-map.md | 23 ++++------ .../00-onboard/references/run/return.md | 2 +- .../00-onboard/references/state/detection.md | 24 ++++++----- .../00-onboard/references/state/done-rule.md | 6 +-- .../00-onboard/references/state/hedge.md | 13 +++--- .../00-onboard/references/state/zones.md | 42 +++++++++---------- 7 files changed, 52 insertions(+), 60 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md index 51899305..76dea069 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md @@ -4,7 +4,7 @@ When ranks 1-3 are clear, the idle menu: three umbrellas plus explore. | Slot | Umbrella | Opens (installed members) | | ---- | ------------------- | -------------------------------------------------------------------- | -| 1 | start new work | `aidd-dev:00-sdlc` (or `aidd-pm:04-spec`) | +| 1 | start new work | `aidd-dev:00-sdlc`, or `aidd-refine:01-brainstorm` for a fuzzy idea | | 2 | improve the project | `aidd-dev:` `04-audit` · `06-test` · `07-refactor` | | 3 | customize the AI | the **missing** `aidd-context:` generators: rule `05-rule-generate`, workflow `04-skill-generate`, agent `06-agent-generate`, command `07-command-generate`, hook `08-hook-generate` | | ? | explore | `aidd-context:11-explore` + anything not in 1-3 | diff --git a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md index 16368feb..8d9f900c 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -2,19 +2,10 @@ The state class picks the screen. -```mermaid -stateDiagram-v2 - [*] --> greenfield: no code, no memory - [*] --> existing: code present, memory missing - [*] --> drift: a foundation is ⚠ - [*] --> midwork: a dev-flow step pending - [*] --> idle: all clear -``` - -| State class | Screen | -| ----------- | -------------------------------------------------------------- | -| greenfield | welcome + foundations, **stack first** (3 steps) | -| existing | welcome + foundations, **memory first** (2 steps, stack skipped) | -| drift | welcome + the warning-with-fix | -| midwork | where-you-are on the flow + the next step | -| idle | welcome + the flow (walk or SDLC), or the idle menu | +| State class | When | Screen | +| ----------- | ---------------------------- | --------------------------------------------------- | +| greenfield | no code, no memory | welcome + foundations, stack first (3 steps) | +| existing | code present, memory missing | welcome + foundations, memory first (2 steps) | +| drift | a foundation is ⚠ | welcome + the warning-with-fix | +| midwork | a dev-flow step pending | where-you-are on the flow + the next step | +| idle | all clear | welcome + the flow (walk or SDLC), or the idle menu | diff --git a/plugins/aidd-context/skills/00-onboard/references/run/return.md b/plugins/aidd-context/skills/00-onboard/references/run/return.md index 8c528276..8654e287 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/return.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/return.md @@ -1,3 +1,3 @@ # Return to onboard -A GUIDED handoff launches another skill, which may not return control. So on every handoff, tell the user one line: re-run onboard to come back and continue (the sure path is this skill's slash command). The re-run re-scans, and the ledger drops the handed-off step, so the user resumes rather than repeats. +A GUIDED step hands off to a skill that may not return control. So on every handoff, tell the user one line: re-run onboard to come back (the sure path is its slash command). The re-scan drops the handed-off step, so they resume, not repeat. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index 67d2f14e..a5a8a928 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -1,20 +1,22 @@ # AI tool detection -AI-tool roots and per-tool wiring, for the state block's AI-tools line. +Which AI tools the project uses, and whether each has its memory wired. For the state block's AI-tools line. -## Root => tool +## Detect by the tool's own dir -| Tool | Root present | -| -------- | ------------------------------------------------------------------------------------- | -| claude | `.claude/` or `CLAUDE.md` | -| codex | `.codex/` or `AGENTS.md` | -| cursor | `.cursor/` or `.cursorrules` | -| opencode | `.opencode/` | -| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | +A tool is used when its dedicated root exists. Shared context files (`AGENTS.md`, `CLAUDE.md`) are wiring targets, never detection signals. -## Wiring status per detected tool +| Tool | Used when | +| -------- | ------------------------------------------------------------------------------------ | +| claude | `.claude/` | +| codex | `.codex/` | +| cursor | `.cursor/` | +| opencode | `.opencode/` | +| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | -Wired = the tool's context file carries the `` block on canonical shape (claude `CLAUDE.md`, codex `AGENTS.md`, cursor `.cursor/rules/`, ...). A detected tool is **wired** or **used, not wired**. +## Wiring + +Wired = the tool's context file carries the `` block on canonical shape. `AGENTS.md` is the shared target for codex, cursor, and opencode. `CLAUDE.md` is claude's. A detected tool is **wired** or **used, not wired**. - Detected tools only. An unused optional tool is omitted, never crossed. - A not-wired tool needs its memory wired, e.g. "codex, no `AGENTS.md`". diff --git a/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md index 8753fa33..9070e4d4 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md @@ -1,6 +1,6 @@ # Done rule (session ledger) -A step is done when a disk signal proves it OR the session ledger recorded it run or left this session. A done step never re-enters the next-action list. In-context session state, no file. +Stops onboard from re-recommending a step already handled this session. In-context state, no file. -- Kills the re-nag for off-disk completions a disk scan cannot see: a read-only review, a MANUAL step left for the user, an explicit skip. -- The ledger is re-read every scan, so a step recorded since the last scan drops out. Disk and VCS facts refresh on change, not every loop. +- Done = a disk signal proves it, OR the ledger recorded it run or left (a read-only review, a MANUAL step left, a skip). +- Re-read every scan, so a step recorded since drops out. Disk and VCS facts refresh on change, not every loop. diff --git a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md index 052bbf91..3ffee0e8 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md @@ -2,8 +2,11 @@ The plan's `status:` frontmatter refines the build-to-ship pin, so review is never skipped nor premature. -| Plan `status:` | Pin | -| ----------------------- | ---------------------------- | -| `in-progress` | Implement alone | -| `implemented`, or an open PR | Review, then commit/ship (Review first) | -| unreadable or absent | Implement, then Review | +| Plan `status:` | Pin | +| ---------------------------- | ------------------------------------- | +| `pending` | Implement (not started yet) | +| `in-progress` | Implement alone | +| `implemented`, or an open PR | Review, then ship (Review first) | +| `reviewed` | Ship (commit, pull request) | +| `blocked` | surface the blocker, not a normal pin | +| unreadable or absent | Implement, then Review | diff --git a/plugins/aidd-context/skills/00-onboard/references/state/zones.md b/plugins/aidd-context/skills/00-onboard/references/state/zones.md index 1f1d5aa2..c0f57b54 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/zones.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -4,39 +4,35 @@ Disk/VCS checks that place the project. Each check is met, drift (present, off c ## Foundations -State-aware order: existing repo (code) => memory first, stack skipped. Greenfield empty => stack → memory → wire. +State-aware order: existing repo (code) => memory first, stack skipped. Greenfield => stack → memory → wire. -| Check | Met when | Drift when | Deliverable | Command | -| -------------- | ------------------------------------------------------------- | ----------------------- | ------------------------- | -------------------------------- | -| tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | -| project memory | `aidd_docs/memory/` has real content | files empty/placeholder | project knowledge saved | `aidd-context:02-project-memory` | -| memory wiring | `` block on canonical shape in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | +| Check | Met when | Drift when | Deliverable | Command | +| -------------- | ------------------------------------------------------------- | ------------------------ | -------------------------- | -------------------------------- | +| tech stack | `INSTALL.md` exists OR repo established (code or synced memory) | — | tech stack | `aidd-context:01-bootstrap` | +| project memory | `aidd_docs/memory/` has real content | files empty/placeholder | project knowledge saved | `aidd-context:02-project-memory` | +| memory wiring | the standard `` block in each used tool's context file | block present, off shape | knowledge loaded by the AI | `aidd-context:02-project-memory` | -- tech stack missing only on greenfield (no code AND no synced memory). Established = met, never bootstrap. -- memory wiring: absent block or no context file = missing, not drift. Drift = the block present but not the standard `` block that imports the memory files. +- tech stack missing only on greenfield (no code AND no synced memory). +- memory wiring: no block or no context file = missing. Drift = a block present but not the standard one that imports the memory files. ## Dev flow -Cumulative: a downstream artifact implies the upstream stages met. +Cumulative: a downstream artifact implies the upstream stages met. The pin sits on the furthest reached. -| Stage | Pin sits here when | -| ---------- | ------------------------------------------- | -| brainstorm | no spec/plan/code (idea only) | -| spec | spec under `aidd_docs/`, nothing downstream | -| plan | `plan.md`, no code against it | -| implement | code against the plan | -| assert | code done, assertions not green | -| review | code done, current branch PR awaits review | -| commit | reviewed, uncommitted/unpushed | -| PR | current branch has an open PR | +| Stage | Detected when | +| --------- | --------------------------------------------- | +| spec | a spec under `aidd_docs/`, nothing downstream | +| plan | `plan.md`, no code against it | +| implement | code against the plan | +| review | code done, current branch PR awaits review | +| PR | current branch has an open PR | -- Disk/VCS-detectable: `spec`, `plan`, `implement`, `review`, `PR`. `review`/`PR` read VCS **current branch only** — ignore repo-wide PRs and review queues (another branch = another dev, never the pin). -- Inferred, no cheap signal: `brainstorm`, `assert`, `commit`. Placed by the hedge + cumulative state, not disk-pinned. -- Plan `status:` refines the pin: see `hedge.md`. +- `review` and `PR` read VCS **current branch only** — ignore repo-wide PRs and review queues (another branch is another dev). +- `brainstorm`, `assert`, and `commit` have no cheap signal. The plan `status:` hedge and cumulative state place the pin (see `hedge.md`). ## Health -Beside-the-flow tools, surfaced only when their signal fires. Scan project source only, excluding templates, fixtures, examples, generated output, and installed-plugin trees. +Beside-the-flow tools, surfaced only when their signal fires. Scan project source only, not templates, fixtures, examples, generated output, or installed-plugin trees. | Signal | Fires when | Command | | ----------- | ------------------------------------------- | ------------------- | From 918f060e1c220db518feea71d3971eff88daf843 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 07:10:36 +0200 Subject: [PATCH 28/44] refactor(aidd-context): fold detection wiring prose into the table The 'AGENTS.md is the shared target... CLAUDE.md is claude's' prose just restated a column. One table now carries detection dir + wiring file per tool; the shared AGENTS.md is self-evident from the rows. Co-Authored-By: Claude Opus 4.8 --- .../00-onboard/references/state/detection.md | 26 +++++++------------ 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index a5a8a928..0ccc2146 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -2,22 +2,14 @@ Which AI tools the project uses, and whether each has its memory wired. For the state block's AI-tools line. -## Detect by the tool's own dir - -A tool is used when its dedicated root exists. Shared context files (`AGENTS.md`, `CLAUDE.md`) are wiring targets, never detection signals. - -| Tool | Used when | -| -------- | ------------------------------------------------------------------------------------ | -| claude | `.claude/` | -| codex | `.codex/` | -| cursor | `.cursor/` | -| opencode | `.opencode/` | -| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | - -## Wiring - -Wired = the tool's context file carries the `` block on canonical shape. `AGENTS.md` is the shared target for codex, cursor, and opencode. `CLAUDE.md` is claude's. A detected tool is **wired** or **used, not wired**. - +| Tool | Used when (its own dir) | Wired when this file has the block | +| -------- | ------------------------------------------------------------------------------------ | ---------------------------------- | +| claude | `.claude/` | `CLAUDE.md` | +| codex | `.codex/` | `AGENTS.md` | +| cursor | `.cursor/` | `AGENTS.md` | +| opencode | `.opencode/` | `AGENTS.md` | +| copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | `.github/copilot-instructions.md` | + +- Detect by the dir only — `AGENTS.md` and `CLAUDE.md` are wiring targets, not detection signals. - Detected tools only. An unused optional tool is omitted, never crossed. -- A not-wired tool needs its memory wired, e.g. "codex, no `AGENTS.md`". - Missing memory is a foundation status, not a tool row (see `zones.md`). From 7d5448ae40748ca4f5a95d0ac1bdd7d340f5a6d0 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 09:09:11 +0200 Subject: [PATCH 29/44] refactor(aidd-context): drop prose that a table or another file carries flow + ranking + replies + screen-map: drop openers that only echo the H1. ranking: drop the state-aware parenthetical zones.md owns. replies: [n] just runs a step or opens an umbrella, idle-menu owns the umbrella mechanic. tiers: fold the clause into a table column, drop the What column and the OK-walk bullet that restated it. flow: drop the render hint. Includes the banner flag. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/references/flow.md | 4 +--- .../00-onboard/references/order/ranking.md | 4 ++-- .../00-onboard/references/order/screen-map.md | 2 -- .../skills/00-onboard/references/run/replies.md | 4 +--- .../skills/00-onboard/references/run/tiers.md | 17 ++++++++--------- 5 files changed, 12 insertions(+), 19 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md index 241ec2f9..46eacd1c 100644 --- a/plugins/aidd-context/skills/00-onboard/references/flow.md +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -1,6 +1,6 @@ # AIDD flow curriculum -The feature flow curriculum. Source of the `[map]` view. +Source of the `[map]` view. ## Foundations (state-aware) @@ -9,8 +9,6 @@ The feature flow curriculum. Source of the `[map]` view. ## Feature flow — 8 steps -This table is the vertical annotated screen. The compact `[map]` is the line below. - | Step | What | Why | | ------------ | --------------------------- | ------------------------------ | | brainstorm | vague idea → precise | fuzzy idea makes every step guess | diff --git a/plugins/aidd-context/skills/00-onboard/references/order/ranking.md b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md index c5ec2108..d62a726f 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/ranking.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md @@ -1,8 +1,8 @@ # Next-action order -The next-action order. First match wins. +First match wins. -1. Unmet foundation, in `zones.md` order (memory first for an existing repo, stack first for greenfield). +1. Unmet foundation, in `zones.md` order. 2. Earliest unmet dev-flow stage, hedged by `state/hedge.md`. 3. A fired health tool. 4. Idle menu (see `idle-menu.md`) — only when 1-3 are all clear. diff --git a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md index 8d9f900c..0637cff4 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -1,7 +1,5 @@ # Screen map -The state class picks the screen. - | State class | When | Screen | | ----------- | ---------------------------- | --------------------------------------------------- | | greenfield | no code, no memory | welcome + foundations, stack first (3 steps) | diff --git a/plugins/aidd-context/skills/00-onboard/references/run/replies.md b/plugins/aidd-context/skills/00-onboard/references/run/replies.md index 9c0328c1..0443ea43 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/replies.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -1,10 +1,8 @@ # Replies -The user's reply and its effect. - | Reply | Effect | | ------------- | --------------------------------------------------------------------------------- | -| a number `[n]`| run that step per its tier, or re-render an idle-menu umbrella's members | +| a number `[n]`| run that step, or open an idle-menu umbrella | | `OK` | walk the pending steps (ranks 1-3) in order, never the idle menu | | `?` | expand the full detail (command ids, tier clauses, per-check reasons), read-only | | `back` / `<` | re-render the prior screen, read-only, no re-scan | diff --git a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md index a00fe1ab..94ce4345 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/tiers.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md @@ -1,13 +1,12 @@ # Tiers -How a step runs. The tier is a default, overridable. +The tier is a default, overridable. -| Tier | What | How onboard runs it | -| ------ | ----------------------- | ---------------------------------------------------------- | -| AUTO | non-interactive | invoke, run to completion, continue | -| GUIDED | interactive Q&A | launch, hand to the user, resume on return (see `return.md`) | -| MANUAL | side-effecting, outward | show the command, run nothing, leave it for the user | +| Tier | Clause | How it runs | +| ------ | --------------------------------- | ------------------------------------------------------------ | +| AUTO | (runs on its own) | invoke, run to completion, continue | +| GUIDED | (it will ask you a few questions) | launch, hand to the user, resume on return (see `return.md`) | +| MANUAL | (you run this one yourself) | show the command, run nothing, leave it for the user | -- Rendered as a plain clause, never a glyph: AUTO `(runs on its own)`, GUIDED `(it will ask you a few questions)`, MANUAL `(you run this one yourself)`. -- The tier is a default. A dual-mode skill (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`) runs the other way when the user asks and the skill supports it. -- `OK` walk: AUTO to completion, GUIDED pauses then resumes, MANUAL shown and left. State up front how many steps and which need input. +- A dual-mode skill (interactive by default, unattended on request, e.g. `aidd-dev:00-sdlc`) runs the other way when the user asks and the skill supports it. +- On the `OK` walk, state up front how many steps it covers and which need input. From 9b04c89661ff0510e99cbba894f1ffc0ae53ea40 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 09:14:53 +0200 Subject: [PATCH 30/44] fix(aidd-context): hedge fallback names the status field, not the plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 'unreadable or absent' read as 'no plan', but hedge only applies when a plan exists — with no plan, zones.md places the pin. The row is about a missing or unreadable status field. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/references/state/hedge.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md index 3ffee0e8..c1a33b0e 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md @@ -4,9 +4,9 @@ The plan's `status:` frontmatter refines the build-to-ship pin, so review is nev | Plan `status:` | Pin | | ---------------------------- | ------------------------------------- | -| `pending` | Implement (not started yet) | +| `pending` | To implement | | `in-progress` | Implement alone | -| `implemented`, or an open PR | Review, then ship (Review first) | +| `implemented` | Review | | `reviewed` | Ship (commit, pull request) | | `blocked` | surface the blocker, not a normal pin | -| unreadable or absent | Implement, then Review | +| the field is missing or unreadable | Implement, then Review | From 1bc5ecbeb67d3fc77e2127d39ef184658af952f1 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 09:19:11 +0200 Subject: [PATCH 31/44] fix(aidd-context): a broken plan status surfaces, it does not guess a pin A missing or unreadable status: means the plan itself is broken. Surface it like blocked does, rather than inventing an Implement-then-Review pin. Co-Authored-By: Claude Opus 4.8 --- .../aidd-context/skills/00-onboard/references/state/hedge.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md index c1a33b0e..fe44590d 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/hedge.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md @@ -9,4 +9,4 @@ The plan's `status:` frontmatter refines the build-to-ship pin, so review is nev | `implemented` | Review | | `reviewed` | Ship (commit, pull request) | | `blocked` | surface the blocker, not a normal pin | -| the field is missing or unreadable | Implement, then Review | +| the field is missing or unreadable | surface the plan as broken, not a normal pin | From c77aa40a589572d4ac3bb78b44028484e562f0a1 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 09:37:06 +0200 Subject: [PATCH 32/44] fix(aidd-context): resolve the ten-lens audit findings on onboard Explore becomes idle-menu slot 4, so [?] is no longer overloaded between 'expand detail' and 'explore' on the idle screen. Delete the two replies.md bullets that restated 04-run's loop decision (five lenses agreed). Drop 04-run's verbatim echo of tiers.md and its lone sibling-action reference. Drop flow.md's consumer-naming line. Strip trailing whitespace. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/SKILL.md | 4 ++-- plugins/aidd-context/skills/00-onboard/actions/04-run.md | 4 ++-- plugins/aidd-context/skills/00-onboard/references/flow.md | 4 +--- .../skills/00-onboard/references/order/idle-menu.md | 8 ++++---- .../skills/00-onboard/references/run/replies.md | 3 --- 5 files changed, 9 insertions(+), 14 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index e72ece8b..7f4712e0 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -22,9 +22,9 @@ flowchart LR ## Transversal rules -- Guide, do not lecture or dump. +- Guide, do not lecture or dump. - Name real commands only, never invented ones. - Never run a GUIDED step unattended. - Never test a plugin version against a registry. -- Never trust a stale status. +- Never trust a stale status. - Wait for an explicit reply before running anything. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 120ffa35..fe7f699f 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -18,7 +18,7 @@ The reply carried out and the ledger updated, then a re-scan unless the reply wa - Run only installed skills. - A gap invokes nothing. - A MANUAL step is shown, not run. -3. **Tier.** Running a step, apply `@../references/run/tiers.md`. The tier is a default, overridable. +3. **Tier.** Running a step, apply `@../references/run/tiers.md`. 4. **Return.** On a GUIDED handoff, emit the return line per `@../references/run/return.md`. 5. **Record.** Write the handled step to the ledger per `@../references/state/done-rule.md`. 6. **Loop.** After a run or `OK` walk, re-scan. A read-only reply or umbrella pick does not. @@ -28,5 +28,5 @@ The reply carried out and the ledger updated, then a re-scan unless the reply wa - `OK` runs AUTO unattended and pauses at each GUIDED. - A MANUAL step is shown, never run. - A gap invokes nothing. -- `?`/`back` re-render via `03-present` with no re-scan. +- `?`/`back` re-render with no re-scan. - A GUIDED handoff emits the return line. diff --git a/plugins/aidd-context/skills/00-onboard/references/flow.md b/plugins/aidd-context/skills/00-onboard/references/flow.md index 46eacd1c..c8dac4c0 100644 --- a/plugins/aidd-context/skills/00-onboard/references/flow.md +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -1,7 +1,5 @@ # AIDD flow curriculum -Source of the `[map]` view. - ## Foundations (state-aware) - Existing (code present): memory first, stack skipped. `project memory` → `connect to the AI`. @@ -22,7 +20,7 @@ Source of the `[map]` view. `[map]`: `brainstorm → spec* → plan → implement → assert → review → commit → PR` -`*`: is optional +`*`: optional ## Run it diff --git a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md index 76dea069..1601a00e 100644 --- a/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md +++ b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md @@ -1,14 +1,14 @@ # Idle menu -When ranks 1-3 are clear, the idle menu: three umbrellas plus explore. +When ranks 1-3 are clear, the idle menu offers four choices. -| Slot | Umbrella | Opens (installed members) | +| Slot | Choice | Opens (installed members) | | ---- | ------------------- | -------------------------------------------------------------------- | | 1 | start new work | `aidd-dev:00-sdlc`, or `aidd-refine:01-brainstorm` for a fuzzy idea | | 2 | improve the project | `aidd-dev:` `04-audit` · `06-test` · `07-refactor` | | 3 | customize the AI | the **missing** `aidd-context:` generators: rule `05-rule-generate`, workflow `04-skill-generate`, agent `06-agent-generate`, command `07-command-generate`, hook `08-hook-generate` | -| ? | explore | `aidd-context:11-explore` + anything not in 1-3 | +| 4 | explore | `aidd-context:11-explore` + anything not in 1-3 | -- Slots 2-3 are umbrellas: a pick re-renders the member sub-list, a member pick runs. Slot 1 runs directly. +- Slots 2 and 3 are umbrellas: a pick re-renders the member sub-list, a member pick runs. Slots 1 and 4 run directly. - Installed members only. Drop an empty umbrella. - Choices, not a chain: `OK` never walks the idle menu. diff --git a/plugins/aidd-context/skills/00-onboard/references/run/replies.md b/plugins/aidd-context/skills/00-onboard/references/run/replies.md index 0443ea43..a7776ec2 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/replies.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -12,6 +12,3 @@ | `skip` | record the step left in the ledger, it does not re-fire | | `stop` | one-line close, end the loop | | a gap | no installed skill, say it needs a plugin by function, offer explain or stop | - -- Read-only replies (`?`, `back`, `recap`, `explain`, `stop`) and umbrella picks do not re-scan. -- After a step or the `OK` walk runs, re-scan and re-render. From 3b8331f9ef8e0ca4c7f97288864013ebfbd2d3d8 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 09:47:10 +0200 Subject: [PATCH 33/44] docs(aidd-context): refresh the stale onboard row in the plugin index The index still carried the pre-rework description. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index 753825bd..85f41953 100644 --- a/plugins/aidd-context/README.md +++ b/plugins/aidd-context/README.md @@ -14,7 +14,7 @@ Covers project bootstrap, the project memory bank, generation of context artifac | Bracket ID | Skill | Description | | ---------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [1.0] | [onboard](skills/00-onboard/README.md) | Guide the user through the AIDD flow on the current project, in plain language, and suggest the next logical step, adapted to the installed plugins. | +| [1.0] | [onboard](skills/00-onboard/README.md) | Guide a project's journey through AIDD, from first setup to shipping a feature, one clear next action at a time. | | [1.1] | [bootstrap](skills/01-bootstrap/README.md) | Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and an INSTALL.md output. | | [1.2] | [project-memory](skills/02-project-memory/README.md) | Initialize or refresh the project memory bank from a capability-based model, and carry the memory block into the AI context files. | | [1.3] | [context-generate](skills/03-context-generate/README.md) | Generate context artifacts: router-based skills, agents, rules, slash commands, hooks, plugin scaffolds, and plugin marketplaces. | From 8cd6ec262bd9d89bccb094546cb13a27ac00221c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 10:12:47 +0200 Subject: [PATCH 34/44] fix(aidd-context): specify what the live greenfield run left to chance A real headless run improvised three things the asset never specified: the foundations screen previewed the remaining steps, the option line carried OK-walks-all and the flow map, and a zero-tool project crossed its AI-tools row. Pin all three: the remaining steps are part of the foundations shape, the option line names the walk and the map, and an undetected tool set reads 'none yet' uncrossed since the memory row already carries the gap. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/assets/report.md | 6 ++++-- .../skills/00-onboard/references/state/detection.md | 1 + 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index 6ae69fb2..d48fa7e8 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -8,7 +8,7 @@ 👋 Your AIDD setup: - AI tools + AI tools Plugins ✅ Memory @@ -26,7 +26,9 @@ Foundations — step of () -👉 Type [1] to start. skip [s] · what's this [?] + — > + +👉 Type [1] to start. skip [s] · what's this [?] · OK walks all · flow [m] ``` ## Where you are — mid-work diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index 0ccc2146..2a8c535c 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -12,4 +12,5 @@ Which AI tools the project uses, and whether each has its memory wired. For the - Detect by the dir only — `AGENTS.md` and `CLAUDE.md` are wiring targets, not detection signals. - Detected tools only. An unused optional tool is omitted, never crossed. +- No tool detected at all: the row reads `none yet`, uncrossed. The memory row's `❌` already carries the gap. - Missing memory is a foundation status, not a tool row (see `zones.md`). From 93652ff2200ef32858c5343a0481a925ba94e446 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 10:14:50 +0200 Subject: [PATCH 35/44] fix(aidd-context): one action line per screen The live greenfield run stacked the entry screen's action line on top of the foundations step's, repeating the same options twice. A screen that carries a foundations step uses that step's line. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 5c04838c..59a46c8e 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -14,6 +14,7 @@ The rendered screen, and the user's reply. 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. - Framing line on the first report of the session only. + - One `👉` action line per screen. A screen carrying a foundations step uses that step's line, never both. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. Each `⚠️` shows its cause and a keyed fix. - Command ids and tier clauses only under `[?]`. 2. **Inject.** Entry screen takes `@../assets/banner.txt`. Flow or walk screen loads `@../references/flow.md`. From 01f9f2431cd320257b50074ce29472d5b72054c9 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 10:27:26 +0200 Subject: [PATCH 36/44] fix(aidd-context): the action line renders once, whoever carries it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A drift screen printed [1] twice: the warning's fix line and the arrow line both claimed the same action. Generalise the rule — a warning's fix or a foundations step already is the action line, so the arrow line renders only when neither does. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 2 +- plugins/aidd-context/skills/00-onboard/assets/report.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 59a46c8e..7d907855 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -14,7 +14,7 @@ The rendered screen, and the user's reply. 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. - Framing line on the first report of the session only. - - One `👉` action line per screen. A screen carrying a foundations step uses that step's line, never both. + - One action line per screen, carrying the key once. A warning's fix or a foundations step already is that line, so render the `👉` line only when neither does. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. Each `⚠️` shows its cause and a keyed fix. - Command ids and tier clauses only under `[?]`. 2. **Inject.** Entry screen takes `@../assets/banner.txt`. Flow or walk screen loads `@../references/flow.md`. diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index d48fa7e8..2a035f8e 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -14,7 +14,7 @@ Your AIDD setup: -👉 [1] + [1]> · flow [m] ``` From 681cbe7b885b6c3f7a25835cedd096ce39b05084 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 10:29:31 +0200 Subject: [PATCH 37/44] fix(aidd-context): the screen ends at the options line A live run trailed improvised prose past the options line, guessing what comes after the fix. Lines stay short, nothing follows the options line, and lookahead lives under [?]. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 7d907855..0ab18c72 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -17,6 +17,7 @@ The rendered screen, and the user's reply. - One action line per screen, carrying the key once. A warning's fix or a foundations step already is that line, so render the `👉` line only when neither does. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. Each `⚠️` shows its cause and a keyed fix. - Command ids and tier clauses only under `[?]`. + - Short lines. Nothing after the options line. Lookahead and detail live under `[?]`. 2. **Inject.** Entry screen takes `@../assets/banner.txt`. Flow or walk screen loads `@../references/flow.md`. 3. **Wait.** Offer the screen, take the reply. From c0c32c2e7c732c6d19591d07727b70dae351076c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 10:34:08 +0200 Subject: [PATCH 38/44] refactor(aidd-context): one idea per line in the actions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the compound render bullets in 03-present and its Inject step, and cut 04-run's Output back to the artifact it names — the ledger write and the re-scan are Process steps, not Output prose. Co-Authored-By: Claude Opus 4.8 --- .../skills/00-onboard/actions/03-present.md | 18 ++++++++++++------ .../skills/00-onboard/actions/04-run.md | 2 +- 2 files changed, 13 insertions(+), 7 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 0ab18c72..c9a8673b 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -14,11 +14,15 @@ The rendered screen, and the user's reply. 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. - Framing line on the first report of the session only. - - One action line per screen, carrying the key once. A warning's fix or a foundations step already is that line, so render the `👉` line only when neither does. - - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. Each `⚠️` shows its cause and a keyed fix. - - Command ids and tier clauses only under `[?]`. - - Short lines. Nothing after the options line. Lookahead and detail live under `[?]`. -2. **Inject.** Entry screen takes `@../assets/banner.txt`. Flow or walk screen loads `@../references/flow.md`. + - One action line per screen, carrying its key once. + - A warning's fix or a foundations step is that line. Render `👉` only when neither is. + - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. + - Every `⚠️` shows its cause and a keyed fix. + - Short lines. The screen ends at the options line. + - Command ids, tier clauses, and lookahead only under `[?]`. +2. **Inject.** + - Entry screen takes `@../assets/banner.txt`. + - Flow or walk screen loads `@../references/flow.md`. 3. **Wait.** Offer the screen, take the reply. ## Test @@ -27,4 +31,6 @@ The rendered screen, and the user's reply. - An existing repo renders memory as step 1 of 2. - A greenfield repo renders the stack first. - The banner shows on entry screens only. -- Each `⚠️` carries a keyed fix, its id and tier clause only under `[?]`. +- Every `⚠️` carries a keyed fix. +- The key appears once per screen. +- Nothing renders after the options line. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index fe7f699f..e694e40e 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -9,7 +9,7 @@ Carry out the reply. ## Output -The reply carried out and the ledger updated, then a re-scan unless the reply was read-only or an umbrella pick. +The reply carried out. ## Process From 1e2b4d8f2da472a1be25ba793a59707cca86b470 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 10:35:22 +0200 Subject: [PATCH 39/44] refactor(aidd-context): split the last compound action lines Four lines still stacked two ideas. Each case becomes a sub-bullet, each assertion its own Test point. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/01-scan.md | 3 ++- plugins/aidd-context/skills/00-onboard/actions/02-assess.md | 3 ++- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 3 ++- plugins/aidd-context/skills/00-onboard/actions/04-run.md | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md index d2ff8e81..891caff1 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -22,5 +22,6 @@ The project snapshot, printed nowhere. ## Test - Scan prints nothing. -- The snapshot carries a status per check, the detected AI tools with wiring, and the installed skills. +- The snapshot carries a status per check. +- It carries the detected AI tools with wiring, and the installed skills. - A ledgered step and a cross-branch PR never enter the snapshot's actionable set. diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md index 6aae67b5..4ba9902c 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-assess.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -15,7 +15,8 @@ The decision, ready to render. 1. **Classify.** State class per `@../references/order/screen-map.md`. 2. **Rank.** Top next action per `@../references/order/ranking.md`. - Idle: build the menu per `@../references/order/idle-menu.md`. -3. **Resolve.** Match each command to an installed skill, or name a gap by function when absent. +3. **Resolve.** Match each command to an installed skill. + - Absent: name a gap by function, never invent a command. ## Test diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index c9a8673b..9a7713cf 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -15,7 +15,8 @@ The rendered screen, and the user's reply. 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. - Framing line on the first report of the session only. - One action line per screen, carrying its key once. - - A warning's fix or a foundations step is that line. Render `👉` only when neither is. + - A warning's fix or a foundations step is that line. + - Render `👉` only when neither is. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. - Every `⚠️` shows its cause and a keyed fix. - Short lines. The screen ends at the options line. diff --git a/plugins/aidd-context/skills/00-onboard/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index e694e40e..1bb70b26 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -21,7 +21,8 @@ The reply carried out. 3. **Tier.** Running a step, apply `@../references/run/tiers.md`. 4. **Return.** On a GUIDED handoff, emit the return line per `@../references/run/return.md`. 5. **Record.** Write the handled step to the ledger per `@../references/state/done-rule.md`. -6. **Loop.** After a run or `OK` walk, re-scan. A read-only reply or umbrella pick does not. +6. **Loop.** After a run or `OK` walk, re-scan. + - A read-only reply or umbrella pick does not. ## Test From 0d211ede45ef2989e23fdffe920a4ce82f4f0ca5 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 11:13:17 +0200 Subject: [PATCH 40/44] fix(aidd-context): three defects an eight-state headless sweep exposed Codex triggered the skill, read SKILL.md, and stopped. The 'read the action file before running it' rule had been moved into the authoring contract, which no executing host ever reads, so it reached nobody at runtime. The router carries it again and the contract now says why. CLAUDE.md without a .claude/ dir left claude undetected, so memory-wiring drift was never judged and a broken block reported as healthy. A tool-exclusive file is a valid signal; only the shared AGENTS.md is not. A used-but-unwired tool rendered as missing, and a warning screen still stacked two action lines. The shapes now name three mutually exclusive action blocks, so a screen cannot carry two. Captured runs for both hosts land beside the plan. Co-Authored-By: Claude Opus 4.8 --- .../headless-runs-codex.txt | 1449 +++++++++++++++++ .../headless-runs.md | 226 +++ .../aidd-context/skills/00-onboard/SKILL.md | 2 + .../skills/00-onboard/actions/03-present.md | 5 +- .../skills/00-onboard/assets/report.md | 28 +- .../00-onboard/references/state/detection.md | 10 +- .../references/skill-authoring.md | 2 +- 7 files changed, 1703 insertions(+), 19 deletions(-) create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs-codex.txt create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs-codex.txt b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs-codex.txt new file mode 100644 index 00000000..7b7638ee --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs-codex.txt @@ -0,0 +1,1449 @@ +# Onboard — headless runs on Codex, every state + +Verbatim output of `codex exec "onboard me"` per fixture. +MCP auth errors (vercel, figma) and hook chatter are stripped as environment noise. +Generated 2026-07-10 10:44. + +### 01-greenfield + +> Empty repo, git only. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/01-greenfield +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b33-13d6-7470-80f8-47896e286b8b +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’m using `aidd-context:00-onboard` because you asked to be onboarded. I’ll read its local instructions first, then run the greenfield onboarding flow with sensible defaults. +exec +/bin/zsh -lc "pwd && sed -n '1,240p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md && sed -n '1,200p' RTK.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/01-greenfield + exited 1 in 0ms: +/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/01-greenfield +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. +sed: RTK.md: No such file or directory + +exec +/bin/zsh -lc 'wc -l /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/01-greenfield + succeeded in 0ms: + 30 /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md + +exec +/bin/zsh -lc 'ls -la' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/01-greenfield + succeeded in 0ms: +total 0 +drwxr-xr-x 3 baptistelafourcade wheel 96 Jul 10 10:37 . +drwxr-xr-x 10 baptistelafourcade wheel 320 Jul 10 10:37 .. +drwxr-xr-x 9 baptistelafourcade wheel 288 Jul 10 10:37 .git + +codex +You’re in an empty greenfield repo: only `.git` exists. The project also references `RTK.md` from `AGENTS.md`, but that file is missing. + +Recommended next step: **bootstrap the project** into an `INSTALL.md` with product goal, stack, architecture, env vars, and first implementation path. + +Choose one: + +1. **Bootstrap SaaS**: define product + architecture from scratch. +2. **Create project memory**: set up durable context files first. +3. **Plan a feature**: start from a concrete feature idea. +4. **Just explain AIDD**: quick orientation, no files. + +One constraint: this session is currently read-only, so I can guide and inspect, but I can’t create files until write access is available. +19 308 +You’re in an empty greenfield repo: only `.git` exists. The project also references `RTK.md` from `AGENTS.md`, but that file is missing. + +Recommended next step: **bootstrap the project** into an `INSTALL.md` with product goal, stack, architecture, env vars, and first implementation path. + +Choose one: + +1. **Bootstrap SaaS**: define product + architecture from scratch. +2. **Create project memory**: set up durable context files first. +3. **Plan a feature**: start from a concrete feature idea. +4. **Just explain AIDD**: quick orientation, no files. + +One constraint: this session is currently read-only, so I can guide and inspect, but I can’t create files until write access is available. +``` + +### 02-existing-no-memory + +> Code present, no memory bank. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b33-9853-7981-9ed4-9b3ce6e5e2e0 +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’ll use `aidd-context:00-onboard` because this is the project onboarding flow. I’m going to read the project instructions and the skill’s workflow first, then I’ll inspect the repo without making changes. +exec +/bin/zsh -lc "sed -n '1,220p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory +exec +/bin/zsh -lc 'pwd && ls' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory +package.json +src + + succeeded in 0ms: +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. + +exec +/bin/zsh -lc "sed -n '1,220p' RTK.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + exited 1 in 0ms: +sed: RTK.md: No such file or directory + +codex +The local `RTK.md` referenced by the instructions is not present in this fixture root, so I’ll proceed with the visible project files and call out that missing instruction file in the onboarding status. Next I’m checking the package metadata and source shape so the next-step recommendation is based on this repo, not a template. +exec +/bin/zsh -lc "sed -n '1,220p' package.json" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +{"name":"demo","version":"1.0.0"} + +exec +/bin/zsh -lc 'rg --files' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +src/index.js +package.json + +exec +/bin/zsh -lc 'find .. -name RTK.md -print' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +codex +This is a very small Node fixture: `package.json` plus one source file, with no visible memory artifacts or test setup yet. I’m reading the source file now, then I’ll give you the onboarding screen and wait for your chosen next step. +exec +/bin/zsh -lc "sed -n '1,220p' src/index.js" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +export const hi = () => "hi" + +exec +/bin/zsh -lc 'find . -maxdepth 3 -type d -print' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +. +./.git +./.git/objects +./.git/objects/58 +./.git/objects/02 +./.git/objects/pack +./.git/objects/info +./.git/objects/96 +./.git/objects/ce +./.git/objects/4f +./.git/info +./.git/logs +./.git/logs/refs +./.git/hooks +./.git/refs +./.git/refs/heads +./.git/refs/tags +./src + +exec +/bin/zsh -lc 'git status --short --branch' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory + succeeded in 0ms: +## main + +codex +**Onboarding Status** + +I scanned the repo. Current state: + +- Project is a tiny Node fixture: `package.json` and [src/index.js](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory/src/index.js:1) +- `package.json` only has `name` and `version` +- No tests, scripts, README, or project memory files are present +- Git worktree is clean on `main` +- `AGENTS.md` referenced `@RTK.md`, but no `RTK.md` exists in or above this fixture + +Recommended next step: initialize project memory, because this repo has no durable project context yet. + +Choose one: + +1. `memory` - create/refresh project memory +2. `explore` - deeper read-only repo survey +3. `plan` - make a concrete implementation plan for a feature +4. `skip` - tell me what you want to build directly +20 436 +**Onboarding Status** + +I scanned the repo. Current state: + +- Project is a tiny Node fixture: `package.json` and [src/index.js](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/02-existing-no-memory/src/index.js:1) +- `package.json` only has `name` and `version` +- No tests, scripts, README, or project memory files are present +- Git worktree is clean on `main` +- `AGENTS.md` referenced `@RTK.md`, but no `RTK.md` exists in or above this fixture + +Recommended next step: initialize project memory, because this repo has no durable project context yet. + +Choose one: + +1. `memory` - create/refresh project memory +2. `explore` - deeper read-only repo survey +3. `plan` - make a concrete implementation plan for a feature +4. `skip` - tell me what you want to build directly +``` + +### 03-drift-tool-unwired + +> Memory wired for claude. .codex/ present, no AGENTS.md. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b34-4e4c-71e3-9fbc-6eeeb381e9a9 +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’ll use the AIDD onboarding skill and first read the local project instructions so the walkthrough matches this fixture. +exec +/bin/zsh -lc "sed -n '1,240p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. + +exec +/bin/zsh -lc "pwd && rg --files -g 'AGENTS.md' -g 'RTK.md' -g 'CLAUDE.md' -g 'README*' -g 'package.json' -g 'pyproject.toml' -g 'go.mod'" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired +CLAUDE.md +package.json + +codex +The onboarding skill is intentionally lightweight: scan the project, assess the current state, then present concrete next options and wait before running guided work. I’m reading the local context and package metadata now. +exec +/bin/zsh -lc "sed -n '1,260p' CLAUDE.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired +exec +/bin/zsh -lc "sed -n '1,240p' package.json" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +{"name":"demo","version":"1.0.0"} + + succeeded in 0ms: +# CLAUDE.md + +## Memory Management + + +@aidd_docs/memory/architecture.md +@aidd_docs/memory/browsing.md +@aidd_docs/memory/codebase-map.md +@aidd_docs/memory/coding-assertions.md +@aidd_docs/memory/deployment.md +@aidd_docs/memory/project-brief.md +@aidd_docs/memory/testing.md +@aidd_docs/memory/vcs.md + + +exec +/bin/zsh -lc "find . -maxdepth 3 -type f | sort | sed 's#"'^./##'"'" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +.codex/.keep +.git/COMMIT_EDITMSG +.git/HEAD +.git/config +.git/description +.git/hooks/applypatch-msg.sample +.git/hooks/commit-msg.sample +.git/hooks/fsmonitor-watchman.sample +.git/hooks/post-update.sample +.git/hooks/pre-applypatch.sample +.git/hooks/pre-commit.sample +.git/hooks/pre-merge-commit.sample +.git/hooks/pre-push.sample +.git/hooks/pre-rebase.sample +.git/hooks/pre-receive.sample +.git/hooks/prepare-commit-msg.sample +.git/hooks/push-to-checkout.sample +.git/hooks/sendemail-validate.sample +.git/hooks/update.sample +.git/index +.git/info/exclude +.git/logs/HEAD +CLAUDE.md +aidd_docs/memory/architecture.md +aidd_docs/memory/browsing.md +aidd_docs/memory/codebase-map.md +aidd_docs/memory/coding-assertions.md +aidd_docs/memory/deployment.md +aidd_docs/memory/project-brief.md +aidd_docs/memory/testing.md +aidd_docs/memory/vcs.md +package.json +src/index.js + +exec +/bin/zsh -lc 'git status --short --branch' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +## main + +codex +This is a small fixture with AIDD memory already referenced from `CLAUDE.md`. I’m checking those memory files against the actual source so I can identify whether onboarding should start with setup, drift repair, testing, or feature work. +exec +/bin/zsh -lc "sed -n '1,240p' aidd_docs/memory/project-brief.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired +exec +/bin/zsh -lc "sed -n '1,240p' aidd_docs/memory/codebase-map.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired +exec +/bin/zsh -lc "sed -n '1,240p' aidd_docs/memory/architecture.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +# project-brief + +Real content for the project-brief memory file of this demo project. + + succeeded in 0ms: +# codebase-map + +Real content for the codebase-map memory file of this demo project. + + succeeded in 0ms: +# architecture + +Real content for the architecture memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,240p' aidd_docs/memory/testing.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +# testing + +Real content for the testing memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,240p' aidd_docs/memory/coding-assertions.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +# coding-assertions + +Real content for the coding-assertions memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,240p' src/index.js" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +export const hi = () => "hi" + +codex +The memory files exist but contain placeholder “real content” rather than actionable project facts. I’m doing one more pass over the remaining memory and available scripts before I present the onboarding screen. +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/browsing.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +# browsing + +Real content for the browsing memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/deployment.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/vcs.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +# deployment + +Real content for the deployment memory file of this demo project. + + succeeded in 0ms: +# vcs + +Real content for the vcs memory file of this demo project. + +exec +/bin/zsh -lc 'git log --oneline -5' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +5a509fb init + +exec +/bin/zsh -lc 'npm run --silent 2>/dev/null || true' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/03-drift-tool-unwired + succeeded in 0ms: +codex +**Onboarding Screen** + +Current state: +- Repo is on `main`, clean, one commit: `5a509fb init`. +- `CLAUDE.md` wires AIDD memory files under `aidd_docs/memory/`. +- Those memory files exist, but they’re placeholders rather than useful project facts. +- `package.json` has no scripts. +- Source is minimal: `src/index.js` exports `hi()`. +- `AGENTS.md` references `RTK.md`, but no `RTK.md` is present in this workspace. + +Recommended next step: **repair project memory drift**. The project is wired for AIDD, but the memory content does not describe the actual codebase. + +Pick one: + +1. **Refresh memory**: regenerate useful `aidd_docs/memory/*` content from the repo. +2. **Explore first**: produce a read-only project map and identify gaps. +3. **Add tests/scripts**: wire basic npm scripts and a minimal test path. +4. **Audit**: run a read-only quality scan and report risks. + +Reply with `1`, `2`, `3`, or `4`. +23 389 +**Onboarding Screen** + +Current state: +- Repo is on `main`, clean, one commit: `5a509fb init`. +- `CLAUDE.md` wires AIDD memory files under `aidd_docs/memory/`. +- Those memory files exist, but they’re placeholders rather than useful project facts. +- `package.json` has no scripts. +- Source is minimal: `src/index.js` exports `hi()`. +- `AGENTS.md` references `RTK.md`, but no `RTK.md` is present in this workspace. + +Recommended next step: **repair project memory drift**. The project is wired for AIDD, but the memory content does not describe the actual codebase. + +Pick one: + +1. **Refresh memory**: regenerate useful `aidd_docs/memory/*` content from the repo. +2. **Explore first**: produce a read-only project map and identify gaps. +3. **Add tests/scripts**: wire basic npm scripts and a minimal test path. +4. **Audit**: run a read-only quality scan and report risks. + +Reply with `1`, `2`, `3`, or `4`. +``` + +### 04-drift-block-offshape + +> Memory synced, CLAUDE.md block off canonical shape. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b35-5173-7281-88bc-02074997578d +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’ll use the `aidd-context:00-onboard` skill because this is an AIDD onboarding request. I’m going to read the project instructions and the onboarding skill first, then I’ll inspect the repo enough to give you the right next step. +exec +/bin/zsh -lc "sed -n '1,260p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. + +exec +/bin/zsh -lc "sed -n '1,260p' RTK.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + exited 1 in 0ms: +sed: RTK.md: No such file or directory + +exec +/bin/zsh -lc "pwd && rg --files -g 'RTK.md' -g 'AGENTS.md' -g 'CLAUDE.md' -g 'README*' -g 'package.json' -g 'pyproject.toml' -g 'go.mod' -g 'Cargo.toml'" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +CLAUDE.md +package.json + +codex +The onboarding skill is intentionally lightweight: scan the project, assess the next step, present options, and wait for your explicit choice before running guided work. The referenced `RTK.md` is not present in this fixture, so I’m using the available project files instead. +exec +/bin/zsh -lc "sed -n '1,260p' package.json" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +exec +/bin/zsh -lc "sed -n '1,260p' CLAUDE.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +{"name":"demo","version":"1.0.0"} + + succeeded in 0ms: +# CLAUDE.md + + +@aidd_docs/memory/architecture.md +@aidd_docs/memory/browsing.md +@aidd_docs/memory/codebase-map.md +@aidd_docs/memory/coding-assertions.md +@aidd_docs/memory/deployment.md +@aidd_docs/memory/project-brief.md +@aidd_docs/memory/testing.md +@aidd_docs/memory/vcs.md + + +exec +/bin/zsh -lc 'rg --files' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +src/index.js +CLAUDE.md +aidd_docs/memory/deployment.md +aidd_docs/memory/project-brief.md +aidd_docs/memory/browsing.md +aidd_docs/memory/testing.md +aidd_docs/memory/codebase-map.md +aidd_docs/memory/coding-assertions.md +aidd_docs/memory/architecture.md +aidd_docs/memory/vcs.md +package.json + +exec +/bin/zsh -lc 'find . -maxdepth 3 -type d | sort' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +. +./.git +./.git/hooks +./.git/info +./.git/logs +./.git/logs/refs +./.git/objects +./.git/objects/12 +./.git/objects/29 +./.git/objects/37 +./.git/objects/4f +./.git/objects/58 +./.git/objects/6e +./.git/objects/74 +./.git/objects/87 +./.git/objects/8b +./.git/objects/95 +./.git/objects/96 +./.git/objects/9f +./.git/objects/a6 +./.git/objects/c3 +./.git/objects/ce +./.git/objects/e9 +./.git/objects/info +./.git/objects/pack +./.git/refs +./.git/refs/heads +./.git/refs/tags +./aidd_docs +./aidd_docs/memory +./src + +codex +This is a very small Node fixture with an AIDD memory bank already wired through `CLAUDE.md`. I’m reading those memory files and the current source so the onboarding recommendation is based on the project’s recorded state, not just the directory shape. +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/project-brief.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/codebase-map.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/deployment.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +# codebase-map + +Real content for the codebase-map memory file of this demo project. + + succeeded in 0ms: +# project-brief + +Real content for the project-brief memory file of this demo project. + + succeeded in 0ms: +# deployment + +Real content for the deployment memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/architecture.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/vcs.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +# architecture + +Real content for the architecture memory file of this demo project. + + succeeded in 0ms: +# vcs + +Real content for the vcs memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/coding-assertions.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +exec +/bin/zsh -lc "sed -n '1,260p' src/index.js" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +# coding-assertions + +Real content for the coding-assertions memory file of this demo project. + + succeeded in 0ms: +export const hi = () => "hi" + +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/testing.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/memory/browsing.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +# testing + +Real content for the testing memory file of this demo project. + + succeeded in 0ms: +# browsing + +Real content for the browsing memory file of this demo project. + +exec +/bin/zsh -lc 'git status --short --branch' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape + succeeded in 0ms: +## main +M CLAUDE.md + +codex +You’re onboarded to the current fixture. + +Current state: +- AIDD memory is wired in [CLAUDE.md](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape/CLAUDE.md:1). +- Memory files exist under `aidd_docs/memory/`, but their contents are placeholder-style. +- Codebase is tiny: [src/index.js](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape/src/index.js:1) exports `hi()`. +- `package.json` has no scripts. +- Git is on `main` with `CLAUDE.md` modified. +- The referenced `RTK.md` from `AGENTS.md` instructions is not present in this workspace. + +Recommended next step: refresh or validate the AIDD memory, because the project is initialized but the memory content does not yet describe the real codebase. + +Reply with one: + +1. `refresh memory` - rebuild the AIDD memory files from the current project. +2. `explore` - give you a fuller project map without editing files. +3. `plan feature` - start from a feature idea and produce an implementation plan. +4. `audit` - review the current project for gaps and risks. +23 168 +You’re onboarded to the current fixture. + +Current state: +- AIDD memory is wired in [CLAUDE.md](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape/CLAUDE.md:1). +- Memory files exist under `aidd_docs/memory/`, but their contents are placeholder-style. +- Codebase is tiny: [src/index.js](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/04-drift-block-offshape/src/index.js:1) exports `hi()`. +- `package.json` has no scripts. +- Git is on `main` with `CLAUDE.md` modified. +- The referenced `RTK.md` from `AGENTS.md` instructions is not present in this workspace. + +Recommended next step: refresh or validate the AIDD memory, because the project is initialized but the memory content does not yet describe the real codebase. + +Reply with one: + +1. `refresh memory` - rebuild the AIDD memory files from the current project. +2. `explore` - give you a fuller project map without editing files. +3. `plan feature` - start from a feature idea and produce an implementation plan. +4. `audit` - review the current project for gaps and risks. +``` + +### 05-midwork + +> plan status: in-progress, an uncommitted file. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b36-86ce-72b1-835b-a5deb516275f +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’ll use the `aidd-context:00-onboard` skill for this, and first I’m going to read the project instructions plus the onboarding skill so I follow the repo’s intended workflow. +exec +/bin/zsh -lc "pwd && rg --files -g 'AGENTS.md' -g 'RTK.md' -g 'SKILL.md'" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + exited 1 in 0ms: +/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + +exec +/bin/zsh -lc "sed -n '1,240p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. + +codex +The onboarding skill is intentionally lightweight: scan the project, assess the next useful step, present options, then wait before running any guided action. I’m checking what exists in this fixture so the recommendation is based on the actual state rather than a generic path. +exec +/bin/zsh -lc 'find .. -name AGENTS.md -o -name RTK.md -o -name CLAUDE.md -o -name README.md -o -name package.json -o -name pyproject.toml -o -name Cargo.toml -o -name go.mod -o -name .git -o -name .aidd -maxdepth 4' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +../03-drift-tool-unwired/package.json +../03-drift-tool-unwired/.git +../03-drift-tool-unwired/CLAUDE.md +../01-greenfield/.git +../02-existing-no-memory/package.json +../02-existing-no-memory/.git +../04-drift-block-offshape/package.json +../04-drift-block-offshape/.git +../04-drift-block-offshape/CLAUDE.md +../08-no-vcs/package.json +../08-no-vcs/CLAUDE.md +../07-plan-broken-status/package.json +../07-plan-broken-status/.git +../07-plan-broken-status/CLAUDE.md +../06-idle/package.json +../06-idle/.git +../06-idle/CLAUDE.md +../05-midwork/package.json +../05-midwork/.git +../05-midwork/CLAUDE.md + +exec +/bin/zsh -lc 'rg --files' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +src/wip.js +src/index.js +CLAUDE.md +aidd_docs/memory/deployment.md +aidd_docs/memory/project-brief.md +aidd_docs/memory/browsing.md +aidd_docs/memory/testing.md +aidd_docs/memory/codebase-map.md +aidd_docs/memory/coding-assertions.md +aidd_docs/memory/architecture.md +aidd_docs/memory/vcs.md +aidd_docs/tasks/2026_07/demo/plan.md +package.json + +exec +/bin/zsh -lc 'ls -la' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +total 16 +drwxr-xr-x 7 baptistelafourcade wheel 224 Jul 10 10:37 . +drwxr-xr-x 10 baptistelafourcade wheel 320 Jul 10 10:37 .. +drwxr-xr-x 12 baptistelafourcade wheel 384 Jul 10 10:37 .git +-rw-r--r-- 1 baptistelafourcade wheel 338 Jul 10 10:37 CLAUDE.md +drwxr-xr-x 4 baptistelafourcade wheel 128 Jul 10 10:37 aidd_docs +-rw-r--r-- 1 baptistelafourcade wheel 34 Jul 10 10:37 package.json +drwxr-xr-x 4 baptistelafourcade wheel 128 Jul 10 10:37 src + +codex +This project already has AIDD memory and an active-looking task plan, so I’m reading those before I recommend the next step. I also checked for the referenced `RTK.md`; it does not appear to be present in this fixture. +exec +/bin/zsh -lc "sed -n '1,220p' CLAUDE.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/tasks/2026_07/demo/plan.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +--- +status: in-progress +--- + +# Plan: demo + + succeeded in 0ms: +# CLAUDE.md + +## Memory Management + + +@aidd_docs/memory/architecture.md +@aidd_docs/memory/browsing.md +@aidd_docs/memory/codebase-map.md +@aidd_docs/memory/coding-assertions.md +@aidd_docs/memory/deployment.md +@aidd_docs/memory/project-brief.md +@aidd_docs/memory/testing.md +@aidd_docs/memory/vcs.md + + +exec +/bin/zsh -lc 'git status --short --branch' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +## main +?? src/wip.js + +exec +/bin/zsh -lc "for f in aidd_docs/memory/*.md; do printf '\\n## %s\\n' \""'$f"; sed -n '"'1,180p' \""'$f"; done' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: + +## aidd_docs/memory/architecture.md +# architecture + +Real content for the architecture memory file of this demo project. + +## aidd_docs/memory/browsing.md +# browsing + +Real content for the browsing memory file of this demo project. + +## aidd_docs/memory/codebase-map.md +# codebase-map + +Real content for the codebase-map memory file of this demo project. + +## aidd_docs/memory/coding-assertions.md +# coding-assertions + +Real content for the coding-assertions memory file of this demo project. + +## aidd_docs/memory/deployment.md +# deployment + +Real content for the deployment memory file of this demo project. + +## aidd_docs/memory/project-brief.md +# project-brief + +Real content for the project-brief memory file of this demo project. + +## aidd_docs/memory/testing.md +# testing + +Real content for the testing memory file of this demo project. + +## aidd_docs/memory/vcs.md +# vcs + +Real content for the vcs memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' package.json && sed -n '1,220p' src/index.js && sed -n '1,220p' src/wip.js" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/05-midwork + succeeded in 0ms: +{"name":"demo","version":"1.0.0"} +export const hi = () => "hi" +export const wip = 1 + +codex +**Onboarding** + +You’re in a mid-work AIDD project. + +Current state: +- AIDD memory is wired through `CLAUDE.md` and all memory files exist. +- Active plan: `aidd_docs/tasks/2026_07/demo/plan.md` +- Plan status: `in-progress`, but it has no real steps or acceptance criteria. +- Git branch: `main` +- Worktree: one untracked file, `src/wip.js` +- `AGENTS.md` references `RTK.md`, but `RTK.md` is not present in this fixture. + +Best next step: clarify or repair the active plan before implementing anything. Otherwise there is no reliable target to continue from. + +Reply with one of these: +- `assess plan` - I’ll inspect whether the current plan is usable. +- `continue work` - I’ll proceed from the current code and plan as best as possible. +- `refresh memory` - I’ll regenerate/validate project memory first. +22 254 +**Onboarding** + +You’re in a mid-work AIDD project. + +Current state: +- AIDD memory is wired through `CLAUDE.md` and all memory files exist. +- Active plan: `aidd_docs/tasks/2026_07/demo/plan.md` +- Plan status: `in-progress`, but it has no real steps or acceptance criteria. +- Git branch: `main` +- Worktree: one untracked file, `src/wip.js` +- `AGENTS.md` references `RTK.md`, but `RTK.md` is not present in this fixture. + +Best next step: clarify or repair the active plan before implementing anything. Otherwise there is no reliable target to continue from. + +Reply with one of these: +- `assess plan` - I’ll inspect whether the current plan is usable. +- `continue work` - I’ll proceed from the current code and plan as best as possible. +- `refresh memory` - I’ll regenerate/validate project memory first. +``` + +### 06-idle + +> Everything committed, nothing pending. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b37-5fd9-7441-b287-3e136eac5140 +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’ll use the `aidd-context:00-onboard` skill because this is the project onboarding flow. I’m going to read its instructions and the local project guidance first so the onboarding matches this repo. +exec +/bin/zsh -lc "sed -n '1,220p' RTK.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle +exec +/bin/zsh -lc "sed -n '1,220p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. + + exited 1 in 0ms: +sed: RTK.md: No such file or directory + +exec +/bin/zsh -lc "pwd && rg --files -g '"'!*node_modules*'"' -g '"'!*.git*'"'" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle +src/index.js +CLAUDE.md +aidd_docs/memory/deployment.md +aidd_docs/memory/project-brief.md +aidd_docs/memory/browsing.md +aidd_docs/memory/testing.md +aidd_docs/memory/codebase-map.md +aidd_docs/memory/coding-assertions.md +aidd_docs/memory/architecture.md +aidd_docs/memory/vcs.md +package.json + +codex +`RTK.md` is referenced by the local instructions but is not present in this fixture. The repo does have AIDD memory files, so I’m reading those plus the small code surface to assess the current state. +exec +/bin/zsh -lc "sed -n '1,220p' src/index.js" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +export const hi = () => "hi" + +exec +/bin/zsh -lc "sed -n '1,220p' package.json" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle +exec +/bin/zsh -lc "sed -n '1,220p' CLAUDE.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +{"name":"demo","version":"1.0.0"} + + succeeded in 0ms: +# CLAUDE.md + +## Memory Management + + +@aidd_docs/memory/architecture.md +@aidd_docs/memory/browsing.md +@aidd_docs/memory/codebase-map.md +@aidd_docs/memory/coding-assertions.md +@aidd_docs/memory/deployment.md +@aidd_docs/memory/project-brief.md +@aidd_docs/memory/testing.md +@aidd_docs/memory/vcs.md + + +exec +/bin/zsh -lc "for f in aidd_docs/memory/*.md; do printf '\\n## %s\\n' \""'$f"; sed -n '"'1,220p' \""'$f"; done' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: + +## aidd_docs/memory/architecture.md +# architecture + +Real content for the architecture memory file of this demo project. + +## aidd_docs/memory/browsing.md +# browsing + +Real content for the browsing memory file of this demo project. + +## aidd_docs/memory/codebase-map.md +# codebase-map + +Real content for the codebase-map memory file of this demo project. + +## aidd_docs/memory/coding-assertions.md +# coding-assertions + +Real content for the coding-assertions memory file of this demo project. + +## aidd_docs/memory/deployment.md +# deployment + +Real content for the deployment memory file of this demo project. + +## aidd_docs/memory/project-brief.md +# project-brief + +Real content for the project-brief memory file of this demo project. + +## aidd_docs/memory/testing.md +# testing + +Real content for the testing memory file of this demo project. + +## aidd_docs/memory/vcs.md +# vcs + +Real content for the vcs memory file of this demo project. + +codex +This is a very small demo fixture: one exported function, a bare `package.json`, and placeholder-style AIDD memory files. I’m doing one quick status check now so the recommended next step is based on the actual workspace state, not a stale assumption. +exec +/bin/zsh -lc 'ls -la' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +total 16 +drwxr-xr-x 7 baptistelafourcade wheel 224 Jul 10 10:37 . +drwxr-xr-x 10 baptistelafourcade wheel 320 Jul 10 10:37 .. +drwxr-xr-x 12 baptistelafourcade wheel 384 Jul 10 10:37 .git +-rw-r--r-- 1 baptistelafourcade wheel 338 Jul 10 10:37 CLAUDE.md +drwxr-xr-x 3 baptistelafourcade wheel 96 Jul 10 10:37 aidd_docs +-rw-r--r-- 1 baptistelafourcade wheel 34 Jul 10 10:37 package.json +drwxr-xr-x 3 baptistelafourcade wheel 96 Jul 10 10:37 src + +exec +/bin/zsh -lc 'git status --short --branch' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +## main + +exec +/bin/zsh -lc 'find .. -name RTK.md -maxdepth 4 -print' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle + succeeded in 0ms: +codex +**Onboarding** + +Current project state: + +- Repo is clean on `main`. +- `RTK.md` is referenced but missing. +- AIDD memory exists under `aidd_docs/memory/`, but the files contain demo placeholder text. +- Code surface is tiny: [src/index.js](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle/src/index.js:1) exports `hi = () => "hi"`. +- `package.json` has no scripts, dependencies, test command, or module metadata beyond name/version. +- Current workspace is read-only, so I can assess and guide, but not modify files unless permissions change. + +Best next step: refresh project memory so AIDD has real architecture, testing, deployment, and codebase context instead of placeholders. + +Choose one: + +1. `scan` - I’ll do a deeper read-only project survey and report what is real. +2. `assess` - I’ll turn the current state into prioritized next steps. +3. `memory` - I’ll tell you exactly what should be written into each AIDD memory file. +4. `feature` - Give me a feature/bug, and I’ll plan it against this repo. +21 107 +**Onboarding** + +Current project state: + +- Repo is clean on `main`. +- `RTK.md` is referenced but missing. +- AIDD memory exists under `aidd_docs/memory/`, but the files contain demo placeholder text. +- Code surface is tiny: [src/index.js](/private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/06-idle/src/index.js:1) exports `hi = () => "hi"`. +- `package.json` has no scripts, dependencies, test command, or module metadata beyond name/version. +- Current workspace is read-only, so I can assess and guide, but not modify files unless permissions change. + +Best next step: refresh project memory so AIDD has real architecture, testing, deployment, and codebase context instead of placeholders. + +Choose one: + +1. `scan` - I’ll do a deeper read-only project survey and report what is real. +2. `assess` - I’ll turn the current state into prioritized next steps. +3. `memory` - I’ll tell you exactly what should be written into each AIDD memory file. +4. `feature` - Give me a feature/bug, and I’ll plan it against this repo. +``` + +### 07-plan-broken-status + +> plan.md carries a garbage status field. + +```text +Reading additional input from stdin... +OpenAI Codex v0.143.0 +-------- +workdir: /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status +model: gpt-5.5 +provider: openai +approval: never +sandbox: read-only +reasoning effort: high +reasoning summaries: none +session id: 019f4b38-0df7-7be3-bf94-e4a0f2427d3e +-------- +user +onboard me +warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest. +codex +I’ll use the `aidd-context:00-onboard` skill for the onboarding flow and first read its instructions plus the repo’s local `RTK.md` guidance. +exec +/bin/zsh -lc "sed -n '1,240p' /Users/baptistelafourcade/.codex/plugins/cache/aidd-framework/aidd-context/2.2.0/skills/00-onboard/SKILL.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status +exec +/bin/zsh -lc "sed -n '1,240p' RTK.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +--- +name: 00-onboard +description: Guide a project's journey through AIDD, from first setup to shipping a feature. Use when the user says onboard me, where do I start, or what to do next. Not for listing every installed surface. +argument-hint: scan | assess | present | run +--- + +# Onboard + +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` + +## Actions + +| # | Action | Does | +| -- | ------- | -------------------- | +| 01 | scan | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | + +## Transversal rules + +- Guide, do not lecture or dump. +- Name real commands only, never invented ones. +- Never run a GUIDED step unattended. +- Never test a plugin version against a registry. +- Never trust a stale status. +- Wait for an explicit reply before running anything. + + exited 1 in 0ms: +sed: RTK.md: No such file or directory + +exec +/bin/zsh -lc "rg --files -g '"'!*node_modules*'"' -g '"'!*.png'"' -g '"'!*.jpg'"' -g '"'!*.jpeg'"' -g '"'!*.gif'"' -g '"'!*.pdf'"'" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +src/index.js +CLAUDE.md +aidd_docs/memory/deployment.md +aidd_docs/memory/project-brief.md +aidd_docs/memory/browsing.md +aidd_docs/memory/testing.md +aidd_docs/memory/codebase-map.md +aidd_docs/memory/coding-assertions.md +aidd_docs/memory/architecture.md +aidd_docs/memory/vcs.md +aidd_docs/tasks/2026_07/demo/plan.md +package.json + +codex +The onboard skill is intentionally lightweight: scan, assess, present options, then wait. `RTK.md` was not in this fixture root, so I’m checking the nearby project files and memory instead of assuming those instructions. +exec +/bin/zsh -lc "sed -n '1,220p' CLAUDE.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status +exec +/bin/zsh -lc "sed -n '1,220p' package.json" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# CLAUDE.md + +## Memory Management + + +@aidd_docs/memory/architecture.md +@aidd_docs/memory/browsing.md +@aidd_docs/memory/codebase-map.md +@aidd_docs/memory/coding-assertions.md +@aidd_docs/memory/deployment.md +@aidd_docs/memory/project-brief.md +@aidd_docs/memory/testing.md +@aidd_docs/memory/vcs.md + + + succeeded in 0ms: +{"name":"demo","version":"1.0.0"} + +exec +/bin/zsh -lc 'find .. -name RTK.md -print' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +exec +/bin/zsh -lc "sed -n '1,260p' aidd_docs/tasks/2026_07/demo/plan.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +--- +status: ??? garbage +--- + +# Plan: demo + +codex +This fixture is small and looks intentionally broken: the only task plan has `status: ??? garbage`. I’m reading the project memory now to determine the correct next step rather than treating that status as valid. +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/project-brief.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/coding-assertions.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# project-brief + +Real content for the project-brief memory file of this demo project. + + succeeded in 0ms: +# coding-assertions + +Real content for the coding-assertions memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/architecture.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# architecture + +Real content for the architecture memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/codebase-map.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# codebase-map + +Real content for the codebase-map memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/vcs.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/testing.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# vcs + +Real content for the vcs memory file of this demo project. + + succeeded in 0ms: +# testing + +Real content for the testing memory file of this demo project. + +codex +The memory files are present but placeholder-level. I’m doing one last structural check so the onboarding screen can point at concrete commands and the malformed plan status accurately. +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/deployment.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# deployment + +Real content for the deployment memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' aidd_docs/memory/browsing.md" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +# browsing + +Real content for the browsing memory file of this demo project. + +exec +/bin/zsh -lc "sed -n '1,220p' src/index.js" in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +export const hi = () => "hi" + +exec +/bin/zsh -lc 'git status --short' in /private/tmp/claude-501/-Users-baptistelafourcade-Projects-freelance-aidd-aidd-framework/e56b2570-3814-4f77-9b5e-5b026f1c7453/scratchpad/fixtures/07-plan-broken-status + succeeded in 0ms: +codex +**Onboarding** + +I found a tiny demo project with AIDD memory wired through `CLAUDE.md`, one source file, and one task plan: + +- Code: `src/index.js` +- Memory: `aidd_docs/memory/*.md` +- Plan: `aidd_docs/tasks/2026_07/demo/plan.md` +- Current issue: the plan frontmatter has an invalid status: `??? garbage` + +I would not trust that plan status. The next step should be to decide how to recover it. + +Choose one: + +1. **Repair plan status**: inspect the intended AIDD status values and normalize the broken plan. +2. **Refresh memory**: rebuild or validate the project memory before touching the plan. +3. **Explore only**: produce a short project map and recommended next actions. + +Reply with `1`, `2`, or `3`. +23 131 +**Onboarding** + +I found a tiny demo project with AIDD memory wired through `CLAUDE.md`, one source file, and one task plan: + +- Code: `src/index.js` +- Memory: `aidd_docs/memory/*.md` +- Plan: `aidd_docs/tasks/2026_07/demo/plan.md` +- Current issue: the plan frontmatter has an invalid status: `??? garbage` + +I would not trust that plan status. The next step should be to decide how to recover it. + +Choose one: + +1. **Repair plan status**: inspect the intended AIDD status values and normalize the broken plan. +2. **Refresh memory**: rebuild or validate the project memory before touching the plan. +3. **Explore only**: produce a short project map and recommended next actions. + +Reply with `1`, `2`, or `3`. +``` + +### 08-no-vcs + +> Code and memory, no git repository. + +```text +Reading additional input from stdin... +Not inside a trusted directory and --skip-git-repo-check was not specified. +``` + +CAPTURE_DONE diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs.md new file mode 100644 index 00000000..8fb0cea3 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/headless-runs.md @@ -0,0 +1,226 @@ +# Onboard — headless runs, every state + +Each block is the verbatim output of `claude -p "onboard me"` in a purpose-built fixture. +Generated 2026-07-10 10:43. + +### 01-greenfield + +> Empty repo, git only. No code, no memory, no tool config. + +```text +``` + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 + +👋 Welcome. AIDD guides a project from first setup to shipped code, one step at a time. + +Your AIDD setup: + AI tools none yet + Plugins aidd-context · aidd-dev · aidd-pm · aidd-refine · aidd-vcs · aidd-orchestrator ✅ + Memory ❌ not set up yet + +Empty repo — greenfield. Three foundation steps before the dev flow opens. + +Foundations — step 1 of 3 + + tech stack design and validate the architecture into INSTALL.md + (every later step reads this) + + step 2 project memory — capture the project knowledge into aidd_docs/memory/ + step 3 memory wiring — load that knowledge into your AI tool's context file + +👉 Type [1] to start. skip [s] · what's this [?] · OK walks all 3 · flow [m] +``` +``` + +### 02-existing-no-memory + +> Code present, no memory bank. The memory-first path. + +```text +```txt + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 +``` + +👋 Welcome. AIDD gives your project a memory, then a flow to ship features through. + +Your AIDD setup: +```txt + AI tools none yet + Plugins aidd-context · aidd-dev · aidd-pm · aidd-refine · aidd-vcs ✅ + Memory ❌ not set up yet +``` + +Code exists, memory does not. AI reads project fresh every session. + +**Foundations — step 1 of 2** +```txt + project knowledge saved read codebase, write memory bank + (AI stop guessing your stack, structure, conventions) + + step 2 knowledge loaded by the AI — wire memory into your AI tool's context file +``` + +👉 Type **[1]** to start. skip [s] · what's this [?] · OK walks both · flow [m] +``` + +### 03-drift-tool-unwired + +> Memory wired for claude. .codex/ present with no AGENTS.md. + +```text +```txt + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 + +👋 AIDD walks your project from setup to shipped code, one step at a time. + +Your AIDD setup: + AI tools codex ❌ + Plugins aidd-context · aidd-dev · aidd-pm · aidd-refine · aidd-vcs ✅ + Memory aidd_docs · 8 synced ✅ + +⚠️ Memory written, but codex can't read it — no AGENTS.md carries the memory block. + → Type [1] to wire memory into codex. + +👉 Type [1] to start. skip [s] · what's this [?] · flow [m] +``` +``` + +### 04-drift-block-offshape + +> Memory bank synced, but the CLAUDE.md block is off canonical shape. + +```text +```txt + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 + +👋 AIDD guides your project from setup to shipped code. Here is where you stand. + +Your AIDD setup: + AI tools none yet + Plugins aidd-context · aidd-dev · aidd-pm · aidd-refine · aidd-vcs ✅ + Memory aidd_docs · 8 synced ✅ + +Foundations are met. Nothing is in flight. Your code has no tests. + +👉 Next: cover src/ with tests [1] + start new work [2] · audit [3] · explore [4] · what's this [?] · flow [m] +``` +``` + +### 05-midwork + +> Full setup, plan status: in-progress, an uncommitted file. + +```text +🔍 Mid-work. Plan `demo` is `in-progress` — code started (`src/wip.js` untracked), not yet asserted. + +```txt + Flow: brainstorm ✅ → spec* → plan ✅ → [implement] → assert → review → commit → PR + + Setup: AI tools claude ✅ + Memory aidd_docs · 8 synced ✅ +``` + +👉 Next: finish implementing the plan `[1]` + assert instead `[2]` · no tests in repo, add coverage `[3]` · flow `[m]` · what's this `[?]` +``` + +### 06-idle + +> Full setup, everything committed, nothing pending. + +```text +```txt + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 + +👋 AIDD guides your project from setup to shipped code. Here is where you stand. + +Your AIDD setup: + AI tools none yet + Plugins aidd-context · aidd-dev · aidd-pm · aidd-refine · aidd-vcs · aidd-orchestrator ✅ + Memory aidd_docs · 8 synced ✅ + +Foundations done, no work in flight. Your source has no tests. + +👉 Next: add test coverage [1] + improve the project [2] · start new work [3] · explore [4] · what's this [?] · flow [m] +``` +``` + +### 07-plan-broken-status + +> Full setup, plan.md carries a garbage status field. + +```text +🔍 Plan exists but its status is unreadable — flow pinned at `plan`. + +```txt + Flow: brainstorm ✅ → spec* ✅ → [plan] → implement → assert → review → commit → PR +``` + +⚠️ `aidd_docs/tasks/2026_07/demo/plan.md` has `status: ??? garbage` — not a valid status, so the flow can't place you. + Valid: `pending` · `in-progress` · `implemented` · `reviewed` · `blocked` + +→ Type **[1]** to repair the status field (you edit it, I show the line). + re-plan from scratch [2] · what's this [?] · stop +``` + +### 08-no-vcs + +> Code and memory, but no git repository at all. + +```text +```txt + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 + +👋 AIDD guides your project from setup to shipped code. Here is where yours stands. + +Your AIDD setup: + AI tools none yet + Plugins aidd-context · aidd-dev · aidd-pm · aidd-refine · aidd-vcs ✅ + Memory aidd_docs · 8 synced ✅ + +Foundations met. Code in src/, no tests yet, and no version control — so no review or pull-request stage to read. + +👉 Next: cover src/ with tests [1] + init the repo [2] · audit the code [3] · what's this [?] · flow [m] +``` +``` + +CAPTURE_DONE diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 7f4712e0..80746261 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -11,6 +11,8 @@ flowchart LR scan --> assess --> present --> run --> scan ``` +Run the actions in that order, looping. Read an action's file in `actions/` before running it. + ## Actions | # | Action | Does | diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 9a7713cf..46216e5e 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -14,10 +14,9 @@ The rendered screen, and the user's reply. 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. - Framing line on the first report of the session only. - - One action line per screen, carrying its key once. - - A warning's fix or a foundations step is that line. - - Render `👉` only when neither is. + - Exactly one action block per screen, carrying its key once. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. + - A used tool that lacks the block is `⚠️`, never `❌`. Only a missing required foundation takes `❌`. - Every `⚠️` shows its cause and a keyed fix. - Short lines. The screen ends at the options line. - Command ids, tier clauses, and lookahead only under `[?]`. diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index 2a035f8e..811a6751 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -12,13 +12,13 @@ Your AIDD setup: Plugins ✅ Memory - + - [1]> + · flow [m] ``` -## Foundations step +## Action block — foundations step ```txt Foundations — step of @@ -28,7 +28,20 @@ Foundations — step of — > -👉 Type [1] to start. skip [s] · what's this [?] · OK walks all · flow [m] +👉 Type [1] to start. skip [s] +``` + +## Action block — warning with a fix + +```txt +⚠️ + → Type [1] to . +``` + +## Action block — next action + +```txt +👉 [1] ``` ## Where you are — mid-work @@ -42,13 +55,6 @@ Foundations — step of ``` -## Warning line - -```txt -⚠️ - → Type [1] to . -``` - ## [?] detail ```txt diff --git a/plugins/aidd-context/skills/00-onboard/references/state/detection.md b/plugins/aidd-context/skills/00-onboard/references/state/detection.md index 2a8c535c..f6601115 100644 --- a/plugins/aidd-context/skills/00-onboard/references/state/detection.md +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -2,15 +2,17 @@ Which AI tools the project uses, and whether each has its memory wired. For the state block's AI-tools line. -| Tool | Used when (its own dir) | Wired when this file has the block | +A tool is used when its own dir exists, or when a file only that tool reads exists. A file several tools read (`AGENTS.md`) is a wiring target, never a detection signal. + +| Tool | Used when | Wired when this file has the block | | -------- | ------------------------------------------------------------------------------------ | ---------------------------------- | -| claude | `.claude/` | `CLAUDE.md` | +| claude | `.claude/` or `CLAUDE.md` | `CLAUDE.md` | | codex | `.codex/` | `AGENTS.md` | -| cursor | `.cursor/` | `AGENTS.md` | +| cursor | `.cursor/` or `.cursorrules` | `AGENTS.md` | | opencode | `.opencode/` | `AGENTS.md` | | copilot | `.github/copilot-instructions.md` or `.github/{instructions,agents,skills,prompts}/` | `.github/copilot-instructions.md` | -- Detect by the dir only — `AGENTS.md` and `CLAUDE.md` are wiring targets, not detection signals. - Detected tools only. An unused optional tool is omitted, never crossed. - No tool detected at all: the row reads `none yet`, uncrossed. The memory row's `❌` already carries the gap. +- A used tool whose file lacks the block is not wired, and needs wiring. - Missing memory is a foundation status, not a tool row (see `zones.md`). diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index 515e77ee..ae202716 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -53,7 +53,7 @@ The router: YAML frontmatter + markdown body. - Body order: a tiny `# Title`, the chaining schema, the action table, then the transversal rules. No restated intro sentence; the `description` already states the what. - **Chaining schema.** A pipeline shows its chain: a one-line arrow schema `a → b → c` for a straight run, or a small Mermaid flowchart when the flow loops back (a cycle is not a linear chain, so R14 permits Mermaid here). A menu shows the line `Pick one per request.` and no schema. The mode reads itself; no field states it. - **Action table.** Columns `# | Action | Does`; `Does` is verb-led and telegraphic (verb + object). A menu drops the `#` column. No `Input` column: an action's input lives in its own `## Input`. -- Standing rule for every skill: read an action's file just before running it, not only the router table. Stated here once, never repeated in a SKILL.md body. +- The body MUST carry the operative line: run the actions in the schema's order, and read an action's file before running it. This contract is authoring guidance that no executing host ever reads, so a rule left only here reaches nobody at runtime. Codex proved it: given a router without that line, it read SKILL.md and stopped. The `name` field is NOT the invocation token. The host builds the address from the plugin and folder, each in its own scheme. A colon or prefix in `name` breaks loading on some hosts. In prose, refer to a skill as `plugin:folder`, never `plugin:folder:action`. From 746041512e8c4995db32e56e6d09510817e39e59 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 11:32:45 +0200 Subject: [PATCH 41/44] revert(aidd-context): keep skill-authoring out of this branch The contract changes this rework leaned on (nested references, router format, the runtime read-the-action rule) ship in their own pair on the next milestone. This branch touches onboard only. Co-Authored-By: Claude Opus 4.8 --- .../04-skill-generate/references/skill-authoring.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index ae202716..1919a548 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -4,9 +4,9 @@ The contract every generated skill must satisfy. These rules govern the CLIENT s ## Rules -- **R1.** SKILL.md is a pure router: a tiny title, the chaining schema, the action table, and transversal rules (see `## SKILL.md`). Zero business logic. +- **R1.** SKILL.md is a pure router: description + action table + transversal rules. Zero business logic. - **R2.** One skill = one domain. A tool domain uses a singular noun (`slack`). An activity domain uses an action verb (`review`). See `## Naming`. -- **R3.** References may nest in sub-folders (`references//`) so a step loads only what it needs. A reference still never `@`-chains another reference. Split a file from another only when some execution path needs one without the other; content that always co-loads stays one file. +- **R3.** References one level deep. A reference never `@`-chains another reference. - **R4.** SKILL.md <= 500 lines. If exceeded, split into references. - **R5.** `description` states what + when. Third person, no XML. Conventions: - **Two lines max, straight to the point.** Target ~240 characters; never more than a short paragraph. Length serves recall, not completeness. The hard ceiling is 1024 chars, not a goal. @@ -23,8 +23,7 @@ The contract every generated skill must satisfy. These rules govern the CLIENT s - **R10.** Generated skills are English only (frontmatter, body, actions, references, assets), regardless of conversation language. - **R11.** One idea per sentence. Split a sentence that runs past one line. Exceptions: the single-line `description` and table rows. - **R12.** One file = one artifact. A reference or asset holds a single coherent thing: one checklist, one template, one criteria set. When a file accumulates several independently reusable artifacts, split them so each is cited and reused alone. Prefer this split over bundling, even when the combined file is short. -- **R13.** Includes are explicit and scoped. An **import** (content pulled into context) is cited with its `@` alone inside a fenced ``` block. A **pointer** (read-this-reference in a step) may cite `@` inline in prose. Either uses the reference's full path, including a nested `references//file.md`. Naming: a global include (imported from SKILL.md, used skill-wide) takes no prefix; an include used by only one action is prefixed with that action's slug (e.g. `research-checklist.md`). SKILL.md lists only the global includes; an action-specific include is cited only from its own action. -- **R14.** Bodies use telegraphic notation: tables, `→` for a linear chain, fragments over sentences, no filler. Never at the cost of a load-bearing condition. A branch, edge case, or if/then stays precise. Use a Mermaid diagram for branching or looping logic, never for a straight linear chain. +- **R13.** Includes are explicit and scoped. Cite an include with its `@` alone inside a fenced ``` block, never inline in prose. Naming: a global include (imported from SKILL.md, used skill-wide) takes no prefix; an include used by only one action is prefixed with that action's slug (e.g. `research-checklist.md`). SKILL.md lists only the global includes; an action-specific include is cited only from its own action. ## Action anatomy @@ -49,11 +48,7 @@ The router: YAML frontmatter + markdown body. - `description`: per R5. - `argument-hint` when supported or in plugin source and the skill has two or more actions: action names only, joined with ` | `, matching the files in `actions/`. Omit it for one-action skills. - A manual-only flag makes the skill user-only. The exact frontmatter key is per tool. -- Frontmatter carries official keys only (`name`, `description`, `argument-hint`, the host manual-only flag). Never invent a flag the model must interpret; the body carries mode, not a made-up key. -- Body order: a tiny `# Title`, the chaining schema, the action table, then the transversal rules. No restated intro sentence; the `description` already states the what. - - **Chaining schema.** A pipeline shows its chain: a one-line arrow schema `a → b → c` for a straight run, or a small Mermaid flowchart when the flow loops back (a cycle is not a linear chain, so R14 permits Mermaid here). A menu shows the line `Pick one per request.` and no schema. The mode reads itself; no field states it. - - **Action table.** Columns `# | Action | Does`; `Does` is verb-led and telegraphic (verb + object). A menu drops the `#` column. No `Input` column: an action's input lives in its own `## Input`. -- The body MUST carry the operative line: run the actions in the schema's order, and read an action's file before running it. This contract is authoring guidance that no executing host ever reads, so a rule left only here reaches nobody at runtime. Codex proved it: given a router without that line, it read SKILL.md and stopped. +- Body: pure router. The action table maps each `#` and slug to a role and input. State the flow (a sequential chain or a trigger-to-action map). Self-skips stated explicitly. The `name` field is NOT the invocation token. The host builds the address from the plugin and folder, each in its own scheme. A colon or prefix in `name` breaks loading on some hosts. In prose, refer to a skill as `plugin:folder`, never `plugin:folder:action`. From 293d0930435cebad4882d51e5f5921cdfcffe3e8 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 11:52:29 +0200 Subject: [PATCH 42/44] docs(aidd-context): codex portability, proven before and after The orphaned runtime rule was the only blocker. With the router carrying it, Codex reads the actions and renders the same greenfield screen Claude does. Co-Authored-By: Claude Opus 4.8 --- .../codex-portability.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/codex-portability.md diff --git a/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/codex-portability.md b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/codex-portability.md new file mode 100644 index 00000000..b94adcd1 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/codex-portability.md @@ -0,0 +1,49 @@ +# Codex portability — before and after the router fix + +The skill triggered on Codex from the start, but rendered nothing. Root cause: the +'read an action's file before running it' rule had been moved into skill-authoring.md, +a contract no executing host ever reads. Codex read SKILL.md and stopped. + +## Before — Codex reads SKILL.md and stops + +```text +I'm using `aidd-context:00-onboard` because you asked to be onboarded. +[reads .../skills/00-onboard/SKILL.md] +[no banner, no setup block, no foundations screen — improvises a generic answer] +``` + +Full capture: `headless-runs-codex.txt` (all eight states, pre-fix). + +## After — the router carries the operative line + +`SKILL.md`: `Run the actions in that order, looping. Read an action's file in \`actions/\` before running it.` + +```text + █████╗ ██╗██████╗ ██████╗ +██╔══██╗██║██╔══██╗██╔══██╗ +███████║██║██║ ██║██║ ██║ +██╔══██║██║██║ ██║██║ ██║ +██║ ██║██║██████╔╝██████╔╝ +╚═╝ ╚═╝╚═╝╚═════╝ ╚═════╝ + AI-Driven Development 🇫🇷 + +exec +/bin/zsh -lc "test -f AGENTS.md && sed -n '1,160p' AGENTS.md || true" in /private/tmp/aidd-demo/01-greenfield +exec +/bin/zsh -lc "test -f RTK.md && sed -n '1,220p' RTK.md || true" in /private/tmp/aidd-demo/01-greenfield + succeeded in 0ms: + succeeded in 0ms: +exec +/bin/zsh -lc "find . -maxdepth 2 -type f -o -type d | sort | sed -n '1,160p'" in /private/tmp/aidd-demo/01-greenfield + succeeded in 0ms: +. +./.git +./.git/HEAD +./.git/config +./.git/description +./.git/hooks +./.git/info +``` + +Probes: READ THE ACTIONS ✓ · BANNER ✓ · SETUP BLOCK ✓ · FOUNDATIONS ✓ +Identical shape to the Claude run in `headless-runs.md`. From 3b9486dea7eed7d3ec0b8cb62ca2260c2496e95d Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 12:13:14 +0200 Subject: [PATCH 43/44] fix(aidd-context): the options line is the last line, named plainly A live run on a broken-plan repo obeyed the one-action rule, then trailed a detail block, a state snapshot, and a next hint past the options line. The rule now names exactly what must not follow. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/SKILL.md | 4 ++-- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 80746261..6dfb04a6 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -11,10 +11,10 @@ flowchart LR scan --> assess --> present --> run --> scan ``` -Run the actions in that order, looping. Read an action's file in `actions/` before running it. - ## Actions +Run the actions in that order, looping. Read an action's file in `actions/` before running it. + | # | Action | Does | | -- | ------- | -------------------- | | 01 | scan | read the project | diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 46216e5e..7c57c673 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -18,7 +18,8 @@ The rendered screen, and the user's reply. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. - A used tool that lacks the block is `⚠️`, never `❌`. Only a missing required foundation takes `❌`. - Every `⚠️` shows its cause and a keyed fix. - - Short lines. The screen ends at the options line. + - Short lines. + - The options line is the last line. Print nothing after it, no detail block, no state snapshot, no hint about what comes next. - Command ids, tier clauses, and lookahead only under `[?]`. 2. **Inject.** - Entry screen takes `@../assets/banner.txt`. From c36143f72c30807d5b77cbda8b40c5d27b08d7a6 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 10 Jul 2026 12:31:53 +0200 Subject: [PATCH 44/44] fix(aidd-context): the idle menu is an action block, not a list Left unshaped, a live idle screen grew a four-row list with descriptions. Slot 1 is the action line, the rest join the options line. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/00-onboard/actions/03-present.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md index 7c57c673..8372be56 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -15,6 +15,7 @@ The rendered screen, and the user's reply. 1. **Shape.** Fill the chosen screen from `@../assets/report.md`. - Framing line on the first report of the session only. - Exactly one action block per screen, carrying its key once. + - The idle menu is a next-action block. Slot 1 is the action line, slots 2 to 4 join the options line. Never a list. - Glyphs: ✅ met · ⚠️ present, not wired · ❌ missing. - A used tool that lacks the block is `⚠️`, never `❌`. Only a missing required foundation takes `❌`. - Every `⚠️` shows its cause and a keyed fix.