From bb475ec0a2967139c67c97281913466bf6ca6b0d 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 01/20] 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 7e54ef9c1627399f89c22a092cc6dcbb2df35ce3 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Mon, 6 Jul 2026 07:21:58 +0200 Subject: [PATCH 02/20] ci(framework): drop the aidd-ui release-as pin, keep it consistent (#395) 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. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 --- 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 e36035ef23b8f20060d4ed4d4938c38d7a0f16fb Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:06:06 +0200 Subject: [PATCH 03/20] refactor: remove per-skill README.md mirrors (#302) (#396) * refactor: remove per-skill README.md mirrors, retarget to SKILL.md Delete the 39 per-skill README.md files that mirrored their SKILL.md, merge the genuinely-unique content from the 7 outlier READMEs into SKILL.md (memory-bank-optional note, install prerequisite, experimental status), retarget plugin-level README skill tables and CREATE_PLUGIN.md to SKILL.md, and regenerate every plugin CATALOG.md. Phase 1 of aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme. Co-Authored-By: Claude Opus 4.8 * chore: mark phase 2 done for remove-per-skill-readme plan All verify-and-guard gates pass: check-markdown-links.js exits 0, zero plugins/*/skills/*/README.md remain, every affected skill dir still has SKILL.md, both asset READMEs and all plugin-level/framework READMEs are intact, sync-readme-counts.mjs --check exits 0, no CATALOG lists a per-skill README row, and 04-skill-generate scaffolds no per-skill README. Co-Authored-By: Claude Opus 4.8 * chore: mark remove-per-skill-readme plan implemented Both phases done and validation green (check-markdown-links.js and sync-readme-counts.mjs --check both exit 0). Co-Authored-By: Claude Opus 4.8 * chore: mark remove-per-skill-readme plan reviewed --------- Co-authored-by: Claude Opus 4.8 --- .../phase-1.md | 84 +++++++++++++++++++ .../phase-2.md | 47 +++++++++++ .../plan.md | 38 +++++++++ .../review.md | 39 +++++++++ docs/CREATE_PLUGIN.md | 5 -- plugins/aidd-context/CATALOG.md | 12 --- plugins/aidd-context/README.md | 16 ++-- .../aidd-context/skills/00-onboard/README.md | 39 --------- .../aidd-context/skills/00-onboard/SKILL.md | 1 + .../skills/01-bootstrap/README.md | 59 ------------- .../skills/02-project-memory/README.md | 31 ------- .../skills/03-context-generate/README.md | 24 ------ .../skills/04-skill-generate/README.md | 21 ----- .../skills/05-rule-generate/README.md | 19 ----- .../skills/06-agent-generate/README.md | 18 ---- .../skills/07-command-generate/README.md | 18 ---- .../aidd-context/skills/09-mermaid/README.md | 29 ------- .../aidd-context/skills/10-learn/README.md | 43 ---------- .../aidd-context/skills/11-explore/README.md | 31 ------- plugins/aidd-context/skills/12-cook/README.md | 12 --- plugins/aidd-dev/CATALOG.md | 11 --- plugins/aidd-dev/README.md | 20 ++--- plugins/aidd-dev/skills/00-sdlc/README.md | 68 --------------- plugins/aidd-dev/skills/01-plan/README.md | 45 ---------- .../aidd-dev/skills/02-implement/README.md | 45 ---------- plugins/aidd-dev/skills/03-assert/README.md | 58 ------------- plugins/aidd-dev/skills/04-audit/README.md | 66 --------------- plugins/aidd-dev/skills/05-review/README.md | 69 --------------- plugins/aidd-dev/skills/06-test/README.md | 56 ------------- plugins/aidd-dev/skills/07-refactor/README.md | 72 ---------------- plugins/aidd-dev/skills/08-debug/README.md | 58 ------------- plugins/aidd-dev/skills/09-for-sure/README.md | 66 --------------- plugins/aidd-dev/skills/10-todo/README.md | 19 ----- plugins/aidd-orchestrator/CATALOG.md | 1 - plugins/aidd-orchestrator/README.md | 4 +- .../skills/00-async-dev/README.md | 54 ------------ plugins/aidd-pm/CATALOG.md | 4 - plugins/aidd-pm/README.md | 8 +- .../aidd-pm/skills/01-ticket-info/README.md | 52 ------------ .../aidd-pm/skills/02-user-stories/README.md | 58 ------------- plugins/aidd-pm/skills/03-prd/README.md | 52 ------------ plugins/aidd-pm/skills/04-spec/README.md | 60 ------------- plugins/aidd-refine/CATALOG.md | 5 -- plugins/aidd-refine/README.md | 10 +-- .../skills/01-brainstorm/README.md | 32 ------- .../aidd-refine/skills/02-challenge/README.md | 57 ------------- .../aidd-refine/skills/03-condense/README.md | 64 -------------- .../skills/04-shadow-areas/README.md | 69 --------------- .../skills/05-fact-check/README.md | 69 --------------- plugins/aidd-ui/CATALOG.md | 1 - plugins/aidd-ui/README.md | 2 +- plugins/aidd-ui/skills/01-hello/README.md | 29 ------- plugins/aidd-ui/skills/01-hello/SKILL.md | 4 + plugins/aidd-vcs/CATALOG.md | 5 -- plugins/aidd-vcs/README.md | 8 +- .../aidd-vcs/skills/00-repo-init/README.md | 34 -------- plugins/aidd-vcs/skills/00-repo-init/SKILL.md | 6 ++ plugins/aidd-vcs/skills/01-commit/README.md | 53 ------------ .../aidd-vcs/skills/02-pull-request/README.md | 55 ------------ .../aidd-vcs/skills/03-release-tag/README.md | 54 ------------ .../aidd-vcs/skills/04-issue-create/README.md | 54 ------------ 61 files changed, 253 insertions(+), 1890 deletions(-) create mode 100644 aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-1.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-2.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/plan.md create mode 100644 aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/review.md delete mode 100644 plugins/aidd-context/skills/00-onboard/README.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/README.md delete mode 100644 plugins/aidd-context/skills/02-project-memory/README.md delete mode 100644 plugins/aidd-context/skills/03-context-generate/README.md delete mode 100644 plugins/aidd-context/skills/04-skill-generate/README.md delete mode 100644 plugins/aidd-context/skills/05-rule-generate/README.md delete mode 100644 plugins/aidd-context/skills/06-agent-generate/README.md delete mode 100644 plugins/aidd-context/skills/07-command-generate/README.md delete mode 100644 plugins/aidd-context/skills/09-mermaid/README.md delete mode 100644 plugins/aidd-context/skills/10-learn/README.md delete mode 100644 plugins/aidd-context/skills/11-explore/README.md delete mode 100644 plugins/aidd-context/skills/12-cook/README.md delete mode 100644 plugins/aidd-dev/skills/00-sdlc/README.md delete mode 100644 plugins/aidd-dev/skills/01-plan/README.md delete mode 100644 plugins/aidd-dev/skills/02-implement/README.md delete mode 100644 plugins/aidd-dev/skills/03-assert/README.md delete mode 100644 plugins/aidd-dev/skills/04-audit/README.md delete mode 100644 plugins/aidd-dev/skills/05-review/README.md delete mode 100644 plugins/aidd-dev/skills/06-test/README.md delete mode 100644 plugins/aidd-dev/skills/07-refactor/README.md delete mode 100644 plugins/aidd-dev/skills/08-debug/README.md delete mode 100644 plugins/aidd-dev/skills/09-for-sure/README.md delete mode 100644 plugins/aidd-dev/skills/10-todo/README.md delete mode 100644 plugins/aidd-orchestrator/skills/00-async-dev/README.md delete mode 100644 plugins/aidd-pm/skills/01-ticket-info/README.md delete mode 100644 plugins/aidd-pm/skills/02-user-stories/README.md delete mode 100644 plugins/aidd-pm/skills/03-prd/README.md delete mode 100644 plugins/aidd-pm/skills/04-spec/README.md delete mode 100644 plugins/aidd-refine/skills/01-brainstorm/README.md delete mode 100644 plugins/aidd-refine/skills/02-challenge/README.md delete mode 100644 plugins/aidd-refine/skills/03-condense/README.md delete mode 100644 plugins/aidd-refine/skills/04-shadow-areas/README.md delete mode 100644 plugins/aidd-refine/skills/05-fact-check/README.md delete mode 100644 plugins/aidd-ui/skills/01-hello/README.md delete mode 100644 plugins/aidd-vcs/skills/00-repo-init/README.md delete mode 100644 plugins/aidd-vcs/skills/01-commit/README.md delete mode 100644 plugins/aidd-vcs/skills/02-pull-request/README.md delete mode 100644 plugins/aidd-vcs/skills/03-release-tag/README.md delete mode 100644 plugins/aidd-vcs/skills/04-issue-create/README.md diff --git a/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-1.md b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-1.md new file mode 100644 index 00000000..2f0b0fee --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-1.md @@ -0,0 +1,84 @@ +--- +status: done +--- + +# Instruction: Remove per-skill READMEs and fix every reference + +## Architecture projection + +> ✅ create · ✏️ modify · ❌ delete + +```txt +. +├── plugins/ +│ ├── aidd-context/ +│ │ ├── README.md ✏️ retarget 13 skill-table links -> SKILL.md +│ │ ├── CATALOG.md ✏️ regenerate (auto) +│ │ └── skills/*/README.md ❌ delete 13 (NOT assets/**/README.md) +│ ├── aidd-dev/ +│ │ ├── README.md ✏️ retarget 11 skill-table links -> SKILL.md +│ │ ├── CATALOG.md ✏️ regenerate (auto) +│ │ └── skills/*/README.md ❌ delete 11 +│ ├── aidd-orchestrator/{README,CATALOG}.md ✏️ retarget / regenerate +│ │ └── skills/00-async-dev/README.md ❌ delete 1 +│ ├── aidd-pm/{README,CATALOG}.md ✏️ retarget / regenerate +│ │ └── skills/*/README.md ❌ delete 4 +│ ├── aidd-refine/{README,CATALOG}.md ✏️ retarget / regenerate +│ │ └── skills/*/README.md ❌ delete 5 +│ ├── aidd-ui/{README,CATALOG}.md ✏️ retarget / regenerate +│ │ └── skills/01-hello/README.md ❌ delete 1 +│ └── aidd-vcs/{README,CATALOG}.md ✏️ retarget / regenerate +│ └── skills/*/README.md ❌ delete 4 +└── docs/CREATE_PLUGIN.md ✏️ drop per-skill README from structure + section, retarget links +``` + +Do NOT touch: `plugins/*/README.md` as skills (plugin-level, kept), the top-level framework `README.md`, or asset READMEs (`plugins/aidd-context/skills/02-project-memory/assets/README.md`, `.../assets/templates/memory/README.md`). + +## Tasks to do + +### `1)` Spot-check the 7 outlier READMEs before deleting + +> 7 READMEs lack the breadcrumb header, so they may carry prose their SKILL.md does not. Merge unique content, then delete. Do not blind-delete these. + +Outliers: `aidd-context/skills/{00-onboard,09-mermaid,10-learn,11-explore,12-cook}`, `aidd-ui/skills/01-hello`, `aidd-vcs/skills/00-repo-init`. + +1. Diff each README against its sibling SKILL.md. +2. If the README holds substantive info absent from SKILL.md (e.g. `01-hello` documents an install prerequisite / `claude --plugin-dir` invocation), fold the essential line into the SKILL.md, matching that file's terse style. +3. Pure mirrors (heading + when-to/not-to that the SKILL description already states): nothing to merge. + +### `2)` Delete the 39 per-skill READMEs + +> Direct children of a skill directory only. + +1. Remove every file matching `plugins/*/skills/*/README.md`. +2. Leave the two asset READMEs and all plugin-level / framework READMEs in place. + +### `3)` Retarget the plugin-level README skill tables + +> Each of the 7 `plugins//README.md` has a Skills table linking `skills//README.md`. Point them at `SKILL.md`. + +1. In every `plugins/*/README.md`, replace `skills//README.md` link targets with `skills//SKILL.md`. Link text and table rows stay unchanged. + +### `4)` Update `docs/CREATE_PLUGIN.md` + +> The doc prescribes a per-skill README; drop that so the convention does not reintroduce them. + +1. Remove the per-skill `README.md` entry from the structure diagram (keep the plugin-level `README.md` entry). +2. Remove or rewrite the `### skills/01-hello/README.md` section so it no longer instructs authors to ship a per-skill README; keep the plugin-level README guidance. +3. Retarget any `skills//README.md` link in the doc to `SKILL.md`. + +### `5)` Regenerate the CATALOGs + +> `CATALOG.md` is auto-generated; do not hand-edit. Regenerate so the README rows drop out. + +1. For each plugin run `node scripts/summarize-markdown.js "plugins//" "plugins//CATALOG.md" --depth=4 --fields=description --title=" catalog" --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`\` plugin."` (identical to the `lefthook.yml` block), or let the pre-commit hook run it. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ----------------------------------------------------------------------------------------------------------- | +| 1 | Each outlier's unique content is either merged into its SKILL.md or confirmed to be a pure mirror. | +| 2 | `find plugins -path '*/skills/*/README.md'` returns zero results; both asset READMEs still exist. | +| 3 | No `plugins/*/README.md` skill table links to a `skills/*/README.md`; all point to `SKILL.md`. | +| 4 | `docs/CREATE_PLUGIN.md` no longer prescribes a per-skill README and links to no removed file. | +| 5 | Regenerated `CATALOG.md` files list no `skills/*/README.md` row. | diff --git a/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-2.md b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-2.md new file mode 100644 index 00000000..1bea9b05 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-2.md @@ -0,0 +1,47 @@ +--- +status: done +--- + +# Instruction: Verify and guard + +## Architecture projection + +> No file changes; this phase runs the gates that prove the QA holds. + +```txt +. +└── (verification only — scripts/check-markdown-links.js, sync scripts) +``` + +## Tasks to do + +### `1)` Broken-link gate (the QA#3 proof) + +> Every markdown link that resolved to a now-deleted README must be gone. + +1. Run `node scripts/check-markdown-links.js` from the repo root. It resolves relative links across all markdown; a dangling link to a removed README fails it. +2. Fix any residual dangling reference it reports (retarget to `SKILL.md` or drop), then re-run until clean. + +### `2)` No per-skill README, no orphan skill + +1. `find plugins -path '*/skills/*/README.md'` returns nothing. +2. Every skill directory that lost its README still has a `SKILL.md` (no orphaned skill dir). +3. The two asset READMEs and all plugin-level / framework READMEs remain. + +### `3)` Generated artifacts consistent + +1. `node scripts/sync-readme-counts.mjs --check` exits 0 (top-level counts unaffected). +2. Regenerated CATALOGs contain no `skills/*/README.md` rows. + +### `4)` Durability + +1. Confirm `aidd-context/04-skill-generate` does not scaffold a per-skill README (a newly generated skill would not reintroduce one). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------- | +| 1 | `node scripts/check-markdown-links.js` exits 0 with no dangling README link reported. | +| 2 | Zero `skills/*/README.md`; every affected skill dir still has `SKILL.md`; asset READMEs intact. | +| 3 | `sync-readme-counts.mjs --check` exits 0; no CATALOG lists a per-skill README. | +| 4 | The skill generator emits no per-skill README. | diff --git a/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/plan.md b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/plan.md new file mode 100644 index 00000000..ebcfcdf2 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/plan.md @@ -0,0 +1,38 @@ +--- +objective: "Every per-skill README.md that mirrors its SKILL.md is gone, and no link, doc, or generator points at a removed file." +status: reviewed +--- + +# Plan: Remove per-skill README.md + +## Overview + +| Field | Value | +| ---------- | --------------------------------------------------------------------- | +| **Goal** | Delete the 39 per-skill `README.md` mirrors; keep navigation intact. | +| **Source** | GitHub issue #302 (ai-driven-dev/framework) | + +## Phases + +| # | Phase | File | +| --- | ---------------------------- | ---------------------------- | +| 1 | Remove READMEs, fix all refs | [`phase-1.md`](./phase-1.md) | +| 2 | Verify and guard | [`phase-2.md`](./phase-2.md) | + +## Resources + +| Source | Verified | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| GitHub issue #302 | Objective + QA acceptance criteria; symlink is optional and droppable. | +| `lefthook.yml` | Pre-commit runs `check-markdown-links.js` (link gate), regenerates every `CATALOG.md`, and syncs `README.md` counts. | +| `scripts/summarize-markdown.js` | `CATALOG.md` is fully auto-generated from the file tree; deleted READMEs vanish on regen. | +| `scripts/sync-readme-counts.mjs` | Counts skills by directory, README-independent; only touches the top-level `README.md`. | +| `plugins/aidd-context/skills/04-skill-generate/*` | Does not scaffold a per-skill README; removal is durable for future skills. | + +## Decisions + +| Decision | Why | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| Delete the READMEs, do not symlink to SKILL.md | Plugin ships cross-OS (symlink fragile); a symlink would render SKILL.md's raw YAML frontmatter on GitHub; issue accepts clean removal. | +| Retarget plugin-README skill-table links to SKILL.md | Preserves folder navigation after the README is gone; these tables are hand-written, not generated. | +| Regenerate CATALOG.md, never hand-edit it | `CATALOG.md` is auto-generated; hand edits are overwritten by the pre-commit hook. | diff --git a/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/review.md b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/review.md new file mode 100644 index 00000000..5a55ab31 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/review.md @@ -0,0 +1,39 @@ +# Review: Remove per-skill README.md + +- **Verdict**: approve +- **Diff**: `484928c...9b327eb` +- **Axes run**: code, functional, relevancy +- **Date**: 2026_07_06 +- **Findings**: 0 critical, 0 warning, 1 minor + +## Phases + +### Phase 1 — Remove READMEs, fix all refs + +- [x] Task 1: each outlier's unique content merged into SKILL.md or confirmed a pure mirror — 00-onboard/SKILL.md:36 (Requires folded), 01-hello/SKILL.md:19-21 (prereq folded), 00-repo-init/SKILL.md:9,30-33 (status + prereq folded); 09-mermaid/10-learn/11-explore/12-cook confirmed pure mirrors (prereq already in SKILL.md) +- [x] Task 2: no direct-child `skills/*/README.md` remains; both asset READMEs present — direct-child loop returns nothing; `plugins/aidd-context/skills/02-project-memory/assets/README.md` + `.../assets/templates/memory/README.md` intact +- [x] Task 3: no `plugins/*/README.md` skill table links to `skills/*/README.md`; all point to SKILL.md — grep of `plugins/*/README.md` returns none; aidd-orchestrator/README.md:19,21 retargeted +- [x] Task 4: `docs/CREATE_PLUGIN.md` no longer prescribes a per-skill README, links to no removed file — docs/CREATE_PLUGIN.md:41,94 (structure line + section removed) +- [x] Task 5: regenerated CATALOG.md files list no `skills/*/README.md` row — grep returns only the retained asset README row (aidd-context/CATALOG.md:81), not a per-skill mirror + +### Phase 2 — Verify and guard + +- [x] Task 1: `node scripts/check-markdown-links.js` exits 0, no dangling README link — "Links: 0 broken in 364 files", exit 0 +- [x] Task 2: zero direct-child `skills/*/README.md`; every affected skill dir keeps SKILL.md; asset READMEs intact — orphan loop returns nothing; asset READMEs present +- [x] Task 3: `sync-readme-counts.mjs --check` exits 0; no CATALOG lists a per-skill README — exit 0; CATALOG regen produced zero drift (proves generated, not hand-edited) +- [x] Task 4: skill generator emits no per-skill README — `grep -rniE readme plugins/aidd-context/skills/04-skill-generate/` returns nothing; templates scaffold SKILL.md + actions only + +## Findings + +| Sev | Kind | Phase | Location | Issue | Fix | +| --- | ---- | ----- | -------- | ----- | --- | +| 🟢 | rot | 1 | plugins/aidd-context/skills/09-mermaid/SKILL.md | Deleted README's `## Requires` elaborated the input as "a paragraph, a list, or a section"; SKILL.md keeps the essential "written source" (description + Actions input) but drops that parenthetical granularity. Judged a pure mirror; noted for completeness. | Optional: none required — essential prerequisite is preserved. | + +## Verification + +| Metric | Value | +| ------------- | ------------------------------------------------- | +| Verified | 100% (9/9) | +| Files checked | 39 deleted skill READMEs, 7 plugin READMEs, 7 CATALOG.md, 3 SKILL.md merges (00-onboard, 01-hello, 00-repo-init), docs/CREATE_PLUGIN.md, plugins/aidd-context/skills/04-skill-generate/* | +| Unchecked | none | +| Unplanned | none (60 files = 39 deletions + 3 plan docs added + 18 modified; exactly scoped, no creep) | diff --git a/docs/CREATE_PLUGIN.md b/docs/CREATE_PLUGIN.md index dce4d5b6..c442692e 100644 --- a/docs/CREATE_PLUGIN.md +++ b/docs/CREATE_PLUGIN.md @@ -41,7 +41,6 @@ plugins/aidd-example/ ├── skills/ │ └── 01-hello/ │ ├── SKILL.md -│ ├── README.md │ └── actions/ │ └── 01-greet.md ├── agents/ # optional @@ -95,10 +94,6 @@ description: One-sentence summary. Use when ... Do NOT use for ... Run action `01-greet` and return its message. ``` -### `skills/01-hello/README.md` - -Mirror the sibling pattern: title, paragraph, When to use, When NOT to use, How to invoke, Outputs, Prerequisites, Technical details (link to SKILL.md). ~30-50 lines. - ### `skills/01-hello/actions/01-greet.md` ```markdown diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index f19f7334..78647903 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -48,7 +48,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-report.md](skills/00-onboard/actions/02-report.md) | - | | `actions` | [03-run.md](skills/00-onboard/actions/03-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) | `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.` | @@ -64,7 +63,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-write-install-md.md](skills/01-bootstrap/actions/05-write-install-md.md) | - | | `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | | `assets` | [install-template.md](skills/01-bootstrap/assets/install-template.md) | - | -| `-` | [README.md](skills/01-bootstrap/README.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | | `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Design and validate a new SaaS's architecture into an INSTALL.md via Q&A and stack comparison. Use when the user starts a project, chooses a stack, or picks an architecture pattern. Not for editing an existing stack or scaffolding code.` | @@ -81,7 +79,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [CONTRIBUTING.md](skills/02-project-memory/assets/CONTRIBUTING.md) | - | | `assets` | [GUIDELINES.md](skills/02-project-memory/assets/GUIDELINES.md) | - | | `assets` | [README.md](skills/02-project-memory/assets/README.md) | - | -| `-` | [README.md](skills/02-project-memory/README.md) | - | | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - | | `references` | [mapping-ai-context-file.md](skills/02-project-memory/references/mapping-ai-context-file.md) | - | | `references` | [memory-block.md](skills/02-project-memory/references/memory-block.md) | - | @@ -91,7 +88,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [README.md](skills/03-context-generate/README.md) | - | | [SKILL.md](skills/03-context-generate/SKILL.md) | `Route a request to generate a context artifact (skill, rule, agent, command, or hook) to its generator when the kind is unnamed. A named kind triggers its generator directly. Not for listing existing artifacts.` | #### `skills/04-skill-generate` @@ -105,7 +101,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-validate.md](skills/04-skill-generate/actions/05-validate.md) | - | | `assets` | [action-template.md](skills/04-skill-generate/assets/action-template.md) | - | | `assets` | [skill-template.md](skills/04-skill-generate/assets/skill-template.md) | `. Use when the user wants to . " in plain words when a sibling could mis-trigger.> (Two lines max, ~240 chars, straight to the point. Third person, no XML. Never name another skill, never write a /command token. All "when" lives here, not in the body.)` | -| `-` | [README.md](skills/04-skill-generate/README.md) | - | | `references` | [skill-authoring.md](skills/04-skill-generate/references/skill-authoring.md) | - | | `references` | [tool-paths.md](skills/04-skill-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/04-skill-generate/SKILL.md) | `Generate a router-based skill across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a skill, or turn a workflow into one. Not for other artifacts like rules, agents, commands, hooks.` | @@ -118,7 +113,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write-rule.md](skills/05-rule-generate/actions/02-write-rule.md) | - | | `actions` | [03-validate.md](skills/05-rule-generate/actions/03-validate.md) | - | | `assets` | [rule-template.md](skills/05-rule-generate/assets/rule-template.md) | - | -| `-` | [README.md](skills/05-rule-generate/README.md) | - | | `references` | [rule-authoring.md](skills/05-rule-generate/references/rule-authoring.md) | - | | `references` | [tool-paths.md](skills/05-rule-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/05-rule-generate/SKILL.md) | `Generate a coding rule that governs editor and agent behavior across the host AI tools. Use when the user wants to write, add, or refactor a rule, convention, or coding standard. Not for other artifacts like skills, agents, or hooks.` | @@ -131,7 +125,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write-agent.md](skills/06-agent-generate/actions/02-write-agent.md) | - | | `actions` | [03-validate.md](skills/06-agent-generate/actions/03-validate.md) | - | | `assets` | [agent-template.md](skills/06-agent-generate/assets/agent-template.md) | ` # required, third person` | -| `-` | [README.md](skills/06-agent-generate/README.md) | - | | `references` | [agent-authoring.md](skills/06-agent-generate/references/agent-authoring.md) | - | | `references` | [tool-paths.md](skills/06-agent-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/06-agent-generate/SKILL.md) | `Generate an agent across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor an agent, subagent or specialized role. Not for other artifacts like skills, rules, commands, hooks.` | @@ -144,7 +137,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write-command.md](skills/07-command-generate/actions/02-write-command.md) | - | | `actions` | [03-validate.md](skills/07-command-generate/actions/03-validate.md) | - | | `assets` | [command-template.md](skills/07-command-generate/assets/command-template.md) | - | -| `-` | [README.md](skills/07-command-generate/README.md) | - | | `references` | [command-authoring.md](skills/07-command-generate/references/command-authoring.md) | - | | `references` | [tool-paths.md](skills/07-command-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/07-command-generate/SKILL.md) | `Generate a flat slash command across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a one-shot slash command. Not for multi-step skills or other artifacts like rules, agents, hooks.` | @@ -167,7 +159,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-mermaid.md](skills/09-mermaid/actions/01-mermaid.md) | - | -| `-` | [README.md](skills/09-mermaid/README.md) | - | | `references` | [mermaid-conventions.md](skills/09-mermaid/references/mermaid-conventions.md) | - | | `-` | [SKILL.md](skills/09-mermaid/SKILL.md) | `Generate a valid Mermaid diagram from a written source through a plan, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow into a Mermaid diagram. Not for other diagram formats or image rendering.` | @@ -180,7 +171,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-write.md](skills/10-learn/actions/03-write.md) | - | | `actions` | [04-sync.md](skills/10-learn/actions/04-sync.md) | - | | `assets` | [decision-template.md](skills/10-learn/assets/decision-template.md) | - | -| `-` | [README.md](skills/10-learn/README.md) | - | | `-` | [SKILL.md](skills/10-learn/SKILL.md) | `Capture durable project learnings from the conversation or git history into memory, a record, a rule, or a skill. Use when the user asks to capture, record, or remember a decision or lesson. Not for AI preferences or already-captured items.` | #### `skills/11-explore` @@ -189,7 +179,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-survey.md](skills/11-explore/actions/01-survey.md) | - | | `actions` | [02-drill.md](skills/11-explore/actions/02-drill.md) | - | -| `-` | [README.md](skills/11-explore/README.md) | - | | `references` | [ai-mapping.md](skills/11-explore/references/ai-mapping.md) | - | | `-` | [SKILL.md](skills/11-explore/SKILL.md) | `Explore the current project across its tooling, context, and codebase. Use to survey what is installed, see what is available, or find which skill, agent, or rule fits a goal. Not for choosing the next step or running an item; it only points.` | @@ -200,6 +189,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-list.md](skills/12-cook/actions/01-list.md) | - | | `actions` | [02-upsert.md](skills/12-cook/actions/02-upsert.md) | - | | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - | -| `-` | [README.md](skills/12-cook/README.md) | - | | `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes and how-to sheets. List them as a table, or create and update one from the canonical template. Use when the user wants to list, create, update, or cook a recipe.` | diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index 753825bd..fab12ea3 100644 --- a/plugins/aidd-context/README.md +++ b/plugins/aidd-context/README.md @@ -14,14 +14,14 @@ 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.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. | -| [1.4] | [mermaid](skills/09-mermaid/README.md) | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow. | -| [1.5] | [learn](skills/10-learn/README.md) | Capture durable learnings from the conversation or git history, score each, and route the worthwhile ones to memory, a decision record, a rule, or a new skill. | -| [1.6] | [explore](skills/11-explore/README.md) | Survey the project across three axes (tooling, context, codebase), then drill into one axis and point to the best-matching item for a goal. | -| [1.7] | [cook](skills/12-cook/README.md) | Maintain the project's `recipes/` how-to sheets: list every recipe, or create and update one from the canonical recipe template. | +| [1.0] | [onboard](skills/00-onboard/SKILL.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.1] | [bootstrap](skills/01-bootstrap/SKILL.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/SKILL.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/SKILL.md) | Generate context artifacts: router-based skills, agents, rules, slash commands, hooks, plugin scaffolds, and plugin marketplaces. | +| [1.4] | [mermaid](skills/09-mermaid/SKILL.md) | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow. | +| [1.5] | [learn](skills/10-learn/SKILL.md) | Capture durable learnings from the conversation or git history, score each, and route the worthwhile ones to memory, a decision record, a rule, or a new skill. | +| [1.6] | [explore](skills/11-explore/SKILL.md) | Survey the project across three axes (tooling, context, codebase), then drill into one axis and point to the best-matching item for a goal. | +| [1.7] | [cook](skills/12-cook/SKILL.md) | Maintain the project's `recipes/` how-to sheets: list every recipe, or create and update one from the canonical recipe template. | ## Onboarding diff --git a/plugins/aidd-context/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md deleted file mode 100644 index 0ecc2e53..00000000 --- a/plugins/aidd-context/skills/00-onboard/README.md +++ /dev/null @@ -1,39 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 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. - -## When to use - -- "Where do I start?" / "Onboard me to this project." -- "What should I do next?" -- "How does this project stand against AIDD?" -- After a partial setup, to see what is still missing. - -## When not to use - -- To list every installed surface. Use the explore skill in this plugin. -- To run a specific command you already know. Invoke it directly. - -## Flow - -Three actions, in a loop: - -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. - -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. - -## Run tiers - -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. - -## 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. - -## 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). diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index 59ab1e93..76bc2e2a 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -33,6 +33,7 @@ Run `01 → 02 → 03`, then loop back to `01` after each run until the user sto - 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. +- Requires only the `aidd-context` plugin installed and a working directory rooted in the target project. The `aidd_docs/` memory bank is not a prerequisite: 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. 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`. diff --git a/plugins/aidd-context/skills/01-bootstrap/README.md b/plugins/aidd-context/skills/01-bootstrap/README.md deleted file mode 100644 index 15ae57b0..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/README.md +++ /dev/null @@ -1,59 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 01 - Bootstrap - -Plays the role of technical architect for a new SaaS project. Walks the user -through a 24-item checklist, proposes 2-3 candidate stacks, audits each via -parallel agents, then produces `aidd_docs/INSTALL.md` capturing the technical -vision, decisions, stack, architecture pattern, folder tree, and install -steps. Documentation only - no code, no scaffolding. - -## When to use - -- Starting a brand-new SaaS project and choosing a stack. -- Deciding the architecture pattern (monolith vs microservices vs serverless). -- Producing a project's `INSTALL.md` from a fresh idea. - -## When NOT to use - -- To edit an existing project's stack (the audit is too heavy for one - swap-out). -- For database schema design or detailed data modeling. -- To scaffold actual files - this skill produces docs only. - -## How to invoke - -``` -Use skill aidd-context:01-bootstrap -``` - -The skill walks 5 atomic actions in sequence: - -1. `gather-needs` - Q&A across the 24-item checklist (18 user-input, 6 - derived). -2. `propose-candidates` - derive 2-3 candidate stacks and render a - comparison table. -3. `audit-candidates` - spawn parallel agents to validate each candidate - and emit a verdict; if every candidate fails, loop back to `02` or `01`. -4. `pick-and-design` - user picks the winner, then generate the folder tree - and a Mermaid architecture diagram. -5. `write-install-md` - produce `aidd_docs/INSTALL.md`. - -## Outputs - -- `aidd_docs/INSTALL.md` capturing vision, decisions, chosen stack, - architecture pattern, folder tree, install steps, and a Mermaid diagram. - -## Prerequisites - -- A clear (or at least loosely-formed) product idea to discuss. -- A working directory where `aidd_docs/INSTALL.md` can be written. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) -for each step, `references/stack-heuristics.md` for the input → recommended -stack-family heuristics, and `assets/checklist.md` + `assets/install-template.md` -for the canonical 24-item checklist and `INSTALL.md` skeleton. The Mermaid -architecture diagram in action 04 is rendered via the sibling -`09-mermaid` skill. diff --git a/plugins/aidd-context/skills/02-project-memory/README.md b/plugins/aidd-context/skills/02-project-memory/README.md deleted file mode 100644 index e39929b4..00000000 --- a/plugins/aidd-context/skills/02-project-memory/README.md +++ /dev/null @@ -1,31 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 02 - Project Memory - -Bootstraps the project's context layer: the AI context files with the `` block, the `aidd_docs/` structure, and the memory bank. - -## When to use - -- The first `aidd init` on a repo. -- A new project with no `aidd_docs/` yet. -- A re-run on an existing project to refresh missing memory files. - -## When not to use - -- Updating one memory file after it exists: use `aidd-context:10-learn`. -- Editing a single rule: edit the file directly. -- Generating a new artifact: use `aidd-context:03-context-generate`. - -## Flow - -Five actions, in order: - -1. `init-context-file`: resolve the tools, then upsert the memory block. -2. `scaffold-docs`: create the `aidd_docs/` structure. -3. `generate-memory`: detect the project's capabilities and fill the memory templates. -4. `review-memory`: review the memory files for consistency. -5. `sync-memory`: fill each memory block with references to the generated files. - -## Details - -See [`SKILL.md`](SKILL.md), [`actions/`](actions/), `references/mapping-ai-context-file.md` for the per-tool context-file path, and `assets/templates/memory/` for the memory templates. diff --git a/plugins/aidd-context/skills/03-context-generate/README.md b/plugins/aidd-context/skills/03-context-generate/README.md deleted file mode 100644 index fa358087..00000000 --- a/plugins/aidd-context/skills/03-context-generate/README.md +++ /dev/null @@ -1,24 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 03 - Context Generate - -A router. It sends a request to generate a context artifact to the dedicated generator for that kind, and holds no generation logic of its own. - -## Routing - -| Artifact | Generator | -| -------- | ---------------------------------- | -| skill | `aidd-context:04-skill-generate` | -| rule | `aidd-context:05-rule-generate` | -| agent | `aidd-context:06-agent-generate` | -| command | `aidd-context:07-command-generate` | -| hook | `aidd-context:08-hook-generate` | - -## When to use - -- The user wants to generate a context artifact but has not said which kind. - -## When not to use - -- A named kind: the dedicated generator triggers directly. -- Surveying or listing existing artifacts: use `aidd-context:11-explore`. diff --git a/plugins/aidd-context/skills/04-skill-generate/README.md b/plugins/aidd-context/skills/04-skill-generate/README.md deleted file mode 100644 index c53887ad..00000000 --- a/plugins/aidd-context/skills/04-skill-generate/README.md +++ /dev/null @@ -1,21 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 07 - skill-generate - -Build one canonical skill from intent (a SKILL.md router plus chained actions) and render it once per confirmed host tool. This skill is its own reference implementation: it obeys every rule it ships in `references/skill-authoring.md`. - -## When to use - -- The user wants to create, scaffold, or refactor a skill. -- Turn an existing workflow into a router-based skill. -- Not for other artifacts (rules, agents, commands, hooks). - -## Actions - -| # | Action | Purpose | -| --- | ----------------------------------------------------- | --------------------------------------------- | -| 01 | [capture-intent](actions/01-capture-intent.md) | Clarify intent + tools, inventory overlaps. | -| 02 | [decompose-actions](actions/02-decompose-actions.md) | Break the skill into atomic testable actions. | -| 03 | [draft-skill](actions/03-draft-skill.md) | Write the SKILL.md router. | -| 04 | [write-actions](actions/04-write-actions.md) | Write each action file from the template. | -| 05 | [validate](actions/05-validate.md) | Run each action's Test, aggregate pass/fail. | diff --git a/plugins/aidd-context/skills/05-rule-generate/README.md b/plugins/aidd-context/skills/05-rule-generate/README.md deleted file mode 100644 index a0e3b07f..00000000 --- a/plugins/aidd-context/skills/05-rule-generate/README.md +++ /dev/null @@ -1,19 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 08 - rule-generate - -Write one canonical coding rule from intent and render it once per host AI tool that supports rules. A sibling of `04-skill-generate` for the rule artifact. - -## When to use - -- The user wants to write, add, or refactor a rule, a convention, or a coding standard. -- Scan a codebase and propose rules. -- Not for other artifacts (skills, agents, commands, hooks). - -## Actions - -| # | Action | Purpose | -| --- | ----------------------------------------- | -------------------------------------------- | -| 01 | [capture-rule](actions/01-capture-rule.md) | Capture the topic, pick category and slug. | -| 02 | [write-rule](actions/02-write-rule.md) | Write the rule file per supported tool. | -| 03 | [validate](actions/03-validate.md) | Check each rule file. | diff --git a/plugins/aidd-context/skills/06-agent-generate/README.md b/plugins/aidd-context/skills/06-agent-generate/README.md deleted file mode 100644 index 8748dd26..00000000 --- a/plugins/aidd-context/skills/06-agent-generate/README.md +++ /dev/null @@ -1,18 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 06 - agent-generate - -Write one canonical subagent from intent and render it once per host AI tool, converting to each tool's shape (markdown, or Codex TOML). A sibling of `04-skill-generate` for the agent artifact. - -## When to use - -- The user wants to create, scaffold, or refactor an agent or subagent. -- Not for other artifacts (skills, rules, commands, hooks). - -## Actions - -| # | Action | Purpose | -| --- | -------------------------------------------- | ---------------------------------------------- | -| 01 | [capture-agent](actions/01-capture-agent.md) | Gather the role, propose names, pick the model. | -| 02 | [write-agent](actions/02-write-agent.md) | Render the agent per tool and write. | -| 03 | [validate](actions/03-validate.md) | Check each agent file. | diff --git a/plugins/aidd-context/skills/07-command-generate/README.md b/plugins/aidd-context/skills/07-command-generate/README.md deleted file mode 100644 index efd2bddf..00000000 --- a/plugins/aidd-context/skills/07-command-generate/README.md +++ /dev/null @@ -1,18 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 07 - command-generate - -Write one canonical slash command from intent and render it once per host AI tool that supports commands. A sibling of `04-skill-generate` for the command artifact. - -## When to use - -- The user wants to create, scaffold, or refactor a one-shot slash command. -- Not for multi-step skills (use the skill generator) or other artifacts (rules, agents, hooks). - -## Actions - -| # | Action | Purpose | -| --- | ----------------------------------------------- | ------------------------------------------ | -| 01 | [capture-command](actions/01-capture-command.md) | Capture the goal, location, and arguments. | -| 02 | [write-command](actions/02-write-command.md) | Write the command file per supported tool. | -| 03 | [validate](actions/03-validate.md) | Check each command file. | diff --git a/plugins/aidd-context/skills/09-mermaid/README.md b/plugins/aidd-context/skills/09-mermaid/README.md deleted file mode 100644 index 237a3503..00000000 --- a/plugins/aidd-context/skills/09-mermaid/README.md +++ /dev/null @@ -1,29 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 09 - Mermaid - -Generates a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. - -## When to use - -- Turning a written description (architecture, lifecycle, flow) into a Mermaid diagram. -- Producing a diagram to embed in an `INSTALL.md`, a decision record, or a memory file. -- When another skill needs a diagram (for example `01-bootstrap` calls it). - -## When not to use - -- For other diagram formats (PlantUML, Graphviz, draw.io). -- To freehand a diagram without a written source to plan from. -- To render or export to an image. This skill produces fenced Mermaid text only. - -## Flow - -One action with a six-step loop: get the source, plan, confirm the plan, generate, offer a review, review on confirm. The diagram is generated only from the confirmed plan, and never adds an element the user did not confirm. - -## Requires - -A written source (a paragraph, a list, or a section) describing what to diagram. - -## Details - -See [`SKILL.md`](SKILL.md) for the contract, [`actions/01-mermaid.md`](actions/01-mermaid.md) for the process, and [`references/mermaid-conventions.md`](references/mermaid-conventions.md) for the conventions and defaults every diagram follows. diff --git a/plugins/aidd-context/skills/10-learn/README.md b/plugins/aidd-context/skills/10-learn/README.md deleted file mode 100644 index d091b63c..00000000 --- a/plugins/aidd-context/skills/10-learn/README.md +++ /dev/null @@ -1,43 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 10 - Learn - -Distills what a piece of work taught into the project's lasting context. It picks a source, scores each candidate learning, asks the user what to do with each one, writes only the approved lessons, and refreshes the memory block so the next session starts from them. - -## When to use - -- The user states a lasting rule or convention ("from now on", "always", "going forward"). -- A decision is made and worth recording with its rationale. -- Something is deprecated, or a piece of work is worth distilling before moving on. - -## When not to use - -- For personal or AI-preference reminders. Those belong in user memory, not the project. -- For routine edits, minor fixes, or anything already captured. -- To stand up the memory bank itself. Use `aidd-context:02-project-memory`. - -## Requires - -An existing memory bank (`aidd_docs/memory/`). If it is missing, run `aidd-context:02-project-memory` first. - -## Flow - -Four actions, in order: - -1. `gather`: pick a source (the conversation, the git history, or one the user names), collect candidates, drop the noise. -2. `assess`: score each candidate from 0 to 10 with a reason, propose a destination, and ask the user what to do with each. -3. `write`: write the lessons the user approved to their destinations. -4. `sync`: refresh the memory block in every context file. - -## Destinations - -- **Memory**: a fact or convention, into the matching memory file. -- **Decision**: a choice with a rationale, a record in `aidd_docs/memory/internal/decisions/` from `assets/decision-template.md`. -- **Rule**: a convention to enforce, handed to `aidd-context:05-rule-generate`. -- **Skill**: a reusable workflow, handed to `aidd-context:04-skill-generate`. - -The score is the brake (bar 6 of 10), and the user decides every item before anything is written. - -## Details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/). diff --git a/plugins/aidd-context/skills/11-explore/README.md b/plugins/aidd-context/skills/11-explore/README.md deleted file mode 100644 index 7a8eb5c0..00000000 --- a/plugins/aidd-context/skills/11-explore/README.md +++ /dev/null @@ -1,31 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 11 - Explore - -Surveys the current project across three axes so you see what is there, then lets you dig into any of them. It maps the project, it never tells you the next step (that is onboard's job). - -## When to use - -- "What do we have here?" / "What is installed?" / "What is set up?" -- Browsing the AIDD capabilities, the context layer, or the project shape. -- Finding which skill, agent, rule, or hook fits a goal. - -## When not to use - -- For the next logical step to take. Use `aidd-context:00-onboard`. -- To run a found item. Explore points, the user invokes. -- To create a new skill, rule, or agent. Use the generators. - -## The three axes - -- **Tooling**: the installed skills, agents, commands, rules, hooks, MCP servers, and plugins. What you can run. -- **Context**: the memory bank, specs, plans, and the AI context files. What the AI knows. -- **Codebase**: the stack and the high-level structure. What the project is. - -## Flow - -It detects your AI tools first, then routes by what you asked. Name nothing and `survey` reads the three axes and presents a compact map, then proposes one axis or all. Name an axis (or all) and `drill` goes straight in. `drill` lists the level in full, recommends the single best match with its invocation path when you name a goal, and descends one level deeper on request, a skill into its actions, a memory file into its sections, until a leaf or a stop. - -## Details - -See [`SKILL.md`](SKILL.md) for the contract, [`actions/`](actions/) for the two actions, and [`references/ai-mapping.md`](references/ai-mapping.md) for the per-tool scan paths. diff --git a/plugins/aidd-context/skills/12-cook/README.md b/plugins/aidd-context/skills/12-cook/README.md deleted file mode 100644 index d4d04135..00000000 --- a/plugins/aidd-context/skills/12-cook/README.md +++ /dev/null @@ -1,12 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 12 - cook - -Maintain the project's `recipes/` how-to sheets: list them, or create and update one from the canonical template. The recipes are the short runbooks at the root of whatever project the skill runs in. - -| # | Action | Purpose | -| --- | ------------------------------ | ---------------------------------------------- | -| 01 | [list](actions/01-list.md) | List every recipe as a table. | -| 02 | [upsert](actions/02-upsert.md) | Create or update one recipe from the template. | - -See [`SKILL.md`](SKILL.md) for the router and [`assets/recipe-template.md`](assets/recipe-template.md) for the recipe shape. diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 3841384c..399feb29 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -47,7 +47,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-implement.md](skills/00-sdlc/actions/03-implement.md) | - | | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | -| `-` | [README.md](skills/00-sdlc/README.md) | - | | `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended.` | #### `skills/01-plan` @@ -60,7 +59,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-plan.md](skills/01-plan/actions/04-plan.md) | - | | `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | - | | `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | - | -| `-` | [README.md](skills/01-plan/README.md) | - | | `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | | `references` | [wireframe-conventions.md](skills/01-plan/references/wireframe-conventions.md) | - | | `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff.` | @@ -72,7 +70,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-prepare.md](skills/02-implement/actions/01-prepare.md) | - | | `actions` | [02-execute.md](skills/02-implement/actions/02-execute.md) | - | | `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | -| `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | | `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.` | @@ -84,7 +81,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-assert-architecture.md](skills/03-assert/actions/02-assert-architecture.md) | - | | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | | `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | - | -| `-` | [README.md](skills/03-assert/README.md) | - | | `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert the work behaves by iterating the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Not for reviewing or writing tests.` | #### `skills/04-audit` @@ -99,7 +95,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | | `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | | `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | -| `-` | [README.md](skills/04-audit/README.md) | - | | `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Audit a codebase read-only across seven quality pillars into one ranked report. Use when the user wants to assess, health-check, or audit a codebase or one pillar. Not for fixing findings, reviewing a change, or checking a feature works.` | #### `skills/05-review` @@ -110,7 +105,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | | `actions` | [03-review-relevancy.md](skills/05-review/actions/03-review-relevancy.md) | - | | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | -| `-` | [README.md](skills/05-review/README.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | | `-` | [SKILL.md](skills/05-review/SKILL.md) | `Review a diff read-only on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Not for fixing findings or auditing a codebase.` | @@ -120,7 +114,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-test.md](skills/06-test/actions/01-test.md) | - | | `actions` | [02-test-journey.md](skills/06-test/actions/02-test-journey.md) | - | -| `-` | [README.md](skills/06-test/README.md) | - | | `-` | [SKILL.md](skills/06-test/SKILL.md) | `Write and iterate tests until they pass, or validate a user journey end to end in the browser. Use when the user wants to add coverage, find what's untested, or walk a flow. Not for auditing test health or debugging a failure.` | #### `skills/07-refactor` @@ -131,7 +124,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-security.md](skills/07-refactor/actions/02-security.md) | - | | `actions` | [03-cleanup.md](skills/07-refactor/actions/03-cleanup.md) | - | | `actions` | [04-architecture.md](skills/07-refactor/actions/04-architecture.md) | - | -| `-` | [README.md](skills/07-refactor/README.md) | - | | `-` | [SKILL.md](skills/07-refactor/SKILL.md) | `Improve code across four axes (cleanup, performance, security, architecture) by scanning and fixing, or applying a pushed audit report. Use when the user wants to refactor, optimize, harden, or remove code. Not for read-only diagnosis or adding tests.` | #### `skills/08-debug` @@ -142,7 +134,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-debug.md](skills/08-debug/actions/02-debug.md) | - | | `actions` | [03-reflect-issue.md](skills/08-debug/actions/03-reflect-issue.md) | - | | `assets` | [task-template.md](skills/08-debug/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | -| `-` | [README.md](skills/08-debug/README.md) | - | | `references` | [mermaid-conventions.md](skills/08-debug/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `-` | [SKILL.md](skills/08-debug/SKILL.md) | `Reproduce and fix a known bug, or find an unknown root cause by hypothesis validation. Use when the user wants to fix a bug, find why something breaks, or reopen a stuck investigation. Not for building a feature or reviewing a diff.` | @@ -155,7 +146,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | | `assets` | [autonomous-loop-worker-prompt.md](skills/09-for-sure/assets/autonomous-loop-worker-prompt.md) | - | | `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | - | -| `-` | [README.md](skills/09-for-sure/README.md) | - | | `references` | [autonomous-loop-log-format.md](skills/09-for-sure/references/autonomous-loop-log-format.md) | - | | `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Run an iterative agent loop that retries until a runnable success condition passes. Use when the user says "for sure", "keep trying until", or wants guaranteed completion against a success command. Not for one-shot tasks or uncheckable goals.` | @@ -164,6 +154,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-todo.md](skills/10-todo/actions/01-todo.md) | - | -| `-` | [README.md](skills/10-todo/README.md) | - | | `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos and run one executor agent per todo in parallel, then report a minimal table. Use when the user says "todo" or asks to fan out a multi-part request into parallel implementations.` | diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index 99939744..a741fe70 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -14,16 +14,16 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Bracket ID | Skill | Description | |---|---|---| -| [2.0] | [sdlc](skills/00-sdlc/README.md) | Dev SDLC orchestrator (code-shipping pipeline): spec, plan, implement, test, review, commit, PR. | -| [2.1] | [plan](skills/01-plan/README.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. | -| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | -| [2.3] | [assert](skills/03-assert/README.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | -| [2.4] | [audit](skills/04-audit/README.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | -| [2.5] | [review](skills/05-review/README.md) | Review a diff along three axes: code quality, feature behavior against the plan, and relevancy (fit to the need, declared-rule conformance, no rot). | -| [2.6] | [test](skills/06-test/README.md) | Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. | -| [2.7] | [refactor](skills/07-refactor/README.md) | Optimize code for performance and fix security vulnerabilities following OWASP guidelines. | -| [2.8] | [debug](skills/08-debug/README.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. | -| [2.9] | [for-sure](skills/09-for-sure/README.md) | Iterative agent loop that tracks attempts and retries until a success condition is met. | +| [2.0] | [sdlc](skills/00-sdlc/SKILL.md) | Dev SDLC orchestrator (code-shipping pipeline): spec, plan, implement, test, review, commit, PR. | +| [2.1] | [plan](skills/01-plan/SKILL.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. | +| [2.2] | [implement](skills/02-implement/SKILL.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | +| [2.3] | [assert](skills/03-assert/SKILL.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | +| [2.4] | [audit](skills/04-audit/SKILL.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | +| [2.5] | [review](skills/05-review/SKILL.md) | Review a diff along three axes: code quality, feature behavior against the plan, and relevancy (fit to the need, declared-rule conformance, no rot). | +| [2.6] | [test](skills/06-test/SKILL.md) | Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. | +| [2.7] | [refactor](skills/07-refactor/SKILL.md) | Optimize code for performance and fix security vulnerabilities following OWASP guidelines. | +| [2.8] | [debug](skills/08-debug/SKILL.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. | +| [2.9] | [for-sure](skills/09-for-sure/SKILL.md) | Iterative agent loop that tracks attempts and retries until a success condition is met. | ## Agents diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md deleted file mode 100644 index f588e49f..00000000 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ /dev/null @@ -1,68 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 00 - sdlc - -Pure orchestrator for the full AIDD development flow. Takes a free-form request -from idea to shipped code by composing the other skills in this plugin (and any -VCS-providing capabilities loaded at runtime, e.g. commit and pull-request). -Holds no business logic of its own; every step is delegated. - -## When to use - -- A human (or upstream orchestrator) hands over a free-form request and you - need to drive it end-to-end: spec, plan, implement, review, ship. -- You want the default run with confirmation gates (`interactive` mode). -- You want an unattended run with no human prompts (`auto` mode). - -## When NOT to use - -- A single SDLC step is enough → call that skill directly - ([01-plan](../01-plan/README.md), [02-implement](../02-implement/README.md), - [05-review](../05-review/README.md), etc.). -- You need to audit, refactor, debug, test, or assert outside of a shipping - pipeline → see [04-audit](../04-audit/README.md), - [07-refactor](../07-refactor/README.md), [08-debug](../08-debug/README.md), - [06-test](../06-test/README.md), [03-assert](../03-assert/README.md). -- The task has an explicit retry-until-success contract → use - [09-for-sure](../09-for-sure/README.md). - -## How to invoke - -``` -/sdlc # interactive (default): pauses at each gate -/sdlc auto # unattended: no human prompts -``` - -The skill walks 5 actions: - -1. `spec` - consolidate sources, draft or refine the contract (skippable if - the source ticket already carries objective + acceptance criteria). -2. `plan` - produce the mandatory plan file by running `aidd-dev:01-plan` in - the orchestrator's own context (it owns the plan). -3. `implement` - loop milestones via the `executor` agent until complete. -4. `review` - verdict `ship` or `iterate` via the `checker` agent; on - `iterate`, loop back to step 3 with findings. -5. `ship` - commit and open the pull request. - -## Outputs - -- A spec file (unless skipped). -- A plan file in `aidd_docs/tasks/`. -- Atomic commits on the active branch, one per phase. -- A pull request with title, body, base branch, and draft state. -- Findings + completion + quality scores from the checker. - -## Prerequisites - -- HEAD is on a non-default branch when the run is meant to ship. `05-ship` - aborts with `contract_violation: on_default_branch` otherwise. -- The `executor` and `checker` agents are available. -- A VCS-providing capability is loaded at runtime for the ship step - (commit + pull-request creation). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the orchestration contract, the iron rule -("you are the conductor, not a player"), the mode detection logic, and the -five interactive gate definitions. Per-action contracts live in -[`actions/`](actions/). diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md deleted file mode 100644 index 1bf79fb6..00000000 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ /dev/null @@ -1,45 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 01 - plan - -Turns a request, ticket, or file into a phased implementation plan and its phase files. The plan is the single source of truth that downstream skills (`02-implement`, `05-review`) consume. - -## When to use - -- A spec, ticket, or request exists and you need a phased plan with deterministic acceptance criteria before any code change. -- A screen needs its layout fixed with a low-fidelity wireframe before the plan. - -## When NOT to use - -- You already have a plan and need to write code → use [02-implement](../02-implement/README.md). -- The task is a single fix with no planning surface → use [08-debug](../08-debug/README.md) or edit directly. -- You want spec drafting, not planning → use the project's spec-drafting capability. - -## How to invoke - -``` -Use skill aidd-dev:01-plan -``` - -The skill runs four actions in order, the plan being the culmination: - -1. `gather` collects the source the plan rests on and restates it. Always first. -2. `explore` reads the codebase for the architecture projection, the applicable rules, and feasibility. Gated with the user. -3. `wireframe` sketches a low-fidelity ASCII layout of any screen the feature needs, using the explored context. Frontend only, skipped when there is no UI. -4. `plan` breaks the work into phases and writes the plan and its phase files. - -A feature folder `aidd_docs/tasks//_/`: - -- `plan.md` from the plan template: objective, phases, resources, decisions. -- `phase-.md` per phase from the phase template: projection slice, user journey, tasks, acceptance criteria, any wireframe. - -The plan reuses the folder when the source already lives in one, so a `brainstorm.md` or `spec.md` already there sits alongside, not duplicated. - -## Prerequisites - -- A request, ticket, or file as the source. -- The plan and phase templates bundled with this skill. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action flow, [`assets/plan-template.md`](assets/plan-template.md) for the plan format, and [`actions/`](actions/) for the per-action contracts. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md deleted file mode 100644 index ea254931..00000000 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ /dev/null @@ -1,45 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 02 - implement - -Executes an existing implementation plan phase by phase, iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. - -## When to use - -- A plan produced by [01-plan](../01-plan/README.md) is ready and you need the code written against it. -- An iteration of [00-sdlc](../00-sdlc/README.md) delegates the implement step. - -## When NOT to use - -- No plan exists yet → use [01-plan](../01-plan/README.md) first. -- The plan is wrong and needs replanning → replan with [01-plan](../01-plan/README.md); this skill never rewrites the plan. -- A bug fix with no plan surface → use [08-debug](../08-debug/README.md). - -## How to invoke - -``` -Use skill aidd-dev:02-implement -``` - -Pass the plan path or content as the arguments. The skill runs three actions in order: - -1. **prepare**: fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. -2. **execute**: loops the plan's phases: per phase it sets `status: in-progress` as a runtime marker, codes the phase, asserts it clean, then commits the phase and sets `status: done`; stops at `status: blocked` on a human-only condition. -3. **finalize**: runs validation, then marks the plan `status: implemented` once every phase is done. - -**Commits**: code and status are committed together, one commit per phase, plus a final `implemented` commit. The `in-progress` marks are runtime-only, so the tree is never left dirty at a phase boundary. - -## Outputs - -- Code for the feature, one phase at a time, committed on the active feature branch, one commit per phase. -- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked`. -- A `replan needed` report when the plan no longer matches reality; this recipe never rewrites the plan. - -## Prerequisites - -- A plan file with phases and acceptance criteria, from `01-plan`. -- Project conventions honoured by whoever runs the recipe. - -## Technical details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the prepare/execute/finalize split: the branch guard, the phase loop, the assert gate, the status lifecycle, and the boundary constraints (no formatting, no dev mode). diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md deleted file mode 100644 index 2d79a27d..00000000 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ /dev/null @@ -1,58 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 03 - assert - -A gate that validates the work behaves as intended: it iterates the project's -coding assertions until they pass, with optional architecture-conformance and -running-frontend facets. Returns a pass or fail verdict. - -## When to use - -- Work is implemented and you need to assert it behaves as intended - before merging or shipping. -- You need to verify code conforms to documented architecture (ADRs, - diagrams, structure). -- A frontend change needs visual / behavioral validation in a real browser. - -## When NOT to use - -- The work isn't built yet → plan first with - [01-plan](../01-plan/README.md) and implement with - [02-implement](../02-implement/README.md). -- You want a rule-based code review → use - [05-review](../05-review/README.md). -- You're writing tests for the first time → use - [06-test](../06-test/README.md). - -## How to invoke - -``` -Use skill aidd-dev:03-assert -``` - -The skill exposes 3 facets, run together when applicable or one when named: - -1. `assert` - the coding-assertion loop; always applies. -2. `assert-architecture` - report where code breaks the documented - architecture (ADRs, diagrams, structure); report only, opt-in. -3. `assert-frontend` - drive a browser to confirm the frontend - behaves as intended; needs a running frontend (it resolves the URL). - -## Outputs - -- A pass or fail verdict on the work (this is a gate, not a stored report). -- The fixes applied by the coding and frontend facets. -- The conformance violations from the architecture facet. - -## Prerequisites - -- An explicit acceptance criterion, architecture artifact, or frontend - surface to validate against. -- A running dev server / preview when asserting frontend. -- Browser automation tooling available in the runtime for the frontend - variant. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action list. Per-action contracts live -in [`actions/`](actions/). diff --git a/plugins/aidd-dev/skills/04-audit/README.md b/plugins/aidd-dev/skills/04-audit/README.md deleted file mode 100644 index 6e534c45..00000000 --- a/plugins/aidd-dev/skills/04-audit/README.md +++ /dev/null @@ -1,66 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 04 - audit - -Read-only codebase audit across seven quality pillars. Diagnoses and ranks -findings into a structured report; it never edits code. Each finding carries -a suggested fix for a later act-skill to apply. - -## When to use - -- You want a global health check of the codebase, or a deep look at one - dimension (security, performance, dependencies, ...). -- You're preparing a refactor and need a prioritized, located list of issues. -- A new contributor (or a stale repo) needs hidden problems surfaced. - -## When NOT to use - -- A specific bug is already known → use [08-debug](../08-debug/README.md). -- You want to fix the problems → run the audit first, then an act-skill such - as [07-refactor](../07-refactor/README.md) or - [06-test](../06-test/README.md). -- You want a per-PR code review → use [05-review](../05-review/README.md). -- You want to validate a feature works → use [03-assert](../03-assert/README.md). - -## How to invoke - -``` -Use skill aidd-dev:04-audit -``` - -Run-one or run-all: - -- Name a pillar (`audit security`, `perf audit`) → one pillar. -- Ask for a full audit (`/audit`, "health check") → the skill asks "full or a - specific pillar?", then scans all applicable pillars into one merged report. - -The seven pillars: - -1. `code-quality` - clean code (naming, SOLID, DRY, smells) + tech debt. -2. `architecture` - C4 / ADR conformance, coupling, boundaries, layering. -3. `security` - OWASP, authz, input validation, secrets. -4. `dependencies` - CVEs, licenses, outdated and unused deps. -5. `performance` - N+1, hot paths, bundle size, heavy operations. -6. `tests` - critical-path coverage, flakiness, pyramid balance. -7. `ui` - states, visual hierarchy, design-system drift, responsive, a11y. - -## Outputs - -- One structured report: a findings table (severity, pillar, `file:line`, - issue, fix, effort), a ranked Top-actions list, and a Coverage section - proving which pillars were scanned (and which were skipped, with reason). - -## Prerequisites - -- Project rules and architecture docs loaded in context (the audit grades - against them). -- Read access to the codebase. -- For tool/runtime pillars (dependencies, performance, tests, ui): the - relevant tool when available; otherwise that pillar degrades or is skipped - with a recorded reason. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the routing + output contract, the -`actions/0X-.md` files for each pillar's lens and method, and -[`assets/audit-template.md`](assets/audit-template.md) for the report shape. diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md deleted file mode 100644 index 96962343..00000000 --- a/plugins/aidd-dev/skills/05-review/README.md +++ /dev/null @@ -1,69 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 05 - review - -Reviews a diff along three axes: code quality (clean-code), feature behavior -against the plan's acceptance criteria, and relevancy (does the change belong: -fit to the need, declared-rule conformance, no rot). Read-only: surfaces -findings and one verdict into a single report, never edits the artifact. Runs -all three axes by default, or one when named. - -## When to use - -- A feature is implemented and you need an independent verdict before - shipping. -- A diff needs a grounded review without ad-hoc opinion. - -## When NOT to use - -- You want to assert runtime behavior, not review code → use - [03-assert](../03-assert/README.md). -- You want to fix the issues, not surface them → use - [02-implement](../02-implement/README.md) or - [07-refactor](../07-refactor/README.md) after the review. -- You want a global codebase audit, not a per-feature review → use - [04-audit](../04-audit/README.md). - -## How to invoke - -``` -Use skill aidd-dev:05-review # all three axes -Use skill aidd-dev:05-review review-relevancy # one named axis -``` - -The skill exposes 3 axes, run together by default or one when named: - -1. `review-code` - grade the diff against clean-code principles; surface - violations with file and line. -2. `review-functional` - trace the feature against the plan's phases; each - acceptance criterion a checked or unchecked box, plus a verification summary. -3. `review-relevancy` - judge whether the change belongs: fit to the need, - conformance to the project's declared rules, and no duplication or - over-engineering. - -## Outputs - -- One read-only `review.md` in the reviewed work's feature folder, beside - `plan.md`, never patches the code: - - Header: the overall verdict (`approve` / `changes-requested` / `blocked`), - scope, and findings count. - - `Phases`: plan phases with a checked or unchecked box per acceptance - criterion (functional axis). - - `Findings`: one table for every axis (🔴 / 🟡 / 🟢), Kind (`code` / `fit` / - `conform` / `rot`), a Phase column, and `file:line`; code and relevancy - append their rows here. - - `Verification`: percent verified, files checked, a tag on each unchecked - criterion, and the unplanned changes. - - Each axis runs independently, appending to the shared report. - -## Prerequisites - -- A diff or a set of changes to review. -- A plan file with explicit acceptance criteria for the functional axis. -- The project's declared rules, discovered at runtime, for the relevancy axis. - -## Technical details - -See [`SKILL.md`](SKILL.md), [`actions/`](actions/), and the report template in -[`assets/`](assets/) for the three review axes and the single report they -compose. diff --git a/plugins/aidd-dev/skills/06-test/README.md b/plugins/aidd-dev/skills/06-test/README.md deleted file mode 100644 index 452e7826..00000000 --- a/plugins/aidd-dev/skills/06-test/README.md +++ /dev/null @@ -1,56 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 06 - test - -Writes and iterates on tests until they pass, and validates user journeys -end-to-end through browser automation. Identifies untested behaviors first, -then drives test creation until quality criteria are met. - -## When to use - -- A feature has insufficient test coverage and you want a list of - untested behaviors plus iteration toward passing tests. -- A user journey needs end-to-end validation in a real browser before - shipping. -- You want test-first iteration on an existing module. - -## When NOT to use - -- You want to assert a single criterion, not build a test suite → use - [03-assert](../03-assert/README.md). -- You're debugging a known failure → use - [08-debug](../08-debug/README.md). -- You want a rule-based code review of existing tests → use - [05-review](../05-review/README.md). - -## How to invoke - -``` -Use skill aidd-dev:06-test -``` - -The skill exposes 2 actions: - -1. `test` - list untested behaviors and iterate on test creation until - tests pass with best practices applied. -2. `test-journey` - navigate a user journey in the browser and validate - each step end-to-end. - -## Outputs - -- New or updated test files following project test conventions. -- A list of remaining untested behaviors when coverage is incomplete. -- A journey transcript with per-step verdicts for the browser variant. - -## Prerequisites - -- A test runner configured in the repo (Jest, Vitest, Playwright, etc.). -- A running app / preview when validating user journeys. -- Browser automation tooling available in the runtime for the journey - variant. - -## Technical details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two test -contracts. The journey action depends on browser tooling exposed by the -runtime. diff --git a/plugins/aidd-dev/skills/07-refactor/README.md b/plugins/aidd-dev/skills/07-refactor/README.md deleted file mode 100644 index acb06dd9..00000000 --- a/plugins/aidd-dev/skills/07-refactor/README.md +++ /dev/null @@ -1,72 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 07 - refactor - -Improves code without breaking behavior across four axes: cleanup -(clean-code + tech debt), performance, security, and architecture. It is -the act-side counterpart of [04-audit](../04-audit/README.md) - audit -reports, refactor fixes. - -## When to use - -- You want to clean up, optimize, harden, or restructure existing code. -- An [04-audit](../04-audit/README.md) report flagged issues to fix now - - push the report into refactor and it fixes the listed findings. -- A profile, security review, or coupling problem points to a concrete - improvement. - -## When NOT to use - -- You only want a read-only diagnosis → run [04-audit](../04-audit/README.md). -- The task is a functional bug fix → use [08-debug](../08-debug/README.md). -- You want to add new behavior, not improve existing → use - [02-implement](../02-implement/README.md). -- You want to add tests → [06-test](../06-test/README.md). - -## How to invoke - -``` -Use skill aidd-dev:07-refactor -``` - -Run-one or run-all: - -- Name an axis (`optimize`, `harden`, `clean up`, `restructure`) → that axis. -- Unscoped (`refactor this`) → the skill asks "all applicable axes, or a - specific one?", then runs the chosen one or all. - -The four axes (each maps to an audit pillar): - -1. `performance` - N+1, hot paths, batching, memoization. -2. `security` - OWASP, validation, authz, secrets (may change behavior to - close a hole). -3. `cleanup` - clean-code: rename, extract, DRY, dead-code, complexity. -4. `architecture` - extract layers, fix coupling, enforce boundaries. - -## Audit handoff (push, never pull) - -Refactor never loads the audit skill. Each axis runs **standalone** (scans -its lens, then fixes) or **audit-fed** when the caller pushes an -`audit_report` (path under `aidd_docs/tasks/audits/` or pasted findings) - -then it fixes that report's findings for its axis and skips its own scan. -The bridge is the report artifact, not a cross-skill dependency. - -## Outputs - -- Code changes scoped to the axis, with a list of `changes_applied`. -- Behavior-preserving verification (tests / types / side-by-side) for - cleanup, performance, architecture; an explicit behavior-change call-out - for security. - -## Prerequisites - -- Tests in place so the refactor is verifiable (or scheduled via - [06-test](../06-test/README.md)). -- For the architecture axis: the documented architecture (C4 / ADRs) in - `aidd_docs/memory/` to enforce against; large moves may need - [01-plan](../01-plan/README.md) first. - -## Technical details - -See [`SKILL.md`](SKILL.md) for routing + the push-not-pull audit handoff, -and [`actions/`](actions/) for each axis contract. diff --git a/plugins/aidd-dev/skills/08-debug/README.md b/plugins/aidd-dev/skills/08-debug/README.md deleted file mode 100644 index 10775b76..00000000 --- a/plugins/aidd-dev/skills/08-debug/README.md +++ /dev/null @@ -1,58 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 08 - debug - -Reproduces and fixes bugs systematically using a test-driven workflow: -reproduce the failure, reflect on hypotheses, validate with logs, then -apply a targeted fix. Drives the loop from issue to PR. - -## When to use - -- A bug is reported and you want a disciplined reproduce → diagnose → - fix → verify loop. -- A flaky test or intermittent failure needs root-cause analysis backed by - validation logs. -- An issue exists in the tracker and you want to ship the fix as a PR. - -## When NOT to use - -- The work is new feature development → use - [00-sdlc](../00-sdlc/README.md) or - [02-implement](../02-implement/README.md). -- The fix is a refactor with no behavioral defect → use - [07-refactor](../07-refactor/README.md). -- You want broad coverage analysis, not one bug → use - [04-audit](../04-audit/README.md). - -## How to invoke - -``` -Use skill aidd-dev:08-debug -``` - -The skill exposes 3 actions: - -1. `reproduce` - produce a deterministic reproduction (failing test or - command). -2. `debug` - diagnose the root cause and apply the fix. -3. `reflect-issue` - enumerate likely causes, rank them, add validation - logs before committing to a hypothesis. - -## Outputs - -- A failing reproduction (test or script) that turns green after the fix. -- A root-cause note attached to the issue or PR. -- Targeted fix commits scoped to the defect. -- Updated tests covering the regression. - -## Prerequisites - -- An issue or report describing the failure (stack trace, repro steps, - expected vs observed). -- Test infrastructure able to host the reproduction. - -## Technical details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the three -debug contracts. The reflect-issue action explicitly mandates logs before -acting, to prevent jumping to the wrong hypothesis. diff --git a/plugins/aidd-dev/skills/09-for-sure/README.md b/plugins/aidd-dev/skills/09-for-sure/README.md deleted file mode 100644 index 9bee2507..00000000 --- a/plugins/aidd-dev/skills/09-for-sure/README.md +++ /dev/null @@ -1,66 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 09 - for-sure - -Autonomous loop that runs until a `success_condition` is verified. Two -phases: interactive pre-flight (human present), then autonomous execution -(human gone). The agent auto-accepts everything, acts as the user, and -never stops until the success condition holds. - -## When to use - -- The user says "for sure", "make sure", "keep trying until", "loop until - done", "don't stop until", or otherwise requests guaranteed completion. -- A long-running task with an explicit, verifiable success condition can - run unattended. -- You need a retry loop that tracks attempts in a durable tracking file. - -## When NOT to use - -- No verifiable success condition exists → define one first, or use a - one-shot skill. -- The task is part of a standard SDLC pipeline → use - [00-sdlc](../00-sdlc/README.md). -- The task is a single bug fix → use [08-debug](../08-debug/README.md). -- The task needs human gates mid-loop - this skill auto-accepts and never - asks once it enters Phase 2. - -## How to invoke - -``` -/for-sure -``` - -The skill exposes 3 actions across two phases: - -1. `init-tracking` (Phase 1, interactive) - pre-flight validation, - create the tracking file, spawn the first autonomous agent. -2. `auto-accept` (Phase 2) - activate auto-accept mode for the - autonomous run. -3. `autonomous-loop` (Phase 2) - orchestrator that spawns one worker per - step, verifies output, retries on failure with a meaningful change, - evaluates the success condition. - -## Outputs - -- A tracking file at `aidd_docs/tasks/.md` (state in the - `status` frontmatter field) from For Sure's own plan template, which - extends the [01-plan](../01-plan/README.md) format with - `success_condition` and `iteration`. -- Per-attempt log entries inside the tracking file. -- The tracking file's `status` set to `implemented` once and only once the - success condition genuinely verifies. - -## Prerequisites - -- An explicit `success_condition` expressed as a command whose exit code - (or output) decides success. -- Acceptance criteria and steps documented in the tracking file. -- Task-specific secrets validated during pre-flight (Phase 1). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the iron rules (single source of truth, -no repeated failures, honesty over escape, auto-accept) and -[`actions/`](actions/) for the per-phase contracts. The tracking file -uses For Sure's own plan template asset (`@assets/plan-template.md`). diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md deleted file mode 100644 index 734bde80..00000000 --- a/plugins/aidd-dev/skills/10-todo/README.md +++ /dev/null @@ -1,19 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 10 - todo - -Split one prompt into independent todos, run one executor agent per -todo in parallel (each refines its todo before coding), and report a -minimal table: category, what was launched, output. - -## When to use - -- The user says "todo" or `/todo`. -- A single prompt bundles several independent tasks that can be - implemented in parallel. - -## Actions - -| # | Action | Purpose | -| --- | --------------------------------- | --------------------------------------------- | -| 01 | [todo](actions/01-todo.md) | Categorize, launch parallel agents, report. | diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 625b679b..3b881985 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -24,7 +24,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| -| `-` | [README.md](skills/00-async-dev/README.md) | - | | `references` | [routing.md](skills/00-async-dev/references/routing.md) | - | | `-` | [SKILL.md](skills/00-async-dev/SKILL.md) | `Drive the async-dev pipeline from one entry point, whether setup, run, or review. Use when the user wants to install async dev, run a ready issue, or address PR review comments, or on a webhook trigger. Not for plain status checks.` | diff --git a/plugins/aidd-orchestrator/README.md b/plugins/aidd-orchestrator/README.md index 3c90de17..15eab9e7 100644 --- a/plugins/aidd-orchestrator/README.md +++ b/plugins/aidd-orchestrator/README.md @@ -16,9 +16,9 @@ Composes capabilities into deterministic, auditable flows. Each skill is one orc | Bracket ID | Skill | Description | |------------|-------|-------------| -| [6.0] | [async-dev](skills/00-async-dev/README.md) | Single router-based skill covering the full pipeline — setup, run, and review — selected by `$ARGUMENTS` keyword, trigger source, repo state, or natural-language intent. | +| [6.0] | [async-dev](skills/00-async-dev/SKILL.md) | Single router-based skill covering the full pipeline — setup, run, and review — selected by `$ARGUMENTS` keyword, trigger source, repo state, or natural-language intent. | -See the [skill README](skills/00-async-dev/README.md) for the sub-flow inventory and invocation contract. +See the [skill's SKILL.md](skills/00-async-dev/SKILL.md) for the sub-flow inventory and invocation contract. ### Roadmap diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/README.md b/plugins/aidd-orchestrator/skills/00-async-dev/README.md deleted file mode 100644 index 32097d12..00000000 --- a/plugins/aidd-orchestrator/skills/00-async-dev/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-orchestrator](../../README.md) - -# 00 - Async-dev - -Single entry point for the async-dev pipeline. Hybrid router that picks one of three internal sub-flows (`setup`, `run`, `review`) from `$ARGUMENTS` keyword, trigger source, repo state, or natural-language intent, then runs that sub-flow to completion. - -## When to use - -- You want to install / configure async-dev in a repo. -- A GitHub event fires (`to-implement` / `to-review` label, `@claude /implement` or `/review` comment) and the workflow needs to react. -- You want to handle a ready issue or address review comments on an open PR. -- The user types "async dev", "/async-dev", or mixes phases ("set up async dev and run on issue 42"). - -## When NOT to use - -- For plain status checks on the async pipeline (read labels / comments directly). -- For SDLC orchestration unrelated to issue / PR automation (use `aidd-dev:00-sdlc`). -- From inside a sub-flow action, actions never re-enter the router. - -## How to invoke - -```text -Use skill aidd-orchestrator:00-async-dev -``` - -With an explicit sub-flow keyword (preferred from CI): - -```text -Use skill aidd-orchestrator:00-async-dev with action=setup -Use skill aidd-orchestrator:00-async-dev with action=run on issue #42 -Use skill aidd-orchestrator:00-async-dev with action=review on PR #17 -``` - -The router reads `$ARGUMENTS`, then trigger env, then repo state, then natural intent. See [`references/routing.md`](references/routing.md) for the full decision tree. - -## Sub-flows - -| Sub-flow | First action | Cardinality | -| -------- | -------------------------------------------------- | ------------------ | -| Setup | [`actions/setup/01-detect-context.md`](actions/setup/01-detect-context.md) | 11 actions, run once per install | -| Run | [`actions/run/01-poll-ready.md`](actions/run/01-poll-ready.md) | 6 actions, run once per ready issue | -| Review | [`actions/review/01-collect-comments.md`](actions/review/01-collect-comments.md) | 4 actions, looped on the PR until stop | - -## Output -Each sub-flow defines its own outputs: - -- **Setup**: workflow file, config file, scripts, labels, schedule routine id (if applicable). -- **Run**: `run-result.json` artefact consumed by the workflow's post-job. -- **Review**: stop-reason + structured summary comment on the PR. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the hybrid routing contract, sub-flow indexes, and rules. -See [`references/routing.md`](references/routing.md) for the full decision tree. diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index a262047f..f7268dce 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -28,7 +28,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-ticket-info.md](skills/01-ticket-info/actions/01-ticket-info.md) | - | -| `-` | [README.md](skills/01-ticket-info/README.md) | - | | `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display a ticket from the configured ticketing tool. Use when the user wants to see, show, or look up a ticket's details. Not for creating a ticket, or commenting on, transitioning, or reassigning one.` | #### `skills/02-user-stories` @@ -42,7 +41,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-prioritize.md](skills/02-user-stories/actions/05-prioritize.md) | - | | `actions` | [06-sync-tracker.md](skills/02-user-stories/actions/06-sync-tracker.md) | - | | `assets` | [user-story-template.md](skills/02-user-stories/assets/user-story-template.md) | - | -| `-` | [README.md](skills/02-user-stories/README.md) | - | | `references` | [rating.md](skills/02-user-stories/references/rating.md) | - | | `-` | [SKILL.md](skills/02-user-stories/SKILL.md) | `Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog in the tracker. Use when the user wants to create, split, estimate, or prioritize user stories. Not for source code or a PRD.` | @@ -53,7 +51,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | | `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | - | | `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | -| `-` | [README.md](skills/03-prd/README.md) | - | | `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a need, idea, or brainstorm, confirmed before save. Use when the user wants to draft or generate a PRD or product requirements. Not for user stories or a technical plan.` | #### `skills/04-spec` @@ -63,6 +60,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-build.md](skills/04-spec/actions/01-build.md) | - | | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | -| `-` | [README.md](skills/04-spec/README.md) | - | | `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec.` | diff --git a/plugins/aidd-pm/README.md b/plugins/aidd-pm/README.md index 1edfea84..308914a3 100644 --- a/plugins/aidd-pm/README.md +++ b/plugins/aidd-pm/README.md @@ -14,7 +14,7 @@ Covers ticket information retrieval, user story creation, product requirement do | Bracket ID | Skill | Description | |---|---|---| -| [4.1] | [ticket-info](skills/01-ticket-info/README.md) | Retrieve and display ticket information from the configured ticketing tool. | -| [4.2] | [user-stories](skills/02-user-stories/README.md) | Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog. | -| [4.3] | [prd](skills/03-prd/README.md) | Generate a structured Product Requirements Document. | -| [4.4] | [spec](skills/04-spec/README.md) | Generate and refine a project spec from a free-form human request. The spec is the immutable target a planner consumes. | +| [4.1] | [ticket-info](skills/01-ticket-info/SKILL.md) | Retrieve and display ticket information from the configured ticketing tool. | +| [4.2] | [user-stories](skills/02-user-stories/SKILL.md) | Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog. | +| [4.3] | [prd](skills/03-prd/SKILL.md) | Generate a structured Product Requirements Document. | +| [4.4] | [spec](skills/04-spec/SKILL.md) | Generate and refine a project spec from a free-form human request. The spec is the immutable target a planner consumes. | diff --git a/plugins/aidd-pm/skills/01-ticket-info/README.md b/plugins/aidd-pm/skills/01-ticket-info/README.md deleted file mode 100644 index fece34b3..00000000 --- a/plugins/aidd-pm/skills/01-ticket-info/README.md +++ /dev/null @@ -1,52 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 01 - Ticket Info - -Reads ticket details from the configured ticketing tool and displays them in -the chat. Read-only and tool-agnostic: the same skill works whether the -project is on Jira, Linear, GitHub Issues, or any other tracker recorded in -the project memory. - -## When to use - -- "ticket info", "show ticket", "get ticket", "ticket details". -- "what's " when `` looks like a ticket reference. -- Invoking `/ticket-info`. -- Pulling a ticket id from the current branch name when no id is supplied. - -## When NOT to use - -- To create a new issue, use a skill that advertises issue creation in its description (run `/plugin` and browse the **Discover** tab to find one). -- To comment on, transition, or reassign a ticket - this skill is read-only. -- For free-form ticket searches across a project; this skill targets one id. - -## How to invoke - -``` -Use skill aidd-pm:01-ticket-info on -``` - -Or, with no id, let the skill auto-detect from the current git branch: - -``` -Use skill aidd-pm:01-ticket-info -``` - -## Outputs - -- A chat-rendered summary of the ticket: id, title, status, assignee, type, - priority, and description, formatted per the configured tool's conventions. -- No files written. No tracker mutations. - -## Prerequisites - -- Project memory declares the active ticketing tool (or repo config / - environment makes it inferable). -- Auth for that tool is reachable from the runtime (MCP server, CLI, or API - token already configured at the project level). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and -[`actions/01-ticket-info.md`](actions/01-ticket-info.md) for the single -atomic action that resolves the id, queries the tool, and formats output. diff --git a/plugins/aidd-pm/skills/02-user-stories/README.md b/plugins/aidd-pm/skills/02-user-stories/README.md deleted file mode 100644 index 95763b00..00000000 --- a/plugins/aidd-pm/skills/02-user-stories/README.md +++ /dev/null @@ -1,58 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 02 - User Stories - -Turns a feature or epic into a prioritized backlog of INVEST-compliant user -stories. Each story carries acceptance criteria, a pragmatic functional -Definition of Done, an effort estimate, and an impact rating, then is saved to -the project's configured tracker once you validate the draft. - -## When to use - -- "user stories", "create user stories", "write user stories for X". -- "INVEST stories", "draft stories". -- "split this epic", "break down this feature". -- "estimate stories", "prioritize the backlog". -- Invoking `/user-stories`. -- Right after a brainstorming session, when scope is clear enough to slice. - -## When NOT to use - -- To write source code - this skill produces stories, not implementation. -- To draft a full PRD → use `03-prd`. -- To refine a single existing story (edit the tracker directly). -- To copy already-ready story text into a tracker (just paste it). - -## How to invoke - -``` -Use skill aidd-pm:02-user-stories for -``` - -The skill clarifies in at most 3 questions per round, splits an epic into -candidate stories, drafts them, estimates effort and impact, ranks the -backlog, shows it for explicit validation, then saves on confirmation. - -## Outputs - -- A set of INVEST-compliant user stories, each with acceptance criteria, a - functional Definition of Done, dependencies, and story points. -- An impact rating (minor, major, critic) per story. -- The backlog ranked by value against effort and impact. -- One ticket per story created in the configured tracker after explicit - validation. - -## Prerequisites - -- Project memory declares the active ticketing tool with write access. -- A clear-enough feature description; if too vague, the skill asks you to - brainstorm first rather than fabricating stories. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, the files under -[`actions/`](actions) for each step of the chain, -[`references/rating.md`](references/rating.md) for the INVEST, readiness, -Definition of Done, impact, and prioritization definitions, and -[`assets/user-story-template.md`](assets/user-story-template.md) for the story -body template. diff --git a/plugins/aidd-pm/skills/03-prd/README.md b/plugins/aidd-pm/skills/03-prd/README.md deleted file mode 100644 index 9e1a59a3..00000000 --- a/plugins/aidd-pm/skills/03-prd/README.md +++ /dev/null @@ -1,52 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 03 - PRD - -Drafts a structured Product Requirements Document covering scope, goals, -and acceptance criteria from a feature description or a set of user stories. -Stays at the "what and why" level; never crosses into implementation detail. - -## When to use - -- "prd", "draft prd", "write prd". -- "product requirements for X", "generate a prd". -- Invoking `/prd`. -- After user stories are ready and you need a single document to align - stakeholders before planning starts. - -## When NOT to use - -- To write user stories → use `02-user-stories`. -- To draft a technical implementation plan (libraries, file layout, - algorithms) - those belong to the planning skill in your dev capability. -- To write source code. - -## How to invoke - -``` -Use skill aidd-pm:03-prd for -``` - -The skill parses the input, drafts each section per template, shows the -draft, and waits for explicit validation before saving. - -## Outputs - -- A PRD file saved at - `aidd_docs/tasks//--prd.md`. -- Sections: scope, goals, non-goals, user stories or personas, acceptance - criteria, and any task references needed. -- No tracker mutations. - -## Prerequisites - -- A feature description, a set of user stories, or both. -- Write access to `aidd_docs/tasks/` in the current repo. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, -[`actions/01-prd.md`](actions/01-prd.md) for the single atomic action, -[`assets/prd-template.md`](assets/prd-template.md) for the PRD structure, -and [`assets/task-template.md`](assets/task-template.md) for the lightweight -task template referenced from the PRD when needed. diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md deleted file mode 100644 index 8a593136..00000000 --- a/plugins/aidd-pm/skills/04-spec/README.md +++ /dev/null @@ -1,60 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 04 - Spec - -Generate or refine the immutable contract for a feature: its target, hard -constraints, non-goals, and done-when. The spec stays free of implementation -detail and is locked once validated. - -## When to use - -- "draft spec", "spec for X", "generate spec from prd". -- "refine the spec" when review findings come back. -- Invoking `/spec`. - -## When NOT to use - -- To write source code. -- To draft a full PRD → use `03-prd`. -- To modify a spec that has already been validated and locked - the spec - is immutable past that point; open a new spec instead. - -## How to invoke - -Build a fresh spec from a request or an existing PRD: - -``` -Use skill aidd-pm:04-spec build for -``` - -Refine an existing spec from review findings: - -``` -Use skill aidd-pm:04-spec refine on with -``` - -The router picks the action from the inputs: presence of `existing_spec` -and `findings` triggers `refine`; otherwise `build` runs. - -## Outputs - -- A spec file structured per [`assets/spec-template.md`](assets/spec-template.md), - with explicit non-goals, bulleted acceptance criteria, and `TBD: ` markers wherever information is missing. -- On `refine`: the same file rewritten to address the supplied findings. -- The skill never self-validates. A spec is checked against - [`assets/spec-validator.yml`](assets/spec-validator.yml); the findings come - back through `refine` for the next iteration. - -## Prerequisites - -- A free-form request, an existing PRD path, or an existing spec plus a - set of review findings. -- Write access to the spec target path in the current repo. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, -[`actions/01-build.md`](actions/01-build.md) and -[`actions/02-refine.md`](actions/02-refine.md) for the two actions, -and [`assets/`](assets/) for the spec template plus the validator checklist. diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md index bd5c4135..4042c979 100644 --- a/plugins/aidd-refine/CATALOG.md +++ b/plugins/aidd-refine/CATALOG.md @@ -41,7 +41,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-integrate.md](skills/01-brainstorm/actions/03-integrate.md) | - | | `actions` | [04-finalize.md](skills/01-brainstorm/actions/04-finalize.md) | - | | `assets` | [question-angles.md](skills/01-brainstorm/assets/question-angles.md) | - | -| `-` | [README.md](skills/01-brainstorm/README.md) | - | | `references` | [probing.md](skills/01-brainstorm/references/probing.md) | - | | `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague idea through deep questioning until it is precise enough to act on. Use when the user surfaces a half-formed idea or under-specified request, or asks to brainstorm or refine. Not for scanning an artifact for gaps or writing code.` | @@ -51,7 +50,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-challenge.md](skills/02-challenge/actions/01-challenge.md) | - | | `assets` | [report-template.md](skills/02-challenge/assets/report-template.md) | - | -| `-` | [README.md](skills/02-challenge/README.md) | - | | `references` | [confidence-rubric.md](skills/02-challenge/references/confidence-rubric.md) | - | | `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.` | @@ -61,7 +59,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-condense.md](skills/03-condense/actions/01-condense.md) | - | | `actions` | [02-stats.md](skills/03-condense/actions/02-stats.md) | - | -| `-` | [README.md](skills/03-condense/README.md) | - | | `references` | [intensity-levels.md](skills/03-condense/references/intensity-levels.md) | - | | `-` | [SKILL.md](skills/03-condense/SKILL.md) | `Toggle terse output mode (lite, full, ultra) that drops filler while code and errors stay verbatim, and report token savings. Use to condense output, switch intensity, or check savings. Not for editing prose or compressing code.` | @@ -73,7 +70,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-render-report.md](skills/04-shadow-areas/actions/02-render-report.md) | - | | `actions` | [03-diff.md](skills/04-shadow-areas/actions/03-diff.md) | - | | `assets` | [report-template.md](skills/04-shadow-areas/assets/report-template.md) | - | -| `-` | [README.md](skills/04-shadow-areas/README.md) | - | | `references` | [categories.md](skills/04-shadow-areas/references/categories.md) | - | | `references` | [locked-sets.json](skills/04-shadow-areas/references/locked-sets.json) | - | | `references` | [probe-style.md](skills/04-shadow-areas/references/probe-style.md) | - | @@ -88,7 +84,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-verify.md](skills/05-fact-check/actions/02-verify.md) | - | | `actions` | [03-report.md](skills/05-fact-check/actions/03-report.md) | - | | `assets` | [report-template.md](skills/05-fact-check/assets/report-template.md) | - | -| `-` | [README.md](skills/05-fact-check/README.md) | - | | `references` | [claim-categories.md](skills/05-fact-check/references/claim-categories.md) | - | | `references` | [report-output-discipline.md](skills/05-fact-check/references/report-output-discipline.md) | - | | `references` | [verification-cascade.md](skills/05-fact-check/references/verification-cascade.md) | - | diff --git a/plugins/aidd-refine/README.md b/plugins/aidd-refine/README.md index 65fd8ef2..2783aad4 100644 --- a/plugins/aidd-refine/README.md +++ b/plugins/aidd-refine/README.md @@ -14,8 +14,8 @@ Five skills that refine inputs and outputs through reflection: clarify vague req | Bracket ID | Skill | Description | | ---------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [5.1] | [brainstorm](skills/01-brainstorm/README.md) | Clarify a vague request through a bounded loop of targeted questions over six clarity dimensions, converging until the request is precise or the user is satisfied. | -| [5.2] | [challenge](skills/02-challenge/README.md) | Rethink prior work to verify correctness against an agreed plan, classifying findings with a confidence score. | -| [5.3] | [condense](skills/03-condense/README.md) | Toggle terse output mode with intensity levels so prose drops fluff while code, errors, and warnings stay verbatim. | -| [5.4] | [shadow-areas](skills/04-shadow-areas/README.md) | Analytical scan of a written artifact for blind spots: each gap is classified by category and severity, paired with a direct-question probe. | -| [5.5] | [fact-check](skills/05-fact-check/README.md) | Verify factual claims against authoritative sources and rewrite the text with footnote citations, hedging anything that cannot be confirmed. | +| [5.1] | [brainstorm](skills/01-brainstorm/SKILL.md) | Clarify a vague request through a bounded loop of targeted questions over six clarity dimensions, converging until the request is precise or the user is satisfied. | +| [5.2] | [challenge](skills/02-challenge/SKILL.md) | Rethink prior work to verify correctness against an agreed plan, classifying findings with a confidence score. | +| [5.3] | [condense](skills/03-condense/SKILL.md) | Toggle terse output mode with intensity levels so prose drops fluff while code, errors, and warnings stay verbatim. | +| [5.4] | [shadow-areas](skills/04-shadow-areas/SKILL.md) | Analytical scan of a written artifact for blind spots: each gap is classified by category and severity, paired with a direct-question probe. | +| [5.5] | [fact-check](skills/05-fact-check/SKILL.md) | Verify factual claims against authoritative sources and rewrite the text with footnote citations, hedging anything that cannot be confirmed. | diff --git a/plugins/aidd-refine/skills/01-brainstorm/README.md b/plugins/aidd-refine/skills/01-brainstorm/README.md deleted file mode 100644 index 4ab29000..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/README.md +++ /dev/null @@ -1,32 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 01 - Brainstorm - -Turns a vague idea into a precise one through a deep, natural conversation, at whatever level the user is thinking, functional or technical. It asks pointed questions, follows the threads each answer opens, and challenges assumptions until the idea is clear enough to act on. It digs, it does not tick boxes. - -## When to use - -- The user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request. -- An idea would otherwise force the next step (plan, code, test) to rest on assumptions. -- The user asks to brainstorm, clarify, or refine before committing. - -## When not to use - -- To scan a written artifact for gaps. Use `aidd-refine:04-shadow-areas`. -- To critique finished work. Use `aidd-refine:02-challenge`. -- The idea is already concrete enough to plan or code. - -## The loop - -`capture` restates the idea and reads its altitude. Then `probe → integrate` repeats: each round asks pointed questions on the live thread, follows the forks the answers open, challenges assumptions, and folds the answers back in. It keeps going until no real ambiguity remains or the user is satisfied. There is no fixed round count, the idea is done when it is clear, not on a timer. `finalize` consolidates the refined idea, flags every open assumption and risk, and offers to persist it as `brainstorm.md` in the feature folder under `aidd_docs/tasks/`, a ticket, or the session only. - -## What makes it dig - -- **Follows threads, not topics.** It pulls on the fork an answer opens (filename versus full-text search, for instance), where the depth is, instead of cycling a fixed list. -- **Works at your altitude.** A technical question gets technical probing, a fuzzy feature gets product probing, never one level finer than you opened. -- **Leans when the facts point.** When the answers favor one option it says so with the tradeoff, and keeps the implementation as a flagged assumption for planning. -- **Flags, never fakes.** Whatever stays open is reported as an assumption or risk, never dressed up as settled. - -## Details - -See [`SKILL.md`](SKILL.md) for the contract, [`actions/`](actions/) for the four actions, [`references/probing.md`](references/probing.md) for how to read altitude, follow threads, the tactics, and when to stop, and [`assets/question-angles.md`](assets/question-angles.md) for the topical prompt banks. diff --git a/plugins/aidd-refine/skills/02-challenge/README.md b/plugins/aidd-refine/skills/02-challenge/README.md deleted file mode 100644 index c415880b..00000000 --- a/plugins/aidd-refine/skills/02-challenge/README.md +++ /dev/null @@ -1,57 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 02 - Challenge - -Rethinks just-completed work against an agreed plan, surfaces what is wrong, -missing, or duplicated, and classifies each finding as deal-breaker, -suggestion, or correct. Outputs a confidence score so the user knows whether -to ship, iterate, or rework. - -## When to use - -- The user says "challenge this", "rethink your plan", "is this correct", - "review my last decision", "challenge my decision", "challenge what you - did", "is my decision right", "criticize this", or "find flaws". -- A critical review of just-completed work is requested before shipping. -- A decision needs adversarial scrutiny before being committed to. - -## When NOT to use - -- Line-by-line code review against a style guide. -- Implementing features, writing tests, or generating new code. -- Reviewing a plan that has not yet been written. - -## How to invoke - -``` -Use skill aidd-refine:02-challenge -``` - -The skill is single-action - the router dispatches to `challenge` whenever -the trigger phrases above appear. - -1. `challenge` - rethink prior work, classify findings, score confidence - against the agreed plan. - -## Outputs - -- A structured verdict report with three classified buckets: - - **Deal-breakers** - issues that block shipping. - - **Suggestions** - improvements that are not blockers. - - **Correct** - explicit acknowledgement of what is already right. -- A confidence percentage based on the tiered rubric. -- No code edits. The report is informational; the user decides what to act on. - -## Prerequisites - -- A piece of recently completed work (plan, decision, implementation, diff) - to challenge. -- An agreed reference point (plan, spec, decision record) to challenge it - against. Without one, the skill challenges against stated user intent. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for -the single step, and -[`references/confidence-rubric.md`](references/confidence-rubric.md) for the -tiered rubric backing the confidence percentage. diff --git a/plugins/aidd-refine/skills/03-condense/README.md b/plugins/aidd-refine/skills/03-condense/README.md deleted file mode 100644 index af75df33..00000000 --- a/plugins/aidd-refine/skills/03-condense/README.md +++ /dev/null @@ -1,64 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 03 - Condense - -Toggles a terse output mode with three intensity levels (`lite`, `full`, -`ultra`). Strips articles, filler, and pleasantries from prose while leaving -code blocks, quoted errors, and security warnings verbatim. Also reports real -token usage and estimated savings for the current session. - -## When to use - -- The user says "condense", "condense output", "be more concise", "shorter - answers", "tighten output", "/condense", "/condense full", "/condense - ultra", "stop condense", or "normal mode". -- The user asks for token-savings stats: "/condense-stats", "how much have we - saved", "token savings". -- A long session would benefit from compressed prose without losing technical - substance. - -## When NOT to use - -- Editing existing prose written by the user - only the assistant's own - output style is affected. -- Summarizing a long document into a shorter version. -- Compressing source code, commit messages, or pull request bodies - those - stay in normal English regardless of intensity. - -## How to invoke - -``` -Use skill aidd-refine:03-condense -``` - -The router dispatches by intent: - -- Toggle phrase or intensity command (`condense`, `/condense full`, `stop - condense`, `normal mode`, ...) → `01-condense`. -- Stats query (`/condense-stats`, `how much have we saved`, `token - savings`, ...) → `02-stats`. - -## Outputs - -- A toggled response mode for the rest of the session. No files are written. -- Intensity persists across turns until the user explicitly turns it off - (`stop condense`, `normal mode`, `/condense off`) or toggles the skill - again. -- Stats action returns a formatted report of real token usage and estimated - savings under condense mode for the session. - -## Prerequisites - -- None for the toggle. The skill operates on the assistant's output style. -- Stats action expects a session transcript readable by the - `condense-stats.js` hook. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for -both steps, and -[`references/intensity-levels.md`](references/intensity-levels.md) for -per-level rules and side-by-side examples. The stats action is backed by the -`condense-stats.js` UserPromptSubmit hook, which intercepts stats triggers, -reads the session transcript, and returns the formatted savings report -without invoking the model. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/README.md b/plugins/aidd-refine/skills/04-shadow-areas/README.md deleted file mode 100644 index efb26a5d..00000000 --- a/plugins/aidd-refine/skills/04-shadow-areas/README.md +++ /dev/null @@ -1,69 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 04 - Shadow Areas - -Analytically scans a written artifact (idea, user stories, PRD, or spec) for -blind spots: unstated assumptions, missing actors, missing failure modes, -ambiguous terms, missing acceptance criteria, missing edge cases, and missing -dependencies. Each gap is classified by category and severity, paired with a -direct-question probe the author can act on, and written to a structured -`-shadow-report.md` next to the source. - -## When to use - -- The user asks to "find blind spots", "scan for gaps", "shadow report", or - "what's missing" in a written artifact. -- A PRD, spec, idea note, or user-story set needs an analytical pass before - planning or implementation starts. -- A prior shadow report exists and the user re-runs after editing the source, - wanting to see which gaps are closed, still open, or newly introduced. - -## When NOT to use - -- The artifact does not yet exist and the user needs to clarify a vague intent - through iterative questioning - use the `aidd-refine:01-brainstorm` skill. -- The request is to review code style or check implementation correctness. -- The user needs a general chat about what to do next, not a gap analysis. - -## How to invoke - -``` -Use skill aidd-refine:04-shadow-areas -``` - -Provide either a file path or inline text as the source: - -``` -Use skill aidd-refine:04-shadow-areas with -``` - -The router dispatches based on whether a prior report is already present: - -1. `detect` - parse the source, extract gaps, assign category and severity, - write a direct-question probe per gap. -2. `diff` (only when a prior report exists) - load the prior report and - classify each gap as closed, still open, or newly introduced. -3. `render-report` - write `-shadow-report.md` grouped by category - and sorted by severity (blockers first). - -## Outputs - -- A markdown report `-shadow-report.md` written next to the source. -- Each gap entry: `category`, `severity`, `probe`, optional quoted `snippet`. -- Report header carries `status: clean` when zero blockers and zero majors remain. -- On re-runs: three labeled sections (Closed, Still Open, Newly Introduced). - -## Prerequisites - -- A written artifact in markdown (or plain text) the skill can read. -- The file must be inside the working directory; outside-tree relative paths - are rejected. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and transversal rules. -Action implementations are under [`actions/`](actions/). -The locked taxonomy and severity rubric live in [`references/`](references/); -[`references/locked-sets.json`](references/locked-sets.json) is the single -source of truth reused by both docs and the validator. -The report skeleton is at [`assets/report-template.md`](assets/report-template.md). diff --git a/plugins/aidd-refine/skills/05-fact-check/README.md b/plugins/aidd-refine/skills/05-fact-check/README.md deleted file mode 100644 index 170d6a03..00000000 --- a/plugins/aidd-refine/skills/05-fact-check/README.md +++ /dev/null @@ -1,69 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 05 - Fact-check - -Verifies the factual claims inside a target text and rewrites it grounded in -evidence. Each verifiable claim is extracted, classified, and checked against a -cheapest-first cascade (project memory and docs, then codebase inspection, then -web lookup). The rewritten answer carries a footnote citation on every confirmed -claim, an explicit hedge on every unconfirmed claim, and both sources whenever -they disagree. - -## When to use - -- The user asks to "fact-check this", "verify that claim", "are you sure", "is - that actually true", "cite your sources", or "where did you get that fact". -- A prior answer states versions, API behavior, dates, or repository facts that - must be confirmed before being trusted. -- The user wants a clear separation between what is sourced and what is a guess. - -## When NOT to use - -- To auto-guard the AI's own output - this skill only fires on an explicit - request. A permanent "always verify" guard belongs in an always-loaded rule. -- To judge code logic correctness or review code style. -- To clarify vague requirements through iterative Q&A - use the - `aidd-refine:01-brainstorm` skill. - -## How to invoke - -``` -Use skill aidd-refine:05-fact-check -``` - -Provide the text to check - the prior answer, a quoted passage, or a pasted -block: - -``` -Use skill aidd-refine:05-fact-check on -``` - -The skill runs a fixed three-step pipeline: - -1. `identify-claims` - extract verifiable claims, classify each, drop opinion. -2. `verify` - run the cascade per claim, assign a verdict and record sources. -3. `report` - rewrite the text with footnote citations, hedge unverified - claims, and surface conflicts with both sources. - -## Outputs - -- The rewritten answer with a `[n]` marker on every verified claim. -- A `## Sources` footnote block - one numbered entry per source. -- A `## Unverified claims` section listing every claim the cascade could not - resolve (omitted when none). -- An optional cache suggestion for stable verified facts, opt-in only. - -## Prerequisites - -- A piece of text whose claims need checking. -- Project memory, docs, and codebase available for the cheap cascade tiers; a - web lookup tool for the last-resort tier. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and transversal rules. -Action implementations are under [`actions/`](actions/). -The claim taxonomy and the verification cascade live in -[`references/`](references/). -The rewritten-answer skeleton is at -[`assets/report-template.md`](assets/report-template.md). diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md index 633d25f1..73912f57 100644 --- a/plugins/aidd-ui/CATALOG.md +++ b/plugins/aidd-ui/CATALOG.md @@ -25,6 +25,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-greet.md](skills/01-hello/actions/01-greet.md) | - | -| `-` | [README.md](skills/01-hello/README.md) | - | | `-` | [SKILL.md](skills/01-hello/SKILL.md) | `Smoke-test that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Not for real UI or UX design work.` | diff --git a/plugins/aidd-ui/README.md b/plugins/aidd-ui/README.md index f54d34cd..868d24cb 100644 --- a/plugins/aidd-ui/README.md +++ b/plugins/aidd-ui/README.md @@ -25,4 +25,4 @@ One starter skill today; real UI and UX skills land as the concern stabilises. | Bracket ID | Skill | Description | | ---------- | ----- | ----------- | -| [7.1] | [hello](skills/01-hello/README.md) | Smoke-test skill that confirms the plugin loads. | +| [7.1] | [hello](skills/01-hello/SKILL.md) | Smoke-test skill that confirms the plugin loads. | diff --git a/plugins/aidd-ui/skills/01-hello/README.md b/plugins/aidd-ui/skills/01-hello/README.md deleted file mode 100644 index 11b4803c..00000000 --- a/plugins/aidd-ui/skills/01-hello/README.md +++ /dev/null @@ -1,29 +0,0 @@ -← [aidd-ui](../../README.md) - -# hello - -Smoke-test skill for the alpha `aidd-ui` plugin. It greets the caller and confirms the plugin loaded. - -## When to use - -- To verify the alpha `aidd-ui` plugin is installed and reachable after a local install or reload. - -## When NOT to use - -- For real UI or UX design, review, or improvement work. Those skills do not exist yet. - -## How to invoke - -`aidd-ui:01-hello` - -## Outputs - -- A short greeting printed in the chat. - -## Prerequisites - -- The plugin loaded locally (`claude --plugin-dir plugins/aidd-ui`, or installed from the marketplace). - -## Technical details - -See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-ui/skills/01-hello/SKILL.md b/plugins/aidd-ui/skills/01-hello/SKILL.md index 471d5b0c..e3406a95 100644 --- a/plugins/aidd-ui/skills/01-hello/SKILL.md +++ b/plugins/aidd-ui/skills/01-hello/SKILL.md @@ -15,3 +15,7 @@ Confirm the aidd-ui plugin loads and is reachable. Single action skill: run `greet` and return its message. Before running an action, read its file in `actions/`, not only the table or assets. + +## Prerequisites + +- The plugin loaded locally (`claude --plugin-dir plugins/aidd-ui`, or installed from the marketplace). diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 3a2333a6..fed85e29 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -31,7 +31,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-init.md](skills/00-repo-init/actions/01-init.md) | - | | `actions` | [02-publish.md](skills/00-repo-init/actions/02-publish.md) | - | | `assets` | [CONTRIBUTING.md](skills/00-repo-init/assets/CONTRIBUTING.md) | - | -| `-` | [README.md](skills/00-repo-init/README.md) | - | | `-` | [SKILL.md](skills/00-repo-init/SKILL.md) | `Initialize a project repository with git init, a default branch, a bootstrap commit, CONTRIBUTING.md, and optionally the remote. Use when the user wants to init or set up a new repo, or publish to a remote. Not for committing, opening a PR, or tagging.` | #### `skills/01-commit` @@ -42,7 +41,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-message.md](skills/01-commit/actions/02-message.md) | - | | `actions` | [03-commit.md](skills/01-commit/actions/03-commit.md) | - | | `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | -| `-` | [README.md](skills/01-commit/README.md) | - | | `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.` | #### `skills/02-pull-request` @@ -54,7 +52,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-create.md](skills/02-pull-request/actions/03-create.md) | - | | `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | -| `-` | [README.md](skills/02-pull-request/README.md) | - | | `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use when the user wants to open a pull or merge request. Not for committing, pushing, or merging a branch.` | #### `skills/03-release-tag` @@ -63,7 +60,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-release-tag.md](skills/03-release-tag/actions/01-release-tag.md) | - | | `assets` | [release-template.md](skills/03-release-tag/assets/release-template.md) | `VCS release notes template` | -| `-` | [README.md](skills/03-release-tag/README.md) | - | | `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with an annotated tag and release notes. Use when the user wants to release, tag a release, bump the version, or cut a version. Not for a plain commit, a pull request, or amending an existing tag.` | #### `skills/04-issue-create` @@ -73,6 +69,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-issue-create.md](skills/04-issue-create/actions/01-issue-create.md) | - | | `assets` | [CONTRIBUTING.md](skills/04-issue-create/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | | `assets` | [issue-template.md](skills/04-issue-create/assets/issue-template.md) | `VCS issue/ticket template` | -| `-` | [README.md](skills/04-issue-create/README.md) | - | | `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user wants to file a bug, open an issue, or report a problem. Not for committing, opening a pull request, or commenting on an existing issue.` | diff --git a/plugins/aidd-vcs/README.md b/plugins/aidd-vcs/README.md index 7f24ea67..fe89ad57 100644 --- a/plugins/aidd-vcs/README.md +++ b/plugins/aidd-vcs/README.md @@ -16,10 +16,10 @@ Covers all external artifact creation: commits, pull/merge requests, release tag | Bracket ID | Skill | Description | |---|---|---| -| [3.1] | [commit](skills/01-commit/README.md) | Create a git commit with proper conventional message format. | -| [3.2] | [pull-request](skills/02-pull-request/README.md) | Create PR (GitHub) or MR (GitLab) with filled template. | -| [3.3] | [release-tag](skills/03-release-tag/README.md) | Create and push a semantic version git tag with release notes. | -| [3.4] | [issue-create](skills/04-issue-create/README.md) | Create issues in the configured ticketing tool. | +| [3.1] | [commit](skills/01-commit/SKILL.md) | Create a git commit with proper conventional message format. | +| [3.2] | [pull-request](skills/02-pull-request/SKILL.md) | Create PR (GitHub) or MR (GitLab) with filled template. | +| [3.3] | [release-tag](skills/03-release-tag/SKILL.md) | Create and push a semantic version git tag with release notes. | +| [3.4] | [issue-create](skills/04-issue-create/SKILL.md) | Create issues in the configured ticketing tool. | ## Assets diff --git a/plugins/aidd-vcs/skills/00-repo-init/README.md b/plugins/aidd-vcs/skills/00-repo-init/README.md deleted file mode 100644 index 6c7ecd3b..00000000 --- a/plugins/aidd-vcs/skills/00-repo-init/README.md +++ /dev/null @@ -1,34 +0,0 @@ -← [aidd-vcs](../../README.md) - -# 00-repo-init - -Initializes a project's repository locally and, on request, on the remote host: `git init`, sets the default branch, resolves the provider, and can create the remote repository and push, returning its URL. - -> Status: experimental. - -## When to use - -- Starting version control on a new project (e.g. right after scaffolding it). -- Creating the remote repository and pushing the initial state. - -## When NOT to use - -- Cloning an existing remote, opening pull requests, or tagging releases. -- Re-initializing a directory that is already a repository (the local step no-ops there). - -## How to invoke - -`aidd-vcs:00-repo-init`, or say "initialize a git repository here" / "create the remote and publish". - -## Outputs - -- `init`: an initialized `.git`, the default branch set, the resolved provider, and `origin` added when a remote URL is given. -- `publish`: the created remote repository and a push, returning its URL. - -## Prerequisites - -- `git` on the PATH. For `publish`, the resolved host's tooling (CLI, MCP, or API) available and authenticated. - -## Technical details - -Two actions: `init` (local) and `publish` (remote, outward-facing, confirms first). See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md index afe0bd3c..3ec1c1e1 100644 --- a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md +++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md @@ -6,6 +6,8 @@ argument-hint: init | publish # Repo Init +> Status: experimental. + Initializes a project's repository locally and, on request, on the remote host, then returns the remote URL. ## Actions @@ -25,6 +27,10 @@ Before running an action, read its file in `actions/`, not only the table or ass - `publish` is outward-facing. It confirms before creating the remote unless `non_interactive` is set. - The provider is open. Resolve the host and how to reach it (CLI, MCP, or API) from the VCS memory when present, else from the VCS tooling available in the environment. Never restrict to a fixed list or a fixed mechanism. `main` is the default-branch fallback. +## Prerequisites + +- `git` on the PATH. For `publish`, the resolved host's tooling (CLI, MCP, or API) available and authenticated. + ## Assets - `assets/CONTRIBUTING.md`: the project-root `CONTRIBUTING.md` template. diff --git a/plugins/aidd-vcs/skills/01-commit/README.md b/plugins/aidd-vcs/skills/01-commit/README.md deleted file mode 100644 index 5f4a992f..00000000 --- a/plugins/aidd-vcs/skills/01-commit/README.md +++ /dev/null @@ -1,53 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 01 - Commit - -Creates an atomic git commit with a conventional, imperative-mood message, -optionally pushing the branch when the caller asks for it. - -## When to use - -- The user says "commit", "git commit", "create a commit", "commit my - changes", or "commit and push". -- The user invokes the `/commit` slash command. -- An agent has finished a contained change and needs it recorded as a single - atomic commit. - -## When NOT to use - -- To amend an existing commit (this skill always creates a new one). -- To force-push or rebase the current branch. -- To open a pull or merge request → use `02-pull-request`. -- To cut a release tag → use `03-release-tag`. - -## How to invoke - -``` -Use skill aidd-vcs:01-commit -``` - -Or via the slash command: - -- `/commit` - stage, commit, stay local (`push: false`). -- `/commit push` - stage, commit, then push the branch (`push: true`). - -The skill chains three actions, collect then message then commit, that run -end to end: stage one concern, write the conventional message, commit, and -optionally push. - -## Outputs - -- One new git commit on the current branch with a conventional message. -- Optionally, a pushed branch on the remote when `push: true`. - -## Prerequisites - -- A git repository with at least one staged or unstaged change. -- A configured git identity (`user.name`, `user.email`). -- A writable remote when `push: true`. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and -[`assets/commit-template.md`](assets/commit-template.md) for the conventional -commit format reference shipped with the skill. diff --git a/plugins/aidd-vcs/skills/02-pull-request/README.md b/plugins/aidd-vcs/skills/02-pull-request/README.md deleted file mode 100644 index 8482dc0d..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/README.md +++ /dev/null @@ -1,55 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 02 - Pull Request - -Drafts a pull request (GitHub) or merge request (GitLab) from the current -branch using the team's template, validates it with the user, and opens it -as a draft for manual promotion. - -## When to use - -- The user says "open a pr", "open a pull request", "create a pr", "create a - merge request", "open mr", or "draft a pr for this branch". -- The user invokes the `/pull-request` slash command. -- A feature branch is ready for review and needs a request opened against - the detected base branch. - -## When NOT to use - -- To commit changes → use `01-commit`. -- To push the working branch on its own (no request created). -- To tag a release → use `03-release-tag`. -- To merge an existing request, or to amend commits. - -## How to invoke - -``` -Use skill aidd-vcs:02-pull-request -``` - -Or via the slash command: `/pull-request`. - -The skill chains three actions, collect then draft then create: collect -resolves the base and gathers the commits, draft writes and validates the -title and body, create opens the request as a draft. - -## Outputs - -- A new draft pull request on GitHub, or a draft merge request on GitLab, - pointing from the current branch to the detected base branch, with the - filled template as its body. - -## Prerequisites - -- A git repository with a remote on GitHub or GitLab. -- The current branch is pushed (or the skill will defer to the user). -- `gh` (GitHub) or `glab` (GitLab) CLI authenticated, depending on the - detected VCS tool. -- The base branch resolves from project memory or remote inspection; the - skill does not assume `main` / `master`. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract. Templates ship in -[`assets/`](assets/): `pull_request.md` (request body) and `branch.md` (naming -conventions). diff --git a/plugins/aidd-vcs/skills/03-release-tag/README.md b/plugins/aidd-vcs/skills/03-release-tag/README.md deleted file mode 100644 index 7041cc93..00000000 --- a/plugins/aidd-vcs/skills/03-release-tag/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 03 - Release Tag - -Cuts a semver release: computes the next version, drafts notes from recent -commits, validates with the user, bumps version-manager files, creates an -annotated git tag, and pushes it. - -## When to use - -- The user says "release", "tag", "tag this release", "bump version", - "release v1.2.0", or "cut a release". -- The user invokes the `/release-tag` slash command. -- A release-ready commit exists on the release branch and needs a versioned - tag with notes. - -## When NOT to use - -- For plain commits without a tag → use `01-commit`. -- To open a pull or merge request → use `02-pull-request`. -- To push a branch only, with no tag created. -- To amend or move an existing tag (this skill never force-updates tags). - -## How to invoke - -``` -Use skill aidd-vcs:03-release-tag -``` - -Or via the slash command: `/release-tag`. - -The skill runs a single action (`release-tag`) that computes the version, -drafts notes, validates with the user, applies the version bump, creates the -annotated tag, and pushes it. - -## Outputs - -- A version-bump commit touching only version-manager files (e.g. - `package.json`, `pyproject.toml`). -- An annotated git tag (`git tag -a vX.Y.Z`) carrying the release notes. -- The bump commit and the tag pushed to the remote. - -## Prerequisites - -- A git repository with a writable remote. -- A version-manager file the skill can update (e.g. `package.json`, - `pyproject.toml`). -- A clean working tree, or changes the user is willing to bundle into the - bump commit when prompted. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract. The release notes -template ships at [`assets/release-template.md`](assets/release-template.md). diff --git a/plugins/aidd-vcs/skills/04-issue-create/README.md b/plugins/aidd-vcs/skills/04-issue-create/README.md deleted file mode 100644 index 1aee05e6..00000000 --- a/plugins/aidd-vcs/skills/04-issue-create/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 04 - Issue Create - -Files a well-formed issue in the configured ticketing tool after gathering -enough context to be actionable, validated with the user before creation. - -## When to use - -- The user says "new issue", "create an issue", "file a bug", "file an - issue", "report bug", or "open an issue". -- The user invokes the `/issue-create` slash command. -- A bug or feature request surfaces during work and needs a tracked record - in whichever ticketing tool the project uses. - -## When NOT to use - -- To commit changes → use `01-commit`. -- To open a pull or merge request → use `02-pull-request`. -- To cut a release tag → use `03-release-tag`. -- To comment on an existing issue (this skill only creates new ones). - -## How to invoke - -``` -Use skill aidd-vcs:04-issue-create -``` - -Or via the slash command: `/issue-create`. - -The skill runs a single action (`issue-create`) that detects the ticketing -tool, fills the issue template, validates title / body / labels / type / -projects / milestones with the user, then creates the issue. - -## Outputs - -- A new issue in the configured tracker (GitHub Issues, GitLab Issues, Jira, - Linear, or whichever tool project memory points at) with the filled - template body, requested labels, type, projects, and milestones. - -## Prerequisites - -- The project memory identifies the ticketing tool, or the remote URL - reveals it via `git remote get-url origin`. -- The matching CLI is authenticated (`gh`, `glab`, etc.) or the tool's API - credentials are configured. -- The user is available to approve the draft before the issue is filed; - the skill always waits for explicit confirmation. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract. Templates ship in -[`assets/`](assets/): `issue-template.md` (issue body) and `CONTRIBUTING.md` -(project-specific issue rules consulted before drafting). From b0142368460cd5b329738db2d4264a3d3f0a5e84 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:33:58 +0200 Subject: [PATCH 04/20] ci(deps): bump github/codeql-action/init from 4.36.2 to 4.36.3 (#398) Bumps [github/codeql-action/init](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/8aad20d150bbac5944a9f9d289da16a4b0d87c1e...54f647b7e1bb85c95cddabcd46b0c578ec92bc1a) --- updated-dependencies: - dependency-name: github/codeql-action/init dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 68b81d32..feeacc8e 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -31,7 +31,7 @@ jobs: uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Initialize CodeQL - uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2 + uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3 with: languages: ${{ matrix.language }} queries: security-and-quality From 3a1d1bf4504de8cf543465405c2103f8e275ecfa Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:34:14 +0200 Subject: [PATCH 05/20] chore(deps-dev): bump js-yaml from 5.0.0 to 5.2.1 (#401) Bumps [js-yaml](https://github.com/nodeca/js-yaml) from 5.0.0 to 5.2.1. - [Changelog](https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md) - [Commits](https://github.com/nodeca/js-yaml/compare/5.0.0...5.2.1) --- updated-dependencies: - dependency-name: js-yaml dependency-version: 5.2.1 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- package.json | 2 +- pnpm-lock.yaml | 19 ++++++++++--------- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/package.json b/package.json index 3a00677e..60c79744 100644 --- a/package.json +++ b/package.json @@ -35,7 +35,7 @@ "@commitlint/config-conventional": "^21.0.2", "ajv": "8.20.0", "ajv-formats": "3.0.1", - "js-yaml": "5.0.0", + "js-yaml": "5.2.1", "lefthook": "^2.1.9" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d2616131..3089de09 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -21,8 +21,8 @@ importers: specifier: 3.0.1 version: 3.0.1(ajv@8.20.0) js-yaml: - specifier: 5.0.0 - version: 5.0.0 + specifier: 5.2.1 + version: 5.2.1 lefthook: specifier: ^2.1.9 version: 2.1.9 @@ -233,6 +233,7 @@ packages: git-raw-commits@5.0.1: resolution: {integrity: sha512-Y+csSm2GD/PCSh6Isd/WiMjNAydu0VBiG9J7EdQsNA5P9uXvLayqjmTsNlK5Gs9IhblFZqOU0yid5Il5JPoLiQ==} engines: {node: '>=18'} + deprecated: Deprecated and no longer maintained. Use @conventional-changelog/git-client instead. hasBin: true global-directory@5.0.0: @@ -265,12 +266,12 @@ packages: js-tokens@4.0.0: resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} - js-yaml@4.2.0: - resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==} + js-yaml@4.3.0: + resolution: {integrity: sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==} hasBin: true - js-yaml@5.0.0: - resolution: {integrity: sha512-GSvaPUbk1U+FMZ7rJzF+F8e5YVtu7KnD40et/5rBXXRBv2jCO9L3qCewvIDDdudC0QycTFlf6EAA+h3kxBsuUw==} + js-yaml@5.2.1: + resolution: {integrity: sha512-zfLtNfQqxVqq3uaTqSkh4x4hZw3KHobGUA0fJUj4wawW8bsQLTVqpHdXSIzidh7o+4lEW36tANuAGdaFx6Zgnw==} hasBin: true json-parse-even-better-errors@2.3.1: @@ -596,7 +597,7 @@ snapshots: dependencies: env-paths: 2.2.1 import-fresh: 3.3.1 - js-yaml: 4.2.0 + js-yaml: 4.3.0 parse-json: 5.2.0 optionalDependencies: typescript: 5.9.3 @@ -654,11 +655,11 @@ snapshots: js-tokens@4.0.0: {} - js-yaml@4.2.0: + js-yaml@4.3.0: dependencies: argparse: 2.0.1 - js-yaml@5.0.0: + js-yaml@5.2.1: dependencies: argparse: 2.0.1 From ecede5e426f31696ef0b5777496309958a8b0c0f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:35:32 +0200 Subject: [PATCH 06/20] ci(deps): bump github/codeql-action/autobuild from 4.36.2 to 4.36.3 (#399) Bumps [github/codeql-action/autobuild](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/8aad20d150bbac5944a9f9d289da16a4b0d87c1e...54f647b7e1bb85c95cddabcd46b0c578ec92bc1a) --- updated-dependencies: - dependency-name: github/codeql-action/autobuild dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index feeacc8e..473462d3 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -37,7 +37,7 @@ jobs: queries: security-and-quality - name: Autobuild - uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2 + uses: github/codeql-action/autobuild@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3 - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2 From aef39acd829db9613669769f32c4b6b765b1a16c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:35:35 +0200 Subject: [PATCH 07/20] ci(deps): bump github/codeql-action/analyze from 4.36.2 to 4.36.3 (#400) Bumps [github/codeql-action/analyze](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/8aad20d150bbac5944a9f9d289da16a4b0d87c1e...54f647b7e1bb85c95cddabcd46b0c578ec92bc1a) --- updated-dependencies: - dependency-name: github/codeql-action/analyze dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 473462d3..6ce318e1 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -40,6 +40,6 @@ jobs: uses: github/codeql-action/autobuild@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3 - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2 + uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3 with: category: "/language:${{ matrix.language }}" From a40c288b2b582ac29636e5b6be7c094f3b0da97a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:46:53 +0200 Subject: [PATCH 08/20] feat(hooks): base new worktrees on next (#402) Add a WorktreeCreate hook so every worktree Claude Code creates branches from `next` (falling back to `main` when `next` is absent) instead of the repo default. Registered in .claude/settings.json. Co-authored-by: Claude Opus 4.8 --- .claude/hooks/worktree-create.js | 50 ++++++++++++++++++++++++++++++++ .claude/settings.json | 12 ++++++++ 2 files changed, 62 insertions(+) create mode 100644 .claude/hooks/worktree-create.js diff --git a/.claude/hooks/worktree-create.js b/.claude/hooks/worktree-create.js new file mode 100644 index 00000000..5920cc77 --- /dev/null +++ b/.claude/hooks/worktree-create.js @@ -0,0 +1,50 @@ +#!/usr/bin/env node +// WorktreeCreate hook — base every new worktree on `next`, falling back to +// `main` when the `next` branch does not exist. +// +// Docs: https://code.claude.com/docs/en/hooks#worktreecreate +// stdin : JSON { name } — the worktree name +// stdout: the created worktree path, and nothing else +// This replaces Claude's default `git worktree add`. + +const { execFileSync } = require("node:child_process"); +const { readFileSync } = require("node:fs"); +const { join } = require("node:path"); + +// Run a git command and return its trimmed stdout. git's own progress text is +// forwarded to our stderr so this process's stdout stays reserved for the path. +function git(...args) { + return execFileSync("git", args, { + encoding: "utf8", + stdio: ["ignore", "pipe", "inherit"], + }).trim(); +} + +function branchExists(branch) { + try { + git("rev-parse", "--verify", "--quiet", `refs/heads/${branch}`); + return true; + } catch { + return false; + } +} + +function readWorktreeName() { + const payload = JSON.parse(readFileSync(0, "utf8")); + return payload.name; +} + +function createWorktree() { + const worktreeName = readWorktreeName(); + const baseBranch = branchExists("next") ? "next" : "main"; + + const repoRoot = git("rev-parse", "--show-toplevel"); + const worktreePath = join(repoRoot, ".claude", "worktrees", worktreeName); + const newBranch = `worktree-${worktreeName}`; + + git("worktree", "add", worktreePath, "-b", newBranch, baseBranch); + + process.stdout.write(worktreePath + "\n"); +} + +createWorktree(); diff --git a/.claude/settings.json b/.claude/settings.json index 07193ab1..04bbef92 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -12,5 +12,17 @@ "aidd-pm@aidd-framework": true, "aidd-orchestrator@aidd-framework": true, "aidd-refine@aidd-framework": true + }, + "hooks": { + "WorktreeCreate": [ + { + "hooks": [ + { + "type": "command", + "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-create.js\"" + } + ] + } + ] } } From 5b3fe8a0bdc76574a2b0b5742494117c03b80970 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:47:18 +0200 Subject: [PATCH 09/20] ci(dependabot): approve non-major updates to unblock auto-merge (#403) The next-branch ruleset requires 1 approving review. Dependabot PRs never get one, so auto-merge stayed BLOCKED indefinitely. Approve non-major (patch + minor) updates with the app token before enabling auto-merge; the app identity differs from the PR author, so the approval satisfies the rule. Co-authored-by: Claude Opus 4.8 --- .github/workflows/dependabot-auto-merge.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml index 526fe15f..02dde859 100644 --- a/.github/workflows/dependabot-auto-merge.yml +++ b/.github/workflows/dependabot-auto-merge.yml @@ -25,6 +25,15 @@ jobs: id: meta uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0 + - name: Approve non-major updates + # Required-review rulesets (e.g. on `next`) block auto-merge until a + # review approves. Dependabot never gets one, so the app approves here. + # The app identity differs from the PR author, so the approval counts. + if: steps.meta.outputs.update-type != 'version-update:semver-major' + run: gh pr review --approve "${{ github.event.pull_request.html_url }}" + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + - name: Enable auto-merge for non-major updates if: steps.meta.outputs.update-type != 'version-update:semver-major' run: gh pr merge --auto --squash "${{ github.event.pull_request.html_url }}" From 84cbb08e2185debcf15fa43252f23b05bd6cc9c3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 06:48:12 +0200 Subject: [PATCH 10/20] chore(deps-dev): bump @commitlint/cli from 21.0.2 to 21.2.0 (#361) * 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 * ci(framework): drop the aidd-ui release-as pin, keep it consistent (#395) 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. Claude-Session: https://claude.ai/code/session_01WKWd6AVpdYSCmRZWQWAnRt Co-authored-by: Claude Opus 4.8 * refactor: remove per-skill README.md mirrors (#302) (#396) * refactor: remove per-skill README.md mirrors, retarget to SKILL.md Delete the 39 per-skill README.md files that mirrored their SKILL.md, merge the genuinely-unique content from the 7 outlier READMEs into SKILL.md (memory-bank-optional note, install prerequisite, experimental status), retarget plugin-level README skill tables and CREATE_PLUGIN.md to SKILL.md, and regenerate every plugin CATALOG.md. Phase 1 of aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme. Co-Authored-By: Claude Opus 4.8 * chore: mark phase 2 done for remove-per-skill-readme plan All verify-and-guard gates pass: check-markdown-links.js exits 0, zero plugins/*/skills/*/README.md remain, every affected skill dir still has SKILL.md, both asset READMEs and all plugin-level/framework READMEs are intact, sync-readme-counts.mjs --check exits 0, no CATALOG lists a per-skill README row, and 04-skill-generate scaffolds no per-skill README. Co-Authored-By: Claude Opus 4.8 * chore: mark remove-per-skill-readme plan implemented Both phases done and validation green (check-markdown-links.js and sync-readme-counts.mjs --check both exit 0). Co-Authored-By: Claude Opus 4.8 * chore: mark remove-per-skill-readme plan reviewed --------- Co-authored-by: Claude Opus 4.8 * ci(deps): bump github/codeql-action/init from 4.36.2 to 4.36.3 (#398) Bumps [github/codeql-action/init](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/8aad20d150bbac5944a9f9d289da16a4b0d87c1e...54f647b7e1bb85c95cddabcd46b0c578ec92bc1a) --- updated-dependencies: - dependency-name: github/codeql-action/init dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(deps-dev): bump js-yaml from 5.0.0 to 5.2.1 (#401) Bumps [js-yaml](https://github.com/nodeca/js-yaml) from 5.0.0 to 5.2.1. - [Changelog](https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md) - [Commits](https://github.com/nodeca/js-yaml/compare/5.0.0...5.2.1) --- updated-dependencies: - dependency-name: js-yaml dependency-version: 5.2.1 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * ci(deps): bump github/codeql-action/autobuild from 4.36.2 to 4.36.3 (#399) Bumps [github/codeql-action/autobuild](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/8aad20d150bbac5944a9f9d289da16a4b0d87c1e...54f647b7e1bb85c95cddabcd46b0c578ec92bc1a) --- updated-dependencies: - dependency-name: github/codeql-action/autobuild dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * ci(deps): bump github/codeql-action/analyze from 4.36.2 to 4.36.3 (#400) Bumps [github/codeql-action/analyze](https://github.com/github/codeql-action) from 4.36.2 to 4.36.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/8aad20d150bbac5944a9f9d289da16a4b0d87c1e...54f647b7e1bb85c95cddabcd46b0c578ec92bc1a) --- updated-dependencies: - dependency-name: github/codeql-action/analyze dependency-version: 4.36.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore(deps-dev): bump @commitlint/cli from 21.0.2 to 21.2.0 Bumps [@commitlint/cli](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/cli) from 21.0.2 to 21.2.0. - [Release notes](https://github.com/conventional-changelog/commitlint/releases) - [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/cli/CHANGELOG.md) - [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.0/@commitlint/cli) --- updated-dependencies: - dependency-name: "@commitlint/cli" dependency-version: 21.2.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --------- Signed-off-by: dependabot[bot] Co-authored-by: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- package.json | 2 +- pnpm-lock.yaml | 235 ++++++++++++++++++++++++++++++------------------- 2 files changed, 146 insertions(+), 91 deletions(-) diff --git a/package.json b/package.json index 60c79744..5e7fdbd0 100644 --- a/package.json +++ b/package.json @@ -31,7 +31,7 @@ "prepare": "lefthook install || true" }, "devDependencies": { - "@commitlint/cli": "^21.0.2", + "@commitlint/cli": "^21.2.0", "@commitlint/config-conventional": "^21.0.2", "ajv": "8.20.0", "ajv-formats": "3.0.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3089de09..4bc5ab2e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -9,8 +9,8 @@ importers: .: devDependencies: '@commitlint/cli': - specifier: ^21.0.2 - version: 21.0.2(@types/node@25.3.5)(conventional-commits-parser@6.4.0)(typescript@5.9.3) + specifier: ^21.2.0 + version: 21.2.0(@types/node@25.3.5)(conventional-commits-parser@6.4.0)(typescript@5.9.3) '@commitlint/config-conventional': specifier: ^21.0.2 version: 21.0.2 @@ -37,8 +37,8 @@ packages: resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==} engines: {node: '>=6.9.0'} - '@commitlint/cli@21.0.2': - resolution: {integrity: sha512-YMmfLbqBg+ZRvvmPhc+cilSQFrh/AgzVgCT1U/OifmUZEwPbvCtA8rN//YNaF9d5eoZphxVMGYtmwA2QgQORgg==} + '@commitlint/cli@21.2.0': + resolution: {integrity: sha512-4GLVIhUaT3c3GBlQ0GB80/5H3xXdn/Tgw4lrsuoOQVDu2wl4Xw0GuzSar8xZKSMv4H3xaKaQXmvH91GmdyYBZA==} engines: {node: '>=22.12.0'} hasBin: true @@ -46,66 +46,74 @@ packages: resolution: {integrity: sha512-P/ZRhryQmkj0Z0dY9FOoRwe3xkwJyyAdtXwt01NT2kuZttcG2CNYp1q5Ci3u+nDT2jcbJRw2kt13Czl1qKNPfg==} engines: {node: '>=22.12.0'} - '@commitlint/config-validator@21.0.1': - resolution: {integrity: sha512-Zd2UFdndeMMaW2O96HK0tdfT4gOImUvidMpAd/pws2zZ4m1nrAZ/9b/v2JYuE8fs86GpXv9F7LNaIuCIWhY+pA==} + '@commitlint/config-conventional@21.2.0': + resolution: {integrity: sha512-Qf8WRDVcyVd14if6VTWenebxFbKnVnbzPUJjlzjkyJGeHK2xCGd63Dr1XZzj0plXKQb9P0BfOxoc1HVeCo2BWQ==} + engines: {node: '>=22.12.0'} + + '@commitlint/config-validator@21.2.0': + resolution: {integrity: sha512-t7AzNHAKeIdo/3NRGwzpufKHsKkPHmFs/56N2Fnsh0/r0rGtnQzTxk6vnFgjaGr4hdSQKNB50/KAhR9Yk4LJKA==} engines: {node: '>=22.12.0'} - '@commitlint/ensure@21.0.1': - resolution: {integrity: sha512-jJ1037967wU7YN/xkv+iRlOBlmaOXPhPO5KQSqya6GyXzBlwuLzELBFao16DVg9dZyqmNrhewzwZ3SAibetHBQ==} + '@commitlint/ensure@21.2.0': + resolution: {integrity: sha512-76IF9vDNS13lAzEEik9eKwzt8f9hYhWiwVXZ2AnyLCz5/f511FsEQ3pw1X3/zSQpdRLQU7i5qDMVKyXi1GWjSg==} engines: {node: '>=22.12.0'} '@commitlint/execute-rule@21.0.1': resolution: {integrity: sha512-RifH+FmImozKBE6mozhF4K3r2RRKP7SMi/Q/zLCmExtp5e05lhHOUYqGBlFBAGNHaZxU/WYw1XuugYK9jQzqnA==} engines: {node: '>=22.12.0'} - '@commitlint/format@21.0.1': - resolution: {integrity: sha512-ksmG2+cHGtuDPQQbhBbC4unwm444+6TiPw0d1bKf67hntgZqZ8E0g1MuYKUuyT5IH4IMmXZhKq22/Z3jBvtQIw==} + '@commitlint/format@21.2.0': + resolution: {integrity: sha512-c4q64xaav2U83t7k7RyzJerBZurPer7FxUOY0RL5L/6CZijZ7K+s6HIBGIghj0ey1P2+seRX0J9XQYtDued6tg==} engines: {node: '>=22.12.0'} - '@commitlint/is-ignored@21.0.2': - resolution: {integrity: sha512-H5z4t8PC9tUsmZ/o+EptM3Nq8sTFtskAShdcqxCoyzklW5eaVT5xbrDAET2uypzir9Vsj4ZZmBtyKjYe2XqgeQ==} + '@commitlint/is-ignored@21.2.0': + resolution: {integrity: sha512-4/eB0vBN7L88O/oC4ajAEqi7j2ZfNgxl/+11RfAV9YosejZgDXhY2C9VcHnHJhOzPLoSy5P3Mg/46kqeyJfXKw==} engines: {node: '>=22.12.0'} - '@commitlint/lint@21.0.2': - resolution: {integrity: sha512-PnUmLYGeGLfW8oVatR9KpNxSHYAnJOEWlMZzfdeFOUq6WUrFx1fGQaWCWJqMoIll/xPM+GdfJV+tKHZVHhl0Fg==} + '@commitlint/lint@21.2.0': + resolution: {integrity: sha512-ceO5dp9pLjEZ6y6qbq/uXWXDPykqqlTsyzoQ0NzecpisSJhK3kTy9qzQoPeJuWG/IMNdV1lO0RgmzqoAlSi1uw==} engines: {node: '>=22.12.0'} - '@commitlint/load@21.0.2': - resolution: {integrity: sha512-lwUE70hN0/qE/ZRROhbaX65ly/FF12DrqfReLCESo37M0OQCFAf2jRS+2tSCSORq+bm4Kdju7qNDj46uc1QzTA==} + '@commitlint/load@21.2.0': + resolution: {integrity: sha512-RjlzWQqruRwIenJEfZtq7kG97co97nKoHpflE5YnF61tDLXxHPrdWImgzw6VL6MlFyaOcVlk74eBV8ZQmc3oIA==} engines: {node: '>=22.12.0'} - '@commitlint/message@21.0.2': - resolution: {integrity: sha512-5n4aqHGD/FNnom/D5L8i7cYtV+xjuXcBL832C3w9VglEsZzIsoHpJsvxzJ7cgiOsOdc/2jU4t5+7qMHh7GBX3g==} + '@commitlint/message@21.2.0': + resolution: {integrity: sha512-YxGoiXD/HXNXLJPrQwE5poXa+XH0CBEm+mdvbHQP0g6MV/dmJyUFCzPNzZbxL93GvZ70TmtTK0Z0/IBpAqHv8g==} engines: {node: '>=22.12.0'} - '@commitlint/parse@21.0.2': - resolution: {integrity: sha512-QVZJhGHTm+oiuWyEKOCTQ0ZM3mfJ0eGWFeHuj7WzSKEth+UukcCHac9GD8pgdFlg/qGkFWOtyaNd1T8REgagaw==} + '@commitlint/parse@21.2.0': + resolution: {integrity: sha512-QHWxG4d0PLTF634/AdyZ0MQS+CLn5YOuJlCFhMMlSGKFxzYGUetkHBj18xgBD+6fVzUrA2lrCdi/vlS2f/oYXg==} engines: {node: '>=22.12.0'} - '@commitlint/read@21.0.2': - resolution: {integrity: sha512-BtsrnLVycSSKf4Q0gMch4giCj5NNlmcbhc8ra5vONgGtP2IjRDo33bEFtr5Pm+2N+5fXGWb2MksWPrspPfdhdw==} + '@commitlint/read@21.2.0': + resolution: {integrity: sha512-ELx8Ovh/JoAw5lpvDgxc6Y0We9skf2IPI2RFN+gnYgDGjRdMSF8zeodxhZmcclLWzfUIF7hXLOa8gOlllYcvBA==} engines: {node: '>=22.12.0'} - '@commitlint/resolve-extends@21.0.1': - resolution: {integrity: sha512-0DhjYWL6uYrY16Efa032fYk3woGJDU4AGWiG1XXltT9AMUNYKyb5cIZU2ivbaMZ3+kKFqUjikD2cjh66Sbh/Sg==} + '@commitlint/resolve-extends@21.2.0': + resolution: {integrity: sha512-4O/1j51+79Wth9s/MGxt/5gs0XYLDgNlYpltQfhAvLE0itusLKs9zruxbiNg1oOkmkb9L9L4USYGjEj7n87NxA==} engines: {node: '>=22.12.0'} - '@commitlint/rules@21.0.2': - resolution: {integrity: sha512-k6tQ69Td7t2qUSIbik8D3TL1q3ZJpkEbV+yLogDzCRAdOxJm4ndhtBNREsLA1/puRfWvzS9eioF2w43WT+hHgQ==} + '@commitlint/rules@21.2.0': + resolution: {integrity: sha512-C2yXMNpiB8ETZKfx5JD8+ExgF8vTU1VQMKPSUUYwqKpw9oJWQBrlXBpdU038mj2WPjof7o9UzFpmTyBeGMZwZg==} engines: {node: '>=22.12.0'} '@commitlint/to-lines@21.0.1': resolution: {integrity: sha512-bd1BFII7p1EQZre9Kaj+kKaMFP3cFCdt21K7DItVux9XP5WjLgJ0/Uy1pJJh9aPwVJ6SKg62PxqlZaHI8hQAXw==} engines: {node: '>=22.12.0'} - '@commitlint/top-level@21.0.2': - resolution: {integrity: sha512-s9KKM+e+mXgFeIh4n7KmOGAVT3mkJ3Fp1bBYHIK5pjeUwlEMzp/tZfb5u0Poa680AsQTXMEMRxZi1vQ9m2X5ug==} + '@commitlint/top-level@21.2.0': + resolution: {integrity: sha512-Y5gmQ+KxzqCrBFJfLvFEPvvwD3LDiNZoTT2yeFBm96M8qhmqSzQc5DvX3rheAaAMjyIvMXOCLS/mWfdpONsjyQ==} engines: {node: '>=22.12.0'} '@commitlint/types@21.0.1': resolution: {integrity: sha512-4u7w8jcoCUFWhjWnASYzZHAP34OqOtuFBN87nQmFvqda03YU0T6z+yB4w0gSAMpekiRqqGk5rt+qSlW+a2vSEg==} engines: {node: '>=22.12.0'} + '@commitlint/types@21.2.0': + resolution: {integrity: sha512-7zVFCDB2reMvJH5dmbKnOQPjZEvjdJTH8jc0U/PIPU1r3/+vf5pD1HlfitV2MWsWXrvu7u39iY1lyLUPOaN0Gw==} + engines: {node: '>=22.12.0'} + '@conventional-changelog/git-client@2.7.0': resolution: {integrity: sha512-j7A8/LBEQ+3rugMzPXoKYzyUPpw/0CBQCyvtTR7Lmu4olG4yRC/Tfkq79Mr3yuPs0SUitlO2HwGP3gitMJnRFw==} engines: {node: '>=18'} @@ -118,6 +126,10 @@ packages: conventional-commits-parser: optional: true + '@conventional-changelog/template@1.2.1': + resolution: {integrity: sha512-TzlTVpKPjaqW6qOYjQcYUDuGsLCNsvFHVBXkYGTAnf5V37jCWrE5haKNXzz0WZUtVHjrpV76L1buANjwXMfT8w==} + engines: {node: '>=22'} + '@simple-libs/child-process-utils@1.0.2': resolution: {integrity: sha512-/4R8QKnd/8agJynkNdJmNw2MBxuFTRcNFnE5Sg/G+jkSsV8/UBgULMzhizWWW42p8L5H7flImV2ATi79Ove2Tw==} engines: {node: '>=18'} @@ -126,6 +138,10 @@ packages: resolution: {integrity: sha512-KxXvfapcixpz6rVEB6HPjOUZT22yN6v0vI0urQSk1L8MlEWPDFCZkhw2xmkyoTGYeFw7tWTZd7e3lVzRZRN/EA==} engines: {node: '>=18'} + '@simple-libs/stream-utils@2.0.0': + resolution: {integrity: sha512-fCTuZK4QBa+39Oz9l4OGfJfz+GpwCp3AqO7Zch3to99xHPgstVsRFpeQ8LNd2o1Gv8raL2mCFwiaHh7bFSp5DQ==} + engines: {node: '>=22'} + '@types/node@25.3.5': resolution: {integrity: sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA==} @@ -165,9 +181,13 @@ packages: compare-func@2.0.0: resolution: {integrity: sha512-zHig5N+tPWARooBnb0Zx1MFcdfpyJrfTJ3Y5L+IFvUm8rM74hHz66z0gw0x4tijh5CorKkKUCnW82R2vmpeCRA==} - conventional-changelog-angular@8.3.1: - resolution: {integrity: sha512-6gfI3otXK5Ph5DfCOI1dblr+kN3FAm5a97hYoQkqNZxOaYa5WKfXH+AnpsmS+iUH2mgVC2Cg2Qw9m5OKcmNrIg==} - engines: {node: '>=18'} + conventional-changelog-angular@9.2.1: + resolution: {integrity: sha512-oWSL6ZhnXbYraOFTK3PgRAQJ8fADDAEv5K6AdeyQPLvjFmhG8+ejL0jZZp/R7vTmGJaBvZEE+sE7dB4bCv7sAw==} + engines: {node: '>=22'} + + conventional-changelog-conventionalcommits@10.2.1: + resolution: {integrity: sha512-n4Kr1HFMTf3iMbES0TMxKIcYtUUv4rKqyQQp2JwfOEfFCOfGT3Tq4mCyJ8S9/YPyWhydjfKrrvnyl+gCjA+mJQ==} + engines: {node: '>=22'} conventional-changelog-conventionalcommits@9.3.1: resolution: {integrity: sha512-dTYtpIacRpcZgrvBYvBfArMmK2xvIpv2TaxM0/ZI5CBtNUzvF2x0t15HsbRABWprS6UPmvj+PzHVjSx4qAVKyw==} @@ -178,6 +198,11 @@ packages: engines: {node: '>=18'} hasBin: true + conventional-commits-parser@7.0.1: + resolution: {integrity: sha512-6VtskFpPsNkGVk/TY2RnV/MEdKfvCPBtQZN9x8jh9+k5RWBQ+tiaWn5UFCzTr0Dd88iKx7xghxbjBRp5uIzp3g==} + engines: {node: '>=22'} + hasBin: true + cosmiconfig-typescript-loader@6.3.0: resolution: {integrity: sha512-Akr82WH1Wfqatyiqpj8HDkO2o2KmJRu1FhKfSNJP3K4IdXwHfEyL7MOb62i1AGQVLtIQM+iCE9CGOtrfhR+mmA==} engines: {node: '>=v18'} @@ -186,8 +211,8 @@ packages: cosmiconfig: '>=9' typescript: '>=5' - cosmiconfig@9.0.1: - resolution: {integrity: sha512-hr4ihw+DBqcvrsEDioRO31Z17x71pUYoNe/4h6Z0wB72p7MU7/9gH8Q3s12NFhHPfYBBOV3qyfUxmr/Yn3shnQ==} + cosmiconfig@9.0.2: + resolution: {integrity: sha512-gtTZxTDau1wL7Y7zifc2dd8jHSK/k6BTx/2Xp/BpdlAdnlYWFVt7qhJqgwi7637yRwRQ3qL4ZidbB4I8tA5VOg==} engines: {node: '>=14'} peerDependencies: typescript: '>=4.9.5' @@ -209,8 +234,8 @@ packages: error-ex@1.3.4: resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==} - es-toolkit@1.47.0: - resolution: {integrity: sha512-n1GuoD0WEQZMBk5tttoZSqwgyLx01oqa5XsBmCHwPyNe1S9jPBEmtR2pSgp2kJuWE3ciFZ6yRHmY4pM4C3OOkw==} + es-toolkit@1.49.0: + resolution: {integrity: sha512-G5iZ6Pc/FNRY/soKZHC+TxGDD83rHUDXxzaWhGCX44vAv/tMs56WMusnm/KMNK+luUPsgA9U28cGr4RDlSzL2g==} escalade@3.2.0: resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} @@ -341,6 +366,10 @@ packages: resolution: {integrity: sha512-pxQJQzB6djGPXh08dacEloMFopsOqGVRKFPYvPOt9XDZ1HasbgDZA74CJGreSU4G3Ak7EFJGoiH2auq+yXISgA==} engines: {node: '>=18'} + meow@14.1.0: + resolution: {integrity: sha512-EDYo6VlmtnumlcBCbh1gLJ//9jvM/ndXHfVXIFrZVr6fGcwTUyCTFNTLCKuY3ffbK8L/+3Mzqnd58RojiZqHVw==} + engines: {node: '>=20'} + parent-module@1.0.1: resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==} engines: {node: '>=6'} @@ -364,8 +393,8 @@ packages: resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==} engines: {node: '>=8'} - semver@7.8.1: - resolution: {integrity: sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==} + semver@7.8.5: + resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==} engines: {node: '>=10'} hasBin: true @@ -415,13 +444,14 @@ snapshots: '@babel/helper-validator-identifier@7.29.7': {} - '@commitlint/cli@21.0.2(@types/node@25.3.5)(conventional-commits-parser@6.4.0)(typescript@5.9.3)': + '@commitlint/cli@21.2.0(@types/node@25.3.5)(conventional-commits-parser@6.4.0)(typescript@5.9.3)': dependencies: - '@commitlint/format': 21.0.1 - '@commitlint/lint': 21.0.2 - '@commitlint/load': 21.0.2(@types/node@25.3.5)(typescript@5.9.3) - '@commitlint/read': 21.0.2(conventional-commits-parser@6.4.0) - '@commitlint/types': 21.0.1 + '@commitlint/config-conventional': 21.2.0 + '@commitlint/format': 21.2.0 + '@commitlint/lint': 21.2.0 + '@commitlint/load': 21.2.0(@types/node@25.3.5)(typescript@5.9.3) + '@commitlint/read': 21.2.0(conventional-commits-parser@6.4.0) + '@commitlint/types': 21.2.0 tinyexec: 1.2.4 yargs: 18.0.0 transitivePeerDependencies: @@ -435,86 +465,91 @@ snapshots: '@commitlint/types': 21.0.1 conventional-changelog-conventionalcommits: 9.3.1 - '@commitlint/config-validator@21.0.1': + '@commitlint/config-conventional@21.2.0': dependencies: - '@commitlint/types': 21.0.1 + '@commitlint/types': 21.2.0 + conventional-changelog-conventionalcommits: 10.2.1 + + '@commitlint/config-validator@21.2.0': + dependencies: + '@commitlint/types': 21.2.0 ajv: 8.20.0 - '@commitlint/ensure@21.0.1': + '@commitlint/ensure@21.2.0': dependencies: - '@commitlint/types': 21.0.1 - es-toolkit: 1.47.0 + '@commitlint/types': 21.2.0 + es-toolkit: 1.49.0 '@commitlint/execute-rule@21.0.1': {} - '@commitlint/format@21.0.1': + '@commitlint/format@21.2.0': dependencies: - '@commitlint/types': 21.0.1 + '@commitlint/types': 21.2.0 picocolors: 1.1.1 - '@commitlint/is-ignored@21.0.2': + '@commitlint/is-ignored@21.2.0': dependencies: - '@commitlint/types': 21.0.1 - semver: 7.8.1 + '@commitlint/types': 21.2.0 + semver: 7.8.5 - '@commitlint/lint@21.0.2': + '@commitlint/lint@21.2.0': dependencies: - '@commitlint/is-ignored': 21.0.2 - '@commitlint/parse': 21.0.2 - '@commitlint/rules': 21.0.2 - '@commitlint/types': 21.0.1 + '@commitlint/is-ignored': 21.2.0 + '@commitlint/parse': 21.2.0 + '@commitlint/rules': 21.2.0 + '@commitlint/types': 21.2.0 - '@commitlint/load@21.0.2(@types/node@25.3.5)(typescript@5.9.3)': + '@commitlint/load@21.2.0(@types/node@25.3.5)(typescript@5.9.3)': dependencies: - '@commitlint/config-validator': 21.0.1 + '@commitlint/config-validator': 21.2.0 '@commitlint/execute-rule': 21.0.1 - '@commitlint/resolve-extends': 21.0.1 - '@commitlint/types': 21.0.1 - cosmiconfig: 9.0.1(typescript@5.9.3) - cosmiconfig-typescript-loader: 6.3.0(@types/node@25.3.5)(cosmiconfig@9.0.1(typescript@5.9.3))(typescript@5.9.3) - es-toolkit: 1.47.0 + '@commitlint/resolve-extends': 21.2.0 + '@commitlint/types': 21.2.0 + cosmiconfig: 9.0.2(typescript@5.9.3) + cosmiconfig-typescript-loader: 6.3.0(@types/node@25.3.5)(cosmiconfig@9.0.2(typescript@5.9.3))(typescript@5.9.3) + es-toolkit: 1.49.0 is-plain-obj: 4.1.0 picocolors: 1.1.1 transitivePeerDependencies: - '@types/node' - typescript - '@commitlint/message@21.0.2': {} + '@commitlint/message@21.2.0': {} - '@commitlint/parse@21.0.2': + '@commitlint/parse@21.2.0': dependencies: - '@commitlint/types': 21.0.1 - conventional-changelog-angular: 8.3.1 - conventional-commits-parser: 6.4.0 + '@commitlint/types': 21.2.0 + conventional-changelog-angular: 9.2.1 + conventional-commits-parser: 7.0.1 - '@commitlint/read@21.0.2(conventional-commits-parser@6.4.0)': + '@commitlint/read@21.2.0(conventional-commits-parser@6.4.0)': dependencies: - '@commitlint/top-level': 21.0.2 - '@commitlint/types': 21.0.1 + '@commitlint/top-level': 21.2.0 + '@commitlint/types': 21.2.0 git-raw-commits: 5.0.1(conventional-commits-parser@6.4.0) tinyexec: 1.2.4 transitivePeerDependencies: - conventional-commits-filter - conventional-commits-parser - '@commitlint/resolve-extends@21.0.1': + '@commitlint/resolve-extends@21.2.0': dependencies: - '@commitlint/config-validator': 21.0.1 - '@commitlint/types': 21.0.1 - es-toolkit: 1.47.0 + '@commitlint/config-validator': 21.2.0 + '@commitlint/types': 21.2.0 + es-toolkit: 1.49.0 global-directory: 5.0.0 resolve-from: 5.0.0 - '@commitlint/rules@21.0.2': + '@commitlint/rules@21.2.0': dependencies: - '@commitlint/ensure': 21.0.1 - '@commitlint/message': 21.0.2 + '@commitlint/ensure': 21.2.0 + '@commitlint/message': 21.2.0 '@commitlint/to-lines': 21.0.1 - '@commitlint/types': 21.0.1 + '@commitlint/types': 21.2.0 '@commitlint/to-lines@21.0.1': {} - '@commitlint/top-level@21.0.2': + '@commitlint/top-level@21.2.0': dependencies: escalade: 3.2.0 @@ -523,20 +558,29 @@ snapshots: conventional-commits-parser: 6.4.0 picocolors: 1.1.1 + '@commitlint/types@21.2.0': + dependencies: + conventional-commits-parser: 7.0.1 + picocolors: 1.1.1 + '@conventional-changelog/git-client@2.7.0(conventional-commits-parser@6.4.0)': dependencies: '@simple-libs/child-process-utils': 1.0.2 '@simple-libs/stream-utils': 1.2.0 - semver: 7.8.1 + semver: 7.8.5 optionalDependencies: conventional-commits-parser: 6.4.0 + '@conventional-changelog/template@1.2.1': {} + '@simple-libs/child-process-utils@1.0.2': dependencies: '@simple-libs/stream-utils': 1.2.0 '@simple-libs/stream-utils@1.2.0': {} + '@simple-libs/stream-utils@2.0.0': {} + '@types/node@25.3.5': dependencies: undici-types: 7.18.2 @@ -573,9 +617,13 @@ snapshots: array-ify: 1.0.0 dot-prop: 5.3.0 - conventional-changelog-angular@8.3.1: + conventional-changelog-angular@9.2.1: dependencies: - compare-func: 2.0.0 + '@conventional-changelog/template': 1.2.1 + + conventional-changelog-conventionalcommits@10.2.1: + dependencies: + '@conventional-changelog/template': 1.2.1 conventional-changelog-conventionalcommits@9.3.1: dependencies: @@ -586,14 +634,19 @@ snapshots: '@simple-libs/stream-utils': 1.2.0 meow: 13.2.0 - cosmiconfig-typescript-loader@6.3.0(@types/node@25.3.5)(cosmiconfig@9.0.1(typescript@5.9.3))(typescript@5.9.3): + conventional-commits-parser@7.0.1: + dependencies: + '@simple-libs/stream-utils': 2.0.0 + meow: 14.1.0 + + cosmiconfig-typescript-loader@6.3.0(@types/node@25.3.5)(cosmiconfig@9.0.2(typescript@5.9.3))(typescript@5.9.3): dependencies: '@types/node': 25.3.5 - cosmiconfig: 9.0.1(typescript@5.9.3) + cosmiconfig: 9.0.2(typescript@5.9.3) jiti: 2.6.1 typescript: 5.9.3 - cosmiconfig@9.0.1(typescript@5.9.3): + cosmiconfig@9.0.2(typescript@5.9.3): dependencies: env-paths: 2.2.1 import-fresh: 3.3.1 @@ -614,7 +667,7 @@ snapshots: dependencies: is-arrayish: 0.2.1 - es-toolkit@1.47.0: {} + es-toolkit@1.49.0: {} escalade@3.2.0: {} @@ -714,6 +767,8 @@ snapshots: meow@13.2.0: {} + meow@14.1.0: {} + parent-module@1.0.1: dependencies: callsites: 3.1.0 @@ -733,7 +788,7 @@ snapshots: resolve-from@5.0.0: {} - semver@7.8.1: {} + semver@7.8.5: {} string-width@7.2.0: dependencies: From a799c4ed57419bea941ce2fbb75285868412531b Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 7 Jul 2026 04:49:54 +0000 Subject: [PATCH 11/20] chore(deps-dev): bump @commitlint/config-conventional (#362) Bumps [@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/HEAD/@commitlint/config-conventional) from 21.0.2 to 21.2.0. - [Release notes](https://github.com/conventional-changelog/commitlint/releases) - [Changelog](https://github.com/conventional-changelog/commitlint/blob/master/@commitlint/config-conventional/CHANGELOG.md) - [Commits](https://github.com/conventional-changelog/commitlint/commits/v21.2.0/@commitlint/config-conventional) --- updated-dependencies: - dependency-name: "@commitlint/config-conventional" dependency-version: 21.2.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- package.json | 2 +- pnpm-lock.yaml | 58 +++----------------------------------------------- 2 files changed, 4 insertions(+), 56 deletions(-) diff --git a/package.json b/package.json index 5e7fdbd0..64bdebcc 100644 --- a/package.json +++ b/package.json @@ -32,7 +32,7 @@ }, "devDependencies": { "@commitlint/cli": "^21.2.0", - "@commitlint/config-conventional": "^21.0.2", + "@commitlint/config-conventional": "^21.2.0", "ajv": "8.20.0", "ajv-formats": "3.0.1", "js-yaml": "5.2.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4bc5ab2e..fd05eb99 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -12,8 +12,8 @@ importers: specifier: ^21.2.0 version: 21.2.0(@types/node@25.3.5)(conventional-commits-parser@6.4.0)(typescript@5.9.3) '@commitlint/config-conventional': - specifier: ^21.0.2 - version: 21.0.2 + specifier: ^21.2.0 + version: 21.2.0 ajv: specifier: 8.20.0 version: 8.20.0 @@ -42,10 +42,6 @@ packages: engines: {node: '>=22.12.0'} hasBin: true - '@commitlint/config-conventional@21.0.2': - resolution: {integrity: sha512-P/ZRhryQmkj0Z0dY9FOoRwe3xkwJyyAdtXwt01NT2kuZttcG2CNYp1q5Ci3u+nDT2jcbJRw2kt13Czl1qKNPfg==} - engines: {node: '>=22.12.0'} - '@commitlint/config-conventional@21.2.0': resolution: {integrity: sha512-Qf8WRDVcyVd14if6VTWenebxFbKnVnbzPUJjlzjkyJGeHK2xCGd63Dr1XZzj0plXKQb9P0BfOxoc1HVeCo2BWQ==} engines: {node: '>=22.12.0'} @@ -106,10 +102,6 @@ packages: resolution: {integrity: sha512-Y5gmQ+KxzqCrBFJfLvFEPvvwD3LDiNZoTT2yeFBm96M8qhmqSzQc5DvX3rheAaAMjyIvMXOCLS/mWfdpONsjyQ==} engines: {node: '>=22.12.0'} - '@commitlint/types@21.0.1': - resolution: {integrity: sha512-4u7w8jcoCUFWhjWnASYzZHAP34OqOtuFBN87nQmFvqda03YU0T6z+yB4w0gSAMpekiRqqGk5rt+qSlW+a2vSEg==} - engines: {node: '>=22.12.0'} - '@commitlint/types@21.2.0': resolution: {integrity: sha512-7zVFCDB2reMvJH5dmbKnOQPjZEvjdJTH8jc0U/PIPU1r3/+vf5pD1HlfitV2MWsWXrvu7u39iY1lyLUPOaN0Gw==} engines: {node: '>=22.12.0'} @@ -167,9 +159,6 @@ packages: argparse@2.0.1: resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} - array-ify@1.0.0: - resolution: {integrity: sha512-c5AMf34bKdvPhQ7tBGhqkgKNUzMr4WUs+WDtC2ZUGOUncbxKMTvqxYctiseW3+L4bA8ec+GcZ6/A/FW4m8ukng==} - callsites@3.1.0: resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==} engines: {node: '>=6'} @@ -178,9 +167,6 @@ packages: resolution: {integrity: sha512-k7ndgKhwoQveBL+/1tqGJYNz097I7WOvwbmmU2AR5+magtbjPWQTS1C5vzGkBC8Ym8UWRzfKUzUUqFLypY4Q+w==} engines: {node: '>=20'} - compare-func@2.0.0: - resolution: {integrity: sha512-zHig5N+tPWARooBnb0Zx1MFcdfpyJrfTJ3Y5L+IFvUm8rM74hHz66z0gw0x4tijh5CorKkKUCnW82R2vmpeCRA==} - conventional-changelog-angular@9.2.1: resolution: {integrity: sha512-oWSL6ZhnXbYraOFTK3PgRAQJ8fADDAEv5K6AdeyQPLvjFmhG8+ejL0jZZp/R7vTmGJaBvZEE+sE7dB4bCv7sAw==} engines: {node: '>=22'} @@ -189,10 +175,6 @@ packages: resolution: {integrity: sha512-n4Kr1HFMTf3iMbES0TMxKIcYtUUv4rKqyQQp2JwfOEfFCOfGT3Tq4mCyJ8S9/YPyWhydjfKrrvnyl+gCjA+mJQ==} engines: {node: '>=22'} - conventional-changelog-conventionalcommits@9.3.1: - resolution: {integrity: sha512-dTYtpIacRpcZgrvBYvBfArMmK2xvIpv2TaxM0/ZI5CBtNUzvF2x0t15HsbRABWprS6UPmvj+PzHVjSx4qAVKyw==} - engines: {node: '>=18'} - conventional-commits-parser@6.4.0: resolution: {integrity: sha512-tvRg7FIBNlyPzjdG8wWRlPHQJJHI7DylhtRGeU9Lq+JuoPh5BKpPRX83ZdLrvXuOSu5Eo/e7SzOQhU4Hd2Miuw==} engines: {node: '>=18'} @@ -220,10 +202,6 @@ packages: typescript: optional: true - dot-prop@5.3.0: - resolution: {integrity: sha512-QM8q3zDe58hqUqjraQOmzZ1LIH9SWQJTlEKCH4kJ2oQvLZk7RbQXvtDM2XEq3fwkV9CCvvH4LA0AV+ogFsBM2Q==} - engines: {node: '>=8'} - emoji-regex@10.6.0: resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==} @@ -276,10 +254,6 @@ packages: is-arrayish@0.2.1: resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==} - is-obj@2.0.0: - resolution: {integrity: sha512-drqDG3cbczxxEJRoOXcOjtdp1J/lyp1mNn0xaznRs8+muBhgQcrnbspox5X5fOw0HnMnbfDzvnEMEtqDEJEo8w==} - engines: {node: '>=8'} - is-plain-obj@4.1.0: resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==} engines: {node: '>=12'} @@ -460,11 +434,6 @@ snapshots: - conventional-commits-parser - typescript - '@commitlint/config-conventional@21.0.2': - dependencies: - '@commitlint/types': 21.0.1 - conventional-changelog-conventionalcommits: 9.3.1 - '@commitlint/config-conventional@21.2.0': dependencies: '@commitlint/types': 21.2.0 @@ -553,11 +522,6 @@ snapshots: dependencies: escalade: 3.2.0 - '@commitlint/types@21.0.1': - dependencies: - conventional-commits-parser: 6.4.0 - picocolors: 1.1.1 - '@commitlint/types@21.2.0': dependencies: conventional-commits-parser: 7.0.1 @@ -602,8 +566,6 @@ snapshots: argparse@2.0.1: {} - array-ify@1.0.0: {} - callsites@3.1.0: {} cliui@9.0.1: @@ -612,11 +574,6 @@ snapshots: strip-ansi: 7.2.0 wrap-ansi: 9.0.2 - compare-func@2.0.0: - dependencies: - array-ify: 1.0.0 - dot-prop: 5.3.0 - conventional-changelog-angular@9.2.1: dependencies: '@conventional-changelog/template': 1.2.1 @@ -625,14 +582,11 @@ snapshots: dependencies: '@conventional-changelog/template': 1.2.1 - conventional-changelog-conventionalcommits@9.3.1: - dependencies: - compare-func: 2.0.0 - conventional-commits-parser@6.4.0: dependencies: '@simple-libs/stream-utils': 1.2.0 meow: 13.2.0 + optional: true conventional-commits-parser@7.0.1: dependencies: @@ -655,10 +609,6 @@ snapshots: optionalDependencies: typescript: 5.9.3 - dot-prop@5.3.0: - dependencies: - is-obj: 2.0.0 - emoji-regex@10.6.0: {} env-paths@2.2.1: {} @@ -700,8 +650,6 @@ snapshots: is-arrayish@0.2.1: {} - is-obj@2.0.0: {} - is-plain-obj@4.1.0: {} jiti@2.6.1: {} From 8e59e77129589dc8c01b71f2399c9e5a145be1c6 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 7 Jul 2026 09:42:32 +0200 Subject: [PATCH 12/20] =?UTF-8?q?docs(framework):=20rework=20the=20documen?= =?UTF-8?q?tation=20=E2=80=94=20install-first,=20concise,=20emoji-styled?= =?UTF-8?q?=20(#407)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(framework): rework docs to be install-first, concise, and consistent Restructure the README to lead with installation (Claude Code first, other tools folded into one section), moving community context below. Fix cross-doc anchor rot in FAQ/TROUBLESHOOTING, reconcile stale plugin/skill/package counts against the filesystem (7 plugins, 40 skills, 2 agents, 8 release packages), and add the missing aidd-ui, aidd-vcs 00-repo-init, and aidd-dev 10-todo entries. Collapse duplication: delete the orphaned docs/RELEASE.md (duplicated the canonical root RELEASE.md) after moving its unique promote/recovery content into MAINTAINERS; make MAINTAINERS the single home for the per-tool bundle list and point CONTRIBUTING at it. Co-Authored-By: Claude Opus 4.8 * docs(framework): make README essential — visual quick start, prerequisites, flat-only other tools Rework the README around the "best repo" pattern: one-line what, a two-phase visual quick start (onboard → project memory once, then the feature loop), install with explicit prerequisites (Claude Code + Node for plugin hooks), and marketing collapsed to a short community line. Other tools now install from the flat archive only (unzip, no CLI); the CLI-registered marketplace flow is marked as coming, since the CLI is not yet available. List the two bundled Node hooks in ARCHITECTURE and tie them to prerequisites + Trust and safety. Fix cross-doc anchors to the real GitHub slugs (emoji headings carry a leading hyphen). Co-Authored-By: Claude Opus 4.8 * docs(framework): restructure README install/quick-start for clarity Split into a dedicated Prerequisites section, a clear Claude Code install, a tool-compatibility table, and per-tool collapsible install blocks (flat archive). Quick start now offers three explicit entry points: guided onboard, manual project-memory, or the full feature flow. Group Recipes and docs into one readable "Learn more" block, and tighten Trust and safety to two lines. Link to owning docs instead of restating scopes, versioning, or hook details. Co-Authored-By: Claude Opus 4.8 * docs(framework): refine README install/quick-start and slim CONTRIBUTING README: move the tool-support table under Prerequisites (framed as "an AI tool we support"), drop the inline scopes/versioning pointer (now only in Learn more), and give each other-tool a marketplace + flat split in its collapsible. Quick start now shows the three entry points (onboard / project-memory / feature flow) as a scannable table above the flow diagram. Contribute line just links CONTRIBUTING. CONTRIBUTING: refactor dense paragraphs into scannable bullets, fix the stale Node version (22.12+), and let it own the PR-rights rule the README delegates. No duplication — link to vcs.md, GOVERNANCE, RELEASE, and MAINTAINERS for the details they own. Co-Authored-By: Claude Opus 4.8 * docs(framework): document real per-tool install methods Replace the guessed "aidd marketplace add" steps with each tool's actual native mechanism, verified against official docs and the release archives: - Cursor: copy plugins into ~/.cursor/plugins/local/ (all plans; only team marketplaces are Teams/Enterprise-gated). - GitHub Copilot: .github/ customization files (skills, agents); Copilot CLI plugin marketplace noted. - Codex: native `codex plugin marketplace add` / `codex plugin add`, or skills via .codex/skills/. - OpenCode: file-based, unzip into .opencode/. The compatibility table now shows only Flat/Marketplace dist availability; how-to lives in each collapsible. FAQ and TROUBLESHOOTING no longer claim a universal flat-unzip. Co-Authored-By: Claude Opus 4.8 * docs(framework): use each tool's official marketplace commands Codex and Copilot install via their native ` plugin marketplace add ai-driven-dev/framework` + install commands, mirroring Claude Code and using the same plugin names. Cursor via Customize → Plugins (local fallback for plans without team marketplaces). OpenCode stays file-based. Drops the archive-download clutter for the marketplace tools. Co-Authored-By: Claude Opus 4.8 * docs(framework): structure each tool as Marketplace + Flat with release archives Every other-tool collapsible now follows one shape: a Marketplace block (release zip + install commands) and a Flat block (release zip + target dir), so each format is explicit. OpenCode is Flat only. Co-Authored-By: Claude Opus 4.8 * docs(framework): recipe-style per-tool install blocks Rewrite each other-tool collapsible as terse Marketplace/Flat subheads with numbered steps, cutting prose. OpenCode marked Flat-only in its summary. Co-Authored-By: Claude Opus 4.8 * docs(framework): note Claude-format support for Cursor/Copilot, fence commands Add a Claude-format line to the Cursor and Copilot install blocks (Copilot auto-detects .claude/skills and .claude/agents; Cursor reads .claude/skills), and move the install commands into fenced code blocks for readability. Co-Authored-By: Claude Opus 4.8 * docs(framework): collapse per-tool install into a single code block each Each other-tool block is now one fenced recipe: download steps as comments, Marketplace and Flat inline, with a one-line Claude-format / docs note underneath. Much lighter to scan than the prose + inline codespans. Co-Authored-By: Claude Opus 4.8 * docs(framework): split each tool back into visible Marketplace / Flat blocks Restore the two categories as bold subheads, each with its own fenced code block on its own lines. Merging them into one block had hidden the distinction. Co-Authored-By: Claude Opus 4.8 * docs(framework): fenced blocks hold real commands only, not comments Move the download/unzip step to a short prose line per category and keep only actual commands inside the code fences. Flat entries with no command are a plain line, no empty comment block. Co-Authored-By: Claude Opus 4.8 * docs(framework): per-tool install as title-only heads + numbered recipe Each category (Marketplace / Flat) is a bare bold title on its own line, followed by numbered steps; commands sit in a fence as a step. Notes (plan, Claude format) move to one italic line under the steps. Co-Authored-By: Claude Opus 4.8 * docs(framework): Claude Code install in-session and by command line Show both official paths: the /plugin slash commands in a session and the equivalent `claude plugin marketplace add` / `claude plugin install` shell commands. Co-Authored-By: Claude Opus 4.8 * docs(framework): restore intro, split Prerequisites/Compatibility, vertical diagram - Bring back the fuller intro (marketplace one-liner + SDLC blockquote). - Separate Prerequisites (an AI tool + Node) from a dedicated Compatibility section holding the tool table. - Reword the Other-tools intro onto its own lines ("bundle" not "archives"). - Flip the quick-start diagram to top-down. Co-Authored-By: Claude Opus 4.8 * docs(framework): add cookbook recipes for greenfield and feature flow Add two at-a-glance command-sequence recipes via the cook template: start-a-project (greenfield setup) and ship-a-feature (idea → PR). Index them in recipes/README.md, surface them in the README, and point the contributing note at the shipped /aidd-context:12-cook skill. Co-Authored-By: Claude Opus 4.8 * docs(framework): enrich greenfield recipe via cook (brainstorm, PRD, bootstrap) Upsert start-a-project through the /aidd-context:12-cook template: the greenfield sequence now runs brainstorm → PRD → bootstrap → project memory → onboard → first feature. Refresh its recipes index goal. Co-Authored-By: Claude Opus 4.8 * docs(framework): frame onboard as the guided alternative in recipes Onboard is the guided path, not a manual step: drop it from the greenfield sequence and add a "prefer guided?" note pointing to it in both recipes. Ship-a-feature prerequisite now points at Start a project. Co-Authored-By: Claude Opus 4.8 * docs(framework): add recipes CTA under the quick-start diagram Point readers from the quick-start diagram to the recipes for other flows (start a project, ship a feature). Co-Authored-By: Claude Opus 4.8 * docs(framework): restore The AI-Driven Dev section; roles as a nav pointer README: bring back the "The AI-Driven Dev" community section (R&D + Discord/programme/ecosystem) alongside a slim Contributing. CONTRIBUTING: replace the profile mermaid + restated rights with a "where each starts" table that defers role definitions to GOVERNANCE (no duplication of the responsible file). Repoint the FAQ community link. Co-Authored-By: Claude Opus 4.8 * docs(framework): apply no-duplication audit — link owners, fix stale facts - CREATE_PLUGIN: drop the restated toolchain (stale "Node 20+") and dead "Development setup" anchor → link CONTRIBUTING #1-set-up; point the orthogonality bullet at ARCHITECTURE instead of restating it. - MARKETPLACE: fix the wrong tag format (aidd- double prefix) → -vX.Y.Z with the tooling link to vcs.md; trim the marketing paragraph to one line. - MAINTAINERS: People and branch-protection policy now link GOVERNANCE instead of restating roles/promotion/merge rules; split the back-merge run-on into bullets. - GLOSSARY: include aidd-ui in the plugin domain list. Co-Authored-By: Claude Opus 4.8 * docs(framework): bring all docs into the README's emoji-headed style Emoji + lighter prose across ARCHITECTURE, MARKETPLACE, CREATE_PLUGIN, CONTRIBUTING, GOVERNANCE, RELEASE, GLOSSARY, MAINTAINERS, CATALOG — every ## section heading now carries a fitting emoji, matching the README. Cross-doc link-target headings use variation-selector-free emoji so their GitHub slug stays a clean leading-hyphen form; inbound links updated to the new #-slug anchors. Verified: 0 broken fragment links. Co-Authored-By: Claude Opus 4.8 * docs(framework): merge FAQ+Troubleshooting, add flow diagrams Merge TROUBLESHOOTING into a single emoji-headed docs/FAQ.md (FAQ & Troubleshooting) and drop the separate file; repoint the README docs row. Add three flow diagrams: contribution flow (CONTRIBUTING), plugin build lifecycle (CREATE_PLUGIN), and marketplace resolution (MARKETPLACE). Co-Authored-By: Claude Opus 4.8 * docs(framework): slim CREATE_PLUGIN to a lean reference (185 → 38 lines) Drop the verbose scaffolding/SKILL.md/action code examples that duplicated ARCHITECTURE's anatomy; keep only what lives nowhere else — marketplace registration, release-please config, local testing, ship guardrails — and link ARCHITECTURE for the model. No skill scaffolds a full plugin, so this stays the home for the registration steps. Co-Authored-By: Claude Opus 4.8 * docs(framework): trim MAINTAINERS — dedup + condense the board runbook Condense the ~53-line Project board setup to ~18 (drop redundant CLI snippets and the checklist that restated the field bullets). Cut the Daily "Review PRs" merge-rule restatement (link GOVERNANCE) and the "Build your own plugin" registration line (now owned by CREATE_PLUGIN). 174 → 140 lines. Co-Authored-By: Claude Opus 4.8 * docs(framework): correct ARCHITECTURE orthogonality claim and surface usage Cross-plugin orthogonality was overstated as absolute ("plugins do not reference each other by name"), but aidd-orchestrator deliberately names the aidd-dev pipeline it drives. Reframe: recipes delegate by capability; the orchestrator is the named exception. Also note commands/rules/MCP are schema-supported but currently unused by any bundled plugin. Verified correct against the codebase otherwise. Co-Authored-By: Claude Opus 4.8 * docs(framework): keep orthogonality absolute — orchestrators included The rule holds for all plugins, orchestrators included; an orchestrator naming a sibling by aidd-:... is a violation, not an exception. Note it is not yet mechanically enforced, which is how such a hardcode slips through today. Co-Authored-By: Claude Opus 4.8 --------- Co-authored-by: Claude Opus 4.8 --- AGENTS.md | 54 ++++++ CONTRIBUTING.md | 115 ++++--------- GOVERNANCE.md | 43 ++--- README.md | 249 ++++++++++++++++------------ RELEASE.md | 52 +++--- ROADMAP.md | 2 +- docs/ARCHITECTURE.md | 45 +++-- docs/CATALOG.md | 51 +++--- docs/CREATE_PLUGIN.md | 174 +++---------------- docs/FAQ.md | 47 ++++-- docs/GLOSSARY.md | 24 +-- docs/MAINTAINERS.md | 146 ++++++++-------- docs/MARKETPLACE.md | 33 ++-- docs/RELEASE.md | 61 ------- docs/TROUBLESHOOTING.md | 32 ---- plugins/aidd-dev/README.md | 3 +- plugins/aidd-orchestrator/README.md | 6 +- plugins/aidd-vcs/README.md | 5 +- recipes/README.md | 4 +- recipes/ship-a-feature.md | 37 +++++ recipes/start-a-project.md | 34 ++++ 21 files changed, 561 insertions(+), 656 deletions(-) create mode 100644 AGENTS.md delete mode 100644 docs/RELEASE.md delete mode 100644 docs/TROUBLESHOOTING.md create mode 100644 recipes/ship-a-feature.md create mode 100644 recipes/start-a-project.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..51237dab --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# AGENTS.md + +> On the first message of a conversation, tell the user: "AI-Driven Development ON - Date: {current_date}, TZ: {current_timezone}." + +## Behavior + +- **Stay critical.** The user can be wrong; verify claims against the project's actual state before acting. +- **Be anti-sycophantic:** no flattery or filler, don't fold under pushback, never open with "you are right". Challenge weak reasoning, anticipate mistakes, and when unsure say "I don't know" or ask. +- **Surface tradeoffs and evaluate their impact** instead of hiding them. + +## Communication + +- **Answer first:** result before reason. Drop pleasantries (sure, of course, happy to) and hedging. +- **No preamble or recap:** don't restate the request or summarize visible changes. Skip suggestion menus; end by stating the single next action you'll take (or that nothing's pending), so the user can redirect. +- **Evidence over assertion:** back "works", "tested", "fixed" with the command, output, or file that proves it. +- **Quote the shortest decisive line** of an error or log, not the whole dump. +- **No tool-call narration.** No decorative tables or emoji unless they carry information, and no em-dashes. +- **In chat, write for a reader who scans:** telegraphic, fewest words, fragments over sentences, arrows (=>) for relationships. Cut any word that doesn't change meaning. Normal prose in authored docs and code. Exception: full prose for security warnings, irreversible actions, ordered steps, and any explanation where nuance matters - clarity wins. + +## Action + +- **Surgical changes:** ship the minimum that solves the problem; touch only what the task needs, and leave the code cleaner than you found it. +- **Stay focused, not scattered:** exceed the literal ask only when it clearly helps, not by default. When you spot an unrelated issue, note it in one line and keep going; detour only if it blocks the task. +- **Solve your own issues first:** genuinely try to resolve it yourself before escalating to the human. +- **Do not commit or push** unless the user asks. +- **Don't assume your knowledge is current.** +- **Placement discipline:** for every plugin change, think hard about where responsibility belongs; follow `docs/ARCHITECTURE.md`. +- **Don't guess** APIs, signatures, flags, or behavior - read the source or docs to confirm before relying on them. +- **Ambiguous or expensive task:** ask one sharp question to pin down scope before building, rather than guess. +- **Batch independent operations** in one pass, not one at a time. +- **Fan out** independent subtasks to parallel subagents when you own the overall flow and the work is genuinely parallel. +- **Before adding any instruction, finding, or rule, check whether an existing one already covers or contradicts it.** If so, don't add a parallel: delete it, merge it into the stronger one, or rewrite with explicit scope and priority. +- **Name by intention, not mechanism:** describe the goal or responsibility, not the tool or file format. + +## Memory Management + +Project docs, memory, specs, and plans live in `aidd_docs/`. + +### Project memory + + +@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 + + +- If the block above is empty, run `ls -1tr aidd_docs/memory/` and read each file. +- Load `aidd_docs/memory/external/*` when the user asks. +- Load `aidd_docs/memory/internal/*` when the task needs it. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b926b083..b28d4c1d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,110 +1,61 @@ # Contributing to the AIDD Framework -The source of truth for AIDD skills, agents, rules, and templates. Authored in Claude Code syntax; at release time the CLI generates archives adapted to each supported tool. - -> Wider AIDD community, roles, and the training programme live at [ai-driven-dev.fr](https://www.ai-driven-dev.fr/). This file covers contributing to **this repository**. - -## Who does what (by profile) +Source of truth for AIDD skills, agents, rules, and templates — authored in Claude Code syntax; the CLI adapts an archive per tool at release. This file covers contributing to **this repository**; the wider community, roles, and training programme live at [ai-driven-dev.fr](https://www.ai-driven-dev.fr/). ```mermaid ---- -title: Contribution by profile ---- -flowchart TD - Start["Anyone: open an issue, idea or question"] - Who{"Your profile?"} - Pub["Public - discuss, react, upvote"] - Core["Core Team - vote on roadmap priority"] - Cert["Certifie AIDD - branch, commit, open PR"] - Rev["Habilite AIDD - review (CODEOWNERS)"] - Merge["Habilite AIDD - merge, release-please ships"] - - Start --> Who - Who -->|Public| Pub - Who -->|Core Team| Core - Who -->|Certifie| Cert - Cert --> Rev - Rev --> Merge +flowchart LR + Issue["💡 Issue / idea"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Habilité review"] --> Merge["✅ Squash-merge → next"] --> Release["🚀 Weekly promote → release-please ships"] ``` -**Pull-request rights are held by Certifié and Habilité only** (Certifié via [certification](https://www.ai-driven-dev.fr/), Habilité by promotion). Full role ladder, voting weights, and promotion: [`GOVERNANCE.md`](./GOVERNANCE.md#roles). The rest of this guide is the *how* for those opening PRs. - -## 1. Set up +## 👥 Who can contribute -Needs **Node 20+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). Then: +Roles and their rights are defined in [`GOVERNANCE.md`](./GOVERNANCE.md#-roles). Where each starts: -```bash -make setup -``` - -- installs deps + git hooks -- registers this checkout as a local marketplace -- installs the plugins into Claude + Codex (`y/N` confirm, since it writes your global config; `YES=1` skips) +| Role | Start here | +| --- | --- | +| 👤 **Public** | [Open an issue](https://github.com/ai-driven-dev/framework/issues) or [discussion](https://github.com/ai-driven-dev/framework/discussions) | +| 🗳️ **Core Team** | Vote on roadmap priority | +| 🌱 **Certifié** | Open a pull request → [Set up](#-1-set-up) | +| 🛡️ **Habilité** | Review and merge | -`make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks. +The rest of this guide is the *how* for those opening PRs. -### Markdown links +## 🔧 1. Set up -Lefthook runs the Markdown link checker during pre-commit. `make setup` installs the hooks; if dependencies are already installed and you only need the hook wiring, run: +Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). ```bash -pnpm exec lefthook install --force +make setup # deps + git hooks, registers a local marketplace, installs plugins into Claude + Codex ``` -Run `node scripts/check-markdown-links.js` to scan the repository. Detailed usage, supported forms, exclusions, and fix guidance live in `node scripts/check-markdown-links.js --help`. - -### Test your changes locally - -Exercise the skills you touched before opening a PR. Neither tool hot-reloads the checkout (both serve a copied cache), so after editing: - -```bash -make reload # all plugins; or PLUGIN="aidd-refine aidd-pm" for a subset -``` - -- reinstalls each plugin from the checkout (current versions, no bump - nothing to revert) -- Claude installs straight from the raw repo (already native Claude format); Codex installs from a tree the `aidd` CLI builds (Claude syntax -> Codex, e.g. agents -> TOML) -- refreshes the cache in Claude + Codex; Codex agents are copied to `~/.codex/agents/` (Codex does not load plugin-bundled agents yet) -- restart the session to load it (`/reload-plugins` covers a Claude-only edit to an existing skill) - -## 2. Commit - -Format: `(): description`. - -```bash -git commit -m "feat(aidd-dev): add for-sure skill" -``` +`make` lists every target; `make doctor` and `make check` verify the environment and run the pre-commit checks (including the Markdown link checker). -One scope per commit (split cross-plugin changes). The types, the scopes, and the rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) - it mirrors `commitlint.config.cjs`, the source of truth. **Type** drives the release; see [`RELEASE.md`](./RELEASE.md) for what each type produces. +## ✏️ 2. Make your change -## 3. Open a pull request +- **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill. +- **Commit** — `(): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md). -- Branch off `next` and target `next` (the integration branch); only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target — the full prefix → label → target table is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types). -- **Fill the PR template** (applied automatically): explain *what* changed and *how* you resolved it technically - that narrative is the point of the PR. The conventional title and pre-commit hooks are already enforced by CI, so don't spend the description re-asserting them. -- **Label the PR** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance. The triage label follows your branch kind and the PR skill applies it automatically; the label per kind is in that same [routing table](aidd_docs/memory/vcs.md#types) (`security` is cross-cutting — add it to any kind). -- The PR title follows the same conventional format (the **Commitlint** CI job enforces it); PRs are squash-merged using that title. -- A **Habilité** review gates every merge ([`CODEOWNERS`](./.github/CODEOWNERS)); Certifié contributors cannot self-merge. -- Decision rules (lazy consensus, explicit consensus for cross-plugin/contract changes, the quality veto) live in [`GOVERNANCE.md`](./GOVERNANCE.md#code-decisions-merging). +## 🔀 3. Open a pull request -## Releases +- **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types). +- **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them). +- **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant. +- **A Habilité review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — Certifié contributors cannot self-merge. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging). -How releases flow (the `main`/`next` model, weekly cadence, hotfix, auto-merge) is in [`RELEASE.md`](./RELEASE.md); the release tooling is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md). What a release produces, for contributors: +## 🚀 Releases -- **7 independently-versioned packages** (root `aidd-framework` + the 6 plugins). -- On release, CI attaches the bundles: - - `aidd-framework-marketplace-X.Y.Z.zip` - the Claude Code marketplace (`.claude-plugin/` + `plugins/`); kept as the legacy Claude alias of `aidd-framework-claude-marketplace-X.Y.Z.zip`. - - `-vX.Y.Z.zip` - per released plugin. - - `aidd-framework---X.Y.Z.zip` - **per-tool distributions** built by `aidd-cli` (`framework build`) on the root release: 4 marketplace (claude/cursor/copilot/codex) + 5 flat (+opencode, flat-only) = 9 archives. Produced by the `build-per-tool` matrix job in `.github/workflows/ci.yml`, pinned to a specific `@ai-driven-dev/cli` version. +The `main`/`next` model, weekly cadence, and hotfix flow → [`RELEASE.md`](./RELEASE.md). A release ships **8 independently-versioned packages** (root `aidd-framework` + the 7 plugins; `aidd-ui` is alpha) plus per-tool archives; full breakdown → [`MAINTAINERS.md`](docs/MAINTAINERS.md#-releases). -## Reporting issues +## 🐛 Reporting issues -[Open an issue](https://github.com/ai-driven-dev/framework/issues/new/choose) (🐛 Bug or ✨ Feature). New issues are auto-added to the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). For **usage questions**, use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)). +[Open an issue](https://github.com/ai-driven-dev/framework/issues/new/choose) (🐛 Bug or ✨ Feature) — auto-added to the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). For usage questions use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)). -## Reference +## 📚 Reference -- **Build a plugin** - [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) -- **Architecture & terms** - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/GLOSSARY.md`](docs/GLOSSARY.md) -- **Patterns to follow**: a minimal plugin [`aidd-refine`](plugins/aidd-refine/), a router skill [`00-onboard`](plugins/aidd-context/skills/00-onboard/), agents [`aidd-dev/agents`](plugins/aidd-dev/agents/). -- **Syntax & per-tool builds**: source files use Claude Code syntax; at release time the `aidd-cli` generates an archive per supported tool, mapping each surface to that tool's equivalent. In frontmatter, `name` / `description` / `argument-hint` are universal; other keys (`model`, `color`, `paths`, …) are tool-specific and ignored where unsupported. +- **Build a plugin** → [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) +- **Architecture & terms** → [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/GLOSSARY.md`](docs/GLOSSARY.md) +- **Patterns to follow** → a minimal plugin [`aidd-refine`](plugins/aidd-refine/), a router skill [`00-onboard`](plugins/aidd-context/skills/00-onboard/), agents [`aidd-dev/agents`](plugins/aidd-dev/agents/) +- **Per-tool builds** → source files use Claude Code syntax; the `aidd-cli` maps each surface to its per-tool equivalent at release. `name` / `description` / `argument-hint` are universal; other frontmatter keys (`model`, `color`, `paths`, …) are tool-specific and ignored where unsupported. --- diff --git a/GOVERNANCE.md b/GOVERNANCE.md index a8e7cee6..6f96c4ba 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -18,7 +18,7 @@ flowchart LR Certifie -- promoted --> Habilite ``` -## Roles +## 👥 Roles | Tier | How you get there | Adds (on top of the rung below) | Team | | ---- | ----------------- | ------------------------------- | ---- | @@ -30,7 +30,7 @@ flowchart LR **Plugin owners** are Habilité scoped to one plugin (`aidd-context`, `aidd-dev`, …): they merge and triage for that plugin only. -## Roadmap voting +## 📊 Roadmap voting - **Public** reacts (👍 / upvote). This is a **signal**, not a counted vote; it promotes an item to a formal vote. @@ -41,18 +41,14 @@ flowchart LR - A poll runs **≥ 7 days**. Accepted items land on the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). -## Code decisions (merging) +## ✅ Code decisions (merging) -Merge authority is **Habilité only**. Default is **lazy consensus**: a Habilité -may merge if no other Habilité objects within 72h, there is ≥1 Habilité approval, -and CI passes. Any Habilité can block with a `request-changes` review (the -**quality veto**) until resolved. +- Merge authority is **Habilité only**. +- **Lazy consensus** (default): a Habilité may merge if no other Habilité objects within 72h, there is ≥1 Habilité approval, and CI passes. +- **Quality veto**: any Habilité can block with a `request-changes` review until resolved. +- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Habilité approve, none object. -Cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), -or licensing/governance changes need **explicit consensus**: ≥2 Habilité approve, -none object. - -## Promotion and inactivity +## 📈 Promotion and inactivity - **→ Certifié**: pass the AIDD certification → added to `certified`. - **→ Habilité**: a Habilité nominates a Certifié with a track record of merged, @@ -61,7 +57,7 @@ none object. - A Core Team / Habilité member inactive **6 months** may be moved to **emeritus** by a Habilité majority (keeps recognition, loses vote/merge until they return). -## Plugins, breaking changes, conflicts +## 🧩 Plugins, breaking changes, conflicts - **New plugin**: lands via PR following [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) (description on every skill, registered in @@ -76,21 +72,12 @@ none object. - **Conflict of interest**: a Habilité with a stake in a PR discloses it and is not the sole approver (a second Habilité approval becomes mandatory). -## Branch protection on `main` and `next` - -`main` is production: no direct push, no force-push, no deletion; every change is -a PR with ≥1 Habilité (CODEOWNERS) approval, passing checks (`lefthook -(framework-local checks)`, `Commitlint`), and resolved threads. Machine-readable -form: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once -the repo is public / on a paid plan). +## 🔒 Branch protection on `main` and `next` -`next` is the integration branch: PRs with ≥1 review and passing checks, no -direct push or deletion. The release bot bypasses to push the automated -back-merge, and the `admin` team may merge without a second review. Machine-readable form: -[`.github/rulesets/next.json`](.github/rulesets/next.json). The release flow is in -[`RELEASE.md`](RELEASE.md). +- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Habilité (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan). +- **`next`** (integration): PRs with ≥1 review and passing checks, no direct push or deletion. The release bot bypasses to push the automated back-merge; the `admin` team may merge without a second review. Rules: [`.github/rulesets/next.json`](.github/rulesets/next.json). Release flow: [`RELEASE.md`](RELEASE.md). -## Code of Conduct & amendments +## 📜 Code of Conduct & amendments -All interactions follow the [Code of Conduct](./CODE_OF_CONDUCT.md). Changes to -this document follow the explicit-consensus rule above. +- All interactions follow the [Code of Conduct](./CODE_OF_CONDUCT.md). +- Changes to this document follow the explicit-consensus rule above. diff --git a/README.md b/README.md index 139f7115..d3f3aef4 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ # AI-Driven Dev Framework -### A French framework for AI-Driven Developer to produce high code quality. +### A French framework for AI-Driven Developers to ship high-quality code.

7 plugins · 40 skills · 2 agents · MIT @@ -24,7 +24,7 @@ [![CI](https://github.com/ai-driven-dev/framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ai-driven-dev/framework/actions/workflows/ci.yml) [![Made in France](https://img.shields.io/badge/made%20in-France-0055A4?labelColor=EF4135)](https://www.ai-driven-dev.fr/) -

🗺️ Live roadmap — what's shipping Now / Next / Later

+

🗺️ Live roadmap

@@ -32,40 +32,31 @@ The **AI-Driven Dev Framework** is a marketplace — **skills, agents, commands, rules, prompts, templates, recipes…** — that helps you ship **high-quality features to production**. -> Orchestrate your SDLC (Software Development Life Cycle) at scale, the agentic engineering way. +> Orchestrate your SDLC (Software Development Life Cycle) at scale, the agentic-engineering way. -## 🧑‍💻 The AI-Driven Dev +## ✅ Prerequisites -Built by the [AI-Driven Dev](https://www.ai-driven-dev.fr/) community: 3 years of R&D, 500+ developers trained in English 🇬🇧 and French 🇫🇷, shipping production software with 100% AI-generated code. +- **An AI coding tool** — Claude Code (native), or Cursor / Copilot / Codex / OpenCode (see [Compatibility](#-compatibility)). +- **[Node](https://nodejs.org)** on your `PATH` — for the plugins that ship hooks ([what they do](docs/ARCHITECTURE.md#-bundled-hooks)). -- **[Join the Discord 🇫🇷](https://discord.gg/EWySJSpjWs)** — public [roadmap](./ROADMAP.md) decisions every Thursday morning. -- **Want to train your team?** [See the programme](https://www.ai-driven-dev.fr/entreprise). -- **AI is important to you?** [Join the ecosystem](https://www.ai-driven-dev.fr/ecosysteme). +## 🔌 Compatibility -## ✅ Compatibility - -> Primarily built on **Claude Code** (they set the standards), but compatibility with the other tools is ensured. - -| Tool | Status | -| --- | --- | -| **Claude Code** | ✅ Native · **recommended** | -| **GitHub Copilot** | ✅ Supported | -| **Codex** | ✅ Supported | -| **Cursor** | ✅ Supported | -| **OpenCode** | ✅ Supported | -| **Gemini** | 🚧 In progress | -| **Mistral** | 🚧 In progress | +| Tool | Status | Release dist | +| --- | --- | --- | +| **Claude Code** | ✅ Native · recommended | Marketplace | +| **Cursor** | ✅ Supported | Marketplace · Flat | +| **GitHub Copilot** | ✅ Supported | Marketplace · Flat | +| **Codex** | ✅ Supported | Marketplace · Flat | +| **OpenCode** | ✅ Supported | Flat | +| **Gemini · Mistral** | 🚧 In progress | — | -## 📦 Installation +Install steps per tool → [Other tools](#other-tools). -Two install formats, depending on your tool: +## 📦 Install -1. **Marketplace** *(recommended)* — register once, then install and update plugins on demand. Native in Claude Code; for Copilot and Codex, grab the `-marketplace-` archive and run `aidd marketplace add`. -2. **Flat** — unzip a `-flat-` archive straight into your project (it materializes `.cursor/`, `.opencode/`, …). For tools without marketplace support. +### Claude Code -All builds are attached to each [GitHub release](https://github.com/ai-driven-dev/framework/releases) → [latest release](https://github.com/ai-driven-dev/framework/releases/latest). - -**Claude Code** — register the marketplace and install the plugins (slash commands, not shell): +**In the session** (slash commands) ```text /plugin marketplace add ai-driven-dev/framework @@ -77,80 +68,134 @@ All builds are attached to each [GitHub release](https://github.com/ai-driven-de /plugin install aidd-orchestrator@aidd-framework ``` -**Other tools** — every release attaches a per-tool archive. Grab yours from the [latest release](https://github.com/ai-driven-dev/framework/releases/latest): +**Command line** (same, prefixed with `claude`) + +```bash +claude plugin marketplace add ai-driven-dev/framework +claude plugin install aidd-context@aidd-framework # then aidd-refine, aidd-dev, aidd-vcs, aidd-pm, aidd-orchestrator +``` + +Update anytime: `/plugin marketplace update aidd-framework`. + +### Other tools + +Same plugin names as Claude Code. + +Download your tool's bundle from the [latest release](https://github.com/ai-driven-dev/framework/releases/latest), then follow its steps:
-GitHub Copilot — marketplace +Cursor + +**Marketplace** + +1. Unzip the `cursor-marketplace` archive. +2. Copy the plugins, then reload (**Developer → Reload Window**): + +```bash +cp -r plugins/aidd-* ~/.cursor/plugins/local/ +``` + +**Flat** -1. Download [`aidd-framework-copilot-marketplace-.zip`](https://github.com/ai-driven-dev/framework/releases/latest) and unzip it. -2. Register the marketplace: - ```bash - aidd marketplace add aidd-framework ./aidd-framework-copilot-marketplace- - ``` -3. Install the plugins from the registered `aidd-framework` marketplace (same plugin names as Claude Code). +1. Unzip the `cursor-flat` archive into your project root → `.cursor/`. + +_All plans; team marketplaces need Teams/Enterprise. Also reads Claude format (`.claude/skills/`)._ + +[Docs](https://cursor.com/docs/plugins)
-Codex — marketplace +GitHub Copilot + +**Marketplace** + +1. Unzip the `copilot-marketplace` archive. +2. Run: + +```bash +copilot plugin marketplace add ./aidd-framework-copilot-marketplace- +copilot plugin install aidd-context@aidd-framework # per plugin +``` -1. Download [`aidd-framework-codex-marketplace-.zip`](https://github.com/ai-driven-dev/framework/releases/latest) and unzip it. -2. Register the marketplace: - ```bash - aidd marketplace add aidd-framework ./aidd-framework-codex-marketplace- - ``` -3. Install the plugins from the registered `aidd-framework` marketplace (same plugin names as Claude Code). +**Flat** + +1. Unzip the `copilot-flat` archive into your project root → `.github/`. + +_Also reads Claude format (`.claude/skills/`, `.claude/agents/`)._ + +[Docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing)
-Cursor — flat +Codex + +**Marketplace** + +1. Unzip the `codex-marketplace` archive. +2. Run: + +```bash +codex plugin marketplace add ./aidd-framework-codex-marketplace- +codex plugin add aidd-context@aidd-framework # per plugin +``` -1. Download [`aidd-framework-cursor-flat-.zip`](https://github.com/ai-driven-dev/framework/releases/latest). -2. Unzip it into your project root — it materializes `.cursor/`, ready to use. +**Flat** + +1. Unzip the `codex-flat` archive into your project root → `.codex/`. + +[Docs](https://developers.openai.com/codex/plugins/build)
-OpenCode — flat +OpenCode — Flat only + +1. Unzip the `opencode-flat` archive into your project root → `.opencode/`. -1. Download [`aidd-framework-opencode-flat-.zip`](https://github.com/ai-driven-dev/framework/releases/latest). -2. Unzip it into your project root — it materializes `.opencode/`, ready to use. +[Docs](https://opencode.ai/docs/config/)
## 🚀 Quick start -1. **Onboard** — one command inspects your project and guides you: - ```text - /aidd-context:00-onboard - ``` -2. **Run the flow** — take a feature from idea to a tested, shipped PR: +Three ways in — pick one: + +| Start with | Command | When | +| --- | --- | --- | +| 🧭 **Guided onboarding** | `/aidd-context:00-onboard` | First time, or unsure what to run — it inspects the project and routes you. | +| 🧠 **Project memory** | `/aidd-context:02-project-memory` | Build the project memory bank by hand. | +| ⚙️ **Feature flow** | `/aidd-dev:00-sdlc` | Ship a feature end to end (plan → implement → review → PR). | + +The full loop, and how onboarding sets it up: ```mermaid flowchart TD - Idea(["💡 'Add a dark-mode toggle'"]) - Onboard["/aidd-context:00-onboard
understand the project"] - Brainstorm["/aidd-refine:01-brainstorm
clarify the request"] - Plan["/aidd-dev:01-plan
draft the technical plan"] - Implement["/aidd-dev:02-implement
write the code"] - Review["/aidd-dev:05-review
review the diff"] - Commit["/aidd-vcs:01-commit
atomic commit"] - PR(["✅ /aidd-vcs:02-pull-request
tested · shipped"]) - - Idea --> Onboard --> Brainstorm --> Plan --> Implement --> Review --> Commit --> PR - - classDef start fill:#D97757,stroke:#9c4f37,color:#fff; + Onboard(["/aidd-context:00-onboard
inspect · guide"]) + + subgraph setup["① Set up — once"] + Memory["project memory
durable project context"] + end + + subgraph loop["② Per feature — repeat"] + direction LR + B["brainstorm"] --> P["plan"] --> I["implement"] --> R["review"] --> C["commit"] --> PR(["✅ PR"]) + end + + Onboard --> Memory --> B + + classDef hub fill:#D97757,stroke:#9c4f37,color:#fff; classDef done fill:#2ea043,stroke:#1a7f37,color:#fff; - class Idea start; + class Onboard hub; class PR done; ``` -> Prefer one command for the whole loop? `/aidd-dev:00-sdlc` runs plan → implement → review → ship. +> 🍳 **More flows** → the [recipes](recipes/): [start a project](recipes/start-a-project.md), [ship a feature](recipes/ship-a-feature.md), and more. ## 🧩 Plugins -Seven plugins covering the whole SDLC — **install all of them**; they're designed to work together. (`aidd-ui` is 🚧 **alpha — not ready for use**, off the curated install path.) +Seven plugins covering the whole SDLC — **install all of them**; they work together. (`aidd-ui` is 🚧 **alpha**, off the curated path.) @@ -160,7 +205,7 @@ Seven plugins covering the whole SDLC — **install all of them**; they're desig `13 skills` · stable -Project init, architecture, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), diagrams, learning, exploration. +Project init, memory bank, context-artifact generation, diagrams, learning, exploration. @@ -198,16 +243,16 @@ Ticket info, user stories, PRD, spec drafting. `5 skills` · stable -Meta-cognition: brainstorm, challenge, condense, shadow-areas, fact-check. +Brainstorm, challenge, condense, shadow-areas, fact-check. @@ -216,59 +261,53 @@ Label an issue, get a PR; re-label, get the review applied. ### 🎨 [aidd-ui](plugins/aidd-ui/README.md) 🚧 -`1 skill` · **alpha — not ready** +`1 skill` · **alpha** -UI and UX: design, review, and improve frontend interfaces. ⚠️ Alpha (`0.1.0-alpha.0`), smoke-test only — do not rely on it yet. +UI / UX design — smoke-test only, not ready for use.
@@ -169,7 +214,7 @@ Project init, architecture, generation of Claude Code context artifacts (skills, `11 skills` · stable -SDLC loop: sdlc, plan, implement, assert, audit, review, test, refactor, debug, for-sure. +SDLC loop: plan, implement, assert, audit, review, test, refactor, debug. @@ -178,7 +223,7 @@ SDLC loop: sdlc, plan, implement, assert, audit, review, test, refactor, debug, `5 skills` · stable -Commits, pull / merge requests, release tags, issue creation. +Repo init, commits, pull / merge requests, release tags, issues.
### 🎼 [aidd-orchestrator](plugins/aidd-orchestrator/README.md) -`1 skill` · stable (`async-dev`) +`1 skill` · stable -Label an issue, get a PR; re-label, get the review applied. +Async dev: label an issue → get a PR.
-## 📖 Recipes +Full catalog → [`CATALOG.md`](docs/CATALOG.md). -Task-oriented how-to sheets. **[Browse all recipes →](recipes/)** +## 📚 Learn more -| Recipe | What you'll do | +| | | | --- | --- | -| [MCP installations](recipes/mcp-installation.md) | Choose CLI vs MCP, and wire up the recommended servers (GitHub, Atlassian, Figma, Notion…) | - -## 🤝 Contributing - -> ⭐ **Free & open-source (MIT), built by the AIDD community.** If AIDD saves you time, [**a star**](https://github.com/ai-driven-dev/framework/stargazers) genuinely helps the project grow and helps other developers find it. +| 🍳 **[Recipes](recipes/)** | How-to sheets: [start a project](recipes/start-a-project.md), [ship a feature](recipes/ship-a-feature.md), [MCP installations](recipes/mcp-installation.md). | +| 🏛️ **[Architecture](docs/ARCHITECTURE.md)** | How the framework composes: plugins, skills, hooks, agents. | +| 🧩 **[Create a plugin](docs/CREATE_PLUGIN.md)** | Build and publish your own. | +| 🛒 **[Marketplace](docs/MARKETPLACE.md)** | Install scopes, versioning, LLM tiers. | +| ❓ **[FAQ & Troubleshooting](docs/FAQ.md)** · **[Glossary](docs/GLOSSARY.md)** | Common questions, fixes, and terms. | -> Actively maintained — the [roadmap](https://github.com/orgs/ai-driven-dev/projects/8) is public; help shape what comes after. +## 🔒 Trust and safety -Got an idea or hit a bug? **[Open an issue](https://github.com/ai-driven-dev/framework/issues)** or **[start a discussion](https://github.com/ai-driven-dev/framework/discussions)**. For everything else, **[join the Discord](https://discord.gg/EWySJSpjWs)**. +Plugins act with **your permissions**, and some run **Node hooks automatically** at session events ([the list](docs/ARCHITECTURE.md#-bundled-hooks)). -> **Note** — code (pull-request) rights on this repo are reserved for **certified Core Team members** ([`GOVERNANCE.md`](./GOVERNANCE.md)). Everyone else can open issues, join discussions, and shape the roadmap. +Before installing any plugin, skim its `README`, `hooks/`, and `.mcp.json`. Found a vulnerability? Report it privately → [`SECURITY.md`](SECURITY.md). -## 🔒 Trust & safety +## 🧑‍💻 The AI-Driven Dev -Plugins can run commands, edit files, and call external services on your behalf. Before installing any plugin from any marketplace, including this one: read its `README` and `SKILL.md`, inspect its actions, and check the permissions in its hooks and MCP servers. Spot a vulnerability? Report it privately via [`SECURITY.md`](./SECURITY.md). +Built by the [AI-Driven Dev](https://www.ai-driven-dev.fr/) community: 3 years of R&D, 500+ developers trained in English 🇬🇧 and French 🇫🇷, shipping production software with 100% AI-generated code. -## 📚 Documentation +- **[Join the Discord 🇫🇷](https://discord.gg/EWySJSpjWs)** — public [roadmap](ROADMAP.md) decisions every Thursday morning. +- **Want to train your team?** [See the programme](https://www.ai-driven-dev.fr/entreprise). +- **AI is important to you?** [Join the ecosystem](https://www.ai-driven-dev.fr/ecosysteme). -| Doc | What's inside | -| --- | --- | -| [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) | How the framework is structured | -| [`MARKETPLACE.md`](docs/MARKETPLACE.md) | Marketplaces, install scopes, versioning, LLM tiers | -| [`CATALOG.md`](docs/CATALOG.md) | Full skills catalog | -| [`CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) | Build your own plugin | -| [`FAQ.md`](docs/FAQ.md) | Frequently asked questions | -| [`TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) | Install issues, load problems, limits | -| [`GLOSSARY.md`](docs/GLOSSARY.md) | Terms used across the framework | -| [`MAINTAINERS.md`](docs/MAINTAINERS.md) | Maintainer guide | +## 🤝 Contributing -## 📈 Star History +Free and open-source (MIT). If it saves you time, [a ⭐](https://github.com/ai-driven-dev/framework/stargazers) helps others find it. -Star History Chart +- **Idea or bug?** [Open an issue](https://github.com/ai-driven-dev/framework/issues) or [start a discussion](https://github.com/ai-driven-dev/framework/discussions). +- **Contribute code** → [`CONTRIBUTING.md`](CONTRIBUTING.md). ---
-Made with care in France 🇫🇷 by the AIDD community +Star History Chart -← [Back to the AIDD organisation](https://github.com/ai-driven-dev) +Made with care in France 🇫🇷 · ← [AIDD organisation](https://github.com/ai-driven-dev)
diff --git a/RELEASE.md b/RELEASE.md index 8eb93edc..308e7eda 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,29 +1,22 @@ # Release -How the AI-Driven Dev Framework ships, and what to follow when you open a -change. Weekly rolling releases, with a fast lane for urgent fixes. +How the AI-Driven Dev Framework ships, and what to follow when you open a change. Weekly rolling releases, with a fast lane for urgent fixes. -For branch naming, commit format, and the release tooling, see [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md). +- Branch naming, commit format, release tooling → [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md). +- Who may merge and release → [`GOVERNANCE.md`](GOVERNANCE.md). -For who may merge and release, see [`GOVERNANCE.md`](GOVERNANCE.md). +## 🧭 Principle -## Principle +- `main` is production. The marketplace tracks it, so users only ever get released, versioned code. +- `next` is integration. The week's work batches here, and ships in one weekly release. +- A release happens only when there is work, and is cut automatically by release-please. +- A `hotfix/*` skips `next`: it branches from `main` and ships its own release out of cycle, for urgent production fixes. -- `main` is production. The marketplace tracks it, so users only ever get - released, versioned code. -- `next` is integration. The week's work batches here, and ships in one weekly - release. -- A release happens only when there is work, and is cut automatically by - release-please. -- A `hotfix/*` skips `next`: it branches from `main` and ships its own release - out of cycle, for urgent production fixes. +## 🔀 Where your change goes -## Where your change goes - -Almost everything flows through `next` and ships in the weekly release. Only an -urgent production fix takes the fast lane straight to `main`. The branch prefix -decides the target; the canonical prefix → target table lives in -[`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types). +- Almost everything flows through `next` and ships in the weekly release. +- Only an urgent production fix takes the fast lane straight to `main`. +- The branch prefix decides the target; the canonical prefix → target table lives in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types). ```mermaid flowchart LR @@ -34,10 +27,9 @@ flowchart LR hotfix["hotfix/*"] -->|PR| main ``` -Two merges reach `main`: the weekly promotion PR from `next`, then the -auto-merged Release PR that release-please raises. +Two merges reach `main`: the weekly promotion PR from `next`, then the auto-merged Release PR that release-please raises. -## What your commit produces +## 🏷️ What your commit produces The commit type drives the changelog section it lands under. @@ -51,25 +43,21 @@ The commit type drives the changelog section it lands under. | `chore` | Miscellaneous | | `revert` | Reverts | -The version bump is release-please's call: `feat` → minor, `fix` → patch, a `!` -suffix or `BREAKING CHANGE` footer → major. The other types ride along in a -release triggered by a `feat` or `fix`. +The version bump is release-please's call: `feat` → minor, `fix` → patch, a `!` suffix or `BREAKING CHANGE` footer → major. The other types ride along in a release triggered by a `feat` or `fix`. -## The two rules that keep it safe +## 🛟 The two rules that keep it safe -- **The Release PR is auto-merged.** Otherwise `main` briefly holds merged but - unversioned code, and a new user installing in that window picks it up. -- **The `main` → `next` back-merge is automatic.** Otherwise the version - manifest and the changelog on `next` drift from `main`. +- **The Release PR is auto-merged.** Otherwise `main` briefly holds merged but unversioned code, and a new user installing in that window picks it up. +- **The `main` → `next` back-merge is automatic.** Otherwise the version manifest and the changelog on `next` drift from `main`. -## Weekly release, step by step +## 🗓️ Weekly release, step by step 1. Open the promotion PR `next` → `main` once the week's work is ready. 2. release-please opens a Release PR on `main`; it is auto-merged. 3. Tags and version bumps are created; release artifacts are attached. 4. `main` is back-merged into `next` automatically. -## Hotfix +## 🚑 Hotfix 1. Branch `hotfix/*` from `main`, fix, PR back to `main`. 2. release-please cuts a dedicated patch release. diff --git a/ROADMAP.md b/ROADMAP.md index a4d19658..c27c8a52 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -4,7 +4,7 @@ The live roadmap - **Now / Next / Later** with per-item status across the framew ## How to influence -Priority is set by a community vote - full mechanism (who votes, weighting, polls) in [`GOVERNANCE.md`](./GOVERNANCE.md#roadmap-voting). To influence it: +Priority is set by a community vote - full mechanism (who votes, weighting, polls) in [`GOVERNANCE.md`](./GOVERNANCE.md#-roadmap-voting). To influence it: - Open a `feat:` issue or an idea in [GitHub Discussions](https://github.com/ai-driven-dev/framework/discussions), and 👍 / upvote what you want - the signal that promotes an item to a vote. - Discuss on [Discord](https://discord.gg/EWySJSpjWs). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 709cda3c..b355fc57 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,8 +1,8 @@ -# Architecture +# 🏛️ Architecture How the AI-Driven Dev Framework composes inside Claude Code. -## High-level +## 🗺️ High-level ```mermaid --- @@ -25,6 +25,7 @@ flowchart TB Pm["aidd-pm"] Orchestrator["aidd-orchestrator"] Refine["aidd-refine"] + Ui["aidd-ui 🚧"] end subgraph SkillUnit["A plugin may ship (Claude Code surfaces)"] @@ -45,11 +46,12 @@ flowchart TB Pm --> SkillUnit Orchestrator --> SkillUnit Refine --> SkillUnit + Ui --> SkillUnit Editor -->|"/plugin install"| Plugins Editor -->|invokes| Skills ``` -## Anatomy of a plugin +## 🧩 Anatomy of a plugin Every plugin under `plugins//` follows the same shape: @@ -74,11 +76,25 @@ plugins// └── .mcp.json # MCP server configuration (optional) ``` -A plugin bundles **any subset** of the Claude Code surfaces (skills, agents, commands, hooks, rules, MCP servers); only `skills/` and the manifest are universal. Browse the [plugins](../plugins/) to see which surfaces each one ships. +A plugin bundles **any subset** of the Claude Code surfaces (skills, agents, commands, hooks, rules, MCP servers); only `skills/` and the manifest are universal. Today the bundled plugins use skills, agents, and hooks — commands, rules, and MCP servers are supported but not yet shipped by any. Browse the [plugins](../plugins/) to see which surfaces each one ships. -The `plugin.json` is validated against [`claude-code-plugin-manifest`](https://www.schemastore.org/claude-code-plugin-manifest.json) by the `lefthook` pre-commit hook (when the JSON-schema validator, `pipx`/`check-jsonschema`, is available); the same hook validates `marketplace.json` against [`claude-code-marketplace`](https://www.schemastore.org/claude-code-marketplace.json). The `validate` workflow re-runs the hooks on every push and PR. +Validation: -## Plugin concerns and layers +- `plugin.json` against [`claude-code-plugin-manifest`](https://www.schemastore.org/claude-code-plugin-manifest.json). +- `marketplace.json` against [`claude-code-marketplace`](https://www.schemastore.org/claude-code-marketplace.json). + +Both run in the `lefthook` pre-commit hook (when the validator `pipx`/`check-jsonschema` is available). The `validate` workflow re-runs the hooks on every push and PR. + +## 🪝 Bundled hooks + +Two plugins ship Claude Code hooks (declared in `plugins//hooks/hooks.json`). Both run Node, so users need `node` on their `PATH`: + +| Plugin | Event | Runs | Purpose | +| -------------- | ----------------- | ------------------------- | ------------------------------------------------------------- | +| `aidd-context` | `SessionStart` | `hooks/update_memory.js` | Refresh the project memory block in the AI context files | +| `aidd-refine` | `UserPromptSubmit`| `hooks/condense-stats.js` | Report token savings while condensed output mode is on | + +## 🧠 Plugin concerns and layers Every capability lives in exactly one plugin, chosen by **concern**. This taxonomy decides placement; it is only implicit in each `plugin.json`, so it is canonical here. @@ -90,14 +106,17 @@ Every capability lives in exactly one plugin, chosen by **concern**. This taxono | `aidd-dev` | Code transformation | Execution | | `aidd-vcs` | Version control | External | | `aidd-orchestrator` | Orchestration | Coordination | +| `aidd-ui` 🚧 | UI/UX design | Execution | + +`aidd-ui` ships but is **alpha** (smoke-test only, off the curated install path); it is listed here for completeness. Three rules follow: - **Knowledge vs execution is a firewall.** Knowledge plugins produce artifacts you *read* (docs, plans, memory) and never write or run application source - `aidd-context`'s bootstrap deliberately creates no `package.json` or source files. Real code belongs to `aidd-dev` or an orchestrator's own setup actions. - **Concern decides placement, not existence.** A missing capability goes in the plugin whose concern owns it, then the caller delegates. Never reimplement it in the calling plugin because the right home lacks it today. -- **Orchestration = sequencing across multiple concerns** with little domain logic. Any skill may delegate a sub-step ([Cross-plugin orthogonality](#cross-plugin-orthogonality)); doing so once does not make it an orchestrator. The orchestrator owns only glue and delegates the depth, handing off through a seam artifact (e.g. an `INSTALL.md` one plugin produces and another consumes). +- **Orchestration = sequencing across multiple concerns** with little domain logic. Any skill may delegate a sub-step ([Cross-plugin orthogonality](#-cross-plugin-orthogonality)); doing so once does not make it an orchestrator. The orchestrator owns only glue and delegates the depth, handing off through a seam artifact (e.g. an `INSTALL.md` one plugin produces and another consumes). -## Skills are routers +## 🔀 Skills are routers A skill's `SKILL.md` is a manifest plus an actions table. Claude Code loads the SKILL.md when the skill is invoked; the body decides which action(s) to run. @@ -124,7 +143,7 @@ flowchart LR Each action is a self-contained markdown file with inputs, outputs, depends-on, process steps, and a test checklist. Actions can call other skills via the `Skill` tool, so a skill discovers a capability it needs at runtime (by matching skill descriptions, never by hardcoded plugin name) and delegates to it. -## Skills and agents +## 🤖 Skills and agents - A **skill** is a caller-agnostic recipe; it runs in the context of whoever invokes it. - An **agent** is an isolated executor; it runs in its own context and returns only a result. @@ -138,13 +157,13 @@ Composition rules: - An agent invokes only the recipe skills it declares under `# Skills you may invoke`, never an orchestrator skill, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. - An agent never delegates flow work to another agent and never invokes an orchestrator skill. It may spawn a read-only recon helper (for example `Explore`) that mutates nothing and spawns nothing. So the write path stays two layers deep and delegation can never cycle. -## Cross-plugin orthogonality +## 🔗 Cross-plugin orthogonality -Plugins do not reference each other by name. When skill A needs a capability owned by skill B, it discovers a candidate at runtime through description matching. This rule keeps the marketplace forkable, the plugins swappable, and the docs maintainable. +Plugins never reference each other by name — **orchestrators included**. When skill A needs a capability skill B owns, it discovers a candidate at runtime through description matching, never a hardcoded `aidd-:…` address. This keeps the marketplace forkable, the plugins swappable, and the docs maintainable. -The rule is enforced both socially (PR template checklist) and mechanically (lefthook hooks could be extended to grep for cross-plugin literal references). +The rule is social (PR template checklist), not yet mechanically enforced — a lefthook grep for cross-plugin literals would catch violations (an orchestrator hardcoding a sibling skill name still slips through today). -## See also +## 🔎 See also - [`CREATE_PLUGIN.md`](CREATE_PLUGIN.md) - build and publish your own plugin. - [`GLOSSARY.md`](GLOSSARY.md) - terminology used across the framework. diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 1e7b210e..3788ca9b 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -2,22 +2,23 @@ The exhaustive list of AIDD plugins, skills, and actions. Skills are invoked through your AI tool by their `plugin:NN-slug` name (slash command, MCP, or natural-language trigger). Actions are the internal steps a skill runs; you do not call them directly. -- [aidd-context](#aidd-context) - knowledge production -- [aidd-dev](#aidd-dev) - code transformation -- [aidd-pm](#aidd-pm) - product management -- [aidd-refine](#aidd-refine) - meta-cognition -- [aidd-vcs](#aidd-vcs) - version control workflows -- [aidd-orchestrator](#aidd-orchestrator) - async orchestration (optional) +- [aidd-context](#-aidd-context) - knowledge production +- [aidd-dev](#-aidd-dev) - code transformation +- [aidd-pm](#-aidd-pm) - product management +- [aidd-refine](#-aidd-refine) - meta-cognition +- [aidd-vcs](#-aidd-vcs) - version control workflows +- [aidd-orchestrator](#-aidd-orchestrator) - async orchestration (optional) +- [aidd-ui](#-aidd-ui) - UI / UX (🚧 alpha, not ready) --- -## aidd-context +## 🧭 aidd-context Bootstrap, project init, context-artifact generation, diagrams, learning, and exploration. | Skill | Role | Actions | | ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `00-onboard` | Detect project state and open a hub of project actions | `01-detect-state`, `02-recommend-next`, `03-execute-or-handoff` | +| `00-onboard` | Scan the project into a diagnostic of what's set up and missing, then run the recommended next commands | `01-scan`, `02-report`, `03-run` | | `01-bootstrap` | Imagine and validate a new SaaS architecture, output an `INSTALL.md` | `01-gather-needs`, `02-propose-candidates`, `03-audit-candidates`, `04-pick-and-design`, `05-write-install-md` | | `02-project-memory` | Initialize or refresh the memory bank and AI context files | `01-init-context-file`, `02-scaffold-docs`, `03-generate-memory`, `04-review-memory`, `05-sync-memory` | | `03-context-generate` | Router that dispatches an artifact-generation request to the dedicated generator below | delegates to `04`–`08` (and plugins / marketplaces) | @@ -31,7 +32,7 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex | `11-explore` | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill` | | `12-cook` | Manage the project's recipes/ how-to sheets: list, create, or update one | `01-list`, `02-upsert` | -## aidd-dev +## 💻 aidd-dev The development SDLC: plan, implement, assert, audit, review, test, refactor, debug, for-sure, todo. @@ -49,7 +50,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | `09-for-sure` | Iterative loop that retries until a success condition is met | `01-init-tracking`, `02-auto-accept`, `03-autonomous-loop` | | `10-todo` | Split the prompt into independent todos, run one implementer agent per todo in parallel | `01-todo` | -## aidd-pm +## 📋 aidd-pm Product management: ticket retrieval, user stories, PRD, spec. @@ -60,7 +61,7 @@ Product management: ticket retrieval, user stories, PRD, spec. | `03-prd` | Generate a structured Product Requirements Document | `01-prd` | | `04-spec` | Generate or refine a normalized project spec | `01-build`, `02-refine` | -## aidd-refine +## 🪞 aidd-refine Meta-cognition: brainstorm, challenge, condense, blind-spot scan, fact-check. @@ -72,22 +73,30 @@ Meta-cognition: brainstorm, challenge, condense, blind-spot scan, fact-check. | `04-shadow-areas` | Scan a markdown artifact for blind spots | `01-detect`, `02-render-report`, `03-diff` | | `05-fact-check` | Verify factual claims against sources and cite them | `01-identify-claims`, `02-verify`, `03-report` | -## aidd-vcs +## 🌿 aidd-vcs -Version-control workflows: commit, pull/merge request, release tag, issue. +Version-control workflows: repo init, commit, pull/merge request, release tag, issue. -| Skill | Role | Actions | -| ---------------------- | --------------------------------------------------- | ----------------------- | -| `01-commit` | Create an atomic conventional commit | `01-commit` | -| `02-pull-request` | Create a draft pull or merge request | `01-pull-request` | -| `03-release-tag` | Cut a semver release with annotated tag and notes | `01-release-tag` | -| `04-issue-create` | Create an issue in the configured ticketing tool | `01-issue-create` | -| `05-pull-request-list` | List the open pull or merge requests | `01-pull-request-list` | +| Skill | Role | Actions | +| ----------------- | ------------------------------------------------------------------------------- | ----------------------- | +| `00-repo-init` | Initialize a repo: git init, default branch, bootstrap commit, optional remote | `01-init`, `02-publish` | +| `01-commit` | Create an atomic conventional commit | `01-commit` | +| `02-pull-request` | Create a draft pull or merge request | `01-pull-request` | +| `03-release-tag` | Cut a semver release with annotated tag and notes | `01-release-tag` | +| `04-issue-create` | Create an issue in the configured ticketing tool | `01-issue-create` | -## aidd-orchestrator +## 🎼 aidd-orchestrator Optional. Runs the SDLC asynchronously on labeled issues (webhook or cron). Most projects do not need it. | Skill | Role | Sub-flows | | ---------------- | ----------------------------------------------------- | ------------------------- | | `00-async-dev` | Single entry point for the async-dev pipeline | `setup`, `run`, `review` | + +## 🎨 aidd-ui + +🚧 **Alpha — not ready for use.** UI / UX: design, review, and improve frontend interfaces. Currently a smoke-test only. + +| Skill | Role | Actions | +| ---------- | ----------------------------------------- | ---------- | +| `01-hello` | Smoke-test that confirms the plugin loads | `01-greet` | diff --git a/docs/CREATE_PLUGIN.md b/docs/CREATE_PLUGIN.md index c442692e..d2d1670e 100644 --- a/docs/CREATE_PLUGIN.md +++ b/docs/CREATE_PLUGIN.md @@ -1,170 +1,38 @@ -# Build your own plugin +# 🧩 Build your own plugin -This guide walks through building a new plugin for the AI-Driven Dev marketplace, from a blank directory to a merged PR. +Create a new plugin for the AI-Driven Dev marketplace. This is a lean reference — the plugin **anatomy, surfaces, and rules** live in [`ARCHITECTURE.md`](ARCHITECTURE.md); the **contribution flow** in [`../CONTRIBUTING.md`](../CONTRIBUTING.md). -For broader OSS contribution rules (commit scopes, release flow), see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). For the framework's architecture, see [`ARCHITECTURE.md`](ARCHITECTURE.md). - -## Adding a skill to an existing plugin - -Most contributions add a *skill* to an existing plugin, not a new plugin. Decide two things first: - -- **Which plugin** - the owning concern decides; see the [concern taxonomy](ARCHITECTURE.md#plugin-concerns-and-layers). A capability owned by another concern goes in that plugin and you delegate to it. A skill that sequences across several concerns goes in `aidd-orchestrator`. -- **Which number** - `-` encodes the plugin's logical pipeline order, not a next-free counter. Inserting mid-flow means renumbering downstream folders, their `skills[]` entries, and every `:-name` invocation token - so weigh appending against inserting. - -The rest of this guide applies to the skill directory; skip the plugin-registration steps (the plugin already exists - you only edit its `plugin.json` `skills[]`). - -## Prerequisites - -The same toolchain as any framework contribution: - -- Node 20+, pnpm, jq, python3, pipx (`gh` CLI optional). See `Development setup` in [`../CONTRIBUTING.md`](../CONTRIBUTING.md). -- A clear, scannable use case the plugin solves (one or two sentences). - -## Step 1 - decide what the plugin does - -A good plugin in this marketplace is: - -- **Scoped to one phase or one concern.** "Generate user stories", "audit a codebase for tech debt", "rename a Claude Code prompt safely". If you can't say it in one sentence, split it. -- **Composable with siblings.** Avoid duplicating skills already in `aidd-context`, `aidd-dev`, `aidd-vcs`, `aidd-pm`, `aidd-orchestrator`, or `aidd-refine`. Discovery-by-description means your plugin can pull on theirs at runtime. -- **Independent of specific other plugins.** Never reference a sibling plugin by name in skill descriptions or READMEs. The discovery rule keeps the marketplace forkable. - -## Step 2 - scaffold the directory - -Pick a plugin name (lowercase, hyphenated, prefixed with `aidd-`). For this guide, use `aidd-example`. - -``` -plugins/aidd-example/ -├── .claude-plugin/ -│ └── plugin.json -├── README.md -├── CATALOG.md # per-plugin index (auto-generated) -├── skills/ -│ └── 01-hello/ -│ ├── SKILL.md -│ └── actions/ -│ └── 01-greet.md -├── agents/ # optional -├── commands/ # optional -├── hooks/hooks.json # optional -├── rules/ # optional -└── .mcp.json # optional (MCP servers) -``` - -A plugin can bundle any of the Claude Code surfaces above; only the manifest and `skills/` are required. See [`ARCHITECTURE.md`](ARCHITECTURE.md) for the surface model and real examples. - -### `plugin.json` - -```json -{ - "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", - "name": "aidd-example", - "version": "0.1.0", - "description": "One-sentence summary of what the plugin does. Use when the user says ... Do NOT use for ...", - "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, - "skills": ["./skills/01-hello"], - "keywords": ["example"], - "repository": "https://github.com/ai-driven-dev/framework", - "homepage": "https://ai-driven.dev", - "license": "MIT" -} +```mermaid +flowchart LR + Scaffold["🏗️ Scaffold plugin dir"] --> Register["📝 Register in marketplace.json + release config"] --> Test["🧪 Try locally"] --> PR["🔀 PR + review"] --> Release["🚀 release-please tags & publishes"] ``` -The `skills` array registers each skill directory - a skill that is not listed will not load. The pre-commit hook validates this file against the Claude Code plugin manifest schema; run `pnpm exec lefthook run pre-commit` to confirm. +> Adding a *skill* to an existing plugin? Generate it with `/aidd-context:03-context-generate`, then just edit that plugin's `plugin.json` `skills[]` — skip the registration below. -### `README.md` (plugin-level) +## 🏗️ Scaffold -Follow the sibling pattern: one-paragraph description, a `> Status: experimental.` line, a one-line Quick start pointer to your first skill, and a Skills table with one row per skill. See `plugins/aidd-refine/README.md` for a minimal example. +Pick a name (lowercase, `aidd-`). For the directory shape, `plugin.json`, and `SKILL.md`/action format, follow [Anatomy of a plugin](ARCHITECTURE.md#-anatomy-of-a-plugin). Minimum: `.claude-plugin/plugin.json` + `skills/-/` (with `SKILL.md` + `actions/`). -### `skills/01-hello/SKILL.md` +## 📝 Register -```markdown ---- -name: 01-hello -description: One-sentence summary. Use when ... Do NOT use for ... ---- +- **Marketplace** — append an entry to `.claude-plugin/marketplace.json`: `name`, `source` (required, `./plugins/aidd-`), `strict: true`, `recommended: false` (keeps it off the curated install path until it stabilises). +- **Release** — add the package to `release-please-config.json` `packages` **and** `.release-please-manifest.json`, or it never versions. -## Available actions +## 🧪 Try locally -| ID | Name | Purpose | -| --- | ----- | ---------------------------------------- | -| 01 | greet | Greet the user and confirm the skill works. | - -## Default flow - -Run action `01-greet` and return its message. +```text +/plugin marketplace add . +/plugin install aidd-@aidd-framework ``` -### `skills/01-hello/actions/01-greet.md` - -```markdown -# 01 - greet - -Greets the caller. - -## Inputs - -- none - -## Outputs - -- a short greeting printed in the chat - -## Process - -1. Print "Hello from aidd-example." -``` - -## Step 3 - register the plugin - -**a. Marketplace manifest** - append an entry to `.claude-plugin/marketplace.json`: - -```json -{ - "name": "aidd-example", - "version": "0.1.0", - "source": "./plugins/aidd-example", - "description": "One-sentence summary.", - "strict": true, - "recommended": false -} -``` - -`source` is required (without it the plugin won't resolve); `recommended: false` keeps it off the curated install path until it stabilises. The hook validates `marketplace.json` against the marketplace schema on commit. - -**b. Release config** - so `release-please` versions the plugin, add it to both: - -- `release-please-config.json` → `packages` (with `package-name` + the `plugin.json` `extra-files` entry, copy a sibling block). -- `.release-please-manifest.json` → `"plugins/aidd-example": "0.1.0"`. - -Skip this and the plugin will never get a release. - -## Step 4 - try it locally - -``` -/plugin marketplace add . # add the local working tree as a marketplace -/plugin install aidd-example@aidd-framework -Use skill aidd-example:01-hello -``` - -When you change SKILL.md or actions, run `/reload-plugins` in the same Claude Code session. - -## Step 5 - document, test, ship - -- Run `pnpm exec lefthook run pre-commit` to confirm JSON validity, YAML validity, and SKILL.md frontmatter checks pass. The pre-commit hook also regenerates your `plugins/aidd-example/CATALOG.md` automatically. -- Open a PR using the project template and pick the right commit scope (`feat(aidd-example): ...`). Listing the scope in `commitlint.config.cjs` is encouraged (an unlisted scope warns but does not block). - -## Step 6 - release +Run `/reload-plugins` after editing a skill. `pnpm exec lefthook run pre-commit` validates JSON/YAML/frontmatter and regenerates the plugin's `CATALOG.md`. -Once the PR merges to `main`, `release-please` will propose a release PR for your plugin tagged `aidd-example-v0.1.0` (per-plugin tags). Merge the release PR to publish. +## 🚀 Ship -## Style guardrails +Open a PR with the scope `feat(aidd-): …`. On merge, release-please tags `aidd--vX.Y.Z` and publishes. -- English only in committed prose. -- No em-dash characters in text (hyphen instead). -- No cross-plugin references in skill descriptions or READMEs. -- One sentence per `Use when ... / Do NOT use for ...` cue in `description` frontmatter. -- A skill's `name:` is the **folder slug** (`01-hello`), not a prefixed id. The **invocation** token is `:` with a single colon, e.g. `aidd-example:01-hello`. +**Guardrails:** English prose, hyphens not em-dashes, no cross-plugin references in descriptions/READMEs, one sentence per `Use when … / Do NOT use for …` cue, and a skill `name:` is the folder slug (`01-hello`) — the invocation token is `:`. -## Where to ask for help +## ❓ Help -Open a discussion on the AIDD Discord, or file a `feat:` issue here describing the plugin you want to add. +Open a discussion on the AIDD Discord, or file a `feat:` issue describing the plugin. diff --git a/docs/FAQ.md b/docs/FAQ.md index f3604ffd..766f8477 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,31 +1,44 @@ -# Frequently asked questions +# ❓ FAQ & Troubleshooting -Most "how do I…" answers live in the README; this page covers what isn't documented elsewhere and points to the rest. +Most "how do I…" answers live in the README; this page covers what isn't documented elsewhere, plus common install issues and the framework's limits. -## Install, update, other tools +## 📦 Install, update, other tools -- **Install / first run** → [Quick start](../README.md#quick-start). -- **Update plugins** → [Versioning and updates](../README.md#versioning-and-updates). -- **Private repo?** Yes - `/plugin marketplace add` just needs GitHub read access (via `gh auth login` or a PAT). -- **Cursor / Copilot / Codex / OpenCode?** This repo is the Claude Code distribution; for another tool, grab the per-release archive (`aidd-framework---.zip`) attached to each [release](https://github.com/ai-driven-dev/framework/releases/latest), unzip, and install per the [Another AI tool?](../README.md#another-ai-tool) table. +- **Install / first run** → [Quick start](../README.md#-quick-start). +- **Update plugins** → `/plugin marketplace update aidd-framework`, or see [Versioning & updates](MARKETPLACE.md#-versioning--updates). +- **Private repo?** Yes — `/plugin marketplace add` just needs GitHub read access (via `gh auth login` or a PAT). +- **Cursor / Copilot / Codex / OpenCode?** Each other tool installs via its own native mechanism (project files, local plugins, or a plugin command) from the [release](https://github.com/ai-driven-dev/framework/releases/latest) archives. Steps per tool → [Other tools](../README.md#other-tools). -## Cost and quotas +## 💸 Cost and quotas -**Does running plugins cost money?** The plugins are MIT-licensed and free; the Claude calls they make consume your Anthropic plan or API balance (per-invocation on a plan, per-token on an API key). +- **Does running plugins cost money?** The plugins are MIT-licensed and free; the Claude calls they make consume your Anthropic plan or API balance (per-invocation on a plan, per-token on an API key). +- **Disable a plugin without uninstalling?** Run `/plugin` and toggle it off in the **Installed** tab, or remove its entry from `.claude/settings.json` `enabledPlugins` (project scope) or `~/.claude/plugins/` (user scope). -**Disable a plugin without uninstalling?** Run `/plugin` and toggle it off in the **Installed** tab, or remove its entry from `.claude/settings.json` `enabledPlugins` (project scope) or `~/.claude/plugins/` (user scope). +## 🔒 Security -## Security - -- **What can a plugin do? Is it safe?** → [Trust and safety](../README.md#trust-and-safety) and [`SECURITY.md`](../SECURITY.md). Plugins run commands, edit files, and call services through your AI tool - inspect a plugin's `actions/`, `hooks/hooks.json`, and `.mcp.json` before installing. Claude Code asks before tool calls by default. +- **What can a plugin do? Is it safe?** → [Trust and safety](../README.md#-trust-and-safety) and [`SECURITY.md`](../SECURITY.md). Plugins run commands, edit files, and call services through your AI tool — inspect a plugin's `actions/`, `hooks/hooks.json`, and `.mcp.json` before installing. Claude Code asks before tool calls by default. - **Report a vulnerability** → [`SECURITY.md`](../SECURITY.md) (GitHub Security Advisories; never a public issue). -## Contributing +## 🤝 Contributing - **Write your own plugin** → [`CREATE_PLUGIN.md`](CREATE_PLUGIN.md). - **File a bug / request a feature** → [issue templates](https://github.com/ai-driven-dev/framework/issues/new/choose). -- **Community** → [Discord](https://discord.gg/EWySJSpjWs) · [website](https://www.ai-driven-dev.fr/) (more links in the [README](../README.md#what-is-the-aidd-framework)). +- **Community** → [Discord](https://discord.gg/EWySJSpjWs) · [website](https://www.ai-driven-dev.fr/) (more in the [README](../README.md#-the-ai-driven-dev)). + +## 🛠️ Troubleshooting + +- **Marketplace doesn't show my plugins after `/plugin marketplace add`** — refresh the cache: `/plugin marketplace update aidd-framework`, then open `/plugin` → **Discover**. +- **`/plugin install` says the plugin is unknown** — the marketplace name must match the `name` in this repo's `.claude-plugin/marketplace.json` (`aidd-framework`). Install with `/plugin install @aidd-framework`. +- **A private repo won't add as a marketplace** — `/plugin marketplace add` needs read access; authenticate with `gh auth login` or a PAT on the machine running your AI tool. +- **My new plugin's actions don't load** — run `/reload-plugins` in the same session, or restart the tool if a hook config changed. + +## 🚧 Limitations (what AIDD does not do) + +- **Not autonomous by default.** Skills run under human supervision; you drive each step. +- **Authored for Claude Code.** Other tools install via their native mechanism from the release archives ([Other tools](../README.md#other-tools)); public-marketplace publishing is on the way, native parity is a roadmap item. +- **Plugins assume their own context.** A skill that expects a git repo, a `package.json`, or a ticketing tool won't work without it — check the plugin's README. +- **No hosted service.** AIDD is prompt content you install into your own tool; there is no AIDD server, account, or telemetry. -## Troubleshooting +## 🆘 Still stuck? -Install failures (cache, name mismatch, reload) → [Troubleshooting](../README.md#troubleshooting). +Ask in [Discussions](https://github.com/ai-driven-dev/framework/discussions) or on [Discord](https://discord.gg/EWySJSpjWs). For a bug, open an [issue](https://github.com/ai-driven-dev/framework/issues/new/choose). See [`SUPPORT.md`](../.github/SUPPORT.md). diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 19a57100..f796ba86 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -2,47 +2,47 @@ Definitions for the terms the framework uses without re-explaining each time. One paragraph per term, ordered for reading top to bottom. -## Plugin +## 📦 Plugin -A `plugins//` directory installable from this marketplace into Claude Code. Each plugin owns one domain (context, dev, vcs, pm, orchestrator, refine), ships its own README, CATALOG, and skills, and may add any Claude Code surface: agents, commands, hooks, rules, and MCP servers (`.mcp.json`). Plugins version independently via `release-please`. +A `plugins//` directory installable from this marketplace into Claude Code. Each plugin owns one domain (context, dev, vcs, pm, orchestrator, refine, ui), ships its own README, CATALOG, and skills, and may add any Claude Code surface: agents, commands, hooks, rules, and MCP servers (`.mcp.json`). Plugins version independently via `release-please`. -## Marketplace +## 🏪 Marketplace The Git repository that publishes plugins. When you run `/plugin marketplace add /` Claude Code reads `.claude-plugin/marketplace.json` and offers the listed plugins for install. This repo (`aidd-framework`) is one such marketplace and versions independently of the plugins it ships. -## Memory bank +## 🧠 Memory bank Per-project context files under `aidd_docs/memory/` (architecture, conventions, decisions, and similar) that give the AI durable knowledge of your codebase. Built or refreshed by `aidd-context` (the onboard / project-memory skills) and read by skills that need project context. "Onboard builds the memory bank" in the Quick start refers to this. -## Skill +## 🛠️ Skill A self-contained workflow under `plugins//skills//`. Triggered by a user phrase, a slash command, or an explicit `Use skill ` invocation. A skill owns a `SKILL.md` router, one or more atomic actions, and optional `assets/` and `references/`. The `SKILL.md` `name:` is the folder slug (`00-onboard`); the invocation id is `:`, for example `aidd-context:00-onboard`. -## Router-based skill +## 🧭 Router-based skill The shape every skill in this framework follows. `SKILL.md` is a pure router: it lists triggers, declares `## Available actions`, and dispatches to one of them. It carries no business logic. The logic lives in the action files. This split keeps triggering predictable and keeps each step independently testable. -## Action +## ⚡ Action A single atomic step inside a skill, stored at `plugins//skills//actions/NN-name.md`. Each action file contains only `## Inputs`, `## Outputs`, `## Process`, `## Test`, and optionally `## Depends on`. Tests must be observable: a command to run, an artifact to check, or a side effect to verify. -## Agent +## 🤖 Agent A specialized AI persona under `plugins//agents/.md`. Agents are scoped (for example `executor`, `checker`) and spawned by an orchestrator when a step needs isolation in a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. -## Rule +## 📏 Rule A coding standard the AI loads automatically on relevant files. Rules live under each tool's rules directory (Claude Code uses `.claude/rules/`) and can be scoped via `paths:` glob frontmatter. Rules without `paths` apply to all files. Rules describe how to write code; skills describe what to do. -## Hook +## 🪝 Hook A program declared in `plugins//hooks/hooks.json` that Claude Code runs at lifecycle events (pre-commit, post-tool, etc.). Hooks are how a plugin triggers deterministic side effects rather than asking the model to remember. -## Bracket ID +## 🔖 Bracket ID The short identifier in each plugin's Skills table, for example `[2.1]` for `aidd-dev:01-plan`. The first digit is the plugin ordinal; the second is the skill position inside the plugin. Bracket IDs are the stable references the per-plugin Skills tables use to point at a skill without spelling out the full id. -## See also +## 🔗 See also - [`../README.md`](../README.md) for the marketplace overview, plugin catalog, and install flow. - [`ARCHITECTURE.md`](ARCHITECTURE.md) for the composition model and skill router pattern. diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index cd9f71e7..3bfff5a9 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -1,8 +1,11 @@ # Maintainers guide -How to operate this repository day to day. For **who** may do what and the decision rules, see [`GOVERNANCE.md`](../GOVERNANCE.md); for how contributors work, see [`CONTRIBUTING.md`](../CONTRIBUTING.md). This file is the **Habilité** (maintainer) playbook and does not restate those. +How to operate this repository day to day. This file is the **Habilité** (maintainer) playbook — it does not restate the others: -## The moving parts +- **Who** may do what + decision rules → [`GOVERNANCE.md`](../GOVERNANCE.md). +- **How contributors work** → [`CONTRIBUTING.md`](../CONTRIBUTING.md). + +## 🧩 The moving parts | Thing | Where | Note | | ----- | ----- | ---- | @@ -10,69 +13,38 @@ How to operate this repository day to day. For **who** may do what and the decis | Live backlog & roadmap | [Project board #8](https://github.com/orgs/ai-driven-dev/projects/8) | single source of truth | | Roles → access | GitHub teams `habilitated` / `certified` / `core-team` | mapped to the role ladder | | Branch protection | ruleset "main protection" + `.github/rulesets/main.json` | `main` is PR-only | -| Releases | release-please (`ci.yml`) + `release-please-config.json` | 7 packages, auto | +| Releases | release-please (`ci.yml`) + `release-please-config.json` | 8 packages (root + 7 plugins), auto | | Pre-commit checks | `lefthook.yml` + `scripts/` | json/yaml/schema/frontmatter/catalogs/counts | -## Daily - -- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority`; link under an epic (native sub-issues) if relevant. **Type** is the issue/PR label, not a board field (see [Project board layout](#project-board-project-8)). -- **Roadmap.** Priority is set by the community vote (mechanism in `GOVERNANCE.md`). Accepted items live on board #8 - keep `ROADMAP.md` as a pointer, do not maintain a second list. -- **Review PRs.** Every PR needs a Habilité (CODEOWNERS) approval; checks `lefthook`, `Commitlint` must pass; squash-merge. - -## Project board (Project 8) - -The board is a **view** of the same taxonomy the docs define — it never invents its own. Each property answers one question: **Type** = the label, **Priority** = how urgent, **Status** = where in the flow, **When** = the Timeline. Routing (`next` vs `main`) is *not* a board property — it derives from the branch prefix ([routing table](../aidd_docs/memory/vcs.md#types)). +## 📅 Daily -Apply this layout once (org-admin or board-write needed). Read field IDs first: +- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority`; link under an epic (native sub-issues) if relevant. **Type** is the issue/PR label, not a board field (see [Project board layout](#-project-board-project-8)). +- **Roadmap.** Priority = the community vote (mechanism in `GOVERNANCE.md`). Accepted items live on board #8 — keep `ROADMAP.md` a pointer, don't maintain a second list. +- **Review PRs.** Approve as CODEOWNERS, then squash-merge (merge policy → [`GOVERNANCE.md`](../GOVERNANCE.md#-code-decisions-merging)). -```bash -gh project field-list 8 --owner ai-driven-dev # note the IDs you need below -``` +## 📋 Project board (Project 8) -### Fields - -- **Drop `Work type`** — duplicates the Type label. **Drop `Phases`** — duplicates Status/Milestone (and no milestone exists, so it is noise): - ```bash - gh project field-delete --id - gh project field-delete --id - ``` -- **Keep `Priority`** (P0 · P1 · P2) and `Area`. No action. -- **`Status`** — single-select options, in order: `Todo` · `In progress` · `In review` · `Ready` · `Done`. `Status` is a built-in field; edit its options in the UI (Board → `Status` field header → Edit values). The CLI only *creates* fields, so use it only if you are rebuilding from scratch: - ```bash - # from-scratch alternative only — NOT for editing the existing Status field - gh project field-create 8 --owner ai-driven-dev --name Status \ - --data-type SINGLE_SELECT \ - --single-select-options "Todo,In progress,In review,Ready,Done" - ``` - -### Status automation (UI: Project → ⋯ → Workflows) - -GitHub built-in workflows drive most transitions; `In progress` is the one manual move. - -| Trigger (built-in) | Set `Status` to | -| ------------------ | --------------- | -| Item added to project | `Todo` | -| Pull request linked / ready for review | `In review` | -| Code review approved | `Ready` | -| Pull request merged · item closed | `Done` | -| *(manual — picked up by a maintainer)* | `In progress` | +The board is a **view** of the taxonomy the docs define, never its own. Each property answers one question: **Type** = the label · **Priority** = urgency · **Status** = flow position · **When** = Timeline. Routing (`next`/`main`) is *not* a board property — it derives from the branch prefix ([routing table](../aidd_docs/memory/vcs.md#types)). -### Timeline view +One-time layout (org-admin / board-write; get field IDs via `gh project field-list 8 --owner ai-driven-dev`): -Replaces the old "Phases". UI: **New view → Timeline**, date field = the Milestone / target date. Use it as the roadmap horizon (`this week` / `next` / `later`). +- **Drop** `Work type` (duplicates Type) and `Phases` (duplicates Status) — `gh project field-delete --id `. +- **Keep** `Priority` (P0 · P1 · P2) and `Area`. +- **`Status`** options, in order: `Todo · In progress · In review · Ready · Done` (built-in field — edit its values in the UI). +- **Timeline view** — new view, date = Milestone/target; use it as the roadmap horizon. -### Apply checklist +Status automation (Project → ⋯ → Workflows); `In progress` is the one manual move: -- [ ] `Work type` field deleted -- [ ] `Phases` field deleted -- [ ] `Priority` kept -- [ ] `Status` options = Todo · In progress · In review · Ready · Done -- [ ] Built-in Status workflows enabled (added→Todo, ready→In review, approved→Ready, merged/closed→Done) -- [ ] Timeline view present +| Trigger (built-in) | Status | +| --- | --- | +| Item added | `Todo` | +| PR linked / ready for review | `In review` | +| Code review approved | `Ready` | +| PR merged · item closed | `Done` | -## Labels +## 🏷️ Labels -[`.github/labels.yml`](../.github/labels.yml) is the canonical set (triage only — routing is by branch prefix). The documented sync loop **creates/updates** from the file; it does **not** delete. So when you remove a label from the file, also delete it on GitHub: +[`.github/labels.yml`](../.github/labels.yml) is the canonical set (triage only — routing is by branch prefix). The sync loop **creates/updates** from the file; it does **not** delete. So when you remove a label from the file, also delete it on GitHub: ```bash gh label delete "help wanted" --yes @@ -82,12 +54,12 @@ gh label delete "github-actions" --yes Dependabot labels its PRs `dependencies` only (ecosystem sub-labels were dropped); confirm `.github/dependabot.yml` does not re-add a deleted label before deleting it. -## Releases +## 🚀 Releases release-please opens/updates a `chore: release main` PR on each push to `main`. -1. (Optional) Review the version bumps + changelog. The PR is authored by the **aidd-bot** App, so its checks run normally. -2. CI **auto-merges** it with the App token (`--squash --admin`); no human step is needed. `--admin` is required because a plain `gh pr merge` is refused even for the bypass App. +1. (Optional) Review the version bumps + changelog. Authored by the **aidd-bot** App, so its checks run normally. +2. CI **auto-merges** it with the App token (`--squash --admin`); no human step needed. `--admin` is required because a plain `gh pr merge` is refused even for the bypass App. 3. CI tags each bumped package, creates the GitHub Releases, and attaches the bundles: - `aidd-framework-marketplace-X.Y.Z.zip` (`.claude-plugin/` + `plugins/`) - `-vX.Y.Z.zip` @@ -95,13 +67,30 @@ release-please opens/updates a `chore: release main` PR on each push to `main`. Versions live in `.release-please-manifest.json`. Forcing a version / pre-release: `release-as` in `release-please-config.json` (remove it after the release ships). -## Dependencies (Dependabot) +## 🔄 Promotion & recovery -**Patch + minor bumps auto-merge** once their checks pass (`.github/workflows/dependabot-auto-merge.yml`, via the aidd-bot App). **Major bumps stay manual** - review, then `gh pr merge --squash`. If several lockfile bumps queue up, the first merges and the rest re-base automatically (or comment `@dependabot rebase`). +The weekly `next` → `main` promotion **must rebase, never squash**: -## Branch protection & the bot bypass +- A squash collapses the batch's conventional commits into one subject from the PR title. If that title isn't a valid conventional type, `Commitlint` fails on `main` and **release-please is skipped** — no release. +- release-please also reads each commit's type/scope to bump the right package, which a squash hides. +- Use the **Promote next to main** workflow (it rebase-merges); merging by hand, pick **Rebase and merge**. +- The Release PR release-please opens is its own single commit and is fine to squash. -`main` accepts only PRs (no direct push, no force-push, no deletion) with a CODEOWNERS review and passing `lefthook` / `Commitlint`. +**Recovery** — a bad squashed promote turns `main` red on `Commitlint` and skips **Release Please**. An admin: + +1. Temporarily disables the `main protection` ruleset (Settings → Rules). +2. Force-pushes `main` back to the commit before the bad merge. +3. Re-enables the ruleset, then re-runs **Promote**. + +## 📦 Dependencies (Dependabot) + +- **Patch + minor bumps auto-merge** once checks pass (`.github/workflows/dependabot-auto-merge.yml`, via the aidd-bot App). +- **Major bumps stay manual** — review, then `gh pr merge --squash`. +- Several lockfile bumps queued: the first merges and the rest re-base automatically (or comment `@dependabot rebase`). + +## 🔒 Branch protection & the bot bypass + +The protection policy (PR-only, CODEOWNERS review, required checks) is defined in [`GOVERNANCE.md`](../GOVERNANCE.md#-code-decisions-merging); this is the ops. Two bypass actors (both `pull_request` mode, so neither can push directly to `main`): - the **aidd-bot GitHub App** (`Integration`) - release-please and the Dependabot auto-merge mint a token from it (`actions/create-github-app-token`), so their PRs trigger the required checks *and* the App merges them past the human-review rule. @@ -109,7 +98,11 @@ Two bypass actors (both `pull_request` mode, so neither can push directly to `ma The App: ID in secret `AIDD_BOT_APP_ID`, key in `AIDD_BOT_PRIVATE_KEY`. If the App is broken/uninstalled, release and Dependabot PRs stop merging - fix the App rather than re-adding an admin bypass. -Head branches are **not** auto-deleted on merge (`delete_branch_on_merge: false`): the promote PR merges `next` into `main` without deleting `next`, so the back-merge that realigns `next` afterwards never hits a missing branch. Do not re-enable the setting. +Head branches are **not** auto-deleted on merge (`delete_branch_on_merge: false`): + +- The promote PR merges `next` into `main` without deleting `next`, so the back-merge that realigns `next` never hits a missing branch. **Do not re-enable** the setting. +- The back-merge runs unattended (bot App `always` bypass on the `next` ruleset). If it can't push, it opens an issue labelled `back-merge-failed` — resync with a `main` → `next` PR. +- If `next` is ever missing, recreate it: `git push origin main:next`. To change protection, edit `.github/rulesets/main.json` (or `next.json`), then apply it live: ```bash @@ -117,28 +110,31 @@ gh api -X PUT repos/ai-driven-dev/framework/rulesets/ --input .github/rulese ``` Keep the file and the live ruleset in sync. -## People +## 👥 People + +Roles, promotion, and inactivity rules → [`GOVERNANCE.md`](../GOVERNANCE.md#-roles). Team mechanics only: -- **Promote to Habilité**: a Habilité nominates a Certifié with a track record; majority of Habilité approves; add them to the `habilitated` team and `CODEOWNERS`. -- **Core Team / Certifié**: managed via the `core-team` / `certified` teams (Core Team = paid AIDD programme members; Certifié = passed certification). -- Inactivity 6 months -> emeritus by Habilité majority. +- Habilité ↔ `habilitated` team + `CODEOWNERS`. +- Core Team / Certifié ↔ `core-team` / `certified` teams. -## Security +## 🛡️ Security - Vulnerabilities: GitHub Security Advisories (see `SECURITY.md`); never a public issue. - Secret scanning + push protection + Dependabot alerts are enabled. Push protection blocks new secret commits; it does not scan history, so never paste tokens. - Plugin-specific runtime risks (CI permissions, MCP servers) belong in that plugin's README, not here. -## Do NOT hand-edit +## ✋ Do NOT hand-edit -- **README counts** (`6 plugins · 31 skills · 3 agents` and per-plugin) - auto-generated by `scripts/sync-readme-counts.mjs` via lefthook. -- **Per-plugin `CATALOG.md`** - auto-generated by `scripts/summarize-markdown.js` via lefthook. -- **`CONTRIBUTORS.md` mosaic** - the contrib.rocks image updates itself. +- **README counts** — the hero `N plugins · N skills · N agents` block (between the `counts:start`/`counts:end` markers) and each per-plugin `N skills` span — auto-generated by `scripts/sync-readme-counts.mjs` via lefthook. +- **Per-plugin `CATALOG.md`** — auto-generated by `scripts/summarize-markdown.js` via lefthook. +- **`CONTRIBUTORS.md` mosaic** — the contrib.rocks image updates itself. -## Multi-tool +## 🛠️ Multi-tool -The marketplace is Claude Code native. Other tools are served by per-release archives the `aidd-cli` builds; this repo stays Claude-authored and tool-agnostic in its prose. Keep tool-specific detail in plugin READMEs. +- The marketplace is Claude Code native. +- Other tools are served by per-release archives the `aidd-cli` builds; this repo stays Claude-authored and tool-agnostic in its prose. +- Keep tool-specific detail in plugin READMEs. -## Build your own plugin +## 🧱 Build your own plugin -See [`CREATE_PLUGIN.md`](CREATE_PLUGIN.md). New plugins must also be registered in `release-please-config.json` + `.release-please-manifest.json`, or they never release. +See [`CREATE_PLUGIN.md`](CREATE_PLUGIN.md). diff --git a/docs/MARKETPLACE.md b/docs/MARKETPLACE.md index c5c49069..560fab5e 100644 --- a/docs/MARKETPLACE.md +++ b/docs/MARKETPLACE.md @@ -2,23 +2,28 @@ Reference for how the `aidd-framework` marketplace is registered, scoped, and versioned, plus the LLM tier mapping used by skills. -## How marketplaces work +## 🛒 How marketplaces work -A marketplace is a Git repo that publishes plugins. When you run `/plugin marketplace add /`, Claude Code clones the repo, reads its `.claude-plugin/marketplace.json`, and offers the listed plugins for install. +A marketplace is a Git repo that publishes plugins. Run `/plugin marketplace add /` and Claude Code clones the repo, reads its `.claude-plugin/marketplace.json`, and offers the listed plugins. -`aidd-framework` is a **community-maintained, methodology-driven complement** to Anthropic's [official marketplace](https://github.com/anthropics/claude-plugins-official). The official catalog covers broadly useful plugins curated by Anthropic; AIDD ships plugins that materialise a specific way of working (the AI-Driven Development flow). The two are designed to coexist — register both and install from either. +```mermaid +flowchart LR + Add["/plugin marketplace add owner/repo"] --> Clone["Claude Code clones the repo"] --> Read["reads .claude-plugin/marketplace.json"] --> Offer["offers the listed plugins"] --> Install["/plugin install → user · project · local scope"] +``` + +`aidd-framework` is a community marketplace. It complements Anthropic's [official one](https://github.com/anthropics/claude-plugins-official) — register both, install from either. Official Anthropic docs: -- [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins) — the user-facing flow +- [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins) — user-facing flow - [Plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces) — host your own - [Plugins reference](https://code.claude.com/docs/en/plugins-reference) — manifest + marketplace.json schemas > **Private repo?** `/plugin marketplace add` needs read access (`gh auth login` or a PAT) — see the [install docs](https://code.claude.com/docs/en/discover-plugins). -## Install scopes +## 🔧 Install scopes -Plugins can be installed at three scopes: +Three scopes: | Scope | Stored in | Lifetime | Best for | | --- | --- | --- | --- | @@ -26,19 +31,17 @@ Plugins can be installed at three scopes: | `project` | `.claude/settings.json` (`enabledPlugins`) in the repo | This repo only | Team-shared setup | | `local` | A local directory | This machine | Plugin development | -Set scope at install time with the `/plugin` UI, or by editing `enabledPlugins` directly in `.claude/settings.json`. - -## Versioning & updates +Set scope at install time via the `/plugin` UI, or edit `enabledPlugins` directly in `.claude/settings.json`. -- Each plugin versions independently via `release-please`. Tags look like `aidd--vX.Y.Z`. -- The root marketplace (`marketplace.json`) versions independently as `vX.Y.Z`. -- Pull updates inside Claude Code with `/plugin marketplace update aidd-framework`. +## 🔖 Versioning & updates -See [`CHANGELOG.md`](../CHANGELOG.md) for the full history. +- Each plugin and the root marketplace version independently via `release-please` (tags `-vX.Y.Z`, root `vX.Y.Z`). Tooling → [`vcs.md`](../aidd_docs/memory/vcs.md#release-management). +- Pull updates inside Claude Code: `/plugin marketplace update aidd-framework`. +- Full history → [`CHANGELOG.md`](../CHANGELOG.md). -## LLM tier reference +## 🧠 LLM tier reference -Some skills target a model **tier** when they need a particular capability. The framework is authored against Claude; on another AI tool, map each tier to that tool's nearest model. +Some skills target a model **tier** for a needed capability. The framework is authored against Claude; on another AI tool, map each tier to its nearest model. | Tier | Best for | Claude | Other tools (examples) | | ---- | -------- | ------ | ---------------------- | diff --git a/docs/RELEASE.md b/docs/RELEASE.md deleted file mode 100644 index 77ca16d4..00000000 --- a/docs/RELEASE.md +++ /dev/null @@ -1,61 +0,0 @@ -# Releasing - -The release pipeline is automated. A human (or an AI agent) only triggers the -promotion; everything after that runs itself. - -## The flow - -``` -next --(promote)--> main --(release-please)--> version PR --(auto-merge)--> tags + GitHub releases - | - '--(back-merge)--> next (keeps next in sync) -``` - -1. **Work lands on `next`** via normal PRs (rebase or squash into `next`, your choice). -2. **Promote `next` to `main`.** Run the **Promote next to main** workflow (Actions tab -> Run workflow). It opens a `next -> main` PR and **rebase-merges** it. -3. **release-please** runs on the push to `main`, opens a version PR (bumps + changelogs), and the CI **auto-merges that version PR** (`--squash --admin`). No human needed. -4. **Tags and GitHub releases** are published per package and for the root. -5. **Back-merge** fires on `release: published` and syncs `main` back into `next` so the changelog and version files do not drift. - -## The one rule: promote with REBASE, never squash - -`next -> main` carries many conventional commits (`feat(scope):`, `fix(scope):`). -Two things depend on them: - -- **commitlint** checks every commit message. A squash collapses them into one - subject taken from the PR title; if that title is not a valid conventional - type (e.g. `release:`), commitlint fails on `main` and **release-please is - skipped** -- no release happens. -- **release-please** reads each commit's type and scope to bump the right plugin - by the right amount. A squash hides them, so it cannot compute the versions. - -So always use the **Promote** workflow (it rebase-merges). If you merge by hand, -use **Rebase and merge**, never **Squash**. The version PR that release-please -opens is its own single commit and is fine to squash -- that one is automated. - -## If a release breaks (recovery) - -Symptom: after a promote, `main` CI is red on **Commitlint** and **Release -Please** is skipped -- usually a squashed, non-conventional promote commit. - -1. An admin temporarily disables the `main protection` ruleset (Settings -> - Rules), force-pushes `main` back to the commit before the bad merge, then - re-enables the ruleset. -2. Re-run the **Promote** workflow (rebase). release-please then cuts the - release normally. - -## Pinning a specific version - -To force a package to a chosen version on the next cut, set `release-as` for it -in `release-please-config.json` (deterministic, overrides any `Release-As:` -commit footer). Remove the pin afterwards so automatic bumps resume. - -## Back-merge and drift - -The back-merge runs unattended (the bot app has an `always` bypass on the `next` -ruleset). After each release it either realigns `next` onto `main` (when `next` -holds no unreleased work, the normal case) or keeps a merge (when it does), so -the rebase-promote hash drift never accumulates. If it ever cannot push, it -opens an issue labelled `back-merge-failed`; resync by opening a `main -> next` -PR. If `next` is missing entirely (it must not be — head branches are not -auto-deleted), recreate it from `main` first: `git push origin main:next`. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md deleted file mode 100644 index 9b76ed23..00000000 --- a/docs/TROUBLESHOOTING.md +++ /dev/null @@ -1,32 +0,0 @@ -# Troubleshooting - -Common issues when installing or running the AIDD marketplace, plus the current limits of the framework. - -## Install and load - -### The marketplace doesn't show my plugins after `/plugin marketplace add` - -Refresh the cache: `/plugin marketplace update aidd-framework`, then open `/plugin` → **Discover**. - -### `/plugin install` says the plugin is unknown - -The marketplace name must match the `name` field in this repo's `.claude-plugin/marketplace.json` (currently `aidd-framework`). Install with `/plugin install @aidd-framework`. - -### A private repo won't add as a marketplace - -`/plugin marketplace add /` needs read access to the repo - authenticate with `gh auth login` or a PAT on the machine running your AI tool. - -### My new plugin's actions don't load - -Run `/reload-plugins` in the same session, or restart the tool if a hook config changed. - -## Limitations (what AIDD does not do) - -- **Not autonomous by default.** Skills run under human supervision; you drive each step. -- **Authored for Claude Code.** Other tools get a per-release archive built by the `aidd-cli` (download → unzip → install; see [Another AI tool?](../README.md#another-ai-tool)); native parity is a roadmap item, not a guarantee today. -- **Plugins assume their own context.** A skill that expects a git repo, a `package.json`, or a ticketing tool will not work without it - check the plugin's README. -- **No hosted service.** AIDD is prompt content you install into your own tool; there is no AIDD server, account, or telemetry. - -## Still stuck? - -Ask in [Discussions](https://github.com/ai-driven-dev/framework/discussions) or on [Discord](https://discord.gg/EWySJSpjWs). For a bug, open an [issue](https://github.com/ai-driven-dev/framework/issues/new/choose). See [`SUPPORT.md`](../.github/SUPPORT.md). diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index a741fe70..c214a1cc 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -8,7 +8,7 @@ Code transformation plugin for the AI-Driven Development framework. First time? Install with `/plugin install aidd-dev@aidd-framework`, then run `aidd-dev:00-sdlc`. -Covers the full SDLC coding loop: orchestrator, planning, implementation, assertions, audits, code review, testing, refactoring, debugging, and the for-sure workflow. Also hosts AI agents. +Covers the full SDLC coding loop: orchestrator, planning, implementation, assertions, audits, code review, testing, refactoring, debugging, for-sure, and parallel todo fan-out. Also hosts AI agents. ## Skills @@ -24,6 +24,7 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | [2.7] | [refactor](skills/07-refactor/SKILL.md) | Optimize code for performance and fix security vulnerabilities following OWASP guidelines. | | [2.8] | [debug](skills/08-debug/SKILL.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. | | [2.9] | [for-sure](skills/09-for-sure/SKILL.md) | Iterative agent loop that tracks attempts and retries until a success condition is met. | +| [2.10] | [todo](skills/10-todo/SKILL.md) | Split the prompt into independent todos, run one executor agent per todo in parallel, then report a minimal table. | ## Agents diff --git a/plugins/aidd-orchestrator/README.md b/plugins/aidd-orchestrator/README.md index 15eab9e7..e525323d 100644 --- a/plugins/aidd-orchestrator/README.md +++ b/plugins/aidd-orchestrator/README.md @@ -6,7 +6,7 @@ Orchestration plugin for the AI-Driven Development framework. > Status: stable for use case `async-dev`; other use cases on the roadmap are experimental. -First time? Install with `/plugin install aidd-orchestrator@aidd-framework`, then run `aidd-orchestrator:00-async-dev` with `action=setup` (or just describe what you want; the router decides). +First time? Install with `/plugin install aidd-orchestrator@aidd-framework`, then run `aidd-orchestrator:00-async-dev` with `action=setup` (or just describe what you want; the router decides). New to the framework? See the [quick start](../../README.md#-quick-start). Composes capabilities into deterministic, auditable flows. Each skill is one orchestration brick; several use cases coexist inside the same plugin. @@ -26,7 +26,3 @@ See the [skill's SKILL.md](skills/00-async-dev/SKILL.md) for the sub-flow invent |----------|-----------| | `agentic-orchestration` | Multi-agent coordination - sub-agents, hand-offs, supervision. | | `flow-orchestration` | Conditional / branching pipelines - human gates, fallbacks, retries. | - -## Install - -See the [framework quick start](../../README.md#quick-start). diff --git a/plugins/aidd-vcs/README.md b/plugins/aidd-vcs/README.md index fe89ad57..75e4898d 100644 --- a/plugins/aidd-vcs/README.md +++ b/plugins/aidd-vcs/README.md @@ -8,14 +8,15 @@ VCS workflow plugin for the AI-Driven Development framework. First time? Install with `/plugin install aidd-vcs@aidd-framework`, then run `aidd-vcs:01-commit`. -Typical flow: `01:commit` after each unit of work; `02:pull-request` when the branch is ready; `03:release-tag` at release time; `04:issue-create` from anywhere. +Typical flow: `00-repo-init` once to set up the repo; `01-commit` after each unit of work; `02-pull-request` when the branch is ready; `03-release-tag` at release time; `04-issue-create` from anywhere. -Covers all external artifact creation: commits, pull/merge requests, release tags, and issue tracking. +Covers all external artifact creation: repo init, commits, pull/merge requests, release tags, and issue tracking. ## Skills | Bracket ID | Skill | Description | |---|---|---| +| [3.0] | [repo-init](skills/00-repo-init/SKILL.md) | Initialize a repo: git init, default branch, bootstrap commit, CONTRIBUTING.md, optional remote. | | [3.1] | [commit](skills/01-commit/SKILL.md) | Create a git commit with proper conventional message format. | | [3.2] | [pull-request](skills/02-pull-request/SKILL.md) | Create PR (GitHub) or MR (GitLab) with filled template. | | [3.3] | [release-tag](skills/03-release-tag/SKILL.md) | Create and push a semantic version git tag with release notes. | diff --git a/recipes/README.md b/recipes/README.md index fbdb5c80..a4c65f64 100644 --- a/recipes/README.md +++ b/recipes/README.md @@ -4,10 +4,12 @@ Task-oriented how-to sheets for the AIDD Framework. Each recipe is a self-contai | Recipe | Goal | Level | | --- | --- | --- | +| [Start a project](start-a-project.md) | Take a greenfield idea to a set-up project with its AIDD context | Beginner | +| [Ship a feature](ship-a-feature.md) | Take a feature from idea to a reviewed, shipped PR | Beginner | | [MCP installations](mcp-installation.md) | Decide when to use an MCP server vs a CLI, and wire up the recommended ones | Beginner | > More coming — token optimisation, custom plugins, and others. ## Contributing a recipe -Recipes follow a shared template (title · goal · level · time · prerequisites · steps · verify · related). A `/cook` skill to `list` and `upsert` recipes from a canonical template is on the way; until then, copy the shape of [`mcp-installation.md`](mcp-installation.md) and open a PR. See [`CONTRIBUTING.md`](../CONTRIBUTING.md). +Recipes follow a shared template (title · goal · level · time · prerequisites · steps · verify · related). Use [`/aidd-context:12-cook`](../plugins/aidd-context/skills/12-cook/SKILL.md) to `list` or `upsert` a recipe from the canonical template, then open a PR. See [`CONTRIBUTING.md`](../CONTRIBUTING.md). diff --git a/recipes/ship-a-feature.md b/recipes/ship-a-feature.md new file mode 100644 index 00000000..a23a4b86 --- /dev/null +++ b/recipes/ship-a-feature.md @@ -0,0 +1,37 @@ + + +# Ship a feature end to end + +> **Goal:** Take a feature from a rough idea to a reviewed, shipped pull request with the AIDD flow. + +| | | +| ----------------- | ------------------------------------------------------------ | +| **Level** | Beginner | +| **Time** | ~varies with the feature | +| **Prerequisites** | AIDD installed; project set up ([Start a project](start-a-project.md)) | + +## Why + +The common loop, at a glance — the exact commands to run so you never wonder what comes next. + +> Prefer a guided walkthrough? `/aidd-context:00-onboard` inspects your project and routes you step by step instead of running the sequence by hand. + +## Steps + +1. 💡 **Clarify**: `/aidd-refine:01-brainstorm` — turn the rough idea into a precise request. +2. 📋 **Plan**: `/aidd-dev:01-plan` — draft the phased technical plan. +3. 🔧 **Implement**: `/aidd-dev:02-implement` — write the code, phase by phase. +4. 🔍 **Review**: `/aidd-dev:05-review` — review the diff before it ships. +5. 📦 **Commit**: `/aidd-vcs:01-commit` — one atomic conventional commit. +6. ✅ **Pull request**: `/aidd-vcs:02-pull-request` — open the PR. + +> One command for the whole loop: `/aidd-dev:00-sdlc` runs plan → implement → review → ship. + +## Verify + +- A pull request is open on your branch, with the diff reviewed and tests passing. + +## Related + +- [Start a project](start-a-project.md) — greenfield setup before your first feature. +- `/aidd-context:00-onboard` — guidance on what to run next at any point. diff --git a/recipes/start-a-project.md b/recipes/start-a-project.md new file mode 100644 index 00000000..5fd98f72 --- /dev/null +++ b/recipes/start-a-project.md @@ -0,0 +1,34 @@ + + +# Start a project (greenfield) + +> **Goal:** Take a greenfield idea to a set-up project with its AIDD context, ready for the first feature. + +| | | +| ----------------- | ------------------------------ | +| **Level** | Beginner | +| **Time** | ~30 min | +| **Prerequisites** | AIDD installed in your AI tool | + +## Why + +The greenfield sequence, at a glance — from a raw idea to a project the AIDD flow can build on. + +> Prefer a guided walkthrough? `/aidd-context:00-onboard` inspects your project and routes you step by step instead of running the sequence by hand. + +## Steps + +1. 💡 **Brainstorm the idea**: `/aidd-refine:01-brainstorm` — sharpen the raw idea into a precise request. +2. 📄 **Draft the PRD**: `/aidd-pm:03-prd` — turn the idea into a structured product requirements document. +3. 🏗️ **Design the architecture**: `/aidd-context:01-bootstrap` — validate a stack through Q&A; outputs an `INSTALL.md`. +4. 🧠 **Build project memory**: `/aidd-context:02-project-memory` — create the memory bank and AI context files. +5. 🚀 **Ship the first feature**: follow [Ship a feature](ship-a-feature.md). + +## Verify + +- `aidd_docs/memory/` holds the memory files, and an `INSTALL.md` describes the chosen stack. + +## Related + +- [Ship a feature](ship-a-feature.md) — the per-feature loop once the project is set up. +- `/aidd-context:00-onboard` — re-run any time to see where the project sits. From 92b009773d4572945af5f3f52d1f758dcd33a90e Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 7 Jul 2026 11:06:52 +0200 Subject: [PATCH 13/20] ci(release-please): pin GitHub latest to umbrella marketplace tag (#408) release-please creates the umbrella and every plugin release in one run with no ordering guarantee. GitHub marks whichever release is created last as "Latest" (the create API defaults make_latest to true), so a plugin release (e.g. aidd-dev-v2.3.0) can outrank the marketplace version on batched cycles. Force the root "." package tag (the umbrella v*) as latest after release-please runs. The umbrella bumps every cycle, so a release run always has a root tag to pin. Co-authored-by: Claude Opus 4.8 --- .github/workflows/ci.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 82c59f4d..aa051fb9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,6 +88,22 @@ jobs: GH_TOKEN: ${{ steps.app-token.outputs.token }} run: gh pr merge "${{ fromJSON(steps.release.outputs.pr).number }}" --squash --admin --repo "${{ github.repository }}" + # Pin GitHub's "Latest" badge to the umbrella marketplace release. + # release-please creates the umbrella + every plugin release in one run + # with no ordering guarantee, and GitHub marks whichever release is created + # last as "Latest" (the create API defaults make_latest to true). That + # lets a plugin release (e.g. aidd-dev-v2.3.0) outrank the marketplace + # version whenever a cycle ships plugins alongside the umbrella. Bare + # `tag_name` is the root "." package tag (the umbrella `v*`, the tag that + # carries the marketplace bundle); forcing it latest auto-unsets the plugin + # release that held the badge. The umbrella bumps every cycle, so a + # release run always has a root tag to pin. + - name: Pin umbrella release as latest + if: ${{ steps.release.outputs.release_created == 'true' }} + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: gh release edit "${{ steps.release.outputs.tag_name }}" --latest --repo "${{ github.repository }}" + build-and-attach: name: Build and attach marketplace needs: [release-please] From f6e06e0aa6dd86b7b2de22ca8f0d2a5da0a46281 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Duval?= Date: Thu, 9 Jul 2026 05:06:46 +0200 Subject: [PATCH 14/20] docs(framework): clarify README pitch, terms, and install list (#409) The install-first rework still left a first-time reader with an abstract pitch, undefined Marketplace/Flat terms, a 7-vs-6 plugin count mismatch in the install block, and an asymmetric row in the plugins table. - Ground the pitch in one runnable /aidd-dev:00-sdlc example instead of a list of nouns. - Define Marketplace vs Flat where the compatibility table first uses them, not only inside the Cursor details block. - Note that the Claude Code install list covers the 6 stable plugins (aidd-ui is alpha) so the count matches the header badge. - Pad the aidd-ui table row to three cells like every other row. - Add a FAQ entry answering "why not just write my own skills?", linked from the new pitch. --- README.md | 15 ++++++++++++--- docs/FAQ.md | 4 ++++ 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d3f3aef4..b531e29d 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,14 @@ --- -The **AI-Driven Dev Framework** is a marketplace — **skills, agents, commands, rules, prompts, templates, recipes…** — that helps you ship **high-quality features to production**. +The **AI-Driven Dev Framework** installs a working SDLC (Software Development Life Cycle) into your AI coding tool — **skills, agents, commands, rules** — that turns a rough idea into a reviewed, shipped pull request: -> Orchestrate your SDLC (Software Development Life Cycle) at scale, the agentic-engineering way. +```text +/aidd-dev:00-sdlc "add rate limiting to the /login endpoint" +→ spec → plan → implement → review → ship (commit + PR opened) +``` + +Why not just write your own commands? → [FAQ](docs/FAQ.md#-why-aidd-instead-of-your-own-skills). ## ✅ Prerequisites @@ -50,12 +55,14 @@ The **AI-Driven Dev Framework** is a marketplace — **skills, agents, commands, | **OpenCode** | ✅ Supported | Flat | | **Gemini · Mistral** | 🚧 In progress | — | -Install steps per tool → [Other tools](#other-tools). +**Marketplace** = installed and updated through your tool's plugin manager. **Flat** = files copied directly into your project, no plugin manager involved. Install steps per tool → [Other tools](#other-tools). ## 📦 Install ### Claude Code +Installs the 6 stable plugins (`aidd-ui` is 🚧 alpha, install separately — see [Plugins](#-plugins)). + **In the session** (slash commands) ```text @@ -266,6 +273,8 @@ Async dev: label an issue → get a PR. UI / UX design — smoke-test only, not ready for use. + + diff --git a/docs/FAQ.md b/docs/FAQ.md index 766f8477..7cb6c08e 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -2,6 +2,10 @@ Most "how do I…" answers live in the README; this page covers what isn't documented elsewhere, plus common install issues and the framework's limits. +## 🤔 Why AIDD instead of your own skills? + +You can write your own Claude Code skills — nothing stops you. AIDD exists because that setup is work every team repeats and re-debugs alone: the router/action split ([Skill](GLOSSARY.md#-skill) glossary entry), the plan → implement → review gating, the plugin packaging and versioning, the multi-tool support (Cursor, Copilot, Codex, OpenCode). AIDD ships that scaffolding pre-built and maintained, so you start from a working SDLC loop and only author the skill content specific to your project. If your workflow doesn't match the framework's shape, [`CREATE_PLUGIN.md`](CREATE_PLUGIN.md) shows how to build on the same scaffolding instead of replacing it. + ## 📦 Install, update, other tools - **Install / first run** → [Quick start](../README.md#-quick-start). From 984fab83fd31cbe334b1601e19bdaec07a05864d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Duval?= Date: Thu, 9 Jul 2026 09:11:19 +0200 Subject: [PATCH 15/20] docs(framework): clarify README pitch, terms, and install list (#410) * docs(framework): clarify README pitch, terms, and install list The install-first rework still left a first-time reader with an abstract pitch, undefined Marketplace/Flat terms, a 7-vs-6 plugin count mismatch in the install block, and an asymmetric row in the plugins table. - Ground the pitch in one runnable /aidd-dev:00-sdlc example instead of a list of nouns. - Define Marketplace vs Flat where the compatibility table first uses them, not only inside the Cursor details block. - Note that the Claude Code install list covers the 6 stable plugins (aidd-ui is alpha) so the count matches the header badge. - Pad the aidd-ui table row to three cells like every other row. - Add a FAQ entry answering "why not just write my own skills?", linked from the new pitch. * Missing part with aidd-ui, details for claude's commande lineand remove td at the end --- README.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b531e29d..412dd03b 100644 --- a/README.md +++ b/README.md @@ -73,16 +73,26 @@ Installs the 6 stable plugins (`aidd-ui` is 🚧 alpha, install separately — s /plugin install aidd-vcs@aidd-framework /plugin install aidd-pm@aidd-framework /plugin install aidd-orchestrator@aidd-framework +/plugin install aidd-ui@aidd-framework # 🚧 alpha, install separately ``` -**Command line** (same, prefixed with `claude`) + +
+Command line (same, prefixed with `claude`) ```bash claude plugin marketplace add ai-driven-dev/framework -claude plugin install aidd-context@aidd-framework # then aidd-refine, aidd-dev, aidd-vcs, aidd-pm, aidd-orchestrator +claude plugin install aidd-context@aidd-framework +claude plugin install aidd-refine@aidd-framework +claude plugin install aidd-dev@aidd-framework +claude plugin install aidd-vcs@aidd-framework +claude plugin install aidd-pm@aidd-framework +claude plugin install aidd-orchestrator@aidd-framework +claude plugin install aidd-ui@aidd-framework # 🚧 alpha, install separately ``` +
Update anytime: `/plugin marketplace update aidd-framework`. ### Other tools From d0a17fced63f5519146c066c6ba3321cfc32b689 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Fri, 10 Jul 2026 12:16:12 +0200 Subject: [PATCH 16/20] chore(commitlint): declare the aidd-ui scope, long and short (#423) `plugins/aidd-ui` ships, but neither `aidd-ui` nor `ui` was in `scope-enum`, while the six other plugins each declare both forms. A commit touching the plugin warned on a scope the repo itself defines. Co-authored-by: Claude Opus 4.8 --- commitlint.config.cjs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/commitlint.config.cjs b/commitlint.config.cjs index 51cde411..c44ab106 100644 --- a/commitlint.config.cjs +++ b/commitlint.config.cjs @@ -16,12 +16,14 @@ module.exports = { "aidd-pm", "aidd-refine", "aidd-orchestrator", + "aidd-ui", "context", "dev", "vcs", "pm", "refine", "orchestrator", + "ui", // Root scopes (touching marketplace.json or framework-wide config) "framework", "marketplace", From 86051b7d849f561ec0edfeae577c43e7580d2e1c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Fri, 10 Jul 2026 12:16:16 +0200 Subject: [PATCH 17/20] chore(framework): type issues instead of labelling them (#422) The forms applied `labels: ["bug"]` and `labels: ["enhancement"]`, but neither label existed on GitHub, so every issue created through them landed unlabelled: zero of the repo's 300 issues carries one. Issue types (Bug, Feature, Task) are defined at the org level and the forms can set them directly. - Both forms swap `labels:` for `type:` and scope their title prefix, matching the scope commitlint already expects on the commit. - New `roadmap.yml` for maintainer-authored work: Problem, Scope, Acceptance criteria, and two optional sections that catch duplicates before they ship. - `labels.yml` keeps only what a bot or a human actually reads. Co-authored-by: Claude Opus 4.8 --- .github/ISSUE_TEMPLATE/bug_report.yml | 4 +- .github/ISSUE_TEMPLATE/feature_request.yml | 4 +- .github/ISSUE_TEMPLATE/roadmap.yml | 47 ++++++++++++++++++++++ .github/labels.yml | 32 +++++---------- 4 files changed, 61 insertions(+), 26 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/roadmap.yml diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 02f7fc07..f4c6cb21 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,7 +1,7 @@ name: 🐛 Bug Report description: Report a bug or unexpected behaviour in the framework -title: "fix: " -labels: ["bug"] +title: "fix(): " +type: Bug body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 71f57cec..032f0774 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,7 +1,7 @@ name: ✨ Feature Request description: Propose new content or an improvement to the framework -title: "feat: " -labels: ["enhancement"] +title: "feat(): " +type: Feature body: - type: markdown attributes: diff --git a/.github/ISSUE_TEMPLATE/roadmap.yml b/.github/ISSUE_TEMPLATE/roadmap.yml new file mode 100644 index 00000000..e4fde1f2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/roadmap.yml @@ -0,0 +1,47 @@ +name: 🗺️ Roadmap item +description: "Maintainer-authored work: a skill, a refactor, a rule to enforce" +title: "(): " +type: Task +body: + - type: markdown + attributes: + value: | + For maintainers planning framework work. Reporting a bug or asking for a feature as a user? + Use the **Bug Report** or **Feature Request** form instead. + + The title carries its own scope, matching `commitlint.config.cjs`: `feat(aidd-pm):`, `fix(framework):`, `refactor(aidd-context):`. + - type: textarea + id: problem + attributes: + label: Problem + description: What is wrong or missing today. State the current behaviour, not the fix. + placeholder: The router of `10-learn` is 40 lines of its 153, denser than the four actions it routes to. + validations: + required: true + - type: textarea + id: scope + attributes: + label: Scope + description: What this change does. One bullet per deliverable. + validations: + required: true + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: Checkboxes a reviewer can verify without asking the author. Each one observable. + value: | + - [ ] + - [ ] + validations: + required: true + - type: textarea + id: prior-art + attributes: + label: Prior art in this repo + description: What already exists that this builds on or duplicates. Cite the file and line. Leave empty if you checked and found none. + - type: textarea + id: out-of-scope + attributes: + label: Out of scope + description: What a reader would expect here and will not find, with where it lives instead. diff --git a/.github/labels.yml b/.github/labels.yml index 25ecc914..6160972c 100644 --- a/.github/labels.yml +++ b/.github/labels.yml @@ -1,8 +1,12 @@ # Canonical issue and PR label list for ai-driven-dev/framework. # -# Labels are TRIAGE ONLY: they categorize an issue or PR. They never decide -# where a PR targets — routing is by branch prefix (see aidd_docs/memory/vcs.md). -# Keep one triage label per change. +# Labels do NOT categorize an issue. Issue types (Bug, Feature, Task) and the +# org issue fields (Priority, Effort) do that, and the issue forms set the type. +# A label here exists only when a bot or a human reads it, and nothing else can +# carry the signal. +# +# Labels never decide where a PR targets — routing is by branch prefix +# (see aidd_docs/memory/vcs.md). # # This file is the source of truth. When the GitHub label set drifts from # this file, sync manually with: @@ -13,35 +17,19 @@ # job). Plugins may create their own labels on install; those are documented in # the plugin, not here. -# --- Triage -------------------------------------------------------------- - -- name: bug - description: Something isn't working - color: d73a4a - -- name: enhancement - description: New feature or request - color: a2eeef - -- name: documentation - description: Improvements or additions to documentation - color: 0075ca - -- name: security - description: Security-sensitive issue or fix (cross-cutting, add to any kind) - color: B60205 +# --- Read by a human ----------------------------------------------------- - name: good first issue description: Good for newcomers color: 7057ff -# --- Dependencies -------------------------------------------------------- +# --- Applied by dependabot (.github/dependabot.yml) ---------------------- - name: dependencies description: Dependency update (dependabot) color: 0366d6 -# --- Release tooling ----------------------------------------------------- +# --- Applied by release-please ------------------------------------------- - name: "autorelease: pending" description: Release Please release PR awaiting merge From 468d3b0a0e7559aec3b7d884f62cf210cc40a632 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Fri, 10 Jul 2026 12:32:06 +0200 Subject: [PATCH 18/20] docs(framework): describe the board we actually run (#424) MAINTAINERS.md described fields that no longer exist (`Area`, `Work type`, `Phases`), a `Priority` scale of P0/P1/P2, a `Ready` status, and a label-driven Type. The board has four orthogonal axes instead: the type is an issue type stamped by the form, the milestone says when, the priority orders what has no when, and only the status lives on the board. Also drops `--label back-merge-failed` from the back-merge workflow. The label never existed, so `gh issue create` failed, the trailing `|| echo` swallowed the error, and the step stayed green: the back-merge failed silently, which is what the comment above it forbids. Nothing read the label. Co-authored-by: Claude Opus 4.8 --- .github/workflows/back-merge.yml | 1 - ROADMAP.md | 2 +- aidd_docs/memory/vcs.md | 31 +++++++++++++------------ docs/MAINTAINERS.md | 39 ++++++++++++++++++-------------- 4 files changed, 39 insertions(+), 34 deletions(-) diff --git a/.github/workflows/back-merge.yml b/.github/workflows/back-merge.yml index f4f24fd4..4a0ff6a7 100644 --- a/.github/workflows/back-merge.yml +++ b/.github/workflows/back-merge.yml @@ -74,6 +74,5 @@ jobs: gh issue create \ --repo "${{ github.repository }}" \ --title "Back-merge main into next failed (run ${{ github.run_id }})" \ - --label "back-merge-failed" \ --body "The automated back-merge of \`main\` into \`next\` failed, so \`next\` is drifting from the latest release. Resync manually by opening a PR from \`main\` into \`next\`. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \ || echo "issue creation failed; check the run logs" diff --git a/ROADMAP.md b/ROADMAP.md index c27c8a52..c979ef24 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,6 +1,6 @@ # Roadmap -The live roadmap - **Now / Next / Later** with per-item status across the framework and CLI - is the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). That board is the single source of truth; this file deliberately does not duplicate it. Shipped reality lives in [`CHANGELOG.md`](./CHANGELOG.md). +The live roadmap is the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8): a milestone is a theme, due on a Friday, and everything without one is the backlog, ordered by priority. That board is the single source of truth; this file deliberately does not duplicate it. Shipped reality lives in [`CHANGELOG.md`](./CHANGELOG.md). ## How to influence diff --git a/aidd_docs/memory/vcs.md b/aidd_docs/memory/vcs.md index 06725d7a..633907f4 100644 --- a/aidd_docs/memory/vcs.md +++ b/aidd_docs/memory/vcs.md @@ -18,19 +18,19 @@ type/ticket-short-description ### Types The single source of truth: find your row, read left to right — it tells you the -branch to create, the label that applies, and where the PR goes. The branch -**prefix** alone decides the target (not a label, not a board field); the +branch to create, the issue type that applies, and where the PR goes. The branch +**prefix** alone decides the target (not a type, not a board field); the `aidd-vcs:02-pull-request` skill reads this table to set the base automatically. -| I want to… | Issue template | Branch | Commit | Label (auto) | PR targets | -| ---------- | -------------- | ------ | ------ | ------------ | ---------- | -| ship a feature | ✨ Feature | `feat/…` | `feat:` | `enhancement` | `next` | -| fix a bug | 🐛 Bug | `fix/…` | `fix:` | `bug` | `next` | -| change docs only | ✨ Feature | `docs/…` | `docs:` | `documentation` | `next` | -| refactor (no behaviour change) | — | `refactor/…` | `refactor:` | — | `next` | -| build / config / deps | — | `chore/…` | `chore:` | `dependencies` | `next` | -| add or update tests | — | `test/…` | `test:` | — | `next` | -| 🚨 urgent production fix | 🐛 Bug | `hotfix/…` | `fix:` | `bug` | **`main`** | +| I want to… | Issue template | Branch | Commit | Issue type | PR targets | +| ---------- | -------------- | ------ | ------ | ---------- | ---------- | +| ship a feature | ✨ Feature | `feat/…` | `feat:` | `Feature` | `next` | +| fix a bug | 🐛 Bug | `fix/…` | `fix:` | `Bug` | `next` | +| change docs only | 🗺️ Roadmap | `docs/…` | `docs:` | `Task` | `next` | +| refactor (no behaviour change) | 🗺️ Roadmap | `refactor/…` | `refactor:` | `Task` | `next` | +| build / config / deps | 🗺️ Roadmap | `chore/…` | `chore:` | `Task` | `next` | +| add or update tests | 🗺️ Roadmap | `test/…` | `test:` | `Task` | `next` | +| 🚨 urgent production fix | 🐛 Bug | `hotfix/…` | `fix:` | `Bug` | **`main`** | #### Routing rule (strict) @@ -38,11 +38,12 @@ branch to create, the label that applies, and where the PR goes. The branch - **Only `hotfix/*` targets `main`** — an urgent production fix, out of cycle. Once the PR is open, the board advances on its own: -`Todo → In review` (PR opened) `→ Ready` (review approved) `→ Done` (merged). +`Todo → In review` (PR opened) `→ Done` (merged). -Labels are **triage only**: they categorize, they never route. `security` is -cross-cutting — add it to any kind when the change is security-sensitive. The -"Commit" column shows the conventional type; the authoritative type list is the +The **issue type** categorizes; it never routes. The form stamps it, so you +never set it by hand. Labels categorize nothing here: one exists only when a bot +or a human reads it (`.github/labels.yml`). The "Commit" column shows the +conventional type; the authoritative type list is the [Commit Convention](#commit-convention) below (mirrors `commitlint.config.cjs`). ### Examples diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index 3bfff5a9..ffbde964 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -18,42 +18,47 @@ How to operate this repository day to day. This file is the **Habilité** (maint ## 📅 Daily -- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority`; link under an epic (native sub-issues) if relevant. **Type** is the issue/PR label, not a board field (see [Project board layout](#-project-board-project-8)). +- **Triage issues.** New issues auto-add to board #8. The form already stamped the type. You give the issue a **milestone** or a **priority**, never both. - **Roadmap.** Priority = the community vote (mechanism in `GOVERNANCE.md`). Accepted items live on board #8 — keep `ROADMAP.md` a pointer, don't maintain a second list. - **Review PRs.** Approve as CODEOWNERS, then squash-merge (merge policy → [`GOVERNANCE.md`](../GOVERNANCE.md#-code-decisions-merging)). -## 📋 Project board (Project 8) +## 📋 Four axes, one board -The board is a **view** of the taxonomy the docs define, never its own. Each property answers one question: **Type** = the label · **Priority** = urgency · **Status** = flow position · **When** = Timeline. Routing (`next`/`main`) is *not* a board property — it derives from the branch prefix ([routing table](../aidd_docs/memory/vcs.md#types)). +Each axis answers one question, and only `Status` lives on the board. Routing (`next`/`main`) is not an axis — it derives from the branch prefix ([routing table](../aidd_docs/memory/vcs.md#types)). -One-time layout (org-admin / board-write; get field IDs via `gh project field-list 8 --owner ai-driven-dev`): +| Axis | Lives in | Answers | Values | +| --- | --- | --- | --- | +| **Type** | issue type, stamped by the form | what kind of work | `Bug` · `Feature` · `Task` | +| **Milestone** | repo milestone | *when* it ships | one theme, due a Friday | +| **Priority** | org issue field | *in what order*, among what has no *when* | `Urgent` · `High` · `Medium` · `Low` | +| **Status** | board field | where the work stands | `Ideation` · `Todo` · `In Progress` · `In review` · `Done` | -- **Drop** `Work type` (duplicates Type) and `Phases` (duplicates Status) — `gh project field-delete --id `. -- **Keep** `Priority` (P0 · P1 · P2) and `Area`. -- **`Status`** options, in order: `Todo · In progress · In review · Ready · Done` (built-in field — edit its values in the UI). -- **Timeline view** — new view, date = Milestone/target; use it as the roadmap horizon. +Two rules keep the axes orthogonal: -Status automation (Project → ⋯ → Workflows); `In progress` is the one manual move: +- **A milestone or a priority, never both.** The milestone decided when; the order no longer matters. +- **The scope lives in the title**, conventional and queryable: `feat(aidd-pm): …`. No `Area` field, no scope label. Find work with `gh issue list --search 'aidd-pm in:title'`. + +Status automation (Project → ⋯ → Workflows); `In Progress` is the one manual move: | Trigger (built-in) | Status | | --- | --- | | Item added | `Todo` | | PR linked / ready for review | `In review` | -| Code review approved | `Ready` | | PR merged · item closed | `Done` | +The roadmap layout cannot read a milestone as a date, so the milestone view is a **Table view grouped by `Milestone`**. Its `No milestone` group is the backlog, ordered by `Priority`. + ## 🏷️ Labels -[`.github/labels.yml`](../.github/labels.yml) is the canonical set (triage only — routing is by branch prefix). The sync loop **creates/updates** from the file; it does **not** delete. So when you remove a label from the file, also delete it on GitHub: +Labels categorize nothing: the **issue type** does. A label in [`.github/labels.yml`](../.github/labels.yml) exists only when a bot or a human reads it — `good first issue`, `dependencies` (dependabot), `autorelease: *` (release-please). + +Nothing syncs the file to GitHub. Create and delete by hand, then check they agree: ```bash -gh label delete "help wanted" --yes -gh label delete npm --yes -gh label delete "github-actions" --yes +diff <(gh label list --repo ai-driven-dev/framework | cut -f1 | sort) \ + <(yq e '.[].name' .github/labels.yml | sort) ``` -Dependabot labels its PRs `dependencies` only (ecosystem sub-labels were dropped); confirm `.github/dependabot.yml` does not re-add a deleted label before deleting it. - ## 🚀 Releases release-please opens/updates a `chore: release main` PR on each push to `main`. @@ -101,7 +106,7 @@ The App: ID in secret `AIDD_BOT_APP_ID`, key in `AIDD_BOT_PRIVATE_KEY`. If the A Head branches are **not** auto-deleted on merge (`delete_branch_on_merge: false`): - The promote PR merges `next` into `main` without deleting `next`, so the back-merge that realigns `next` never hits a missing branch. **Do not re-enable** the setting. -- The back-merge runs unattended (bot App `always` bypass on the `next` ruleset). If it can't push, it opens an issue labelled `back-merge-failed` — resync with a `main` → `next` PR. +- The back-merge runs unattended (bot App `always` bypass on the `next` ruleset). If it can't push, it opens a tracking issue — resync with a `main` → `next` PR. - If `next` is ever missing, recreate it: `git push origin main:next`. To change protection, edit `.github/rulesets/main.json` (or `next.json`), then apply it live: From 279842a4046ee2e35143fa51e5d41a18011721f5 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Fri, 10 Jul 2026 12:53:02 +0200 Subject: [PATCH 19/20] feat(aidd-context): rebuild onboard as a token-lean guided tutorial (#425) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * chore: release main (#405) Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com> * 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 * 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 * feat(aidd-context): rework onboard into a noob-first guide 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 * docs(aidd-context): plan the onboard tutorial rebuild 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 * 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 * 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 * feat(aidd-context): onboard assess + run actions with order/ + run/ refs 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 * 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 * feat(aidd-context): lean onboard router + tutorial README 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 * chore(aidd-context): mark onboard tutorial rebuild implemented All five phases done, link check green. Co-Authored-By: Claude Opus 4.8 * 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 * refactor(aidd-context): compress onboard references 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 * 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 * 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 * 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 * refactor(aidd-context): router loop as an explicit mermaid, not the ambiguous ↺ 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 * 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 * 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 * 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 * refactor(aidd-context): name action outputs, drop restated step, kill semicolons 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 * refactor(aidd-context): actions stop naming sibling actions 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 * 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 * 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 * refactor(aidd-context): references hold data, not action coupling 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 * 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 * fix(aidd-context): correct + slim onboard references from review 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 * 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 * 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 * fix(aidd-context): hedge fallback names the status field, not the plan '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 * 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 * 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 * 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 * 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 * 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 * fix(aidd-context): the action line renders once, whoever carries it 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 * 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 * refactor(aidd-context): one idea per line in the actions 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 * 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 * 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 * 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 * 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 * 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 * 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 --------- Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 --- .../codex-portability.md | 49 + .../headless-runs-codex.txt | 1449 +++++++++++++++++ .../headless-runs.md | 226 +++ .../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 + .../review.md | 61 + plugins/aidd-context/CATALOG.md | 13 +- .../aidd-context/skills/00-onboard/SKILL.md | 48 +- .../skills/00-onboard/actions/01-scan.md | 28 +- .../skills/00-onboard/actions/02-assess.md | 25 + .../skills/00-onboard/actions/02-report.md | 26 - .../skills/00-onboard/actions/03-present.md | 38 + .../skills/00-onboard/actions/03-run.md | 25 - .../skills/00-onboard/actions/04-run.md | 33 + .../skills/00-onboard/assets/banner.txt | 7 + .../skills/00-onboard/assets/report.md | 83 +- .../skills/00-onboard/references/checks.md | 68 - .../skills/00-onboard/references/flow.md | 27 + .../00-onboard/references/order/idle-menu.md | 14 + .../00-onboard/references/order/ranking.md | 10 + .../00-onboard/references/order/screen-map.md | 9 + .../skills/00-onboard/references/run-tiers.md | 38 - .../00-onboard/references/run/replies.md | 14 + .../00-onboard/references/run/return.md | 3 + .../skills/00-onboard/references/run/tiers.md | 12 + .../00-onboard/references/state/detection.md | 18 + .../00-onboard/references/state/done-rule.md | 6 + .../00-onboard/references/state/hedge.md | 12 + .../00-onboard/references/state/zones.md | 41 + plugins/aidd-ui/CHANGELOG.md | 14 + 35 files changed, 2900 insertions(+), 233 deletions(-) create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/codex-portability.md 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 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 create mode 100644 aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/review.md create mode 100644 plugins/aidd-context/skills/00-onboard/actions/02-assess.md delete mode 100644 plugins/aidd-context/skills/00-onboard/actions/02-report.md create mode 100644 plugins/aidd-context/skills/00-onboard/actions/03-present.md 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/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 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 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/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`. 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/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..1ab7b6c6 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-1.md @@ -0,0 +1,59 @@ +--- +status: done +--- + + + +# 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..5c60f11c --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-2.md @@ -0,0 +1,53 @@ +--- +status: done +--- + + + +# 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..a430c1b5 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-3.md @@ -0,0 +1,73 @@ +--- +status: done +--- + + + +# 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..19a8ad6a --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-4.md @@ -0,0 +1,84 @@ +--- +status: done +--- + + + +# 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..d411fdd1 --- /dev/null +++ b/aidd_docs/tasks/2026_07/2026_07_08_onboard-tutorial-rebuild/phase-5.md @@ -0,0 +1,51 @@ +--- +status: done +--- + + + +# 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..204cc9a3 --- /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: implemented +--- + + + +# 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. | 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/CATALOG.md b/plugins/aidd-context/CATALOG.md index 78647903..07249a81 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -1,6 +1,6 @@ # aidd-context catalog -Auto-generated index of skills, agents, references and assets shipped by the `aidd-context` plugin. +Auto-generated framework content: agents, commands, rules, skills, and templates. > This file is automatically updated by the `scripts/summarize-markdown.js` script. @@ -45,12 +45,13 @@ 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` | [banner.txt](skills/00-onboard/assets/banner.txt) | - | | `assets` | [report.md](skills/00-onboard/assets/report.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.` | +| `references` | [flow.md](skills/00-onboard/references/flow.md) | - | +| `-` | [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 76bc2e2a..6dfb04a6 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,42 +1,32 @@ --- 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. -argument-hint: scan | report | run +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 -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. +```mermaid +flowchart LR + scan --> assess --> present --> run --> scan +``` ## 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 | +Run the actions in that order, looping. Read an action's file in `actions/` before running it. -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 | read the project | +| 02 | assess | decide the next step | +| 03 | present | show the screen | +| 04 | run | act on the reply | ## 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. -- 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. -- Requires only the `aidd-context` plugin installed and a working directory rooted in the target project. The `aidd_docs/` memory bank is not a prerequisite: 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. - -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. +- 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. 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..891caff1 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-scan.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-scan.md @@ -1,29 +1,27 @@ # 01 - Scan -Read the project once, silently, into a reusable 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 (`✓ ⚠ ✗` 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. +The project snapshot, printed nowhere. ## 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. - - ```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. +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. **List.** Gather installed AIDD plugins and skills via native discovery. +6. **Hold.** Keep the snapshot in context. Print nothing. ## 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. -- No report or command is emitted by this action. +- Scan prints nothing. +- 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 new file mode 100644 index 00000000..4ba9902c --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/actions/02-assess.md @@ -0,0 +1,25 @@ +# 02 - Assess + +Turn the snapshot into one decision. + +## Input + +The project snapshot. + +## Output + +The decision, ready to render. + +## 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. + - Absent: name a gap by function, never invent a command. + +## Test + +- 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/02-report.md b/plugins/aidd-context/skills/00-onboard/actions/02-report.md deleted file mode 100644 index 943cafe4..00000000 --- a/plugins/aidd-context/skills/00-onboard/actions/02-report.md +++ /dev/null @@ -1,26 +0,0 @@ -# 02 - Report - -Show the loud diagnostic and one ordered command list. Concrete, scannable, no lecture. - -## Input - -The snapshot from `01-scan` (statuses + installed skills), held in context, not printed. - -## Process - -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. -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. - -## 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. diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-present.md b/plugins/aidd-context/skills/00-onboard/actions/03-present.md new file mode 100644 index 00000000..8372be56 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -0,0 +1,38 @@ +# 03 - Present + +Render the screen the decision names. + +## Input + +The current decision. + +## Output + +The rendered screen, and the user's reply. + +## Process + +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. + - 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`. + - Flow or walk screen loads `@../references/flow.md`. +3. **Wait.** Offer the screen, take the reply. + +## Test + +- The framing line shows on the first report of the session only. +- An existing repo renders memory as step 1 of 2. +- A greenfield repo renders the stack first. +- The banner shows on entry screens only. +- 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/03-run.md b/plugins/aidd-context/skills/00-onboard/actions/03-run.md deleted file mode 100644 index 6e34f3e3..00000000 --- a/plugins/aidd-context/skills/00-onboard/actions/03-run.md +++ /dev/null @@ -1,25 +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`: `OK`, a step number, an explain 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. -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. - -## 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. 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..1bb70b26 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -0,0 +1,33 @@ +# 04 - Run + +Carry out the reply. + +## Input + +- The user's reply, per `@../references/run/replies.md`. +- The current decision, its resolved commands or a gap. + +## Output + +The reply carried out. + +## 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`. +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. + +## Test + +- `OK` runs AUTO unattended and pauses at each GUIDED. +- A MANUAL step is shown, never run. +- A gap invokes nothing. +- `?`/`back` re-render with no re-scan. +- A GUIDED handoff emits the return line. 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..42283623 --- /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 e7a595c2..811a6751 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -1,34 +1,65 @@ - + -🔍 — AIDD checkup +## Entry — greenfield · existing · idle · drift -🏗️ Foundations - ... -🧩 Context artifacts (optional) - <✓/✗ per artifact, inline> +```txt + -🚦 Dev flow - +👋 -✨ Do this next - 1. - ... +Your AIDD setup: + AI tools + Plugins ✅ + Memory - ↳ " · "explain project" (only when memory is filled) · stop> + - +```txt +Foundations — step of + + + () + + — > + +👉 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 + +```txt +🔍 + + Flow: + +👉 Next: [1] + +``` + +## [?] detail + +```txt +Details — + 1. () + + explain · explain project · recap · stop · back [<] +``` 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 34d5f304..00000000 --- a/plugins/aidd-context/skills/00-onboard/references/checks.md +++ /dev/null @@ -1,68 +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. - -## 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. - -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. - -## 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 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. - -## 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 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. - -## 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 | an open PR, or 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. Build never proves review or ship, so surface both when code looks done and let the user pick. - -`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. - -## 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..c8dac4c0 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/flow.md @@ -0,0 +1,27 @@ +# AIDD flow curriculum + +## Foundations (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`. + +## Feature flow — 8 steps + +| 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 | + +`[map]`: `brainstorm → spec* → plan → implement → assert → review → commit → PR` + +`*`: 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/order/idle-menu.md b/plugins/aidd-context/skills/00-onboard/references/order/idle-menu.md new file mode 100644 index 00000000..1601a00e --- /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, the idle menu offers four choices. + +| 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` | +| 4 | explore | `aidd-context:11-explore` + anything not in 1-3 | + +- 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/order/ranking.md b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md new file mode 100644 index 00000000..d62a726f --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/order/ranking.md @@ -0,0 +1,10 @@ +# Next-action order + +First match wins. + +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. + +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..0637cff4 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/order/screen-map.md @@ -0,0 +1,9 @@ +# Screen map + +| 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-tiers.md b/plugins/aidd-context/skills/00-onboard/references/run-tiers.md deleted file mode 100644 index a03e6905..00000000 --- a/plugins/aidd-context/skills/00-onboard/references/run-tiers.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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. - -## 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 | -| 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 `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. - -## Other replies - -| Reply | What happens | -| --------------- | --------------------------------------------------------------------------------------------- | -| a step number | Run that one step per its tier | -| 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 | -| 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. 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..a7776ec2 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -0,0 +1,14 @@ +# Replies + +| Reply | Effect | +| ------------- | --------------------------------------------------------------------------------- | +| 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 | +| `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/run/return.md b/plugins/aidd-context/skills/00-onboard/references/run/return.md new file mode 100644 index 00000000..8654e287 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/run/return.md @@ -0,0 +1,3 @@ +# Return to onboard + +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/run/tiers.md b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md new file mode 100644 index 00000000..94ce4345 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/run/tiers.md @@ -0,0 +1,12 @@ +# Tiers + +The tier is a default, overridable. + +| 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 | + +- 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. 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..f6601115 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/detection.md @@ -0,0 +1,18 @@ +# AI tool detection + +Which AI tools the project uses, and whether each has its memory wired. For the state block's AI-tools line. + +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/` or `CLAUDE.md` | `CLAUDE.md` | +| codex | `.codex/` | `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` | + +- 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/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..9070e4d4 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/done-rule.md @@ -0,0 +1,6 @@ +# Done rule (session ledger) + +Stops onboard from re-recommending a step already handled this session. In-context state, no file. + +- 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 new file mode 100644 index 00000000..fe44590d --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/hedge.md @@ -0,0 +1,12 @@ +# Plan-status hedge + +The plan's `status:` frontmatter refines the build-to-ship pin, so review is never skipped nor premature. + +| Plan `status:` | Pin | +| ---------------------------- | ------------------------------------- | +| `pending` | To implement | +| `in-progress` | Implement alone | +| `implemented` | Review | +| `reviewed` | Ship (commit, pull request) | +| `blocked` | surface the blocker, not a normal pin | +| the field is missing or unreadable | surface the plan as broken, not a normal 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 new file mode 100644 index 00000000..c0f57b54 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/state/zones.md @@ -0,0 +1,41 @@ +# State zones + +Disk/VCS checks that place the project. Each check is met, drift (present, off canonical shape), or missing. + +## Foundations + +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 | 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). +- 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. The pin sits on the furthest reached. + +| 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 | + +- `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, not templates, fixtures, examples, generated output, or installed-plugin trees. + +| 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/deeper than siblings | `aidd-dev:04-audit` | 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 e3efba1ba34ee6e7c26d8d07138076cb538508d8 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Fri, 10 Jul 2026 13:24:10 +0200 Subject: [PATCH 20/20] fix(aidd-context): onboard shows the stack, and its keys are pressable (#428) * fix(aidd-context): the state block carries the tech stack The foundations step count says "1 of 2" on an existing repo and "1 of 3" on a greenfield one, but the state block listed only AI tools, plugins and memory. The stack was a foundation the reader could not see, so the count had to be justified by a sentence the model was free to drop -- and did. Give the stack its own row. The count now reads off the block: a green stack means it does not count. Co-Authored-By: Claude Opus 4.8 * fix(aidd-context): onboard keys never collide with host shortcuts `?` opens the help prompt in Claude Code, so the detail key could never be pressed. `<` was a punctuation key for the same reason of habit, not need. Details moves to `[d]`, back to `[b]`, and a render rule reserves keys to letters and digits so the next key cannot repeat the mistake. Co-Authored-By: Claude Opus 4.8 --------- Co-authored-by: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- .../skills/00-onboard/actions/03-present.md | 4 +++- .../aidd-context/skills/00-onboard/actions/04-run.md | 2 +- .../aidd-context/skills/00-onboard/assets/report.md | 11 ++++++----- .../skills/00-onboard/references/run/replies.md | 4 ++-- 5 files changed, 13 insertions(+), 10 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 07249a81..1783a184 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -1,6 +1,6 @@ # aidd-context catalog -Auto-generated framework content: agents, commands, rules, skills, and templates. +Auto-generated index of skills, agents, references and assets shipped by the `aidd-context` plugin. > This file is automatically updated by the `scripts/summarize-markdown.js` script. 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 8372be56..5c60a777 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-present.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-present.md @@ -16,12 +16,14 @@ The rendered screen, and the user's reply. - 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. + - The state block carries every foundation, so the foundations step count reads off it. - 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 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 `[?]`. + - Command ids, tier clauses, and lookahead only under `[d]`. + - Keys are letters or digits. Never `?`, `!`, `/`, `@`, `#`: the host takes those. 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/actions/04-run.md b/plugins/aidd-context/skills/00-onboard/actions/04-run.md index 1bb70b26..2791d965 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/04-run.md +++ b/plugins/aidd-context/skills/00-onboard/actions/04-run.md @@ -29,5 +29,5 @@ The reply carried out. - `OK` runs AUTO unattended and pauses at each GUIDED. - A MANUAL step is shown, never run. - A gap invokes nothing. -- `?`/`back` re-render with no re-scan. +- `d`/`back` re-render with no re-scan. - A GUIDED handoff emits the return line. diff --git a/plugins/aidd-context/skills/00-onboard/assets/report.md b/plugins/aidd-context/skills/00-onboard/assets/report.md index 811a6751..e100e2b7 100644 --- a/plugins/aidd-context/skills/00-onboard/assets/report.md +++ b/plugins/aidd-context/skills/00-onboard/assets/report.md @@ -8,9 +8,10 @@ 👋 Your AIDD setup: - AI tools - Plugins ✅ - Memory + AI tools + Plugins ✅ + Tech stack <✅ established | ❌ not chosen yet> + Memory @@ -55,11 +56,11 @@ Foundations — step of ``` -## [?] detail +## [d] detail ```txt Details — 1. () - explain · explain project · recap · stop · back [<] + explain · explain project · recap · stop · back [b] ``` 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 a7776ec2..9108bf7c 100644 --- a/plugins/aidd-context/skills/00-onboard/references/run/replies.md +++ b/plugins/aidd-context/skills/00-onboard/references/run/replies.md @@ -4,8 +4,8 @@ | ------------- | --------------------------------------------------------------------------------- | | 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 | +| `d` / `details` | expand the full detail (command ids, tier clauses, per-check reasons), read-only | +| `b` / `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 |