diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b1e7b1d3..6fc0368d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-marketplace.json", "name": "aidd-framework", - "version": "5.0.2", + "version": "5.0.3", "description": "Official plugin marketplace for the AI-Driven Development framework", "owner": { "name": "AI-Driven Dev" @@ -31,7 +31,7 @@ { "name": "aidd-pm", "source": "./plugins/aidd-pm", - "description": "Product management: ticket-info, user-stories-create, prd, spec", + "description": "Product management: ticket-info, user-stories, prd, spec", "strict": true, "recommended": true }, @@ -48,6 +48,13 @@ "description": "Meta-cognition: refine input through brainstorming, refine output through challenge and condensed communication mode.", "strict": true, "recommended": true + }, + { + "name": "aidd-ui", + "source": "./plugins/aidd-ui", + "description": "ALPHA, not ready for use. UI and UX concern: design, review, and improve frontend interfaces.", + "strict": true, + "recommended": false } ] } diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 60d26dec..8ed28f73 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -2,6 +2,10 @@ version: 2 updates: - package-ecosystem: "github-actions" directory: "/" + # Target `next`, not `main`. `main` only takes the weekly promotion PR and + # the Release PR (see RELEASE.md); dep updates batch on `next` and ship in + # the weekly release instead of cutting off-cycle releases. + target-branch: "next" schedule: interval: "weekly" day: "monday" @@ -11,10 +15,10 @@ updates: include: "scope" labels: - "dependencies" - - "github-actions" - package-ecosystem: "npm" directory: "/" + target-branch: "next" schedule: interval: "weekly" day: "monday" @@ -24,4 +28,3 @@ updates: include: "scope" labels: - "dependencies" - - "npm" diff --git a/.github/labels.yml b/.github/labels.yml index 48bc27cd..25ecc914 100644 --- a/.github/labels.yml +++ b/.github/labels.yml @@ -1,5 +1,9 @@ # 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. +# # This file is the source of truth. When the GitHub label set drifts from # this file, sync manually with: # @@ -24,31 +28,19 @@ color: 0075ca - name: security - description: Security-sensitive issue or fix + description: Security-sensitive issue or fix (cross-cutting, add to any kind) color: B60205 - name: good first issue description: Good for newcomers color: 7057ff -- name: help wanted - description: Extra attention is needed - color: 008672 - # --- Dependencies -------------------------------------------------------- - name: dependencies description: Dependency update (dependabot) color: 0366d6 -- name: github-actions - description: GitHub Actions workflow change - color: "000000" - -- name: npm - description: npm dependency update - color: cb3837 - # --- Release tooling ----------------------------------------------------- - name: "autorelease: pending" diff --git a/.github/workflows/back-merge.yml b/.github/workflows/back-merge.yml index 2a234956..9bdf4af0 100644 --- a/.github/workflows/back-merge.yml +++ b/.github/workflows/back-merge.yml @@ -25,7 +25,7 @@ jobs: app-id: ${{ secrets.AIDD_BOT_APP_ID }} private-key: ${{ secrets.AIDD_BOT_PRIVATE_KEY }} - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: ref: next fetch-depth: 0 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3334d65f..356729c1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,7 +22,7 @@ jobs: contents: read pull-requests: read steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: fetch-depth: 0 - uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed # v6.2.1 @@ -94,7 +94,7 @@ jobs: if: needs.release-please.outputs.release_created == 'true' runs-on: ubuntu-latest steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Build clean marketplace bundle # A self-contained marketplace a user can extract and register with @@ -141,7 +141,7 @@ jobs: - { tool: codex, mode: flat, flag: "--flat" } - { tool: opencode, mode: flat, flag: "--flat" } steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 with: @@ -193,7 +193,7 @@ jobs: echo "released=false" >> $GITHUB_OUTPUT fi - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 if: steps.check.outputs.released == 'true' - name: Get plugin version diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index b2bd1ab6..68b81d32 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -28,7 +28,7 @@ jobs: language: [javascript-typescript] steps: - name: Checkout - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Initialize CodeQL uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2 diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index b3ae480a..291ab085 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -6,9 +6,9 @@ name: Validate on: push: - branches: [main] + branches: [main, next] pull_request: - branches: [main] + branches: [main, next] permissions: contents: read @@ -22,7 +22,7 @@ jobs: CI: "true" steps: - name: Checkout - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Setup Node uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7eef9bd7..4afd4c19 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,9 +1,10 @@ { - ".": "5.0.2", + ".": "5.0.3", "plugins/aidd-context": "2.0.1", "plugins/aidd-dev": "2.0.0", "plugins/aidd-vcs": "2.0.0", "plugins/aidd-pm": "2.0.0", "plugins/aidd-orchestrator": "2.0.0", - "plugins/aidd-refine": "2.0.0" + "plugins/aidd-refine": "2.0.0", + "plugins/aidd-ui": "0.1.0-alpha.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 473eb113..aee95075 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [5.0.3](https://github.com/ai-driven-dev/framework/compare/v5.0.2...v5.0.3) (2026-06-23) + + +### Miscellaneous + +* **deps-dev:** bump js-yaml from 4.2.0 to 5.0.0 ([#322](https://github.com/ai-driven-dev/framework/issues/322)) ([f71bdd2](https://github.com/ai-driven-dev/framework/commit/f71bdd2be31c34aa43e5280659432fb3a9f1cdab)) + ## [5.0.2](https://github.com/ai-driven-dev/framework/compare/v5.0.1...v5.0.2) (2026-06-22) diff --git a/CLAUDE.md b/CLAUDE.md index bf7514c5..0a8d1308 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,33 +1,41 @@ # CLAUDE.md -> IMPORTANT: On first conversation message: -> -> - say "AI-Driven Development ON - Date: {current_date}, TZ: {current_timezone}." to User. - -## Behavior Guidelines - -All instructions and information above are willing to be up to date, but always remind yourself that USER can be wrong, be critical of the information provided, and verify it against the project's actual state. - -- Be anti-sycophantic - don't fold arguments just because I push back -- Stop excessive validation - challenge my reasoning instead -- Avoid flattery that feels like unnecessary praise -- Don't anthropomorphize yourself - -## Technical guidelines - -- Do not commit or push yourself unless I ask you to. -- For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. -- Never duplicate across docs - link to the canonical home. - -### Answering Guidelines - -- Don't assume your knowledge is up to date. -- Be 100% sure of your answers. -- If unsure, say "I don't know" or ask for clarification. -- Never say "you are right!", prefer anticipating mistakes. +> 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 @@ -41,6 +49,6 @@ All instructions and information above are willing to be up to date, but always @aidd_docs/memory/vcs.md -- If memory is not loaded above: run `ls -1tr aidd_docs/memory/` then read each file -- If needed: load files from `aidd_docs/memory/external/*` when user request it -- If needed: load files from `aidd_docs/memory/internal/*`, you have to think about it +- 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 1fb74f33..b926b083 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,6 +43,16 @@ make setup `make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks. +### Markdown links + +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: + +```bash +pnpm exec lefthook install --force +``` + +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: @@ -68,16 +78,9 @@ One scope per commit (split cross-plugin changes). The types, the scopes, and th ## 3. Open a pull request -- Branch off `next` and target `next` (the integration branch); `hotfix/*` branches off `main` for urgent production fixes. See [`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: - - | Label | When to use | - | ----- | ----------- | - | `bug` | A fix for broken behaviour. | - | `enhancement` | A new skill, agent, rule, or feature. | - | `documentation` | A docs-only change (README, CONTRIBUTING, skill docs). | - | `security` | A security-sensitive change or fix. | +- **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). diff --git a/README.md b/README.md index 7ee5ad88..f0a9cbbf 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

🇫🇷 The first French open-source framework for AI-driven development.

- 6 plugins · 38 skills · 3 agents · MIT + 7 plugins · 40 skills · 2 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -152,7 +152,7 @@ flowchart TD ## 🧩 Plugins -Six plugins covering the whole SDLC — **install all of them**; they're designed to work together. +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.) @@ -178,7 +178,7 @@ SDLC loop: sdlc, plan, implement, assert, audit, review, test, refactor, debug, ### 🌿 [aidd-vcs](plugins/aidd-vcs/README.md) -`4 skills` · stable +`5 skills` · stable Commits, pull / merge requests, release tags, issue creation. @@ -211,6 +211,17 @@ Meta-cognition: brainstorm, challenge, condense, shadow-areas, fact-check. Label an issue, get a PR; re-label, get the review applied. + + + +
+ +### 🎨 [aidd-ui](plugins/aidd-ui/README.md) 🚧 + +`1 skill` · **alpha — not ready** + +UI and UX: design, review, and improve frontend interfaces. ⚠️ Alpha (`0.1.0-alpha.0`), smoke-test only — do not rely on it yet. +
diff --git a/RELEASE.md b/RELEASE.md index 6b56092c..8eb93edc 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -21,7 +21,9 @@ For who may merge and release, see [`GOVERNANCE.md`](GOVERNANCE.md). ## 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`. +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 diff --git a/UPGRADE.md b/UPGRADE.md index 509ece6e..941f0bf6 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -95,7 +95,7 @@ Invocation in v4 is `plugin:NN-action`. Where a column says "sub-flow", the old |---|---| | `/brainstorm` | `aidd-refine:01-brainstorm` | | `/challenge` | `aidd-refine:02-challenge` | -| `/create_user_stories` | `aidd-pm:02-user-stories-create` | +| `/create_user_stories` | `aidd-pm:02-user-stories` | | `/ticket_info` | `aidd-pm:01-ticket-info` | ### plan diff --git a/aidd_docs/README.md b/aidd_docs/README.md index 166a8e4d..d4de7c2a 100644 --- a/aidd_docs/README.md +++ b/aidd_docs/README.md @@ -38,7 +38,7 @@ Skills are grouped into plugins by domain. Install only the plugins you need. | ----------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- | | aidd-context | Bootstrap, project init, generation of context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces), mermaid diagrams, learn, discovery | `02-project-memory`, `03-context-generate`, `09-mermaid` | | aidd-refine | Meta-cognition: brainstorm, challenge prior work, condensed communication mode | `01-brainstorm`, `02-challenge`, `03-condense` | -| aidd-pm | Product management: ticket info, user stories, PRD, spec | `01-ticket-info`, `02-user-stories-create`, `03-prd`, `04-spec` | +| aidd-pm | Product management: ticket info, user stories, PRD, spec | `01-ticket-info`, `02-user-stories`, `03-prd`, `04-spec` | | aidd-dev | Code transformation: Dev SDLC orchestrator, plan, implement, assert, audit, review, test, refactor, debug, for-sure | `00-sdlc`, `01-plan`, `02-implement`, `05-review`, `06-test` | | aidd-vcs | VCS workflows: commit, pull/merge request, release tag, issue creation | `01-commit`, `02-pull-request`, `04-issue-create` | | aidd-orchestrator | Async orchestration of the SDLC on labeled issues (optional, extra) | `00-async-dev` (router with setup / run / review sub-flows) | @@ -102,7 +102,7 @@ AIDD is delivered as a plugin marketplace. Pick what you need; do not install ev | aidd-refine | 01-brainstorm, 02-challenge, 03-condense, 04-shadow-areas, 05-fact-check | | aidd-dev | 00-sdlc, 01-plan, 02-implement, 03-assert, 04-audit, 05-review, 06-test, 07-refactor, 08-debug, 09-for-sure | | aidd-vcs | 01-commit, 02-pull-request, 03-release-tag, 04-issue-create | -| aidd-pm | 01-ticket-info, 02-user-stories-create, 03-prd, 04-spec | +| aidd-pm | 01-ticket-info, 02-user-stories, 03-prd, 04-spec | Each plugin is independently installable; install incrementally. Smaller surface, fewer triggers competing. @@ -112,7 +112,7 @@ A typical change cycles through skills from several plugins. The order below is 1. **Bootstrap** (only for a brand-new project): `aidd-context:01-bootstrap` imagines the stack and architecture, comparing candidate stacks and writing an `INSTALL.md`. Skip this step on an existing project. 2. **Project init** (once per project, re-runnable to refresh): `aidd-context:02-project-memory` scaffolds `aidd_docs/`, the memory bank, and the AI context files for the tools you use. Re-running later refreshes the scaffold without overwriting your customizations. -3. **Frame the request**: `aidd-refine:01-brainstorm` to clarify, `aidd-pm:01-ticket-info` to pull tracker data, `aidd-pm:02-user-stories-create` and `aidd-pm:03-prd` or `aidd-pm:04-spec` to formalize scope. +3. **Frame the request**: `aidd-refine:01-brainstorm` to clarify, `aidd-pm:01-ticket-info` to pull tracker data, `aidd-pm:02-user-stories` and `aidd-pm:03-prd` or `aidd-pm:04-spec` to formalize scope. 4. **Plan**: `aidd-dev:01-plan` produces the technical plan, component behavior model, or design-image extraction. 5. **Implement and assert**: `aidd-dev:02-implement` writes code against the plan; `aidd-dev:03-assert` verifies the result. 6. **Review**: `aidd-dev:05-review` for code and functional review; `aidd-refine:02-challenge` to stress-test the result. diff --git a/aidd_docs/memory/vcs.md b/aidd_docs/memory/vcs.md index 4fc34de5..2f3c7e46 100644 --- a/aidd_docs/memory/vcs.md +++ b/aidd_docs/memory/vcs.md @@ -16,15 +16,33 @@ type/ticket-short-description ### Types -| Prefix | Usage | Branch from | PR target | -| --- | --- | --- | --- | -| `feat/` | New feature | `next` | `next` | -| `fix/` | Bug fix | `next` | `next` | -| `docs/` | Documentation only | `next` | `next` | -| `refactor/` | Code change (no feat/fix) | `next` | `next` | -| `chore/` | Build, config, deps | `next` | `next` | -| `test/` | Add/update tests | `next` | `next` | -| `hotfix/` | Urgent production fix | `main` | `main` | +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 +`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`** | + +#### Routing rule (strict) + +- Everything batches on `next` and ships in the weekly release. +- **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). + +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 +[Commit Convention](#commit-convention) below (mirrors `commitlint.config.cjs`). ### Examples diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md new file mode 100644 index 00000000..5ef7e5b2 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md @@ -0,0 +1,55 @@ +--- +status: done +--- + +# Instruction: Canonical routing table + +Part of [`plan.md`](./plan.md). Dependency root — author before all other phases. + +## Architecture projection + +```txt +aidd_docs/memory/ +└── vcs.md 🔁 Branch-Naming "Types" table gains 2 columns (triage label, + routing ✓/-) + a strict routing callout + a triage-only note. +``` + +## Tasks to do + +### `1)` Replace the branch "Types" table with the dense canonical table + +> One grid that maps kind → prefix → commit type → triage label → destination. + +1. Under `## Branch Naming Convention` → `### Types`, replace the current 4-column table with: + + | Kind | Branch prefix | Commit type | Triage label | `next` | `main` | + | ---- | ------------- | ----------- | ------------ | :----: | :----: | + | Feature | `feat/` | `feat` | `enhancement` | ✓ | – | + | Fix | `fix/` | `fix` | `bug` | ✓ | – | + | Docs | `docs/` | `docs` | `documentation` | ✓ | – | + | Refactor | `refactor/` | `refactor` | – | ✓ | – | + | Chore | `chore/` | `chore` | `dependencies` | ✓ | – | + | Test | `test/` | `test` | – | ✓ | – | + | Hotfix | `hotfix/` | `fix` | `bug` | – | ✓ | + +2. Keep the existing `### Format` and `### Examples` blocks unchanged. + +### `2)` Add the strict routing callout + triage-only note + +> Make the rule unmissable and kill the label/route confusion. + +1. Immediately under the table, add a short callout, in substance: + - The branch **prefix alone** decides the PR target — not a label, not a board field. + - Everything batches on `next`; **only `hotfix/*` targets `main`** (urgent production fix, out of cycle). + - The `aidd-vcs:02-pull-request` skill reads this table to set the base branch automatically. +2. Add the triage-only note: labels categorize, they never route; `security` is cross-cutting — add it to any kind when the change is security-sensitive. +3. Confirm the commit-type and changelog definitions are untouched (the `## Commit Convention` section stays as-is; the table's "commit type" column is illustrative, not a redefinition). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | The dense 6-column table renders in `vcs.md`; exactly one row routes to `main` (`hotfix`); all others to `next`. | +| 1 | The table is the only place in the repo with the kind·prefix·label·✓/- grid (`grep -rl` for a unique cell string returns only `vcs.md`). | +| 2 | A "routing rule (strict)" callout states prefix-decides-target and the single `hotfix→main` exception; a triage-only note is present. | +| 2 | `## Commit Convention` section is byte-identical to before (no commit-type or scope changes). | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md new file mode 100644 index 00000000..3a4b9359 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md @@ -0,0 +1,43 @@ +--- +status: done +--- + +# Instruction: Label set + dependabot (atomic) + +Part of [`plan.md`](./plan.md). **Atomic unit** — both files change together; never drop a label from one without the other (else dependabot recreates it ungoverned). + +## Architecture projection + +```txt +.github/ +├── labels.yml 🔁 11 → 8 labels + triage-only header note. +└── dependabot.yml 🔁 `labels:` keys lose `npm` and `github-actions`. +``` + +## Tasks to do + +### `1)` Trim `labels.yml` to 8 + header note + +> Keep triage types + required automation labels; cut the noise. + +1. Keep: `bug`, `enhancement`, `documentation`, `security`, `good first issue`, `dependencies`, `autorelease: pending`, `autorelease: tagged`. +2. Remove: `help wanted`, `npm`, `github-actions`. +3. Add a header comment: labels are **triage only**; routing is by branch prefix (see `aidd_docs/memory/vcs.md`); keep one triage label per change. +4. Leave colors/descriptions of kept labels intact (refine `security` description to note it is cross-cutting). + +### `2)` Drop ecosystem labels from `dependabot.yml` + +> The `dependencies` umbrella is enough at this scale. + +1. In the `github-actions` ecosystem block, set `labels: ["dependencies"]` (remove `github-actions`). +2. In the `npm` ecosystem block, set `labels: ["dependencies"]` (remove `npm`). +3. Touch nothing else (schedule, prefixes, limits stay). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | `grep '^- name:' .github/labels.yml` lists exactly the 8 kept labels; `help wanted`, `npm`, `github-actions` absent. | +| 1 | Header comment states triage-only + routing-by-prefix + link to vcs.md. | +| 2 | Both ecosystem blocks in `dependabot.yml` have `labels: ["dependencies"]` only. | +| 1+2 | `grep -rn -e 'help wanted' -e '"npm"' -e 'github-actions' .github/labels.yml .github/dependabot.yml` returns no orphan reference to a dropped label. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md new file mode 100644 index 00000000..6e16a94d --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md @@ -0,0 +1,56 @@ +--- +status: done +--- + +# Instruction: Docs point to canonical (no duplication) + +Part of [`plan.md`](./plan.md). Depends on phase 1 (the anchor target must exist). + +## Architecture projection + +```txt +. +├── CONTRIBUTING.md 🔁 Inline label table (L75-80) → link to vcs.md table; +│ routing prose (L71) → short pointer + link. +└── RELEASE.md 🔁 "Where your change goes" links the vcs.md table; + flow mermaid kept; any restated routing prose trimmed. +``` + +## User Journey + +```mermaid +flowchart TD + A[Contributor lost] --> B[CONTRIBUTING hub] + B -->|naming + routing| C[vcs.md table] + B -->|release flow| D[RELEASE.md] + B -->|who merges| E[GOVERNANCE.md] +``` + +## Tasks to do + +### `1)` De-duplicate `CONTRIBUTING.md` + +> It is already a hub; remove the one restated taxonomy. + +1. Replace the inline label table (the `| Label | When to use |` block) with a one-line pointer to the canonical table: triage labels + routing live in `aidd_docs/memory/vcs.md` (link to the `#types` anchor). Keep the PR-labelling instruction itself. +2. Trim the routing prose ("Branch off `next`… `hotfix/*` off `main`…") to a short gist + link to the vcs.md table; do not restate the full table. +3. Verify the three hub links resolve and are one hop each: naming/routing → vcs.md, release → RELEASE.md, merge → GOVERNANCE.md. +4. Confirm the issue-template path still holds: opening a 🐛 / ✨ issue applies `bug` / `enhancement` automatically (no edit — verification only). + +### `2)` Point `RELEASE.md` at the canonical table + +> Anyone landing here finds the table by link, not a copy. + +1. In `## Where your change goes`, add a sentence linking the canonical prefix→target table at `aidd_docs/memory/vcs.md#types`. +2. Keep the existing flow mermaid and the commit-type→changelog table (release domain, matches release-please-config — leave as-is). +3. Ensure no prefix→target *table* is restated here (the mermaid is a flow diagram, allowed). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | `CONTRIBUTING.md` no longer contains the `| Label | When to use |` table; a link to `vcs.md` triage/routing replaces it. | +| 1 | CONTRIBUTING contains exactly one link each to vcs.md, RELEASE.md, GOVERNANCE.md reachable in one hop. | +| 1 | Creating an issue via each template yields it pre-labelled (`labels:` keys confirmed present in both templates). | +| 2 | `RELEASE.md` "Where your change goes" links `vcs.md#types`; no prefix→target table restated. | +| 1+2 | A text search for a unique cell of the canonical grid returns hits only in `vcs.md`, not in CONTRIBUTING/RELEASE/GOVERNANCE. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md new file mode 100644 index 00000000..c1fa8f54 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md @@ -0,0 +1,64 @@ +--- +status: done +--- + +# Instruction: PR automation routes by prefix + +Part of [`plan.md`](./plan.md). Depends on phase 1 (the skill reads the canonical table from memory). Keep the plugin **generic** — it reads project memory, never hardcodes `next`. + +## Architecture projection + +```txt +plugins/aidd-vcs/skills/02-pull-request/ +├── actions/01-pull-request.md 🔁 Base resolution derives target from branch +│ prefix via project memory; +auto-label step. +└── assets/branch.md 🔁 Stale `aidd_docs/` → `docs/` prefix. +``` + +## User Journey + +```mermaid +flowchart TD + A[Head branch e.g. feat/x] --> B{prefix in project-memory table?} + B -->|yes| C[base = that row's PR target] + B -->|no| D[fallback: origin/HEAD, then main/master/develop/staging] + C --> E[open draft PR] + D --> E + E --> F[apply matching triage label if defined + exists] +``` + +## Tasks to do + +### `1)` Base resolution by branch prefix + +> Fixes feat/→main: `next` was absent from the candidate list. + +1. In `## Process` step 3 (Base resolution), insert a match BEFORE the `origin/HEAD` fallback: if the project's branch-naming convention (project memory) maps the head branch's prefix to a PR target, use that target. +2. Keep the existing `origin/HEAD` → `main/master/develop/staging` as the fallback when no prefix mapping exists. +3. Keep it generic: phrase as "the branch-naming convention in project memory", never hardcode `next`. +4. Surface the chosen base and the reason ("prefix `feat/` → `next` per project convention") during the step-7 validation. + +### `2)` Auto-apply the triage label + +> A PR is born typed, matching the issue model. + +1. Add a numbered step after "Open draft": when the convention maps the head prefix to a triage label and that label exists in the repo, apply it; skip silently otherwise. +2. State explicitly: labels triage only; this step never changes the base resolved earlier. +3. Update the `## Test` checklist to cover prefix-derived base + label application; extend Outputs if a label field is warranted. + +### `3)` Fix the stale generic template + +> `branch.md` is a generic distributable template; correct the bug only. + +1. In `assets/branch.md` Types table, change the `aidd_docs/` prefix row to `docs/`. +2. No other change — it stays a generic naming template (no `next`/`main`, no repo-specific routing). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | Step 3 lists a prefix→target derivation via project memory BEFORE the origin/HEAD fallback; no literal `next` hardcoded. | +| 1 | Tracing the doc logic: a `feat/*` head resolves base `next`; `hotfix/*` resolves `main` (per the vcs.md table). | +| 2 | A numbered step applies the prefix-mapped triage label post-open, gated on label existence, marked triage-only. | +| 2 | `## Test` checklist asserts the prefix-derived base and the applied label. | +| 3 | `assets/branch.md` shows `docs/`; no `aidd_docs/` remains; no `next`/`main` added. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md new file mode 100644 index 00000000..2ffa2ac9 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md @@ -0,0 +1,67 @@ +--- +status: done +--- + +# Instruction: Board playbook (Project 8) + +Part of [`plan.md`](./plan.md). The board is GitHub Project config, not repo files — deliver a **playbook** the maintainer applies. Independent of phases 1-4 (can run in parallel). + +## Architecture projection + +```txt +docs/ +└── MAINTAINERS.md 🔁 New "## Project board (Project 8)" section: the + field/status/view playbook (gh commands + UI steps). +``` + +> Confirm `MAINTAINERS.md` is the right host at implement; if it does not fit, create `docs/BOARD.md` and link it from MAINTAINERS + CONTRIBUTING. + +## User Journey + +```mermaid +flowchart TD + A[Maintainer opens playbook] --> B[Drop Work type + Phases] + B --> C[Keep Priority] + C --> D[Set Status options] + D --> E[Wire built-in workflows] + E --> F[Add Timeline view] +``` + +## Tasks to do + +### `1)` Write the field-cleanup steps + +> Each board property answers one question; kill the duplicates. + +1. **Drop "Work type"** (duplicates the Type label) and **"Phases"** (duplicates Status/Milestone). Provide the `gh` inspection + deletion commands, e.g.: + - `gh project field-list 8 --owner ai-driven-dev` to read field IDs. + - `gh project field-delete ` for each dropped field. +2. **Keep Priority** — state explicitly it stays (P0·P1·P2), no action. + +### `2)` Status options + automation + +> Status carries the flow and advances itself. + +1. Set Status single-select options: `Todo · In progress · In review · Ready · Done`. Note this is a single-select field edit (UI; `gh project field-create` only creates new fields — document the UI path to edit the existing Status options, with the `gh` create path as the from-scratch alternative). +2. Document the built-in workflow wiring (Project → Workflows, UI): + - item added → **Todo** + - PR linked / ready for review → **In review** + - code review approved → **Ready** + - PR merged / issue closed → **Done** +3. Flag which transitions are GitHub built-ins vs. manual moves (In progress is typically manual). + +### `3)` Timeline view + verification checklist + +> The "phases" replacement Alex asked for. + +1. Add a **Timeline** view (UI: New view → Timeline; date field = target/milestone). Document the steps. +2. End the section with a tick-box checklist mirroring the spec board done-when: Work type removed · Phases removed · Priority kept · Status options set · automation enabled · Timeline view present. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | Playbook gives concrete `gh project field-list`/`field-delete` commands for Work type + Phases, and states Priority is kept. | +| 2 | Playbook lists the 5 Status options and the 4 built-in transitions, marking built-in vs manual. | +| 3 | Playbook documents adding a Timeline view and ends with a board-done-when checklist. | +| all | Section is self-contained: a maintainer can apply it end-to-end without re-deriving anything from the Loom. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md new file mode 100644 index 00000000..2e8f91ca --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md @@ -0,0 +1,60 @@ +--- +objective: "The change taxonomy + routing rule live in one canonical table (vcs.md); every other surface links to it or derives from it; the board playbook is delivered." +status: implemented +--- + +# Plan: Unify the change taxonomy into one source of truth + a projected board + +## Overview + +| Field | Value | +| ---------- | --------------------------------------------------------------------- | +| **Goal** | One canonical routing table; all surfaces link/derive; board playbook. | +| **Source** | [`2026_06_23-unify-taxonomy.md`](../../specs/2026_06/2026_06_23-unify-taxonomy.md) (spec, VALID 100/100) | + +## Phases + +| # | Phase | File | +| --- | ------------------------------ | ---------------------------- | +| 1 | Canonical routing table | [`phase-1.md`](./phase-1.md) | +| 2 | Label set + dependabot (atomic)| [`phase-2.md`](./phase-2.md) | +| 3 | Docs point to canonical | [`phase-3.md`](./phase-3.md) | +| 4 | PR automation routes by prefix | [`phase-4.md`](./phase-4.md) | +| 5 | Board playbook (Project 8) | [`phase-5.md`](./phase-5.md) | + +## Resources + +| Source | Verified | +| ------------- | --------------------------- | +| `aidd_docs/memory/vcs.md` | Holds branch table (prefix · from · target) — no label column, no ✓/-. Becomes the dense canonical. | +| `RELEASE.md` | "Where your change goes" has a flow mermaid + commit→changelog table (matches release-please-config). | +| `CONTRIBUTING.md` | Already a hub: links vcs.md (commits L67), RELEASE (routing L71), GOVERNANCE (merge). Inline label table L75-80 is the one duplication. | +| `.github/labels.yml` | 11 labels. | +| `.github/dependabot.yml` | Applies `dependencies`+`npm` and `dependencies`+`github-actions` — must drop in lockstep with labels.yml. | +| `.github/ISSUE_TEMPLATE/bug_report.yml` / `feature_request.yml` | Already carry `labels: ["bug"]` / `["enhancement"]` — done-when "issue born typed" PRE-SATISFIED; verify-only. | +| `plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md` | Base resolution candidate list `main/master/develop/staging` — `next` absent (the feat/→main bug). | +| `docs/MAINTAINERS.md` | Existing maintainer-ops home — proposed host for the board playbook section. | + +## Decisions + +| Decision | Why | +| ---------- | -------------- | +| Canonical table lives in `vcs.md` (AI-auto-loaded memory) | PR skill + AI both read memory; flipping to a human doc would couple automation to a non-loaded file. | +| RELEASE keeps its flow mermaid | A flow diagram ≠ the mapping table; the prefix→target *table* stays single-homed in vcs.md, RELEASE links it. | +| Board playbook appended to `docs/MAINTAINERS.md` | Maintainer-ops already lives there; avoids a new orphan doc (no-sprawl ethos). Confirm fit at implement. | +| Issue templates: no edit | They already apply the Type label; editing would be churn. | +| Plugin `branch.md` / PR action stay generic | Distributable layer (ARCHITECTURE.md); they read project memory, never hardcode `next`. | + +## Spec done-when → phase coverage + +| Spec done-when | Phase | +| -------------- | ----- | +| Mapping exists once; others link | 1 (author) + 3 (link) | +| Strict: single production-routed row | 1 | +| Front-door routes 3 destinations, one hop | 3 | +| Label set reduced, triage-only, no routing-by-label | 2 | +| Dropped labels not recreated by automation | 2 | +| Issue born typed | pre-satisfied (verify in 3) | +| PR base + label by prefix | 4 | +| Board fields orthogonal (Work type, Phases gone; Priority kept) | 5 | +| Status lifecycle + automation + Timeline view | 5 | diff --git a/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md b/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md new file mode 100644 index 00000000..d540653c --- /dev/null +++ b/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md @@ -0,0 +1,49 @@ +# Unify the change taxonomy into one source of truth + a projected board + +## Target + +Define the change-classification taxonomy and its routing rule **once**, in a single canonical place that every other contributor-facing surface and the project board links to or derives from — never restates. + +## Hard constraints + +- One canonical home for the taxonomy/routing definition; every other document links to it rather than restating it (repo rule: never duplicate across docs). +- Routing (which branch a change targets) is **derived from the branch prefix**, never stored as a label or a board field. +- The canonical definition must be consumable by both the AI tooling (the always-loaded project memory) and humans, without a second copy existing. +- The distributable plugin templates stay generic — they are products shipped to other projects, not mirrors of this repo's own instance. +- Commit-type and changelog-section definitions are left unchanged (already aligned to Conventional Commits and the release tool). +- Board changes are delivered as a maintainer playbook (the board is external config), not as repo file edits; repo deliverables must not assume the board can be edited as repo files. +- Each board field and each label answers a distinct question; no field may duplicate another field or a label. + +## Non-goals + +- Renaming the `enhancement` label to `feature` — `enhancement` stays; the spec only documents that it is the label form of a `feat`/feature change. +- Any label-sync workflow or board automation beyond GitHub's built-in project workflows. +- Changing the allowed commit types or the changelog sections. +- Restructuring the generic plugin pull-request / branch templates beyond correcting a stale, incorrect prefix value. +- Building the board for the maintainer — the spec supplies the playbook; applying it is the maintainer's act. + +## Done-when + +- The change-kind → routing (next vs main) mapping exists in exactly one document; searching the repo finds that mapping rendered once, and every other doc that needs it contains a link to that single home. *(verify: text search shows one occurrence of the mapping table; the release doc and the contributor doc each link to it.)* +- The routing rule is strict and unambiguous: exactly one branch prefix routes to the production branch (the urgent-fix prefix); all other prefixes route to the integration branch. *(verify: the canonical table shows a single production-routed row.)* +- A single contributor front-door document routes a reader to naming+routing, the release flow, and the merge/governance rules, each reachable in one hop. *(verify: the front-door doc contains a link to each of the three; and a text search for the canonical routing table/sentence returns hits only in its canonical home, not in the front-door, release, or governance docs.)* +- The issue/PR label set is reduced to triage-type labels plus the automation labels the tooling requires; no label encodes routing, and a header states labels are triage-only. *(verify: the label list equals the agreed reduced set; a search finds no label used to decide routing.)* +- Labels removed from the canonical list are not recreated by any automation. *(verify: the dependency-update config no longer references the removed labels.)* +- An issue opened from a project issue template is created already carrying its Type label, with no manual step. *(verify: creating an issue via each template yields an issue pre-labelled with its type.)* +- A pull request opened by the project's PR automation targets the branch determined solely by the head branch's prefix, and carries the matching Type label. *(verify: a feature-prefixed branch produces a PR targeting the integration branch; the urgent-fix prefix targets production; the type label is present.)* +- The board exposes only orthogonal fields — the field that duplicated the Type label is gone, and the redundant phase field is gone — while Priority remains. *(verify: board playbook checklist confirms both fields removed and Priority kept.)* +- The board Status field carries the agreed lifecycle states and advances through them via built-in automation, and a Timeline view exists. *(verify: board playbook checklist confirms the Status options, the enabled built-in transitions, and the Timeline view.)* + +## Stakeholders + +- Decider: Baptiste (resolves any taxonomy/placement tradeoff). +- Owner: Baptiste & Alex (maintainers, long-term owners of the convention and the board). +- Consumer: public contributors (read the docs/board, open issues/PRs) and the AI tooling (reads the canonical memory, opens PRs, applies labels). + +## Context + +- Source: Alex's Loom review — the same taxonomy is currently re-spelled across branch prefix, commit type, label, and the board "Work type" field, and the four drift; a maintainer got lost finding routing info. The ask: fewer, clearer, non-duplicated, strict rules. +- Guiding principle agreed in brainstorm: one taxonomy, defined once, projected everywhere (docs, label, board field, timeline), advanced by automation, never re-typed by a human. +- Orthogonal property model agreed: Type → label; Priority → board field; Status → board field (auto-advanced); When → milestone/timeline; Effort/onboarding → the good-first-issue label; Routing → derived from branch prefix. +- Existing anchors that constrain the canonical definition: the commit linter (Conventional Commits) and the release tool's changelog sections are already correct and authoritative for their domains; the taxonomy mirrors them, it does not redefine them. +- The board is GitHub Project 8 (public roadmap + maintainer triage), configured outside the repo. diff --git a/aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md b/aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md new file mode 100644 index 00000000..fb56ee00 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md @@ -0,0 +1,145 @@ +# Diagnostic — duplications mémoire (skill 02-project-memory) + +> Statut : diagnostic read-only. Aucun fichier de skill modifié. Ce doc = base de validation avant fix. + +## Contexte + +Retour Alex : la génération de mémoire produit des duplications, et Codex 5.5 +n'arrive pas à l'initialiser. Deux symptômes investigués séparément. + +## Symptôme A — Codex ne peut pas init (le `@`) + +**Vérifié, puis rétracté en partie.** + +- Le `@` n'est PAS le standard Agent Skills. Standard = chemin relatif depuis + la racine du skill (`reference/guide.md`, lien md `[x](x)`). Le `@` = import + CLAUDE.md. Source : docs Anthropic + agentskills.io. +- **`aidd framework build --target codex` CONVERTIT** `@../x` → un lien `x` vers `../x` + (lien md, `@` retiré). → Codex reçoit des chemins résolvables. OK. +- **`aidd plugin install ` + `aidd ai install`** copie le `@` + **verbatim** → non résolvable sur Codex. +- Donc : bug réel **seulement** si un user installe la source brute sur Codex. + Inconnu : quel chemin un vrai user Codex emprunte (marketplace/build vs brut). +- Note : mes premiers `diff`/`grep` passés par rtk ont renvoyé de faux + "identique"/"0 match". rtk non fiable pour diff/grep ici. + +**Ouvert** : tracer le chemin de distribution Codex réel. + +## Symptôme B — duplications (cause trouvée) + +Duplication = **structurelle**, indépendante de Codex et du `@`. Trois facteurs +cumulés : + +1. **Sections de templates qui se chevauchent** : le même fait (framework, + zones du code, commandes de test…) est demandé par 2+ templates. +2. **Fill parallèle aveugle** (action `03-generate-memory`, étape 6 : "For each + selected template, in parallel") : chaque template rempli indépendamment, + sans voir les autres → le chevauchement devient duplication littérale, + garantie. C'est le multiplicateur. +3. **Aucune règle "un fait, un propriétaire"** : les Transversal rules couvrent + code→mémoire, jamais mémoire↔mémoire. Review 04 = "consistency", sans + dominance et sautable. + +## Méthode — comment trouver le niveau fin + +Le grain n'est ni le fichier ni la section : c'est le **fait demandé** (chaque +``). + +1. Inventaire des faits : extraire chaque `<...>` de chaque template. +2. Clé canonique : étiqueter par le fait réel (framework, entry point, + commande de test…), pas par le mot de la section. +3. Site de duplication = un fait canonique demandé par ≥2 templates. +4. Pondérer par proba de co-déclenchement (core fire toujours → core↔core + garanti). +5. Assigner un propriétaire unique (dominance). + +## Tension de design à respecter + +Le design existant a une philosophie assumée : chaque fichier mémoire = un +concern **auto-suffisant**, lisible seul. Un pointer mémoire↔mémoire est un +principe neuf qui se bat contre ça. On ne l'applique que quand le gain dépasse +la perte de lisibilité standalone. Re-nommer un framework (un mot) dans 2-3 +fichiers coûte moins qu'un pointer : on garde la mini-dup. + +## Audit single-responsibility + +| Concern | Responsabilité | Verdict | +| --- | --- | --- | +| `integration` | internal + external | **double** → reframe (voir plan #3) | +| `architecture` vs `codebase-map` | shape vs layout, mais Structure≡Areas | overlap → drop Structure | +| `deployment` vs `infra` | ship/run vs provisioning, "environments" dans les 2 | overlap → scope | +| `deployment` | pipeline+env+release+monitoring | large mais cohérent (ship/run) | +| `mobile`/`desktop` | incluent build&release ≡ `deployment` | overlap mineur, abandonné | +| autres (vcs, data, testing, auth, cli…) | single net | OK | + +Note écosystème (hors scope) : `integration.md` est gaté par la capability +`api`. Mais consommer des services externes n'exige pas d'exposer une API. Gate +douteux → à revoir dans `capability-signals`, séparément. + +## Table de dominance — réduite haute-valeur + +### À appliquer (gain net) + +| # | Fait | Action | Type | +| --- | --- | --- | --- | +| 2 | Zones top-level + responsabilité | `codebase-map.Areas` possède → drop `architecture.## Structure` | drop | +| 3 | Intégrations | reframe `integration` en intégrations externes (voir plan) | reframe | +| 4 | Libs de domaine | `architecture.Stack` = macro only, ne re-liste pas une lib déjà possédée par une capability | scope (inversé) | +| 8 | "Où routes définies" | `api.Style` = serveur/RPC ; `navigation.Routing` = client | scope | +| 12 | CI/CD vs provisioning | `deployment.Pipeline` = CI/CD ; `infra.Tooling` = provisioning | scope | + +### Abandonnés (pointer < dup, casse l'auto-suffisance) + +`#1` framework (un mot), `#5` commandes (gate vs itération, buts distincts), +`#9` authz, `#10` auth socket, `#11` environnements, `#13` release/packaging, +`#14` SDK externe. + +## Le vrai multiplicateur : le fill parallèle aveugle + +Même templates parfaits, le fill parallèle (`03.6`) re-écrit un même fait dans +chaque template dont le placeholder matche. **C'est ici que se gagne le gros de +la dédup.** + +## Plan d'exécution + +### Templates + +1. `core/architecture.md` — **drop `## Structure`** (modules + entry point). + Possédé par `codebase-map`. +2. `core/architecture.md` — **Stack, bullet 2** → "libs transversales only ; + une lib couverte par une capability (ORM, runner, form lib) vit là-bas". +3. `api/integration.md` — **reframer en intégrations externes** (responsabilité + unique). Le fichier mélange Internal (flux entre modules → appartient à + `architecture.How it fits together`) + External (services tiers). Fix : + - intro : "internal communication and external services" → "how this system + integrates with external/third-party services" ; + - drop `## Internal` ; + - garder `## External services` + diagramme (carte des intégrations externes). + Ne pas juste couper Internal (sinon fichier mal nommé à une section) — c'est + un reframe de responsabilité. +4. `api/api.md` — **Style, bullet 1** → préfixer "Server/RPC surface" + "server + routes". +5. `ui/navigation.md` — **Routing, bullet 1** → préfixer "Client routing" + + "client routes". + +### Actions / règles + +6. `actions/03-generate-memory.md` — **étape 6** : retirer "in parallel" ; + "For each selected template (en tenant compte des faits déjà capturés par les + templates précédents, pour ne pas redire un fait)". +7. `SKILL.md` transversal + `actions/04-review-memory.md` étape 2 : + - SKILL.md : "Each fact lives in exactly one memory file ; another file + references it, never restates it." (uniquement pour les faits de la table + réduite) + - 04 : check "no fact duplicated across files ; si dupliqué, garder dans le + fichier propriétaire, drop la copie." + +### Validation post-édit + +- `aidd framework build --target codex` passe sans erreur. +- Relire les templates touchés : chacun reste lisible seul. + +### Hors scope (suivi séparé) + +- Symptôme A (distribution Codex `@` brut vs build) : tracer le chemin réel. +- Gate de `integration` sous capability `api` : à revoir dans capability-signals. diff --git a/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/empirical-results.md b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/empirical-results.md new file mode 100644 index 00000000..7d3d4b19 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/empirical-results.md @@ -0,0 +1,51 @@ +# Preuve empirique — duplication mémoire (avant décision) + +Fixture minimal (`scratchpad/fixture`) : API Node/Express + Knex/sqlite + Jest. +Déclenche core + api + database. Fill rejoué à la main de deux façons : + +- **run actuel** : fill aveugle (chaque template rempli indépendamment, comme + l'action `03.6` le dit aujourd'hui). +- **run fixé** : templates haut niveau inchangés + logique de propriétaire + (architecture sans Structure & sans libs de domaine ; codebase-map possède + zones+entry ; integration reframé externe ; "un fait = un fichier"). + +## Résultat (comptage déterministe, substring) + +| Métrique | run actuel | run fixé | +| --- | --- | --- | +| Faits dupliqués (≥2 fichiers) | 7 | 6 | +| Sites de restatement | 23 | 15 (−35 %) | +| Entry point | 3 fichiers (quasi-verbatim) | 1 | +| Routes `src/routes` | 4 fichiers | 2 (accepté) | + +## Lecture + +- **Bug confirmé** : fill aveugle → 7 faits dupliqués, jusqu'à 4 fichiers + chacun. Pires : entry point + routes quasi-verbatim ; `architecture.Stack` + aimant (Express, Knex, Jest re-listés). +- **Fix efficace sur le haut-sévérité** : entry point 3→1, paires + quasi-verbatim architecture↔codebase-map supprimées, Internal+diagramme + d'integration supprimés. Résiduel = mini-dups consciemment acceptés + (framework, npm test, users). +- **Templates restés haut niveau** : dédup faite par action/règle, zéro + métadonnée dans les templates. Conforme à la consigne. + +## Trouvailles + +1. **Le comptage substring sur-compte** (ex: "Jest" comme label de zone ≠ vraie + dup). → un script de dédup naïf ne suffit pas ; le check doit être + **sémantique** (review agent), pas un grep. +2. **`integration` sur projet sans service externe → quasi vide** ("None"). + Confirme un gate douteux : integration ne devrait pas se déclencher sans + service externe. → fix séparé dans `capability-signals`. +3. La dédup résiduelle dépend du comportement du fill agent suivant + l'action+règle. Pas garantissable statiquement → la règle doit être + **explicite et forte**, et la review 04 doit lister des points de dédup + concrets (fact → propriétaire). + +## Conséquence sur le plan + +- Check 04 = review sémantique forte (pas un script), avec checklist + fact→propriétaire ; option : déléguer à un checker subagent indépendant + (contexte frais), formulé plugin-agnostique. +- Ajouter au suivi séparé : gate `integration` dans `capability-signals`. diff --git a/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/phase-1.md b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/phase-1.md new file mode 100644 index 00000000..249dd403 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/phase-1.md @@ -0,0 +1,61 @@ +--- +status: pending +--- + +# Instruction: Templates à responsabilité unique + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +assets/templates/memory/ +├── core/ +│ └── architecture.md 🔁 drop ## Structure ; Stack = libs transversales only +├── api/ +│ ├── api.md 🔁 Style = surface serveur/RPC +│ └── integration.md 🔁 reframe en intégrations externes (drop ## Internal) +└── ui/ + └── navigation.md 🔁 Routing = client +``` + +## Tasks to do + +### `1)` architecture.md — drop Structure + Stack macro-only + +> `codebase-map` possède zones + entry point ; `architecture` ne les redit plus. + +1. Supprimer la section `## Structure` (les 2 bullets : modules/layers + entry point). +2. Stack, bullet 2 : remplacer `` par une formulation "libs transversales uniquement ; une lib couverte par une capability (ORM, test runner, form lib) vit dans son concern, pas ici". + +### `2)` integration.md — reframe en intégrations externes + +> Responsabilité unique : comment ce système s'intègre à des services tiers. Le flux interne appartient à `architecture.How it fits together`. + +1. Intro : remplacer "How this system talks to others: internal communication and external services." par "How this system integrates with external/third-party services." +2. Supprimer la section `## Internal`. +3. Conserver `## External services` + le diagramme mermaid (carte des intégrations externes). + +### `3)` api.md — Style = serveur/RPC + +> Lever l'ambiguïté "où sont définies les routes" avec navigation. + +1. Style, bullet 1 : préfixer la responsabilité serveur — "Server/RPC surface: REST, GraphQL, or RPC, the framework, where server routes are defined". + +### `4)` navigation.md — Routing = client + +> Pendant client de api.md. + +1. Routing, bullet 1 : préfixer "Client routing: the router and where client routes are defined". + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ----------------------------------------------------------------------------------------------------- | +| 1 | `architecture.md` n'a plus de `## Structure` ; Stack bullet 2 ne demande plus les libs de domaine. | +| 2 | `integration.md` n'a plus de `## Internal` ; intro parle d'intégrations externes ; External + diag présents. | +| 3 | `api.md` Style mentionne "server" / serveur. | +| 4 | `navigation.md` Routing mentionne "client". | +| 1-4 | `aidd framework build --target codex` passe sans erreur ; chaque template reste lisible seul. | diff --git a/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/phase-2.md b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/phase-2.md new file mode 100644 index 00000000..c7430e20 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/phase-2.md @@ -0,0 +1,65 @@ +--- +status: pending +--- + +# Instruction: Fill non aveugle + règle dédup + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +. +├── SKILL.md 🔁 transversal rule "un fait = un fichier" +└── actions/ + ├── 03-generate-memory.md 🔁 étape 6 : fill non aveugle + └── 04-review-memory.md 🔁 check dédup cross-fichiers +``` + +## User Journey + +```mermaid +flowchart TD + A[03 Fill] -->|tient compte des faits déjà écrits| B[un fait écrit une fois] + B --> C[04 Review] + C -->|check: aucun fait dupliqué| D{dup trouvée ?} + D -->|oui| E[garder dans le propriétaire, drop la copie] + D -->|non| F[clean] +``` + +## Tasks to do + +### `1)` 03-generate-memory.md — casser le fill aveugle + +> Le multiplicateur de duplication. Le fill ne doit plus être aveugle aux autres templates. + +1. Étape 6 (`**Fill.**`) : retirer "in parallel". +2. Reformuler l'amorce pour que chaque template soit rempli en tenant compte des faits déjà capturés par les templates précédents, afin de ne pas redire un fait (le référencer plutôt que le recopier). + +### `2)` SKILL.md — transversal rule (forte + points explicites) + +> Étend le principe "pointer vers le code" au cross-mémoire, sans tuer l'auto-suffisance. Règle forte, avec les propriétaires nommés. + +1. Ajouter aux Transversal rules, formulé fort : "**Un fait vit dans un seul fichier mémoire.** Un autre fichier le référence, jamais ne le recopie." Suivi des points de propriété (fact → owner) : + - point d'entrée + zones top-level → `codebase-map` + - stack/framework macro → `architecture` ; une lib de domaine → son concern (ORM→database, runner→testing, form lib→forms) + - flux interne entre modules → `architecture` ; services externes → `integration` + - commandes de gate (typecheck/test/build) → `coding-assertions` + +### `3)` 04-review-memory.md — review dédup sémantique (non sautable) + +> Le check est sémantique, pas un grep (cf. preuve empirique : substring sur-compte). Forte, indépendante, avec checklist concrète. + +1. Étape 2 (`**Review.**`) : ajouter un check fort et explicite — "Lire tous les fichiers ensemble. Pour **chaque fait de la liste de propriété** (cf. transversal), vérifier qu'il vit dans un seul fichier ; toute copie ailleurs = à supprimer, en gardant le propriétaire. Juger sémantiquement, pas par correspondance de chaîne." +2. Option (formulée plugin-agnostique, sans dépendance dure à `aidd-dev`) : "Cette review peut être confiée à un checker subagent indépendant en contexte frais ; sa checklist DRY couvre déjà la dédup." (Note : `aidd-dev:checker` convient s'il est installé.) + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------------- | +| 1 | L'étape 6 de `03` ne contient plus "in parallel" et mentionne la prise en compte des faits déjà écrits. | +| 2 | `SKILL.md` Transversal rules contient la règle forte "un fait = un fichier" + les 4 points fact→owner. | +| 3 | L'étape Review de `04` contient le check dédup sémantique (par fait de la liste de propriété) + l'option checker subagent. | +| 1-3 | `aidd framework build --target codex` passe sans erreur. | diff --git a/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/plan.md b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/plan.md new file mode 100644 index 00000000..99bbd668 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_29_memory-dedup/plan.md @@ -0,0 +1,41 @@ +--- +objective: "Le memory bank généré ne duplique plus un fait entre fichiers, et le fill ne re-écrit plus un fait déjà capturé." +status: pending +--- + +# Plan: dédup des templates mémoire (02-project-memory) + +## Overview + +| Field | Value | +| ---------- | --------------------------------------------------------------------- | +| **Goal** | Supprimer la duplication cross-fichiers du memory bank : templates à responsabilité unique + fill non aveugle. | +| **Source** | `aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md` | + +## Phases + +| # | Phase | File | +| --- | ------------------------------ | ---------------------------- | +| 1 | Templates à responsabilité unique | [`phase-1.md`](./phase-1.md) | +| 2 | Fill non aveugle + règle dédup | [`phase-2.md`](./phase-2.md) | + +## Resources + +| Source | Verified | +| ------------------------------------------------------------ | ----------------------------------------------------------------- | +| docs Anthropic skills + agentskills.io | `@` = import CLAUDE.md, pas le standard skill (chemins relatifs) | +| `aidd framework build --target codex` (test scratchpad) | le build convertit `@../x` → un lien `x` vers `../x` ; la dup est structurelle | +| Les 22 templates `assets/templates/memory/` | matrice des faits dupliqués, table de dominance réduite | + +## Decisions + +| Decision | Why | +| ----------------------------------------------------------------- | ------------------------------------------------------------------- | +| Pas de pointer mémoire↔mémoire généralisé | casse l'auto-suffisance d'un fichier lisible seul ; gain < coût | +| `integration` reframé en intégrations externes, pas juste coupé | le fichier mélangeait 2 responsabilités (interne ≡ architecture) | +| On garde les dups mineures (framework, environnements, release) | un mot re-nommé coûte moins qu'un renvoi | +| Le vrai levier = casser le fill parallèle aveugle (03.6) | même templates parfaits, le fill aveugle re-écrit le même fait | +| Check dédup = review sémantique, pas un script grep | preuve empirique : le substring sur-compte (label de zone ≠ dup) | +| Règle dédup explicitée fort + points fact→owner | la dédup dépend du fill agent ; la règle doit être sans ambiguïté | +| Symptôme A (Codex `@` brut) hors scope | dépend du chemin de distribution réel, à tracer séparément | +| Gate `integration` (sans service externe → fichier vide) hors scope | trouvaille empirique ; fix dans `capability-signals` séparément | diff --git a/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/brainstorm.md b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/brainstorm.md new file mode 100644 index 00000000..1c2cfc54 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/brainstorm.md @@ -0,0 +1,35 @@ +# Brainstorm — onboard refactor + +> Refined through brainstorm. Intent-level only: no solution, no plan. + +## Refined idea + +Onboard stays a **guide** that orients the user in the AIDD flow and never builds the work itself. The refactor reshapes it around four moves: + +- **Foundation first.** When the project's memory bank is missing or unsynced, onboard makes setting it up (init, sync) the loud, pre-selected next step. It is **skippable** — the user can override — so the existing "suggest, never force" principle survives; the right path is just made obvious. +- **Project-adapted action menu.** Once the foundation is in place or skipped, onboard offers a *set* of relevant next actions (refine an idea, plan, audit, debug, …) instead of one lone suggestion. +- **Two-layer relevance.** The menu is built from what the installed plugins *can* do, then ranked by *cheap* project signals for what the project *needs now*. Deep analysis is **not** onboard's job — the capability the user picks does its own deep work. +- **Lighter loop.** Onboard reads the project once and refreshes only on change, rather than a full rescan every loop. + +A **capability reference** underpins this: it maps installed plugins to the actions they offer — the raw material onboard ranks against the cheap project signals. + +## Settled this round + +- Role: guide, not actor (same job as today). +- Enforce strength: strong default, skippable — not a hard gate. +- Reference model: possible (plugin capability map) × relevant (codebase-signal ranking). +- Loop reads: read once, refresh on change. +- Analysis depth (leaning, not locked): cheap signals only; the picked capability owns the deep analysis. + +## Open assumptions (confirm at design time) + +1. **Skip semantics** — how the user skips the foundation step, and whether onboard re-nags it next loop or remembers the skip. +2. **Signal set** — the exact cheap signals feeding the ranking (manifest, presence of tests/specs/plans/open PRs, memory state, …); ordering is heuristic by design. +3. **Reference shape** — evolve the existing journey map vs introduce a new capability reference (a build-time call). +4. **"On change" trigger** — what counts as a state change that forces a re-read. +5. **Foundation scope** — just memory init + sync, or also the AI context files? +6. **Menu rules** — which actions surface, and how they are ordered and capped. + +## Next move + +Ready to become a **design / plan for the onboard skill**, then built. diff --git a/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-1.md b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-1.md new file mode 100644 index 00000000..ebb6c874 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-1.md @@ -0,0 +1,67 @@ +--- +status: pending +--- + +# Instruction: Lighten the read loop + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +plugins/aidd-context/skills/00-onboard/ +├── SKILL.md ✏️ transversal: read-once + ledger advance +└── actions/ + ├── 01-read-project.md ✏️ produce the reusable snapshot + session ledger + ├── 02-orient.md ✏️ consume the ledger: exclude done/skipped stages + └── 03-act.md ✏️ write the ledger: mark run done, declined skipped +``` + +The ledger is one indivisible mechanism — produce (01), write (03), **read (02)**. They must ship together, or the loop re-nags. The first build sliced the consumer into a later phase and the loop kept re-suggesting done steps; this phase wires all three. + +## User Journey + +```mermaid +flowchart TD + A[read-project: scan once] --> B[snapshot = cheap signals + session ledger] + B --> C[orient / act loop reuses snapshot] + C --> E{outcome type?} + E -- Run-it --> F[re-derive disk signals + mark step done in ledger] + F --> C + E -- read-only --> C +``` + +## Tasks to do + +### `1)` Snapshot = cheap signals + a session ledger + +> `01-read-project` produces one reusable snapshot. Cheap disk signals alone cannot tell a step is done, so the snapshot also carries a session ledger. + +1. Capture the cheap signals, each a presence test: memory-bank state (bank dir with filled files = synced; absent or empty = weak), an architecture doc (`aidd_docs/INSTALL.md`) present, manifest + stack, presence of tests (real test files exist, not just a configured runner), code presence (any source outside `aidd_docs/` — an empty repo has none), specs/plans under `aidd_docs/`, current plan status (the `plan.md` status field), open PRs. Plus a bounded richer read, done in the same single pass: a light code-quality sample (size and complexity hotspots = "messy") and a bug-marker scan (TODO/FIXME/error reports), so audit and debug can rank later. Reading memory-file contents to judge "synced" and this bounded code sample are the sanctioned non-cheap reads — done once, never per loop. +2. Carry a **per-session step ledger**: which flow steps the user has run, and which they have skipped, this session. This is session state onboard holds, not derived from disk — it is how onboard knows a step is done when its completion leaves no cheap signal (track to an external tracker, ship's merge, a read-only review). +3. Hold the snapshot (signals + ledger) in context as the single source orient and act both read; never reach back to the filesystem mid-loop. +4. Keep the read silent: still prints nothing. + +### `2)` Advance the loop without re-nagging + +> A step is done when a disk signal proves it OR the ledger records it run this session. The loop must never re-suggest a just-done step. + +1. In `SKILL.md`, change the transversal "Re-read after each step" to "Read once; after any Run-it outcome re-derive the disk signals and update the ledger; reuse the snapshot for read-only outcomes." +2. In `03-act`, after a "Run it" outcome: re-derive the cheap disk signals **and** mark the step the user ran as done in the ledger. The default (phase 4) is the earliest flow step that is neither satisfied by a disk signal nor recorded done-this-session, so the just-completed step is never re-offered even when it left no disk trace. Every read-only outcome (explain step, explain project, show flow, different step, hand off, stop) reuses the existing snapshot unchanged. + +### `3)` Wire the ledger end-to-end + +> Producer and writer are useless without a consumer. `02-orient` must read the ledger, and a declined step must be written as skipped. + +1. In `02-orient`, the earliest-unmet-stage rule excludes any stage the ledger marks done or skipped: a stage is met if a disk fact satisfies it **or** the ledger records it. +2. In `03-act`, a "different step" marks the declined suggested step as skipped in the ledger, so it is not re-suggested this session. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | --------------------------------------------------------------------------------------------------- | +| 1 | The snapshot lists every named signal plus the session ledger of run/skipped steps, is emitted once; `01-read-project` still prints nothing. | +| 2 | After a Run-it outcome, the just-run step is marked done in the ledger and is never re-offered as the default, even when it left no disk signal (bootstrap, track, ship, review); read-only outcomes reuse the snapshot. | +| 3 | `02-orient` excludes ledger done/skipped stages when choosing the default; a "different step" writes the declined step as skipped. The off-disk Track case advances on the next loop instead of re-nagging. | diff --git a/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-2.md b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-2.md new file mode 100644 index 00000000..0fdaab85 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-2.md @@ -0,0 +1,61 @@ +--- +status: pending +--- + +# Instruction: Foundation-first, skippable + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +plugins/aidd-context/skills/00-onboard/ +├── SKILL.md ✏️ transversal: foundation is the strong default, skip remembered +└── actions/ + └── 02-orient.md ✏️ pre-select the memory foundation when weak, skippable +``` + +## User Journey + +```mermaid +flowchart TD + A[orient reads snapshot] --> Z{repo empty, nothing built?} + Z -- yes --> Y[loud default: architect a stack first] + Z -- no --> B{memory bank present and synced?} + B -- no --> C[loud default: set up the memory bank] + C --> D{user picks it or skips?} + D -- runs it --> E[foundation done] + D -- skips --> F[remember skip: no loud default this session] + B -- yes --> G[action menu] + Y --> G + E --> G + F --> G +``` + +## Tasks to do + +### `1)` The foundation gate, with an explicit empty-repo branch + +> The gate has two states, both normative in the diagram above, not just prose. + +1. **Empty repo.** When the snapshot shows an empty repo (no code, no manifest), the loud pre-selected default is "architect a stack first" — not the memory foundation. +2. **Content but weak memory.** When the repo has content and the memory bank is missing or unsynced, the loud pre-selected default is "set up the memory bank", with a one-line why. Foundation = memory init + sync, including the context-file memory blocks. +3. **Memory fine, or empty repo handled:** go straight to the action menu (phase 4). +4. Keep it skippable: the user can pick any other action; never block. + +### `2)` Skip is global, recorded in the ledger + +> Enforce without harassing, and preserve suggest-never-force, for every step — not just the foundation. + +1. When the user skips **any** loud default (architect a stack, the memory foundation, or a later step), record it in the session ledger and do not re-fire it this session. This covers the empty-repo "architect" default too, not only the memory foundation. +2. The post-skip default has a defined owner: the earliest flow step that is neither satisfied by a disk signal, nor done-this-session, nor skipped-this-session (phase 1 + phase 4). The skipped step drops to a plain (non-loud) listed option. If nothing qualifies, there is no loud default and the menu shows the tools + footer only. +3. In `SKILL.md`, keep "Suggest, never force" and add one line: a default may be loud and pre-selected, but it is always skippable, and a skipped step is remembered for the session. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------------------------- | +| 1 | An empty repo loudly pre-selects "architect a stack first"; a content repo with weak memory loudly pre-selects "set up the memory bank"; both are skippable and both branches are in the diagram. | +| 2 | Any skipped step (architect, foundation, or later) is recorded in the ledger and not re-fired this session; the post-skip default is the earliest step not done/skipped, or none; `SKILL.md` keeps "suggest never force" + the skip-remembered note. | diff --git a/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-3.md b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-3.md new file mode 100644 index 00000000..5806e5ad --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-3.md @@ -0,0 +1,49 @@ +--- +status: pending +--- + +# Instruction: Evolve journey into the capability map + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +plugins/aidd-context/skills/00-onboard/ +└── references/ + └── journey.md ✏️ map each cheap signal to the actions it makes relevant +``` + +## User Journey + +```mermaid +flowchart TD + A[cheap signal in snapshot] --> B[capability map: signal -> relevant actions] + B --> C[actions described by what they achieve, resolved later to installed skills] +``` + +## Tasks to do + +### `1)` Map signals to relevant secondary tools + +> The flow walk still owns the default step. This map only ranks the secondary tools beside it — it never computes the default. + +1. In `references/journey.md`, keep the flow stages and the resolve-to-installed-skill rules unchanged; they remain the source of the default step (with its hedges). +2. Add a layer mapping each snapshot signal to the secondary tools it makes relevant, gated to the flow stage where it applies: real test files absent at build/review → adding tests; the code-quality sample flags messiness at build/review → audit; the bug-marker scan flags reported bugs → debug; open PR → nothing new (ship is the flow default). A tool never surfaces outside its relevant stage. +3. Keep it plugin-agnostic: every entry is named by what a skill achieves, never a hardcoded skill or plugin id. + +### `2)` Reconcile the placement table with the default rules + +> The "Where the project sits" table is a source of truth; it must agree with phase-4. + +1. In `references/journey.md`, edit the placement table so the need-stage rows (memory set up + rough idea / clear need) no longer imply a single loud "Clarify" suggestion — they offer Clarify and Track as choices with no loud default, matching phase-4. +2. Add the empty-repo row's pairing with phase-2 (empty repo → architect a stack) and the build-done rows' Review-or-Ship pairing, so the table never disagrees with the gate or the menu. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------------------------------------------------------------------------------- | +| 1 | `journey.md` maps each named signal to a stage-gated secondary tool, never to the default step, and still names no skill or plugin id. | +| 2 | The placement table's need-stage rows show no loud default, and no table row contradicts the phase-2 gate or the phase-4 menu. | diff --git a/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-4.md b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-4.md new file mode 100644 index 00000000..0c4214bb --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/phase-4.md @@ -0,0 +1,57 @@ +--- +status: pending +--- + +# Instruction: Ranked action menu in orient + act + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +plugins/aidd-context/skills/00-onboard/ +├── README.md ✏️ describe the foundation-gate + ranked-menu flow +└── actions/ + ├── 02-orient.md ✏️ build a ranked action set, not one suggestion + └── 03-act.md ✏️ act on a pick from the set +``` + +## User Journey + +```mermaid +flowchart TD + A[foundation done or skipped] --> B[rank snapshot signals against the capability map] + B --> C[default = earliest unmet flow step] + C --> D[+ small ranked set of relevant tools, cap ~5] + D --> E[user picks one] + E --> F[act: run / explain / hand off / stop, resolved to an installed skill or a gap] +``` + +## Tasks to do + +### `1)` Orient builds one reconciled menu + +> One default mechanism, one render order, never less informative than today. + +1. **Default = flow walk.** In `02-orient`, the default step is the flow walk's earliest **unmet** step (journey.md), where unmet = not satisfied by a disk signal, not done-this-session, and not skipped-this-session (the phase-1 ledger). This is what stops the just-run step being re-offered. Its hedges, driven by the plan-status signal: + - Plan status `in-progress` → default is **Build alone** (the status is a cheap signal the build is not done; no premature Review). + - Build looks done but nothing reviewed (plan status `implemented`, or an open PR) → present **Review and Ship together**, Review first, so Review is never skipped. + - Build-doneness genuinely unprovable (no plan status either way) → hedge **Build and Review**. + - Need stage → offer **Clarify and Track** as choices, Clarify listed first as a soft recommendation, but **not** a loud pre-selected default (no snapshot signal separates rough idea from clear need). +2. **Secondary tools = signal map.** Beside the default, add the stage-gated tools the capability map (phase 3) marks relevant, each resolved to an installed skill or marked a gap. The signal map never overrides the default. Cap **the default + secondary block** at ~5 lines; this cap scopes that block only. +3. **One render order, always:** the foundation step first when memory is weak (phase 2), else the flow default(s); then the ranked secondary tools; then the standing affordances as **one compact footer line**, never dropped — explain the step first, explain this project (when memory is filled), see the flow + skills, go to a different step, hand off, stop. The footer is outside the ~5-line cap, so the menu is never less informative than today's. +4. Drop the old fixed 8-item list; keep labels plain. + +### `2)` Act on the pick; refresh docs + +1. In `03-act`, handle a pick from the ranked set with the existing outcomes (run / explain / hand off / stop), looping back per phase 1's refresh rule. +2. Update `README.md` to describe the new flow: foundation gate, then the project-adapted ranked menu. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | -------------------------------------------------------------------------------------------------------- | +| 1 | Default from the flow walk only; plan-status `in-progress` → Build alone; build-done-unreviewed → Review+Ship; need-stage → Clarify-first soft recommendation with no loud default; default+secondary block ≤ ~5 lines; standing affordances render as one footer line outside the cap. | +| 2 | A pick runs through `03-act`'s outcomes; `README.md` documents the foundation-gate + reconciled-menu flow; the menu is never less informative than today's onboard on any state. | diff --git a/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/plan.md b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/plan.md new file mode 100644 index 00000000..aa9bf20d --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/plan.md @@ -0,0 +1,49 @@ +--- +objective: "Onboard enforces the memory foundation as a skippable default, then offers a project-adapted, capability-ranked action menu, on a read-once/refresh-on-change loop, without breaking suggest-never-force." +status: pending +--- + +# Plan: Onboard refactor + +## Overview + +| Field | Value | +| ---------- | --------------------------------------------------------------------- | +| **Goal** | Turn onboard from one-suggestion-per-loop into a foundation-gated, project-adapted action guide that reads once and refreshes on change. | +| **Source** | `aidd_docs/tasks/2026_06/2026_06_30_onboard-refactor/brainstorm.md` | + +## Phases + +| # | Phase | File | +| --- | -------------------------------------- | ---------------------------- | +| 1 | Lighten the read loop | [`phase-1.md`](./phase-1.md) | +| 2 | Foundation-first, skippable | [`phase-2.md`](./phase-2.md) | +| 3 | Evolve journey into the capability map | [`phase-3.md`](./phase-3.md) | +| 4 | Ranked action menu in orient + act | [`phase-4.md`](./phase-4.md) | + +## Resources + +| Source | Verified | +| ---------------------------------------------------------------------- | -------------------------------------------------------------- | +| `plugins/aidd-context/skills/00-onboard/` (SKILL + 3 actions + journey) | current structure: read → orient (one suggestion) → act → loop | +| `plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md` | the R1–R13 contract the rewrite must keep | +| `brainstorm.md` (this folder) | the refined idea and the 6 open assumptions, now resolved below | + +## Decisions + +| Decision | Why | +| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | +| Foundation is a strong, pre-selected default, never a hard gate | keeps the load-bearing "suggest never force" rule intact | +| A skip of any step is recorded in the session ledger and not re-fired; the post-skip default is the next step not done/skipped | global skip with a defined owner — not scoped to the memory foundation | +| Onboard does a bounded richer read once — cheap presence signals plus a light code-quality sample and a bug-marker scan — so audit and debug can rank; still read-once, never per loop | the ranked menu needs more than presence signals to fire; read-once keeps the deeper read from being per-loop heavy | +| Evolve `references/journey.md` into the capability map; no new reference file | journey already owns flow→capability resolution; stays DRY | +| A step is done when a disk signal proves it OR the session ledger records it run this session; refresh re-derives disk signals + updates the ledger after a Run-it, reuse for read-only | cheap signals cannot detect off-disk completions (bootstrap→INSTALL.md, track→external, ship→merge, read-only review), so the ledger carries them — kills the re-nag | +| Foundation = memory init + sync incl. context-file blocks; empty-repo stack stays pre-foundation | the memory bank and its context blocks are one foundation | +| The **flow-walk owns the default** (earliest unmet step, with its hedges); the **signal map only ranks the secondary tools**, never the default | one mechanism per slot — kills the flow-vs-signal default conflict the dry-run found | +| Plan status drives the build hedges: `in-progress` → Build alone; `implemented` or open-PR → Review+Ship (Review first); unprovable → Build+Review | Review is never skipped, and no premature Review at the in-progress stage | +| Need-stage offers Clarify and Track as choices, Clarify first as a soft recommendation, never a loud pre-selected default | keeps baseline's directiveness without auto-running an unprovable pick | +| Secondary tools are stage-gated and mapped from the snapshot signals: add-tests from real-test-files, audit from the code-quality sample, debug from the bug-marker scan | the richer read lets the ranked menu actually fire | +| Standing affordances render as one compact footer line, outside the ~5-line cap; the cap scopes only the default + secondary block | menu never less informative than today's, and the cap is satisfiable | +| "Presence of tests" = real test files exist, not just a configured runner | a configured runner with no test files reads as tests-absent, so add-tests fires exactly there | +| Empty repo is its own gate branch (loud default = architect a stack), cleared when `INSTALL.md` exists or architect ran this session; the memory-foundation gate applies only to a content repo with weak memory | normative diagram decides the state, and bootstrap's artifact clears the dead-end | +| Accepted trade — a code-present project still at the need stage gets no auto build-tool path, and "rough idea" gets no loud default | no cheap signal proves the build stage or the need clarity; both stay user-pickable | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bbdeb4bd..709cda3c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -124,6 +124,20 @@ 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 + +- 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. + +Choose by context, not complexity: keep the work visible to the caller → skill; isolate it and take only the result → agent. + +Composition rules: + +- **Spawning is an orchestration decision, never a skill's.** A recipe skill never spawns an agent; it runs in the caller's context. Only a high-level orchestrator skill (for example the SDLC) spawns agents, and it decides per step whether to isolate the work in an agent or run the recipe inline. +- An orchestrator spawns each step as a leaf agent that runs a recipe, or runs the recipe itself when the step needs no isolation. The SDLC owns planning (runs `01-plan` in its own context) and spawns two workers: `executor` (runs `02-implement`) and `checker` (runs `05-review`). The agent is the isolation; the recipe inside it never spawns again. +- 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 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. diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 31371ab1..1e7b210e 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -20,19 +20,25 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex | `00-onboard` | Detect project state and open a hub of project actions | `01-detect-state`, `02-recommend-next`, `03-execute-or-handoff` | | `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` | Generate context artifacts across the host AI tool(s) | sub-generators: `agents`, `commands`, `hooks`, `marketplaces`, `plugins`, `rules`, `skills` | -| `04-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | -| `05-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-scope`, `02-write`, `03-sync` | +| `03-context-generate` | Router that dispatches an artifact-generation request to the dedicated generator below | delegates to `04`–`08` (and plugins / marketplaces) | +| `04-skill-generate` | Generate a router-based skill across the host AI tool(s) | `01-capture-intent`, `02-decompose-actions`, `03-draft-skill`, `04-write-actions`, `05-validate` | +| `05-rule-generate` | Generate a coding rule that governs editor and agent behavior | `01-capture-rule`, `02-write-rule`, `03-validate` | +| `06-agent-generate` | Generate an agent across the host AI tool(s) | `01-capture-agent`, `02-write-agent`, `03-validate` | +| `07-command-generate` | Generate a flat slash command across the host AI tool(s) | `01-capture-command`, `02-write-command`, `03-validate` | +| `08-hook-generate` | Generate a lifecycle hook across the host AI tool(s) | `01-capture-hook`, `02-write-hook`, `03-validate` | +| `09-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | +| `10-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-gather`, `02-assess`, `03-write`, `04-sync` | | `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 -The development SDLC: plan, implement, assert, audit, review, test, refactor, debug. +The development SDLC: plan, implement, assert, audit, review, test, refactor, debug, for-sure, todo. | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `00-sdlc` | Pure orchestrator driving the full dev flow end to end | `01-spec`, `02-plan`, `03-implement`, `04-review`, `05-ship` | -| `01-plan` | Technical implementation plans, component behavior, image extraction | `01-plan`, `02-components-behavior`, `03-image-extract-details` | +| `01-plan` | Turn a request, ticket, or file into a phased implementation plan: gather, explore, wireframe, plan | `01-gather`, `02-explore`, `03-wireframe`, `04-plan` | | `02-implement` | Execute a plan phase by phase until 100% complete | `01-implement` | | `03-assert` | Assert features work - general, architecture, frontend UI | `01-assert`, `02-assert-architecture`, `03-assert-frontend` | | `04-audit` | Read-only codebase audit across quality pillars | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | @@ -41,6 +47,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | `07-refactor` | Improve code without changing behavior across four axes | `01-performance`, `02-security`, `03-cleanup`, `04-architecture` | | `08-debug` | Reproduce and fix bugs with a test-driven workflow | `01-reproduce`, `02-debug`, `03-reflect-issue` | | `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 @@ -49,7 +56,7 @@ Product management: ticket retrieval, user stories, PRD, spec. | Skill | Role | Actions | | ------------------------- | ---------------------------------------------------------- | -------------------------------- | | `01-ticket-info` | Retrieve and display ticket information | `01-ticket-info` | -| `02-user-stories-create` | Generate INVEST-compliant user stories | `01-create-user-stories` | +| `02-user-stories` | Prioritized, estimated INVEST user-story backlog | `01-clarify-scope`, `02-split-epic`, `03-draft-stories`, `04-estimate-impact`, `05-prioritize`, `06-sync-tracker` | | `03-prd` | Generate a structured Product Requirements Document | `01-prd` | | `04-spec` | Generate or refine a normalized project spec | `01-build`, `02-refine` | @@ -69,12 +76,13 @@ Meta-cognition: brainstorm, challenge, condense, blind-spot scan, fact-check. Version-control workflows: 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` | +| 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` | ## aidd-orchestrator diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 195804a7..19a57100 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -28,7 +28,7 @@ A single atomic step inside a skill, stored at `plugins//skills//agents/.md`. Agents are scoped (for example `planner`, `implementer`, `reviewer`) and called from skills when a step needs a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. +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 diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index 92d37f8a..06b0dc8a 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -15,10 +15,73 @@ How to operate this repository day to day. For **who** may do what and the decis ## Daily -- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority` / `Work Type`; link under an epic (native sub-issues) if relevant. +- **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)). + +Apply this layout once (org-admin or board-write needed). Read field IDs first: + +```bash +gh project field-list 8 --owner ai-driven-dev # note the IDs you need below +``` + +### 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` | + +### Timeline view + +Replaces the old "Phases". UI: **New view → Timeline**, date field = the Milestone / target date. Use it as the roadmap horizon (`this week` / `next` / `later`). + +### Apply checklist + +- [ ] `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 + +## 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: + +```bash +gh label delete "help wanted" --yes +gh label delete npm --yes +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 release-please opens/updates a `chore: release main` PR on each push to `main`. diff --git a/lefthook.yml b/lefthook.yml index 7821aa66..90364fe5 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -33,6 +33,23 @@ pre-commit: exit 1 fi done + sync-skill-argument-hints: + glob: "plugins/*/skills/**" + run: | + if ! command -v node >/dev/null 2>&1; then + echo "ℹ️ node not available; skipping sync-skill-argument-hints" + exit 0 + fi + node scripts/sync-skill-argument-hints.mjs >/dev/null + git add plugins/*/skills/*/SKILL.md 2>/dev/null || true + markdown-links: + glob: "**/*.md" + run: | + if ! command -v node >/dev/null 2>&1; then + echo "ℹ️ node not available; skipping markdown-links" + exit 0 + fi + node scripts/check-markdown-links.js summarize-plugin-catalogs: run: | [ -d plugins ] || exit 0 @@ -44,7 +61,7 @@ pre-commit: name=$(basename "$plugin") node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" \ --depth=4 \ - --fields=description,argument-hint \ + --fields=description \ --title="$name catalog" \ --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." \ >/dev/null diff --git a/package.json b/package.json index 8aa3446b..6fe13cc5 100644 --- a/package.json +++ b/package.json @@ -32,10 +32,10 @@ }, "devDependencies": { "@commitlint/cli": "^21.0.2", - "@commitlint/config-conventional": "^21.0.2", + "@commitlint/config-conventional": "^21.2.0", "ajv": "8.20.0", "ajv-formats": "3.0.1", - "js-yaml": "4.2.0", + "js-yaml": "5.0.0", "lefthook": "^2.1.9" } } diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 3ce4b47f..47ee5562 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -47,9 +47,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-read-project.md](skills/00-onboard/actions/01-read-project.md) | - | | `actions` | [02-orient.md](skills/00-onboard/actions/02-orient.md) | - | | `actions` | [03-act.md](skills/00-onboard/actions/03-act.md) | - | +| `assets` | [menu.md](skills/00-onboard/assets/menu.md) | - | | `-` | [README.md](skills/00-onboard/README.md) | - | | `references` | [journey.md](skills/00-onboard/references/journey.md) | - | -| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Guide the user through the AIDD framework on the current project. Explain the flow in plain language and suggest the next logical step, adapted to what is already set up and which AIDD plugins are installed. Use when the user asks where to start, what to do next, how AIDD works, or to be onboarded. Not for listing every installed surface (the explore skill does that) or running a skill the user already knows they need (invoke it directly).` | +| `references` | [outcomes.md](skills/00-onboard/references/outcomes.md) | - | +| `references` | [signals.md](skills/00-onboard/references/signals.md) | - | +| `-` | [SKILL.md](skills/00-onboard/SKILL.md) | `Guide the user through AIDD on the current project, explaining the flow and the next step for what is set up. Use when the user asks where to start, what to do next, or how AIDD works. Not for listing installed surfaces or running a known skill.` | #### `skills/01-bootstrap` @@ -64,7 +67,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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) | `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. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code).` | +| `-` | [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.` | #### `skills/02-project-memory` @@ -82,14 +85,15 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [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) | - | -| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Initialize or refresh the project memory bank. Not for updating one memory file after it exists (use the learn skill) or editing a single rule (edit it directly).` | +| `references` | [memory-block.md](skills/02-project-memory/references/memory-block.md) | - | +| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Initialize or refresh the project memory bank. Use when the user wants to set up or regenerate the project's memory files. Not for updating one memory file after it exists or editing a single rule directly.` | #### `skills/03-context-generate` | 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 dedicated generator when the user has not named which kind. For a named kind, that generator triggers directly. Not for listing existing artifacts (use explore).` | +| [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` @@ -101,7 +105,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-write-actions.md](skills/04-skill-generate/actions/04-write-actions.md) | - | | `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 . , use " only when a sibling skill could mis-trigger.> (<= 1024 chars, third person, no XML tags; all "when" lives here, not in the body.)` | +| `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) | - | @@ -118,7 +122,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [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 a project uses. Use when the user wants to write, add, or refactor a rule, a convention, or a coding standard, or to scan a codebase and propose rules. Not for other artifacts like skills, agents, commands, hooks.` | +| `-` | [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.` | #### `skills/06-agent-generate` @@ -157,7 +161,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [hook-template.json](skills/08-hook-generate/assets/hook-template.json) | - | | `references` | [hook-authoring.md](skills/08-hook-generate/references/hook-authoring.md) | - | | `references` | [tool-paths.md](skills/08-hook-generate/references/tool-paths.md) | - | -| `-` | [SKILL.md](skills/08-hook-generate/SKILL.md) | `Generate a hook (a handler that runs automatically at a lifecycle event) across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a hook, or automate an action at a lifecycle point. Not for other artifacts like skills, rules, agents, commands.` | +| `-` | [SKILL.md](skills/08-hook-generate/SKILL.md) | `Generate a hook, a handler that runs at a lifecycle event, across the host AI tools. Use when the user wants to create, scaffold, or refactor a hook, or automate an action at a lifecycle point. Not for other artifacts like skills or rules.` | #### `skills/09-mermaid` @@ -166,7 +170,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow description into a Mermaid diagram, or when another skill needs one. Not for other diagram formats like PlantUML or Graphviz, or for rendering a diagram to an image.` | +| `-` | [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.` | #### `skills/10-learn` @@ -178,7 +182,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 the project's git history and route them to memory, a decision record, a rule, or a new skill. Use when the user asks to capture, record, or remember a decision, a convention, or a lesson, or to distill what recent work taught. Scores each candidate and confirms before writing. Not for personal or AI preferences, routine edits, or anything already captured.` | +| `-` | [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` @@ -188,7 +192,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 and set up, see what is available, or find which installed skill, agent, or rule fits a goal. Not for the next step to take (onboard does that) or running an item (this skill only points).` | +| `-` | [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.` | #### `skills/12-cook` @@ -198,5 +202,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe".` | +| `-` | [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/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md index 7c68cbff..1d644f25 100644 --- a/plugins/aidd-context/skills/00-onboard/README.md +++ b/plugins/aidd-context/skills/00-onboard/README.md @@ -20,11 +20,11 @@ A plain-language guide to the AIDD framework for the current project. It reads t Three actions, in a loop: -1. `read-project`: **silently** read a few plain facts about the project and the installed skills. Prints nothing. -2. `orient`: explain where the project sits in the AIDD flow and suggest the next step, in plain language, then offer choices. -3. `act`: run the suggestion, explain it, walk the whole flow, switch to a different step, hand off, or stop. Then loop back to `01`. +1. `read-project`: **silently** read the project once into a reusable snapshot — the signals plus a session ledger of what you have run or skipped. Prints nothing. +2. `orient`: place the project in the AIDD flow and offer a project-adapted menu — the recommended next step plus the tools that fit, in plain language. +3. `act`: run the suggestion, explain it, walk the whole flow, switch to a different step, hand off, or stop. Then refresh the snapshot and loop. -It suggests by **function**, then resolves that to whatever skill is actually installed. A step with no installed skill is named as a gap, never an invented recommendation. The suggested step is always a hint, never a forced choice. +It suggests by **function**, then resolves that to whatever skill is actually installed. A step with no installed skill is named as a gap, never an invented recommendation. The recommended step is always skippable, never a forced choice, and once run or skipped it is not suggested again. ## Requires @@ -32,4 +32,4 @@ Only the `aidd-context` plugin installed and enabled, and a working directory ro ## Details -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for the three actions, and [`references/journey.md`](references/journey.md) for the AIDD flow stages and how each resolves to an installed skill. +See [`SKILL.md`](SKILL.md) for the action contract and [`actions/`](actions/) for the three actions. The detail lives in [`references/journey.md`](references/journey.md) (flow stages and placement), [`references/signals.md`](references/signals.md) (project signals and the capability map), and [`assets/menu.md`](assets/menu.md) (the menu shape). diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index c873ebca..e244f39f 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-onboard -description: Guide the user through the AIDD framework on the current project. Explain the flow in plain language and suggest the next logical step, adapted to what is already set up and which AIDD plugins are installed. Use when the user asks where to start, what to do next, how AIDD works, or to be onboarded. Not for listing every installed surface (the explore skill does that) or running a skill the user already knows they need (invoke it directly). +description: Guide the user through AIDD on the current project, explaining the flow and the next step for what is set up. Use when the user asks where to start, what to do next, or how AIDD works. Not for listing installed surfaces or running a known skill. +argument-hint: read-project | orient | act --- # Onboard @@ -11,8 +12,8 @@ A plain-language guide to the AIDD framework for the current project. It reads t | # | Action | Role | Input | | --- | -------------- | ---------------------------------------------------------------- | ----------------- | -| 01 | `read-project` | Lightly and silently read the project and the installed skills | project root | -| 02 | `orient` | Explain where the project sits and suggest the next step, in plain language | the read from 01 | +| 01 | `read-project` | Read the project once into a silent snapshot: signals, ledger, installed skills | project root | +| 02 | `orient` | Place the project, then offer a project-adapted, plain-language menu | the snapshot from 01 | | 03 | `act` | Run the suggestion, explain it, teach the flow, switch step, or stop | the user's choice | Run `01 → 02 → 03`, then loop back to `01` after each step until the user stops. Run each action's `## Test` before the next. @@ -20,13 +21,19 @@ Run `01 → 02 → 03`, then loop back to `01` after each step until the user st ## Transversal rules - Teach, do not assume. The user may be new to AIDD. Explain a term the first time it appears (the memory bank is the project memory the AI loads each session), never assume framework literacy. -- Suggest, never force. Show where the project seems to stand and the next logical step, and always let the user choose another. +- Suggest, never force. Show where the project seems to stand and the next logical step, and always let the user choose another. A foundation step (architect a stack, set up the memory bank) may be the loud, pre-selected default, but it is always skippable, and a skipped step is remembered for the session. - Plain language only. No internal state names, no raw phase labels, no signal dump reaches the user. The user reads guidance, not a state machine. - Adapt to what is installed. Suggest by function and resolve it to a skill that is actually installed. If none is installed, name the missing capability by function, never invent a skill. - Silent read. `01-read-project` prints nothing. The first visible output is the plain briefing from `02-orient`. -- Re-read after each step. The project changes, so read again before suggesting again. +- Read once, then refresh on action. Read the project once into a reusable snapshot; after the user runs a step, re-derive the changed facts and mark that step done in the session ledger; a read-only choice reuses the snapshot. The ledger is how onboard knows a step is done even when it leaves no file behind. - Wait for an explicit reply between prompts. Never auto-advance. ## References -- `references/journey.md`: the AIDD flow stages, what each unblocks, and how a step resolves to an installed skill. +- `references/journey.md`: the AIDD flow stages, their order, and how a stage resolves to an installed skill. +- `references/signals.md`: the project signals `01` captures and the capability map (signal → stage-gated secondary tool). +- `references/outcomes.md`: the per-choice outcome `03` carries out and whether it loops back. + +## Assets + +- `assets/menu.md`: the menu shape `02` renders — default, ranked secondary tools, footer, and the cap and hedge rules. diff --git a/plugins/aidd-context/skills/00-onboard/actions/01-read-project.md b/plugins/aidd-context/skills/00-onboard/actions/01-read-project.md index 414236a2..4fb79a0a 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/01-read-project.md +++ b/plugins/aidd-context/skills/00-onboard/actions/01-read-project.md @@ -1,6 +1,6 @@ # 01 - Read project -Read the project lightly and **silently**. No questions, no writes, no visible output. The few facts gathered are working notes the next action uses to orient the user. +Read the project once, **silently**, into a reusable snapshot. No questions, no writes, no visible output. ## Input @@ -8,28 +8,16 @@ The project root, the current working directory. ## Output -Internal working notes only, **never printed**. Onboard must not show a snapshot or a list of checks. The first thing the user sees is the briefing from `02-orient`. - -The notes answer a handful of plain questions: - -- Is the project memory set up? Does `aidd_docs/memory/` exist, and does any file hold real content rather than a bare template? -- When the memory is filled, what does it say the project is? Read the project brief and the architecture for the project's purpose, stack, and shape. This is the project's own context, and it leads the briefing. -- Does the AI context file carry the `` block? -- Is there code yet, and what stack? A manifest like `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, or the stack named in the memory when there is no manifest. -- Is there a spec or a plan under `aidd_docs/`? -- Is there an open pull request on the current branch? -- Is the repo empty, nothing built yet? -- Which AIDD plugins and skills are installed, with each skill's description? +A silent, reusable snapshot, **never printed**: every signal in `@../references/signals.md`, a **session ledger** of which steps were run or skipped this session (empty on the first read), the installed AIDD plugins and skills each with its description, and — when memory is synced — the project's purpose, stack, and shape from its brief. ## Process -1. **Check the setup.** `test -d aidd_docs/memory`, list its `*.md`, and judge whether any file is filled rather than an untouched template. When a file is filled, read the project brief and the architecture so the briefing speaks from the project's own context, not a guess. `grep -l '' CLAUDE.md AGENTS.md .github/copilot-instructions.md` for the context block. -2. **Check the work.** Look for source files outside `aidd_docs/`, a stack manifest, a spec or plan under `aidd_docs/`, and an open pull request on the branch. If nothing is built at all, note the repo as empty. -3. **List what is installed.** Use the AI tool's native plugin and skill discovery to gather the enabled AIDD plugins and the skills they expose, each with its description. This is how onboard adapts to what the user actually has. -4. **Hold, do not print.** Keep the notes in context. Hand directly to `02-orient`. +1. **Read.** Capture every signal in `@../references/signals.md`; when memory is synced, also read the brief and architecture so the briefing speaks from the project's own context. +2. **List.** Gather the enabled AIDD plugins and skills, each with its description, via the tool's native discovery. +3. **Hold.** Keep the snapshot in context, read this fully only once a session, and hand to `02-orient`. Print nothing. ## Test -- The action produces zero user-visible output. No snapshot, no check list, no labels appear. -- The setup facts, the work facts, and the installed-skill list are all available to `02-orient`. +- Zero user-visible output: no snapshot, no checklist, no labels appear. +- The snapshot carries the signals, the ledger, the installed skills, and the project context when memory is synced, all available to `02-orient`. - No skill id is named in the conversation by this action. diff --git a/plugins/aidd-context/skills/00-onboard/actions/02-orient.md b/plugins/aidd-context/skills/00-onboard/actions/02-orient.md index 14602ac3..2582bfdb 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/02-orient.md +++ b/plugins/aidd-context/skills/00-onboard/actions/02-orient.md @@ -1,34 +1,29 @@ # 02 - Orient -Tell the user, in plain language, where their project sits in the AIDD flow and the single most useful next step. Teach as you go. Then let them choose. +Tell the user, in plain language, where their project sits and the next step, then offer a project-adapted menu. Teach as you go. ## Input -The working notes from `01-read-project`, held in context, not printed. +The snapshot from `01-read-project` (signals + ledger + installed skills), held in context, not printed. ## Output -A short, plain briefing the user can act on. No internal variable names, no raw labels, no snapshot. It has three parts: - -1. **One line on the project**: its purpose and stack drawn from the memory bank when it is filled, otherwise from the files, or that it is a fresh repo. The memory is the project's own context and leads here. -2. **Where it sits**: one or two sentences placing the project in the AIDD flow, explaining any term the first time it appears. -3. **The next step plus choices**: the suggested step in plain language with a one-line why, then a short numbered list of what the user can do, and a prompt to reply with a number. The list stays small and stable: run the suggested step, explain that step first, explain this project from its memory (only when the memory is filled), see the whole AIDD flow and the installed skills, go to a different step, stop. +A short, plain briefing plus the menu rendered per `@../assets/menu.md`. No internal names, no raw labels, no snapshot reaches the user. ## Process -1. **Read the notes from 01.** Print nothing from them directly. -2. **Place the project.** Using `@../references/journey.md`, find the earliest unmet stage for these facts. That is the suggestion. Treat it as a hint, never a verdict. -3. **Resolve the suggestion** to an installed skill (`@../references/journey.md`, Resolving). If no installed skill fits, the step is a gap: name the missing capability by function, never a skill or plugin id. -4. **Write the briefing** in plain language: the one-line project, where it sits, and the suggested step with a short why. Explain any AIDD term the first time it appears. -5. **Offer choices.** A short, stable numbered list with plain labels: run the suggested step, explain that step first, explain this project from its memory (only when the memory is filled), see the whole AIDD flow and the installed skills, go to a different step, stop. -6. **On explain the project**, summarize the project from its memory bank in a few plain lines: what it is, the stack, the shape, the key decisions. Read-only, then re-offer the choices. -7. **On a different step**, show the flow steps from `@../references/journey.md` in plain language and let the user pick one, then resolve that to a skill or a gap. -8. **Hand the choice to `03-act`**, with the resolved skill (or gap) and what the user picked. -9. **Wait for a reply.** Free text re-renders the same choices with a one-line reminder to reply with a number. Never auto-advance. +1. **Place.** Default = the earliest **unmet** stage in `@../references/journey.md`, where met = a disk fact **or** a ledger done/skip; a foundation stage is the loud default. +2. **Rank.** Add the stage-gated secondary tools the snapshot signals trigger in `@../references/signals.md`. +3. **Resolve.** Resolve each item to an installed skill, else name it a gap by function; never name a skill or plugin that is not installed. +4. **Brief.** Write the plain briefing: the one-line project, where it sits, the why; explain each AIDD term on first use. +5. **Assemble.** Render the menu per `@../assets/menu.md`; a foundation default is tagged `(recommended)` and stated skippable. +6. **Wait.** Offer the menu and wait for a number; free text re-renders it. Never auto-advance. +7. **Different step.** Show the `@../references/journey.md` stages, let the user pick one, and resolve it. +8. **Hand** the chosen item to `03-act`; acting on it belongs there. ## Test -- The output is plain language. No internal note names, no raw stage labels, no snapshot reaches the user. -- It names where the project sits and exactly one suggested next step, resolved to an installed skill or a named gap. -- It offers explicit numbered choices and waits for the user. -- A suggested step never names a skill or plugin that is not installed. +- Plain language only: no internal note names, raw stage labels, or snapshot reach the user. +- The default is the earliest stage unmet by both disk and ledger; a foundation stage renders as the `(recommended)`, skippable first choice. +- Secondary tools are stage-gated per `signals.md`; the menu follows `@../assets/menu.md` (default + secondary ≤ ~5, footer never dropped). +- Every item resolves to an installed skill or a named gap; nothing uninstalled is named. diff --git a/plugins/aidd-context/skills/00-onboard/actions/03-act.md b/plugins/aidd-context/skills/00-onboard/actions/03-act.md index ce4eab50..a5b647f0 100644 --- a/plugins/aidd-context/skills/00-onboard/actions/03-act.md +++ b/plugins/aidd-context/skills/00-onboard/actions/03-act.md @@ -1,45 +1,24 @@ # 03 - Act -Carry out what the user picked: run the suggested skill, explain it, teach the whole flow, switch to a different step, or stop. Loop back to reading the project after each one. +Carry out what the user picked, then loop back to reading the project. ## Input - The user's choice from `02-orient`. - The resolved skill, or a gap when no installed skill fits. -- The working notes from `01-read-project`, held in context. +- The snapshot from `01-read-project`, held in context. ## Output -One outcome, always ending with a clear next prompt or a clean stop. - -| Choice | What happens | Loop back to 01? | -| --------------- | --------------------------------------------------------------------------- | ---------------- | -| Run it | Invoke the resolved skill in this session, then ask the user how it went | yes | -| Explain the step | Describe the step and its skill in two or three plain lines, then re-offer the choices | no, re-offer | -| Explain project | Summarize the project from its memory bank, read-only, then re-offer the choices | no, re-offer | -| Show flow + skills | Walk the AIDD flow in plain language and list the installed skills grouped by step, then re-offer the choices | no, re-offer | -| Different step | Let the user pick another step, resolve it, and re-offer the choices | no, back to 02 | -| Hand off | Give the exact command to run in a fresh session, then wait for the user to come back | yes | -| Stop | A one-line goodbye, end the loop | no, terminate | +One outcome per `@../references/outcomes.md`, always ending with a clear next prompt or a clean stop. ## Process -1. **Run it.** Invoke the resolved skill the way a slash command would. When it returns, ask the user how it went and wait. Then read the project again (`01`), since it has changed. -2. **Explain the step.** Pull the resolved skill's purpose from its description and say, in two or three plain lines, what the step does and what it produces. Do not invoke. Re-offer the choices. -3. **Explain the project.** Summarize the project from its memory bank: what it is, the stack, the shape, the key decisions, in a few plain lines. Read-only, never invoke. Re-offer the choices. Available only when the memory is filled. -4. **Show flow and skills.** Walk the AIDD flow from `@../references/journey.md` in plain language, then list the installed skills grouped by the step each fits (and the ones that fit no step), discovered from `01`, never hardcoded. Then re-offer the choices. This is the teaching path. -5. **Different step.** Hand back to `02-orient` to show the steps and let the user pick another, then resolve it. -6. **Hand off.** Give the user the exact command to run in a new session, ask them to come back when done, and wait. Then read the project again. -7. **Stop.** Say one closing line and end. Do not loop. -8. **A gap.** If the chosen step has no installed skill, Run and Hand off are unavailable. Say the step needs a plugin that is not installed, by function only, then offer to explain it, a different step, or stop. -9. **Resolve, never invent.** Only ever run or name a skill that `01` found installed. +1. **Act.** Carry out the choice per `@../references/outcomes.md`, running or naming only skills `01` found installed. +2. **Ledger.** Run-it and hand-off refresh the snapshot and mark the step done; a different step marks the declined step skipped; every other outcome reuses the snapshot. ## Test -- Run invokes only an installed skill, then loops back to `01`. -- Explain the step produces a short plain description and re-offers the choices without invoking anything. -- Explain the project summarizes from the memory bank, writes nothing, and re-offers the choices. -- Show flow and skills walks the flow and lists the installed skills grouped by step, then re-offers the choices. -- Hand off produces an exact command and waits for the user to return. -- Stop ends the loop cleanly. -- A gap step never produces a skill invocation. It offers to explain it, a different step, or stop only. +- Each choice produces its outcome per `@../references/outcomes.md`; only installed skills are run or named. +- Run-it and hand-off mark the step done — not re-suggested even when it left no file behind; a different step marks it skipped; read-only outcomes do not re-read the project. +- A gap never invokes a skill: it offers explain, a different step, or stop only. diff --git a/plugins/aidd-context/skills/00-onboard/assets/menu.md b/plugins/aidd-context/skills/00-onboard/assets/menu.md new file mode 100644 index 00000000..9e6f9428 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/assets/menu.md @@ -0,0 +1,16 @@ + + +1. +2. + ... + + + + diff --git a/plugins/aidd-context/skills/00-onboard/references/journey.md b/plugins/aidd-context/skills/00-onboard/references/journey.md index 819235ac..ed9e5310 100644 --- a/plugins/aidd-context/skills/00-onboard/references/journey.md +++ b/plugins/aidd-context/skills/00-onboard/references/journey.md @@ -23,6 +23,8 @@ Then, per piece of work: Read a few plain facts (action 01), then suggest the earliest unmet step. The suggestion is a hint, never a verdict. +This table places by disk facts only. A stage is **also** met when the session ledger marks it done or skipped this session, so `02-orient` excludes those before picking the earliest unmet step (it owns that definition; this table does not repeat it). + | What the project looks like | Suggest | | ----------------------------------------------------------- | -------------- | | Empty repo, nothing built yet | Context (architect a stack first) | @@ -33,15 +35,15 @@ Read a few plain facts (action 01), then suggest the earliest unmet step. The su | A plan is ready, no code against it | Build | | Code in progress, nothing reviewed | Build, or Review if it looks done | | The build looks done | Review | -| An open pull request | Ship (carry it through, release on merge) | +| An open pull request, nothing reviewed | Review, then Ship (carry it through, release on merge) | -Having code never proves the build is finished, so onboard always lets the user pick the step rather than declaring one done. +Place at the earliest stage still unmet, reading the table top-down. Stages are cumulative: a downstream artifact implies the upstream stages are met — a plan means the need is clarified and tracked, so a project with a plan places at Build, not Clarify. Build is the exception: having code never proves it is reviewed or shipped, so onboard hedges there (see `assets/menu.md`) and lets the user pick rather than declaring one done. Clarify and Track have no disk signal, so they are the place only when no downstream artifact exists, and never a loud default. ## Beyond the steps, by discovery The steps are the spine, and they never name a specific skill. Onboard reads the installed skills (action 01) and fills each step with whatever fits. -Most setups also have skills that are not a step but a tool for when the work needs one: fixing a bug, cleaning up code, finding technical debt, adding tests, capturing a lesson, drawing a diagram. Onboard does **not** hardcode these. It reads every installed skill, places the ones that fit a step, and surfaces the rest grouped by what their own description says they do. A skill added to any plugin later shows up on its own, with no change to this file. This file describes the flow, never the catalogue of skills. +Most setups also have skills that are a tool for when the work needs one, not a step: fixing a bug, cleaning up code, adding tests, drawing a diagram. Onboard does **not** hardcode these — it ranks the relevant ones by the project signals (the capability map in `signals.md`) and resolves each to an installed skill. A skill added to any plugin later shows up on its own. This file describes the flow, never the catalogue of skills. ## Resolving a step to an installed skill diff --git a/plugins/aidd-context/skills/00-onboard/references/outcomes.md b/plugins/aidd-context/skills/00-onboard/references/outcomes.md new file mode 100644 index 00000000..f7b46255 --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/outcomes.md @@ -0,0 +1,14 @@ +# Act outcomes + +What `03-act` carries out for each choice, and whether it loops back to `01`. Only ever run or name a skill that `01` found installed. + +| Choice | What happens | Loop back to 01? | +| ---------------- | --------------------------------------------------------------------------------------------- | --------------------------- | +| Run it | Invoke the resolved skill in this session, then ask the user how it went | yes — refresh + mark done | +| Hand off | Give the exact command to run in a fresh session, wait for the user to return | yes — refresh + mark done | +| Different step | Mark the declined step skipped, hand back to `02-orient` to pick another, resolve it | no — back to 02 | +| Explain the step | Describe the step and its skill in two or three plain lines, then re-offer the choices | no — re-offer | +| Explain project | Summarize the project from its memory bank, read-only, then re-offer (only when memory filled) | no — re-offer | +| Show flow + skills | Walk the AIDD flow (`journey.md`) and list the installed skills grouped by step, then re-offer | no — re-offer | +| Stop | A one-line goodbye, end the loop | no — terminate | +| A gap | The step has no installed skill: say it needs a plugin, by function only; offer explain, a different step, or stop | no — re-offer | diff --git a/plugins/aidd-context/skills/00-onboard/references/signals.md b/plugins/aidd-context/skills/00-onboard/references/signals.md new file mode 100644 index 00000000..80e08daf --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/references/signals.md @@ -0,0 +1,38 @@ +# Project signals and the capability map + +What `01-read-project` captures into the snapshot, and which secondary tool each signal makes relevant. Stages and their order live in `journey.md`; this file is signals only. + +## Cheap signals (presence tests) + +| Signal | Met when | +| --------------- | ------------------------------------------------------------------ | +| memory synced | `aidd_docs/memory/` exists and its files hold real content | +| context block | the AI context file carries the `` block | +| architecture | `aidd_docs/INSTALL.md` exists | +| code present | any source outside `aidd_docs/` (a docs/README-only repo is empty) | +| manifest | a stack manifest (`package.json`, `pyproject.toml`, `go.mod`, …) | +| tests present | real test files exist (a configured runner alone does not count) | +| spec or plan | a spec or plan under `aidd_docs/` | +| plan status | the `status` field of a `plan.md` | +| open PR | an open pull request on the current branch | + +## Richer reads (bounded, once per session) + +| Read | Captures | +| ----------------- | ------------------------------------------------- | +| code-quality sample | a file far longer or more deeply nested than its siblings = "messy" | +| bug-marker scan | `TODO` / `FIXME` and reported errors | + +Reading memory-file contents to judge "synced" and this bounded code sample are the only sanctioned non-cheap reads. + +## Capability map (signal → secondary tool) + +Each tool is stage-gated: it surfaces only at the listed stage, and only beside the default, never as the default. + +| Signal | Stage | Surfaces | +| ------------------- | ------------- | ------------- | +| no test files | build, review | add tests | +| messy (code sample) | build, review | audit | +| bug markers | any | debug | + +A tool resolves to an installed skill by description, or is named a gap by function. The flow default itself comes from `journey.md`, never from this map. diff --git a/plugins/aidd-context/skills/01-bootstrap/SKILL.md b/plugins/aidd-context/skills/01-bootstrap/SKILL.md index d5f8efa2..e08d2142 100644 --- a/plugins/aidd-context/skills/01-bootstrap/SKILL.md +++ b/plugins/aidd-context/skills/01-bootstrap/SKILL.md @@ -1,13 +1,14 @@ --- name: 01-bootstrap -description: 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. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code). +description: 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. +argument-hint: gather-needs | propose-candidates | audit-candidates | pick-and-design | write-install-md --- # Bootstrap -Plays the role of technical architect for a new SaaS project. Walks the user through a 24-item checklist (18 user-input + 6 derived), 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. +Plays the role of technical architect for a new SaaS project. Walks the user through a 24-item checklist (18 user-input + 6 derived), 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. -## Available actions +## Actions | # | Action | Role | Input | | --- | --------------------- | -------------------------------------------------------------- | ------------------ | @@ -17,9 +18,7 @@ Plays the role of technical architect for a new SaaS project. Walks the user thr | 04 | `pick-and-design` | User picks winner; generate folder tree + Mermaid diagram | audit report | | 05 | `write-install-md` | Produce `aidd_docs/INSTALL.md` | design + decisions | -## Default flow - -`01 → 02 → 03 → 04 → 05`. Sequential. The audit (03) is a gate: if every candidate returns `❌`, loop back to 02 to revise candidates or 01 to revisit needs. +Run `01 → 02 → 03 → 04 → 05`. The audit (03) gates: if every candidate fails, loop back to 02 or 01. ## Transversal rules @@ -27,17 +26,13 @@ Plays the role of technical architect for a new SaaS project. Walks the user thr - **Anti-sycophancy.** When the user expresses a stack preference that conflicts with their needs (e.g. wants Mongo for heavily relational data), challenge it before accepting: surface audit concerns and ask whether the user has a mitigation plan. - **Recommend opinionated, not encyclopedic.** Each action proposes 2-3 options max, never a long catalog. The user should leave with a concrete decision, not a research paper. - **Stop on full checklist.** Action 01 keeps asking until the 18 user-input items (blocks 1-3) are filled; the 6 derived items (block 4) are filled across actions 02 and 04. -- **Apply heuristics from `@references/stack-heuristics.md`** when proposing candidates. +- **Apply heuristics from `references/stack-heuristics.md`** when proposing candidates. ## References -- `@references/stack-heuristics.md` - input → recommended-stack-family heuristics +- `references/stack-heuristics.md` - input → recommended-stack-family heuristics ## Assets -- `@assets/checklist.md` - the 24-item checklist (4 blocks) -- `@assets/install-template.md` - the `INSTALL.md` skeleton - -## External data - -- `aidd-context/skills/09-mermaid/SKILL.md` - invoked from action 04 to render the architecture diagram +- `assets/checklist.md` - the 24-item checklist (4 blocks) +- `assets/install-template.md` - the `INSTALL.md` skeleton diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md index 355d329c..e8028999 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md @@ -1,32 +1,26 @@ # 01 - Gather needs -Walk the user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1-3) are filled. The 6 derived items (block 4) stay empty here - they are filled by actions 02 and 04. +Walk the user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1 to 3) are filled. The 6 derived items (block 4) stay empty here; actions 02 and 04 fill them. -## Inputs +## Input -- Free-form user request to bootstrap a new SaaS project. +A free-form user request to bootstrap a new SaaS project. -## Outputs +## Output -A filled copy of `@../assets/checklist.md` held in conversation context (not yet written to disk). Each user-input item has a concrete value replacing its `<...>` placeholder. - -```markdown -- [x] **Project name** - Acme Invoicing -- [x] **One-liner** - Smart invoice tracker for freelancers, syncs with Airtable -- [x] **Type** - B2B SaaS -- [x] **Target users** - solo freelancers and 2-5 person agencies, ~500 active at 6 months -... (all 18 input items filled) -``` +A filled copy of `@../assets/checklist.md` held in conversation context, not yet written to disk, with every user-input item's `<...>` placeholder replaced by a concrete value. ## Process -1. Read `@../assets/checklist.md`. Print the four blocks as a single markdown checklist for the user to see the full scope upfront. -2. Ask block by block, one block per message. Within a block, ask all questions at once (the user answers in batch). Do not ask block 4 - it's derived. -3. For each user answer, fill the corresponding item. If an answer is vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). -4. After block 1, sanity-check coherence: does the type match the user volume? Are the integrations realistic for the platform target? -5. After block 3, surface conflicts (e.g. budget < 50€/mo + AWS preference + heavy backend → impossible). Force a re-answer on the conflicting item. -6. Print the filled checklist (blocks 1-3 only) and ask the user to confirm "go" before passing to action 02. +1. **Show.** Read `@../assets/checklist.md` and print the four blocks as one markdown checklist so the user sees the full scope upfront. +2. **Ask.** Ask block by block, one block per message, all questions in a block at once. Do not ask block 4; it is derived. +3. **Fill.** Fill each item from the answer. When an answer is vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). +4. **Check.** After block 1, sanity-check coherence: does the type match the user volume, are the integrations realistic for the platform target. +5. **Resolve.** After block 3, surface conflicts (for example budget under 50€/mo with an AWS preference and a heavy backend) and force a re-answer on the conflicting item. +6. **Confirm.** Print the filled checklist (blocks 1 to 3) and wait for the user to confirm "go" before action 02. ## Test -The 18 user-input items in the in-memory checklist have no remaining `<...>` placeholders, the 6 block-4 items are still placeholders, and the user has explicitly confirmed the filled checklist with "go" or equivalent before action 02 starts. +- The 18 user-input items have no remaining `<...>` placeholders. +- The 6 block-4 items are still placeholders. +- The user explicitly confirmed the filled checklist before action 02 starts. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md b/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md index dd7a539c..8af3df85 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md @@ -1,37 +1,26 @@ # 02 - Propose candidates -Derive 2-3 candidate stacks from the filled checklist using the heuristics in `@../references/stack-heuristics.md`, then render a markdown comparison table for the user. +Derive 2 to 3 candidate stacks from the filled checklist using the heuristics in `@../references/stack-heuristics.md`, then render a markdown comparison table. -## Inputs +## Input -- Filled checklist (blocks 1-3) from action 01. +The filled checklist (blocks 1 to 3) from action 01. -## Outputs +## Output -A markdown comparison table with 2-3 rows. - -```markdown -| Candidate | Front | Back | DB | Hosting | Auth | Archi | Cost/mo | Risks | -|-----------|-------|------|------|---------|------|-------|---------|-------| -| **A. Vercel-native** | Next.js SSR | Next.js API routes | Supabase Postgres | Vercel + Supabase | NextAuth | Modular monolith | ~30€ | Vercel lock-in, cold starts on serverless functions | -| **B. Self-hosted** | Vite + React SPA | NestJS | Postgres on VPS | Coolify on Hetzner VPS | Clerk | Modular monolith | ~15€ | Manual ops, single point of failure | -| **C. Serverless AWS** | Next.js SSR | AWS Lambda + API Gateway | DynamoDB | AWS + CloudFront | Cognito | Serverless | ~50€ at low volume, scales linearly | Vendor lock-in, learning curve | -``` - -## Depends on - -- `01-gather-needs` +A markdown comparison table with 2 to 3 rows, each a candidate with its front, back, DB, hosting, auth, architecture pattern, monthly cost, and risks. ## Process -1. Read the filled checklist from action 01. -2. Apply each rule from `@../references/stack-heuristics.md` to derive the recommended family for: archi pattern, front, back, DB, auth, hosting. -3. Build 2-3 candidates that span the trade-off space - they must differ on at least one of: hosting model (PaaS vs self-host vs serverless), back-end language, or archi pattern. Never propose 3 near-identical candidates. -4. For each candidate, estimate monthly cost at the user's volume target (Block 2 item: "Volume at 6 months"). Use rough public-pricing numbers; flag uncertainty. -5. List 1-3 risks per candidate (lock-in, ops burden, learning curve, scaling limit). Be honest - risks are non-negotiable, no candidate has zero. -6. Render the comparison table. Bold the candidate's name (`**A.**`). -7. Print the table to the user. Do not pick a winner - that's action 04, after audit. +1. **Read.** Read the filled checklist from action 01. +2. **Derive.** Apply each rule from `@../references/stack-heuristics.md` to derive the recommended family for architecture pattern, front, back, DB, auth, and hosting. +3. **Spread.** Build 2 to 3 candidates spanning the trade-off space, differing on at least one of hosting model (PaaS, self-host, serverless), back-end language, or architecture pattern. Never propose near-identical candidates. +4. **Cost.** Estimate each candidate's monthly cost at the user's six-month volume target with rough public pricing, flagging uncertainty. +5. **Risk.** List 1 to 3 honest risks per candidate (lock-in, ops burden, learning curve, scaling limit). No candidate has zero. +6. **Render.** Render the comparison table, bolding each candidate's name. Do not pick a winner; that is action 04, after the audit. ## Test -The output is a markdown table with at least 2 rows; the columns include `Front`, `Back`, `DB`, `Hosting`, `Auth`, `Archi`, `Cost`, `Risks`; each row has a non-empty value in every column; at least two rows differ on hosting model, back-end language, or archi pattern. +- The output is a markdown table with at least two rows. +- The columns include front, back, DB, hosting, auth, architecture, cost, and risks, each cell non-empty. +- At least two rows differ on hosting model, back-end language, or architecture pattern. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md b/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md index 6394bf0e..d96bc8b8 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md @@ -1,63 +1,38 @@ # 03 - Audit candidates -Spawn one parallel agent per candidate to validate the proposed stack: tech compatibility, ecosystem maturity, known gotchas. Returns a verdict (`✅ / ⚠️ / ❌`) plus a 3-bullet rationale per candidate. +Audit each candidate in parallel to validate the proposed stack: tech compatibility, ecosystem maturity, known gotchas. Returns a verdict (✅ / ⚠️ / ❌) and a three-bullet rationale per candidate. -## Inputs +## Input -- Comparison table from action 02. -- Filled checklist from action 01 (for context). +The comparison table from action 02, and the filled checklist from action 01 for context. -## Outputs +## Output -The same table from action 02, augmented with a `Verdict` column and a per-candidate rationale block below. - -```markdown -| Candidate | Verdict | Notes | -|-----------|---------|-------| -| **A. Vercel-native** | ✅ | All components mature, well-documented integration, no gotchas at this scale | -| **B. Self-hosted** | ⚠️ | Coolify is recent (< 2 years); ops burden underestimated for solo dev | -| **C. Serverless AWS** | ❌ | DynamoDB is the wrong fit for relational invoice data; Cognito has known UX friction | -``` - -Per-candidate rationale (3 bullets): - -```markdown -### A. Vercel-native - ✅ -- Next.js + Supabase is the most documented stack in 2026; copy-paste examples exist for every checklist requirement -- Vercel's Hobby tier plus Supabase free tier covers the 6-month volume target; cost forecast holds -- Cold start is the only concrete risk - irrelevant for a B2B SaaS with predictable load patterns - -### B. Self-hosted - ⚠️ -- ... -``` - -## Depends on - -- `02-propose-candidates` +The action 02 table augmented with a verdict column, plus a three-bullet rationale block per candidate. ## Process -1. For each candidate row in the table, spawn a parallel `general-purpose` Agent with this brief: +1. **Audit.** For each candidate row, spawn a parallel `general-purpose` agent with this brief: - ``` + ```text Audit the following candidate stack for a SaaS project. Validate three dimensions: - 1. Tech compatibility - do the components integrate cleanly? Any deprecated combos? - 2. Ecosystem maturity - are the components stable (≥ 2 years prod-tested) and well-documented? - 3. Known gotchas - search recent (last 12 months) issues, blog posts, HN discussions for blockers. + 1. Tech compatibility: do the components integrate cleanly? Any deprecated combos? + 2. Ecosystem maturity: are the components stable (≥ 2 years prod-tested) and well-documented? + 3. Known gotchas: search recent (last 12 months) issues, blog posts, and discussions for blockers. - Project context: + Project context: Candidate: Return: - Verdict: ✅ (no blocker) / ⚠️ (minor concerns) / ❌ (deal-breaker) - - Three bullet points justifying the verdict - concrete, citing specific tech facts - - Cost estimate confirmation: agree / disagree with the proposed monthly cost + - Three bullets justifying the verdict, concrete, citing specific tech facts, one of them stating whether the proposed monthly cost is realistic ``` -2. Wait for all agents to return. Aggregate verdicts into the table. -3. If **every** candidate returns `❌`: print the verdicts, surface the common blocker, and loop back to action 02 with explicit guidance on what to change. Do not proceed to action 04. -4. If **at least one** candidate is `✅` or `⚠️`: print the augmented table + per-candidate rationale to the user. Pass control to action 04. +2. **Aggregate.** Wait for every agent to return, then aggregate the verdicts into the table. +3. **Gate.** When every candidate returns ❌, print the verdicts, surface the common blocker, and loop back to action 02, or to 01 when the needs themselves are the blocker, with explicit guidance. Do not proceed to action 04. +4. **Pass.** When at least one candidate is ✅ or ⚠️, print the augmented table and per-candidate rationale, then pass control to action 04. ## Test -Each candidate row from action 02 has a corresponding verdict in `{✅, ⚠️, ❌}` and a rationale block with exactly 3 bullets; if all verdicts are ❌, the flow does not advance to action 04 and a guidance message back to 02 is printed. +- Each candidate row has a verdict in `{✅, ⚠️, ❌}` and a rationale block of exactly three bullets. +- When every verdict is ❌, the flow does not advance to action 04 and prints guidance back to action 02. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md b/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md index a6c8d3d8..4859ccfc 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md @@ -1,67 +1,26 @@ # 04 - Pick and design -User picks the winning candidate (informed by audit). Generate the folder structure tree and a Mermaid module diagram. Fill block 4 of the checklist with the concrete choices. +The user picks the winning candidate, informed by the audit. Generate the folder-structure tree and a Mermaid module diagram, and fill block 4 of the checklist with the concrete choices. -## Inputs +## Input -- Augmented comparison table from action 03 (with verdicts and rationale). -- Filled checklist blocks 1-3. +The augmented comparison table from action 03 (verdicts and rationale), and the filled checklist blocks 1 to 3. -## Outputs +## Output -Three artifacts held in conversation context (not yet written to disk): - -1. The checklist with **block 4 filled** (architecture pattern, front, back, DB, auth, final hosting). -2. A folder-structure code block showing the project root tree. -3. A Mermaid diagram showing modules and their relations. - -```markdown -## Folder structure - -`​`​` -acme-invoicing/ -├── apps/ -│ ├── web/ # Next.js app -│ └── workers/ # Background jobs (BullMQ) -├── packages/ -│ ├── db/ # Drizzle schema + migrations -│ ├── api/ # tRPC routers shared between web and workers -│ └── ui/ # shared React components -├── infra/ -│ └── supabase/ # Supabase project config + RLS policies -├── aidd_docs/ -│ └── INSTALL.md -└── package.json -`​`​` - -## Architecture diagram - -`​`​`mermaid -graph TD - User --> Web[Next.js Web] - Web --> API[tRPC API] - API --> DB[(Supabase Postgres)] - API --> Airtable[Airtable SDK] - Web --> Auth[NextAuth] - Workers[BullMQ Workers] --> DB - Workers --> Slack[Slack API] -`​`​` -``` - -## Depends on - -- `03-audit-candidates` +Three artifacts held in conversation context: the checklist with block 4 filled (architecture pattern, front, back, DB, auth, final hosting), a folder-structure code block of the project root tree, and a Mermaid diagram of the modules and their relations. ## Process -1. Print the action 03 augmented table. Ask the user to pick a candidate by letter (A / B / C). -2. If the picked candidate has verdict `⚠️`, surface the audit concerns directly: list the specific risks found in action 03, ask whether the user has a mitigation plan, and loop until satisfied or candidate is switched. -3. If the picked candidate has verdict `❌`, refuse the pick and loop back to letting the user choose differently. (Do not proceed with a known-broken stack.) -4. Fill block 4 of the checklist with the picked candidate's concrete choices. Show the user the full filled checklist and ask them to confirm "go". -5. Generate the folder-structure tree following conventions from the picked stack: monorepo (`apps/`, `packages/`) for modular monolith; flat `src/` for monolith; `services/` per service for microservices; `functions/` for serverless. Reflect every component listed in block 4. -6. Generate the Mermaid module diagram by invoking `aidd-context:09-mermaid`. Pass it the list of modules and their relations derived from the folder tree. Verify the rendered diagram passes Mermaid syntax (no parser errors). -7. Print the tree + diagram together. Wait for user confirmation before action 05. +1. **Pick.** Print the action 03 augmented table and ask the user to pick a candidate by name. +2. **Vet.** On a ⚠️ pick, surface the audit concerns, ask for a mitigation plan, and loop until satisfied or the pick changes. On a ❌ pick, refuse and loop back; never proceed with a known-broken stack. +3. **Fill.** Fill block 4 with the picked candidate's concrete choices, show the full checklist, and wait for the user to confirm "go". +4. **Tree.** Generate the folder-structure tree following the picked stack's conventions: a monorepo (`apps/`, `packages/`) for a modular monolith, a flat `src/` for a monolith, `services/` per service for microservices, `functions/` for serverless. Reflect every block-4 component. +5. **Diagram.** Generate the Mermaid module diagram via a Mermaid-rendering capability, passing the modules and relations from the tree, and confirm it parses without error. +6. **Show.** Print the tree and diagram together, then wait for confirmation before action 05. ## Test -The checklist's block 4 has all 6 items filled with no remaining `<...>` placeholders; a folder-structure code block is rendered; a Mermaid code block tagged ` ```mermaid ` is present and parses without error; the user has confirmed in writing. +- Block 4 has all six items filled with no remaining `<...>` placeholders. +- A folder-structure code block is rendered, and a fenced `mermaid` block is present and parses without error. +- The user confirmed in writing. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md b/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md index 73347fd1..210facfb 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md @@ -1,57 +1,31 @@ # 05 - Write INSTALL.md -Produce `aidd_docs/INSTALL.md` from the filled checklist, folder tree, diagram, and audit summary. This is the only file this skill writes to disk. +Produce `aidd_docs/INSTALL.md` from the filled checklist, folder tree, diagram, and audit summary. The only file this skill writes to disk. -## Inputs +## Input -- Filled checklist (from action 04). -- Folder structure code block (from action 04). -- Mermaid diagram (from action 04). -- Augmented audit table (from action 03). +The filled checklist, folder-structure code block, and Mermaid diagram from action 04, and the augmented audit table from action 03. -## Outputs +## Output -A new file at `aidd_docs/INSTALL.md` filled from `@../assets/install-template.md`. - -```markdown -# INSTALL.md - acme-invoicing - -Technical vision and installation guide. - -## Vision -... -## Decisions -... -## Stack summary -... -## Architecture -... -## Folder structure -... -## Install steps -... -## Audit summary -... -``` - -## Depends on - -- `04-pick-and-design` +A new `aidd_docs/INSTALL.md` filled from `@../assets/install-template.md`, with its Vision, Decisions, Stack summary, Architecture, Folder structure, Install steps, and Audit summary sections. ## Process -1. Read `@../assets/install-template.md`. This is the skeleton. -2. Fill each placeholder from upstream artifacts: - - **Vision**: project name + one-liner from block 1 - - **Decisions table**: each row from block 4 paired with a one-line `Why` derived from block 2-3 constraints - - **Stack summary**: concrete versions / SaaS plans where known - - **Architecture**: paste the Mermaid diagram from action 04 + 2-3 sentences explaining module boundaries - - **Folder structure**: paste the tree from action 04 verbatim - - **Install steps**: 3-7 imperative steps the user runs to bring up the empty project (init repo, install runtimes, create cloud accounts, set env vars). No code generation - this is a checklist, not a script. - - **Audit summary**: paste the augmented table from action 03, keep verdicts + one-line notes -3. Write the filled content to `aidd_docs/INSTALL.md` in the user's project root. If the file already exists, ask before overwriting. -4. Print the relative path of the written file and a short summary (which sections were filled, total length). +1. **Load.** Read `@../assets/install-template.md` as the skeleton. +2. **Fill.** Fill each placeholder from the upstream artifacts: + - **Vision**: project name and one-liner from block 1. + - **Decisions**: each block-4 row paired with a one-line why from the block 2 and 3 constraints. + - **Stack summary**: concrete versions or SaaS plans where known. + - **Architecture**: the action 04 Mermaid diagram plus two or three sentences on module boundaries. + - **Folder structure**: the action 04 tree verbatim. + - **Install steps**: 3 to 7 imperative steps to bring up the empty project (init repo, install runtimes, create cloud accounts, set env vars). A checklist, not a script, with no code generation. + - **Audit summary**: the action 03 augmented table, keeping verdicts and one-line notes. +3. **Write.** Write the filled content to `aidd_docs/INSTALL.md` in the project root. When the file already exists, ask before overwriting. +4. **Report.** Print the written file's relative path and a short summary of the sections filled and total length. ## Test -`aidd_docs/INSTALL.md` exists and parses as markdown; it contains exactly these `## ` H2 headings in order: `Vision`, `Decisions`, `Stack summary`, `Architecture`, `Folder structure`, `Install steps`, `Audit summary`; the `Architecture` section contains a fenced ` ```mermaid ` block; the `Folder structure` section contains a fenced code block with at least 5 lines. +- `aidd_docs/INSTALL.md` exists and parses as markdown. +- It contains these H2 headings in order: Vision, Decisions, Stack summary, Architecture, Folder structure, Install steps, Audit summary. +- The Architecture section contains a fenced `mermaid` block, and the Folder structure section a fenced code block of at least five lines. diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index 28af6162..e5957086 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -1,6 +1,7 @@ --- name: 02-project-memory -description: Initialize or refresh the project memory bank. Not for updating one memory file after it exists (use the learn skill) or editing a single rule (edit it directly). +description: Initialize or refresh the project memory bank. Use when the user wants to set up or regenerate the project's memory files. Not for updating one memory file after it exists or editing a single rule directly. +argument-hint: init-context-file | scaffold-docs | generate-memory | review-memory | sync-memory --- # Project Memory @@ -12,29 +13,34 @@ Bootstraps the project's context layer: the AI context files with a memory block | # | Action | Role | Input | | --- | ------------------- | --------------------------------------------------- | ----------------- | | 01 | `init-context-file` | Resolve the tools, then upsert the memory block | project root | -| 02 | `scaffold-docs` | Create the `aidd_docs/` structure | project root | +| 02 | `scaffold-docs` | Create the `aidd_docs/` folder structure | project root | | 03 | `generate-memory` | Detect the capabilities, generate the memory files | the memory dir | | 04 | `review-memory` | Review the memory files for consistency | the memory dir | | 05 | `sync-memory` | Fill the memory block in every context file | the context files | Run the actions in order, `01 → 05`, and run each action's `## Test` before the next. -## Transversal rules +## Memory rules -- Capture the macro picture and the non-derivable: decisions, conventions, gotchas, the why. Never restate derivable detail (a full schema, a file tree). Prefer a pointer to the code over a copy. -- Keep each memory file small. Bullets stay short, code in backticks, no version number in a tech name (`React`, not `React 19`). -- Memory files document the user's project, never AIDD's own scaffold. -- Reflect the current state only. Drop an unused section, no empty placeholder survives. -- Ask the user before including or excluding anything ambiguous. Never decide silently. -- Write files, never display their content. +Govern the content of every memory file. -## Loading +- Capture the macro and the non-derivable: decisions, conventions, gotchas, the why. Never restate a schema or a file tree. Point to the code over a copy. +- One fact, one file: define it in its home, elsewhere reference it. Naming a shared lib in its own concern is fine. +- Keep each file small. Short bullets, code in backticks, no version in a tech name (`React`, not `React 19`). +- Reflect the current state only. Drop an unused section, never leave a placeholder. -The core concerns load always. The `internal/` and `external/` directories are listed for on-demand reading, never auto-loaded. +## Action rules + +Govern how every action runs. + +- Read an asset or reference relative to this skill. If one can't be read, stop and say so, never invent. +- Ask before anything ambiguous. Never default silently. +- End with a short report of what changed. ## References - `references/mapping-ai-context-file.md`: the per-tool context-file path. +- `references/memory-block.md`: the context-file memory block and its upsert cases. - `references/capability-signals.md`: the capabilities, their signals, and the concerns each gates. ## Assets diff --git a/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md b/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md index 9bdb3044..f8836a6d 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md @@ -1,6 +1,6 @@ # 01 - Init context file -Resolve the target tools, then ensure each tool's AI context file carries the project memory block. +Ensure each target tool's AI context file carries the project memory block. ## Input @@ -12,17 +12,9 @@ One context file per confirmed tool, each carrying an empty `` block after the `### Project memory` heading. - - Block present: leave it, report "already ok". -5. **Report.** Print a table: tool, file, action taken. +1. **Detect.** Find the context files already present, by the per-tool paths in `@../references/mapping-ai-context-file.md`. Only those paths qualify; any other file is user content, off-limits. +2. **Resolve tools.** On a re-run, the tools present are the confirmed set, skip the prompt. Otherwise propose the detected tools plus the full list and ask which the user uses; wait for an explicit pick, never default to all. +3. **Upsert.** For each confirmed tool, write the memory block into its context file per `@../references/memory-block.md`. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md index b2f99bc4..3056898c 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md @@ -1,6 +1,6 @@ # 02 - Scaffold docs -Create the `aidd_docs/` structure with its root docs and empty memory subdirectories. +Create the `aidd_docs/` structure: root docs and empty memory subdirectories. ## Input @@ -12,10 +12,9 @@ The project root. ## Process -1. **Docs.** For each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`: write it from the matching `@../assets/` template if absent, or update it in place while preserving the user's customizations. +1. **Docs.** Write each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md` from its `@../assets/` template if absent, else update in place preserving the user's edits. 2. **Memory dirs.** Ensure `aidd_docs/memory/internal/` and `aidd_docs/memory/external/` exist, each with a `.gitkeep`. -3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent, leaving an existing one untouched. -4. **Report.** Print a table: path, action taken (created, updated, or skipped). +3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent; leave an existing one. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md b/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md index 6169aa59..0e719f72 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md @@ -8,24 +8,15 @@ The `aidd_docs/memory/` directory and the project root. ## Output -The `core/` memory files plus the folder of each detected capability, filled and written flat to `aidd_docs/memory/`. +The `core/` memory files plus each detected capability's folder, filled and written flat to `aidd_docs/memory/`. ## Process -1. **Gate.** Read one template (e.g. `@../assets/templates/memory/core/architecture.md`). If it cannot be read, stop: the templates are unreachable. Never invent content. -2. **Detect.** Find the project's capabilities (`@../references/capability-signals.md`). A capability holds when a concrete fact in the repo matches its definition, whether or not the fact is in the Evidence column. Never fire on an inferred domain. In a monorepo, scan every workspace, not the root manifest alone. -3. **Confirm.** Show each detected capability with the concrete evidence behind it and the templates it selects. Ask the user to confirm, add, or drop one. Block on the answer. -4. **Select.** Take every template in `core/`, plus every template in each confirmed capability's folder (`@../references/capability-signals.md`). -5. **Reconcile.** If `aidd_docs/memory/` already holds files: - - A selected concern with an existing file: update it from current reality, preserving the user's edits. - - A selected concern with no file: create it. - - An existing file whose capability is no longer detected: leave it, flag it to the user, never delete. -6. **Fill.** For each selected template, in parallel: - - Read its sections. - - Capture the macro and non-derivable facts from the project, excluding AIDD's own scaffold. Prefer a pointer to the code over a copy. - - Fill the sections. Drop a section with no content. Strip the guidance comment. Never copy a template verbatim, ask the user instead. -7. **Write.** One output per template, named by the template's basename, flat at `aidd_docs/memory/`. Never nest, never rename, never consolidate. -8. **Report.** A table: capability, concern, output file, status (created, updated, kept, or flagged). +1. **Detect.** Find the project's capabilities (`@../references/capability-signals.md`): a capability holds when a concrete repo fact matches its definition, never an inferred domain. In a monorepo, scan every workspace. +2. **Confirm.** Show each capability with its evidence and the templates it selects. Ask the user to confirm, add, or drop one. Block on the answer. +3. **Select.** Take `core/` plus each confirmed capability's folder. On an existing `aidd_docs/memory/`: update a concern from current reality (keep the user's edits), create a missing one, leave-but-flag one whose capability is gone (never delete). +4. **Fill.** For each template, knowing what earlier ones captured (never repeat a fact, point to its file): capture the macro, non-derivable facts (exclude AIDD's scaffold, point to code over a copy), fill its sections, drop an empty one, strip the guidance comment, never copy verbatim. +5. **Write.** One file per template, named by its basename, flat in `aidd_docs/memory/`. Never nest, rename, or consolidate. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md b/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md index af1b5cba..ec72b87b 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md @@ -1,6 +1,6 @@ # 04 - Review memory -Review every memory file together for cross-file consistency, and fix what is safe. +Review every memory file together for cross-file consistency and duplication, fixing what is safe. ## Input @@ -8,14 +8,15 @@ The `aidd_docs/memory/` directory with the generated files. ## Output -The memory files, corrected in place where needed, and a status table. +The memory files, corrected in place where safe, and a status report. ## Process 1. **Read.** Load every `.md` under `aidd_docs/memory/`, recursively. -2. **Review.** In one pass with all files in context, check consistency and accuracy across them. Fix a safe inconsistency in place. Flag one that needs a human. -3. **Report.** A table: file, status (clean, fixed with reason, or needs review). +2. **Review.** In one pass, check cross-file consistency and accuracy. Fix a safe issue in place, flag one that needs a human. +3. **Deduplicate.** Keep each fact in one file, drop the copies (judge by meaning, not wording). May be handed to an independent checker subagent. ## Test -- The status table covers every memory file, and each flagged file carries a reason a human can act on. +- Every memory file is covered by the report, each flagged file with a reason a human can act on. +- No fact's definition is duplicated across files. diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md b/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md index 1eee4349..b7c613c0 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md @@ -12,9 +12,8 @@ Each `` block lists the generated memory files as reference ## Process -1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to inject the references. -2. **Guard.** On a non-zero exit, print the error and stop. Tell the user to confirm `aidd_docs/memory/` holds a `.md` file and that `node` is available. -3. **Report.** Print how many context files were updated and how many references went into each block, then list the references per file. +1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to fill each block (the block: `@../references/memory-block.md`). +2. **Guard.** On a non-zero exit, print the error and stop; tell the user to check that `aidd_docs/memory/` holds a `.md` file and that `node` is available. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md index da9aad46..69bd9267 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md @@ -1,26 +1,35 @@ # AGENTS.md -> On the first message of a conversation, tell the user: "AI-Driven Development ON, {current_date}, {current_timezone}." +> 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 a claim against the project's actual state before acting on it. -- Be anti-sycophantic. Do not fold an argument because the user pushed back. Challenge weak reasoning instead of validating it. -- No flattery, no praise filler. Do not anthropomorphize yourself. -- Anticipate mistakes over agreeing. Never open with "you are right". When unsure, say "I don't know" or ask. +- **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. Lead with the result, then the reason. Drop pleasantries (sure, of course, happy to) and hedging. -- 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. -- Brevity is the default, but write in full for security warnings, irreversible actions, and any sequence where order matters. Clarity wins there. - -## Technical - -- Do not commit or push unless the user asks. -- Do not assume your knowledge is current. Be sure of an answer before giving it. +- **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.** +- **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 diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md index 7145a102..54935d4f 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md @@ -4,7 +4,7 @@ The HTTP API surface: its style, the main resources, and the contracts. ## Style -- +- - ## Resources diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md index 19c53b77..5896eee9 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md @@ -1,10 +1,6 @@ # Integration -How this system talks to others: internal communication and external services. - -## Internal - -- +How this system integrates with external/third-party services. ## External services @@ -12,10 +8,10 @@ How this system talks to others: internal communication and external services. ```mermaid flowchart LR - A[TODO: macro communication between this system and its services] + A[TODO: macro map of this system and its external services] ``` diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md index c921be86..3d844383 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md @@ -5,12 +5,7 @@ The macro technical shape: the stack, how the pieces fit, and the decisions behi ## Stack - -- - -## Structure - -- -- +- ## How it fits together diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md index 2a5b1ba7..8787d1e7 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md @@ -4,7 +4,7 @@ How the user moves through the app: routing and the page structure. ## Routing -- +- - ## Structure diff --git a/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md b/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md index 2a8ca8ef..bb00ba40 100644 --- a/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md +++ b/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md @@ -23,12 +23,3 @@ A capability holds when a concrete fact in the repo matches the capability's **d | `cli` | is run as a command-line tool | a `bin` field, or a CLI-parser dependency (commander, yargs, oclif, clap, click) | cli | | `data` | processes data or trains models | notebooks, a data-versioning or ML tool, or pipeline and model files | data | | `monorepo` | hosts several packages in one repo | workspaces, or a monorepo tool (Turborepo, Nx, Lerna) | enriches `core/codebase-map` (the Packages section), no folder | - -## How the action uses this - -- Always generate every template in `core/`. -- For each capability that holds, generate every template in its folder. -- Fire a capability on a concrete fact that matches its definition, whether or not the fact is in the Evidence column. Never fire on an inferred domain. -- A capability with no concrete fact produces no file. -- A monorepo fills the Packages section of `codebase-map`, it has no folder of its own. -- In a monorepo, gather facts across every workspace, not the root manifest alone. A capability holds when any one workspace shows it (a React app in `packages/web` means `ui` holds for the project). diff --git a/plugins/aidd-context/skills/02-project-memory/references/memory-block.md b/plugins/aidd-context/skills/02-project-memory/references/memory-block.md new file mode 100644 index 00000000..1c7c7b98 --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/references/memory-block.md @@ -0,0 +1,12 @@ +# Memory block + +The `` block is where a tool's AI context file points to the generated memory files. It sits under `## Memory Management` → `### Project memory` (full template: `@../assets/AGENTS.md`). + +## Upsert + +Apply the first case that matches a tool's context file: + +- **Absent:** copy `@../assets/AGENTS.md`, set the tool's title. +- **No `## Memory Management`:** append that section from the template. +- **Section but no block:** insert an empty `` block after `### Project memory`. +- **Block present:** leave it, report "already ok". diff --git a/plugins/aidd-context/skills/03-context-generate/SKILL.md b/plugins/aidd-context/skills/03-context-generate/SKILL.md index 788c0ec2..563e52a9 100644 --- a/plugins/aidd-context/skills/03-context-generate/SKILL.md +++ b/plugins/aidd-context/skills/03-context-generate/SKILL.md @@ -1,6 +1,6 @@ --- name: 03-context-generate -description: Route a request to generate a context artifact (skill, rule, agent, command, or hook) to its dedicated generator when the user has not named which kind. For a named kind, that generator triggers directly. Not for listing existing artifacts (use explore). +description: 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. --- # Context Generate diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md index 34aa875d..ac52a9f8 100644 --- a/plugins/aidd-context/skills/04-skill-generate/SKILL.md +++ b/plugins/aidd-context/skills/04-skill-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-skill-generate description: 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. +argument-hint: capture-intent | decompose-actions | draft-skill | write-actions | validate --- # Skill Generate @@ -21,7 +22,7 @@ Run the actions in order, `01 → 05`, and run each action's `## Test` before th ## References -- `references/skill-authoring.md`: the contract (R1-R11, action anatomy, naming). +- `references/skill-authoring.md`: the contract (R1-R13, action anatomy, naming). - `references/tool-paths.md`: per-tool skills path, frontmatter, resolution + write-safety gate. ## Assets diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md b/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md index 5b29b1ac..951559e5 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md @@ -8,13 +8,13 @@ From 01: the name, domain, what it produces, the invocation mode, the confirmed ## Output -One SKILL.md per confirmed tool, and the list of files written. +One SKILL.md per target (each confirmed host tool, or the plugin source tree), and the list of files written. ## Process 1. **Build.** Copy `@../assets/skill-template.md` into one canonical SKILL.md. Strip the scaffold (comments + `<...>`). - Modify: edit in place. Keep non-router sections, change only the touched rows. -2. **Frontmatter.** Fill per R5 and the naming (`@../references/skill-authoring.md`). `name` equals the folder. Manual mode adds the manual-only flag. +2. **Frontmatter.** Fill per R5 and the naming (`@../references/skill-authoring.md`). `name` equals the folder. For plugin source, or host tools that support it, `argument-hint` lists action names only when the skill has two or more actions, joined with ` | `, and must match the action plan. Manual mode adds the manual-only flag. - Host: per-tool frontmatter (`@../references/tool-paths.md`). - Plugin source: keep canonical `name` + `description`. Reconciled at install. 3. **Body.** Write the action table. State the flow in one line. @@ -31,4 +31,4 @@ One SKILL.md per confirmed tool, and the list of files written. - Each SKILL.md exists and starts with `---` frontmatter. - Each is 500 lines or fewer and sits under the target base. -- The action-table slugs match the plan. +- The action-table slugs match the plan. `argument-hint` is omitted for one-action skills; when emitted, its action names match the plan. diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md b/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md index 26862bfa..4dfdd597 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md @@ -14,11 +14,13 @@ One file per action, per confirmed tool, at `//actions/-< 1. **Resolve.** Host mode: for each confirmed tool, resolve the skills root from `@../references/tool-paths.md`. Plugin source: use `plugins//skills//`. 2. **Fill.** For each action, fill `@../assets/action-template.md`: strip the scaffold (comments + `<...>`), copy the test from 02 verbatim into `## Test`. +3. **Sync hint.** When the parent SKILL.md accepts `argument-hint` and has two or more actions, update it from the final action file names only, joined with ` | `. Omit it for one-action skills. In this repository, run `node scripts/sync-skill-argument-hints.mjs`; otherwise edit the field directly. - Modify: write only the changed actions, leave the rest untouched. -3. **Compose.** Include any template or reference via `@`. Never "read X then apply". -4. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +4. **Compose.** Include any template or reference via `@`. Never "read X then apply". +5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). ## Test - Each action file exists and carries `## Output`, `## Process`, `## Test`. +- One-action skills omit `argument-hint`. When present, the parent SKILL.md `argument-hint` lists the same action names as the action files. - Each sits under the target base. diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md index a9576f05..7dcb8d97 100644 --- a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md +++ b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md @@ -1,6 +1,7 @@ --- name: -description: . Use when . , use " only when a sibling skill could mis-trigger.> (<= 1024 chars, third person, no XML tags; all "when" lives here, not in the body.) +description: . 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.) +argument-hint: # omit when the skill has only one action --- # diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index b45b1cc7..c267cf4f 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -8,11 +8,14 @@ The contract every generated skill must satisfy. These rules govern the CLIENT s - **R2.** One skill = one domain. A tool domain uses a singular noun (`slack`). An activity domain uses an action verb (`review`). See `## Naming`. - **R3.** References one level deep. A reference never `@`-chains another reference. - **R4.** SKILL.md <= 500 lines. If exceeded, split into references. -- **R5.** `description` states what + when. Third person, <= 1024 chars, no XML. Conventions: - - All "when" lives here, not in the body. - - Triggers explicit and slightly pushy. The model under-triggers, so over-list. - - Lead with the plain artifact name. Parentheses for an inline definition, not dashes. - - Optionally a short `Not for ` clause, only when a sibling skill could mis-trigger. +- **R5.** `description` states what + when. Third person, no XML. Conventions: + - **Two lines max, straight to the point.** Target ~240 characters; never more than a short paragraph. Length serves recall, not completeness. The hard ceiling is 1024 chars, not a goal. + - Lead with a verb naming what the skill produces (`Generate a rule...`, `Audit a codebase...`), not a noun phrase. + - All "when" lives here, not in the body. State it as `Use when the user wants to `. List distinct triggers (the model under-triggers, so cover the real ones), but never pad with near-duplicate phrasings. + - Optionally one short `Not for ` clause to fend off a sibling that could mis-trigger, describing the overlap in plain words. + - Never name another skill, and never include a `/command` token: slash commands are tool-native, the host generates them. + - Parentheses for an inline definition, not dashes. + - Never use a colon or an em dash in the description. Split the thought into two sentences instead. - **R6.** Zero duplication. One fact, one home. Actions cite a shared file via `@` instead of restating it. - **R7.** `references/` = documents to READ and apply in place. `assets/` = files to COPY, INJECT, or fill in per run. A template, checklist, or form is an asset, not a reference, because each run instantiates it. - **R8.** Every action follows the action anatomy (below) and carries a `## Test`. @@ -43,6 +46,7 @@ The router: YAML frontmatter + markdown body. - `name` (kebab-case, <= 64 chars) MUST equal the skill's folder name. No colon, slash, dot, plugin prefix, or namespace. Reserved words forbidden: `anthropic`, `claude`. Regex `^[a-z0-9]+(-[a-z0-9]+)*$`. - `description`: per R5. +- `argument-hint` when supported or in plugin source and the skill has two or more actions: action names only, joined with ` | `, matching the files in `actions/`. Omit it for one-action skills. - A manual-only flag makes the skill user-only. The exact frontmatter key is per tool. - Body: pure router. The action table maps each `#` and slug to a role and input. State the flow (a sequential chain or a trigger-to-action map). Self-skips stated explicitly. diff --git a/plugins/aidd-context/skills/05-rule-generate/SKILL.md b/plugins/aidd-context/skills/05-rule-generate/SKILL.md index 696b9f74..dd269bcf 100644 --- a/plugins/aidd-context/skills/05-rule-generate/SKILL.md +++ b/plugins/aidd-context/skills/05-rule-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 05-rule-generate -description: Generate a coding rule that governs editor and agent behavior, across the host AI tools a project uses. Use when the user wants to write, add, or refactor a rule, a convention, or a coding standard, or to scan a codebase and propose rules. Not for other artifacts like skills, agents, commands, hooks. +description: 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. +argument-hint: capture-rule | write-rule | validate --- # Rule Generate diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index 26427308..7e4f3495 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -13,9 +13,10 @@ A short pass or fail line per rule file. ## Process 1. **Exists.** Confirm each file is on disk at its expected path. -2. **Frontmatter.** Confirm each carries its tool's scope frontmatter matching the rule's reach, per `@../references/tool-paths.md`. An all-files rule may carry no scope field. -3. **Concise.** Confirm the body is terse and on one topic. Flag a crowded file to split. +2. **Contract.** Validate the file against `@../references/rule-authoring.md`. +3. **Target.** Validate target path and frontmatter against `@../references/tool-paths.md`. +4. **Report.** Emit one pass/fail line per file. ## Test -- Every written rule file exists. Its scope frontmatter matches its reach, or is absent for an all-files rule. +Every written rule file has one pass/fail result against both referenced contracts. diff --git a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md index 9867cadf..5d40573b 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md @@ -8,6 +8,7 @@ The contract every generated rule must satisfy. A rule governs editor and agent - **R2.** Bullets only, no prose. One ultra-short rule per bullet (3-7 words). Less is more. - **R3.** Scope every rule to the files it applies to, or mark it as applying to all. - **R4.** English only, regardless of conversation language. +- **R5.** Do not add a rule bullet that repeats, weakens, or contradicts another active bullet in the same rule. ## File naming diff --git a/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md b/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md index 0aba68d9..30ad5810 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/tool-paths.md @@ -12,7 +12,7 @@ The per-tool rules path and write targets. Rule slice only, nothing about skills | OpenCode | - | no | | Codex CLI | - | no | -`` is the file name `#-slug` from `@references/rule-authoring.md` (e.g. `2-python-fstrings`). `` is that slug with its leading category digit dropped (`python-fstrings`). `` is the folder `-`, the zero-padded category index plus the category name from the taxonomy, e.g. `01-standards`. `` is that same two-digit index. +`` is the file name `#-slug` from `@rule-authoring.md` (e.g. `2-python-fstrings`). `` is that slug with its leading category digit dropped (`python-fstrings`). `` is the folder `-`, the zero-padded category index plus the category name from the taxonomy, e.g. `01-standards`. `` is that same two-digit index. Copilot is flat: no category folder. Its file is `-`, e.g. `2-python-fstrings` becomes `02-python-fstrings` (one category prefix, no folder). diff --git a/plugins/aidd-context/skills/06-agent-generate/README.md b/plugins/aidd-context/skills/06-agent-generate/README.md index a26fad72..8748dd26 100644 --- a/plugins/aidd-context/skills/06-agent-generate/README.md +++ b/plugins/aidd-context/skills/06-agent-generate/README.md @@ -1,6 +1,6 @@ ← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) -# 09 - agent-generate +# 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. diff --git a/plugins/aidd-context/skills/06-agent-generate/SKILL.md b/plugins/aidd-context/skills/06-agent-generate/SKILL.md index bbebf4ee..ed658a19 100644 --- a/plugins/aidd-context/skills/06-agent-generate/SKILL.md +++ b/plugins/aidd-context/skills/06-agent-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 06-agent-generate description: 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. +argument-hint: capture-agent | write-agent | validate --- # Agent Generate diff --git a/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md b/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md index 1db4e78c..bf34342b 100644 --- a/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md +++ b/plugins/aidd-context/skills/06-agent-generate/actions/01-capture-agent.md @@ -8,14 +8,14 @@ A free-form description of the agent's purpose, tools, and instructions. ## Output -In-context: the role and its system prompt, three proposed names, the model, a quality score, and the write mode (host with confirmed tools, or plugin source). +In-context: the role and its system prompt, the chosen name, the model, a quality score, and the write mode (host with confirmed tools, or plugin source). ## Process 1. **Gate.** Run the asset-access precheck (`@../references/tool-paths.md`). -2. **Clarify.** Ask about the purpose, tools, inputs, and instructions. If anything stays vague, ask again before moving on. +2. **Clarify.** Ask about the purpose, tools, inputs, instructions, and preferred model. If anything stays vague, ask again before moving on. 3. **Draft.** Write the canonical role (`@../references/agent-authoring.md`): a frontmatter intent + a system-prompt body. Include only the optional and orchestration sections it needs. -4. **Name.** Propose three short, catchy names that fit the purpose. +4. **Name.** Propose three short, catchy names that fit the purpose, and have the user pick one. 5. **Score.** Rate the agent 1-10 on clarity and completeness. If it scores under 8, revise and score again. 6. **Mode.** Ask where the agent goes: - **Host project**: detect the installed tools (`@../references/tool-paths.md`), propose them, and confirm which to target. @@ -23,5 +23,5 @@ In-context: the role and its system prompt, three proposed names, the model, a q ## Test -- The role, names, model, and score are stated and confirmed in writing. +- The role, name, model, and score are stated and confirmed in writing. - The score is at least 8 before writing. diff --git a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md index 77152f8f..e3c19a16 100644 --- a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md +++ b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md @@ -16,7 +16,7 @@ model: # optional, per tool-paths.md # Inputs: what it receives when invoked # Outputs: what it returns # Guardrails: what it must never do -# Skills you may invoke: other skills it may run, named by description, never a hardcoded plugin name +# Skills you may invoke: a same-plugin skill by its plugin:folder address, a cross-plugin skill by capability For an orchestration agent only: # Definition of Ready, # Definition of Done, # Decisions in scope, # Decisions out of scope, # Handoffs. See references/agent-authoring.md. --> diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md index 20728d5d..28fae750 100644 --- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md +++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md @@ -12,7 +12,7 @@ The contract every generated agent must satisfy. An agent is a focused role with ## Naming -- Short and catchy, a single word where possible: `reviewer`, `planner`, `implementer`. +- Short and catchy, a single word where possible: `executor`, `checker`, `auditor`. - Fits the role at a glance. Propose three options for the user to pick. ## Body shape @@ -22,7 +22,7 @@ Short imperative sentences. Optional sections, added only when they earn their p - `# Inputs`: what it receives. - `# Outputs`: what it returns. - `# Guardrails`: what it must never do. -- `# Skills you may invoke`: name a skill by its description, never a hardcoded plugin name. The agent discovers it at runtime. +- `# Skills you may invoke`: name a same-plugin skill by its `plugin:folder` address, for deterministic resolution. Name a cross-plugin skill by its capability, discovered at runtime, never hardcoded. - `# Definition of Ready` / `# Definition of Done`: start and finish gates. - `# Decisions in scope` / `# Decisions out of scope`: what it may decide, what it must defer. - `# Handoffs`: who it returns to. diff --git a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md index bdab55e7..5ca7a125 100644 --- a/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md +++ b/plugins/aidd-context/skills/06-agent-generate/references/tool-paths.md @@ -30,7 +30,7 @@ The canonical agent carries `name`, `description`, `model`. Emit those a row acc Codex agents are TOML, not markdown. Convert: -- Each frontmatter field becomes a top-level TOML key. Quote every string value with `'single quotes'` so a quote or apostrophe in the description stays valid TOML. +- Each frontmatter field becomes a top-level TOML key. Quote every string value with `"double quotes"` (a TOML basic string) and escape any embedded `"` or backslash, so a quote or apostrophe in the description stays valid TOML. - The body becomes `developer_instructions`, wrapped in `'''` literal delimiters (no escaping of the markdown). - Drop `model`. diff --git a/plugins/aidd-context/skills/07-command-generate/README.md b/plugins/aidd-context/skills/07-command-generate/README.md index 8fe6196d..efd2bddf 100644 --- a/plugins/aidd-context/skills/07-command-generate/README.md +++ b/plugins/aidd-context/skills/07-command-generate/README.md @@ -1,6 +1,6 @@ ← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) -# 10 - command-generate +# 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. diff --git a/plugins/aidd-context/skills/07-command-generate/SKILL.md b/plugins/aidd-context/skills/07-command-generate/SKILL.md index f0d40d02..6f349a3d 100644 --- a/plugins/aidd-context/skills/07-command-generate/SKILL.md +++ b/plugins/aidd-context/skills/07-command-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 07-command-generate description: 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. +argument-hint: capture-command | write-command | validate --- # Command Generate diff --git a/plugins/aidd-context/skills/07-command-generate/references/tool-paths.md b/plugins/aidd-context/skills/07-command-generate/references/tool-paths.md index c8fe5c41..663455b0 100644 --- a/plugins/aidd-context/skills/07-command-generate/references/tool-paths.md +++ b/plugins/aidd-context/skills/07-command-generate/references/tool-paths.md @@ -6,8 +6,6 @@ The per-tool command path and write targets. Command slice only, nothing about s | Tool | Path | Supported | | -------------- | ------------------------------------------- | ------------------------------------ | -| Tool | Path | Supported | -| -------------- | ----------------------------------------- | ------------------------------------ | | Claude Code | `.claude/commands//.md` | yes | | Cursor | `.cursor/commands//.md` | yes (plain markdown, no frontmatter) | | OpenCode | `.opencode/commands//.md` | yes | diff --git a/plugins/aidd-context/skills/08-hook-generate/SKILL.md b/plugins/aidd-context/skills/08-hook-generate/SKILL.md index 07769648..d1648418 100644 --- a/plugins/aidd-context/skills/08-hook-generate/SKILL.md +++ b/plugins/aidd-context/skills/08-hook-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 08-hook-generate -description: Generate a hook (a handler that runs automatically at a lifecycle event) across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a hook, or automate an action at a lifecycle point. Not for other artifacts like skills, rules, agents, commands. +description: Generate a hook, a handler that runs at a lifecycle event, across the host AI tools. Use when the user wants to create, scaffold, or refactor a hook, or automate an action at a lifecycle point. Not for other artifacts like skills or rules. +argument-hint: capture-hook | write-hook | validate --- # Hook Generate diff --git a/plugins/aidd-context/skills/08-hook-generate/references/hook-authoring.md b/plugins/aidd-context/skills/08-hook-generate/references/hook-authoring.md index 4ccbd4a1..8a8d4eca 100644 --- a/plugins/aidd-context/skills/08-hook-generate/references/hook-authoring.md +++ b/plugins/aidd-context/skills/08-hook-generate/references/hook-authoring.md @@ -14,7 +14,7 @@ The contract every generated hook must satisfy. A hook is a handler wired to a l ## Lifecycle moments -The agnostic moments a hook can target. Each tool names these differently and supports a different subset. The mapping and the gaps live in `references/tool-paths.md`. +The agnostic moments a hook can target. Each tool names these differently and supports a different subset. `references/tool-paths.md` maps the commonly supported moments to each tool's event name; a moment absent from that table has no dedicated cross-tool event, so fold it into the nearest supported moment. | Moment | Fires when | | ------------------- | --------------------------------------------------- | diff --git a/plugins/aidd-context/skills/09-mermaid/SKILL.md b/plugins/aidd-context/skills/09-mermaid/SKILL.md index 34a35d57..b615b3c1 100644 --- a/plugins/aidd-context/skills/09-mermaid/SKILL.md +++ b/plugins/aidd-context/skills/09-mermaid/SKILL.md @@ -1,6 +1,6 @@ --- name: 09-mermaid -description: Generate a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. Use when the user wants to turn an architecture, lifecycle, or flow description into a Mermaid diagram, or when another skill needs one. Not for other diagram formats like PlantUML or Graphviz, or for rendering a diagram to an image. +description: 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. --- # Mermaid diff --git a/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md b/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md index bcb94d8f..9ea04c44 100644 --- a/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md +++ b/plugins/aidd-context/skills/09-mermaid/actions/01-mermaid.md @@ -17,7 +17,7 @@ A Mermaid diagram in a fenced block, plus an optional review note. On the first 3. **Confirm.** Ask the user to confirm the plan. Block on the answer. 4. **Generate.** Produce a valid Mermaid diagram from the confirmed plan, following the conventions and defaults in `@../references/mermaid-conventions.md`. 5. **Offer a review.** Ask whether the user wants a review, and wait. -6. **Review on confirm.** Check the syntax, look for an empty or misplaced node, and suggest improvements. Never add an element that was not in the confirmed plan. +6. **Review on confirm.** Check the syntax, look for an empty or misplaced node, and suggest improvements. ## Test diff --git a/plugins/aidd-context/skills/10-learn/SKILL.md b/plugins/aidd-context/skills/10-learn/SKILL.md index 2abbab67..a9e04f4f 100644 --- a/plugins/aidd-context/skills/10-learn/SKILL.md +++ b/plugins/aidd-context/skills/10-learn/SKILL.md @@ -1,6 +1,7 @@ --- name: 10-learn -description: Capture durable project learnings from the conversation or the project's git history and route them to memory, a decision record, a rule, or a new skill. Use when the user asks to capture, record, or remember a decision, a convention, or a lesson, or to distill what recent work taught. Scores each candidate and confirms before writing. Not for personal or AI preferences, routine edits, or anything already captured. +description: 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. +argument-hint: gather | assess | write | sync --- # Learn diff --git a/plugins/aidd-context/skills/10-learn/actions/02-assess.md b/plugins/aidd-context/skills/10-learn/actions/02-assess.md index 9def3fc0..a63fd816 100644 --- a/plugins/aidd-context/skills/10-learn/actions/02-assess.md +++ b/plugins/aidd-context/skills/10-learn/actions/02-assess.md @@ -14,7 +14,8 @@ A plan the user has approved: the lessons to keep, each with its destination. 1. **Score.** Give each candidate a relevance score from 0 to 10 with a one-line reason. Weigh how durable it is, how far it generalizes beyond this task, and whether it extends or contradicts existing context. 2. **Propose and reconcile.** For each candidate, name the destination it fits (Memory, Decision, Rule, or Skill, see the skill's Destinations). Then read that destination's current content and classify the candidate against it: new, already covered, or a change to what is there. A reworded repeat of something already captured is already covered, not a new lesson, even when the existing wording differs. A candidate that reverses an existing entry supersedes it. -3. **Ask.** Show the candidates sorted by score, each with its score, reason, destination, and how it reconciles (new, already covered, or supersedes). Recommend the bar at 6 of 10 and recommend skipping the already-covered ones. For every candidate, let the user keep it, move it to another destination, or skip it. Write nothing anywhere until the user has decided. Block on the answer. +3. **Show.** Show the candidates sorted by score, each with its reason, destination, and reconciliation (new, already covered, or supersedes). Recommend the bar at 6 of 10 and skipping the already-covered. +4. **Decide.** Let the user keep, redirect, or skip each. Write nothing until they decide; block on the answer. ## Test diff --git a/plugins/aidd-context/skills/10-learn/actions/03-write.md b/plugins/aidd-context/skills/10-learn/actions/03-write.md index b9558365..eca8e2c1 100644 --- a/plugins/aidd-context/skills/10-learn/actions/03-write.md +++ b/plugins/aidd-context/skills/10-learn/actions/03-write.md @@ -13,7 +13,7 @@ The created or updated files, and a summary table. ## Process 1. **Write by destination:** - - **Memory.** Update the matching memory file at the root of the bank. Touch only the relevant section, and replace an entry the lesson supersedes rather than adding a contradicting one. Preserve the user's edits. + - **Memory.** Update the matching memory file at the root of the bank. Touch only the relevant section, and replace an entry the lesson supersedes rather than adding a contradicting one. - **Decision.** Write a record in `aidd_docs/memory/internal/decisions/` from `@../assets/decision-template.md`, named by a short slug. Create the folder if absent. - **Rule.** Hand the convention to the rule generator. Never write a rule file here. - **Skill.** Hand the intent to the skill generator. Never write a skill file here. diff --git a/plugins/aidd-context/skills/10-learn/actions/04-sync.md b/plugins/aidd-context/skills/10-learn/actions/04-sync.md index 44f74ade..131e158a 100644 --- a/plugins/aidd-context/skills/10-learn/actions/04-sync.md +++ b/plugins/aidd-context/skills/10-learn/actions/04-sync.md @@ -14,7 +14,7 @@ Each memory block lists the current memory files, and the memory index is refres 1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to inject the references and refresh the memory index. 2. **Guard.** On a non-zero exit, print the error and stop. Tell the user to confirm the memory bank holds a file and that `node` is available. -3. **Report.** Print how many context files were updated and how many references went into each block. +3. **Report.** Print which context files were updated and the references that went into each block. ## Test diff --git a/plugins/aidd-context/skills/11-explore/SKILL.md b/plugins/aidd-context/skills/11-explore/SKILL.md index d7558dd2..5ad5ffd7 100644 --- a/plugins/aidd-context/skills/11-explore/SKILL.md +++ b/plugins/aidd-context/skills/11-explore/SKILL.md @@ -1,6 +1,7 @@ --- name: 11-explore -description: Explore the current project across its tooling, context, and codebase. Use to survey what is installed and set up, see what is available, or find which installed skill, agent, or rule fits a goal. Not for the next step to take (onboard does that) or running an item (this skill only points). +description: 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. +argument-hint: survey | drill --- # Explore diff --git a/plugins/aidd-context/skills/11-explore/actions/01-survey.md b/plugins/aidd-context/skills/11-explore/actions/01-survey.md index 502c1009..8b868871 100644 --- a/plugins/aidd-context/skills/11-explore/actions/01-survey.md +++ b/plugins/aidd-context/skills/11-explore/actions/01-survey.md @@ -12,12 +12,12 @@ A map grouped by axis, Tooling, Context, and Codebase. Each axis lists what is t ## Process -1. **Detect the tools.** Find which AI tools the project uses from the signals in `@../references/ai-mapping.md`. Propose the set when it is ambiguous, never assume one silently. -2. **Scan Tooling.** For each detected tool, gather the installed skills, agents, commands, rules, hooks, MCP servers, and plugins from the surfaces in `@../references/ai-mapping.md`. A surface a tool does not have is skipped, never an error. +1. **Detect the tools.** Find which AI tools the project uses by the presence signal in `@../references/ai-mapping.md`, keying on a tool's own mapped surfaces, never a shared parent directory. Propose the set when it is ambiguous, never assume one silently. +2. **Scan Tooling.** For each detected tool, gather the installed skills, agents, commands, rules, hooks, MCP servers, and plugins from the surfaces in `@../references/ai-mapping.md`. 3. **Scan Context.** The memory bank under `aidd_docs/memory/` and whether its files are filled, any specs or plans under `aidd_docs/`, and whether the AI context files carry the `` block. 4. **Scan Codebase.** The stack, from the manifest or from the memory bank, and the few top-level modules or layers. -5. **Present the map.** One section per axis, each a short list or count with one-line purposes. No next-step advice, that belongs to the onboard skill. -6. **Propose to dig in.** Offer the three axes or all, and hand the pick to `02-drill`. Never assume one. Wait for the answer. +5. **Present the map.** One section per axis, each a short list or count with one-line purposes. +6. **Propose to dig in.** Offer the three axes or all, and hand the pick to `02-drill`. Wait for the answer. ## Test diff --git a/plugins/aidd-context/skills/11-explore/references/ai-mapping.md b/plugins/aidd-context/skills/11-explore/references/ai-mapping.md index fb30d65f..388337fb 100644 --- a/plugins/aidd-context/skills/11-explore/references/ai-mapping.md +++ b/plugins/aidd-context/skills/11-explore/references/ai-mapping.md @@ -2,6 +2,10 @@ Where to look for each artifact type per AI tool. Scan-only: the paths and formats the survey and drill actions read. This is explore's own minimal map, the single source of per-tool surfaces. Actions never hardcode a tool. +## Presence signal + +A tool is present only when one of its own mapped surfaces below holds a file. A shared parent directory is never a signal by itself. + ## AI quick map - content artifacts | AI | Agents | Commands / Prompts | Rules | Skills | Context file | diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index e0b61a88..81ec2230 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -1,6 +1,7 @@ --- name: 12-cook -description: Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe". +description: 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. +argument-hint: list | upsert --- # Cook diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index 62e87015..c7e681e5 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,11 +1,15 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/.md`, scaffolded from `@assets/recipe-template.md`. +Create or update one recipe at `recipes/.md`, scaffolded from `@../assets/recipe-template.md`. ## Input The recipe topic. Ask for any missing field (level, time, prerequisites, steps, verify, related) before writing. +## Output + +The recipe file at `recipes/.md`, filled from the template, with its row added or refreshed in `recipes/README.md`. + ## Process 1. Derive a kebab-case `` from the topic → `recipes/.md`. @@ -15,3 +19,4 @@ The recipe topic. Ask for any missing field (level, time, prerequisites, steps, ## Test - `recipes/.md` exists and matches the template, every section present, no `<...>` placeholder left. +- `recipes/README.md` carries a row for ``: its title linked, plus the goal and level. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index cdf37fd3..278237ca 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -16,9 +16,9 @@ ## Steps -1. 📋 **** — -2. 🔧 **** — -3. ✅ **** — +1. 📋 ****: +2. 🔧 ****: +3. ✅ ****: ## Verify diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json index a851b8ae..3518598f 100644 --- a/plugins/aidd-dev/.claude-plugin/plugin.json +++ b/plugins/aidd-dev/.claude-plugin/plugin.json @@ -21,9 +21,8 @@ "./skills/10-todo" ], "agents": [ - "./agents/implementer.md", - "./agents/planner.md", - "./agents/reviewer.md" + "./agents/executor.md", + "./agents/checker.md" ], "keywords": [ "sdlc", diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index ec41b86e..3841384c 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -33,9 +33,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [implementer.md](agents/implementer.md) | `Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges.` | -| [planner.md](agents/planner.md) | `Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents.` | -| [reviewer.md](agents/reviewer.md) | `Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next.` | +| [checker.md](agents/checker.md) | `Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix.` | +| [executor.md](agents/executor.md) | `Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.` | ### `skills` @@ -49,31 +48,33 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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) | `Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated.` | +| `-` | [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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | -| `actions` | [02-components-behavior.md](skills/01-plan/actions/02-components-behavior.md) | - | - | -| `actions` | [03-image-extract-details.md](skills/01-plan/actions/03-image-extract-details.md) | - | - | -| `assets` | [master-plan-template.md](skills/01-plan/assets/master-plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | -| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and acceptance criteria.` | - | -| `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - | -| `-` | [README.md](skills/01-plan/README.md) | - | - | -| `references` | [mermaid-conventions.md](skills/01-plan/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).` | - | -| `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-gather.md](skills/01-plan/actions/01-gather.md) | - | +| `actions` | [02-explore.md](skills/01-plan/actions/02-explore.md) | - | +| `actions` | [03-wireframe.md](skills/01-plan/actions/03-wireframe.md) | - | +| `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.` | #### `skills/02-implement` | Group | File | Description | |-------|------|---| -| `actions` | [01-implement.md](skills/02-implement/actions/01-implement.md) | - | +| `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) | `Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness.` | +| `-` | [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.` | #### `skills/03-assert` @@ -82,35 +83,36 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-assert.md](skills/03-assert/actions/01-assert.md) | - | | `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) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `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 features work as intended - general assertions, architecture conformance, and frontend UI validation.` | +| `-` | [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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-code-quality.md](skills/04-audit/actions/01-code-quality.md) | - | - | -| `actions` | [02-architecture.md](skills/04-audit/actions/02-architecture.md) | - | - | -| `actions` | [03-security.md](skills/04-audit/actions/03-security.md) | - | - | -| `actions` | [04-dependencies.md](skills/04-audit/actions/04-dependencies.md) | - | - | -| `actions` | [05-performance.md](skills/04-audit/actions/05-performance.md) | - | - | -| `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) | `Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert).` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-code-quality.md](skills/04-audit/actions/01-code-quality.md) | - | +| `actions` | [02-architecture.md](skills/04-audit/actions/02-architecture.md) | - | +| `actions` | [03-security.md](skills/04-audit/actions/03-security.md) | - | +| `actions` | [04-dependencies.md](skills/04-audit/actions/04-dependencies.md) | - | +| `actions` | [05-performance.md](skills/04-audit/actions/05-performance.md) | - | +| `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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | - | -| `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | - | -| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | - | -| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | - | -| `-` | [README.md](skills/05-review/README.md) | - | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | +| `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.` | #### `skills/06-test` @@ -119,7 +121,7 @@ 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 on tests until they pass, and validate user journeys end-to-end in the browser.` | +| `-` | [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` @@ -130,7 +132,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill).` | +| `-` | [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,18 +144,20 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation.` | +| `-` | [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.` | #### `skills/09-for-sure` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | - | -| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | - | -| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | - | -| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | `For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.` | - | -| `-` | [README.md](skills/09-for-sure/README.md) | - | - | -| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | +| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | +| `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.` | #### `skills/10-todo` @@ -161,5 +165,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `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, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | +| `-` | [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 349b66e1..99939744 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -15,11 +15,11 @@ 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) | Generate technical implementation plans, define component behaviors, and extract design details from images. | -| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. | +| [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 code quality against project rules and validate feature behavior against plan specifications. | +| [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. | @@ -29,6 +29,5 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Agent | Description | |---|---| -| planner | Orchestrator. Turns a validated spec into milestones, drives the implementer/reviewer loop, escalates blocked decisions. Never writes code, never judges code. | -| implementer | Milestone executor. Codes, tests, repairs within the milestone scope. Commits atomically per ticked checkbox. Returns completion score. | -| reviewer | Independent critic in fresh context. Verifies an artifact against an explicit validator (acceptance criteria or checklist). Returns findings, completion and quality scores. Never edits the artifact. | +| executor | Dispatched doer in its own context. Turns a scoped task into working, validated code that fits the project, deciding how, never what. Never authors a plan, never judges its own work. | +| checker | Independent critic in fresh context. Judges finished work against its validator and the real need, leaving nothing unchecked. Returns findings, scores, and a verdict. Never edits the work, never implements the fix. | diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md new file mode 100644 index 00000000..6ed4cf32 --- /dev/null +++ b/plugins/aidd-dev/agents/checker.md @@ -0,0 +1,44 @@ +--- +name: checker +description: Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix. +model: opus +--- + +# Role + +You are the checker. Your job is to judge finished work against its validator and the real need, in a fresh context with no memory of how it was built, and to leave nothing unchecked. + +# Behavior + +- Build your validator stack first: the acceptance criteria and the need the work is meant to serve. Extend the checklist below with the project's own review checklist when it provides one. +- Judge each criterion: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. +- Run the checklist on every code or diff, leaving no item unchecked. +- Then check the layer the reviews miss: does the delivered logic serve the actual need, end to end, even when code review and functional review both pass? Name any gap between intent and result. +- Demand command output or file evidence, never bare claims. Lean strict: a false alarm costs less than a missed defect. +- Return your verdict, findings, and score to whoever invoked you. Hold yourself accountable for whatever you pass. + +# Checklist + +This is the behavioral baseline. Apply it to every code or diff, and extend it with the project's own checklist when one exists. + +- [ ] No information duplication. DRY across code and docs; link to the canonical home instead of copying. +- [ ] No incoherence or contradiction. Naming, behavior, and docs-versus-code stay consistent. +- [ ] No over-engineering. The simplest solution that meets the need; no speculative generality, no unused abstraction. +- [ ] No dead code or debug leftovers. No commented-out blocks, stray logs, or silent TODOs. + +# Scoring + +- If the validator defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero. +- Otherwise score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning. +- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail. + +# Guardrails + +- Never edit the work or its validator. Never implement the fix. Never delegate to another agent. +- Never pass on vibes: tie every verdict to a stated criterion, a checklist item, or a named need-gap. +- Flag an ambiguous criterion instead of guessing. Do not go easy because the work looks impressive. + +# Skills you may invoke + +- `aidd-dev:05-review` +- `aidd-dev:04-audit` diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md new file mode 100644 index 00000000..d9f3ad86 --- /dev/null +++ b/plugins/aidd-dev/agents/executor.md @@ -0,0 +1,33 @@ +--- +name: executor +description: Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work. +model: sonnet +--- + +# Role + +You are the executor. Your job is to turn a dispatched task into working, validated code that fits the project. You decide how, never what. + +# Behavior + +- Honour the project's own conventions where it defines them, and match the code around you. Where it stays silent, follow the prevailing idiom. +- Internalize the acceptance criteria before writing anything. If the scope is ambiguous, surface it instead of guessing. +- Work in a tight loop: build a substep, validate it, repair on red, and only then move on. Validation passing is the gate, never your own say-so. +- Commit per coherent unit, code and its status together, one unit one commit. +- When you finish or stall, return to whoever invoked you with what is done, what is left, and why. + +# Guardrails + +- Never author or edit a plan, spec, or acceptance criterion. That authority is the caller's. On any drift, stop and hand it back to be replanned. +- Stay strictly in the scope you are handed. Declare anything you bypass: no silent TODO, skipped test, or placeholder mock. +- Never judge your own work, and never start a review. The caller handles that. +- Never delegate to another agent. +- When the work is physically impossible for the AI, stop and say so plainly: a real payment, a human login, an unreadable secret, anything behind hardware or 2FA. Do not fake progress. + +# Skills you may invoke + +- `aidd-dev:02-implement` +- `aidd-dev:03-assert` +- `aidd-dev:06-test` +- `aidd-dev:08-debug` +- `commit` (cross-plugin, by capability) diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md deleted file mode 100644 index ae744ae0..00000000 --- a/plugins/aidd-dev/agents/implementer.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: implementer -description: Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges. -model: sonnet ---- - -# Role - -You build what the top-level SDLC orchestrator or Planner specifies, within the boundaries of the input. You decide how to implement, never what. You report back honestly: what you finished, what you couldn't, and why. - -You implement directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- A milestone description with explicit acceptance criteria, OR a fix list, OR an `items_remaining` set -- A relevant slice of the spec (for reference) -- Optionally, validation commands (lint, type check, tests, build) - -# Outputs - -When you return, your output is structured: - -```yaml -items_implemented: - - -items_remaining: - - -completion_score: <0-100> # percentage of input scope actually delivered -notes: -``` - -# Definition of Ready - -You may start when: - -- The input scope is identified with explicit acceptance criteria -- Validation commands are available (or you can derive them from project conventions) - -If the scope is ambiguous, return immediately with `completion_score: 0` and an explanation in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every item in the input scope has been attempted (or explicitly skipped with reason) -- Every attempted item has been validated locally (lint, types, tests, build pass) -- The output accurately reports `items_implemented`, `items_remaining`, and `completion_score` - -# Behavior - -- Internalize acceptance criteria before writing code. -- If a fix list or items_remaining was provided, focus only on those. No scope expansion. -- Implement substep by substep. Validate after each substep. Repair before moving on. No accumulation. -- Before package installation or generated build work, make sure `.gitignore` excludes `.env`, `.env.local`, `.env.*.local`, `node_modules/`, `dist/`, `.astro/`, coverage output, and tool caches. -- Never stage or commit generated artifacts (`node_modules/`, `dist/`, `.astro/`, coverage output, caches). -- If generated artifacts were already tracked before your work, remove them from version control in a dedicated hygiene commit before implementation or package installation. Do not mix those deletions with feature commits. If the caller explicitly says hygiene was already handled, verify with `git ls-files node_modules dist .astro coverage`. -- **After every ticked acceptance criterion, commit atomically** via `aidd-vcs:01-commit` with `mode: auto`, `message: "/: "`, `push: false`, or plain `git commit` if the VCS skill is unavailable. One acceptance criterion = one commit. Tasks within a phase guide HOW to implement and do not trigger commits - only the verified-state checkboxes (acceptance criteria) do. This is non-negotiable: the audit trail is the safety net. -- If the milestone involves providers, unit tests must use fixtures while integration tests must exercise the real provider code path. HTTP mocks/cassettes are acceptable only at the network boundary. -- If you cannot complete an item (technical blocker, ambiguity, missing dependency), record it in `items_remaining` and explain in `notes`. Don't fake completion. -- Be honest about `completion_score`. Underreporting is acceptable. Overreporting breaks the loop and produces silent failures. -- When done (fully or partially), return your output. The Planner decides what happens next. - -# Decisions in scope - -- Implementation choices: libraries, patterns, file layout, naming -- Substep decomposition inside the input scope -- Local refactors strictly within the input scope -- Atomic commit messages (one commit per ticked checkbox is mandatory; you decide the message wording) - -# Decisions out of scope - -- Modifying acceptance criteria - Planner -- Judging your own work - Reviewer -- Replanning, pivoting, expanding scope - surface in `items_remaining` + `notes` - -# Skills you may invoke - -- `aidd-dev:01-plan` (read-only - for context) -- `aidd-dev:03-assert` -- `aidd-dev:06-test` -- `aidd-dev:08-debug` -- `aidd-dev:04-audit` -- `aidd-dev:07-refactor` -- `aidd-vcs:01-commit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the Planner who spawned you. - -# Guardrails - -- No TODOs in code, no skipped tests, no placeholder mocks. -- No silent workarounds. If you bypass a constraint, declare it in `notes`. -- When the work is physically impossible for the AI (see the implement skill's blocked reference for what counts), return `completion_score: 0` with `notes: "BLOCKED: "` — do not fake progress. You decide this block; the implement layer writes `status: blocked`. -- Stay strictly inside the input scope. -- Never modify the spec. -- Never start the Reviewer yourself - the Planner handles that based on your output. -- Never batch checkbox completions into a single commit. One ticked box = one commit, always. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md deleted file mode 100644 index fc0506cc..00000000 --- a/plugins/aidd-dev/agents/planner.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: planner -description: Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents. -model: opus ---- - -# Role - -You are the Planner. Your job is to turn an immutable spec into an executable plan with clear milestones, acceptance criteria, validation commands, and recorded decisions. - -The top-level `aidd-dev:00-sdlc` skill owns the implementation loop. Do not try to spawn implementer or reviewer agents. In Claude Code, agents spawned from `Agent` may not have `Agent` or `Task`; treating that as a blocker wastes the run. Return plans and structured decisions only. - -# Inputs - -When invoked, you receive: - -- A spec (path or inline content) - the immutable target -- Optionally, a working directory for plan and decision artifacts -- Optionally, a previous output from Implementer or Reviewer to interpret for replanning -- Optionally, a human message for clarification or replan - -# Outputs - -When you return, your output is a structured table: - -```yaml -plan_path: -child_paths: [] -decisions_made: - - id: - topic: - decision: - rationale: -decisions_blocked: - - id: - topic: - blocker: - needs: human_approval | clarification | external_input -notes: -``` - -`plan_path` and `child_paths` reflect what `aidd-dev:01-plan` actually wrote - the skill picks the path (typically `aidd_docs/tasks//-?<#ticket>-.md` for simple plans, plus `*-master.md` and `*-part-N.md` for master plans). Capture them from the skill's output and surface them so the SDLC orchestrator can commit, summarize, and route to Phase 3 correctly. - -# Definition of Ready - -You may start when: - -- The spec exists and is non-empty -- The spec contains target, hard constraints, non-goals, and a "done-when" section -- If any of these are missing, escalate before producing anything - -# Definition of Done - -The plan is complete when: - -- Every milestone required by the spec is represented. -- Every milestone has tasks, acceptance criteria, validation commands, dependencies, and expected commit boundaries. -- The decisions table reflects all planning decisions made; blocked decisions are surfaced. - -# Behavior - -- Treat the spec as immutable. If it must change, escalate. -- Decompose the spec into milestones small enough for one Implementer pass. Each milestone has acceptance criteria and validation commands the Reviewer can execute. -- If the repo may contain tracked generated artifacts (`node_modules`, `dist`, `.astro`, coverage), include a preflight hygiene task or milestone that removes them from version control in a dedicated commit before any package install or feature work. -- If previous implementer/reviewer output is supplied, update the plan or produce a focused replan. Do not execute the fix yourself. -- Decide what counts as "satisfactory" based on the spec and the milestone, not on hardcoded numbers when the spec asks for tighter or looser standards. -- Keep the plan small enough to execute. Prefer 3 to 6 milestones for typical apps; use more only when the work is genuinely broad. -- Record any structural decision (architectural pivot, scope reduction, ambiguity resolution) in the decisions table. - -# Decisions in scope - -- Milestone decomposition and ordering -- Acceptance criteria granularity -- Intended architecture (high-level) -- What counts as "satisfactory quality" for this spec -- Decision records - -# Decisions out of scope - -- Implementation choices (libraries, patterns, file layout) - Implementer -- Quality scoring methodology - Reviewer -- Whether to start a new run - Gardener or human via `sdlc` -- Modifying the spec - escalate - -# Skills you may invoke - -- `aidd-refine:01-brainstorm` -- `aidd-refine:02-challenge` -- `aidd-context:09-mermaid` -- `aidd-context:10-learn` -- `aidd-dev:01-plan` - -Anything else is out of bounds. - -# Handoffs - -- Return `plan_path`, `child_paths`, `decisions_made`, and `decisions_blocked`. -- The top-level SDLC orchestrator will spawn `aidd-dev:implementer` and `aidd-dev:reviewer` itself. -- If a decision can be made conservatively, make it and record it. Prefer progress over escalation. -- Use `decisions_blocked` only for decisions that would make implementation unsafe or impossible. - -# Guardrails - -- Never edit the spec. -- Never touch source code. -- Never invoke or search for `Task`, `Agent`, or other spawn tools. They are not required in this role. -- No passive blocking. When in doubt, make a conservative planning assumption and record it unless the spec explicitly forbids that. diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md deleted file mode 100644 index 6724f012..00000000 --- a/plugins/aidd-dev/agents/reviewer.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -name: reviewer -description: Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next. -model: opus ---- - -# Role - -You start with no memory of how the artifact was produced. You judge what was delivered against an explicit validator. Skeptical by default. You describe what's wrong; you never fix it. You don't decide the next step - the caller (typically the Planner or SDLC) does. - -You review directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- An **artifact** to review - code changes, a spec document, a plan document, a doc, or any reviewable scope -- A **validator** - either explicit acceptance criteria (e.g., a milestone's criteria) OR a checklist file (YAML, JSON, or markdown) that enumerates the criteria -- Optionally, **context** - e.g., the spec when reviewing a plan, or the plan when reviewing code - -# Outputs - -When you return, your output is structured: - -```yaml -items_reviewed: - - criterion: - status: fulfilled | partial | unfulfilled - evidence: -findings: - - severity: critical | major | minor - description: - location: - suggested_fix: -completion_score: <0-100> # % of criteria you actually reviewed -quality_score: <0-100> # your overall quality assessment -notes: -``` - -# Definition of Ready - -You may start when: - -- The artifact is readable -- The validator is explicit (criteria are listed and unambiguous) - -If the validator is missing or ambiguous, return immediately with `completion_score: 0` and explain in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every criterion has been judged (or explicitly skipped with reason in `notes`) -- A `completion_score` and a `quality_score` are reported with justification -- Findings are precise enough to act on without further investigation - -# Behavior - -- Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. -- For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. -- Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). -- For provider work, verify that fixture unit tests and real-provider integration tests are separated. Mocks/cassettes only pass if they exercise the real provider implementation and transformer. -- For frontend work, verify build/routing/design/accessibility contracts when they are in the validator. Do not accept screenshots or claims without command output or file evidence when a command can be run. -- Report findings with enough detail that the next pass can fix without guessing. -- When uncertain on a criterion, mark it `partial` and explain in `notes`. Don't bluff. -- Lean toward stricter scoring. False positives on quality cost less than false negatives. - -## Scoring protocol - -The way you compute `quality_score` depends on the validator format. - -- **YAML validator with `weights`, `hard_thresholds`, `scoring.pass_threshold`** (e.g. `spec-validator.yml`): - apply the file's protocol exactly. Don't substitute judgment. - 1. Score each criterion `fulfilled` (full weight) / `partial` (half weight) / `unfulfilled` (zero). - 2. Sum the weighted scores, normalize to 0–100 → that is `quality_score`. - 3. Apply `hard_thresholds`: any condition flagged forces `quality_score: 0` and `notes: "hard threshold violated: "`. Hard thresholds override the weighted sum, no exceptions. - 4. Required criteria unfulfilled → also forces `quality_score: 0`. - 5. The `scoring.pass_threshold` is the caller's gate - you don't decide pass/fail, you report the score. -- **Plain checklist (markdown bullets, no weights)**: - fall back to your earlier rule - `quality_score` is the proportion of fulfilled criteria, adjusted for severity of findings, with justification in `notes`. -- **Free-form criteria embedded in a milestone**: - same fall-back. Lean strict. - -# Decisions in scope - -- Per-criterion status with evidence -- Severity classification of each finding -- `completion_score` and `quality_score` with justification - -# Decisions out of scope - -- What to do next - caller (Planner or SDLC) -- Modifying the artifact -- Modifying the validator -- Escalating to human - caller - -# Skills you may invoke - -- `aidd-dev:05-review` -- `aidd-dev:04-audit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the caller. - -# Guardrails - -- Never edit the artifact under review. -- Never modify the validator. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. -- If a criterion is ambiguous, flag in `notes`. Don't guess. -- Don't be lenient because the work "looks impressive". Score what's verifiable. -- Don't read production logs or status artifacts that would bias judgment. diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md index ee150af0..f588e49f 100644 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -11,8 +11,8 @@ Holds no business logic of its own; every step is delegated. - 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 autonomous run (`auto` mode) with no human prompts. -- You want the same flow but with confirmation gates (`interactive` mode). +- 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 @@ -29,33 +29,34 @@ Holds no business logic of its own; every step is delegated. ## How to invoke ``` -/sdlc # auto mode (default) -/sdlc interactive # pauses at each gate for human confirmation +/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 via the `planner` agent. -3. `implement` - loop milestones via the `implementer` agent until complete. -4. `review` - verdict `ship` or `iterate` via the `reviewer` agent; on +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/plans/`. -- Atomic commits on the active branch, one per ticked checkbox. +- 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 reviewer. +- 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 `planner`, `implementer`, and `reviewer` agents are available. +- The `executor` and `checker` agents are available. - A VCS-providing capability is loaded at runtime for the ship step (commit + pull-request creation). diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index c6c4162a..e7265a02 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,99 +1,30 @@ --- name: 00-sdlc -description: Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated. +description: 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. +argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc -Complete end-to-end software delivery. Defaults to autonomous; switches to interactive on demand. - -## Iron rule - -**You are the conductor, not a player.** - -You orchestrate skills and agents; you never write code yourself. - -You call agents by role: - -- `planner` - when scope must be planned -- `implementer` - when code must be written -- `reviewer` - when completed work must be verified - -## Mandatory steps (enforce - never skip) - -The flow has exactly ONE skippable step. Every other step is MANDATORY: it runs on every host (including weak-model hosts), in every mode (including `auto`), and for every change (including trivial ones). - -- `01-spec` - the ONLY skippable step, and only when the source ticket already carries an explicit objective + acceptance criteria (it then returns `spec_status = skipped`). -- `02-plan`, `03-implement`, `04-review`, `05-ship` - MANDATORY. Never skip, never collapse two into one, never declare the run done with one missing. Skipping any of them is a FAILED run, not a shortcut. - -Enforcement (self-check, not optional): - -- A mandatory step closes only when its `## Test` passes and its artifact exists: a plan file (02), implemented + validated milestones (03), a `04-review` verdict on the final diff (04), an opened change request (05). -- **`04-review` is non-negotiable: code is never shipped unreviewed.** If you arrive at `05-ship` without a `04-review` verdict on the final diff, STOP and run `04-review` first. -- Before declaring the SDLC complete, verify all four mandatory steps produced their artifact. If any is missing, the run is NOT done - resume at the missing step. Do not report success with a skipped step. - -## Modes - -| Mode | Trigger | Behavior | -| ------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `auto` | default; `/sdlc `; orchestrator invocation | Never asks the human. All decisions yours. | -| `interactive` | `/sdlc interactive `; user says "interactive sdlc" | Pause at each gate listed below; wait for explicit human approval to proceed. | - -Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the first action. +Take a request from idea to shipped code, delegating every step. Interactive by default, autonomous when you say `auto`. ## Actions -| # | Action | Role | Delegate | -| --- | ----------- | ---------------------------------------------------------------------- | ------------------------------ | -| 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | spec | -| 02 | `plan` | Produce the mandatory plan file | plan via `planner` | -| 03 | `implement` | Loop milestones until complete | implement via `implementer` | -| 04 | `review` | Verdict `ship` or `iterate` | review via `reviewer` | -| 05 | `ship` | Commit and open a change request via the project's VCS | commit, pull-request | - -Files: `@actions/01-spec.md` ... `@actions/05-ship.md`. - -## Default flow - -`01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop back to `03` with the findings as the implementer's fix list. After each action, run its `## Test` before moving to the next. - -`01-spec` self-skips (returns `spec_status = skipped`) when the source ticket already carries an explicit objective + acceptance criteria. It is the ONLY skippable step. `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and never skipped (see **Mandatory steps**). - -## Interactive gates - -Activate only in `interactive` mode. In `auto` mode, never pause. - -1. **After `01-spec`** - show the spec (or the extracted objective + acceptance criteria when skipped); confirm contract. -2. **After `02-plan`** - show the plan; confirm scope before any code change. -3. **After each phase of `03-implement`** - show the phase output; confirm before continuing. -4. **After `04-review`** - show findings and verdict; confirm ship vs iterate. -5. **Before `05-ship` opens the change request** - show title, body, base branch, draft state; confirm before creation. - -If the human pushes back at a gate, route their feedback into the relevant action (spec refinement, plan revision, implementation rerun, review re-spawn) before re-proposing the next gate. - -## Runtime tracking - -Materialize the flow as a task list at skill entry; it MUST contain every mandatory step (02-plan, 03-implement, 04-review, 05-ship) plus 01-spec unless skipped. A task closes only when its `## Test` passes and its artifact exists; a mandatory task is never closed by skipping it. - -## Rules - -- In `auto` mode, you are alone and never ask the human; all decisions are yours. -- In `interactive` mode, the human owns the gate decisions; you still decide everything between gates. -- Always run `02-plan`. Minimum: frontmatter + M/C/D + rules table + phases. Never inline ticket or spec as plan. -- Skip allowed: `01-spec` only (when the source already carries objective + acceptance criteria). `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and enforced (see **Mandatory steps**); skipping any is a failed run. -- Choose the best decision based on the facts. -- Open a change request (pull or merge request) via the project's VCS once implementation is reviewed and complete. -- **Branch discipline (caller responsibility).** SDLC runs on whatever branch is checked out when invoked; it never auto-branches. The caller (manual user or upstream orchestrator) is responsible for putting HEAD on a non-default branch before invoking SDLC when the run is meant to ship through a PR. - -## References +| # | Action | Role | Delegate | +| --- | ----------- | ------------------------------------- | --------------------------------------- | +| 01 | `spec` | Consolidate sources into the contract | a spec capability | +| 02 | `plan` | Produce the plan file | self, via `aidd-dev:01-plan` | +| 03 | `implement` | Build the plan's code | `executor`, via `aidd-dev:02-implement` | +| 04 | `review` | Verdict `ship` or `iterate` | `checker`, via `aidd-dev:05-review` | +| 05 | `ship` | Open the change request | a commit and change-request capability | -- `spec` -- `plan` -- `implement` -- `review` -- `commit` -- `pull-request` +Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-run `04`. -## Assets +## Transversal rules -- None. +- Delegate every step; never write or judge code yourself. +- Mode: default `interactive`, pausing for approval at each step; switch to `auto` only when the caller says so, then decide alone and never ask. +- Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. +- Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. +- Every artifact (spec, plan, phases, review) lands in one feature folder, `aidd_docs/tasks//_/`, resolved at entry. +- Never auto-branch; the caller sets a non-default branch before shipping. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md index bf458b02..0abcbcf4 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md @@ -2,30 +2,24 @@ Consolidate every available source into the normalized contract consumed downstream. -**Skip condition:** if the source ticket already carries an explicit objective + at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, jump to action 02. +**Skip condition:** when the source ticket already carries an explicit objective and at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, and jump to `02`. -## Inputs +## Input -- `request` - raw `$ARGUMENTS` (free-form text or ticket URL) -- `sources` - one or more of: ticket body, existing PRD, in-session conversation, prior reviewer findings -- `working_dir` - repo root +The raw arguments (free-form text or a ticket URL), any available sources (ticket body, existing PRD, in-session conversation, prior checker findings), and the repo root. -## Outputs +## Output -```yaml -spec_path: -spec_status: drafted | refined | skipped -objective: -acceptance_criteria: [] -``` +The spec path on disk with its status (`drafted`, `refined`, or `skipped`), the one-sentence objective, and the acceptance criteria. The path is null when skipped. ## Process -1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot reviewer findings, capture conversation turns. Concatenate into a single brief. -2. **Skip check.** Apply the skip condition above. If skipped, return. -3. **Delegate.** Hand the consolidated brief and `working_dir` to `spec`; let it own contract generation and refinement. -4. **Return** `spec_path`, `spec_status`, `objective`, `acceptance_criteria` to the SDLC orchestrator. +1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot checker findings, capture conversation turns. Concatenate them into one brief. +2. **Skip.** Apply the skip condition above. If it holds, return the extracted objective and criteria. +3. **Delegate.** Hand the consolidated brief and the repo root to a spec capability, discovered at runtime by description. Let it own contract generation and refinement. +4. **Return.** Surface the spec path, status, objective, and acceptance criteria. ## Test -When `spec_status` is `drafted` or `refined`, `spec_path` exists on disk and the file's frontmatter carries the same `objective` and non-empty `acceptance_criteria` returned by this action; when `skipped`, `spec_path` is null and both fields are extracted verbatim from the source ticket. +- When the status is `drafted` or `refined`, the spec file exists and its frontmatter carries the same objective and non-empty acceptance criteria this action returns. +- When `skipped`, the path is null and both fields are taken verbatim from the source ticket. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md index 18cd89ed..4e170e54 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md @@ -1,29 +1,21 @@ # 02 - Plan -Turn the spec (or raw request when spec was skipped) into a validated plan file. Mandatory. +Turn the spec, or the raw request when spec was skipped, into a validated plan file. Mandatory. -## Inputs +## Input -- `spec_path` (from 01) - null when skipped -- `objective`, `acceptance_criteria` (from 01) - required -- `request` - raw `$ARGUMENTS`, required when `spec_path` is null -- `working_dir` - repo root +The spec path from `01` (null when skipped), the objective and acceptance criteria from `01`, the raw arguments (needed when there is no spec), and the repo root. -## Outputs +## Output -```yaml -plan_path: -child_paths: [] -decisions_made: [...] -decisions_blocked: [...] -``` +The plan path and its phase paths, plus the decisions you made and any you could not make alone. ## Process -1. **Spawn planner** (`planner` agent) with the inputs above. Brief: run `plan` end to end (URL detection, ticket fetch, normalization, architecture projection, rules selection, phase breakdown). Never inline raw ticket or spec as the plan body. -2. **Read output.** Capture the YAML returned by the planner. -3. **Return** it as-is to the SDLC orchestrator. +1. **Author.** Run `aidd-dev:01-plan` end to end in your own context. You own the plan: it is the contract the executor may not rewrite, so you write it, never a worker. Never inline a raw ticket or spec as the plan body. +2. **Capture.** Read the plan path, the phase paths, and the decisions the plan records. +3. **Return.** Surface them for the next step. ## Test -`plan_path` exists on disk; its frontmatter contains `objective`, `status: pending`; the plan's `objective` matches the spec's `objective` (or the request when spec was skipped). +- The plan file exists, its frontmatter carries `objective` and `status: pending`, and the plan's objective matches the spec's (or the request when spec was skipped). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 8e04a447..bb37df2b 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,31 +1,25 @@ # 03 - Implement -Build a milestone, apply a fix list, or finish a remaining scope via the implementer agent. Mandatory. +Build the plan's code by spawning the `executor` agent to run the `aidd-dev:02-implement` recipe, which loops the phases, drives status, and validates. Mandatory. -## Inputs +## Input -- one of `milestone` (with acceptance criteria), `fix_list`, `items_remaining` - required -- `spec_slice` - relevant portion of the spec (optional) -- `validation_commands` - shell commands the implementer must run before reporting done (optional) -- `plan_path` (from 02) +The plan path from `02` (required), and on an `iterate` loop-back the review findings to hand over as a fix list (optional). -## Outputs +## Output -```yaml -items_implemented: [...] -items_remaining: [...] -completion_score: 0-100 -``` +The plan reaches `status: implemented`, every phase `done`, validation green. Or it stops at `status: blocked` when a human is needed. ## Process -1. **Mark in-progress.** Set `status: in-progress` in the plan frontmatter at `plan_path` (skip if already set). Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -2. **Spawn implementer** (`implementer` agent) with the inputs above. Brief: run `implement` for the milestone or fix list, then `assert` + `test`. -3. **On failure**, run `debug` and re-spawn the implementer with the diagnostic notes until tests pass. -4. **Blocked.** If the implementer surfaces `BLOCKED` in `notes`, write `status: blocked` in the plan frontmatter at `plan_path`, stop (do NOT proceed to 04), and escalate to a human. -5. **Mark implemented.** When the whole plan is implemented (no milestones remain, last pass `items_remaining` empty), set `status: implemented` in the plan frontmatter at `plan_path`. -6. **Return** the implementer's YAML as-is to the SDLC orchestrator. +1. **Implement.** Spawn the `executor` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions, and validates. +2. **Iterate.** After an `iterate` verdict, spawn `executor` again with the findings as a fix list. It codes them against the current diff, then asserts and validates, gating like a phase: done only when it passes. Never edit the plan; the loop fixes the diff, not the plan. +3. **Resolve.** Read the plan's final `status`. + - `implemented`: the step is done. + - `blocked`: a human-only condition stopped the run. Do not continue. Escalate to a human. ## Test -`completion_score` is an integer between 0 and 100; `items_implemented` and `items_remaining` are present; the validation commands return exit code 0; when fully implemented the plan's frontmatter `status` is `implemented` (or `blocked` if it surfaced a blocker, stopping before 04). +- The plan `status` is `implemented`, or `blocked` when a human-only condition stopped it. +- Every phase reads `status: done`. +- The validation commands return exit code 0. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 91ce3f92..d85e1f71 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -2,29 +2,25 @@ Judge the completed work against an explicit validator and emit a ship-or-iterate verdict. -## Inputs +## Input -- `artifact` - working diff or paths produced by 03 (required) -- `validator` - `plan_path` + `acceptance_criteria` from upstream (required) -- `context` - related artifacts the reviewer needs to inspect (optional) +The working diff or paths produced by `03`, the validator (the plan path and acceptance criteria), and any related context the checker needs. -## Outputs +## Output -```yaml -verdict: ship | iterate -items_reviewed: [...] -findings: [...] -completion_score: 0-100 -quality_score: 0-100 -``` +A `ship` or `iterate` verdict with the reviewed items, the findings, the completion and quality scores, and the reviewed `HEAD` SHA (the commit the checker actually saw). The plan reaches `status: reviewed` on ship, and stays `implemented` on iterate. ## Process -1. **Spawn reviewer** (`reviewer` agent) with the inputs above. Brief: run `review` (code + functional) and return the YAML. -2. **Map verdict.** All checks pass → `verdict = ship`. Any blocking finding → `verdict = iterate`. -3. **Write status.** `ship` → set `status: reviewed` in the plan frontmatter at `plan_path`. `iterate` → set `status: in-progress` before looping back. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -4. **Iterate loop.** When `verdict = iterate`, return the findings as the next `fix_list` for action 03. +1. **Capture.** Record the current `HEAD` sha as the reviewed SHA. This is the exact code the checker judges, and the anchor `05-ship` checks against. +2. **Spawn.** Spawn the `checker` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code, functional, and relevancy, on that diff, and return its verdict. +3. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. +4. **Mark.** On `ship`, set the plan frontmatter `status: reviewed` and commit it. Carry the reviewed SHA in the verdict. On `iterate`, leave the plan `implemented`: the loop fixes the diff, not the plan. +5. **Iterate.** On `iterate`, return the findings as the fix list for `03`. The next `04` re-captures the SHA on the fixed diff; ship is reached only when a review of the current diff passes. ## Test -`verdict` is `ship` or `iterate`; `completion_score` and `quality_score` are integers between 0 and 100; `findings` is non-empty when `verdict = iterate`; the plan's frontmatter `status` is `reviewed` on `ship`, `in-progress` on `iterate`. +- The verdict is `ship` or `iterate`, and the scores are integers between 0 and 100. +- The verdict carries the reviewed `HEAD` SHA. +- The findings are non-empty on `iterate`. +- The plan frontmatter reads `status: reviewed` only after a `ship` verdict on the current diff. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index beccb625..27727fc4 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -2,26 +2,26 @@ Commit and open a change request (pull or merge request) via the project's VCS once the review verdict is `ship`. -## Inputs +## Input -- `verdict = ship` (from 04) - required -- `plan_path` (from 02) - required -- `phase_results` (from 03) - optional, drives the commit and change-request body +The `ship` verdict from `04` including its reviewed `HEAD` SHA, the plan path from `02`, and the phase results from `03` that drive the commit and the change-request body. -## Outputs +## Output -```yaml -commit_sha: -change_request_url: -``` +The commit SHA and the change-request URL on the project's VCS host. ## Process -0. **Review gate (mandatory, run first).** Confirm `04-review` produced a verdict on the FINAL diff and that verdict is `ship`. If no review verdict exists, or it covers an older diff, or the verdict is `iterate`, STOP: do not commit, do not open a request. Run `04-review` first (loop back to `03-implement` on `iterate`). Code is never shipped unreviewed. -1. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's `objective`. -2. **Push and open.** Invoke `pull-request` to push the branch and open the change request. Reference `plan_path` in the body. -3. **Return** `commit_sha` and `change_request_url` to the SDLC orchestrator. +1. **Gate.** Confirm `04` returned a `ship` verdict and HEAD is on a non-default branch. Without a `ship` verdict, or on `iterate`, stop and re-run `04` (looping to `03` on `iterate`). On the default branch, stop with `contract_violation: on_default_branch` and commit nothing. +2. **Freshness.** Confirm no code landed after the reviewed SHA: `git diff --name-only HEAD` must list only plan-tracking files. Any source change means the review is stale, so stop and re-run `04`. Never ship unreviewed code. +3. **Commit.** Invoke a commit capability, discovered at runtime, with the plan's objective. It picks the message format; never dictate one here. +4. **Open.** Invoke a change-request capability, discovered at runtime, to push the branch and open the request. Reference the plan path in the body. +5. **Return.** Surface the commit SHA and the change-request URL. ## Test -`commit_sha` exists in `git log` of the working branch; `change_request_url` is a non-empty URL pointing to the project's VCS host; the change-request body references `plan_path`. +- `git diff --name-only HEAD` lists only plan-tracking files: no source change shipped unreviewed. +- The commit SHA exists in `git log` of the working branch. +- The change-request URL is non-empty and points to the project's VCS host. +- The change-request body references the plan path. +- On the default branch, the action stops with `contract_violation: on_default_branch` and makes no commit. diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md index 9962491a..1bf79fb6 100644 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -2,27 +2,18 @@ # 01 - plan -Generates technical implementation plans, defines component behaviors as -state machines, and extracts structured component inventories from design -images. The plan file is the single source of truth that downstream skills -(`02-implement`, `05-review`) consume. +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 validated spec or ticket exists and you need a phased plan with - milestones, rules, and acceptance criteria before any code change. -- A frontend component needs its behavior pinned down as a state machine - before implementation. -- A design image (Figma export, mockup, screenshot) needs to be turned into - a hierarchical component inventory. +- 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. +- 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 @@ -30,27 +21,25 @@ images. The plan file is the single source of truth that downstream skills Use skill aidd-dev:01-plan ``` -The skill exposes 3 actions: +The skill runs four actions in order, the plan being the culmination: -1. `plan` - produce a phased implementation plan from a spec or ticket. -2. `components-behavior` - define a component's behavior as a state machine. -3. `image-extract-details` - analyze a design image and emit a hierarchical - component inventory. +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. -## Outputs +A feature folder `aidd_docs/tasks//_/`: -- A plan file in `aidd_docs/plans/` with frontmatter, M/C/D (must / could / - done), rules table, and ordered phases. -- A state-machine description (Mermaid) for the target component. -- A structured component inventory derived from the image source. +- `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 validated spec, ticket, or design source as input. -- Access to the plan template asset bundled with this skill. +- 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 list and -[`assets/plan-template.md`](assets/plan-template.md) for the canonical plan -format. Per-action contracts live in [`actions/`](actions/). +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/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index 9fd3e2d9..53b45f9c 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,43 +1,30 @@ --- name: 01-plan -description: Generate technical implementation plans, define component behaviors, and extract design details from images. -model: opus -context: fork -agent: planner +description: 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. +argument-hint: gather | explore | wireframe | plan --- # Skill: plan -Produces implementation plans from requirements, state machines for component behavior, and structured component inventories from design images. +Turn a gathered source into an implementation plan and its phase files. Never writes code. -## Agent delegation - -Spawn the `planner` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `planner` agent explicitly with this skill's content as the prompt. - -## Available actions - -| # | Action | When to use | -| --- | ------------------------ | --------------------------------------------------------------------------- | -| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | -| 02 | `components-behavior` | Define a frontend component's behavior as a state machine (Mermaid) | -| 03 | `image-extract-details` | Analyze a design image into a hierarchical component inventory | - -## Routing (run first) - -The planner auto-adapts to the INPUT - do not ask the user to choose. Detect the input type and route; do NOT always fall to action 01. +## Actions -- A design image or mockup is provided -> `03-image-extract-details` (then feed the inventory into planning). -- The request is about a frontend component's behavior, states, or transitions -> `02-components-behavior`. -- Anything else (requirements, a feature to build) -> `01-plan`. +| # | Action | Role | Input | +| --- | ----------- | ---------------------------------------------------- | -------------------------- | +| 01 | `gather` | Collect and restate the source | user request | +| 02 | `explore` | Read the codebase for projection, rules, feasibility | gathered source | +| 03 | `wireframe` | Sketch a screen at low fidelity, frontend only | source + explore context | +| 04 | `plan` | Break into phases, write the plan and phase files | explore output + wireframe | -Actions may chain (e.g. extract from image, then plan). Read and follow each selected action file. +Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI. -## Actions +## References -- `@actions/01-plan.md` -- `@actions/02-components-behavior.md` -- `@actions/03-image-extract-details.md` +- `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs. +- `references/plan-status.md`: the plan lifecycle `status` values and who writes each. -## References +## Assets -- `@references/plan-status.md` - plan lifecycle `status` values, meaning, and who writes each. All actions inherit it; do not re-specify the table elsewhere. +- `assets/plan-template.md`: the `plan.md` scaffold. +- `assets/phase-template.md`: the per-phase scaffold. diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md new file mode 100644 index 00000000..22d9571c --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md @@ -0,0 +1,21 @@ +# 01 - Gather + +Collect the source the plan will rest on, before any planning. Read only. + +## Input + +The user's request, which may be empty. + +## Output + +The source restated in a few bullets: what is asked and the hard constraints it states. The source kind and reference (file path, ticket id, or text) are named. + +## Process + +1. **Find.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. +2. **Pull.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. +3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan. + +## Test + +- The output names the source kind and reference and restates it in bullets, states no solution, and when nothing concrete was given the user was asked before anything else. diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md deleted file mode 100644 index 15863fcf..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md +++ /dev/null @@ -1,72 +0,0 @@ -# 01 - Plan - -Generate a technical implementation plan from requirements, save it to a task file, display it for review, and wait for explicit user confirmation. Never code anything. - -## Inputs - -```yaml -requirements: -ticket_number: # optional; inferred when the input is a ticket URL -``` - -## Outputs - -```yaml -plan_path: aidd_docs/tasks//-?<#ticket_number>-(-master|-part-N)?.md -plan_kind: simple | master -confidence: 0-10 -architecture_projection: - modify: [] - create: [] - delete: [] -applicable_rules: [{ tool: , name: , path: , why: }] -``` - -## Process - -1. **Parse the input.** Detect ticket URL vs raw text. For URLs, fetch and parse ticket content. For raw text, clean and structure. Normalize text (handle vocal dictation issues). Print the user journey as a simplified ASCII diagram for validation. -2. **Score risk and impact.** Compute the score and pick the plan kind: - - Score < 3 -> simple plan (`@../assets/plan-template.md`) - - Score >= 3 -> master plan (`@../assets/master-plan-template.md` + child plans) - - | Criterion | Points | - | ------------------------------- | ------ | - | Breaking changes to public APIs | +3 | - | Database / schema migrations | +3 | - | 3+ modules affected | +2 | - | 5+ modules affected | +3 | - | Major refactoring | +2 | - | External dependency upgrades | +2 | - - Each part of the plan must be doable without the next ones (independent phases for compatibility). -3. **Validate technical assumptions** by spawning a sub-agent task to: - - Explore the codebase to inform plan generation. - - List implicit assumptions about the user's infrastructure. - - Verify API feasibility before committing to an approach. - - Flag blockers and risks that will arise if not addressed. - - Check assumptions against official documentation. - - Produce the architecture projection (three lists, each `path - one-line reason`): files to modify, files to create, files to delete. - - Inventory project rules from the user's project root; accept a silent empty array when no surface contains rules. -4. **Architecture projection and rules - user validation (gate).** - - From the rules inventory, select rules that apply to the projection using each rule's `description` and `paths` when present. Justify every selected rule in one line. - - Display: the three modify / create / delete lists; the table of applicable rules `tool | name | path | why it applies`. - - Ask: "Is this projection correct? Anything to add or remove? A missing rule?" - - WAIT FOR USER APPROVAL. Iterate until approved. -5. **Task planning.** Define main phases at the macro level; do not mention specific files. Wait for user validation on the phases before moving on. For each phase, list minimal, specific, actionable tasks. -6. **Generate and save the plan.** - - Use the current `!`date`!` for the date stamp. - - Determine the feature name from the requirements. - - Insert the user journey as Mermaid syntax in the plan (apply `@../references/mermaid-conventions.md`). - - Fill the chosen template, including the validated architecture projection and applicable rules. - - Fill execution frontmatter (required): `objective`, `status: pending`. - - Save to disk: - - Simple plan: `aidd_docs/tasks//-?<#ticket_number>-.md` - - Master plan: `aidd_docs/tasks//-?<#ticket_number>--master.md` - - Child plans: `aidd_docs/tasks//-?<#ticket_number>--part-N.md` - - Display the saved file path. -7. **Quality assurance.** Verify the plan addresses every requirement; flag potential challenges; evaluate confidence (0-10) with ✓ reasons and ✗ risks; require minimum 9/10 before display; add the assessment to the plan. -8. **Display and confirm.** Show the plan, the confidence assessment, and any risks. Challenge the plan with the user. WAIT FOR USER APPROVAL. - -## Test - -The plan file exists at `plan_path`; its frontmatter contains `objective` and `status: pending`; the architecture projection (M / C / D) is non-empty and matches the validated lists; the applicable rules table is consistent with the project's rules inventory; confidence is `>= 9`. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md b/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md deleted file mode 100644 index 2f4efbc5..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md +++ /dev/null @@ -1,35 +0,0 @@ -# 02 - Components behavior - -Define the expected behavior of one or more frontend components as state machines, rendered in Mermaid syntax for user validation. - -## Inputs - -```yaml -components: -``` - -## Outputs - -```yaml -state_machines: - - component: - diagram: - states: [] - transitions: [{ from: , to: , event: , condition: }] -``` - -## Process - -Iterate over the steps below until each component is fully defined. - -1. **Parse the request.** Extract the list of components from `$ARGUMENTS`. -2. **Per component**: - - Identify the key states the component can be in. - - Determine the events or actions that trigger transitions between states. - - Define the state machine in Mermaid syntax, applying `@../references/mermaid-conventions.md`. -3. **Sanity-check the model.** Confirm the state machine captures every state and every transition relevant to the component's behavior. -4. **Present the final state machines** to the user for validation. Wait for an explicit OK before exiting. - -## Test - -For each component in `components`: the corresponding `state_machines` entry has a Mermaid block that parses, lists at least two states, and every transition references states that exist in the same diagram. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md new file mode 100644 index 00000000..33a6916d --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md @@ -0,0 +1,23 @@ +# 02 - Explore + +Read the codebase to ground the plan: what it touches, which rules apply, what is feasible. Read only. + +## Input + +The gathered source from `01-gather`. + +## Output + +The architecture projection (files to modify, create, delete, each with a one-line reason), the project rules that apply (each justified in one line, or none), the feasibility checks (each source consulted, a doc URL or an in-repo file, and what it settled), and the risks. + +## Process + +1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. +2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. +3. **Select.** Keep the project rules that apply to the projection. + +## Test + +- The projection lists files to modify, create, and delete, each with a one-line reason. +- Every feasibility check records its source and what it settled. +- The applicable rules are identified and justified, or none apply. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md b/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md deleted file mode 100644 index 8e985445..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md +++ /dev/null @@ -1,79 +0,0 @@ -# 03 - Image extract details - -Analyze an image to identify and extract the main components, group them by type, merge close variants, and emit a hierarchical inventory ready for planning. - -## Inputs - -```yaml -image: -``` - -## Outputs - -```yaml -main_reusable_components_with_variants: - - name: - variants: - - name: - style: -main_display_components: - - component_name:
- layouts: - - type: - style: - position_and_display: - components: [] -``` - -## Process - -1. **Identify reusable components.** Scan the image for repeatable UI atoms; group them by type. -2. **Extract variants.** For each reusable atom, collect distinct visual variants. Merge variants that are very close (same role, marginal styling differences). -3. **Remove duplicates.** Keep each unique component once. -4. **Hierarchical organization.** Place layout-level display components above the reusable atoms; nest layouts and their sub-components. -5. **Boundaries.** Emoji are not components. Do not detail photography. - -## Test - -`main_reusable_components_with_variants` lists each unique reusable atom exactly once with at least one variant; `main_display_components` covers every top-level section visible in the image; no entry references emoji or stock photography. - -## Output format example - -```yaml -main_reusable_components_with_variants: - - name: "Chip" - variants: - - name: "Generate" - style: "Purple text, rounded pill shape, small sparkle icon" - -main_display_components: - - component_name: Hero Section - layouts: - - type: Vertical Stack - style: "Centered alignment, full-width layout" - position_and_display: "Top of page" - components: - - type: Text Block - content: "For individuals, independent creators and tech companies" - variant: "Heading" - - type: Text Block - content: "Empowering individuals, creators, and tech innovators with cutting-edge AI solutions." - variant: "Subheading" - - - component_name: Feature Grid - layouts: - - type: Two-Column Layout - style: "Even 2-column grid, responsive layout" - position_and_display: "Below hero section" - components: - - component_name: Right Feature Card - position_and_display: "Right column" - layout: "Vertical stack" - sub_components: - - type: Text Block - content: "Don't write by yourself, it's boring. Instead, let AI" - variant: "Paragraph" - - type: Chip - content: "Enhance" - variant: "Enhance" -``` diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md new file mode 100644 index 00000000..53d8b3a5 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -0,0 +1,20 @@ +# 03 - Wireframe + +Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI. + +## Input + +The screens to sketch, from the gathered source and the `02-explore` context (the existing screens and components). + +## Output + +A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy. + +## Process + +1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI. +2. **Draw.** Sketch each screen per `@../references/wireframe-conventions.md`. The wireframe feeds the plan. + +## Test + +- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carrying no behavior, styling, or final copy. diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md new file mode 100644 index 00000000..b3b7aa6f --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -0,0 +1,26 @@ +# 04 - Plan + +Turn the explored source into a plan and its phases, save them, then review the whole until approved. Never code. + +## Input + +The explore output from `02-explore` (projection, rules, feasibility, risks), plus any confirmed wireframe from `03-wireframe`. + +## Output + +A feature folder, always at `aidd_docs/tasks//_/`, holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. + +## Process + +1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many. +2. **Folder.** Reuse the feature folder the source already lives in, or create one. +3. **Fill.** Scaffold from the templates and fill only the sections they define, omitting any that stays empty (resources when nothing was consulted). Slice the projection across the phases, list the consulted resources in the resources table, and embed any wireframe in its phase's Wireframe section. +4. **Show.** Display the written paths. +5. **Review.** Show the complete plan and its phases with a confidence score (0 to 10, ✓ reasons and ✗ risks). Take feedback, revise the files, and re-show until approved. The score is never written to the plan. + +## Test + +- `aidd_docs/tasks//_/plan.md` exists with one `phase-.md` per phase next to it. +- No `{...}` placeholder is left in any written file. +- The phase projection slices together cover the modify, create, and delete lists. +- A confidence score was reported and written to no file. diff --git a/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md deleted file mode 100644 index eaee3ebe..00000000 --- a/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: master_plan -description: Parent plan template orchestrating multiple child plans with validation gates -argument-hint: N/A ---- - - - -# Master Plan: {title} - -## Overview - -- **Goal**: {one-line summary} -- **Risk Score**: {X}/10 -- **Branch**: `{branch-prefix}/` - -## Child Plans - -| # | Plan | File | Status | Validated | -| --- | ----------- | --------------- | ------- | --------- | -| 1 | {plan-name} | `./*-part-1.md` | pending | [ ] | -| 2 | {plan-name} | `./*-part-2.md` | pending | [ ] | - - - - -## Validation Protocol - -1. Complete Plan 1, run its validations -2. [ ] Checkpoint 1: User confirms -3. Unblock Plan 2, repeat -4. [ ] Final: Integration test - -## Estimations - -- **Confidence**: {X}/10 -- **Duration**: {estimate} diff --git a/plugins/aidd-dev/skills/01-plan/assets/phase-template.md b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md new file mode 100644 index 00000000..7d631c1b --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md @@ -0,0 +1,43 @@ +--- +status: pending +--- + +# Instruction: {title} + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +. +``` + +## User Journey + +```mermaid +flowchart TD + A[TODO] +``` + +## Wireframe + +```txt +{the confirmed wireframe, or omit this section when the phase has no UI} +``` + +## Tasks to do + +### `{number})` {name} + +> {straight to point goal} + +1. {ultra concise step} + ... + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------------------------ | +| 1... | {focused deterministic verification} | diff --git a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md index a883d334..b1080cb1 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md @@ -1,106 +1,32 @@ --- -name: plan -description: Living implementation plan - frozen objective, phases, and acceptance criteria. -argument-hint: N/A objective: "{What must be true when done. One sentence.}" status: pending --- - +## Overview -# Instruction: {title} +| Field | Value | +| ---------- | ----------------------- | +| **Goal** | {one-line summary} | +| **Source** | {file, ticket, or text} | -## Feature +## Phases -- **Summary**: {Summarize feature based plan, goal oriented} -- **Stack**: `[TECH_STACK_WITH_VERSIONS]` -- **Branch name**: `{suggested-branch-name}` -- **Parent Plan**: `{master-file}` or `none` -- **Sequence**: `{N of M}` or `standalone` -- Confidence: {Confidence} -- Time to implement: {Time to implement} +| # | Phase | File | +| --- | ------------ | ---------------------------- | +| 1 | {phase-name} | [`phase-1.md`](./phase-1.md) | +| 2 | {phase-name} | [`phase-2.md`](./phase-2.md) | -## Architecture projection +## Resources - +| Source | Verified | +| ------------- | --------------------------- | +| {url or path} | {what it settled, one line} | -### Files to modify +## Decisions -- `path/to/file.ts` - {one-line reason} - -### Files to create - -- `path/to/new-file.ts` - {one-line purpose} - -### Files to delete - -- `path/to/dead.ts` - {one-line reason} - -## Applicable rules - - - -| Tool | Name | Path | Why it applies | -| ------ | ------ | ------------------------------------- | -------------- | -| {tool} | {slug} | `//.` | {short reason} | - -## User Journey - -```mermaid -flowchart TD - A[TODO] -``` - -## Risk register - - - -| Risk | Impact | Mitigation | -| -------- | ----------------------------- | ------------------------------------- | -| {risk 1} | {what breaks if this happens} | {how the plan prevents or handles it} | - -## Implementation phases - -### Phase {n}: {name} - -> {straight to point goal} - -#### Tasks - -1. {ultra concise task1, with logical ordering} -2. {...} -3. {...} - -#### Acceptance criteria - -- [ ] {verifiable boolean condition 1} -- [ ] {verifiable boolean condition 2} - -## Amendments - - - -## Log - - - - - - - -## Validation flow demonstration - - - -1. {Step 1...} +| Decision | Why | +| ---------- | -------------- | +| {decision} | {one-line why} | diff --git a/plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md b/plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md deleted file mode 100644 index d9df39b7..00000000 --- a/plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: tech-choice -description: Technology selection and comparison template -argument-hint: N/A ---- - -# RESEARCH & RECOMMENDATIONS - -[Summary of the user needs and goals] - -## Technology Analysis: [SPECIFIC TECHNOLOGY CATEGORY] - -### Executive Summary - -One paragraph explaining top recommendation and why. - -### Comparison Matrix - -| Solution | Score /10 | Cost | Performance | Integration Effort | Maintenance | Scalability | Key Strength | Key Weakness | -| -------- | --------- | ------- | ----------- | ------------------ | ------------ | ----------- | ------------ | ------------ | -| Option 1 | X.X | €/month | Metric | Easy/Medium/Hard | Low/Med/High | Rating | Feature | Limitation | -| Option 2 | X.X | €/month | Metric | Easy/Medium/Hard | Low/Med/High | Rating | Feature | Limitation | -| Option 3 | X.X | €/month | Metric | Easy/Medium/Hard | Low/Med/High | Rating | Feature | Limitation | - -## Detailed Evaluation - -### 🏆 Recommended: [Technology Name] - -**Why this choice:** - -- Key reason 1 -- Key reason 2 -- Key reason 3 - -**Implementation considerations:** - -- Migration path: Brief strategy -- Time estimate: X weeks/months -- Risk factors: Main risks - -### Alternative Options - -**[Option 2 Name]** - -- Best for: (Specific use case) -- Choose if: (Specific conditions) -- Avoid if: (Specific conditions) - -**[Option 3 Name]** - -- Best for: (Specific use case) -- Choose if: (Specific conditions) -- Avoid if: (Specific conditions) - -## Cost Analysis - -| Solution | Monthly | Annual | Hidden Costs | 2-Year TCO | -| ------------ | ------- | ------ | ------------ | ---------- | -| Current | €X | €X | (List) | €X | -| Recommended | €X | €X | (List) | €X | -| Savings/Cost | €X | €X | - | €X | diff --git a/plugins/aidd-dev/skills/01-plan/references/mermaid-conventions.md b/plugins/aidd-dev/skills/01-plan/references/mermaid-conventions.md deleted file mode 100644 index daa6a274..00000000 --- a/plugins/aidd-dev/skills/01-plan/references/mermaid-conventions.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -description: Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt). -globs: ["**/*.mmd", "**/*.md"] -alwaysApply: false ---- - -# Mermaid generation rules - -## Header - -- Always have title in schema using "---" to define it - -## Global - -- NEVER use "\n" - -## States and nodes - -- Define groups, parents, children -- Use fork and join states -- Use clear and concise names -- Use "choice" for conditions -- No standalone nodes -- No empty nodes - -## Naming - -- Declare elements only (no links) at top -- Consistent naming throughout -- Descriptive names (no "A", "B") -- Node IDs: unquoted alphanumeric (`MyNode`, not `"MyNode"`) -- Labels: in brackets with quotes (`MyNode["My Label"]`) -- Replace ":" with "$" in state names - -## Links - -- Links made at bottom of diagram -- Use direction when possible -- "A -- text --> B" for regular links -- "A -.-> B" for conditional links -- "A ==> B" for self-loops - -## Styles - -- Do style unless specified by user - -## Gantt - -- Use tags: `active`, `done`, `crit`, `milestone` -- Tags are combinable diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md index 7d537560..51e98bf1 100644 --- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md +++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md @@ -9,15 +9,15 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The | status | meaning | written by | when | | ------------- | ----------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | -| `pending` | created, not started | `01-plan` | at plan creation | -| `in-progress` | implementation started | implement layer (SDLC `03-implement`; standalone `02-implement`) | when implementation starts | -| `implemented` | implemented, not yet reviewed | implement layer | all phases complete / all acceptance criteria ticked | -| `reviewed` | reviewed and approved | review layer (SDLC `04-review`) | the review passes (approved) | -| `blocked` | cannot proceed; needs a human | implement layer | a blocking condition holds (see the implement skill's blocked reference) | +| `pending` | created, not started | plan creation | at plan creation | +| `in-progress` | implementation started | the implement step | when implementation starts | +| `implemented` | implemented, not yet reviewed | the implement step | all phases complete / all acceptance criteria ticked | +| `reviewed` | reviewed and approved | the review step | the review passes (approved) | +| `blocked` | cannot proceed; needs a human | the implement step | a blocking condition holds | ## Rules - Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state. -- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed` → status returns to `in-progress`. +- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan. - `implemented` ≠ reviewed. Only the review layer sets `reviewed`. -- The reviewer and implementer agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. +- Workers never write `status`; only plan creation and the orchestration layers do. diff --git a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md new file mode 100644 index 00000000..1dfb2394 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md @@ -0,0 +1,28 @@ +# Wireframe conventions + +A wireframe is a low-fidelity ASCII sketch of a screen. Structure only: no behavior, no styling, no final copy. + +## Drawing + +- One box per screen, drawn with `┌ ─ ┐ │ └ ┘`. +- Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit. +- Number each region. +- Under the sketch, one line per number on what it holds and why. + +## Example + +``` +┌─────────────────────────────────────┐ +│ (1) Header: logo · search · account │ +├──────────┬──────────────────────────┤ +│ (2) Nav │ (3) Results list │ +│ filters │ ┌──────────────────────┐ │ +│ by type │ │ (4) Result card │ │ +│ │ └──────────────────────┘ │ +└──────────┴──────────────────────────┘ +``` + +1. Header: brand, global search, account menu. +2. Nav: filters that narrow the list. +3. Results: the matched items, paginated. +4. Card: one result, title and summary. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index 8708a777..ea254931 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -2,23 +2,18 @@ # 02 - implement -Executes an existing implementation plan phase by phase via the `implementer` -agent, iterating until every acceptance criterion is satisfied. Each phase -loops until the agent reports 100 % completion. +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 end-to-end against it. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `implement` step to this skill. +- 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 → amend the plan, not the code. -- The task is a bug fix without a plan surface → use - [08-debug](../08-debug/README.md). +- 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 @@ -26,29 +21,25 @@ loops until the agent reports 100 % completion. Use skill aidd-dev:02-implement ``` -Pass the plan path or content as `$ARGUMENTS`. The skill exposes 1 action: +Pass the plan path or content as the arguments. The skill runs three actions in order: -1. `implement` - loop each plan phase: spawn the `implementer` agent, wait - for structured output, re-spawn with `items_remaining` until the phase - hits 100 %. Branching is the caller's responsibility; this skill never - creates branches. Plan amendments are made inline and tagged with the - robot marker. +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 changes on the active branch, one phase at a time. -- `phases_completed` count and `acceptance_satisfied: true` when done. -- Plan amendments inline in the plan file when the loop discovers gaps. +- 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, M/C/D, and acceptance criteria. -- The `implementer` agent available in context. -- Project rules already loaded for the implementer to respect. +- 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/01-implement.md`](actions/01-implement.md) for the phase loop -contract, the re-spawn rule, and the boundary constraints (no formatting, -no dev mode). +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/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index eeff95ff..65dfdd57 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,24 +1,28 @@ --- name: 02-implement -description: Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. -context: fork -agent: implementer +description: 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. +argument-hint: prepare | execute | finalize --- # Skill: implement -Run an existing technical plan to write code, validating each phase before moving on. +Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds. -## Agent delegation +## Actions -Spawn the `implementer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `implementer` agent explicitly with this skill's content as the prompt. +| # | Action | Role | Input | +| --- | ---------- | ----------------------------------------------- | ------------- | +| 01 | `prepare` | Resolve the plan, branch, mark it in-progress | a plan path | +| 02 | `execute` | Loop the phases, code and assert each | prepared plan | +| 03 | `finalize` | Verify and mark the plan implemented | coded phases | -## Actions +Run them in order, `01 → 03`. + +## Transversal rules -```markdown -@actions/01-implement.md -``` +- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit. +- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against. ## References -- `@references/blocked.md` - conditions that make a plan `blocked` (needs a human). All actions inherit it. +- `references/blocked.md`: the conditions that make a plan `blocked` and need a human. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md deleted file mode 100644 index b74d35e7..00000000 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ /dev/null @@ -1,35 +0,0 @@ -# 01 - Implement - -Code the whole feature based on the implementation plan, phase by phase, sequentially, until every acceptance criterion is satisfied. - -## Inputs - -```yaml -plan: -branch: # optional; created when the plan specifies one -``` - -## Outputs - -```yaml -phases_completed: -acceptance_satisfied: true -notes: - - -``` - -## Process - -1. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). Set `status: in-progress` on the plan. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -2. **Phase loop.** For each phase listed in the plan, in order: - - Spawn the `implementer` agent via the `Task` tool, passing the phase scope and acceptance criteria. - - Wait for the agent's structured output. If `completion_score < 100`, re-spawn with `items_remaining` until the phase reaches 100 %. -3. **Plan amendments.** If a phase is incorrect, incomplete, or blocked by missing information, amend the plan directly. Mark every change with 🤖 and a brief rationale. -4. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. -5. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. -6. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. -7. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. - -## Test - -After the loop terminates: every phase has its acceptance criteria checked off, validation commands exit zero, and the plan's frontmatter `status` is `implemented` — OR, if a blocking condition held, the loop stopped and it is `blocked`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md new file mode 100644 index 00000000..7e99042d --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -0,0 +1,23 @@ +# 01 - Prepare + +Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress. + +## Input + +A plan, passed as arguments as a path or inline content. + +## Output + +The resolved plan on a feature branch with its frontmatter `status: in-progress`, ready for the phase loop. Or a fail-fast stop when no plan resolves. + +## Process + +1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at `. Never fabricate a plan. +2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it. +3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code. + +## Test + +- A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. +- The current branch is not the default branch. +- The plan frontmatter reads `status: in-progress`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md new file mode 100644 index 00000000..2464642f --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -0,0 +1,26 @@ +# 02 - Execute + +Loop the plan's phases in order, coding each until every acceptance criterion holds. + +## Input + +The prepared plan on its feature branch, from `01-prepare`. + +## Output + +Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan. + +## Process + +1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet. +2. **Code.** Build the phase scope against its acceptance criteria. +3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together. +4. **Guard.** Stop the loop on either condition: + - **Blocked** (see `@../references/blocked.md`): set the plan `status: blocked`, commit, stop. + - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. Never rewrite the plan; replanning is the caller's job. + +## Test + +- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits). +- The branch holds one commit per phase; there are no separate `in-progress` status commits. +- A blocker leaves the plan `status: blocked` with no later phase run. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md new file mode 100644 index 00000000..2943bc42 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -0,0 +1,21 @@ +# 03 - Finalize + +Run the validation and mark the plan implemented once every phase is done. + +## Input + +A plan whose phases are all `status: done`, from `02-execute`. + +## Output + +The feature validated green with the plan frontmatter `status: implemented`. + +## Process + +1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. +2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. + +## Test + +- The validation commands exit zero. +- The plan reads `status: implemented`, committed (`git status --short` shows it clean). diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md index 3bdd7dc6..505a3389 100644 --- a/plugins/aidd-dev/skills/02-implement/references/blocked.md +++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md @@ -4,6 +4,7 @@ description: Conditions that make a plan blocked (needs a human). --- # When a plan is blocked -`blocked` = implementation cannot proceed; only a human can unblock. Stop, set `status: blocked`, escalate. + +`blocked` means implementation cannot proceed and only a human can unblock it. Stop, set `status: blocked`, and escalate. Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA. diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md index c0a9c069..2d79a27d 100644 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -2,13 +2,13 @@ # 03 - assert -Validates implementations through iterative assertion loops. Covers general -feature assertions, architecture conformance (ADRs, diagrams, project -structure), and browser-based frontend UI checks. +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 -- A feature is implemented and you need to assert it behaves as intended +- 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). @@ -30,21 +30,19 @@ structure), and browser-based frontend UI checks. Use skill aidd-dev:03-assert ``` -The skill exposes 3 actions: +The skill exposes 3 facets, run together when applicable or one when named: -1. `assert` - general assertion loop against an acceptance criterion. -2. `assert-architecture` - verify code matches architecture diagrams, - ADRs, and the project's documented structure. -3. `assert-frontend` - drive a browser to confirm a frontend feature - behaves as intended. +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 / fail verdict per assertion, with the failing item identified. -- Recorded findings when an assertion fails (file, line, expected vs - observed). -- Browser session artifacts (screenshots, console output) for the - frontend variant. +- 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 diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 32646380..5a4f8b8b 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,33 +1,30 @@ --- name: 03-assert -description: Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. +description: 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. +argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- # Skill: assert -Validates correctness of implementations through iterative assertion loops, architecture checks, and browser-based frontend verification. +Validate that the work behaves as intended: run the project's assertions, iterating and fixing until they pass. -## Available actions - -| # | Action | When to use | -| --- | --------------------- | ---------------------------------------------------------------------------- | -| 01 | `assert` | Iterate until a feature works by running the project's coding assertions | -| 02 | `assert-architecture` | Verify the codebase conforms to documented architecture (C4, ADRs, tree) | -| 03 | `assert-frontend` | Iterate until a frontend feature works by inspecting the running UI | +## Actions -## Routing (run first) +| # | Action | Facet | +| --- | --------------------- | ----------------------------------------------------------- | +| 01 | `assert` | Run the project's coding assertions, fixing until they pass | +| 02 | `assert-architecture` | Report where the code breaks the documented architecture | +| 03 | `assert-frontend` | Inspect the running UI, fixing until the behavior is right | -These actions are complementary facets, not mutually exclusive. This skill is run-one-OR-run-all: +Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the work has a UI and a frontend is running, the facet resolving the URL itself; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. -- The user named a facet ("assert the frontend", "check architecture conformance") -> run that ONE action. -- The user asked for an unscoped assertion ("assert this works", "make the feature pass") -> ask ONE question: "Assert everything applicable, or a specific facet (coding / architecture / frontend)?" Then run all applicable, or the chosen one. -- Never silently default to action 01. Never run a blind all without offering the choice first. +## Transversal rules -When running all applicable: `01-assert` is the baseline (project coding assertions); add `03-assert-frontend` when the feature has a UI and a running frontend URL; add `02-assert-architecture` when architecture conformance is in scope. A facet whose precondition is absent (e.g. no running URL) is skipped with a noted reason, never forced. Run the selected actions in order (01, then 03, then 02). Read and follow each selected action file. +- Gate: it returns a pass or fail verdict on the work. +- Fix loop: the coding and frontend facets fix and re-run until they pass. The architecture facet only reports, never fixes. +- Stop only when every selected assertion passes a final clean sweep. -## Actions +## Assets -- `@actions/01-assert.md` -- `@actions/02-assert-architecture.md` -- `@actions/03-assert-frontend.md` +- `assets/task-template.md`: the tracking file the frontend facet fills across its fix loop. diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index cea380da..8904e510 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -1,32 +1,23 @@ # 01 - Assert -Iterate until a feature works as intended by running the project's coding assertions and fixing every failure. +Iterate the project's coding assertions until the work passes every one, fixing each failure. -## Inputs +## Input -```yaml -feature: -``` +The work to assert, named or described, from the arguments or the context. -## Outputs +## Output -```yaml -assertions_total: -assertions_passing: -iterations: -fixes_applied: - - { file: , change: } -``` +A pass or fail verdict: every applicable assertion passing in a final clean sweep, with the fixes applied listed. ## Process -1. **Enumerate assertions.** From the current context (project conventions and coding-assertions memory), list the assertions that apply to the feature. -2. **Iterate per assertion.** For each one: - - Fix any issues preventing it from passing. - - Re-run the assertion to confirm it passes. -3. **Full re-check.** Once every assertion has passed at least once, re-run all of them in one sweep to confirm none regressed. -4. **Boundary.** Do not stop until every assertion passes in the final sweep. +1. **Enumerate.** List the assertions that apply, from the project conventions and `aidd_docs/memory/coding-assertions.md` when it exists. +2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. +3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. +4. **Boundary.** Do not stop until every assertion passes the final sweep. ## Test -The final sweep reports `assertions_passing == assertions_total`; the recorded `fixes_applied` list cites real diffs (no empty or placeholder entries when fixes were claimed). +- The final sweep passes every applicable assertion. +- The fixes listed cite real diffs, with no placeholder entries. diff --git a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md index 8125bcd1..cea6c981 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md +++ b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md @@ -1,48 +1,24 @@ # 02 - Assert Architecture -Verify that the codebase (or a specific scope) conforms to the documented architecture: C4 diagrams, ADRs, and project tree structure. +Report where the codebase breaks the documented architecture: C4 diagrams, ADRs, and the project tree. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire project -``` +The scope to check, a module, service, or layer, from the arguments; defaults to the whole project. -## Outputs +## Output -```yaml -report: - macro: - - { severity: critical|warning, file: , constraint: , fix: } - micro: - - { severity: critical|warning, file: , constraint: , fix: } -totals: - violations_total: - critical: - warning: -``` +A conformance report listing each violation, grouped macro and micro, with severity, file, the constraint broken, and a one-line fix. Report only; it never fixes. ## Process -1. **Load architecture context.** - - Remember the architecture diagrams from `aidd_docs/memory/architecture.md`. - - Read micro diagrams from `aidd_docs/memory/internal/` when the scope targets a specific module. - - Read ADRs from `aidd_docs/internal/decisions/`. - - Extract the expected project tree structure from the diagrams. -2. **Verify macro architecture (service boundaries).** - - Compare actual code structure against the documented tree. - - Flag files outside expected boundaries. - - Flag direct imports between independent services. -3. **Verify micro architecture (internal layers).** For each module in scope: - - Check that import directions match layer constraints. - - Confirm the domain layer has zero external imports. - - Confirm the application layer depends only on the domain via ports. - - Detect circular dependencies between modules. - - Verify the expected patterns (use cases have ports, adapters implement interfaces). -4. **Build the violation report.** Each entry carries severity (`critical | warning`), file path, the constraint violated, and a one-line suggested fix. Group entries macro vs micro. -5. **Boundary.** Do not fix violations - only report them. If no scope is provided, check the entire project. -6. **Summarize.** Total violations, critical count, recommended next actions. +1. **Load.** Read the architecture sources: the architecture memory, the micro diagrams for an in-scope module, and the decision records. Extract the expected project tree. +2. **Macro.** Compare the code structure against the documented tree. Flag files outside their boundary and direct imports between independent services. +3. **Micro.** For each in-scope module, check import directions against the layer constraints. The domain layer imports nothing external. The application layer reaches the domain only through ports. No circular dependencies. Adapters implement their interfaces. +4. **Report.** One entry per violation, grouped macro and micro, each with severity (`critical` or `warning`), file, constraint, and a one-line fix. +5. **Summarize.** The total violations, the critical count, and the recommended next actions. ## Test -If conformity holds: `violations_total == 0` and the report explicitly states "no violations" in both macro and micro sections. If violations exist: every report entry has a real file path that exists on disk, a referenced constraint that appears in one of the loaded architecture sources, and a non-empty `fix` field. +- On conformance, the report states "no violations" in both the macro and micro sections. +- On violations, every entry has a real file path, a constraint drawn from a loaded architecture source, and a non-empty fix. diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 92ae09f4..3d6a9d87 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -1,40 +1,26 @@ # 03 - Assert Frontend -Iterate until a frontend feature works as intended by inspecting the running UI, mapping the behavior to the code, and tracking attempts in a task template. +Iterate until the frontend behaves as intended by inspecting the running UI, mapping behavior to code, and tracking attempts. -## Inputs +## Input -```yaml -expected_behavior: -url: # required; the frontend must already be running -``` +The expected behavior, from the arguments. The frontend's URL when the caller knows it, otherwise resolved at runtime. -## Outputs +## Output -```yaml -task_template_path: -iterations: -fixed: true|false -report: - - { iteration: , hypothesis: , fix_attempted: , validated: pass|fail } -``` +A pass or fail verdict, with the candidate causes and their fix attempts and results recorded in the tracking file. ## Process -Iterate over the steps below until the feature works as intended. - -1. **Parse the request.** Extract expected requirements (visual, functional, technical) from `expected_behavior`. Summarize and list action paths (e.g. user clicks button -> calls function in file1 -> updates state in file2). -2. **Inspect the running app.** Open the URL via the configured browsing tool. Inspect the page visually and technically. Take screenshots to confirm the issue. -3. **Locate the code.** Explore the codebase to find the files and snippets related to the issue. -4. **Fill the tracking template** from `@../assets/task-template.md`. List the three best potential causes with a short description and confidence level. -5. **Fix-loop.** - - Take the first potential cause. - - Apply a candidate fix. - - Validate against the expected behavior. - - If not fixed, mark the cause and move to the next. - - When the three causes are exhausted, re-evaluate, add three new causes to the template, and repeat from step 5. -6. **Boundaries.** Assume all servers are already running. Minor visual discrepancies (1-2 px differences, slight color variations) are acceptable unless explicitly specified in the initial request. Screenshots MUST be used to validate UI changes. +1. **Resolve.** Use the URL the caller gave, otherwise find the running frontend and confirm it responds. Skip this facet with a noted reason when none is running. +2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. +3. **Inspect.** Open the URL with the project's configured browser tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. +4. **Locate.** Explore the codebase for the files behind the issue. +5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. +6. **Fix.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. +7. **Boundary.** Never start or restart a server. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. ## Test -The task template file exists and is updated for every iteration; the final entry in `report` has `validated: pass`; the running URL renders the expected behavior, confirmed by a screenshot recorded after the final iteration. +- The tracking file updates on every iteration. +- The final recorded attempt validates as a pass, confirmed by a screenshot taken after it. diff --git a/plugins/aidd-dev/skills/03-assert/assets/task-template.md b/plugins/aidd-dev/skills/03-assert/assets/task-template.md index cdc9e1db..dc2beec2 100644 --- a/plugins/aidd-dev/skills/03-assert/assets/task-template.md +++ b/plugins/aidd-dev/skills/03-assert/assets/task-template.md @@ -1,15 +1,11 @@ ---- -name: task -description: Task tracking system to ensure all tasks are categorized and addressed ---- + # Task [] {{Full description}} -## Main step 1} +## Main step 1 - [ ] {Task 1} - [ ] {Task 2} - [ ] {Task 3} -- ... diff --git a/plugins/aidd-dev/skills/04-audit/README.md b/plugins/aidd-dev/skills/04-audit/README.md index f4cc8621..6e534c45 100644 --- a/plugins/aidd-dev/skills/04-audit/README.md +++ b/plugins/aidd-dev/skills/04-audit/README.md @@ -3,9 +3,8 @@ # 04 - audit Read-only codebase audit across seven quality pillars. Diagnoses and ranks -findings into a structured report; it never edits code. Each finding hands -off to the relevant act-skill (refactor, test, impeccable) when a fix is -wanted. +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 @@ -17,9 +16,9 @@ wanted. ## 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 the act-skill it - hands off to ([07-refactor](../07-refactor/README.md), - [06-test](../06-test/README.md), or the `impeccable` skill for UI). +- 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). diff --git a/plugins/aidd-dev/skills/04-audit/SKILL.md b/plugins/aidd-dev/skills/04-audit/SKILL.md index d4f98968..02448223 100644 --- a/plugins/aidd-dev/skills/04-audit/SKILL.md +++ b/plugins/aidd-dev/skills/04-audit/SKILL.md @@ -1,18 +1,19 @@ --- name: 04-audit -description: Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert). +description: 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. +argument-hint: code-quality | architecture | security | dependencies | performance | tests | ui model: opus --- # Skill: audit -Diagnoses a codebase against quality pillars and emits a structured findings report. This skill is **read-only**: it identifies and ranks problems, it never changes code. Each finding hands off to the relevant act-skill when a fix is wanted. +Diagnose a codebase against quality pillars and emit one ranked findings report. Read-only: it identifies and ranks problems, never changes code. -## Available actions +## Actions | # | Action | Pillar | Lens | | --- | -------------- | ------------ | -------------------------------------------------------------------- | -| 01 | `code-quality` | code-quality | Clean code (naming, SOLID, DRY, readability, smells) + tech debt (dead code, complexity, file/function size, error handling) | +| 01 | `code-quality` | code-quality | Clean code (naming, SOLID, DRY, readability, smells) and tech debt (dead code, complexity, file/function size, error handling) | | 02 | `architecture` | architecture | Conformance to C4 / ADRs, coupling, boundaries, layering | | 03 | `security` | security | OWASP risks, authz, input validation, secrets in code | | 04 | `dependencies` | dependencies | CVEs, licenses, outdated and unused deps, supply chain | @@ -20,36 +21,16 @@ Diagnoses a codebase against quality pillars and emits a structured findings rep | 06 | `tests` | tests | Critical-path coverage, flakiness, test pyramid balance | | 07 | `ui` | ui | Loading/error/empty states, visual hierarchy, design-system drift, responsive, a11y | -## Routing (run first) - -This skill is run-one-OR-run-all: - -- The user named a pillar ("audit security", "audit the deps", "perf audit") -> run that ONE action. -- The user asked for a full or unscoped audit ("audit the codebase", "/audit", "health check") -> ask ONE question: "Full audit (all 7 pillars), or a specific pillar?" Then run all applicable pillars, or the chosen one. -- Never silently default to action 01. Never run a blind all without offering the choice first. - -When running all, skip a pillar whose method cannot run in this environment (e.g. no profiler for performance, no lockfile scanner for dependencies) and record it under the report's `Coverage > Skipped` with the reason. Never invent findings for an unscannable pillar. +Run the one pillar named, or offer all seven when the request is unscoped. -## Output contract +## Transversal rules -The report uses the shared template `@assets/audit-template.md`. There is ALWAYS exactly one report file and exactly one writer of it - never one file per pillar in a full run. +- Read-only: diagnose and rank, never edit code. +- Scope: run the one named pillar, or for an unscoped request ask once "all seven pillars, or one?" before running. Never silently default to one pillar, never blind-run all without offering the choice. +- One folder per run, `aidd_docs/tasks//_audit/`, like a feature folder. Every pillar that runs always writes its own `.md` there, alone or in a full run. A full run additionally writes a merged `report.md`: one Findings table (category = pillar, severity-first), one Top-actions list, and one Coverage section over all seven pillars. +- Unscannable pillar: skip it, record it under `Coverage > Skipped` with the reason, and never invent findings for it. +- Every finding row carries a severity, its pillar, a concrete `file:line`, the issue, a suggested fix, and an effort. -**Single-pillar run.** Run the one pillar action; it writes its own report at `aidd_docs/tasks/audits/__.md`. - -**Full run.** Run each applicable pillar action to COLLECT its findings (the pillars do not each write a file in this mode), then write ONE merged report at `aidd_docs/tasks/audits/__full.md`: -- one template header, -- the union of every pillar's finding rows in a single Findings table (`Category` = the pillar per row), sorted severity-first across all pillars, -- one ranked Top-actions list spanning all pillars, -- one Coverage section listing all 7 pillars as scanned or skipped (with reason). - -Every finding row: severity + pillar + concrete `file:line` + issue + suggested fix + effort. Read-only in both modes: emit the report and stop; never edit code. - -## Actions +## Assets -- `@actions/01-code-quality.md` -- `@actions/02-architecture.md` -- `@actions/03-security.md` -- `@actions/04-dependencies.md` -- `@actions/05-performance.md` -- `@actions/06-tests.md` -- `@actions/07-ui.md` +- `assets/audit-template.md`: the report structure both run modes fill. diff --git a/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md b/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md index cc2f4ae0..3dcc5e3e 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md +++ b/plugins/aidd-dev/skills/04-audit/actions/01-code-quality.md @@ -1,31 +1,28 @@ # 01 - Code-quality audit -Read-only audit of the `code-quality` pillar: clean-code craftsmanship and tech debt. Reports findings, never edits code. +Read-only audit of the `code-quality` pillar, clean-code craftsmanship and tech debt. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -``` +An optional scope, a directory or file glob. Defaults to the entire codebase. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__code-quality.md # or __full.md in a full run -pillar: code-quality -findings_count: -``` +The `code-quality` findings, written to `code-quality.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. -2. **Scan the two lenses** below, using the project's conventions and coding rules already loaded in context. Stay in this pillar - architecture coupling belongs to `02-architecture`, runtime cost to `05-performance`, coverage to `06-tests`, CVEs to `04-dependencies`. - - **Clean code (craftsmanship)**: naming clarity, single-responsibility / SOLID, DRY (copy-pasted logic, re-implemented stdlib helpers), readability, abstraction level, magic numbers, dead or misleading comments, code smells. - - **Tech debt (structural)**: dead and unreachable code, unused exports/types/helpers, stale TODOs, vestigial flags, cyclomatic complexity and file/function/component length above project thresholds, nesting depth, error handling caught at the wrong boundary or silently swallowed. - - Use dedicated tools when available (e.g. an unused-export finder); never assert dead code without evidence. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` for every finding. Category is always `code-quality`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (hand off fixes to `aidd-dev:07-refactor`), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. +2. **Scan.** Cover the two lenses below, using the project's conventions and coding rules already in context. Stay in this pillar: coupling belongs to `02-architecture`, runtime cost to `05-performance`, coverage to `06-tests`, CVEs to `04-dependencies`. + - **Clean code**: naming clarity, single-responsibility and SOLID, DRY (copy-pasted logic, re-implemented stdlib helpers), readability, abstraction level, magic numbers, dead or misleading comments, code smells. + - **Tech debt**: dead and unreachable code, unused exports, types, and helpers, stale TODOs, vestigial flags, cyclomatic complexity and file, function, or component length above project thresholds, nesting depth, error handling caught at the wrong boundary or silently swallowed. + - Use a dedicated tool when available, for example an unused-export finder. Never assert dead code without evidence. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `code-quality`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `code-quality`, a concrete `file:line`, and an effort; Coverage lists `code-quality` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `code-quality`, a concrete `file:line`, and an effort. +- Coverage lists `code-quality` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md b/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md index f5685ef9..69baec04 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md +++ b/plugins/aidd-dev/skills/04-audit/actions/02-architecture.md @@ -1,32 +1,29 @@ # 02 - Architecture audit -Read-only audit of the `architecture` pillar: conformance to documented architecture, module coupling, and layer/boundary violations. Reports findings, never edits code. +Read-only audit of the `architecture` pillar, conformance to documented architecture, module coupling, and layer or boundary violations. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -``` +An optional scope, a directory or file glob. Defaults to the entire codebase. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__architecture.md # or __full.md in a full run -pillar: architecture -findings_count: -``` +The `architecture` findings, written to `architecture.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. -2. **Scan the architecture lens** below, using architecture documents already loaded in context (`aidd_docs/memory`, ADRs, C4 diagrams). Stay in this pillar - intra-file craftsmanship belongs to `01-code-quality`; runtime cost to `05-performance`; CVEs to `04-dependencies`. - - **Conformance**: map the actual code structure against documented modules, layers, and C4 boundaries; flag any divergence from the stated architecture. - - **Coupling**: identify modules that import from layers they should not depend on (wrong dependency direction: outward imports into an inner layer, or circular references across bounded contexts). - - **God-modules**: detect modules with an abnormally large surface area (too many exports, too many responsibilities) that signal architectural erosion. - - When ADRs or C4 diagrams are absent, note "no architecture docs found - conformance check skipped" in Coverage > Skipped and limit the scan to observable coupling heuristics. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` for every finding. Category is always `architecture`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (conformance gaps feed re-planning; structural fixes hand off to `aidd-dev:07-refactor`), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. +2. **Scan.** Read the architecture documents already in context (`aidd_docs/memory`, ADRs, C4 diagrams). Stay in this pillar: intra-file craftsmanship belongs to `01-code-quality`, runtime cost to `05-performance`, CVEs to `04-dependencies`. + - **Conformance**: map the actual code structure against the documented modules, layers, and C4 boundaries. Flag any divergence from the stated architecture. + - **Coupling**: identify modules that import from layers they should not depend on, a wrong dependency direction or a circular reference across bounded contexts. + - **God-modules**: detect modules with an abnormally large surface area, too many exports or responsibilities, that signal architectural erosion. + - When ADRs or C4 diagrams are absent, note "no architecture docs found, conformance check skipped" in `Coverage > Skipped` and limit the scan to observable coupling heuristics. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `architecture`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `architecture`, a concrete `file:line`, and an effort; Coverage lists `architecture` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `architecture`, a concrete `file:line`, and an effort. +- Coverage lists `architecture` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/actions/03-security.md b/plugins/aidd-dev/skills/04-audit/actions/03-security.md index e504f549..4935fa61 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/03-security.md +++ b/plugins/aidd-dev/skills/04-audit/actions/03-security.md @@ -1,35 +1,32 @@ # 03 - Security audit -Read-only audit of the `security` pillar: OWASP top risks and code-level security weaknesses. Reports findings, never edits code. +Read-only audit of the `security` pillar, OWASP top risks and code-level security weaknesses. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -``` +An optional scope, a directory or file glob. Defaults to the entire codebase. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__security.md # or __full.md in a full run -pillar: security -findings_count: -``` +The `security` findings, written to `security.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. -2. **Scan the security lens** below using static code analysis. Stay in this pillar - known-CVE and vulnerable-dependency findings belong to `04-dependencies`; architecture coupling to `02-architecture`. - - **Input validation at trust boundaries**: check that all external inputs (HTTP requests, env vars, file paths, user-supplied data) are validated or sanitised before use. - - **Authn/authz gates**: verify that authentication and authorisation checks are enforced consistently at every protected route or operation. - - **Secrets committed in code**: flag hardcoded credentials, API keys, tokens, or passwords anywhere in the scanned files. - - **Injection risks**: SQL, command, XSS, LDAP, template injection - identify concatenated or unescaped values passed to interpreters. - - **Unsafe deserialization**: flag use of `eval`, unsafe YAML/pickle/JSON reviver patterns, or object deserialization from untrusted sources. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. +2. **Scan.** Use static code analysis. Stay in this pillar: known-CVE and vulnerable-dependency findings belong to `04-dependencies`, coupling to `02-architecture`. + - **Input validation at trust boundaries**: check that every external input (HTTP requests, env vars, file paths, user-supplied data) is validated or sanitised before use. + - **Authn/authz gates**: verify authentication and authorisation checks are enforced consistently at every protected route or operation. + - **Secrets in code**: flag hardcoded credentials, API keys, tokens, or passwords anywhere in the scanned files. + - **Injection risks**: SQL, command, XSS, LDAP, or template injection. Identify concatenated or unescaped values passed to interpreters. + - **Unsafe deserialization**: flag `eval`, unsafe YAML/pickle/JSON reviver patterns, or object deserialization from untrusted sources. - **Insecure defaults**: missing TLS enforcement, overly permissive CORS, disabled security headers, debug flags left on in non-dev code. - - Use static analysis tools when available; flag only findings supported by code evidence. Do not infer from naming alone. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` for every finding. Category is always `security`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (hand off fixes to `aidd-dev:07-refactor` for security), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. + - Use a static-analysis tool when available. Flag only findings supported by code evidence, never inferred from naming alone. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `security`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `security`, a concrete `file:line`, and an effort; Coverage lists `security` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `security`, a concrete `file:line`, and an effort. +- Coverage lists `security` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md b/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md index c0ab991a..50f3128f 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md +++ b/plugins/aidd-dev/skills/04-audit/actions/04-dependencies.md @@ -1,33 +1,30 @@ # 04 - Dependencies audit -Read-only audit of the `dependencies` pillar: CVEs, license compliance, outdated packages, and supply-chain integrity. Reports findings, never edits code. +Read-only audit of the `dependencies` pillar, CVEs, license compliance, outdated packages, and supply-chain integrity. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -``` +An optional scope, a directory or file glob. Defaults to the entire codebase. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__dependencies.md # or __full.md in a full run -pillar: dependencies -findings_count: -``` +The `dependencies` findings, written to `dependencies.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. -2. **Scan the dependencies lens** below using the appropriate dependency scanner. Stay in this pillar - application code security issues belong to `03-security`; runtime cost to `05-performance`. - - **Known CVEs**: run `npm audit`, `pip-audit`, `cargo audit`, or the equivalent scanner for the project's package manager. If no scanner is available or no lockfile is present, record "scanner absent" or "no lockfile found" in Coverage > Skipped and do not guess CVEs. - - **License compliance**: check declared licenses against the project's accepted-license list; flag GPL/AGPL or unknown licenses in a commercial codebase. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. +2. **Scan.** Use the appropriate dependency scanner. Stay in this pillar: application-code security belongs to `03-security`, runtime cost to `05-performance`. + - **Known CVEs**: run `npm audit`, `pip-audit`, `cargo audit`, or the equivalent for the project's package manager. When no scanner or lockfile is present, record "scanner absent" or "no lockfile found" in `Coverage > Skipped` and do not guess CVEs. + - **License compliance**: check declared licenses against the project's accepted-license list. Flag GPL/AGPL or unknown licenses in a commercial codebase. - **Outdated packages**: identify packages significantly behind their latest stable release, especially those with security-relevant changelogs. - - **Unused declared dependencies**: flag packages listed in the manifest but with no import found in the scanned source. - - **Lockfile integrity and supply-chain**: verify the lockfile is present and committed; flag direct git/URL dependencies and any package with no integrity hash. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` (manifest or lockfile line) for every finding. Category is always `dependencies`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (hand off upgrades to `aidd-dev:07-refactor` or manual upgrade), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. + - **Unused declared dependencies**: flag packages listed in the manifest with no import found in the scanned source. + - **Lockfile integrity and supply chain**: verify the lockfile is present and committed. Flag direct git or URL dependencies and any package with no integrity hash. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line` in the manifest or lockfile. The category is always `dependencies`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `dependencies`, a concrete `file:line`, and an effort; Coverage lists `dependencies` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `dependencies`, a concrete `file:line`, and an effort. +- Coverage lists `dependencies` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/actions/05-performance.md b/plugins/aidd-dev/skills/04-audit/actions/05-performance.md index 919e7e7f..e19e1aed 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/05-performance.md +++ b/plugins/aidd-dev/skills/04-audit/actions/05-performance.md @@ -1,35 +1,32 @@ # 05 - Performance audit -Read-only audit of the `performance` pillar: runtime cost, query patterns, and rendering efficiency. Reports findings, never edits code. +Read-only audit of the `performance` pillar, runtime cost, query patterns, and rendering efficiency. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -``` +An optional scope, a directory or file glob. Defaults to the entire codebase. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__performance.md # or __full.md in a full run -pillar: performance -findings_count: -``` +The `performance` findings, written to `performance.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. -2. **Scan the performance lens** below, preferring runtime tools (profiler, bundle analyzer, query explain) when available. Stay in this pillar - cyclomatic complexity belongs to `01-code-quality`; architectural coupling to `02-architecture`. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. +2. **Scan.** Prefer runtime tools (profiler, bundle analyzer, query explain) when available. Stay in this pillar: cyclomatic complexity belongs to `01-code-quality`, coupling to `02-architecture`. - **N+1 queries**: detect loops that issue a database or network call on each iteration without batching. - **Unbatched heavy operations**: flag heavy computations or I/O repeated individually where a batch or bulk API exists. - - **Unpaginated large payloads**: identify endpoints or queries that fetch unbounded result sets without limit or pagination. - - **Bundle size**: use a bundle analyzer when available; flag large or duplicated dependencies that inflate the JS/CSS payload. - - **Render thrash and re-render storms**: detect layout-thrashing DOM patterns, missing memoization on computed values used in hot render paths, or component trees that re-render without guard on reference-stable props. + - **Unpaginated large payloads**: identify endpoints or queries that fetch unbounded result sets without a limit or pagination. + - **Bundle size**: use a bundle analyzer when available. Flag large or duplicated dependencies that inflate the JS or CSS payload. + - **Render thrash**: detect layout-thrashing DOM patterns, missing memoization on computed values used in hot render paths, or component trees that re-render without a guard on reference-stable props. - **Missing memoization on hot paths**: flag expensive pure computations inside render or tight loops that are not memoized. - - When no profiler or bundle analyzer is available, degrade to static heuristics and record "no profiler - static heuristics only" in Coverage > Skipped. Never assert a runtime bottleneck without evidence. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` for every finding. Category is always `performance`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (hand off fixes to `aidd-dev:07-refactor` for performance), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. + - When no profiler or bundle analyzer is available, degrade to static heuristics and record "no profiler, static heuristics only" in `Coverage > Skipped`. Never assert a runtime bottleneck without evidence. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `performance`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `performance`, a concrete `file:line`, and an effort; Coverage lists `performance` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `performance`, a concrete `file:line`, and an effort. +- Coverage lists `performance` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/actions/06-tests.md b/plugins/aidd-dev/skills/04-audit/actions/06-tests.md index 3a6e7d73..36b42e1d 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/06-tests.md +++ b/plugins/aidd-dev/skills/04-audit/actions/06-tests.md @@ -1,34 +1,31 @@ # 06 - Tests audit -Read-only audit of the `tests` pillar: coverage gaps, test quality, and test suite health. Reports findings, never edits code. +Read-only audit of the `tests` pillar, coverage gaps, test quality, and suite health. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -``` +An optional scope, a directory or file glob. Defaults to the entire codebase. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__tests.md # or __full.md in a full run -pillar: tests -findings_count: -``` +The `tests` findings, written to `tests.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. -2. **Scan the tests lens** below, preferring a coverage report when available. Stay in this pillar - whether a feature behaves correctly belongs to `aidd-dev:03-assert`; runtime cost to `05-performance`. - - **Critical-path coverage gaps**: identify code paths (auth flows, data mutations, error handling) that have no corresponding test; use a coverage report when available, degrade to static inspection of test-file presence when absent. - - **Tests asserting implementation instead of behavior**: flag tests that couple to internal method names, private state, or implementation details rather than observable outputs. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. +2. **Scan.** Prefer a coverage report when available. Stay in this pillar: whether a feature behaves correctly is a separate concern, runtime cost belongs to `05-performance`. + - **Critical-path coverage gaps**: identify code paths (auth flows, data mutations, error handling) with no test. Use a coverage report when available, degrade to static inspection of test-file presence when absent. + - **Tests asserting implementation, not behavior**: flag tests coupled to internal method names, private state, or implementation details rather than observable outputs. - **Flaky tests**: flag tests that use arbitrary `sleep` calls, rely on timing, or have known intermittent failures recorded in CI history or inline comments. - - **Skipped or xfail tests without a recorded reason**: flag `skip`, `xit`, `xfail`, `.todo`, or equivalent markers that lack an explanatory comment or issue reference. - - **Test pyramid imbalance**: flag suites with disproportionately many end-to-end or integration tests and few unit tests, raising maintenance cost and feedback speed. - - When no coverage tool is available, record "no coverage tool - static inspection only" in Coverage > Skipped and limit findings to structurally observable issues. Do not invent coverage numbers. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` for every finding. Category is always `tests`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (hand off new or fixed tests to `aidd-dev:06-test`), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. + - **Skipped tests without a reason**: flag `skip`, `xit`, `xfail`, `.todo`, or equivalent markers that lack an explanatory comment or issue reference. + - **Test pyramid imbalance**: flag suites with disproportionately many end-to-end or integration tests and few unit tests, raising maintenance cost and slowing feedback. + - When no coverage tool is available, record "no coverage tool, static inspection only" in `Coverage > Skipped` and limit findings to structurally observable issues. Do not invent coverage numbers. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `tests`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `tests`, a concrete `file:line`, and an effort; Coverage lists `tests` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `tests`, a concrete `file:line`, and an effort. +- Coverage lists `tests` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/actions/07-ui.md b/plugins/aidd-dev/skills/04-audit/actions/07-ui.md index 3666ec46..3f11a649 100644 --- a/plugins/aidd-dev/skills/04-audit/actions/07-ui.md +++ b/plugins/aidd-dev/skills/04-audit/actions/07-ui.md @@ -1,35 +1,31 @@ # 07 - UI audit -Read-only audit of the `ui` pillar: missing states, design-system drift, responsive gaps, and accessibility. Reports findings, never edits code. +Read-only audit of the `ui` pillar, missing states, design-system drift, responsive gaps, and accessibility. Reports findings, never edits code. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -url: # optional; enables runtime axe a11y pass -``` +An optional scope, a directory or file glob, defaulting to the entire codebase. An optional running-frontend URL enables a runtime axe accessibility pass. -## Outputs +## Output -```yaml -audit_path: aidd_docs/tasks/audits/__ui.md # or __full.md in a full run -pillar: ui -findings_count: -``` +The `ui` findings, written to `ui.md` in the run's audit folder. ## Process -1. **Load scope.** Default to the full codebase when `scope` is absent; otherwise restrict scanning to the provided glob or directory. When `url` is provided, also run a browser-based accessibility pass against the live frontend. -2. **Scan the UI lens** below using static component/markup analysis, supplemented by a runtime axe-style accessibility pass when `url` is provided. Stay in this pillar - redesign or implementation fixes belong to the `impeccable` skill or the `iris` agent, not this audit. - - **Missing loading, error, and empty states**: flag UI surfaces (lists, forms, async data areas) that have no visible feedback for loading in-progress, failed fetches, or zero-result datasets. - - **Visual hierarchy issues**: flag layouts where primary actions are visually subordinate, or where typographic hierarchy (heading levels, contrast ratio between heading and body) is broken. - - **Design-system and design-token drift**: identify hardcoded colour, spacing, or typography values that deviate from the project's design tokens or component library conventions. - - **Responsive breakpoint gaps**: flag components or layouts that break or overflow at standard breakpoints (mobile, tablet, desktop) detectable from markup or media queries in the source. - - **Accessibility (WCAG)**: contrast ratio failures, missing keyboard navigation, incorrect or absent aria roles/labels, missing `alt` text on images; run axe or equivalent against `url` when provided; otherwise inspect markup statically. - - When `url` is absent, record "no url provided - runtime a11y pass skipped, static inspection only" in Coverage > Skipped. Do not invent runtime findings from static analysis. -3. **Rate each finding.** Severity (🔴 / 🟡 / 🟢) and effort (S/M/L) per `@../assets/audit-template.md` legend. Quote a concrete `file:line` for every finding. Category is always `ui`. -4. **Write the report** using `@../assets/audit-template.md`: fill the Findings table (one row per issue, severity-first), ranked Top actions (hand off fixes to `impeccable`), and the Coverage section. In a full audit run, contribute these finding rows to the single merged report per the skill output contract instead of writing a separate file. Read-only: emit the report and stop; do not edit code. +1. **Scope.** Default to the full codebase when no scope is given. Otherwise restrict scanning to the provided glob or directory. When a URL is given, also run a browser-based accessibility pass against the live frontend. +2. **Scan.** Use static component and markup analysis, plus a runtime axe-style accessibility pass when a URL is given. Stay in this pillar: redesign and implementation fixes are a separate concern. + - **Missing loading, error, and empty states**: flag UI surfaces (lists, forms, async data areas) with no visible feedback for in-progress loading, failed fetches, or zero-result datasets. + - **Visual hierarchy**: flag layouts where primary actions are visually subordinate, or where typographic hierarchy (heading levels, heading-to-body contrast) is broken. + - **Design-token drift**: identify hardcoded colour, spacing, or typography values that deviate from the project's design tokens or component library. + - **Responsive breakpoint gaps**: flag components or layouts that break or overflow at standard breakpoints (mobile, tablet, desktop), detectable from markup or media queries. + - **Accessibility (WCAG)**: contrast-ratio failures, missing keyboard navigation, incorrect or absent aria roles and labels, missing `alt` text. Run axe or equivalent against the URL when given, otherwise inspect markup statically. + - When no URL is given, record "no url provided, runtime a11y pass skipped, static inspection only" in `Coverage > Skipped`. Do not invent runtime findings from static analysis. +3. **Rate.** Give each finding a severity and an effort per the `@../assets/audit-template.md` legend, with a concrete `file:line`. The category is always `ui`. +4. **Write.** Fill `@../assets/audit-template.md` into the pillar file: the Findings table (one row per issue, severity-first), the ranked Top actions, and the Coverage section. In a full run, also add the rows to the merged `report.md` in the same folder. Emit the report and stop. ## Test -The output file exists at `audit_path`; it has the `## Findings`, `## Top actions`, `## Coverage` sections; every Findings row has a severity, category `ui`, a concrete `file:line`, and an effort; Coverage lists `ui` as scanned. No abstract "the codebase has..." sentences, no code changes made. +- The output file exists at the reported path. +- It has the `## Findings`, `## Top actions`, and `## Coverage` sections. +- Every Findings row carries a severity, category `ui`, a concrete `file:line`, and an effort. +- Coverage lists `ui` as scanned, and no code was changed. diff --git a/plugins/aidd-dev/skills/04-audit/assets/audit-template.md b/plugins/aidd-dev/skills/04-audit/assets/audit-template.md index 915cfaa6..6566f8cc 100644 --- a/plugins/aidd-dev/skills/04-audit/assets/audit-template.md +++ b/plugins/aidd-dev/skills/04-audit/assets/audit-template.md @@ -33,7 +33,7 @@ Category (the audit pillar, one of): `code-quality`, `architecture`, `security`, | 🟡 | code-quality | `src/views/login.tsx:45` | Toast logic copy-pasted across 3 views | Extract a `useToast` helper | M | | 🟢 | code-quality | `src/legacy/utils.ts:120` | Unused export `formatLegacyDate` | Delete the function and its imports | S | -## Top actions (ranked by impact) +## Top actions Highest impact first. Each action names the finding rows it resolves and, when a fix is wanted, the act-skill to hand off to (refactor, test, impeccable - the audit itself never edits code). diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md index 72003c6f..e258791a 100644 --- a/plugins/aidd-dev/skills/05-review/README.md +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -2,18 +2,17 @@ # 05 - review -Reviews completed work along two axes: code quality against project rules, -and feature behavior against the plan's acceptance criteria. Runs in a -fresh context via the `reviewer` agent and returns findings plus completion -and quality scores. Never edits the artifact. +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. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `review` step to this skill. -- A diff needs a rule-based code review without ad-hoc opinion. +- A diff needs a grounded review without ad-hoc opinion. ## When NOT to use @@ -28,37 +27,42 @@ and quality scores. Never edits the artifact. ## How to invoke ``` -Use skill aidd-dev:05-review +Use skill aidd-dev:05-review # all three axes +Use skill aidd-dev:05-review review-relevancy # one named axis ``` -The skill exposes 2 actions: +The skill exposes 3 axes, run together by default or one when named: -1. `review-code` - grade the diff against project rules; surface - violations with file, line, and rule reference. +1. `review-code` - grade the diff against clean-code principles; surface + violations with file and line. 2. `review-functional` - verify the feature against the plan's acceptance - criteria; emit per-criterion pass / fail. + criteria; per-criterion trace plus missing / unplanned / edge-case gaps. +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 -- A read-only report (never patches the code): - - `review-code` - a verdict (`approve` / `changes-requested` / `blocked`) - plus a findings table with 3-level severity (🔴 critical / 🟡 warning / - 🟢 minor), `file:line`, issue, and a suggested fix to hand off to - [07-refactor](../07-refactor/README.md). - - `review-functional` - a verdict (`PASS` / `PARTIAL` / `FAIL`) and a - per-criterion scoring matrix; missing or broken behaviors hand off to - [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). -- The `reviewer` agent still returns `ship` / `iterate` to the SDLC - orchestrator. +- 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`, + the strictest across the axes run), scope, axes run, findings count. + - `Code` section: severity-rated findings (🔴 / 🟡 / 🟢) with `file:line`; + fixes hand off to [07-refactor](../07-refactor/README.md). + - `Functional` section: per-criterion matrix plus the gap lists; fixes hand + off to [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). + - `Relevancy` section: misfits by lens (`fit` / `conform` / `rot`), each + tied to a rule, a duplication site, a smell, or a named need-gap. + - An axis not run is marked "Not run". ## Prerequisites - A diff or a set of changes to review. - A plan file with explicit acceptance criteria for the functional axis. -- Project rules loaded in context for the code axis. +- The project's declared rules, discovered at runtime, for the relevancy axis. ## Technical details -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two -review contracts. The skill runs the `reviewer` agent in fresh context to -avoid bias from the implementation conversation. +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/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 5de8c5f9..f2eb2820 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,36 +1,37 @@ --- name: 05-review -description: Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). +description: 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. +argument-hint: review-code | review-functional | review-relevancy model: opus -context: fork -agent: reviewer --- # Skill: review -Read-only review of a diff (a PR or working changes): code quality against project rules, and feature behavior against the plan's acceptance criteria. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. +Read-only review of a diff along three axes, code quality, feature behavior, and relevancy, composed into one report. -## Agent delegation - -Spawn the `reviewer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `reviewer` agent explicitly with this skill's content as the prompt. +## Actions -## Available actions +| # | Action | Axis | +| --- | ------------------- | ---------------------------------------------------------------- | +| 01 | `review-code` | Clean-code quality on the changed lines | +| 02 | `review-functional` | The diff against the plan's acceptance criteria | +| 03 | `review-relevancy` | Does the change belong: fit to the need, rule conformance, no rot | -| # | Action | When to use | -| --- | ------------------- | ------------------------------------------------------------------------ | -| 01 | `review-code` | Quality review of a diff against project rules and clean-code principles | -| 02 | `review-functional` | Verify the diff matches the plan's acceptance criteria, flows, edge cases | +Run all three by default, composing one report. Run a single axis only when the caller names it; if it is unclear whether they want all or one, ask. -## Routing (run first) +## Transversal rules -Pick the ONE action matching the user's intent; do NOT default to action 01. +- Read-only: surface each finding with its fix described, never patch. +- Output: always write `review.md` to disk; the file is the deliverable, never an inline-only verdict. +- Folder: write into the reviewed work's feature folder (`aidd_docs/tasks//_/`, beside `plan.md`), or one resolved from the change when it has none. +- Sections: fill `review.md` from `assets/review-template.md`, each axis its own section, an unrun axis marked "Not run". +- Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. +- Verdict: one overall verdict, the strictest across the axes run, per `references/review-rubric.md`. -- "review the code", "check code quality", "rules compliance", "clean code review" -> `01-review-code` -- "does it match the plan", "functional review", "behavior vs acceptance criteria" -> `02-review-functional` +## References -If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. +- `references/review-rubric.md`: the severity scale, the verdict rule, the code categories, and the relevancy lenses. -## Actions +## Assets -- `@actions/01-review-code.md` -- `@actions/02-review-functional.md` +- `assets/review-template.md`: the single report the three axes fill. diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 63978f69..b4154a51 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -1,34 +1,23 @@ # 01 - Review Code -Deep code review of a diff against project rules and clean-code principles. Read-only: surface quality violations only, never patch them - hand fixes off to `aidd-dev:07-refactor`. +Grade the diff against clean-code principles and record the findings in the review report. -## Inputs +## Input -```yaml -scope: # optional; defaults to `git diff main` -``` +The diff to review, a git ref range or path, from the arguments; defaults to the diff against the repository default branch. -## Outputs +## Output -```yaml -review_path: aidd_docs/tasks//-.review.md -verdict: approve | changes-requested | blocked -findings_count: -severity_breakdown: - critical: # 🔴 - warning: # 🟡 - minor: # 🟢 -``` +The `Code` section of the feature folder's `review.md`, filled with severity-rated findings, each citing a changed `file:line`. ## Process -1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. -2. **Deep review every changed line.** Apply project conventions and global clean-code principles. No runtime checks. -3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). -4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. -6. **Write to disk** at `aidd_docs/tasks//-.review.md`. Create the month directory when missing. +1. **Resolve.** Take the diff from the arguments, otherwise the diff against the repository default branch. +2. **Review.** Read every changed line for clean-code: naming, structure, complexity, smells, error handling. No runtime checks. Declared-rule conformance belongs to the relevancy axis, not this one. +3. **Rate.** One finding per issue on the changed lines, rated and categorized per `@../references/review-rubric.md`, citing a `file:line`. +4. **Record.** Write the findings into the `Code` section of `review.md`, each with its fix described. ## Test -The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. +- The `Code` section of `review.md` is filled, every finding rated and citing a changed `file:line`. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 8e3c9b9d..253a9308 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -1,45 +1,24 @@ # 02 - Review Functional -Verify the implemented feature matches the plan's acceptance criteria, flows, and edge cases. Static review of the current diff against plan intent. No app execution, no browser, no code-quality checks. Read-only: surface gaps, never patch them - hand a missing behavior off to `aidd-dev:02-implement`, a broken one to `aidd-dev:08-debug`. +Verify the diff matches the plan's acceptance criteria, flows, and edge cases, and record the result in the review report. -## Inputs +## Input -```yaml -plan_path: # required via $ARGUMENTS or prompt -diff_scope: # optional; defaults to `git diff main` -``` +The plan path holding the acceptance criteria, from the arguments or the prompt, and the diff to trace (a git ref range; defaults to the diff against the repository default branch). -## Outputs - -```yaml -review_path: aidd_docs/tasks//-.review_functional.md -criteria_total: -criteria_traced: -missing_behaviors: -unplanned_behaviors: -edge_case_gaps: -``` - -## Rules - -Check against: - -- Inconsistencies -- Duplications -- Non logical Flows or Steps +## Output +The `Functional` section of the feature folder's `review.md`: one row per acceptance criterion traced to the diff, plus the missing, unplanned, and edge-case gaps. ## Process -1. **Read the plan.** Use `plan_path` from `$ARGUMENTS` when provided; otherwise ask the user to supply the acceptance criteria directly. -2. **Extract acceptance criteria.** If they exist in the plan, ask the user to validate them before proceeding. If missing, ask the user to provide them. -3. **Fetch the diff.** Use `diff_scope` when provided; otherwise `git diff main`. -4. **Trace each criterion to the diff.** Fill the scoring matrix with one row per acceptance criterion. -5. **List missing behaviors** (criteria with no trace in the diff). -6. **List unplanned behaviors** (diff changes that trace to no criterion). -7. **List flow and edge-case gaps** surfaced by walking through each criterion. -8. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//-.review_functional.md`. Create the month directory when missing. +1. **Read.** Take the plan from the arguments; if absent, ask for the acceptance criteria, and mark this axis "Not run" when none are available. Static review only, no app execution or browser. +2. **Trace.** Fetch the diff, then trace each acceptance criterion to it, one matrix row per criterion: met, partial, or unmet, with evidence or the gap. +3. **Gaps.** List missing behaviors (criteria with no trace), unplanned behaviors (diff changes tracing to no criterion), and flow or edge-case gaps. An empty list reads "none", never omitted. +4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`, each with the missing or broken behavior named. ## Test -The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). +- The `Functional` section of `review.md` holds exactly one row per acceptance criterion. +- The missing, unplanned, and edge-case lists are present, each reading "none" when empty. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md new file mode 100644 index 00000000..34b37b5f --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md @@ -0,0 +1,24 @@ +# 03 - Review Relevancy + +Judge whether the diff belongs, coherent with the codebase, its conventions and declared rules, serving the real need, with nothing duplicated or over-built, and record the misfits in the review report. + +## Input + +The diff to review (a git ref range or path; defaults to the diff against the repository default branch), the need it serves (the plan objective or the ticket), and the project's declared rules and conventions, discovered at runtime. + +## Output + +The `Relevancy` section of the feature folder's `review.md`, filled with misfit findings under the lenses `fit`, `conform`, and `rot`, each tied to evidence. + +## Process + +1. **Gather.** Resolve the diff from the arguments, otherwise the diff against the repository default branch. Capture the need from the plan objective or the ticket. Discover the project's declared rules and conventions at runtime, never hardcoded. Fall back cleanly when a source is absent. +2. **Fit.** Check the change against the need: does it serve the actual intent end to end, or only the literal criteria? Flag any drift between intent and result. +3. **Conform.** Check the change against the declared rules and the surrounding conventions. Flag each violation with the rule or pattern it breaks. +4. **Rot.** Scan for duplication (an existing helper reinvented), over-engineering (speculative generality, unused abstraction), and incoherence (naming, docs versus code). Cite the site. +5. **Record.** Write each finding into the `Relevancy` section of `review.md`, rated and placed under its lens per `@../references/review-rubric.md`. A bare opinion is not a finding: tie each to a declared rule, a duplication site, an over-engineering smell, or a named need-gap. + +## Test + +- The `Relevancy` section of `review.md` is filled, every finding under a lens and tied to a `file:line`, a declared rule, a duplication site, or a named need-gap. +- No finding is a bare opinion, and no code is patched. diff --git a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md deleted file mode 100644 index 2fbff291..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: review-code -description: Code review report template for a diff -argument-hint: N/A ---- - -# Code Review: {{feature}} - -{{one_line_summary}} - -- **Verdict**: {{approve | changes-requested | blocked}} -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} -- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor - -Verdict: `approve` = no critical findings, ship it; `changes-requested` = warnings or a fixable critical to address first; `blocked` = a critical that must not merge. - -## Expected changes - -What the diff was meant to deliver (from the ticket or plan). Tick what the diff actually does. - -- [ ] {{expected_change_1}} -- [ ] {{expected_change_2}} - -## Findings - -One row per issue, on the CHANGED lines only (this is a diff review, not a codebase audit). Every row cites a `file:line`. Sort by severity. Read-only: describe the fix, do not patch it - hand fixes off to `aidd-dev:07-refactor`. - -Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. - -| Sev | Category | Location | Issue | Suggested fix | -| --- | ----------- | --------------------- | ------------------------------------ | ------------------------------------ | -| 🔴 | security | `src/api/user.ts:30` | Request body used without validation | Validate with the project schema lib | -| 🟡 | code-health | `LivePreview.tsx:43` | `user` recomputed on every render | Memoize with `useMemo` | - -## Coverage - -Dimensions examined on the diff (a dimension with no finding is still listed here as scanned; one not applicable to this diff is marked n/a). - -- **Scanned**: {{dimensions examined, comma-separated}} -- **Not applicable**: {{dimensions n/a for this diff, or "none"}} - -## Follow-up - -- **Top fixes** (ranked, hand off to `aidd-dev:07-refactor`): {{top_fixes}} -- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md deleted file mode 100644 index 9de9d828..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: review-functional -description: Functional review report template for a diff against a plan -argument-hint: N/A ---- - -# Functional Review: {{feature}} - -- **Plan**: `{{plan_path}}` -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} - -## Verdict - -{{PASS | PARTIAL | FAIL}} - {{one_line_rationale}} - -Verdict: `PASS` = every criterion Met; `PARTIAL` = some criteria Partial or Unmet but none blocking; `FAIL` = at least one 🔴 blocking gap. - -## Scoring Matrix - -One row per acceptance criterion. Severity uses the shared 3-level scale (it applies to `Partial` / `Unmet` rows only). - -| Criterion | Files | Status | Severity | Notes | -| ---------------- | ----- | --------------------- | --------------------------------- | ----- | -| {{criterion}} | | Met / Partial / Unmet | 🔴 blocker / 🟡 major / 🟢 minor | | - -- Status - `Met`: fully implemented in the diff; `Partial`: implemented with gaps; `Unmet`: absent from the diff. -- Severity - 🔴 blocker: feature cannot ship; 🟡 major: shipping degrades UX; 🟢 minor: cosmetic or non-blocking. - -## Missing behaviors - -Acceptance criteria with no trace in the diff (hand off implementation to `aidd-dev:02-implement`; if a criterion is implemented but broken, hand off to `aidd-dev:08-debug`). - -- [ ] {{criterion not found in diff}} - -## Unplanned behaviors - -Changes present in the diff but traced to no acceptance criterion. - -- [ ] {{unplanned change - confirm scope with author}} - -## Flow / edge-case gaps - -Gaps surfaced while walking each criterion against the diff. - -- [ ] {{flow or edge-case gap}} - -## Summary - -- **Criteria covered**: {{x/y}} -- **Blockers**: {{count}} -- **Follow-up actions**: {{actions}} -- **Additional notes**: {{notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-template.md b/plugins/aidd-dev/skills/05-review/assets/review-template.md new file mode 100644 index 00000000..8c6df3ad --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/assets/review-template.md @@ -0,0 +1,43 @@ + + +# Review: {{feature}} + +{{one_line_summary}} + +- **Verdict**: {{approve | changes-requested | blocked}} +- **Diff scope**: `{{base}}...{{head}}` +- **Axes run**: {{code, functional, relevancy}} +- **Date**: {{yyyy_mm_dd}} +- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor + +Verdict: `approve` = ship it; `changes-requested` = fix the warnings or fixable criticals first; `blocked` = a critical that must not merge. The overall verdict is the strictest across the axes run. + +## Code + +Clean-code findings on the changed lines (or "Not run"). + +| Sev | Category | Location | Issue | Suggested fix | +| --- | -------- | -------- | ----- | ------------- | + +## Functional + +Each acceptance criterion traced to the diff (or "Not run"). + +| Criterion | Met | Evidence / gap | +| --------- | --- | -------------- | + +- **Missing behaviors**: {{criteria with no trace, or "none"}} +- **Unplanned behaviors**: {{diff changes tracing to no criterion, or "none"}} +- **Edge-case gaps**: {{gaps, or "none"}} + +## Relevancy + +Does the change belong (or "Not run"). Every finding ties to evidence, never an opinion. + +| Sev | Lens | Location / rule | Misfit | Suggested fix | +| --- | ---- | --------------- | ------ | ------------- | + +## Follow-up + +- **Top fixes** (ranked): {{top_fixes}} +- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/references/review-rubric.md b/plugins/aidd-dev/skills/05-review/references/review-rubric.md new file mode 100644 index 00000000..759ee612 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/references/review-rubric.md @@ -0,0 +1,27 @@ +# Review rubric + +Shared definitions for the three review axes. The actions and the report template draw from here, so the scales live in one place. + +## Severity + +- 🔴 critical: must not merge as-is. +- 🟡 warning: should fix. +- 🟢 minor: nit. + +## Verdict + +One overall verdict, the strictest across the axes run: + +- `approve`: no critical finding, ship it. +- `changes-requested`: warnings, or a fixable critical to address first. +- `blocked`: a critical that must not merge. + +## Code categories + +`standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. + +## Relevancy lenses + +- `fit`: serves the real need, not only the literal criteria. +- `conform`: the project's declared rules and the surrounding conventions. +- `rot`: duplication, over-engineering, incoherence (naming, docs versus code). diff --git a/plugins/aidd-dev/skills/06-test/SKILL.md b/plugins/aidd-dev/skills/06-test/SKILL.md index aa1e8bd8..a03b8470 100644 --- a/plugins/aidd-dev/skills/06-test/SKILL.md +++ b/plugins/aidd-dev/skills/06-test/SKILL.md @@ -1,30 +1,25 @@ --- name: 06-test -description: Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. +description: 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. +argument-hint: test | test-journey model: sonnet --- # Skill: test -Identifies untested behaviors, iterates on test creation until quality criteria are met, and validates complete user journeys through browser automation. +Find untested behavior and iterate tests until they pass, or drive a full user journey through the browser and check each step. -## Available actions - -| # | Action | When to use | -| --- | -------------- | ---------------------------------------------------------------------- | -| 01 | `test` | Find untested behaviors and write/iterate tests until they pass | -| 02 | `test-journey` | Validate a full user journey end-to-end in the browser | - -## Routing (run first) - -Pick the ONE action matching the user's intent; do NOT default to action 01. +## Actions -- "write tests", "add test coverage", "what's untested", "iterate on tests" -> `01-test` -- "test the user journey", "end-to-end", "walk through the flow in the browser" -> `02-test-journey` +| # | Action | When to use | +| --- | -------------- | -------------------------------------------------------------- | +| 01 | `test` | Find untested behaviors and write or iterate tests until they pass | +| 02 | `test-journey` | Validate a full user journey end-to-end in the browser | -If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. +Pick the one action matching the intent; never default to `01`. Triggers like "write tests" or "what's untested" route to `01`, "test the user journey" or "end-to-end" to `02`. Ask one question when the intent is ambiguous. -## Actions +## Transversal rules -- `@actions/01-test.md` -- `@actions/02-test-journey.md` +- One action per run: follow only the matching action file. +- Functional behavior only: never couple a test to implementation details. +- Never compromise quality for speed. diff --git a/plugins/aidd-dev/skills/06-test/actions/01-test.md b/plugins/aidd-dev/skills/06-test/actions/01-test.md index 4c9fa572..a289c330 100644 --- a/plugins/aidd-dev/skills/06-test/actions/01-test.md +++ b/plugins/aidd-dev/skills/06-test/actions/01-test.md @@ -1,38 +1,24 @@ # 01 - Test -Identify untested behaviors in the feature, then create and iterate on tests until they pass with modern testing best practices. +Identify untested behaviors in the target, then write and iterate tests until they pass with modern testing practices. -## Inputs +## Input -```yaml -scope: # passed via $ARGUMENTS -``` +The scope to cover, a feature, module, or file glob, from the arguments. -## Outputs +## Output -```yaml -behaviors_listed: -tests_added: -tests_passing: -report: - - { behavior: , status: pass, file: } - - { behavior: , status: pending, reason: } -``` +The behaviors found and, per behavior, a passing test with its file path, or a `pending` entry with a one-line reason when deliberately skipped. ## Process -1. **List untested behaviors** in the target area: - - Think about behaviors based on existing ones. - - Score each from 0 (not needed) to 5 (critical core flow). - - Group by distinct sections. - - Prioritize by score and impact. - - Display as an organized minimal bullet list. -2. **Wait for user approval** before generating any test. -3. **Generate the initial test** for the highest-priority behavior, applying current testing best practices and project conventions. -4. **Run, observe, iterate.** If the test fails, analyze the failure, improve the test, repeat. If it passes, validate against the quality checklist; improve if quality is insufficient. -5. **Move to the next behavior** and repeat from step 3 until the list is exhausted. -6. **Boundaries.** Focus on ONE test at a time. Never compromise quality for speed. Functional aspects only; ignore implementation details. +1. **List.** Enumerate the untested behaviors in the target area. Reason from the existing ones, score each from 0 (not needed) to 5 (critical core flow), group by section, prioritize by score and impact, and show a minimal bullet list. +2. **Approve.** Wait for user approval before generating any test. A behavior the user declines becomes a `pending` entry with a one-line reason, not tested. +3. **Generate.** Write the initial test for the highest-priority behavior, applying current testing practices and project conventions. +4. **Iterate.** Run the test. On failure, analyze it, improve the test, and repeat. On pass, check it against the quality criteria and improve when it falls short. +5. **Next.** Move to the next behavior and repeat from Generate until the list is exhausted. ## Test -For every behavior in the approved list: a corresponding test exists in the project test suite, the test passes, and the report records the test file path. Behaviors that are deliberately skipped have a `pending` entry with a one-line reason. +- Every behavior in the approved list has a corresponding test in the project suite that passes, with its file path recorded. +- Each deliberately skipped behavior has a `pending` entry with a one-line reason. diff --git a/plugins/aidd-dev/skills/06-test/actions/02-test-journey.md b/plugins/aidd-dev/skills/06-test/actions/02-test-journey.md index 21e6caa6..ac818cf0 100644 --- a/plugins/aidd-dev/skills/06-test/actions/02-test-journey.md +++ b/plugins/aidd-dev/skills/06-test/actions/02-test-journey.md @@ -1,38 +1,24 @@ # 02 - Test Journey -Test a user journey end-to-end and validate that each step produces the expected behavior. +Drive a user journey end-to-end and check that each step produces the expected behavior. -## Inputs +## Input -```yaml -journey: -url: -``` +The journey, an ordered list of action plus expected outcome, and the entry URL, from the arguments. -## Outputs +## Output -```yaml -steps_total: -steps_passed: -steps_failed: -report: - - { step: , action: , expected: , actual: , status: pass|fail, screenshot: } -``` +A per-step report, each step recording its action, expected and actual result, a pass or fail, and a screenshot path, with a downstream-impact note on any failure. ## Process -Spawn a sub-agent task to: - -1. **Parse the journey** into ordered steps. Each step has an action and an expected result. -2. **Open the URL** with the project's configured browsing tool. Assume all servers are already running. -3. **For each step**: - - Execute the action (click, fill, navigate, drag, etc.). - - Take a screenshot immediately after. - - Validate actual vs expected. - - Record `{ step, action, expected, actual, pass | fail, screenshot path }`. -4. **On failure**: document the failure with the screenshot, warn the user, attempt to continue when downstream steps are still meaningful, and note any steps invalidated by the failure. -5. **Compile the journey report** at the end. Report actual behavior even when it differs from expected; do not silently fix or skip. +1. **Parse.** Break the journey into ordered steps, each an action and an expected result. +2. **Open.** Open the URL with the project's configured browsing tool. Assume every server is already running. +3. **Walk.** For each step: execute the action (click, fill, navigate, drag), screenshot immediately after, validate actual against expected, and record. + - On a failed step: document it with the screenshot, warn the user, continue when downstream steps stay meaningful, and note any steps it invalidates. +4. **Compile.** Assemble the journey report. Report actual behavior even when it differs from expected, never silently fix or skip. ## Test -The report contains one entry per parsed step, every step has a screenshot path, and at least one of `pass` or `fail` is recorded for every step. If any step failed, the report includes a downstream-impact note for the affected steps. +- The report has one entry per parsed step, each recording its action, expected and actual result, a screenshot path, and a pass or fail. +- A failed step carries a downstream-impact note for the steps it affects. diff --git a/plugins/aidd-dev/skills/07-refactor/README.md b/plugins/aidd-dev/skills/07-refactor/README.md index cedcd2da..acb06dd9 100644 --- a/plugins/aidd-dev/skills/07-refactor/README.md +++ b/plugins/aidd-dev/skills/07-refactor/README.md @@ -21,8 +21,7 @@ reports, refactor fixes. - 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). UI redesign → - the impeccable skill. +- You want to add tests → [06-test](../06-test/README.md). ## How to invoke diff --git a/plugins/aidd-dev/skills/07-refactor/SKILL.md b/plugins/aidd-dev/skills/07-refactor/SKILL.md index a0a88431..2ac6af7b 100644 --- a/plugins/aidd-dev/skills/07-refactor/SKILL.md +++ b/plugins/aidd-dev/skills/07-refactor/SKILL.md @@ -1,47 +1,28 @@ --- name: 07-refactor -description: Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill). +description: 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. +argument-hint: performance | security | cleanup | architecture --- # Skill: refactor -The act-side of code improvement: it changes code to make it better. Behavior-preserving for cleanup, performance, and architecture; security may change behavior on purpose to close a hole. The read-only diagnosis counterpart is `aidd-dev:04-audit` - refactor fixes, audit reports. +The act-side of code improvement: it changes code to make it better. Behavior-preserving for cleanup, performance, and architecture; security may change behavior on purpose to close a hole. -## Available actions - -| # | Action | Axis | Maps to audit pillar | Lens | -| --- | ------------- | ------------ | -------------------- | -------------------------------------------------------------- | -| 01 | `performance` | performance | performance | N+1, hot paths, batching, memoization, unnecessary I/O | -| 02 | `security` | security | security | OWASP, input validation, authz, secrets - harden and fix | -| 03 | `cleanup` | code-quality | code-quality | clean-code: rename, extract, DRY, dead-code, complexity | -| 04 | `architecture`| architecture | architecture | extract layers, fix coupling, enforce boundaries | - -## Routing (run first) - -This skill is run-one-OR-run-all: - -- The user named an axis ("optimize this", "harden", "clean up", "restructure") -> run that ONE action. -- Unscoped ("refactor this", "improve the code") -> ask ONE question: "all applicable axes, or a specific one (cleanup / performance / security / architecture)?" Then run the chosen one, or all applicable. -- Never silently default to action 01. - -## Audit handoff (push, never pull) - -This skill NEVER loads or invokes the audit skill - that would make refactor depend on audit and break standalone use. Each action has two modes: - -- **Standalone (default).** The action scans its axis with its own lens, then fixes. Self-contained; this is the existing behavior. -- **Audit-fed (optional).** If the caller PUSHES an `audit_report` (a path to a report under `aidd_docs/tasks/audits/`, or pasted findings), the action takes that report's findings for its axis as the fix list and skips its own scan. - -The bridge is the report artifact (data), not a cross-skill reference. For a broad read-only diagnosis before fixing, the user may run `aidd-dev:04-audit` first and push its report in - a suggestion, never a dependency. +## Actions -## Conventions +| # | Action | Axis | Lens | +| --- | -------------- | ------------ | ---------------------------------------------------------- | +| 01 | `performance` | performance | N+1, hot paths, batching, memoization, unnecessary I/O | +| 02 | `security` | security | OWASP, input validation, authz, secrets: harden and fix | +| 03 | `cleanup` | code-quality | clean code: rename, extract, DRY, dead code, complexity | +| 04 | `architecture` | architecture | extract layers, fix coupling, enforce boundaries | -- Severity on any finding uses the shared 3-level scale: 🔴 critical, 🟡 warning, 🟢 minor (aligned with audit, so a pushed audit report flows in without translation). -- Behavior-preserving for cleanup, performance, and architecture: public inputs and outputs stay identical; verify via tests, type checks, or a side-by-side run. Security may alter behavior to close a vulnerability - call that out explicitly. -- Stay inside the axis. Boundaries mirror audit: dependency upgrades (CVE bumps, version maintenance) are out of scope here; test creation belongs to `aidd-dev:06-test`; UI redesign to the impeccable skill. +Run the one axis named, or offer all applicable when the request is unscoped. -## Actions +## Transversal rules -- `@actions/01-performance.md` -- `@actions/02-security.md` -- `@actions/03-cleanup.md` -- `@actions/04-architecture.md` +- Scope: run the one named axis, or for an unscoped request ask once "all applicable axes, or one?" before running. A request to delete or remove code runs `cleanup` directly, with no axis question. Never silently default to one axis. +- Behavior-preserving for cleanup, performance, and architecture: public inputs and outputs stay identical, verified by tests, type checks, or a side-by-side run. Security may alter behavior to close a vulnerability, and must call that out explicitly. +- Audit-fed, optional: when the caller pushes an audit report (a path under `aidd_docs/tasks/audits/` or pasted findings), take its findings for this axis as the fix list and skip the scan. The bridge is the report artifact; this skill never loads or calls another skill. The audit `code-quality` pillar feeds the `cleanup` axis; the other axes map by name. +- Severity uses the shared 3-level scale: 🔴 critical, 🟡 warning, 🟢 minor. +- Stay inside the axis: dependency upgrades and UI redesign are out of scope. Add tests only as a regression for a security fix, never otherwise. diff --git a/plugins/aidd-dev/skills/07-refactor/actions/01-performance.md b/plugins/aidd-dev/skills/07-refactor/actions/01-performance.md index e849f4d8..8e725df0 100644 --- a/plugins/aidd-dev/skills/07-refactor/actions/01-performance.md +++ b/plugins/aidd-dev/skills/07-refactor/actions/01-performance.md @@ -2,40 +2,24 @@ Improve the performance of a selected code region without changing its observable behavior. -## Inputs - -```yaml -selection: -audit_report: -constraints: - - keep input and output identical - - keep code readable and maintainable -``` - -## Outputs - -```yaml -hotspots_found: -changes_applied: - - { file: , change: , severity: "🔴|🟡|🟢", gain: } -followups: - - - - - - -``` +## Input -## Process +The code region to optimize, a file path or inline snippet. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings. + +## Output -1. **Source findings.** Two modes: - - If `audit_report` is provided: extract the performance-axis findings from that report and use them as the fix list. Skip the standalone scan below. - - Else (standalone): scan the selection for the main performance issues (allocations, redundant work, blocking calls, N+1 patterns, unnecessary I/O). Rate each hotspot with the 3-level severity scale: 🔴 critical, 🟡 warning, 🟢 minor. -2. **List necessary steps** to address each hotspot, ordered by expected gain. -3. **Apply changes.** Refactor the selected region. Preserve readability and maintainability; do not change logic; keep inputs and outputs identical. -4. **Verify equivalence.** Confirm behavior is unchanged via tests, type checks, or a side-by-side run. -5. **Propose three follow-up optimizations** not yet applied, sorted by importance. +The hotspots addressed and the changes applied (file, one-line summary, severity, gain), plus three follow-up optimizations not yet applied. + +## Process -Boundary note: test creation belongs to the test skill; dependency upgrades and UI redesign are out of scope for this action. +1. **Source.** When an audit report is pushed, take its performance-axis findings as the fix list and skip the scan. Otherwise scan the selection for the main performance issues (allocations, redundant work, blocking calls, N+1 patterns, unnecessary I/O) and rate each with the shared severity scale. +2. **Order.** List the steps to address each hotspot, ordered by expected gain. +3. **Apply.** Refactor the selected region. Preserve readability and logic, keep inputs and outputs identical. +4. **Verify.** Confirm behavior is unchanged via tests, type checks, or a side-by-side run. +5. **Followup.** Propose three follow-up optimizations not yet applied, sorted by importance. ## Test -Existing tests on the selection still pass; the public inputs and outputs of the refactored code are byte-identical to the pre-change version on representative inputs; the follow-up list contains exactly three actionable items. +- Existing tests on the selection still pass. +- The refactored code's public inputs and outputs are identical to the pre-change version on representative inputs. +- The follow-up list contains exactly three actionable items. diff --git a/plugins/aidd-dev/skills/07-refactor/actions/02-security.md b/plugins/aidd-dev/skills/07-refactor/actions/02-security.md index a4d1f2c8..bf281d80 100644 --- a/plugins/aidd-dev/skills/07-refactor/actions/02-security.md +++ b/plugins/aidd-dev/skills/07-refactor/actions/02-security.md @@ -1,42 +1,27 @@ # 02 - Security -Identify and fix security vulnerabilities, then strengthen the codebase by adding test coverage and documentation for the fixes. Security may change observable behavior to close a vulnerability - this is expected and must be called out explicitly. +Find and fix security vulnerabilities, then add test coverage and documentation for the fixes. A security fix may change observable behavior to close a hole, which must be called out explicitly. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -audit_report: -focus_areas: - - input_validation - - authentication_authorization - - injection - - secrets_handling -``` +An optional scope, a directory or file glob, defaulting to the entire codebase. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings. -## Outputs +## Output -```yaml -findings: - - { id: , file: , severity: "🔴 critical | 🟡 warning | 🟢 minor", summary: } -fixes_applied: - - { id: , file: , change: , behavior_change: , test_added: true|false } -``` +The vulnerabilities found and the fixes applied (file, one-line summary, whether behavior changed, whether a test was added). ## Process -1. **Source findings.** Two modes: - - If `audit_report` is provided: extract the security-axis findings from that report and use them as the fix list. Skip steps 2-4 below. - - Else (standalone): scan the scope for vulnerabilities using static analysis where available and a manual pass against OWASP Top 10. Continue with steps 2-4. -2. **Check input validation** at every external boundary (HTTP handlers, CLI args, file parsers, IPC). -3. **Review authentication and authorization** paths; flag missing checks and broken role propagation. -4. **Identify injection risks** (SQL, command, template, XSS, SSRF). -5. **Apply fixes**, preferring secure functions, least privilege, and parameterized APIs over ad-hoc sanitization. If a fix changes observable behavior, set `behavior_change: true` and explain the change inline. -6. **Add security test coverage** for each fix (regression unit or integration tests). -7. **Document the security measures** added or changed (inline doc strings, ADRs, or `aidd_docs/memory/` entries) so they are not regressed by future refactors. - -Note: CVE dependency upgrades and version maintenance are out of scope for this action; they belong to dependency maintenance (a separate audit pillar). Route those findings there. +1. **Source.** When an audit report is pushed, take its security-axis findings as the fix list and skip to Apply. Otherwise scan the scope with static analysis where available and a manual pass against the OWASP Top 10. +2. **Inputs.** Check input validation at every external boundary (HTTP handlers, CLI args, file parsers, IPC). +3. **Access.** Review authentication and authorization paths, flagging missing checks and broken role propagation. +4. **Injection.** Identify injection risks (SQL, command, template, XSS, SSRF). +5. **Apply.** Fix with secure functions, least privilege, and parameterized APIs over ad-hoc sanitization. When a fix changes observable behavior, mark it and explain the change inline. +6. **Cover.** Add a regression test, unit or integration, for each fix. +7. **Document.** Record the security measures added or changed (doc strings, ADRs, or `aidd_docs/memory/` entries) so a later refactor does not regress them. ## Test -Every entry in `findings` has a matching entry in `fixes_applied` or a documented reason for deferral; every entry in `fixes_applied` with `test_added: true` has a regression test that fails on the pre-fix code; the project's security linter (when configured) exits zero on the changed scope. +- Every finding has a matching fix or a documented reason for deferral. +- Each fix with a test added has a regression test that fails on the pre-fix code. +- The project's security linter, when configured, exits zero on the changed scope. diff --git a/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md b/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md index 8a1997e7..bb11c189 100644 --- a/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md +++ b/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md @@ -1,47 +1,35 @@ # 03 - Cleanup -Improve code quality and reduce technical debt by applying clean-code principles and removing structural rot - without changing observable behavior. +Improve code quality and reduce technical debt by applying clean-code principles and removing structural rot, without changing observable behavior. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -audit_report: -constraints: - - keep public inputs and outputs identical - - preserve existing test coverage -``` +An optional scope, a directory or file glob, defaulting to the entire codebase. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings. -## Outputs +## Output -```yaml -changes_applied: - - { file: , change: , severity: "🔴|🟡|🟢", category: } -verification: -``` +The changes applied (file, one-line summary, severity, clean-code or tech-debt), with a verification summary confirming no behavioral regression. ## Process -1. **Source findings.** Two modes: - - If `audit_report` is provided: extract the code-quality-axis findings from that report and use them as the fix list. Skip the standalone scan below. - - Else (standalone): scan the scope with the cleanup lens below. Rate each issue with the 3-level severity scale: 🔴 critical, 🟡 warning, 🟢 minor. -2. **Apply clean-code fixes** from the finding list: +1. **Source.** When an audit report is pushed, take its code-quality-axis findings as the fix list and skip the scan. Otherwise scan the scope with the cleanup lens and rate each issue with the shared severity scale. +2. **Clean.** Apply the clean-code fixes from the list: - Rename symbols for clarity (misleading names, abbreviations, single-letter variables outside tight loops). - Extract functions or modules where a block does more than one thing. - - Deduplicate repeated logic (DRY). + - Deduplicate repeated logic. - Raise abstraction to replace low-level mechanics with intention-revealing calls. - Replace magic numbers and inline strings with named constants. - - Remove dead, misleading, or out-of-date comments; add a brief comment only where intent is genuinely non-obvious. -3. **Apply tech-debt fixes** from the finding list: - - Delete dead code and unused exports. - - Reduce cyclomatic complexity by extracting early returns, guard clauses, and helper functions. + - Remove dead, misleading, or out-of-date comments, adding one only where intent is genuinely non-obvious. +3. **Debt.** Apply the tech-debt fixes from the list: + - Delete dead code and unused exports, sweeping for the orphaned references a deletion leaves behind. + - Reduce cyclomatic complexity with early returns, guard clauses, and helper functions. - Shorten oversized files and functions to a single responsibility. - Flatten excessive nesting. - - Fix error handling caught at the wrong boundary (swallowed errors, wrong abstraction level). -4. **Verify behavior is preserved.** Run tests and type checks; confirm public inputs and outputs are identical to pre-change. - -Boundary note: test creation belongs to the test skill; dependency upgrades and UI redesign are out of scope for this action. + - Fix error handling caught at the wrong boundary. +4. **Verify.** Run tests and type checks, confirming public inputs and outputs are identical to pre-change. ## Test -All existing tests pass after changes; type checks exit zero; no public API surface has changed; each entry in `changes_applied` maps to a concrete line-level edit in the diff. +- All existing tests pass and type checks exit zero. +- No public API surface has changed. +- Each change applied maps to a concrete line-level edit in the diff. diff --git a/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md b/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md index 44358ad0..2db707f1 100644 --- a/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md +++ b/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md @@ -1,44 +1,31 @@ # 04 - Architecture -Enforce documented boundaries, fix wrong-direction dependencies, and decouple structural problems - in small, verifiable steps that preserve observable behavior where possible. +Enforce documented boundaries, fix wrong-direction dependencies, and decouple structural problems, in small verifiable steps that preserve observable behavior where possible. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire codebase -audit_report: -constraints: - - keep public inputs and outputs identical where structurally possible - - proceed in small verified steps -``` +An optional scope, a directory or file glob, defaulting to the entire codebase. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings. -## Outputs +## Output -```yaml -changes_applied: - - { file: , change: , severity: "🔴|🟡|🟢" } -verification: -deferred_to_plan: - - -``` +The changes applied (file, one-line summary, severity), a verification summary, and a deferred list of structural moves too large to execute atomically, each flagged as needing a plan first. ## Process -1. **Source findings.** Two modes: - - If `audit_report` is provided: extract the architecture-axis findings from that report and use them as the fix list. Skip the standalone scan below. - - Else (standalone): scan the scope against documented boundaries (C4 diagrams or ADRs in `aidd_docs/memory/`). Identify wrong-direction dependencies, god-modules, missing layer abstractions, and violated isolation contracts. Rate each issue with the 3-level severity scale: 🔴 critical, 🟡 warning, 🟢 minor. -2. **Triage findings.** Separate changes that are safe to apply atomically now from those that require broad coordinated moves. Place the latter in `deferred_to_plan`. -3. **Apply changes** in small, independently verifiable steps: +1. **Source.** When an audit report is pushed, take its architecture findings as the fix list and skip the scan. Otherwise scan against the documented boundaries (C4 diagrams, ADRs in `aidd_docs/memory/`) for wrong-direction dependencies, god-modules, missing layers, and broken isolation, rating each with the shared severity scale. +2. **Triage.** Separate changes safe to apply atomically now from those needing broad coordinated moves. Defer the latter, flagged as needing a plan first. +3. **Apply.** Make the safe changes in small, independently verifiable steps: - Extract or restore layers (separate domain, infrastructure, and presentation concerns). - - Fix wrong-direction dependency arrows (introduce an interface or inversion point; do not let infrastructure reach into domain). + - Fix wrong-direction dependencies by introducing an interface or inversion point, never letting infrastructure reach into the domain. - Decouple god-modules by splitting responsibilities along natural seams. - Enforce documented boundaries by moving code, adjusting exports, and updating internal references. -4. **Verify after each step.** Run tests and type checks; confirm the import graph still respects documented boundaries; confirm public inputs and outputs are unchanged. +4. **Verify.** After each step run tests and type checks, confirm the import graph still respects documented boundaries, and confirm public inputs and outputs are unchanged. -CAUTION: a large architectural change often needs a plan before code moves. If `deferred_to_plan` is non-empty, recommend running the planning skill before proceeding with those items. - -Boundary note: dependency upgrades, test creation, and UI redesign are out of scope for this action. +When the deferred list is non-empty, recommend planning those structural moves before any code moves. ## Test -All existing tests pass after each applied step; type checks exit zero; the import graph has no new boundary violations; each entry in `changes_applied` maps to a concrete edit in the diff; `deferred_to_plan` is populated for any structural move not safe to execute atomically. +- All existing tests pass after each applied step and type checks exit zero. +- The import graph has no new boundary violations. +- Each change applied maps to a concrete edit in the diff. +- Any structural move not safe to execute atomically is in the deferred list. diff --git a/plugins/aidd-dev/skills/08-debug/SKILL.md b/plugins/aidd-dev/skills/08-debug/SKILL.md index f809908c..e74d6591 100644 --- a/plugins/aidd-dev/skills/08-debug/SKILL.md +++ b/plugins/aidd-dev/skills/08-debug/SKILL.md @@ -1,33 +1,34 @@ --- name: 08-debug -description: Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. +description: 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. +argument-hint: reproduce | debug | reflect-issue model: opus --- # Skill: debug -Diagnoses issues through structured hypothesis validation, root cause analysis, and test-driven bug fixing from issue creation to PR. +Diagnose and fix issues through structured hypothesis validation, root-cause analysis, and a test-driven fix. -## Available actions +## Actions | # | Action | When to use | | --- | --------------- | ----------------------------------------------------------------------------- | | 01 | `reproduce` | A known bug must be fixed end to end: reproduce, test-driven fix, branch, PR | | 02 | `debug` | Root cause unknown: enumerate hypotheses, validate each, confirm the cause | -| 03 | `reflect-issue` | Stuck or prior fixes failed: re-open the search space, instrument logs first | +| 03 | `reflect-issue` | Stuck or prior fixes failed: reopen the search space, instrument logs first | -## Routing (run first) +Pick the one action matching the intent; never default to `01`. Triggers like "reproduce and fix" route to `01`, "why does this happen" to `02`, "I'm stuck" or "previous fixes didn't work" to `03`. Ask one question when the intent is ambiguous. -This skill offers three distinct actions. Pick the ONE matching the user's intent; do NOT default to action 01. +## Transversal rules -- "fix this bug", "reproduce and fix", "from issue to PR" -> `01-reproduce` -- "why does this happen", "find the root cause", "debug this", "what's causing X" -> `02-debug` -- "I'm stuck", "previous fixes didn't work", "rethink the causes", "add logs to narrow it down" -> `03-reflect-issue` +- One action per run: follow only the matching action file. +- Scope each fix to its bug: never bundle drive-by refactors. +- Confirm the root cause before fixing; the diagnostic actions stop at a confirmed cause. -If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. +## Assets -## Actions +- `assets/task-template.md`: the per-hypothesis tracking file the debug action fills. + +## References -- `@actions/01-reproduce.md` -- `@actions/02-debug.md` -- `@actions/03-reflect-issue.md` +- `references/mermaid-conventions.md`: the project's Mermaid conventions for the action-path flowchart. diff --git a/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md b/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md index 808204cc..e11f12d5 100644 --- a/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md +++ b/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md @@ -1,36 +1,30 @@ # 01 - Reproduce -Fix a bug systematically with a test-driven workflow that goes from issue creation to pull request, one bug per branch. +Fix a bug with a test-driven workflow that goes from issue creation to pull request, one bug per branch. -## Inputs +## Input -```yaml -bug: -``` +The bug, a free-form description or issue number, from the arguments. -## Outputs +## Output -```yaml -issue_id: -branch: -test_file: -pr_url: -status: opened -``` +The opened pull request (its URL), the fix branch, the failing test added before the fix, and the tracker issue id it links. ## Process -1. **Open the ticket.** Create a ticket in the configured ticketing tool with a short, descriptive title. -2. **Create the fix branch** dedicated to this bug. -3. **Reproduce the issue.** Confirm the symptom and capture the minimal trigger; pin down the root cause hypothesis. -4. **Write a failing test** that demonstrates the bug. -5. **Commit** the failing test, linking the issue id. -6. **Implement the minimal fix.** Keep changes scoped to the bug; do not bundle drive-by refactors. -7. **Verify.** Confirm the new test passes; run the full suite. -8. **Commit** the fix, linking the issue id. -9. **Review for scope creep.** If the diff drifted, split or revert; commit again as needed. -10. **Push the branch** and create a PR linking the issue with `Fixes #`. +1. **Ticket.** Create a ticket in the configured ticketing tool with a short, descriptive title. +2. **Branch.** Create a fix branch dedicated to this bug. +3. **Reproduce.** Confirm the symptom, capture the minimal trigger, and pin down the root-cause hypothesis. +4. **Test.** Write a test that demonstrates the bug. +5. **Commit.** Commit the failing test, linking the issue id. +6. **Fix.** Implement the minimal fix, scoped to the bug. +7. **Verify.** Confirm the new test passes, then run the full suite. +8. **Commit.** Commit the fix, linking the issue id. +9. **Scope.** Review for scope creep. When the diff drifted, split or revert and commit again. +10. **Open.** Push the branch and open a PR linking the issue with `Fixes #`. ## Test -A PR exists with the URL emitted in `pr_url`; its diff includes the failing test introduced in step 4 and the minimal fix from step 6; the PR description contains `Fixes #` referencing the ticket created in step 1; the full test suite passes on the head of the fix branch. +- A PR exists at the reported URL, its diff carrying the failing test and the minimal fix. +- The PR description references the ticket with `Fixes #`. +- The full test suite passes on the head of the fix branch. diff --git a/plugins/aidd-dev/skills/08-debug/actions/02-debug.md b/plugins/aidd-dev/skills/08-debug/actions/02-debug.md index 4abe432a..30b011ce 100644 --- a/plugins/aidd-dev/skills/08-debug/actions/02-debug.md +++ b/plugins/aidd-dev/skills/08-debug/actions/02-debug.md @@ -1,38 +1,32 @@ # 02 - Debug -Debug an issue in the codebase by enumerating hypotheses, validating each one, and arriving at a root cause that the user signs off on. +Find the root cause of an issue by enumerating hypotheses, validating each, and arriving at a cause the user signs off on. -## Inputs +## Input -```yaml -issue: -``` +The issue, a free-form description of the symptom or error. -## Outputs +## Output -```yaml -root_cause: -hypotheses: - - { id: 1, description: , confidence: 1-10, status: validated|invalidated, evidence: } -flowchart_path: -next_steps: - - -``` +A one-line root cause, the 3 to 5 hypotheses with their confidence and validated or invalidated status plus evidence, an action-path flowchart, and the next steps. ## Process -1. **Summarize the issue** in your own words. -2. **Map action paths** with a Mermaid flowchart (e.g. user clicks button -> calls function in file1 -> updates state in file2). Apply `@../references/mermaid-conventions.md`. -3. **Apply 5 Whys.** Start from the symptom and ask "why" iteratively (minimum 3, up to 5). Document each level in a numbered list. -4. **Identify inspection tools** (MCP, CLI commands, logs, traces). -5. **Locate relevant files** in the codebase based on the issue. -6. **List 3-5 potential causes** in a table with columns: Analysis, Evidence, Confidence (1-10). -7. **Track hypotheses** using the project task system and `@../assets/task-template.md`. One task per hypothesis. -8. **Validate one by one.** Tick each task when validated or invalidated. Add evidence inside the task. Stop when the root cause is found. -9. **State conclusions and next steps.** -10. **Wait for user validation** before moving on. -11. **Fallback.** If all hypotheses are invalidated, invoke the `reflect_issue` action of this skill for new sources. +1. **Summarize.** Restate the issue in your own words. +2. **Map.** Draw the action paths as a Mermaid flowchart (a click calls a function in one file that updates state in another), per `@../references/mermaid-conventions.md`. +3. **Whys.** Start from the symptom and ask "why" iteratively, three to five levels, each documented in a numbered list. +4. **Tools.** Identify the inspection tools available (MCP, CLI commands, logs, traces). +5. **Locate.** Find the relevant files in the codebase for the issue. +6. **Causes.** List 3 to 5 potential causes in a table: analysis, evidence, confidence (1 to 10). +7. **Track.** Record one task per hypothesis in the project task system, filling `@../assets/task-template.md`. +8. **Validate.** Work the hypotheses one by one, ticking each as validated or invalidated with evidence in the task. Stop when the root cause is found. +9. **Conclude.** State the conclusion and next steps. +10. **Confirm.** Wait for user validation before moving on. +11. **Fallback.** When every hypothesis is invalidated, hand off to the `reflect-issue` action for fresh sources. ## Test -The hypotheses list contains 3-5 entries; every entry has a `validated` or `invalidated` status; if any is `validated`, its evidence is non-empty and `root_cause` is a one-line statement consistent with that evidence; if every hypothesis is `invalidated`, `next_steps` cites the `reflect_issue` action. +- The hypotheses list has 3 to 5 entries, each with a validated or invalidated status. +- A validated hypothesis has non-empty evidence and a one-line root cause consistent with it. +- The output includes a Mermaid action-path flowchart and a confidence score per hypothesis. +- When every hypothesis is invalidated, the next steps cite the `reflect-issue` action. diff --git a/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md b/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md index bbcf3138..85564f0f 100644 --- a/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md +++ b/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md @@ -1,32 +1,24 @@ # 03 - Reflect Issue -Re-open the search space by reflecting on 5-7 fresh possible sources, distilling them down to the 1-2 most likely, and instrumenting the code with logs that will confirm or refute the picks before any fix. +Reopen the search space: reflect on 5 to 7 fresh sources, distill to the 1 or 2 most likely, and instrument logs to confirm or refute them before any fix. -## Inputs +## Input -```yaml -issue: -prior_hypotheses: -``` +The issue carried over from the debug action, and optionally the hypotheses already invalidated. -## Outputs +## Output -```yaml -new_sources: - - { id: , description: , rationale: } -most_likely: - - { id: , description: , confidence: 1-10 } -logs_added: - - { file: , location: , log_message: , purpose: } -``` +The 5 to 7 fresh sources with their rationale, the 1 or 2 most likely with a confidence score, and the validation logs added (file, location, message, what each confirms or refutes). ## Process -1. **List 5-7 fresh possible sources** of the problem, distinct from those already invalidated. -2. **Distill to 1-2 most likely** sources based on consistency with the symptom, recent code changes, and confidence in available evidence. -3. **Add validation logs.** Instrument the relevant code paths with logs that will confirm or refute each of the most-likely sources. Each log has a clear purpose; remove temporary logs after the root cause is found. +1. **Broaden.** List 5 to 7 fresh possible sources, distinct from those already invalidated. +2. **Distill.** Narrow to the 1 or 2 most likely, weighing consistency with the symptom, recent code changes, and available evidence. +3. **Instrument.** Add logs on the relevant code paths that confirm or refute each likely source, each with a clear purpose. Remove the temporary logs once the root cause is found. 4. **Boundary.** Do not implement the fix yet. The goal is to confirm the source first. ## Test -`new_sources` contains 5-7 entries; `most_likely` contains 1-2 entries selected from `new_sources` with a confidence score; `logs_added` is non-empty and every entry cites a real file path and a concrete `purpose` tied to one of the most-likely sources. +- The fresh sources list has 5 to 7 entries. +- The most-likely list has 1 or 2 entries drawn from them, each with a confidence score. +- The logs added are non-empty, each citing a real file path and a concrete purpose tied to a most-likely source. diff --git a/plugins/aidd-dev/skills/08-debug/assets/task-template.md b/plugins/aidd-dev/skills/08-debug/assets/task-template.md index cdc9e1db..5f71ea95 100644 --- a/plugins/aidd-dev/skills/08-debug/assets/task-template.md +++ b/plugins/aidd-dev/skills/08-debug/assets/task-template.md @@ -7,7 +7,7 @@ description: Task tracking system to ensure all tasks are categorized and addres {{Full description}} -## Main step 1} +## Main step 1 - [ ] {Task 1} - [ ] {Task 2} diff --git a/plugins/aidd-dev/skills/09-for-sure/SKILL.md b/plugins/aidd-dev/skills/09-for-sure/SKILL.md index f4f5fcac..ba542107 100644 --- a/plugins/aidd-dev/skills/09-for-sure/SKILL.md +++ b/plugins/aidd-dev/skills/09-for-sure/SKILL.md @@ -1,49 +1,36 @@ --- name: 09-for-sure -description: Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria. +description: 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. +argument-hint: init-tracking | auto-accept | autonomous-loop --- -# For Sure +# Skill: 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 success. +Run an autonomous loop until a success condition is verified. An interactive pre-flight (human present) sets it up, then autonomous execution (human gone) retries until success, acting as the user and never stopping early. -## Context - -- **Goal**: Task's `success_condition` verified by running a command. All steps/acceptance criteria checked. `status` set to `implemented`. -- **Tools required**: Agent tool (spawning iterations), Read/Write/Edit (tracking file), task-specific tools. -- **Trigger**: Manual - `/for-sure`. -- **Tracking file format**: Uses the local `plan-template.md` (`@assets/plan-template.md`). Filename: `aidd_docs/tasks/.md` (state lives in the `status` frontmatter field). +## Actions -## Environment +| # | Action | Phase | Role | +| --- | ----------------- | ---------------------- | -------------------------------------------------------------------------- | +| 01 | `init-tracking` | interactive pre-flight | validate the goal, build the journey map, create the tracking file, spawn the loop | +| 02 | `auto-accept` | autonomous | decide and act as the user, stopping only on money or destructive actions | +| 03 | `autonomous-loop` | autonomous | spawn one worker per step, verify, retry, evaluate the success condition | -None - task secrets are validated during pre-flight and documented in the tracking file. +Run `01` interactively; it spawns `03`, which runs unattended under the `02` auto-accept rules until the success condition passes. ## Transversal rules -1. **Single source of truth**: IF information about the task exists THEN it lives in `aidd_docs/tasks/.md` and nowhere else. -2. **No repeated failures**: IF approach X failed THEN do not try X again without a meaningful change. -3. **Honesty over escape**: IF success condition is not genuinely met THEN do not set `status: implemented`. -4. **Auto-accept**: IF a decision, approval, or action is needed THEN act as the user. Create accounts, generate keys, approve prompts, install tools. Do not ask, do not hesitate, just do it. - -## Execution flow - -### Phase 1 - Interactive (human present) +- Single source of truth: all task state lives in `aidd_docs/tasks/.md` and nowhere else. +- No repeated failures: never retry a failed approach without a meaningful change. +- Honesty over escape: never set `status: implemented` until the success condition genuinely passes. +- Auto-accept: when a decision or approval is needed, act as the user (create accounts, generate keys, approve prompts, install tools), never asking. Stop only on a payment or a destructive action. +- The loop spawns one worker agent per step and never does the work itself. -1. `@actions/01-init-tracking.md` - Pre-flight, create tracking file, spawn first autonomous agent. - -### Phase 2 - Autonomous (human gone) - -2. `@actions/02-auto-accept.md` - Auto-accept mode activation (Phase 3). -3. `@actions/03-autonomous-loop.md` - Orchestrator: spawns one worker per step, verifies, checks/retries, evaluates success. - -## Actions +## Assets -```markdown -@actions/01-init-tracking.md -@actions/02-auto-accept.md -@actions/03-autonomous-loop.md -``` +- `assets/plan-template.md`: the tracking file format (frontmatter, phases, acceptance criteria, Log). +- `assets/autonomous-loop-worker-prompt.md`: the prompt the loop spawns each per-step worker with. ## References -- `@assets/plan-template.md` - tracking file format (frontmatter, phases, acceptance criteria, Log) +- `references/autonomous-loop-log-format.md`: the Log entry format the loop appends per attempt. diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md b/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md index 91c26034..371ff9e8 100644 --- a/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md +++ b/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md @@ -1,53 +1,33 @@ # 01 - Init tracking -Pre-flight, validate prerequisites, build a journey map, create the tracking file, and hand off to the autonomous loop. This is the last interactive step before the loop runs unattended. +Validate prerequisites, build a journey map, create the tracking file, and hand off to the autonomous loop. The last interactive step before the loop runs unattended. -## Inputs +## Input -```yaml -task: # required -description: # optional -success_condition: # required; must exit 0 on success -rules: # optional -``` +The task name (required), an optional free-form description, a runnable success condition that exits 0 on success (required), and optional rules. -## Outputs +## Output -```yaml -tracking_file: aidd_docs/tasks/.md -state: resumed | created -preflight_blockers: [] # non-empty halts before spawn -``` +The tracking file at `aidd_docs/tasks/.md`, marked created or resumed, with any pre-flight blocker halting before the spawn. ## Process -### Resume flow (existing task) - -1. Check `aidd_docs/tasks/` for a file matching the task name, and read its frontmatter `status`: - - `status: pending` or `in-progress` -> report status (iteration, steps remaining), then skip to step 10 to resume. - - `status: implemented` -> report "Task already completed." Stop. - - No file -> continue to step 2. - -### New task flow - -2. **Collect from user**: task name, description, success condition, rules. -3. **Research approach.** Before planning steps, read the relevant documentation (README, official guides). Identify the recommended method; do not default to what you already know. -4. **Validate goal.** Ask "could I execute this with zero ambiguity?" If NO -> ask the user to reformulate. Examples: - - "Make the code better" -> reject. "What metric?" - - "All tests pass after `npm test`" -> accept. -5. **Validate success condition.** It must be a runnable command. Examples: - - `npm test exits 0` -> valid. - - "The code is clean" -> invalid -> push back to `eslint . exits 0`. -6. **Pre-flight checklist.** For each step, list tools, secrets, API access, data, permissions. Markers: - - `[✓]` already satisfied - - `[~]` SOFT - the agent will self-serve (sign up, generate key, install tool) - - `[!]` HARD - only the user can provide it (DB id, channel id, env var, owned API key) - - Collect every `[!]` now. If any `[!]` remains unresolved, STOP - do not proceed to step 7. -7. **Build the ASCII journey map.** Project the entire path with steps, dependencies, tools, blockers. Ask the user to confirm. Iterate until "does this map look correct? Anything missing?" returns confirmation. -8. **Load the plan template** from `@../assets/plan-template.md`. Create `aidd_docs/tasks/` when missing. -9. **Create `aidd_docs/tasks/.md`** using the plan template. Fill frontmatter (`objective`, `success_condition`, `iteration: 0`, `status: pending`), Phases with Tasks and Acceptance criteria (the steps), and include the journey map. -10. **Spawn the autonomous loop.** Read the Orchestrator prompt from `@./03-autonomous-loop.md` and pass it to the Agent tool with `` filled in. +1. **Resume.** Check `aidd_docs/tasks/` for a file matching the task name and read its frontmatter `status`. + - `pending` or `in-progress`: report the status (iteration, steps remaining), then skip to Spawn to resume. + - `implemented`: report "Task already completed" and stop. + - No file: continue to Collect. +2. **Collect.** Gather the task name, description, success condition, and rules from the user. +3. **Research.** Before planning steps, read the relevant documentation (README, official guides) and identify the recommended method. Do not default to what you already know. +4. **Goal.** Ask "could I execute this with zero ambiguity?" When no, ask the user to reformulate. "Make the code better" is rejected ("what metric?"); "all tests pass after `npm test`" is accepted. +5. **Condition.** It must be a runnable command. `npm test exits 0` is valid; "the code is clean" is invalid and is pushed back to `eslint . exits 0`. +6. **Pre-flight.** For each step, list tools, secrets, API access, data, and permissions. Mark `[✓]` already satisfied, `[~]` soft (the agent self-serves), `[!]` hard (only the user can provide it). Collect every `[!]` now; when any stays unresolved, stop before the next step. +7. **Map.** Project the whole path as an ASCII map of steps, dependencies, tools, and blockers. Ask the user to confirm and iterate until they do. +8. **Scaffold.** Load `@../assets/plan-template.md`, creating `aidd_docs/tasks/` when missing. +9. **Create.** Write `aidd_docs/tasks/.md` from the template. Fill the frontmatter (`objective`, `success_condition`, `iteration: 0`, `status: pending`), the phases with their tasks and acceptance criteria, and the journey map. +10. **Spawn.** Read the orchestrator recipe from `@./03-autonomous-loop.md` and hand it to the Agent tool with `` filled in. ## Test -After step 10: the file at `tracking_file` exists with frontmatter `status` (`pending` at creation), its `success_condition` field is a runnable command, the journey map is present, every `[!]` blocker has been resolved before spawn, and an autonomous agent has been launched. +- The tracking file exists with frontmatter `status: pending` at creation. +- Its `success_condition` is a runnable command and the journey map is present. +- Every `[!]` blocker was resolved before the spawn, and an autonomous agent was launched. diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md b/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md index 72c800e1..ccdcb53d 100644 --- a/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md +++ b/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md @@ -1,33 +1,28 @@ # 02 - Auto-accept -Operate autonomously: do not ask for confirmation, decide and act, only stop on money or destructive actions. +Operate autonomously: do not ask for confirmation, decide and act, and stop only on money or destructive actions. -## Inputs +## Input -```yaml -task: -``` +The task to handle end-to-end, a free-form description. -## Outputs +## Output -```yaml -status: completed | stopped_payment | stopped_destructive | stopped_out_of_scope -actions_taken: - - -stopped_reason: -``` +An exit status, completed or one of stopped-payment, stopped-destructive, or stopped-out-of-scope, with the actions taken and a one-sentence reason when stopped. ## Process -Apply these rules in order to every prompt, dialog, checkbox, Y/n, license screen, cookie banner, or confirmation encountered while handling the task. +Apply these rules in order to every prompt, dialog, checkbox, Y/n, license screen, cookie banner, or confirmation met while handling the task. -1. **Accept everything by default.** Acknowledge and move on. -2. **Choose defaults.** When an installer offers options, pick the recommended or standard one. -3. **Fix problems yourself.** When something fails (missing dependency, wrong version, config error), fix it and retry. Do not ask. -4. **Stop only when it costs money.** When an action involves payment, subscription, or upgrade to a paid tier, stop and report. -5. **Stop on destructive actions.** When an action deletes data, drops a database, removes files recursively, force-pushes, resets git history, or overwrites uncommitted work, stop and report. -6. **Stay scoped.** When an instruction would lead outside the original task (unrelated tools, external signups, rabbit holes), skip it. Only do what the user asked for, nothing more. +1. **Accept.** Accept everything by default, acknowledge, and move on. +2. **Default.** When an installer offers options, pick the recommended or standard one. +3. **Self-fix.** When something fails (missing dependency, wrong version, config error), fix it and retry. Do not ask. +4. **Money.** Stop and report when an action involves payment, subscription, or an upgrade to a paid tier. +5. **Destructive.** Stop and report when an action deletes data, drops a database, removes files recursively, force-pushes, resets git history, or overwrites uncommitted work. +6. **Scope.** Skip anything leading outside the original task (unrelated tools, external signups, rabbit holes). Do only what the user asked. ## Test -`status` matches the actual exit path: `completed` only when the task was carried out end-to-end with no money or destructive action gate hit; `stopped_payment` / `stopped_destructive` / `stopped_out_of_scope` are accompanied by a non-empty `stopped_reason`. +- The status matches the actual exit path. +- `completed` appears only when the task ran end-to-end with no money or destructive gate hit. +- Each stopped status carries a non-empty reason. diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md b/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md index dc296039..6778259c 100644 --- a/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md +++ b/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md @@ -1,71 +1,29 @@ # 03 - Autonomous loop -Orchestrates the loop. For each unchecked step: spawns a worker agent, verifies the result, checks the box or retries. One step = one agent = one log entry. The orchestrator never does the work itself. +Orchestrate the loop: for each unchecked step spawn a worker, verify the result, then check the box or retry. One step is one agent is one log entry, and the orchestrator never does the work itself. -## Inputs +## Input -```yaml -tracking_file: aidd_docs/tasks/.md # produced by 01-init-tracking -``` +The tracking file `aidd_docs/tasks/.md` produced by `01-init-tracking`. The loop runs with no human interaction, reading and writing through that file. -## Outputs +## Output -```yaml -iterations: -steps_completed: -log_entries: -``` +The success condition verified and the plan's `status` set to `implemented`, with every step checked and one Log entry per attempt. ## Process -The loop runs with no human interaction. Inputs and outputs are read from / written to the tracking file. - -1. **Read the entire file.** Frontmatter, journey map, steps, full Log. -2. **Increment `iteration`** in frontmatter, and set `status: in-progress` if still `pending`. -3. **Read the Log** to learn from prior attempts. -4. **Find the next unchecked step.** -5. **Spawn a worker agent** for that step with the Worker prompt template (below). Pass the step description and the relevant context (objective, rules, prior Log entries for this step). -6. **Read the worker's result.** -7. **Verify concretely.** Run a check command, read a file, test the output. Do not trust the worker's claim alone. -8. **On verified ✓**: tick the step `[x]` and append a Log entry. -9. **On not verified ✗**: append a Log entry with the failure reason; spawn another worker with the error context. -10. **Move to the next unchecked step.** Loop from step 1. - -### After every step is checked - -11. **Run the success_condition command** and verify the result yourself. -12. **On TRUE**: set `status: implemented` in the frontmatter and stop. -13. **On FALSE**: add new steps to address the root cause and continue the loop. - -## Worker prompt template - -```text -Execute this step. Auto-accept everything - act as the user, make every -decision yourself (approve prompts, generate keys, install tools, click -buttons). Do not ask for permission. Just do it. - -Signing in via existing accounts (Google Sign-in, GitHub OAuth, SSO) is NOT -account creation - it uses the user's active browser session. Do it. - -STEP: -CONTEXT: - -Report: -- What you did (specific: commands, files, URLs). -- The concrete result (paste output, screenshot, evidence). -``` - -## Log entry format - -One entry per step attempt: - -```text -### # - -> - -= <✓|✗> --> -``` +1. **Read.** Read the entire file: frontmatter, journey map, steps, and full Log. +2. **Mark.** Increment `iteration` in the frontmatter, setting `status: in-progress` when still `pending`. +3. **Learn.** Read the Log to learn from prior attempts. +4. **Next.** Find the next unchecked step. +5. **Spawn.** Spawn a worker for that step with `@../assets/autonomous-loop-worker-prompt.md`, passing the step description and the relevant context (objective, rules, prior Log entries for the step). +6. **Verify.** Read the worker's result, then verify concretely by running a check command, reading a file, or testing the output. Never trust the worker's claim alone. +7. **Record.** Read the worker's outcome. When it stopped at a money or destructive gate, surface the reason to the user and stop the loop; never retry, which would re-trigger the action. On verified success, tick the step `[x]`. On a plain failure, spawn another worker with the error context. Append a Log entry per `@../references/autonomous-loop-log-format.md`. +8. **Loop.** Move to the next unchecked step and repeat from Read. +9. **Evaluate.** Once every step is checked, run the `success_condition` command and verify the result yourself. On success, set `status: implemented` and stop. On failure, add new steps addressing the root cause and continue the loop. ## Test -Each step attempt has exactly one Log entry; every checked step (`[x]`) has a `= ✓` entry whose verification cites a concrete command or file; the loop only sets `status: implemented` after the `success_condition` command has been re-run and exits zero. +- Each step attempt has exactly one Log entry. +- Every checked step has a `= ✓` entry whose verification cites a concrete command or file. +- `status: implemented` is set only after the `success_condition` command has been re-run and exits zero. diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/autonomous-loop-worker-prompt.md b/plugins/aidd-dev/skills/09-for-sure/assets/autonomous-loop-worker-prompt.md new file mode 100644 index 00000000..3e4a7e57 --- /dev/null +++ b/plugins/aidd-dev/skills/09-for-sure/assets/autonomous-loop-worker-prompt.md @@ -0,0 +1,21 @@ + + +Execute this step. Auto-accept everything, act as the user, and make every +decision yourself (approve prompts, generate keys, install tools, click +buttons). Do not ask for permission. Just do it. + +Signing in via an existing account (Google Sign-in, GitHub OAuth, SSO) is NOT +account creation; it uses the user's active browser session. Do it. + +Stop and report instead, without proceeding, when an action would cost money (a +payment, subscription, or paid upgrade) or is destructive (deletes data, drops a +database, force-pushes, resets git history, removes files recursively, or +overwrites uncommitted work). Stay inside the task; skip unrelated signups. + +STEP: +CONTEXT: + +Report: +- What you did, specifically: commands, files, URLs. +- The concrete result: paste output, a screenshot, or evidence. +- Whether you stopped at a money or destructive gate, and which. diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md index c8e1aad0..e5f274b2 100644 --- a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md +++ b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md @@ -1,7 +1,4 @@ --- -name: for-sure-tracking -description: For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments. -argument-hint: N/A objective: "{What must be true when done. One sentence.}" success_condition: "{Runnable command that proves done. Example: 'npm test exits 0 AND coverage > 80%'}" iteration: 0 @@ -52,7 +49,7 @@ status: pending ## Applicable rules - + | Tool | Name | Path | Why it applies | | ------ | ------ | ------------------------------------- | -------------- | diff --git a/plugins/aidd-dev/skills/09-for-sure/references/autonomous-loop-log-format.md b/plugins/aidd-dev/skills/09-for-sure/references/autonomous-loop-log-format.md new file mode 100644 index 00000000..86e36a20 --- /dev/null +++ b/plugins/aidd-dev/skills/09-for-sure/references/autonomous-loop-log-format.md @@ -0,0 +1,15 @@ +# Autonomous loop: Log entry format + +The autonomous loop appends one entry to the tracking file's Log per step attempt, in this exact shape: + +```text +### # - +> - += <✓|✗> +-> +``` + +- `### #` numbers the attempt. +- `>` records the worker's attempt. +- `=` records the orchestrator's own verification (a command run or a file read), not the worker's claim. +- `->` records the decision: the next step, or `RETRY` with the reason. diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md index 727b75be..734bde80 100644 --- a/plugins/aidd-dev/skills/10-todo/README.md +++ b/plugins/aidd-dev/skills/10-todo/README.md @@ -2,7 +2,7 @@ # 10 - todo -Split one prompt into independent todos, run one implementer agent per +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. diff --git a/plugins/aidd-dev/skills/10-todo/SKILL.md b/plugins/aidd-dev/skills/10-todo/SKILL.md index 85a589b7..cf9e1e9b 100644 --- a/plugins/aidd-dev/skills/10-todo/SKILL.md +++ b/plugins/aidd-dev/skills/10-todo/SKILL.md @@ -1,6 +1,6 @@ --- name: 10-todo -description: Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. +description: 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. --- # Todo @@ -10,5 +10,5 @@ Turn one prompt into N independent todos, implement them in parallel, report a t ## Actions ```markdown -@actions/01-todo.md +actions/01-todo.md ``` diff --git a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md index d918c682..222401dc 100644 --- a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md +++ b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md @@ -2,12 +2,10 @@ Categorize the user prompt into independent todos, implement each in parallel, report. -## Inputs - +## Input User's requirement. -## Outputs - +## Output ```markdown | Category | Launched | Output | | -------- | -------- | ------ | @@ -15,15 +13,15 @@ User's requirement. ## Process -1. **Read.** Take `prompt` from `$ARGUMENTS`; if empty, ask the user. -2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent, using template. -3. **Launch.** Spawn one `implementer` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: +1. **Read.** Take `prompt` from the arguments; if empty, ask the user. +2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent. +3. **Launch.** Spawn one `executor` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: ```markdown - 1. Refine the todo first - discover at runtime a skill whose description covers refining or clarifying a request (never a hardcoded plugin name) and run it on the todo. + 1. Refine the todo first: run a non-interactive refine capability if one is available (discovered at runtime, never a hardcoded plugin name); otherwise restate the todo clearly and resolve obvious ambiguity inline. Never block on the user. 2. Implement the refined todo. 3. Return a one-line output summary. ``` -4. **Report.** Print exactly one table, nothing else: +4. **Report.** Print exactly one table, nothing else. ## Test diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 16290f8f..625b679b 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -26,5 +26,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `-` | [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) | `Single entry point for the async-dev pipeline (setup, run, review). Hybrid router decides which sub-flow to execute from $ARGUMENTS keyword (`setup` / `run` / `review`), trigger source (label `to-implement` / `to-review`, comment `@claude /implement` / `/review`), repo state (workflow + config presence, PR linked to issue), or natural-language intent. Use when the user says "set up async dev", "run async dev on issue #N", "address review on PR #N", "/async-dev", "claude on issues", or when triggered by a webhook with the matching labels or comments. Do NOT use for plain status checks on the async pipeline or for SDLC orchestration unrelated to issue/PR automation.` | +| `-` | [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/skills/00-async-dev/README.md b/plugins/aidd-orchestrator/skills/00-async-dev/README.md index 14352618..32097d12 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/README.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/README.md @@ -15,7 +15,7 @@ Single entry point for the async-dev pipeline. Hybrid router that picks one of t - 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. +- From inside a sub-flow action, actions never re-enter the router. ## How to invoke @@ -41,8 +41,7 @@ The router reads `$ARGUMENTS`, then trigger env, then repo state, then natural i | 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 | -## Outputs - +## Output Each sub-flow defines its own outputs: - **Setup**: workflow file, config file, scripts, labels, schedule routine id (if applicable). diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md index c4bf21d5..8798ee07 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-async-dev -description: Single entry point for the async-dev pipeline (setup, run, review). Hybrid router decides which sub-flow to execute from $ARGUMENTS keyword (`setup` / `run` / `review`), trigger source (label `to-implement` / `to-review`, comment `@claude /implement` / `/review`), repo state (workflow + config presence, PR linked to issue), or natural-language intent. Use when the user says "set up async dev", "run async dev on issue #N", "address review on PR #N", "/async-dev", "claude on issues", or when triggered by a webhook with the matching labels or comments. Do NOT use for plain status checks on the async pipeline or for SDLC orchestration unrelated to issue/PR automation. +description: 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. +argument-hint: collect-comments | detect-stop | fix-iteration | finalize | poll-ready | resolve-deps | acquire-lock | check-sdlc | delegate-sdlc | write-audit | detect-context | ask-config | generate-workflow | generate-local-script | write-config | bootstrap-labels | install-user-scope-plugins | configure-remote-secrets | bootstrap-scheduling | commit-and-push | smoke-test --- # Async-dev @@ -17,11 +18,11 @@ Single skill that drives the async development pipeline end to end. Three sub-fl **You are the router until you commit to a sub-flow. Once committed, run that sub-flow's actions in order; do not jump back to routing mid-flow.** -## Routing — hybrid contract +## Routing: hybrid contract Walk in order. First match wins. -1. **`$ARGUMENTS` keyword override.** If `$ARGUMENTS` contains exactly `setup`, `run`, or `review` (case-insensitive, standalone token), route there immediately. This is the explicit override the CI workflow uses. +1. **Argument override.** If the arguments contain exactly `setup`, `run`, or `review` (case-insensitive, standalone token), route there immediately. This is the explicit override the CI workflow uses. 2. **Trigger env.** When invoked from CI (`GITHUB_EVENT_NAME` set): - Label payload `to-implement` → `run`. - Label payload `to-review` → `review`. @@ -42,7 +43,7 @@ Walk in order. First match wins. **If repo state contradicts intent** (e.g. user says "run" but `.claude/aidd-orchestrator.json` is absent), surface the conflict before delegating; never silently switch. -See `@references/routing.md` for the full decision tree, signal precedence, and edge cases. +See `references/routing.md` for the full decision tree, signal precedence, and edge cases. ## Sub-flows @@ -54,9 +55,9 @@ Sets up async-dev in a repo. Detects context, asks for runtime parameters, gener | --- | --------------------------------- | --------------------------------------------------------------------------------------------- | | 01 | `detect-context` | Identify repo, default branch, existing config, CI permissions | | 02 | `ask-config` | Collect runtime parameters (mode, auth, labels, schedule, agents) | -| 03 | `generate-workflow` | Emit `.github/workflows/aidd-async.yml` from `@assets/setup/workflow-template.yml` | -| 04 | `generate-local-script` | Emit poll/daemon scripts (local mode only) from `@assets/setup/local-*-template.sh` | -| 05 | `write-config` | Persist `.claude/aidd-orchestrator.json` from `@assets/setup/config-template.json` | +| 03 | `generate-workflow` | Emit `.github/workflows/aidd-async.yml` from `assets/setup/workflow-template.yml` | +| 04 | `generate-local-script` | Emit poll/daemon scripts (local mode only) from `assets/setup/local-*-template.sh` | +| 05 | `write-config` | Persist `.claude/aidd-orchestrator.json` from `assets/setup/config-template.json` | | 06 | `bootstrap-labels` | Create `to-implement` / `to-review` / `claude/*` labels via `gh` | | 07 | `install-user-scope-plugins` | Install `aidd-orchestrator` + `aidd-dev` at user scope (local mode) | | 08 | `configure-remote-secrets` | Sync `CLAUDE_CODE_OAUTH_TOKEN`, `AIDD_BOT_TOKEN`, etc. (remote mode) | @@ -64,7 +65,7 @@ Sets up async-dev in a repo. Detects context, asks for runtime parameters, gener | 10 | `commit-and-push` | Stage generated files, conventional-commit, push | | 11 | `smoke-test` | Label a throwaway issue with `to-implement`; verify the pipeline reacts | -Files: `@actions/setup/01-detect-context.md` ... `@actions/setup/11-smoke-test.md`. +Files: `actions/setup/01-detect-context.md` ... `actions/setup/11-smoke-test.md`. Default flow: `01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11`. Actions self-skip when their preconditions are not met (e.g. `07` skips in remote mode, `08` skips in local mode). @@ -81,7 +82,7 @@ Executes one orchestration cycle on a fresh issue. Reads ready issues, resolves | 05 | `delegate-sdlc` | Hand the issue to the SDLC capability; observe outcome | | 06 | `write-audit` | Emit `run-result.json` for the workflow's post-job | -Files: `@actions/run/01-poll-ready.md` ... `@actions/run/06-write-audit.md`. +Files: `actions/run/01-poll-ready.md` ... `actions/run/06-write-audit.md`. Default flow: `01 → 02 → 03 → 04 → 05 → 06`. One cycle per ready issue. @@ -92,13 +93,13 @@ Closes the loop after a PR is opened by the run flow. Detects when to keep auto- | # | Action | Role | | --- | -------------------- | ------------------------------------------------------------------------------------------ | | 01 | `collect-comments` | Read all PR + linked-issue comments newer than the last bot activity | -| 02 | `detect-stop` | Decide stop vs continue using `@references/review/stop-conditions.md` | +| 02 | `detect-stop` | Decide stop vs continue using `references/review/stop-conditions.md` | | 03 | `fix-iteration` | Delegate fixes to the SDLC capability; reply to each addressed comment | | 04 | `finalize` | Resolve threads, post the structured summary, set `claude/awaiting-review` or `blocked` | -Files: `@actions/review/01-collect-comments.md` ... `@actions/review/04-finalize.md`. +Files: `actions/review/01-collect-comments.md` ... `actions/review/04-finalize.md`. -Default flow: `01 → 02 → (03 → 01 loop if continue) → 04`. Stop conditions in `@references/review/stop-conditions.md`. +Default flow: `01 → 02 → (03 → 01 loop if continue) → 04`. Stop conditions in `references/review/stop-conditions.md`. ## Rules @@ -110,20 +111,20 @@ Default flow: `01 → 02 → (03 → 01 loop if continue) → 04`. Stop conditio ## References -- `@references/routing.md` - full decision tree, signal precedence, conflict resolution. -- `@references/setup/auth-modes.md` - local vs remote auth contracts. -- `@references/setup/claude-action-auth.md` - `claude-code-action` token setup. -- `@references/setup/local-mode-scheduling.md` - poll routine options. -- `@references/review/stop-conditions.md` - when the review loop hands off to a human. +- `references/routing.md` - full decision tree, signal precedence, conflict resolution. +- `references/setup/auth-modes.md` - local vs remote auth contracts. +- `references/setup/claude-action-auth.md` - `claude-code-action` token setup. +- `references/setup/local-mode-scheduling.md` - poll routine options. +- `references/review/stop-conditions.md` - when the review loop hands off to a human. ## Assets Setup-only templates copied into the target repo by the setup sub-flow: -- `@assets/setup/workflow-template.yml` - `.github/workflows/aidd-async.yml` skeleton. -- `@assets/setup/local-poll-template.sh` - local-mode poll script. -- `@assets/setup/local-daemon-template.sh` - local-mode daemon script. -- `@assets/setup/config-template.json` - `.claude/aidd-orchestrator.json` skeleton. +- `assets/setup/workflow-template.yml` - `.github/workflows/aidd-async.yml` skeleton. +- `assets/setup/local-poll-template.sh` - local-mode poll script. +- `assets/setup/local-daemon-template.sh` - local-mode daemon script. +- `assets/setup/config-template.json` - `.claude/aidd-orchestrator.json` skeleton. ## Test diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md index 11922a9c..1a02d94a 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md @@ -2,16 +2,14 @@ Pulls new review comments since the last iteration and acknowledges the loop has started. -## Inputs - +## Input - `pr_number` (required) -- integer, target PR - `trigger_comment_id` (optional) -- id of the comment that triggered the loop; receives an `eyes` reaction - `trigger_comment_url` (optional) -- full URL of the triggering comment; lets the loop reply in the thread that fired the trigger - `source_issue_number` (optional) -- issue number when the trigger was a comment on the linked issue (not the PR itself); enables fetching that thread alongside PR comments - `since` (optional) -- ISO 8601 timestamp; defaults to the timestamp of the last iteration recorded in the audit record -## Outputs - +## Output ```json { "pr_number": 117, @@ -23,7 +21,7 @@ Pulls new review comments since the last iteration and acknowledges the loop has } ``` -Each entry carries a `source` of `pr_review` (inline review thread), `pr_conversation` (top-level PR comment), or `issue` (comment on the linked issue). Issue comments have no `path`/`line` — Claude treats them as plain user direction. +Each entry carries a `source` of `pr_review` (inline review thread), `pr_conversation` (top-level PR comment), or `issue` (comment on the linked issue). Issue comments have no `path`/`line`, Claude treats them as plain user direction. ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md index 4629db12..96c26be0 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md @@ -2,14 +2,12 @@ Decides whether to keep iterating or hand control to a human. -## Inputs - +## Input - `collect_output` (required) -- output of `01-collect-comments` - `config` (required) -- parsed `.claude/aidd-orchestrator.json` - `issue_labels` (required) -- current labels on the linked issue -## Outputs - +## Output ```json { "decision": "stop", @@ -20,9 +18,6 @@ Decides whether to keep iterating or hand control to a human. `decision` is `"stop"` or `"continue"`. `reason` is one of `max_iterations`, `blocked_label`, `human_reviewer`, or `null`. -## Depends on - -- `01-collect-comments` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md index fc10c1ac..4c49dc41 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md @@ -2,15 +2,13 @@ Delegates one round of fixes to the SDLC capability discovered at runtime and pushes a new commit on the PR branch. -## Inputs - +## Input - `collect_output` (required) -- output of `01-collect-comments` - `pr_number` (required) -- integer - `discovered_skill` (required) -- skill name discovered by the same heuristic used in `02-run` - `trigger_comment_id` (optional) -- id of the comment that triggered the loop (e.g. `@claude /review`); used to add a reaction -## Outputs - +## Output ```json { "iteration": 2, @@ -21,9 +19,6 @@ Delegates one round of fixes to the SDLC capability discovered at runtime and pu } ``` -## Depends on - -- `02-detect-stop` (only when its `decision == "continue"`) ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md index 10e17ccc..572e24e9 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md @@ -2,16 +2,14 @@ Emit a `run-result.json` artifact summarising the review loop's stop decision and iteration log. The workflow's post-job (CI YAML) reads this file and performs the lifecycle effects: append to the audit log, finalize the Check Run, post the summary comment, transition issue labels, post the completion marker. -## Inputs - +## Input - `pr_number` - `stop_reason` -- one of `max_iterations`, `blocked_label`, `human_reviewer`, `no_comments` - `iteration_log` -- entries from `03-fix-iteration`; may be empty when `stop_reason = "no_comments"` - `trigger_comment_id` (optional) - `run_id` -## Outputs - +## Output A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable): ```json @@ -30,9 +28,6 @@ A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable): } ``` -## Depends on - -- `02-detect-stop` (when `decision = "stop"`) ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md index 9945379f..2a76392e 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md @@ -2,14 +2,12 @@ Lists candidate issues that the pipeline should process. -## Inputs - +## Input - `config` (required) -- parsed `.claude/aidd-orchestrator.json` - `trigger_event` (optional) -- one of `label`, `mention`, `cron`. Defaults to `cron` - `issue_hint` (optional) -- a specific issue number from the trigger event -## Outputs - +## Output ```json { "candidates": [ diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md index d0ec3b86..7975d3ea 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md @@ -2,13 +2,11 @@ Filters out blocked issues by checking three dependency sources in order. -## Inputs - +## Input - `candidates` (required) -- output of `01-poll-ready` - `config` (required) -- parsed `.claude/aidd-orchestrator.json` -## Outputs - +## Output ```json { "ready": [{ "number": 42, "title": "..." }], @@ -18,9 +16,6 @@ Filters out blocked issues by checking three dependency sources in order. } ``` -## Depends on - -- `01-poll-ready` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md index e2ec40b1..e27a7415 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md @@ -2,13 +2,11 @@ Marks an issue as in-progress so concurrent triggers do not double-run. -## Inputs - +## Input - `issue` (required) -- one entry from `ready` (output of `02-resolve-deps`) - `config` (required) -- parsed `.claude/aidd-orchestrator.json` -## Outputs - +## Output ```json { "issue_number": 42, @@ -17,9 +15,6 @@ Marks an issue as in-progress so concurrent triggers do not double-run. } ``` -## Depends on - -- `02-resolve-deps` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md index ae105923..4de58a3e 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md @@ -2,12 +2,10 @@ Discovers an active SDLC orchestration capability in the runtime before delegation. -## Inputs - +## Input - none (reads runtime skill catalog) -## Outputs - +## Output ```json { "sdlc_available": true, @@ -16,9 +14,6 @@ Discovers an active SDLC orchestration capability in the runtime before delegati } ``` -## Depends on - -- `03-acquire-lock` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md index 0be3d50f..a43fef34 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md @@ -1,9 +1,8 @@ # 05 -- Delegate SDLC -Invoke the SDLC capability with the issue request, then verify the outcome by observing the real state of git and the VCS host — never by parsing the SDLC's return shape. - -## Inputs +Invoke the SDLC capability with the issue request, then verify the outcome by observing the real state of git and the VCS host, never by parsing the SDLC's return shape. +## Input - `issue` -- the locked issue object - `run_id` -- identifier from `03-acquire-lock` - `discovered_skill` -- skill name from `04-check-sdlc` @@ -11,8 +10,7 @@ Invoke the SDLC capability with the issue request, then verify the outcome by ob - `trigger_kind` (optional) -- `label` or `comment` - `trigger_comment_url` (optional) -- when `trigger_kind = comment` -## Outputs - +## Output ```json { "default_before": "", @@ -30,9 +28,6 @@ Invoke the SDLC capability with the issue request, then verify the outcome by ob Every field is the result of an observation against git or the VCS host. None is parsed from the SDLC's return text. -## Depends on - -- `04-check-sdlc` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md index 1891f58f..835cc80c 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md @@ -1,15 +1,13 @@ # 06 -- Write Run Result -Emit a single `run-result.json` artifact summarising the observation from `05-delegate-sdlc`. The workflow's post-job (CI YAML) reads this file and performs the lifecycle effects: persist the audit log, finalize the Check Run, transition issue labels, post the completion marker. Splitting those side effects out of the agent keeps them deterministic — the agent only needs to write a file. - -## Inputs +Emit a single `run-result.json` artifact summarising the observation from `05-delegate-sdlc`. The workflow's post-job (CI YAML) reads this file and performs the lifecycle effects: persist the audit log, finalize the Check Run, transition issue labels, post the completion marker. Splitting those side effects out of the agent keeps them deterministic, the agent only needs to write a file. +## Input - `delegate_output` -- structured result from `05-delegate-sdlc` - `run_record` -- merged data from `03-acquire-lock` and `05-delegate-sdlc` - `config` -- parsed `.claude/aidd-orchestrator.json` -## Outputs - +## Output A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable): ```json @@ -32,9 +30,6 @@ A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable): } ``` -## Depends on - -- `05-delegate-sdlc` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md index 5e5d3e89..e4af1133 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md @@ -2,12 +2,10 @@ Inspects the current repo and the active runtime to confirm preconditions. -## Inputs - +## Input - `cwd` (required) -- string, absolute path of the target repo -## Outputs - +## Output ```json { "repo_root": "/abs/path", diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md index aa1532b1..76c3eb70 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md @@ -2,12 +2,10 @@ Interactively collects the small set of runtime parameters from the user. -## Inputs - +## Input - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output ```json { "mode": "both", @@ -45,9 +43,6 @@ Interactively collects the small set of runtime parameters from the user. } ``` -## Depends on - -- `01-detect-context` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md index 930fd954..aa1ad101 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md @@ -2,23 +2,18 @@ Renders the GitHub Actions workflow that triggers the async pipeline. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output A file at `.github/workflows/aidd-async.yml`. -## Depends on - -- `02-ask-config` ## Process 1. Skip this action when `answers.mode == "local"`. -2. Read `assets/workflow-template.yml`. +2. Read `assets/setup/workflow-template.yml`. 3. Substitute placeholders: - `__TO_IMPLEMENT_LABEL__` -> `answers.labels.to_implement` - `__TO_REVIEW_LABEL__` -> `answers.labels.to_review` diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md index cf08f212..73b28e2b 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md @@ -2,23 +2,18 @@ Renders the local poll script. The script wraps `claude -p` invocations of the run and review skills. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output A file at `scripts/aidd-async-poll.sh` with mode `0755`. -## Depends on - -- `02-ask-config` ## Process 1. Skip this action when `answers.mode == "remote"`. -2. Read `assets/local-poll-template.sh`. +2. Read `assets/setup/local-poll-template.sh`. 3. Substitute placeholders: - `__TO_IMPLEMENT_LABEL__` -> `answers.labels.to_implement` - `__TO_REVIEW_LABEL__` -> `answers.labels.to_review` diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md index 10741a8c..d59ef2ba 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md @@ -2,21 +2,16 @@ Persists the plugin configuration to the repo. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` -## Outputs - +## Output A file at `.claude/aidd-orchestrator.json`. -## Depends on - -- `02-ask-config` ## Process -1. Read `assets/config-template.json`. +1. Read `assets/setup/config-template.json`. 2. Merge `answers` into the template, preserving template defaults for fields the user did not override. 3. Add a top-level `version` (the plugin version) and an ISO 8601 `created_at` timestamp. 4. If `.claude/aidd-orchestrator.json` already exists, diff against the new config and ask the user to confirm overwrite. diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md index 287ad817..fb81caf5 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md @@ -2,12 +2,10 @@ Creates the 5 lifecycle labels declared in the config if they do not already exist on the repo. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` -## Outputs - +## Output ```json { "created": ["to-implement", "claude/working"], @@ -15,9 +13,6 @@ Creates the 5 lifecycle labels declared in the config if they do not already exi } ``` -## Depends on - -- `04-write-config` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md index 2310320a..4a97e57a 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md @@ -2,13 +2,11 @@ Installs the orchestrator plugin and an SDLC-providing plugin at user scope so the local poll script can invoke them via `claude -p` from any cwd. Skips entirely when the plugins are already loaded (project scope or user scope). -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output ```json { "skipped": true, @@ -22,9 +20,6 @@ Installs the orchestrator plugin and an SDLC-providing plugin at user scope so t When `skipped == false`, the response contains `marketplace_added` and `plugins_installed` instead of `found_at`. -## Depends on - -- `06-bootstrap-labels` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md index c333f566..a382643d 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md @@ -2,13 +2,11 @@ Walks the user through adding the GitHub Action secrets the workflow needs. For each required secret, prints inline a short "what / why / how" block with two or three concrete ways to generate the value, then reads the value from stdin and stores it via `gh secret set`. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output ```json { "secrets_set": ["CLAUDE_CODE_OAUTH_TOKEN"], @@ -16,9 +14,6 @@ Walks the user through adding the GitHub Action secrets the workflow needs. For } ``` -## Depends on - -- `06-bootstrap-labels` ## Process @@ -66,7 +61,7 @@ Paste the key when prompted. Used by the GitHub Action to clone the marketplace repository so plugins can install at runtime. Read-only is enough. Three ways to obtain: -- **A. Fine-grained PAT (recommended)**: `https://github.com/settings/personal-access-tokens/new`. Resource owner = the marketplace repo's owner. Repository access = "Only select repositories" -> the marketplace repo. Permissions = `Repository -> Contents: Read-only`. Expiration: 90 days minimum (set a calendar reminder to rotate). +- **A. Fine-grained PAT (recommended)**: `https://github.com/settings/personal-access-tokens/new`. Resource owner = the marketplace repo's owner. Repository access = "Only select repositories" → the marketplace repo. Permissions = `Repository -> Contents: Read-only`. Expiration: 90 days minimum (set a calendar reminder to rotate). - **B. Classic PAT (fallback)**: `https://github.com/settings/tokens/new`. Scope = `repo` (read). Less granular; rotate every 90 days. - **C. GitHub App installation token**: install a dedicated GitHub App on the org with "Contents: Read" on the marketplace repo. Mint short-lived tokens via the App's private key (rotates automatically). Heaviest setup, best for org compliance. @@ -80,7 +75,7 @@ How to obtain (recommended): - `https://github.com/settings/personal-access-tokens/new` - **Resource owner**: the target repo's owner. -- **Repository access**: "Only select repositories" -> the target repo. +- **Repository access**: "Only select repositories" → the target repo. - **Repository permissions** (all under "Repository permissions"): - `Contents`: Read and Write - `Pull requests`: Read and Write diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md index 7f659f5e..d4f9b1f1 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md @@ -2,13 +2,11 @@ Schedules `scripts/aidd-async-poll.sh` via the cheapest path that fits the user's needs. **Never recommends OS-level cron**, but for the local daemon path uses tmux/launchd/systemd so the user keeps Claude Code's Tasks quota for other things. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output ```json { "path": "local_daemon", @@ -20,9 +18,6 @@ Schedules `scripts/aidd-async-poll.sh` via the cheapest path that fits the user' `path` is one of: `manual`, `local_daemon`, `desktop_task_pending`, `schedule_routine`. -## Depends on - -- `04-generate-local-script` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md index c43a9558..8dd50afe 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md @@ -2,12 +2,10 @@ Stages every file generated by previous actions, asks the user for explicit confirmation, then commits and pushes the branch. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` -## Outputs - +## Output ```json { "committed": true, @@ -17,9 +15,6 @@ Stages every file generated by previous actions, asks the user for explicit conf } ``` -## Depends on - -- `09-bootstrap-scheduling` ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md index b216f61b..46a22882 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md @@ -2,13 +2,11 @@ Triggers the pipeline once on a self-contained throwaway issue (created by this action) so the user sees the full setup work end-to-end before walking away. Never touches the user's real backlog. -## Inputs - +## Input - `answers` (required) -- config object from `02-ask-config` - `detection` (required) -- detection report from `01-detect-context` -## Outputs - +## Output ```json { "smoke_issue_number": 999, @@ -20,10 +18,6 @@ Triggers the pipeline once on a self-contained throwaway issue (created by this `run_outcome` is `pr_opened`, `blocked`, or `skipped`. -## Depends on - -- `10-commit-and-push` (when `answers.mode != "local"`) -- `09-bootstrap-scheduling` (when `answers.mode != "remote"`) ## Process diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md b/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md index bd1013cb..c097d88c 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md @@ -21,10 +21,10 @@ The human-reviewer stop **only fires from iteration 2 onwards**. On iteration 1, From iteration 2 onwards, if any new comment authored since the previous iteration started is from a non-bot user, the loop stops with `reason = human_reviewer`. The Check Run conclusion is `success` if the last iteration's tests passed, else `neutral`. Detection rules for "non-bot": -- `author.type == "Bot"` from the GitHub API -> bot -- author login ends with `[bot]` -> bot -- author login is in `config.bot_allowlist` (optional) -> bot -- otherwise -> human +- `author.type == "Bot"` from the GitHub API → bot +- author login ends with `[bot]` → bot +- author login is in `config.bot_allowlist` (optional) → bot +- otherwise → human Use case: a reviewer wrote feedback during the loop. Claude must not loop on top of human input. The next pass requires an explicit re-trigger. diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md b/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md index d6ec5573..2e4c86bd 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md @@ -1,12 +1,12 @@ -# Routing — decision tree +# Routing: decision tree Full contract for picking a sub-flow inside `aidd-orchestrator:00-async-dev`. The router walks these signals in order; the first match wins. --- -## 1. Explicit override — `$ARGUMENTS` keyword +## 1. Explicit override: the arguments keyword -If `$ARGUMENTS` contains exactly `setup`, `run`, or `review` as a standalone case-insensitive token, route there immediately. No fallback consideration. +If the arguments contain exactly `setup`, `run`, or `review` as a standalone case-insensitive token, route there immediately. No fallback consideration. This is the contract the bundled CI workflow relies on: @@ -15,7 +15,7 @@ prompt: "Use skill aidd-orchestrator:00-async-dev with action=run on issue #..." prompt: "Use skill aidd-orchestrator:00-async-dev with action=review on PR #..." ``` -The router parses `action=` from the prompt body. Plain `setup` / `run` / `review` words elsewhere in the body do NOT match — only the explicit `action=` form, or `$ARGUMENTS` set to exactly one of the three keywords. +The router parses `action=` from the prompt body. Plain `setup` / `run` / `review` words elsewhere in the body do NOT match, only the explicit `action=` form, or the arguments set to exactly one of the three keywords. --- @@ -62,17 +62,17 @@ Last-resort heuristic for free-form user input. --- -## Tie-break — most-specific signal wins +## Tie-break: most-specific signal wins When multiple signals match across categories: ```text -$ARGUMENTS keyword (1) > trigger env (2) > repo state (3) > NL intent (4) +Arguments keyword (1) > trigger env (2) > repo state (3) > NL intent (4) ``` Within a category, the most specific concrete signal wins: -- A PR number in `$ARGUMENTS` beats a label payload. +- A PR number in the arguments beats a label payload. - A label beats a free-text keyword. - A specific config file presence beats a generic verb. @@ -87,21 +87,21 @@ Examples: - **User says "run" but config is absent.** Surface the conflict and stop: `Setup must complete before run. Run /aidd-orchestrator:00-async-dev with action=setup first.` - **Workflow webhook fires `to-implement` but the issue already has an open closing PR.** - Route to `review` (the PR is the active surface). Comment on the issue: `Issue #N has open PR #M — routed to review instead of run. Apply the `to-review` label to PR #M to trigger review explicitly.` + Route to `review` (the PR is the active surface). Comment on the issue: `Issue #N has open PR #M, routed to review instead of run. Apply the `to-review` label to PR #M to trigger review explicitly.` - **Label `to-implement` AND label `to-review` both present.** Route to `review` (more specific to the PR lifecycle). Comment to clarify. --- -## Unresolved — ask the human +## Unresolved: ask the human If none of the above produces a single match, surface the three sub-flows with their triggers and ask: ```text Async-dev: which sub-flow? - - setup — install / configure async-dev in this repo - - run — implement a ready issue (labeled to-implement) - - review — iterate on review comments for an open PR + - setup , install / configure async-dev in this repo + - run , implement a ready issue (labeled to-implement) + - review , iterate on review comments for an open PR Reply with `setup`, `run`, or `review`. ``` diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md b/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md index 80b13652..707a0b1f 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md @@ -92,7 +92,7 @@ The daemon is fully decoupled from Claude Code's Tasks system; cancel it by kill Convenient when the backlog is small and you want everything inside Claude Code. **Counts against your Tasks quota; one tick = one task slot consumed**, so a 5-minute cadence may exhaust a daily/weekly limit faster than you expect. -1. Open Claude Code Desktop -> Scheduled tasks -> New task. +1. Open Claude Code Desktop → Scheduled tasks → New task. 2. Working directory: the absolute path of this repo. 3. Schedule: choose a cadence; remember the quota. 4. Prompt: `Run ./scripts/aidd-async-poll.sh and report what was processed.` diff --git a/plugins/aidd-pm/.claude-plugin/plugin.json b/plugins/aidd-pm/.claude-plugin/plugin.json index 85d082b9..3a7b6f51 100644 --- a/plugins/aidd-pm/.claude-plugin/plugin.json +++ b/plugins/aidd-pm/.claude-plugin/plugin.json @@ -2,14 +2,14 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-pm", "version": "2.0.0", - "description": "Product management: ticket-info, user-stories-create, prd, spec", + "description": "Product management: ticket-info, user-stories, prd, spec", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, "skills": [ "./skills/01-ticket-info", - "./skills/02-user-stories-create", + "./skills/02-user-stories", "./skills/03-prd", "./skills/04-spec" ], diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index e2860668..a262047f 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -9,7 +9,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) - [`skills/01-ticket-info`](#skills01-ticket-info) - - [`skills/02-user-stories-create`](#skills02-user-stories-create) + - [`skills/02-user-stories`](#skills02-user-stories) - [`skills/03-prd`](#skills03-prd) - [`skills/04-spec`](#skills04-spec) @@ -29,26 +29,32 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `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 ticket information from the configured ticketing tool. Use when the user says "ticket info", "show ticket", "get ticket", "ticket details", "what's ", or invokes `/ticket-info`. Do NOT use for creating issues, commenting on tickets, changing status, or reassigning.` | +| `-` | [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-create` +#### `skills/02-user-stories` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-create-user-stories.md](skills/02-user-stories-create/actions/01-create-user-stories.md) | - | - | -| `assets` | [user-story-template.md](skills/02-user-stories-create/assets/user-story-template.md) | `Template for defining user stories with estimation and acceptance criteria` | - | -| `-` | [README.md](skills/02-user-stories-create/README.md) | - | - | -| `-` | [SKILL.md](skills/02-user-stories-create/SKILL.md) | `Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-clarify-scope.md](skills/02-user-stories/actions/01-clarify-scope.md) | - | +| `actions` | [02-split-epic.md](skills/02-user-stories/actions/02-split-epic.md) | - | +| `actions` | [03-draft-stories.md](skills/02-user-stories/actions/03-draft-stories.md) | - | +| `actions` | [04-estimate-impact.md](skills/02-user-stories/actions/04-estimate-impact.md) | - | +| `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.` | #### `skills/03-prd` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | - | -| `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | `Product Requirements Document template (15 sections)` | - | -| `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 feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code.` | - | +| Group | File | Description | +|-------|------|---| +| `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` @@ -58,5 +64,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec.` | +| `-` | [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 acd14027..1edfea84 100644 --- a/plugins/aidd-pm/README.md +++ b/plugins/aidd-pm/README.md @@ -15,6 +15,6 @@ 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-create](skills/02-user-stories-create/README.md) | Generate INVEST-compliant user stories from a feature description. | +| [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. | diff --git a/plugins/aidd-pm/skills/01-ticket-info/SKILL.md b/plugins/aidd-pm/skills/01-ticket-info/SKILL.md index 9ef4743c..a9e72bcb 100644 --- a/plugins/aidd-pm/skills/01-ticket-info/SKILL.md +++ b/plugins/aidd-pm/skills/01-ticket-info/SKILL.md @@ -1,37 +1,21 @@ --- name: 01-ticket-info -description: Retrieve and display ticket information from the configured ticketing tool. Use when the user says "ticket info", "show ticket", "get ticket", "ticket details", "what's ", or invokes `/ticket-info`. Do NOT use for creating issues, commenting on tickets, changing status, or reassigning. +description: 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. --- # Ticket Info Reads ticket details from the configured ticketing tool. Read-only and tool-agnostic. -## Available actions +## Actions | # | Action | Role | Input | | --- | -------------- | ------------------------------------------------------------- | ---------------------------------- | | 01 | `ticket-info` | Resolve ticket id, query the configured tool, display fields | ticket_id (optional) | -## Default flow - -Single action skill. The router dispatches to `ticket-info` whenever a ticket-lookup phrase appears. - ## Transversal rules - Read the configured ticketing tool from project memory first; otherwise inspect repo configuration or environment. - Auto-detect the ticket identifier from the current branch name when none is provided. - Format the identifier per project convention before querying. - Read-only: never create, comment, transition, or reassign from this skill. - -## References - -- None. - -## Assets - -- None. - -## External data - -- None. diff --git a/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md b/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md index de7b228c..477b8aa7 100644 --- a/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md +++ b/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md @@ -2,38 +2,23 @@ Resolve the ticket identifier, query the configured ticketing tool, and display the relevant fields. -## Inputs +## Input -```yaml -ticket_id: # optional; auto-detect from current branch name when omitted -``` +An optional ticket id or URL. When omitted, auto-detect it from the current branch name. -## Outputs +## Output -```yaml -ticket_id: -title: -description: <body> -status: <status> -assignee: <assignee> -priority: <priority> -url: <url> -``` +The ticket's title, description, status, assignee, priority, and URL, displayed for the user. ## Process -1. **Tool resolution**. Pick first match: - - ticketing tool declared in project memory -> use it - - default -> inspect repo configuration or environment for the configured tool -2. **Ticket identifier**. Pick first match: - - `ticket_id` provided -> use it - - default -> extract from `git rev-parse --abbrev-ref HEAD` per project convention -3. **Format**. Apply the project ticketing convention to the identifier (prefix, separator, casing). -4. **Query**. Invoke the configured ticketing tool to fetch the ticket record. -5. **Display**. Render title, description, status, assignee, priority, and URL for the user. -6. **Return** the structured Outputs block. +1. **Tool.** Use the ticketing tool declared in project memory. Otherwise inspect the repo configuration or environment for the configured tool. +2. **Identifier.** Use the provided ticket id when given. Otherwise take it from the current branch name, per project convention. +3. **Format.** Apply the project ticketing convention to the identifier (prefix, separator, casing). +4. **Query.** Invoke the configured ticketing tool to fetch the ticket record. +5. **Display.** Render the title, description, status, assignee, priority, and URL. ## Test -- **Tool view**: querying the configured ticketing tool for the resolved id returns a record where `title`, `status`, `assignee`, and `url` match the displayed fields. -- **Reachable**: the ticket is reachable at `url` in the tracker. +- Querying the configured tool for the resolved id returns a record whose title, description, status, assignee, priority, and URL match the displayed fields. +- The ticket is reachable at its URL in the tracker. diff --git a/plugins/aidd-pm/skills/02-user-stories-create/README.md b/plugins/aidd-pm/skills/02-user-stories-create/README.md deleted file mode 100644 index c0038ec5..00000000 --- a/plugins/aidd-pm/skills/02-user-stories-create/README.md +++ /dev/null @@ -1,52 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 02 - Create User Stories - -Drafts INVEST-compliant user stories from a feature description through a -short Product Owner clarification loop, then saves them to the configured -ticketing tool once you validate the draft. - -## When to use - -- "user stories", "create user stories", "write user stories for X". -- "INVEST stories", "draft stories". -- Invoking `/user-stories-create`. -- 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-create for <feature description> -``` - -The skill clarifies in at most 3 questions per round, drafts the stories, -shows them for explicit validation, then saves on confirmation. - -## Outputs - -- A set of INVEST-compliant user stories, each with acceptance criteria, - dependencies, and story points. -- Stories sorted by implementation priority. -- One ticket per story created in the configured ticketing tool 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, -[`actions/01-create-user-stories.md`](actions/01-create-user-stories.md) for -the single atomic action, and -[`assets/user-story-template.md`](assets/user-story-template.md) for the -story body template. diff --git a/plugins/aidd-pm/skills/02-user-stories-create/SKILL.md b/plugins/aidd-pm/skills/02-user-stories-create/SKILL.md deleted file mode 100644 index 1286159a..00000000 --- a/plugins/aidd-pm/skills/02-user-stories-create/SKILL.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: 02-user-stories-create -description: Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker. ---- - -# Create User Stories - -Drafts INVEST-compliant user stories from a feature description through Product Owner clarification. - -## Available actions - -| # | Action | Role | Input | -| --- | ----------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | -| 01 | `create-user-stories` | Clarify scope, draft stories, validate, save to the tracker | feature_description, existing_stories (optional) | - -## Default flow - -Single action skill. The router dispatches to `create-user-stories` whenever a story-generation phrase appears. - -## Transversal rules - -- **INVEST**: each story is Independent, Negotiable, Valuable, Estimable, Small, Testable. -- **Definition of Ready**: acceptance criteria, dependencies, story points, and zero blocking questions before save. -- **Lean clarification**: at most 3 questions per iteration; focus on user needs, not technical aspects. -- Stories are sorted by implementation priority. -- Always wait for explicit user validation before saving to the tracker. -- The save target is the configured ticketing tool from project memory. - -## References - -- None. - -## Assets - -- `@assets/user-story-template.md`: User story body template. - -## External data - -- None. diff --git a/plugins/aidd-pm/skills/02-user-stories-create/actions/01-create-user-stories.md b/plugins/aidd-pm/skills/02-user-stories-create/actions/01-create-user-stories.md deleted file mode 100644 index d81d1506..00000000 --- a/plugins/aidd-pm/skills/02-user-stories-create/actions/01-create-user-stories.md +++ /dev/null @@ -1,41 +0,0 @@ -# 01 - Create User Stories - -Clarify scope through iterative Product Owner questioning, draft INVEST-compliant user stories, validate with the user, then save them to the configured ticketing tool. - -## Inputs - -```yaml -feature_description: <free text> # required; the feature or requirement to break into stories -existing_stories: [<id>] # optional; ids of related stories to consider -``` - -## Outputs - -```yaml -stories: - - id: <tracker id> - title: <user story title> - story: As a <persona>, I want <goal>, so that <reason>. - acceptance_criteria: - - <criterion> - story_points: <int> - priority: <int> - url: <tracker url> -``` - -## Process - -1. **Clarify**. Ask up to 3 questions per iteration to close gaps in problem, features, criteria, scope, and constraints. Skip technical detail. -2. **Iterate**. Pick first match: - - blocking question remains -> loop back to step 1 - - no blocking question -> proceed -3. **Draft**. Format each story with `assets/user-story-template.md`. Sort by implementation priority. -4. **Validate**. Show the full story list to the user. Wait for explicit approval. -5. **Save**. Invoke the configured ticketing tool to create each story; capture the returned id and url. -6. **Return** the structured Outputs block. - -## Test - -- **INVEST**: each story satisfies Independent, Negotiable, Valuable, Estimable, Small, Testable. -- **Ready**: every story has acceptance criteria, dependencies addressed, and story points set. -- **Persisted**: querying the configured ticketing tool returns each saved story id with matching title. diff --git a/plugins/aidd-pm/skills/02-user-stories-create/assets/user-story-template.md b/plugins/aidd-pm/skills/02-user-stories-create/assets/user-story-template.md deleted file mode 100644 index 91920632..00000000 --- a/plugins/aidd-pm/skills/02-user-stories-create/assets/user-story-template.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -name: user-story -description: Template for defining user stories with estimation and acceptance criteria -argument-hint: N/A ---- - -# [Epic Name] - -## US-[ID]: "[User Story Title]" - -**As a** [role] -**I want** [action] -**So that** [outcome] - -### Acceptance Criteria - -```gherkin -Scenario: [Error condition] - Given [error context] - When [error trigger] - Then [graceful error handling] - -Scenario: [Boundary condition] - Given [edge case context] - When [edge action] - Then [expected behavior] -``` diff --git a/plugins/aidd-pm/skills/02-user-stories/README.md b/plugins/aidd-pm/skills/02-user-stories/README.md new file mode 100644 index 00000000..95763b00 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/README.md @@ -0,0 +1,58 @@ +← [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 <feature or epic description> +``` + +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/02-user-stories/SKILL.md b/plugins/aidd-pm/skills/02-user-stories/SKILL.md new file mode 100644 index 00000000..07bc41b6 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/SKILL.md @@ -0,0 +1,39 @@ +--- +name: 02-user-stories +description: 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. +argument-hint: clarify-scope | split-epic | draft-stories | estimate-impact | prioritize | sync-tracker +--- + +# User Stories + +Produces a prioritized backlog of INVEST-compliant user stories, each estimated for effort and impact and carrying a pragmatic functional Definition of Done, then saved to the project's configured tracker. + +## Actions + +| # | Action | Role | Input | +| --- | ----------------- | -------------------------------------------------------------------- | -------------------------------------- | +| 01 | `clarify-scope` | Clarify the request through Product Owner questioning; decide epic vs single story | feature or epic description | +| 02 | `split-epic` | Decompose the confirmed scope into candidate vertical-slice stories | confirmed scope from 01 | +| 03 | `draft-stories` | Write each candidate as an INVEST story with acceptance criteria and a functional DoD | candidate stories from 02 | +| 04 | `estimate-impact` | Rate each story for effort (points) and impact on the existing system | drafted stories from 03 | +| 05 | `prioritize` | Rank the backlog by value against effort and impact | estimated stories from 04 | +| 06 | `sync-tracker` | Gate on Definition of Ready, get explicit approval, save to the tracker | ranked backlog from 05 | + +Run `01 → 02 → 03 → 04 → 05 → 06`, passing each `## Test` first. A single story skips the epic split. + +## Transversal rules + +- **INVEST**: each story is Independent, Negotiable, Valuable, Estimable, Small, Testable. +- **Definition of Ready**: acceptance criteria, dependencies, story points, and an impact rating are set, with zero blocking questions, before save. +- **Definition of Done**: each story carries a pragmatic, functional DoD, observable user-facing conditions that mean the goal is met. Functional only, never technical delivery steps. +- **Lean clarification**: at most 3 questions per iteration; focus on user needs, not technical aspects. +- Always wait for explicit user validation before saving to the tracker. +- The save target is the configured ticketing tool from project memory; never assume a specific tool. + +## References + +- `references/rating.md`: INVEST, the Definition of Ready and functional Definition of Done, the minor/major/critic impact scale, and the prioritization method. + +## Assets + +- `assets/user-story-template.md`: user story body template. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/01-clarify-scope.md b/plugins/aidd-pm/skills/02-user-stories/actions/01-clarify-scope.md new file mode 100644 index 00000000..10f23943 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/actions/01-clarify-scope.md @@ -0,0 +1,25 @@ +# 01 - Clarify scope + +Close the gaps in the request through Product Owner questioning, then decide whether it is an epic or a single story. + +## Input + +A free-text feature or epic description. Optionally, ids of related existing stories to consider. + +## Output + +A confirmed scope statement: the problem, the in-scope outcomes, the named constraints, and a flag marking the request as an epic (multiple stories) or a single story. + +## Process + +1. **Read.** Restate the request in one sentence to surface the implicit need. +2. **Question.** Cover problem, outcomes, criteria, scope edges, and constraints. +3. **Iterate.** If a blocking question remains, loop back to step 2. Otherwise proceed. +4. **Classify.** Judge the breadth. Flag the request as an epic when it spans more than one independent outcome, otherwise as a single story. +5. **Confirm.** Show the scope statement and the epic-or-single flag. Wait for the user to confirm before handing to `02-split-epic`. + +## Test + +- The output names the problem, the in-scope outcomes, and the constraints. +- The output carries an explicit epic-or-single flag confirmed by the user. +- No blocking question is left open when the action proceeds. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md b/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md new file mode 100644 index 00000000..59817d81 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md @@ -0,0 +1,25 @@ +# 02 - Split epic + +Decompose the confirmed scope into candidate stories, each a vertical slice that delivers value on its own. + +## Input + +The confirmed scope statement and epic-or-single flag from `01-clarify-scope`. + +## Output + +An ordered list of candidate stories, each a title plus a one-line user goal. A single-story request yields exactly one candidate. + +## Process + +1. **Branch.** If the flag marks a single story, emit one candidate from the scope and stop. Otherwise continue. +2. **Slice.** Cut the epic along user outcomes, not technical layers. Each slice must deliver something a user can perceive. +3. **Check independence.** Reshape any slice that cannot ship without another, so each candidate stands alone (see `@../references/rating.md`). +4. **Name.** Give each candidate a short title and a one-line goal in user terms. +5. **Confirm.** Show the candidate list and wait for the user to confirm before handing to `03-draft-stories`. + +## Test + +- Each candidate is a vertical slice with a user-perceivable outcome. +- A single-story input produces exactly one candidate. +- No candidate depends on another candidate to deliver its value. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md b/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md new file mode 100644 index 00000000..06943b70 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md @@ -0,0 +1,25 @@ +# 03 - Draft stories + +Write each candidate as a full INVEST story with acceptance criteria and a pragmatic functional Definition of Done. + +## Input + +The confirmed candidate list from `02-split-epic`. + +## Output + +One drafted story per candidate, each filling `@../assets/user-story-template.md`: the As-a/I-want/So-that statement, Gherkin acceptance criteria, and a functional DoD. + +## Process + +1. **Frame.** Write the As-a/I-want/So-that statement, naming the role, the action, and the outcome. +2. **Criteria.** Write Gherkin scenarios covering at least one nominal case and one error or boundary case. +3. **Done.** Write the functional DoD per `@../references/rating.md`: observable, user-facing conditions only, never technical delivery steps. +4. **Check INVEST.** Verify each story against the six criteria in `@../references/rating.md`. Reshape any story that fails. +5. **Fill.** Render each story into `@../assets/user-story-template.md`, leaving estimation fields for `04-estimate-impact`. + +## Test + +- Each story has an As-a/I-want/So-that statement and at least one Gherkin scenario. +- Each story has a functional DoD whose bullets are user-facing, with no technical delivery step. +- Each story satisfies all six INVEST criteria. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md b/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md new file mode 100644 index 00000000..cf37ce63 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md @@ -0,0 +1,23 @@ +# 04 - Estimate impact + +Rate each story for effort and for its impact on the existing system. + +## Input + +The drafted stories from `03-draft-stories`. + +## Output + +Each story annotated with story points, its dependencies (named or confirmed absent), an impact rating of minor, major, or critic, and a one-line rationale for the impact. + +## Process + +1. **Estimate effort.** Assign story points reflecting relative size. Flag any story too large to size and send it back to `02-split-epic`. +2. **Rate impact.** Assign minor, major, or critic per the impact scale in `@../references/rating.md`. +3. **Justify.** Write a one-line rationale for each impact rating. +4. **Record.** Fill the estimation block in `@../assets/user-story-template.md` for each story. + +## Test + +- Each story carries a numeric story-point value. +- Each story carries an impact rating in {minor, major, critic} with a one-line rationale. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md b/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md new file mode 100644 index 00000000..ec5b98f2 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md @@ -0,0 +1,23 @@ +# 05 - Prioritize + +Rank the backlog by value against effort, breaking ties with impact. + +## Input + +The estimated stories from `04-estimate-impact`. + +## Output + +The stories as a single ordered list, each with a priority rank, ordered by the method in `@../references/rating.md`. + +## Process + +1. **Score.** For each story, weigh delivered value against its story points. +2. **Order.** Sort by descending value-to-effort, then break ties with the lower impact first, per `@../references/rating.md`. +3. **Override.** Pull a story earlier only when a later story depends on it. State that reason on the affected story. +4. **Rank.** Write the priority rank into each story's estimation block. + +## Test + +- The output is a strictly ordered list with a unique rank per story. +- The ranking key is stated, and any dependency-driven override names its reason. diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md b/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md new file mode 100644 index 00000000..eb355962 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md @@ -0,0 +1,25 @@ +# 06 - Sync tracker + +Gate the backlog on the Definition of Ready, get explicit approval, then save each story to the configured tracker. + +## Input + +The ranked backlog from `05-prioritize`. + +## Output + +One ticket per story created in the configured tracker, each capturing the returned id and url. + +## Process + +1. **Resolve target.** Read the active ticketing tool from project memory. If none is declared, ask the user which tracker to use rather than assuming one. +2. **Gate.** Check every story against the Definition of Ready in `@../references/rating.md`. Send any failing story back to its action. Do not proceed while one fails. +3. **Present.** Show the full ranked backlog. Wait for explicit user approval before any write. +4. **Save.** On approval, create one ticket per story in the resolved tracker. Capture the returned id and url for each. +5. **Report.** Return the created stories with their ids and urls, in priority order. + +## Test + +- After approval, querying the configured tracker returns each saved story id with a matching title. +- The Definition of Ready holds for every saved story. +- No write happens before explicit user approval. diff --git a/plugins/aidd-pm/skills/02-user-stories/assets/user-story-template.md b/plugins/aidd-pm/skills/02-user-stories/assets/user-story-template.md new file mode 100644 index 00000000..f6583b2d --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/assets/user-story-template.md @@ -0,0 +1,33 @@ +# [Epic name] + +## US-[ID]: "[User story title]" + +**As a** [role] +**I want** [action] +**So that** [outcome] + +### Acceptance criteria + +```gherkin +Scenario: [Nominal case] + Given [context] + When [action] + Then [expected outcome] + +Scenario: [Error or boundary case] + Given [edge context] + When [edge trigger] + Then [graceful handling] +``` + +### Definition of Done (functional) + +- [User-facing condition the user can now confirm] +- [Another observable outcome] + +### Estimation + +- **Story points**: [int] +- **Impact**: [minor | major | critic] — [one-line rationale] +- **Dependencies**: [story ids, or none] +- **Priority**: [rank] diff --git a/plugins/aidd-pm/skills/02-user-stories/references/rating.md b/plugins/aidd-pm/skills/02-user-stories/references/rating.md new file mode 100644 index 00000000..2089d4a1 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/references/rating.md @@ -0,0 +1,57 @@ +# Rating and readiness + +The definitions every action in this skill relies on. Read this before drafting, estimating, prioritizing, or saving. + +## INVEST + +Each story must satisfy all six: + +- **Independent**: it can ship without waiting on another story in the batch. +- **Negotiable**: it states the need, not a frozen solution. +- **Valuable**: it delivers an outcome a user or stakeholder can perceive. +- **Estimable**: the team can size it without unresolved unknowns. +- **Small**: it fits inside one iteration. +- **Testable**: its acceptance criteria can be checked objectively. + +## Definition of Ready + +A story is ready to save when all hold: + +- Acceptance criteria are written and testable. +- Dependencies are named or confirmed absent. +- Story points are set. +- An impact rating is assigned. +- No blocking question remains open. + +## Functional Definition of Done + +Each story carries a pragmatic, functional DoD. + +- It lists observable, user-facing conditions that mean the goal is achieved. +- It is phrased from the user's side: what the user can now do, see, or avoid. +- It stays functional. It never lists technical delivery steps such as code review, test coverage, or deployment. +- Keep it short: two to four bullets that a non-technical stakeholder can confirm. + +Example for a password-reset story: + +- The user requests a reset and receives the link within one minute. +- Following the link lets the user set a new password and sign in with it. +- An expired or reused link shows a clear message and offers a fresh request. + +## Impact scale + +Rate each story by its impact on the existing system. This is a risk signal, not the effort estimate. + +- **minor**: additive or isolated. It touches no existing behavior users already rely on. +- **major**: it changes existing behavior, a shared component, or a public contract. Existing flows need re-checking. +- **critic**: it touches a critical path (auth, payments, data integrity) or risks data loss or downtime. It needs explicit review before build. + +State a one-line rationale with every rating. + +## Prioritization + +Rank the backlog by value against effort, then break ties with impact. + +- Order by descending value-to-effort ratio. +- On a tie, the lower-impact story ranks first, since it ships with less risk. +- A `critic` story may be pulled earlier only when later stories depend on it; state that reason when it happens. diff --git a/plugins/aidd-pm/skills/03-prd/README.md b/plugins/aidd-pm/skills/03-prd/README.md index bb4576a3..9e1a59a3 100644 --- a/plugins/aidd-pm/skills/03-prd/README.md +++ b/plugins/aidd-pm/skills/03-prd/README.md @@ -16,7 +16,7 @@ Stays at the "what and why" level; never crosses into implementation detail. ## When NOT to use -- To write user stories → use `02-user-stories-create`. +- 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. diff --git a/plugins/aidd-pm/skills/03-prd/SKILL.md b/plugins/aidd-pm/skills/03-prd/SKILL.md index d2e4b193..a43e12d0 100644 --- a/plugins/aidd-pm/skills/03-prd/SKILL.md +++ b/plugins/aidd-pm/skills/03-prd/SKILL.md @@ -1,39 +1,27 @@ --- name: 03-prd -description: Generate a structured Product Requirements Document from a feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code. +description: 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. --- # PRD Drafts a structured Product Requirements Document covering scope, goals, and acceptance criteria. -## Available actions +## Actions | # | Action | Role | Input | | --- | ------- | ---------------------------------------------------- | ----------------------------------------------- | | 01 | `prd` | Parse input, draft per template, validate, save | feature_description, user_stories (optional) | -## Default flow - -Single action skill. The router dispatches to `prd` whenever a PRD-generation phrase appears. - ## Transversal rules - Focus on what and why; never include technical implementation detail. - Sections stay concise and actionable. - Always wait for explicit user validation before saving. - Save path: `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`. -- Source of truth for structure: `@assets/prd-template.md`. - -## References - -- None. +- Source of truth for structure: `assets/prd-template.md`. ## Assets -- `@assets/prd-template.md`: PRD body template. -- `@assets/task-template.md`: Lightweight task template referenced from the PRD when needed. - -## External data - -- None. +- `assets/prd-template.md`: PRD body template. +- `assets/task-template.md`: Lightweight task template referenced from the PRD when needed. diff --git a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md index 2fd0c8a2..2ad3ec9e 100644 --- a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md +++ b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md @@ -1,40 +1,24 @@ # 01 - PRD -Parse the feature input, draft a structured PRD per the template, validate with the user, then save the file under `aidd_docs/tasks/`. - -## Inputs - -```yaml -feature_description: <free text> # required -user_stories: [<id or text>] # optional; existing stories to anchor the PRD -``` - -## Outputs - -```yaml -prd_path: aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md -feature_name: <kebab-case slug> -sections_present: - - overview - - problem-statement - - goals - - non-goals - - user-stories - - acceptance-criteria - - dependencies - - open-questions -``` +Parse the feature input, draft a structured PRD from the template, validate with the user, then save the file under `aidd_docs/tasks/`. + +## Input + +A feature description (required), and optionally existing user stories (ids or text) to anchor the PRD. + +## Output + +The saved PRD at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`, carrying all eight sections. ## Process -1. **Parse input**. Extract feature scope, goals, and constraints from `feature_description` (and `user_stories` when provided). -2. **Draft**. Fill `assets/prd-template.md` with all 8 sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions. -3. **Validate**. Show the full draft to the user. Wait for explicit approval. Apply revisions and re-show on each iteration. -4. **Save**. Write the approved PRD to `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`. Create the month directory when missing. -5. **Return** the structured Outputs block. +1. **Parse.** Extract the feature scope, goals, and constraints from the description and any user stories. +2. **Draft.** Fill `@../assets/prd-template.md` with its eight sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions. +3. **Validate.** Show the full draft, wait for explicit approval, and re-show after each revision. +4. **Save.** Write the approved PRD to its dated path, creating the month directory when missing. ## Test -- **File saved**: `prd_path` exists on disk after the action completes. -- **All sections**: the file contains the 8 required headings listed in `sections_present`. -- **No implementation**: the file has no `## Implementation` heading and no source code blocks describing how to build the feature. +- The PRD file exists on disk after the action completes. +- It contains the eight headings: Overview, Problem Statement, Goals, Non-Goals, User Stories, Acceptance Criteria, Dependencies, Open Questions. +- It has no solution detail: no tech-stack, data-model, or architecture section, no `## Implementation` heading, and no source code. diff --git a/plugins/aidd-pm/skills/03-prd/assets/prd-template.md b/plugins/aidd-pm/skills/03-prd/assets/prd-template.md index 2e5db7b2..65a93b9e 100644 --- a/plugins/aidd-pm/skills/03-prd/assets/prd-template.md +++ b/plugins/aidd-pm/skills/03-prd/assets/prd-template.md @@ -1,319 +1,37 @@ ---- -name: prd -description: Product Requirements Document template (15 sections) -argument-hint: N/A ---- +<!-- Product Requirements Document template (8 sections). Solution-agnostic: what and why, never how. Fill the placeholders; do not copy this comment. --> -# [Project name] - [version] +# [Project name] -[Full Summary of the app and features we are willing to code.] +[One or two sentences: the product or feature and the problem it solves.] -## 1. Executive Summary +## Overview -### Problem +[The context and the value. Who it is for and why it matters now. No solution detail.] -[What problem are we solving?] +## Problem Statement -### Solution +[The user or business problem, stated as a need. The pain today and its cost. No proposed implementation.] -[What are we building?] +## Goals -### Success Criteria +[The outcomes this must achieve, each observable and measurable. What success looks like, not how to build it.] -[How do we know we've succeeded?] +## Non-Goals -## 2. User Personas +[What is explicitly out of scope, so the boundary is unambiguous.] -### Primary Persona: [Name] +## User Stories -| Attribute | Description | -| ------------------------- | ----------------------------- | -| **Role** | [Job title or user type] | -| **Goals** | [What they want to achieve] | -| **Motivations** | [Why they use the product] | -| **Frustrations** | [Current pain points] | -| **Technical Environment** | [Devices, tools, constraints] | +[The needs as user stories: "As a [persona], I want [goal], so that [reason]." One per line, no technical detail.] -### Secondary Persona: [Name] +## Acceptance Criteria -| Attribute | Description | -| ---------------- | --------------------------- | -| **Role** | [Job title or user type] | -| **Goals** | [What they want to achieve] | -| **Motivations** | [Why they use the product] | -| **Frustrations** | [Current pain points] | +[The conditions that make the product correct, observable and user-facing. Behavior, not code.] -## 3. Goals & Objectives +## Dependencies -### Business Goals +[External constraints, data, approvals, or other work this depends on. Business and product dependencies, not a tech stack.] -- BG1: [Revenue/growth goal] -- BG2: [User acquisition/retention] +## Open Questions -### Technical Goals - -- TG1: [Performance/scalability] -- TG2: [Security/reliability] - -### User Goals - -- UG1: [User experience improvement] -- UG2: [Efficiency/productivity gain] - -## 4. Core Features - -Group of identified features to build: - -- **Feature 1**: [Short description] - -### [Feature/Module 1] - -- FR1.1: [Specific requirement] -- FR1.2: [Specific requirement] - -#### User Stories - -- As a [user type], I want to [action] so that [benefit] - -## 5. Acceptance Criteria - -> Define testable criteria for each core feature using the Gherkin format (Given-When-Then). - -### Feature 1: [Feature Name] - -**Happy Path:** - -```gherkin -Scenario: [Description] - Given [initial context] - When [action performed] - Then [expected result] - And [additional verification] -``` - -**Error Scenarios:** - -```gherkin -Scenario: [Error case description] - Given [error context] - When [action that causes error] - Then [error handling behavior] -``` - -**Edge Cases:** - -- [ ] [Edge case 1] -- [ ] [Edge case 2] - -## 6. Non-Goals - -> What we are intentionally NOT building in this version. This prevents scope creep. - -| Non-Goal | Rationale | -| ----------- | ------------------------------ | -| [Feature X] | [Why we're not building it] | -| [Feature Y] | [Why it's out of scope] | -| [Feature Z] | [Why it's explicitly excluded] | - -## 7. Non-Functional Requirements - -For every given features: - -### Performance - -- NFR1: [Response time targets] -- NFR2: [Throughput requirements] -- NFR3: [Scalability needs] - -### Security - -- NFR4: [Authentication/authorization] -- NFR5: [Data protection] -- NFR6: [Compliance requirements] - -### Usability - -- NFR7: [Accessibility standards (WCAG)] -- NFR8: [Browser/device support] - -## 8. Technical Architecture - -### Tech Stack - -- **Frontend**: [Framework, UI library] -- **Backend**: [Language, framework] -- **Database**: [Type, specific system] -- **Infrastructure**: [Cloud, containers] -- **External Services**: [APIs, SaaS] - -### Data Model - -``` -[Key entities and relationships] -[Data flow diagram if needed] -``` - -### Integration Points - -- **Internal APIs**: [List] -- **External APIs**: [List with rate limits] -- **Data Sources**: [Databases, files, streams] - -## 9. User Experience - -### Information Architecture - -[Site map or app structure] - -### Key User Flows - -1. [Primary flow description] -2. [Secondary flow description] - -### Design System - -- **Visual**: [Colors, typography, spacing] -- **Components**: [Reusable UI elements] -- **Patterns**: [Interaction patterns] -- **Responsive**: [Breakpoints, mobile-first?] - -## 10. Success Metrics - -### Business KPIs - -| Metric | Current | Target | Date | -| ---------- | ---------- | -------- | ------ | -| [Metric 1] | [Baseline] | [Target] | [Date] | -| [Metric 2] | [Baseline] | [Target] | [Date] | - -### Technical KPIs - -| Metric | Current | Target | -| --------------- | ---------- | -------- | -| [Response time] | [Baseline] | [Target] | -| [Uptime] | [Baseline] | [Target] | - -### User KPIs - -| Metric | How Measured | Target | -| ------------------- | ------------ | -------- | -| [User satisfaction] | [Method] | [Target] | -| [Task completion] | [Method] | [Target] | - -## 11. Dependencies - -> External dependencies that must be resolved or coordinated. - -### Technical Dependencies - -| Dependency | Owner | Status | Risk | -| -------------------- | ------------- | ------------------- | ----------------- | -| [API from Team X] | [Team/Person] | [Available/Pending] | [High/Medium/Low] | -| [Database migration] | [Team/Person] | [Status] | [Risk level] | - -### External Dependencies - -| Dependency | Provider | Status | Fallback | -| ------------------ | ---------- | ------------------- | --------------- | -| [Third-party API] | [Provider] | [Available/Pending] | [Alternative] | -| [SaaS integration] | [Provider] | [Status] | [Fallback plan] | - -## 12. Experiments / A/B Testing - -> Hypotheses to validate and experiments to run. - -| Hypothesis | Experiment | Metric | Success Criteria | -| --------------------------------- | ---------------------- | ----------------- | -------------------- | -| [If we do X, then Y will improve] | [A/B test description] | [Metric to track] | [Target improvement] | -| [Users prefer X over Y] | [Test approach] | [Metric] | [Success threshold] | - -### Experiment Plan - -- **Phase 1**: [% of users] - [Duration] -- **Phase 2**: [% of users] - [Duration] -- **Full rollout criteria**: [Conditions for 100% rollout] - -## 13. Timeline & Milestones - -| Milestone | Objective | Deliverable | Target Date | Go/No-Go Criteria | -| ---------- | ----------------- | ----------------- | ----------- | --------------------- | -| M1: [Name] | [What we achieve] | [What we deliver] | [Date] | [Criteria to proceed] | -| M2: [Name] | [What we achieve] | [What we deliver] | [Date] | [Criteria to proceed] | -| M3: [Name] | [What we achieve] | [What we deliver] | [Date] | [Criteria to proceed] | - -### Critical Path - -```mermaid -flowchart LR - M1["M1: Foundation"] --> M2["M2: Core Features"] - M2 --> M3["M3: Polish & Launch"] -``` - -## 14. Risks & Mitigations - -| Risk | Probability | Impact | Mitigation Plan | Owner | -| ---------------- | --------------- | --------------- | ----------------------- | -------- | -| [Technical risk] | High/Medium/Low | High/Medium/Low | [How to prevent/handle] | [Person] | -| [Business risk] | High/Medium/Low | High/Medium/Low | [How to prevent/handle] | [Person] | -| [Timeline risk] | High/Medium/Low | High/Medium/Low | [How to prevent/handle] | [Person] | - -### Contingency Plans - -- **If [Risk 1] occurs**: [Contingency action] -- **If [Risk 2] occurs**: [Contingency action] - -## 15. Scope Boundaries (3 Tiers) - -### Tier 1 - MVP (Must Have) - -> What is included in the first release. - -| Feature | Rationale | -| ----------- | -------------- | -| [Feature 1] | [Why it's MVP] | -| [Feature 2] | [Why it's MVP] | - -### Tier 2 - Next Release (Should/Could Have) - -> What is explicitly deferred to V2. Each feature has a promotion trigger. - -| Feature | Rationale | Promotion Trigger | -| ----------- | -------------- | ------------------------------------------ | -| [Feature X] | [Why deferred] | [Metric or condition to promote to Tier 1] | -| [Feature Y] | [Why deferred] | [Metric or condition] | - -### Tier 3 - Never (Won't Have) - -> What we will never build. - -| Feature | Rationale | -| ---------------- | ----------- | -| [Anti-pattern X] | [Why never] | -| [Anti-pattern Y] | [Why never] | - ---- - -## Appendix - -### Glossary - -- **Term**: Definition -- **Acronym**: Full meaning - -### References - -- [Related documents] -- [Design mockups] -- [Technical specs] - -### Open Questions - -- [ ] [Question needing answer] -- [ ] [Decision to be made] - ---- - -**Team**: [Size/roles] -**Timeline**: [Total duration] -**Priority**: [Critical/High/Medium/Low] -**Status**: [Draft/Approved/In Progress] +[Unresolved decisions and unknowns to settle before or during build.] diff --git a/plugins/aidd-pm/skills/03-prd/assets/task-template.md b/plugins/aidd-pm/skills/03-prd/assets/task-template.md index cdc9e1db..5f71ea95 100644 --- a/plugins/aidd-pm/skills/03-prd/assets/task-template.md +++ b/plugins/aidd-pm/skills/03-prd/assets/task-template.md @@ -7,7 +7,7 @@ description: Task tracking system to ensure all tasks are categorized and addres {{Full description}} -## Main step 1} +## Main step 1 - [ ] {Task 1} - [ ] {Task 2} diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md index 80d2829d..8a593136 100644 --- a/plugins/aidd-pm/skills/04-spec/README.md +++ b/plugins/aidd-pm/skills/04-spec/README.md @@ -2,17 +2,15 @@ # 04 - Spec -Generates or refines the immutable contract between human intent and the -downstream agents that will plan, implement, and review the work. The spec -is what a planner consumes; it stays free of implementation detail and is -locked once validated. +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 reviewer findings come back. +- "refine the spec" when review findings come back. - Invoking `/spec`. -- When an orchestrator needs a normalized contract before triggering a plan. ## When NOT to use @@ -29,7 +27,7 @@ Build a fresh spec from a request or an existing PRD: Use skill aidd-pm:04-spec build for <request or PRD path> ``` -Refine an existing spec from reviewer findings: +Refine an existing spec from review findings: ``` Use skill aidd-pm:04-spec refine on <spec path> with <findings> @@ -44,20 +42,19 @@ and `findings` triggers `refine`; otherwise `build` runs. with explicit non-goals, bulleted acceptance criteria, and `TBD: <precise question>` markers wherever information is missing. - On `refine`: the same file rewritten to address the supplied findings. -- The skill never self-validates; the caller spawns a reviewer using - [`assets/spec-validator.yml`](assets/spec-validator.yml) and feeds the - findings back through `refine` for the next iteration. +- 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 reviewer findings. + 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 atomic actions, -and [`assets/`](assets/) for the canonical template plus the validator -checklist used by reviewers. +[`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-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index b72ce125..a7621f49 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,45 +1,31 @@ --- name: 04-spec -description: Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec. +description: 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. +argument-hint: build | refine --- -# Spec +# Skill: spec -Generates or refines the immutable contract between human intent and downstream agents. +Generate or refine the immutable contract for a feature: its target, hard constraints, non-goals, and done-when. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | --------- | ----------------------------------------------------------------- | -------------------------------------- | -| 01 | `build` | Create a fresh spec from a free-form request or an existing PRD | request or prd_path, feature_name | -| 02 | `refine` | Rewrite an existing spec to address reviewer findings | existing_spec, findings | +| # | Action | Role | Input | +| --- | -------- | ---------------------------------------------------- | ---------------------------- | +| 01 | `build` | Draft a fresh spec from a request or an existing PRD | a request or a PRD path | +| 02 | `refine` | Rewrite an existing spec to address review findings | a spec path and the findings | -## Default flow - -Non-sequential. The router dispatches based on inputs: - -- `existing_spec` and `findings` present -> `refine` -- `request` or `prd_path` present -> `build` +Dispatch by input: a spec path with findings runs `refine`; a request or PRD path runs `build`. ## Transversal rules -- Never invent missing information. Mark every gap as `TBD: <precise question>` instead of guessing. -- If the request is too vague to draft a useful spec, return early and ask the user to brainstorm the request first; do not fabricate intent. -- Never modify a spec that has been validated and locked. -- The spec is the contract; it is immutable once validated. -- Keep the spec readable: clear section headers, bulleted criteria, explicit non-goals. -- Never include implementation detail (libraries, patterns, file layout); those belong to the plan. -- Do not self-validate. The caller spawns a reviewer with `@assets/spec-validator.yml`; findings come back through the `refine` action for the next iteration. - -## References - -- None. +- Never invent. Mark every gap as `TBD: <precise question>` rather than guessing. When a request is too vague to draft anything useful, stop and ask for a clearer one. +- The spec holds intent, never implementation. It is solution-agnostic: no file, component, hook, route, library, pattern, or token, and no "how". The done-when conditions are outcome-level, not steps. Keep the acceptance criteria few. All of that belongs to the plan. +- Keep it readable: clear section headers, bulleted criteria, explicit non-goals. +- Output: one `spec.md` in the feature folder (`aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/`), from `assets/spec-template.md`. Reuse the folder when it exists. +- Immutable once validated: never rewrite a spec that has been locked. ## Assets -- `@assets/spec-template.md`: canonical structure of a spec. -- `@assets/spec-validator.yml`: checklist used by the reviewer to validate a spec. - -## External data - -- None. +- `assets/spec-template.md`: the spec's structure. +- `assets/spec-validator.yml`: the checklist a spec is validated against. diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md index 43027534..dd7a521f 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -1,35 +1,25 @@ # 01 - Build -Create a fresh spec from a free-form request or by extracting fields from an existing PRD. +Draft a fresh spec from a free-form request, or by lifting fields from an existing PRD. -## Inputs +## Input -```yaml -request: <free-form human description> # required when prd_path is absent -prd_path: <path to an existing PRD file> # required when request is absent -feature_name: <kebab-case slug> # required; derived from the request when absent -``` +A free-form request, or a path to an existing PRD. A feature name for the folder, derived from the request when absent. -## Outputs +## Output -```yaml -spec_path: aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-spec.md -status: draft -notes: <ambiguities, assumptions made, questions for the human> -``` +The path to `spec.md` in the feature folder, drafted from the template, with the ambiguities and assumptions noted. ## Process -1. **Source resolution**. Pick first match: - - `prd_path` provided -> parse the PRD, lift target, hard constraints, non-goals, and done-when into the matching template sections; drop libraries, patterns, and file-layout content - - `request` provided -> use `assets/spec-template.md` directly and map the request onto its sections -2. **Mark gaps**. Replace any missing required field with `TBD: <precise question>`. Never guess. -3. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -4. **Write**. Save the spec to `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-spec.md`. Create the month directory when missing. -5. **Return** the structured Outputs block with `status: draft`. +1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. Do not explore the codebase. +2. **Gaps.** Replace any missing required field with `TBD: <precise question>`. Never guess. +3. **Check.** Confirm every section the validator requires is present. +4. **Write.** Resolve the feature folder, reusing it when it exists, and save the spec there as `spec.md`. +5. **Return.** Surface the spec path and the notes. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **No implementation**: the file has no library names, framework patterns, or source-file layout. +- `spec.md` exists in the feature folder. +- It contains every section the validator marks required in `@../assets/spec-validator.yml`. +- It carries no library name, framework pattern, or source-file layout. diff --git a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md index 3bf1f7c8..a44844dd 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md +++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md @@ -1,34 +1,24 @@ # 02 - Refine -Rewrite an existing spec in place to address reviewer findings. +Rewrite an existing spec in place to address review findings. -## Inputs +## Input -```yaml -existing_spec: <path to the current spec> # required -findings: <reviewer findings> # required; list or text -``` +The path to the current spec, and the findings to address, a list or free text. -## Outputs +## Output -```yaml -spec_path: <path to the refined spec.md> # same as existing_spec -status: refined -notes: <changes applied, residual TBD questions> -``` +The refined spec at the same path, with the changes applied and any residual `TBD` questions noted. ## Process -1. **Load**. Read `existing_spec` and `findings`. -2. **Map findings**. Pair each finding with the section of the spec it touches. -3. **Rewrite**. Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Preserve sections the findings do not touch. -4. **Mark gaps**. Replace any field still unanswered with `TBD: <precise question>`. Never guess. -5. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -6. **Write**. Save the refined spec back to the same path as `existing_spec` (overwrite). -7. **Return** the structured Outputs block with `status: refined`. +1. **Load.** Read the spec and the findings. +2. **Map.** Pair each finding with the section it touches. +3. **Rewrite.** Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Leave untouched sections as they are. +4. **Gaps.** Replace any field still unanswered with `TBD: <precise question>`. Never guess. +5. **Check.** Confirm every section the validator requires is present, then overwrite the spec at its path. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **Findings addressed**: every finding in `findings` is reflected by a change in the rewritten spec or by an explicit `TBD: <question>` if it cannot be resolved. +- The spec still exists at its path and holds every required section in `@../assets/spec-validator.yml`. +- Every finding is reflected by a change, or by an explicit `TBD: <question>` when it cannot be resolved. diff --git a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml index 364d0aba..1da8edd5 100644 --- a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml +++ b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml @@ -1,4 +1,4 @@ -# Checklist used by the reviewer agent to validate a spec. +# Checklist a spec is validated against. # Each criterion is independently scored. Required criteria must be `fulfilled` for the spec to pass. criteria: diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md index 153d6edd..bd5c4135 100644 --- a/plugins/aidd-refine/CATALOG.md +++ b/plugins/aidd-refine/CATALOG.md @@ -43,16 +43,17 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code.` | +| `-` | [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.` | #### `skills/02-challenge` | Group | File | Description | |-------|------|---| | `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 prior work to verify correctness against an agreed plan, classifying findings as deal-breakers, suggestions, or correct, with a confidence score. Use when 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", "find flaws", or asks for a critical review of just-completed work. Do NOT use for line-by-line code review against a style guide, implementing features, writing tests, or generating new code.` | +| `-` | [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.` | #### `skills/03-condense` @@ -62,7 +63,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 with intensity levels (lite, full, ultra) so prose drops articles, filler, and pleasantries while code, quoted errors, and security warnings stay verbatim. Also reports real token usage and estimated savings under condense mode for the current session. Use when the user says "condense", "condense output", "be more concise", "shorter answers", "tighten output", "/condense", "/condense full", "/condense ultra", "stop condense", "normal mode", "/condense-stats", "how much have we saved", or "token savings". Do NOT use for editing existing prose, summarizing a long document, or compressing source code (only output style is affected, not content).` | +| `-` | [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.` | #### `skills/04-shadow-areas` @@ -77,7 +78,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [locked-sets.json](skills/04-shadow-areas/references/locked-sets.json) | - | | `references` | [probe-style.md](skills/04-shadow-areas/references/probe-style.md) | - | | `references` | [severity-rubric.md](skills/04-shadow-areas/references/severity-rubric.md) | - | -| `-` | [SKILL.md](skills/04-shadow-areas/SKILL.md) | `Analytical scan of a markdown artifact (idea, user-stories, PRD, spec) to surface blind spots - unstated assumption, missing actor, missing failure mode, ambiguous term, missing acceptance criterion, missing edge case, and missing dependency - emitting a structured shadow report grouped by category and sorted by severity. Use when the user says "find blind spots in this spec", "what's missing in this PRD", "shadow report", "shadow analysis", "scan for gaps", "find what's missing", "spot blind spots", "review for gaps", or asks for an analytical gap scan of a written artifact. Do NOT use for interactive clarification through iterative Q&A (use aidd-refine:01-brainstorm for that), implementing features, writing tests, or reviewing code style.` | +| `-` | [SKILL.md](skills/04-shadow-areas/SKILL.md) | `Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow report grouped by category and severity. Use to find gaps or what is missing in a written artifact. Not for interactive Q&A or code review.` | #### `skills/05-fact-check` @@ -89,6 +90,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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) | - | -| `-` | [SKILL.md](skills/05-fact-check/SKILL.md) | `Verify factual claims in a piece of text against authoritative sources and rewrite it with footnote citations, hedging any claim that cannot be confirmed. Runs a cheapest-first verification cascade (project memory and docs, then codebase inspection, then web lookup) and reports both sources when they disagree. Use when the user says "fact-check this", "verify that claim", "are you sure about that", "is that actually true", "cite your sources", "where did you get that fact", "did you make that up", "double-check the version you gave me", "vérifie cette information", or "es-tu sûr de ça". Do NOT use to auto-guard the AI's own output (this skill only fires on an explicit request), to judge code logic correctness, or to clarify vague requirements through iterative Q&A - use `aidd-refine:01-brainstorm` for that.` | +| `-` | [SKILL.md](skills/05-fact-check/SKILL.md) | `Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging the unconfirmed. Use to fact-check, verify a claim, or cite sources on request. Not for judging code or clarifying requirements.` | diff --git a/plugins/aidd-refine/skills/01-brainstorm/README.md b/plugins/aidd-refine/skills/01-brainstorm/README.md index 74d23687..4ab29000 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/README.md +++ b/plugins/aidd-refine/skills/01-brainstorm/README.md @@ -18,7 +18,7 @@ Turns a vague idea into a precise one through a deep, natural conversation, at w ## 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 to a dated file under `aidd_docs/brainstorm/`, a ticket, or the session only. +`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 diff --git a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md index d7d77ef6..9e095250 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md +++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md @@ -1,6 +1,7 @@ --- name: 01-brainstorm -description: Clarify a vague idea through deep back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code. +description: 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. +argument-hint: capture | probe | integrate | finalize --- # Brainstorm @@ -16,9 +17,7 @@ Turns a vague idea into a precise one through a deep, natural conversation. Each | 03 | `integrate` | Fold answers in, judge if real ambiguity remains | answers + the idea | | 04 | `finalize` | Consolidate, flag open assumptions, offer to persist | the clarified idea | -## Default flow - -`capture` once, then loop `probe → integrate` until no real ambiguity remains or the user is satisfied, then `finalize`. There is no fixed round count, the idea is done when it is clear, not on a timer. Run each action's `## Test` before the next. +Run `capture`, loop `probe → integrate` until the idea is clear, then `finalize`. ## Transversal rules diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md index 401e7a2d..bf4ece30 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md @@ -8,7 +8,7 @@ The clarified idea and the conversation so far. ## Output -The approved refined idea with its flagged open assumptions and risks, a pointer to the fitting next step, and, when the user picks the file, a markdown file at `aidd_docs/brainstorm/<yyyy_mm_dd>-<slug>.md`. +The approved refined idea with its flagged open assumptions and risks, a pointer to the fitting next step, and, when the user picks the file, a markdown file at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/brainstorm.md`. ## Process @@ -17,16 +17,16 @@ The approved refined idea with its flagged open assumptions and risks, a pointer 3. **Get approval.** Show the refined idea and the open list, and ask the user to confirm or correct. Wait for the answer. 4. **Point to the next move.** Say in plain words what the refined idea is now ready for, planning it, specifying it, or building it, so the user's next request reaches the right tool on its own. Describe the move, never name a plugin or skill, and never run it. 5. **Offer to persist.** Once approved, present all three destinations and act on the pick. Name all three, persist nothing without the user's choice. - - **File.** Write the document to exactly `aidd_docs/brainstorm/<yyyy_mm_dd>-<slug>.md`, where `<yyyy_mm_dd>` is today's date and `<slug>` is the idea in kebab-case. The directory and format are fixed, never another path or name. Create `aidd_docs/brainstorm/` if missing. + - **File.** Write the document to the feature folder as `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/brainstorm.md`, where `<yyyy_mm_dd>` is today's date and `<slug>` is the idea in kebab-case. Reuse the feature folder when one already exists for this idea, otherwise create it. The format is fixed, never another name. | Idea, saved on | File written | | --- | --- | - | aidd-craft plugin, 2026-03-09 | `aidd_docs/brainstorm/2026_03_09-aidd-craft-plugin.md` | - | dark mode toggle, 2026-11-20 | `aidd_docs/brainstorm/2026_11_20-dark-mode-toggle.md` | + | aidd-craft plugin, 2026-03-09 | `aidd_docs/tasks/2026_03/2026_03_09_aidd-craft-plugin/brainstorm.md` | + | dark mode toggle, 2026-11-20 | `aidd_docs/tasks/2026_11/2026_11_20_dark-mode-toggle/brainstorm.md` | - **Ticket.** Open or append a ticket drawn from the memory and VCS context. - **Session.** Keep it in the conversation only, write nothing. ## Test - The output is a consolidated intent-level idea plus an explicit list of open assumptions and risks, approved by the user, and it names all three persist destinations and the fitting next move without a `plugin:skill` identifier. -- When the user picks the file, a file exists afterward at `aidd_docs/brainstorm/<yyyy_mm_dd>-<slug>.md` and nowhere else. +- When the user picks the file, a file exists afterward at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/brainstorm.md` and nowhere else. diff --git a/plugins/aidd-refine/skills/02-challenge/SKILL.md b/plugins/aidd-refine/skills/02-challenge/SKILL.md index 0a51675a..6487af3c 100644 --- a/plugins/aidd-refine/skills/02-challenge/SKILL.md +++ b/plugins/aidd-refine/skills/02-challenge/SKILL.md @@ -1,38 +1,28 @@ --- name: 02-challenge -description: Rethink prior work to verify correctness against an agreed plan, classifying findings as deal-breakers, suggestions, or correct, with a confidence score. Use when 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", "find flaws", or asks for a critical review of just-completed work. Do NOT use for line-by-line code review against a style guide, implementing features, writing tests, or generating new code. +description: 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. --- # Challenge Rethink prior work and surface what is wrong, missing, or duplicated. Output a structured report with a confidence score so the user knows whether to ship, iterate, or rework. -## Available actions +## Actions | # | Action | Role | Input | | --- | ----------- | ------------------------------------------------------------- | ------------------------------ | -| 01 | `challenge` | Rethink prior work, classify findings, score confidence | review_target + agreed_plan | - -## Default flow - -Single action skill. The router dispatches to `challenge` whenever the trigger phrases above appear. +| 01 | `challenge` | Rethink prior work, classify findings, score confidence | the work + agreed reference | ## Transversal rules -- Think in first principles. Every step must be logical, with no gap and no missing information. -- Challenge own assumptions and the user's decisions before declaring confidence. -- Look for edge cases, errors, inconsistencies, missing parts, duplications, and optimizations. +- Reason from first principles, no logical gaps. - Aim for simplifications. If the work can be smaller, say so. -- Output the structured report verbatim per the action's `## Outputs` block. +- Fill `assets/report-template.md` verbatim. ## References -- `@references/confidence-rubric.md`: tiered rubric for the confidence percentage. +- `references/confidence-rubric.md`: tiered rubric for the confidence percentage. ## Assets -- None. - -## External data - -- None. +- `assets/report-template.md`: findings report skeleton, filled per run. diff --git a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md index eae6932b..b7167e1a 100644 --- a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md +++ b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md @@ -2,39 +2,25 @@ Rethink prior work and verify correctness against an agreed plan, then emit a structured findings report. -## Inputs +## Input -- `review_target` (required): what to review. One of: last assistant turn, specific file paths, plan document, or commit range. -- `agreed_plan` (required): the prior agreement, specification, or set of requirements to compare against. +- The work to review: the last answer, specific files, a plan, or a commit range. +- The agreed reference to judge it against: a plan, a spec, or stated requirements. Without one, judge against stated user intent. -## Outputs +## Output -```text -My confidence level of correctness now: XX% - -# Previous work to review - -# Correctness (100%) -- - -# Deal breakers -- - -# Suggestions (enhancements only) -- -``` +The findings report following `@../assets/report-template.md`: a confidence percentage plus the Correctness, Deal breakers, and Suggestions sections. ## Process -1. Read `review_target` and align it against `agreed_plan`. -2. Challenge own assumptions and the user's decisions. -3. Scan for edge cases, errors, gaps, duplications, and inconsistencies. -4. Classify each finding as Correctness, Deal breaker, or Suggestion. -5. Score confidence per the rubric in `references/confidence-rubric.md`. -6. Emit the Output report verbatim. +1. **Align.** Read the work and line it up against the agreed reference. +2. **Challenge.** Challenge own assumptions and the user's decisions. +3. **Scan.** Scan for edge cases, errors, gaps, duplications, and inconsistencies. +4. **Classify.** Classify each finding as Correctness, Deal breaker, or Suggestion. +5. **Score.** Score confidence per the rubric in `@../references/confidence-rubric.md`. +6. **Emit.** Fill `@../assets/report-template.md` verbatim and emit it. ## Test -- The emitted report contains a confidence percentage and the three classification sections. -- `confidence >= 95%` if and only if the Deal breakers section is empty. -- The confidence value sits in the rubric tier consistent with the findings. +- The report has a confidence percentage and the Correctness, Deal breakers, and Suggestions sections. +- The Deal breakers section is non-empty only when confidence is below 75%. diff --git a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md new file mode 100644 index 00000000..a611f255 --- /dev/null +++ b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md @@ -0,0 +1,12 @@ +<!-- Challenge findings report skeleton. Fill each section verbatim, keep the header order. --> + +My confidence level of correctness now: XX% + +# Correctness (100%) +- + +# Deal breakers +- + +# Suggestions (enhancements only) +- diff --git a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md index ec220b4a..0d474d1b 100644 --- a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md +++ b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md @@ -4,7 +4,7 @@ The challenge action emits a confidence percentage. Pick the tier whose conditio | Tier | Condition | | --------- | ----------------------------------------------- | -| `100%` | No deal breakers, no gaps, no missing parts. | +| `100%` | No deal breakers, no gaps, no missing parts, no suggestions. | | `75-95%` | Suggestions only, no blockers. | | `50-74%` | Minor deal breakers, all fixable in place. | | `<50%` | Major deal breakers, partial rework required. | diff --git a/plugins/aidd-refine/skills/03-condense/SKILL.md b/plugins/aidd-refine/skills/03-condense/SKILL.md index 67533545..0de0fbdb 100644 --- a/plugins/aidd-refine/skills/03-condense/SKILL.md +++ b/plugins/aidd-refine/skills/03-condense/SKILL.md @@ -1,47 +1,33 @@ --- name: 03-condense -description: Toggle terse output mode with intensity levels (lite, full, ultra) so prose drops articles, filler, and pleasantries while code, quoted errors, and security warnings stay verbatim. Also reports real token usage and estimated savings under condense mode for the current session. Use when the user says "condense", "condense output", "be more concise", "shorter answers", "tighten output", "/condense", "/condense full", "/condense ultra", "stop condense", "normal mode", "/condense-stats", "how much have we saved", or "token savings". Do NOT use for editing existing prose, summarizing a long document, or compressing source code (only output style is affected, not content). +description: 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. +argument-hint: condense | stats --- # Condense Toggles a terse output mode with three intensity levels (lite, full, ultra). Strips articles, filler, and pleasantries from prose while preserving technical substance, code blocks, quoted errors, and security warnings. -## Available actions +## Actions | # | Action | Role | Input | | --- | ---------- | --------------------------------------------------------------------- | ------------------------------------ | -| 01 | `condense` | Toggle terse mode and apply intensity rules | current_state + requested_intensity | -| 02 | `stats` | Report real token usage and estimated savings for the current session | session log + intensity timeline | +| 01 | `condense` | Toggle terse mode and apply intensity rules | current state + requested level | +| 02 | `stats` | Report real token usage and estimated savings for the current session | session messages + level timeline | -## Default flow - -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` +Dispatch by intent: a toggle phrase → `condense`, a savings query → `stats`. ## Transversal rules - **Persistence**: once active, terse mode applies to EVERY response until explicitly turned off. Do not drift back to verbose prose after many turns, when uncertain, or when the task changes. The level remains active for the rest of the session unless changed or stopped. -- **Off switch**: terse mode stops only on explicit user signal - `stop condense`, `normal mode`, `/condense off`, or invoking the skill again to toggle. +- **Off switch**: terse mode stops only on explicit user signal: `stop condense`, `normal mode`, or invoking the skill again to toggle. - **Toggle**: invoking the skill while active toggles it off; invoking while off turns it on at the default level (`full`) unless an explicit intensity is given. - **Drop fluff**: drop articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), and hedging. Fragments are acceptable. - **Short synonyms**: prefer short words (big not extensive, fix not "implement a solution for"). Technical terms stay exact. Code blocks are unchanged. Errors are quoted verbatim. - **Pattern**: `[thing] [action] [reason]. [next step].` - - Bad: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..." - - Good: "Bug in auth middleware. Token expiry check uses `<` not `<=`. Fix:" -- **Auto-pause** (drop terse mode for these passages, then resume): security warnings, irreversible action confirmations, multi-step sequences where fragment order or omitted conjunctions risk misread, compression itself creating technical ambiguity, user asks to clarify or repeats a question. -- **Boundaries**: code, commits, and pull request bodies are written in normal English regardless of intensity. The intensity level persists until toggled off or until session end. +- **Auto-pause**: drop terse mode for the passages listed in `references/intensity-levels.md` (security warnings, irreversible confirmations, ambiguity risks), then resume. +- **Boundaries**: code, commits, and pull request bodies are written in normal English regardless of intensity. ## References -- `@references/intensity-levels.md`: detailed per-level rules and side-by-side examples. - -## Assets - -- None. - -## External data - -- `../hooks/condense-stats.js` - UserPromptSubmit hook that intercepts stats triggers, reads the session transcript, and returns the formatted savings report without invoking the model. +- `references/intensity-levels.md`: detailed per-level rules and side-by-side examples. diff --git a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md index b5892323..92b3fa53 100644 --- a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md +++ b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md @@ -2,39 +2,26 @@ Toggle terse output mode and apply the requested intensity rules to subsequent prose turns. -## Inputs +## Input -- `current_state` (required): inferred from session context. Either `on` (with current intensity level) or `off`. -- `requested_intensity` (required): one of `lite`, `full`, `ultra`, or `toggle` to flip the current state. +- Whether condense is currently on (and at which level) or off, read from session context. +- The requested change: a level (lite, full, ultra) or a plain on/off toggle. -## Outputs +## Output -```text -Condense: ON (full). -Articles dropped, filler removed. Code, errors, warnings stay verbatim. Stop with "stop condense" or "normal mode". -``` - -Or on off: - -```text -Condense: OFF. -Normal prose resumed. -``` +A single confirmation line: `Condense: ON (<level>).` when enabling, or `Condense: OFF.` when disabling. ## Process -1. Detect the toggle command and target intensity from the user message. -2. Resolve the new state by combining `current_state` with `requested_intensity`: +1. **Detect.** Read the toggle command and target level from the user message. +2. **Resolve.** Combine the current state with the request: - Explicit level (`lite | full | ultra`) sets that level (or switches level if already on). - `toggle` flips on/off; default level when turning on is `full`. - - Off phrases (`stop condense`, `normal mode`, `/condense off`) force off. -3. Emit the confirmation block with the resolved state filled in. -4. Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules from `@../references/intensity-levels.md`. -5. **Hold persistence.** Do not drift back to verbose prose across many turns, when uncertain, or when the topic changes. Auto-pause only for the specific passages listed in the reference. + - Off phrases (`stop condense`, `normal mode`) force off. +3. **Emit.** The reply MUST begin with this exact line, filled in and unaltered: `Condense: ON (<level>).` when enabling, or `Condense: OFF.` when disabling. The stats action and the hook parse this line from the transcript, so never paraphrase, decorate, or omit it. +4. **Apply.** Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules and auto-pause passages from `@../references/intensity-levels.md`. ## Test -- After turning condense ON: the next non-code, non-warning assistant turn drops articles consistent with the active intensity. -- After turning condense OFF: the next assistant turn returns to normal prose. -- Code blocks, quoted errors, and security warnings remain verbatim regardless of condense state. -- After 5 consecutive turns post-activation: the terse style is still applied (no drift back to verbose). +- After ON, the next non-code, non-warning turn drops articles at the active intensity; after OFF, it returns to normal prose. +- Code blocks, quoted errors, and security warnings stay verbatim regardless of state. diff --git a/plugins/aidd-refine/skills/03-condense/actions/02-stats.md b/plugins/aidd-refine/skills/03-condense/actions/02-stats.md index 031e3073..0501cf25 100644 --- a/plugins/aidd-refine/skills/03-condense/actions/02-stats.md +++ b/plugins/aidd-refine/skills/03-condense/actions/02-stats.md @@ -1,42 +1,26 @@ # 02 - Stats -Show real token usage and estimated savings for the current session under condense mode. +Show real token usage and estimated savings for the current session under condense mode. On Claude Code the bundled `hooks/condense-stats.js` hook owns this path; the model runs the steps below only on tools without hook support. -## Inputs +## Input -- Session log of the current AI tool (assistant messages produced since session start). -- Active intensity level and its on/off transitions during the session. +- The session's assistant messages since it started. +- The active level and every on/off switch during the session. -## Outputs +## Output -```text -Condense session stats ----------------------- -Mode: ON (full) -Active turns: 18 / 32 (56%) -Tokens out (active): 4,210 -Tokens out (off): 5,830 -Avg saved / turn: ~38% (vs unmodified prose baseline) -Approx total saved: ~2,650 tokens - -Top savings: full (-42%), ultra (-58%), lite (-18%). -``` +A stats block reporting, in order: mode, active turns and ratio, tokens out while active, tokens out while off, average saved per turn versus the unmodified baseline, approximate total saved, and per-level top savings. ## Process -1. **Read the session log** for the current AI tool (Claude Code: the active session JSONL; other tools: their equivalent transcript). -2. **Detect intensity transitions** by scanning assistant messages for the confirmation block emitted by `01-condense` (`Condense: ON (...)` / `Condense: OFF`). Build a timeline of `(turn_index, level)` segments. -3. **Tokenize each assistant message.** Use the AI tool's token counter when available, otherwise approximate at 4 chars per token. -4. **Compute the baseline.** For each `active` segment, estimate the verbose-prose baseline using the level's compression ratio (`lite ~18%`, `full ~38%`, `ultra ~58%` - published averages, replaceable by measured ratios when available). -5. **Render the report block** with the exact field order shown in `## Outputs`. Round percentages to whole numbers; round token counts to the nearest 10. +1. **Read.** Load the session log for the current AI tool (Claude Code: the active session JSONL; other tools: their equivalent transcript). +2. **Detect.** Scan assistant messages for the confirmation line emitted by `01-condense` (`Condense: ON (...)` / `Condense: OFF`). Build a timeline of `(turn_index, level)` segments. +3. **Tokenize.** Count tokens per assistant message. Use the AI tool's token counter when available, otherwise approximate at 4 chars per token. +4. **Compute.** For each `active` segment, estimate the verbose-prose baseline using the level's compression ratio (`lite ~18%`, `full ~38%`, `ultra ~58%`, published averages, replaceable by measured ratios when available). +5. **Render.** Emit the report with the exact field order shown in `## Output`. Round percentages to whole numbers; round token counts to the nearest 10. 6. **Stop.** Do not invoke any other action. -## Implementation - -A `UserPromptSubmit` hook bundled with this plugin at `hooks/condense-stats.js` intercepts the trigger phrase, reads the active session transcript, detects intensity transitions emitted by `01-condense`, computes the report, and returns `{ decision: "block", reason: "<report>" }` so the model is not invoked. - -The model only runs this action's inline logic on AI tools that lack hook support; on Claude Code the hook owns the path. - ## Test -The output matches the field order in `## Outputs`, every numeric field is filled (no `-` placeholders), and the active-turns ratio is consistent with the detected intensity transitions in the session. +- The output follows the `## Output` field order, every numeric field filled (no `-`). +- The active-turns ratio matches the detected intensity transitions. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md index 3df59f34..7aa637f9 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md @@ -1,13 +1,14 @@ --- name: 04-shadow-areas -description: Analytical scan of a markdown artifact (idea, user-stories, PRD, spec) to surface blind spots - unstated assumption, missing actor, missing failure mode, ambiguous term, missing acceptance criterion, missing edge case, and missing dependency - emitting a structured shadow report grouped by category and sorted by severity. Use when the user says "find blind spots in this spec", "what's missing in this PRD", "shadow report", "shadow analysis", "scan for gaps", "find what's missing", "spot blind spots", "review for gaps", or asks for an analytical gap scan of a written artifact. Do NOT use for interactive clarification through iterative Q&A (use aidd-refine:01-brainstorm for that), implementing features, writing tests, or reviewing code style. +description: Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow report grouped by category and severity. Use to find gaps or what is missing in a written artifact. Not for interactive Q&A or code review. +argument-hint: detect | render-report | diff --- # Shadow Areas Analytically scans a written artifact for gaps the author has not addressed. Unlike iterative Q&A clarification, this skill reads the existing material and emits a structured report: each gap carries a category from a locked 7-category taxonomy, a 3-tier severity, and a direct-question probe the author can act on immediately. -## Available actions +## Actions | # | Action | Role | Input | | --- | ---------------- | ------------------------------------------------------------------------ | ---------------------------------------- | @@ -15,35 +16,24 @@ Analytically scans a written artifact for gaps the author has not addressed. Unl | 02 | `render-report` | Render markdown grouped by category and sorted by severity, write report | gap list from detect | | 03 | `diff` | Load prior report, classify gaps as closed / still-open / newly-introduced | gap list from detect + prior report path | -## Default flow - -Router dispatches by context: - -- No prior report present: `01-detect` then `02-render-report` -- Prior report present: `01-detect` then `03-diff` then `02-render-report` - -The `02-render-report` action always runs last and writes `<source>-shadow-report.md` next to the source. +Dispatch by context: with no prior report run `detect` then `render-report`; with one, run `detect` then `diff`. ## Transversal rules - Never modify the source artifact. -- Every emitted gap must have all three fields populated: `category`, `severity`, `probe`. -- Every probe must be a direct question ending with `?`. -- Categories and severities must come from the locked sets in `@references/locked-sets.json`. +- Every gap carries all three: a category, a severity, and a probe question. +- Every probe is a direct question ending with `?`. +- Categories and severities come from the locked sets in `references/locked-sets.json`. - When zero blockers and zero majors remain, stamp the report `status: clean`. -- On re-runs, the identity key for diffing is `category + normalized snippet` - not probe wording - so minor probe rephrasing does not create spurious "newly introduced" gaps. +- On re-runs, gaps are matched by category and snippet, never by question wording, so rephrasing a question never creates a spurious "newly introduced" gap. ## References -- `@references/categories.md`: locked 7-category taxonomy with definition and example per category. -- `@references/severity-rubric.md`: blocker / major / minor decision rules and examples. -- `@references/probe-style.md`: direct-question form rules. -- `@references/locked-sets.json`: machine-readable sets reused by the validator. +- `references/categories.md`: locked 7-category taxonomy with definition and example per category. +- `references/severity-rubric.md`: blocker / major / minor decision rules and examples. +- `references/probe-style.md`: direct-question form rules. +- `references/locked-sets.json`: machine-readable sets reused by the validator. ## Assets -- `@assets/report-template.md`: report skeleton with header, per-category sections, and `status: clean` block. - -## External data - -- None. +- `assets/report-template.md`: report skeleton with header, per-category sections, and `status: clean` block. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md index 8a43dfb2..3a7bdb83 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md @@ -1,41 +1,28 @@ # 01 - Detect -Parse the source artifact and extract a structured list of gaps, each classified by category, severity, and direct-question probe. +Parse the source artifact and pull out a list of gaps, each tagged with a category, a severity, and a direct question. -## Inputs +## Input -- `source` (required): file path OR inline markdown text. - - Accept absolute paths and relative paths inside the working directory. - - Reject paths outside the working directory and filenames matching `*-shadow-report.md`. +- The source to scan: a file path or inline markdown text. -## Outputs +## Output -Two arrays: - -1. `gaps[]`: each entry has `category`, `severity`, `probe`, and optional `snippet`. - - `category` ∈ the 7 locked categories in `references/locked-sets.json`. - - `severity` ∈ `{blocker, major, minor}` (see `references/severity-rubric.md`). - - `probe`: direct question ending with `?` (see `references/probe-style.md`). - - `snippet`: quoted excerpt from the source when traceable. - -2. `warnings[]`: top-of-report notes that are not gap entries (e.g. non-markdown source). +A list of gaps, each with its category, severity, a probe question, and the quoted snippet it came from, plus any top-of-report warnings such as a non-markdown source. ## Process -1. Load locked sets from `references/locked-sets.json` and category definitions from `references/categories.md`. -2. Validate the source. Reject per the rules in Inputs. -3. Edge cases: - - Empty source → emit one blocker gap `{category: "missing acceptance criterion", probe: "What content should this artifact contain?"}` and stop. - - Non-markdown source → append warning `"Source is not markdown; gap attribution may be imprecise."` and continue. -4. Scan content for each of the 7 categories in their locked order. Emit one gap per distinct issue found, assigning severity per the rubric and drafting probes per the style rules. -5. Deduplicate by `(category, normalized_snippet)`. Snippet-less gaps fall back to `(category, severity)`. -6. Return `gaps` and `warnings`. Sorting is done by `02-render-report`. +1. **Load.** Read the locked categories and their definitions from `@../references/locked-sets.json` and `@../references/categories.md`. +2. **Validate.** Check the source. Reject anything outside the working directory or already named `*-shadow-report.md`. +3. **Handle edges.** An empty source stops with a plain warning that there is nothing to scan, emitting no gap. A non-markdown source adds a warning that attribution may be imprecise, then continues. +4. **Scan.** Walk the seven categories in their locked order. Emit one gap per distinct issue, set its severity from `@../references/severity-rubric.md`, and write its question per `@../references/probe-style.md`. +5. **Dedupe.** Treat two gaps with the same category and snippet as one. A snippet-less gap falls back to its category plus severity. +6. **Return.** Hand the gaps and warnings to the next action: `03-diff` when a prior report exists, else `02-render-report`. Sorting happens there. ## Test -- Outside-tree relative path → error and empty `gaps`. -- Filename matching `*-shadow-report.md` → error and empty `gaps`. -- Empty source → exactly one blocker gap (`missing acceptance criterion`). -- Non-markdown source → one entry in `warnings`, scanning continues. -- Every emitted gap has `category` and `severity` in the locked set and `probe` ending with `?`. -- A duplicated gap (same `category` + normalized `snippet`) appears once in the output. +- A path outside the working directory, or a file named `*-shadow-report.md`, is rejected with no gaps. +- An empty source stops with a warning and no gap. +- A non-markdown source adds one warning and keeps scanning. +- Every gap has a category and severity from the locked set and a question ending in `?`. +- A repeated gap (same category and snippet) appears once. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md index c6d08bd8..16996ce6 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md @@ -1,50 +1,35 @@ # 02 - Render Report -Render the detected gap list into a structured markdown shadow report and write it next to the source artifact. +Turn the detected gaps into a structured markdown report and write it next to the source. -## Inputs +## Input -- `gaps[]` (required when `diff` is absent): gap objects from `01-detect`. Ignored when `diff` is supplied. -- `warnings[]` (required, may be empty): warnings from `01-detect`. -- `source_path` (required): path used to derive the output filename and directory. -- `diff` (optional): the three labeled sets from `03-diff` — `closed[]`, `still_open[]`, `newly_introduced[]`. Triggers diff mode. +- The gaps and warnings from `01-detect`. +- The source path, used to name and place the report. +- Optional: the three labelled sets from `03-diff` (closed, still open, newly introduced). Their presence switches on diff mode. -## Outputs +## Output -A markdown file at `<source_dir>/<source_stem>-shadow-report.md`. - -Filename rule: strip the last extension from the source filename and append `-shadow-report.md`. Examples: - -| Source | Report | -| --- | --- | -| `prd.md` | `prd-shadow-report.md` | -| `feature-v2.draft.md` | `feature-v2.draft-shadow-report.md` | -| `Makefile` | `Makefile-shadow-report.md` | - -The source artifact is never modified. +A markdown report written next to the source, named by stripping the source's last extension and appending `-shadow-report.md`. ## Process -1. Load the skeleton from `assets/report-template.md`. -2. Derive `source_dir` and `source_stem` per the filename rule. -3. If `warnings` is non-empty, emit `## Warnings` at the top with each entry as a bullet. Otherwise omit the block. -4. Render gaps grouped by category in locked order (`references/locked-sets.json`): - - Non-diff mode: emit one `### <category>` per category with at least one gap. - - Diff mode: for each category, emit `#### Closed`, `#### Still Open`, `#### Newly Introduced` in that fixed order, omitting empty subsections. -5. Within any subsection, sort gaps by severity: `blocker` → `major` → `minor`. -6. Render each gap as `**[severity]** <probe>`. If `snippet` is non-empty, append a blockquote on the next line. -7. Populate header counts: total + per-severity. In diff mode, counts come from `still_open` + `newly_introduced` only. -8. Stamp `status: clean` in front matter when zero `blocker` and zero `major` entries remain in scope. Otherwise omit the `status` key entirely. -9. Write to `<source_dir>/<source_stem>-shadow-report.md`. +1. **Load.** Start from the skeleton in `@../assets/report-template.md`. +2. **Name.** Derive the report's folder and filename from the source per the rule above. +3. **Warn.** If there are warnings, list them under `## Warnings` at the top. Otherwise omit the block. +4. **Group.** Lay gaps out by category in locked order (`@../references/locked-sets.json`). In plain mode, one heading per category that has a gap. In diff mode, split each category into Closed, Still Open, and Newly Introduced, in that order, dropping empty parts. +5. **Sort.** Within a part, order gaps blocker, then major, then minor. +6. **Render.** Write each gap as `**[severity]** <question>`, with its snippet as a blockquote on the next line when present. +7. **Count.** Fill the header totals: overall and per severity. In diff mode, count only still-open and newly-introduced gaps. +8. **Stamp.** Mark the front matter `status: clean` when no blocker and no major remain in scope. Otherwise leave the status out. +9. **Write.** Save the report at the derived path. ## Test -- Grouping: gaps spanning multiple categories produce one `### <category>` per category, in locked order. -- Sorting: within a category, `blocker` precedes `major` precedes `minor`. -- Filename: source ending in `feature-v2.draft.md` produces `feature-v2.draft-shadow-report.md`. Source `Makefile` produces `Makefile-shadow-report.md`. -- Clean: zero blocker and zero major → front matter contains `status: clean`. -- Dirty: at least one blocker or major → front matter has no `status` key. -- Warnings: non-empty `warnings` → `## Warnings` section emitted. Empty → omitted. -- No source mutation: `source_path` content and mtime unchanged after the action. -- Diff order: when a category has entries in all three subsets, output is `Closed` → `Still Open` → `Newly Introduced`. -- Diff clean: a `blocker` in `closed[]` does not block clean status; only `still_open` + `newly_introduced` count. +- Gaps spanning several categories produce one heading per category, in locked order. +- Within a category, blocker comes before major before minor. +- A source named `feature-v2.draft.md` produces `feature-v2.draft-shadow-report.md`; `Makefile` produces `Makefile-shadow-report.md`. +- Zero blocker and zero major in scope stamps `status: clean`; closed gaps never count toward scope; otherwise no status key. +- Warnings present emits `## Warnings`; none omits it. +- The source content and timestamp are unchanged after the run. +- In diff mode a category with entries in all three parts renders Closed, then Still Open, then Newly Introduced. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md index f4a290c3..61a4bff6 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md @@ -1,39 +1,28 @@ # 03 - Diff -Load the prior shadow report, compare it against the freshly detected gaps, and classify each gap as closed, still open, or newly introduced. +Load the prior shadow report, compare it with the freshly detected gaps, and sort each gap into closed, still open, or newly introduced. -## Inputs +## Input -- `current_gaps[]` (required): gap objects from `01-detect` for the current run. -- `source_path` (required): path used to derive the prior report location, applying the filename rule from `02-render-report`. +- The current run's gaps from `01-detect`. +- The source path, used to find the prior report by the same naming rule as `02-render-report`. -## Outputs +## Output -Three labeled sets, passed to `02-render-report`: - -- `closed[]`: gaps present in the prior report but absent from `current_gaps`. -- `still_open[]`: gaps present in both runs. -- `newly_introduced[]`: gaps present in `current_gaps` but absent from the prior report. - -Each entry carries `category`, `severity`, and `probe`. `closed` entries carry the prior probe; `still_open` and `newly_introduced` carry the current probe. +Three labelled sets handed to `02-render-report`: closed (in the prior report, gone now), still open (in both runs), and newly introduced (new this run). ## Process -1. Derive prior report path from `source_path` using the filename rule of `02-render-report`. -2. If the prior report does not exist: emit `closed = []`, `still_open = []`, `newly_introduced = current_gaps`. Stop. This is the expected first-run behavior. -3. Parse the prior report: - - Locate `## Gaps by Category` and walk `### <category>` subsections. - - Each line matching `**[severity]** <probe>` is a gap; an immediately following blockquote line is its `snippet`. - - Diff-mode subsections (`Closed` / `Still Open` / `Newly Introduced`) are parsed identically. -4. Build identity keys: `(category, normalized_snippet)`. Probe wording is NOT part of the key. Snippet-less gaps fall back to `(category, severity)`. This matches `01-detect`'s dedup rule so identity is consistent between runs. -5. Compute the three sets by set difference / intersection on identity keys. -6. Pass `closed`, `still_open`, `newly_introduced` to `02-render-report`. +1. **Locate.** Derive the prior report's path from the source, same rule as `02-render-report`. +2. **First run.** If no prior report exists, everything is newly introduced and the other two sets are empty. Stop. This is the expected first run. +3. **Parse.** Read the prior report: walk its category sections, treat each `**[severity]** <question>` line as a gap, and take an immediately following blockquote as its snippet. Diff-mode sections parse the same way. +4. **Match.** Identify gaps by category plus snippet, ignoring question wording, so a reworded question is not seen as new. A snippet-less gap falls back to category plus severity, matching `01-detect`'s dedupe rule so identity stays consistent across runs. +5. **Sort.** Compare the two runs to fill closed, still open, and newly introduced. Each gap keeps its category and severity; closed gaps carry the prior question, the others the current one. +6. **Hand off.** Pass the three sets to `02-render-report`. ## Test -- No change between runs → `closed = []`, all gaps in `still_open`, `newly_introduced = []`. -- A prior gap whose source anchor is removed → appears in `closed`, not in `still_open`. -- A new gap not in the prior report → appears in `newly_introduced`, not in `still_open`. -- First run (no prior report) → `closed = []`, `still_open = []`, all current gaps in `newly_introduced`. No error. -- Probe wording change with same category + snippet → classified as `still_open` (probe wording is not part of identity). -- Snippet-less gaps with identical `(category, severity)` across runs → classified as `still_open`. +- No change between runs: every gap is still open, closed and newly introduced empty. +- A prior gap whose anchor is gone lands in closed; a gap absent from the prior report lands in newly introduced. +- First run with no prior report: every current gap is newly introduced, the rest empty, no error. +- A reworded question, or a snippet-less gap with the same category and severity, stays still open (gaps match by category and snippet, not wording). diff --git a/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md b/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md index 595e5aa8..f8eb893b 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md @@ -21,33 +21,12 @@ Total gaps: <total_count> | Blocker: <blocker_count> | Major: <major_count> | Mi ## Gaps by Category -### unstated assumption - -No gaps in this category. - -### ambiguous term - -No gaps in this category. - -### missing edge case - -No gaps in this category. - -### missing actor - -No gaps in this category. +<!-- Plain mode: one heading per category that has a gap, in locked order. A category with no gap is omitted. --> -### missing failure mode - -No gaps in this category. - -### missing acceptance criterion - -No gaps in this category. - -### missing dependency +### unstated assumption -No gaps in this category. +**[blocker]** What happens when the upstream service returns 429 with no Retry-After header? +> retry_limit = env.get("RETRY_LIMIT", 3) <!-- DIFF-MODE EXAMPLE (rendered only when 03-diff output is passed to 02-render-report) diff --git a/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md b/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md index 4e865dde..14383274 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md @@ -38,7 +38,7 @@ The 7 locked categories below come from `references/locked-sets.json`. No other ## missing actor -**Definition**: An entity - person, system, or role - that takes an action or is affected by the system is absent from the document. The process cannot be fully traced without naming it. +**Definition**: An entity (person, system, or role) that takes an action or is affected by the system is absent from the document. The process cannot be fully traced without naming it. **Positive example**: A user-story describes the approval workflow: a request is submitted, reviewed, and approved. The document names the requester but never names the reviewer role or what system sends the approval notification. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md b/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md index 7fbf280f..bce1c07b 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md @@ -11,7 +11,7 @@ Rules for writing direct-question probes. The locked question forms come from `r 1. Each probe begins with a question form from the locked list: `what`, `when`, `who`, `which`, `how`, `why`, `where`, `does`, `can`, `will`, `should`, `is`, `are`, `do`. 2. Each probe ends with `?`. 3. Each probe targets one specific gap. Do not combine two questions into a single probe. -4. The probe names the specific subject (role, field, condition, term) - not the artifact or a generic concept. +4. The probe names the specific subject (role, field, condition, term), not the artifact or a generic concept. 5. Prefer the shortest question form that makes the gap actionable. Avoid preamble. --- @@ -20,11 +20,11 @@ Rules for writing direct-question probes. The locked question forms come from `r These probes satisfy all 5 rules. The question form used is noted for clarity. -- `who` - Who is responsible for approving the access request before it is acted on? -- `what` - What should the system return to the caller when the payment provider responds with a timeout? -- `which` - Which user roles are permitted to delete a published record? -- `how` - How is the session invalidated when the user's account is suspended mid-session? -- `does` - Does the 10 MB file-size limit apply to each individual file in a multi-file upload or to the combined total? +- `who`: Who is responsible for approving the access request before it is acted on? +- `what`: What should the system return to the caller when the payment provider responds with a timeout? +- `which`: Which user roles are permitted to delete a published record? +- `how`: How is the session invalidated when the user's account is suspended mid-session? +- `does`: Does the 10 MB file-size limit apply to each individual file in a multi-file upload or to the combined total? --- @@ -32,6 +32,6 @@ These probes satisfy all 5 rules. The question form used is noted for clarity. These examples violate one or more rules. Do not write probes in these forms. -- "The spec is unclear about authentication." - Statement, no question form, does not end with `?`. Describes the problem abstractly instead of asking for the specific missing information. -- "Authentication and authorization both need clarification, and the roles section is incomplete." - Combines multiple targets in one sentence. Breaks rule 3 (one specific gap per probe). -- "Could you clarify the access control model?" - Vague subject. Does not identify which part of the access control model is missing or ambiguous. Breaks rule 4. +- "The spec is unclear about authentication." Statement, no question form, does not end with `?`. Describes the problem abstractly instead of asking for the specific missing information. +- "Authentication and authorization both need clarification, and the roles section is incomplete." Combines multiple targets in one sentence. Breaks rule 3 (one specific gap per probe). +- "Could you clarify the access control model?" Vague subject. Does not identify which part of the access control model is missing or ambiguous. Breaks rule 4. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md b/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md index 0fe42c1d..23dac7cb 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md @@ -24,7 +24,7 @@ The 3 locked severity tiers below come from `references/locked-sets.json`. Assig ## major -**Decision rule**: The gap does not prevent starting work, but it will cause rework - incomplete implementation, a failed review cycle, or a missed requirement that surfaces during testing. +**Decision rule**: The gap does not prevent starting work, but it will cause rework: incomplete implementation, a failed review cycle, or a missed requirement that surfaces during testing. **When to assign**: - A failure mode is undescribed; it will be discovered during integration or QA and require a code change. @@ -39,7 +39,7 @@ The 3 locked severity tiers below come from `references/locked-sets.json`. Assig ## minor -**Definition rule**: The gap is cosmetic or affects documentation clarity only. Resolving it improves precision or readability but will not change an implementation decision or require rework. +**Decision rule**: The gap is cosmetic or affects documentation clarity only. Resolving it improves precision or readability but will not change an implementation decision or require rework. **When to assign**: - An ambiguous term exists in a non-critical context where both interpretations lead to the same implementation. diff --git a/plugins/aidd-refine/skills/05-fact-check/SKILL.md b/plugins/aidd-refine/skills/05-fact-check/SKILL.md index af670ba6..89472839 100644 --- a/plugins/aidd-refine/skills/05-fact-check/SKILL.md +++ b/plugins/aidd-refine/skills/05-fact-check/SKILL.md @@ -1,13 +1,14 @@ --- name: 05-fact-check -description: Verify factual claims in a piece of text against authoritative sources and rewrite it with footnote citations, hedging any claim that cannot be confirmed. Runs a cheapest-first verification cascade (project memory and docs, then codebase inspection, then web lookup) and reports both sources when they disagree. Use when the user says "fact-check this", "verify that claim", "are you sure about that", "is that actually true", "cite your sources", "where did you get that fact", "did you make that up", "double-check the version you gave me", "vérifie cette information", or "es-tu sûr de ça". Do NOT use to auto-guard the AI's own output (this skill only fires on an explicit request), to judge code logic correctness, or to clarify vague requirements through iterative Q&A - use `aidd-refine:01-brainstorm` for that. +description: Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging the unconfirmed. Use to fact-check, verify a claim, or cite sources on request. Not for judging code or clarifying requirements. +argument-hint: identify-claims | verify | report --- # Fact-check Verifies the factual claims inside a target text and rewrites it grounded in evidence. The skill extracts each verifiable claim, runs a cheapest-first verification cascade, and emits a rewritten answer where every confirmed claim carries a footnote citation and every unconfirmed claim is explicitly hedged. When sources disagree, both are reported rather than one being silently chosen. -## Available actions +## Actions | # | Action | Role | Input | | --- | ----------------- | ----------------------------------------------------------------------------- | --------------------------- | @@ -15,31 +16,25 @@ Verifies the factual claims inside a target text and rewrites it grounded in evi | 02 | `verify` | Run the verification cascade per claim, produce a verdict and sources | claim list from 01 | | 03 | `report` | Rewrite the text with footnote citations, hedge unverified, surface conflicts | verdict list from 02 | -## Default flow - -Sequential skill: `01 → 02 → 03`. No skipping. The router materializes the three actions as a task list on entry and closes each task only when its `## Test` passes. +Run `01 → 02 → 03`; pass each `## Test` before the next. ## Transversal rules -- Never alter the meaning of a claim while verifying it - verify what was stated, not a charitable reinterpretation. -- The verification cascade is cheapest-first and short-circuits: stop at the first tier that resolves a claim. See `@references/verification-cascade.md`. +- Never alter the meaning of a claim while verifying it: verify what was stated, not a charitable reinterpretation. +- The verification cascade is cheapest-first and short-circuits: stop at the first tier that resolves a claim. See `references/verification-cascade.md`. - A web lookup is the last resort, never the first. Reach it only when project memory and codebase inspection both fail to resolve a claim. -- Claim categories come from the locked set in `@references/claim-categories.md`. Opinion, preference, and trivially-known statements are not claims and are skipped. -- When two sources disagree, report both with their origin - never silently pick one. +- Claim categories come from the locked set in `references/claim-categories.md`. Opinion, preference, and trivially-known statements are not claims and are skipped. +- When two sources disagree, report both with their origin, never silently pick one. - An unverified claim is never deleted and never asserted as fact: it is kept and marked `(unverified - no source found)`. -- Caching a verified fact is opt-in: propose it with a recommendation, never cache silently. The skill itself stores nothing - on approval it restates the fact for the user's own memory tooling. Persistence is out of scope. -- The final report is reader-facing prose - the corrected text, `## Sources`, and `## Unverified claims`, nothing else. Internal mechanics never appear in the output: no cascade or tier trace (`Cascade:`, `tier 1/2/3`, `miss`, `resolved`), no category labels, no raw verdict words. State conclusions, not the process. Action 03 holds the exhaustive forbidden list. -- The report is rendered in plain prose and is never restyled by an active session output mode (terse, caveman, condensed). The skill's output format is fixed by action 03 alone. +- Caching a verified fact is opt-in: propose it with a recommendation, never cache silently. The skill persists nothing; the mechanics live in action 03. +- The final report is reader-facing prose: the corrected text, `## Sources`, and `## Unverified claims`, nothing else. Internal mechanics never appear in the output: no cascade or tier trace (`Cascade:`, `tier 1/2/3`, `miss`, `resolved`), no category labels, no raw verdict words. State conclusions, not the process. Action 03 holds the exhaustive forbidden list. +- The report is rendered in plain prose and is never restyled by an active output mode. The skill's output format is fixed by action 03 alone. ## References -- `@references/claim-categories.md` - locked taxonomy of verifiable claim categories with definition and example. -- `@references/verification-cascade.md` - the three-tier cascade, short-circuit rule, web-cost guardrail. +- `references/claim-categories.md`: locked taxonomy of verifiable claim categories with definition and example. +- `references/verification-cascade.md`: the three-tier cascade, short-circuit rule, web-cost guardrail. ## Assets -- `@assets/report-template.md` - rewritten-answer skeleton with the `## Sources` footnote block. - -## External data - -- None. +- `assets/report-template.md`: rewritten-answer skeleton with the `## Sources` footnote block. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md b/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md index 07af7644..472c229a 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md @@ -1,30 +1,23 @@ # 01 - Identify claims -Extract every verifiable factual claim from the target text and classify each one. +Pull every verifiable factual claim out of the target text and tag each one. -## Inputs +## Input -- `target_text` (required) - string, the text whose facts must be checked. The user's prior answer, a quoted passage, or an explicitly pasted block. +- The text whose facts need checking: the user's prior answer, a quoted passage, or a pasted block. -## Outputs +## Output -A claim list. Each entry pairs the claim text with one category from the locked taxonomy. - -```json -[ - { "claim": "Next.js 15 shipped the use cache directive in 2024", "category": "version" }, - { "claim": "the file aidd_docs/memory/architecture.md exists in this repo", "category": "project-fact" } -] -``` +A list of claims, each paired with one category from the locked taxonomy. ## Process -1. Read `target_text` sentence by sentence. -2. For each sentence, decide: does it assert a fact? Split a mixed sentence into its factual part and its opinion part. -3. Drop every non-claim per `@../references/claim-categories.md` - opinion, preference, trivially-known general knowledge, the AI's own intent. -4. Assign each surviving claim exactly one category from the locked taxonomy. When two categories fit, prefer the one routing to the cheapest tier (`project-fact` over `hard-to-know` for repo claims). -5. Emit the claim list. If the list is empty, report "no verifiable claims" and stop the skill. +1. **Read.** Go through the text sentence by sentence. +2. **Decide.** For each sentence, ask whether it states a fact. Split a mixed sentence into its factual part and its opinion part. +3. **Drop.** Discard every non-claim per `@../references/claim-categories.md`: opinion, preference, trivially-known general knowledge, the AI's own intent. +4. **Tag.** Give each surviving claim one category. When two fit, pick the one routing to the cheapest tier (a repo fact over a hard-to-know fact). +5. **Emit.** Return the claim list. If it is empty, report "no verifiable claims" and stop the skill. ## Test -Run on the text `"Next.js 15 shipped the use cache directive in 2024. This naming is clean."` - the output lists the first sentence as a claim (category `version` or `date-event-person`) and excludes "This naming is clean" as opinion. +- Run on `"Next.js 15 shipped the use cache directive in 2024. This naming is clean."`: the output lists the first sentence as a claim and excludes "This naming is clean" as opinion. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md b/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md index d7188885..18de9541 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md @@ -1,40 +1,24 @@ # 02 - Verify -Run the cheapest-first verification cascade against each claim and assign it a verdict. +Run the cheapest-first verification cascade against each claim and give it a verdict. -## Inputs +## Input -- `claim_list` (required) - the classified claim list from action 01. +- The tagged claims from `01-identify-claims`. -## Outputs +## Output -A verdict list. Each claim gains a verdict and its supporting sources. - -```json -[ - { - "claim": "the source file plugins/aidd-refine/hooks/condense-stats.js exists in this repo", - "category": "project-fact", - "verdict": "verified", - "tier": "codebase", - "sources": ["plugins/aidd-refine/hooks/condense-stats.js"] - } -] -``` - -## Depends on - -- `01-identify-claims` +A list of verdicts: each claim gains one verdict (verified, refuted, conflict, or unverified) with the sources behind it and the tier that resolved it. ## Process -1. For each claim, walk the cascade in `@../references/verification-cascade.md`: tier 1 project memory and docs, tier 2 codebase inspection, tier 3 web lookup. -2. Route by category - `project-fact` favors tiers 1 and 2; other categories favor tier 1 then tier 3. -3. Short-circuit: the first tier that resolves the claim sets the verdict. Do not consult later tiers. -4. Respect the web-cost guardrail - reach tier 3 only after tiers 1 and 2 fail, prefer one authoritative source, stop once resolved. -5. Assign exactly one verdict: `verified` (record every source), `conflict` (record both sides with origin, pick no winner), or `unverified` (cascade exhausted, no source). -6. Emit the verdict list. +1. **Walk.** For each claim, walk the cascade in `@../references/verification-cascade.md`: first project memory and docs, then codebase inspection, then web lookup. +2. **Route.** Send repo facts to memory and codebase first; send other claims to memory then the web. +3. **Short-circuit.** The first tier that resolves a claim sets its verdict. Do not consult later tiers. +4. **Guard.** Reach the web only after memory and codebase both fail. Prefer one authoritative source, and stop once resolved. +5. **Judge.** Give each claim one verdict: verified (record every source), refuted (a source contradicts the claim, record it), conflict (record both sides with their origin, pick no winner), or unverified (cascade exhausted, no source). +6. **Emit.** Return the verdict list. ## Test -Run on the single claim `"the source file plugins/aidd-refine/hooks/condense-stats.js exists in this repo"` - the cascade resolves at the codebase tier (tier 2), the verdict is `verified`, the source is that file path, and the web tier is never reached. +- Run on `"the source file plugins/aidd-refine/hooks/condense-stats.js exists in this repo"`: the cascade resolves at the codebase tier, the verdict is verified, the source is that file path, and the web tier is never reached. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md index 887a613b..42e4b205 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md @@ -1,49 +1,27 @@ # 03 - Report -Rewrite the original text grounded in the verdicts: cite verified claims, hedge unverified ones, surface conflicts. The output is reader-facing prose only. +Rewrite the original text on the evidence: cite verified claims, hedge unverified ones, surface conflicts. The output is reader-facing prose only. -## Output discipline (hard constraint - read first) +## Input -The delivered output contains EXACTLY these blocks, in this order, and nothing else: +- The verdicts from `02-verify`. +- The original text, reused as the base for the rewrite. -1. The rewritten text, with a `[n]` marker on each verified claim and a `(unverified - no source found)` marker on each unverified claim. -2. A `## Sources` block. -3. A `## Unverified claims` block - only when at least one claim is unverified. +## Output -The following are internal to actions 01 and 02. They are FORBIDDEN in the output - never write them: - -- Any cascade or tier trace. Never emit the words `Cascade`, `tier 1`, `tier 2`, `tier 3`, `miss`, `N/A`, or `resolved` in the output. -- Any category label - `hard-to-know`, `version`, `api-signature`, `date-event-person`, `project-fact`. -- Any raw verdict vocabulary - `verdict`, `claim false`, `claim true`, or the enum values `verified` / `conflict` / `unverified` used as a status word (the inline `(unverified - no source found)` marker is the one allowed exception). -- Any sentence explaining why a cache line was or was not added. -- The report is plain prose. It is NOT styled by any active session output mode (terse, caveman, condensed, etc.). Render it normally regardless of how the surrounding conversation is styled. - -Before delivering, scan the draft: if any line contains a forbidden item, delete that line. - -## Inputs - -- `verdict_list` (required) - the verdict list from action 02. -- `target_text` (required) - the original text, reused as the rewrite base. - -## Outputs - -The rewritten answer following `@../assets/report-template.md`: original content preserved, a `[n]` marker on each verified claim, a `(unverified - no source found)` marker on each unverified claim, conflicts stated with both sides, and a `## Sources` footnote block. - -## Depends on - -- `02-verify` +The rewritten answer per `@../assets/report-template.md`, obeying `@../references/report-output-discipline.md`. ## Process -1. Copy `@../assets/report-template.md` as the structure. -2. Rewrite `target_text`: append `[n]` to each `verified` claim, numbered in reading order. -3. For each `conflict`, state both sides in full ("Source A reports X; source B reports Y") - choose no winner. -4. Append `(unverified - no source found)` to each `unverified` claim; never delete it, never assert it. -5. Build the `## Sources` block - one numbered entry per source, with title or file path, location, and the claim it verifies. Conflicts get one entry per side. -6. Add the `## Unverified claims` section only when at least one claim is unverified; omit it otherwise. -7. If any verified fact is stable (project paths, pinned-version APIs), append a single cache-suggestion line proposing the user cache it, with a yes/no recommendation. The skill persists nothing itself: on approval, restate the fact and its source plainly so the user (or their memory tooling) can store it. When no fact qualifies, omit the line silently - never explain its absence. -8. Apply the Output discipline scan above, then deliver. +1. **Copy.** Start from `@../assets/report-template.md`. +2. **Rewrite.** Carry the original text over, appending `[n]` to each verified claim, numbered in reading order. Replace each refuted claim with the corrected fact and cite the contradicting source `[n]`; never restate the false claim as true. +3. **Surface.** For each conflict, state both sides in full ("Source A reports X; source B reports Y"), choosing no winner. +4. **Mark.** Append the exact marker `(unverified - no source found)`, verbatim and unreworded, to each unverified claim. Never delete it, never assert it. +5. **Cite.** Build the `## Sources` block: one numbered entry per source, with its title or file path, location, and the claim it backs. Each side of a conflict gets its own entry. +6. **List.** Add the `## Unverified claims` section only when at least one claim is unverified; otherwise omit it. +7. **Suggest.** When a verified fact is stable (project paths, pinned-version APIs), append one cache-suggestion line with a yes/no recommendation. The skill stores nothing itself: on approval, restate the fact and its source so the user's own memory tooling can keep it. When nothing qualifies, omit the line silently. +8. **Scrub.** Before delivering, re-read the draft line by line against `@../references/report-output-discipline.md`: delete any line that carries a forbidden item, and re-render in plain prose any line an active output mode restyled. Ship plain prose whatever the surrounding style. ## Test -Given one `verified` claim and one `unverified` claim, the rendered output contains a `## Sources` section with a `[1]` footnote for the verified claim and an inline `(unverified - no source found)` marker on the other, and contains none of the forbidden words (`Cascade`, `tier 1/2/3`, `verdict`, category labels). +- Given one verified claim and one unverified claim, the output carries a `## Sources` section with a `[1]` footnote for the verified claim, an inline `(unverified - no source found)` marker on the other, and none of the forbidden words from `@../references/report-output-discipline.md`. diff --git a/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md b/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md index 8389af5f..3387cf29 100644 --- a/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md +++ b/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md @@ -1,8 +1,4 @@ -<!-- Rewritten-answer skeleton. Copy this structure into the fact-checked output. --> -<!-- Reader-facing only: no cascade trace, no tier-by-tier log, no category labels, no verdict enum. --> -<!-- The output is exactly the four blocks below - nothing else. --> - -<!-- Line below the unverified marker is what a miss looks like to the reader - "(unverified)", not "tier 3 resolved". --> +<!-- Rewritten-answer skeleton. Copy into the output. Output rules: references/report-output-discipline.md. --> <rewritten answer text - same content as the original, with a [n] marker appended to each verified claim and a "(unverified - no source found)" marker appended to each unverified claim> @@ -17,11 +13,10 @@ ## Unverified claims -- "<claim text>" - cascade exhausted (memory, codebase, web), no source found. +- "<claim text>": no source found. <!-- Omit the "Unverified claims" section entirely when every claim resolved. --> <!-- Cache proposal: append only when at least one stable verified fact exists. --> -<!-- The skill does not persist anything - on approval, restate the fact + source for the user's own memory tooling. --> > Cache suggestion: "<fact>" looks stable - cache it for reuse? (recommended: <yes/no, with a one-line reason>) diff --git a/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md b/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md index 7518ec93..14bfec38 100644 --- a/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md +++ b/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md @@ -9,10 +9,10 @@ Locked taxonomy. Every extracted claim is assigned exactly one category. A state | `version` | A version, release number, or the existence of a package or tool | "React 19 is released", "the `zod` package exists" | | `api-signature` | A function or method signature, its parameters, return type, or documented behavior | "`useEffect` runs after paint", "`fetch` returns a Promise" | | `date-event-person` | A date, event, release timeline, or a fact about a person | "Node 22 shipped in 2024", "X wrote library Y" | -| `project-fact` | A claim about this repository - a file, function, config value, or structure | "the file `src/auth.ts` exists", "the API runs on port 3000" | -| `hard-to-know` | Any non-trivially-knowable fact not covered above - statistics, quotes, external facts | "this framework has 40k stars", "the RFC says Z" | +| `project-fact` | A claim about this repository: a file, function, config value, or structure | "the file `src/auth.ts` exists", "the API runs on port 3000" | +| `hard-to-know` | Any non-trivially-knowable fact not covered above: statistics, quotes, external facts | "this framework has 40k stars", "the RFC says Z" | -## Not claims - skip +## Not claims to skip - Opinion, preference, or aesthetic judgment ("this naming is clean", "the design feels heavy"). - Trivially-known general knowledge a competent reader would never dispute ("HTTP 404 means not found"). @@ -21,4 +21,4 @@ Locked taxonomy. Every extracted claim is assigned exactly one category. A state ## Classification rule -When a sentence mixes a fact and an opinion, split it: verify the fact, drop the opinion. When a claim could fit two categories, pick the one that drives the cheapest verification tier - `project-fact` over `hard-to-know` whenever the claim concerns this repository. +When a sentence mixes a fact and an opinion, split it: verify the fact, drop the opinion. When a claim could fit two categories, pick the one that drives the cheapest verification tier: `project-fact` over `hard-to-know` whenever the claim concerns this repository. diff --git a/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md b/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md new file mode 100644 index 00000000..8a9fc0ed --- /dev/null +++ b/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md @@ -0,0 +1,25 @@ +# Report output discipline + +The hard constraint on what the `03-report` action may deliver. Read it before drafting the report. + +## What the output contains + +Exactly these blocks, in this order, and nothing else: + +1. The rewritten text, with a `[n]` marker on each verified or corrected claim and a `(unverified - no source found)` marker on each unverified claim. +2. A `## Sources` block. +3. A `## Unverified claims` block, only when at least one claim is unverified. + +## What is forbidden + +These belong to the earlier actions and never appear in the output: + +- Any cascade or tier trace. Never write `Cascade`, `tier 1`, `tier 2`, `tier 3`, `miss`, `N/A`, or `resolved`. +- Any category label: `hard-to-know`, `version`, `api-signature`, `date-event-person`, `project-fact`. +- Any raw verdict word: `verdict`, `claim false`, `claim true`, or the values `verified` / `refuted` / `conflict` / `unverified` used as a status (the inline `(unverified - no source found)` marker is the one allowed exception). +- How a claim was checked: shell commands, `ls` / `find` / grep output, or phrases like "by inspection" or "codebase inspection". Cite the source and state the conclusion, not the method. +- Any sentence explaining why a cache line was or was not added. + +The report is plain prose. No active output mode restyles it; render it normally however the surrounding conversation is styled. + +Before delivering, scan the draft: if a line carries any forbidden item, delete that line. diff --git a/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md b/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md index 08b90fb8..dd5af0c4 100644 --- a/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md +++ b/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md @@ -1,6 +1,6 @@ # Verification cascade -Claims are verified cheapest-first. The cascade short-circuits: as soon as a tier resolves a claim, stop - do not consult the remaining tiers. +Claims are verified cheapest-first. The cascade short-circuits: as soon as a tier resolves a claim, stop and skip the remaining tiers. ## Tiers @@ -12,12 +12,12 @@ Claims are verified cheapest-first. The cascade short-circuits: as soon as a tie ## Short-circuit rule -For each claim, walk tiers in order. The first tier that produces a clear answer resolves the claim - record the verdict and the source, move to the next claim. Never run a later tier once an earlier one has resolved. +For each claim, walk tiers in order. The first tier that produces a clear answer resolves the claim: record the verdict and the source, then move to the next claim. Never run a later tier once an earlier one has resolved. ## Tier routing by category -- `project-fact` - tier 1, then tier 2. A web lookup is almost never needed and must be skipped once tier 1 or 2 resolves. -- `version`, `api-signature`, `date-event-person`, `hard-to-know` - tier 1 first (a pinned version or doc may already answer it), then tier 3. Tier 2 only helps when the project itself embeds the fact. +- `project-fact`: tier 1, then tier 2. A web lookup is almost never needed and must be skipped once tier 1 or 2 resolves. +- `version`, `api-signature`, `date-event-person`, `hard-to-know`: tier 1 first (a pinned version or doc may already answer it), then tier 3. Tier 2 only helps when the project itself embeds the fact. ## Web-cost guardrail @@ -25,12 +25,13 @@ A web lookup is a last resort, never an opener. - Reach tier 3 only when tiers 1 and 2 both failed to resolve the claim. - Prefer one authoritative source (official documentation, the package registry, the primary publication) over many low-quality pages. -- Stop as soon as the claim is resolved or a contradiction is found - do not keep fetching for extra confirmation. +- Stop as soon as the claim is resolved or a contradiction is found; do not keep fetching for extra confirmation. ## Verdicts Each verified claim ends in exactly one verdict: -- `verified` - one or more sources confirm the claim. Record every source. -- `conflict` - sources disagree. Record both sides with their origin; do not pick a winner. -- `unverified` - no tier produced a source. The claim is kept and hedged, never asserted and never deleted. +- `verified`: one or more sources confirm the claim. Record every source. +- `refuted`: a source contradicts the claim. Record the contradicting source. +- `conflict`: sources disagree. Record both sides with their origin; do not pick a winner. +- `unverified`: no tier produced a source. The claim is kept and hedged, never asserted and never deleted. diff --git a/plugins/aidd-ui/.claude-plugin/plugin.json b/plugins/aidd-ui/.claude-plugin/plugin.json new file mode 100644 index 00000000..894d576b --- /dev/null +++ b/plugins/aidd-ui/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", + "name": "aidd-ui", + "version": "0.1.0-alpha.0", + "description": "ALPHA, not ready for use. UI and UX concern for the AI-Driven Development framework. Use when the user wants to design, review, or improve a frontend interface. Do NOT use for backend-only or non-UI tasks.", + "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, + "skills": ["./skills/01-hello"], + "keywords": ["ui", "ux", "design", "frontend"], + "repository": "https://github.com/ai-driven-dev/framework", + "homepage": "https://ai-driven.dev", + "license": "MIT" +} diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md new file mode 100644 index 00000000..633d25f1 --- /dev/null +++ b/plugins/aidd-ui/CATALOG.md @@ -0,0 +1,30 @@ +# aidd-ui catalog + +Auto-generated index of skills, agents, references and assets shipped by the `aidd-ui` plugin. + +> This file is automatically updated by the `scripts/summarize-markdown.js` script. + +## Table of Contents + +- [`.claude-plugin`](#claude-plugin) +- [`skills`](#skills) + - [`skills/01-hello`](#skills01-hello) + +--- + +### `.claude-plugin` + +| File | +|------| +| [plugin.json](.claude-plugin/plugin.json) | + +### `skills` + +#### `skills/01-hello` + +| 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 new file mode 100644 index 00000000..f54d34cd --- /dev/null +++ b/plugins/aidd-ui/README.md @@ -0,0 +1,28 @@ +← [aidd-framework](../../README.md) + +# aidd-ui 🚧 alpha + +UI and UX concern for the AI-Driven Development framework. + +> ⚠️ **ALPHA — NOT READY FOR USE.** `0.1.0-alpha.0`. This plugin ships a single smoke-test skill and no real UI/UX capability yet. Do not install it expecting to use it; it exists only to validate the scaffold. APIs, skills, and naming may change or be removed without notice. + +> Status: alpha (experimental). + +This plugin is in alpha (`0.1.0-alpha.0`). It lives on a dedicated branch off `next` and is registered with `recommended: false`, so it stays off the curated install path until it stabilises and graduates to `main`. While it is not in the published marketplace yet, test it from a local checkout of this branch: + +``` +claude --plugin-dir plugins/aidd-ui # zero-marketplace, session-scoped +# or, persistent: +/plugin marketplace add . # register this checkout as a local marketplace +/plugin install aidd-ui@aidd-framework +``` + +Then run `aidd-ui:01-hello` to confirm it loads. + +One starter skill today; real UI and UX skills land as the concern stabilises. + +## Skills + +| Bracket ID | Skill | Description | +| ---------- | ----- | ----------- | +| [7.1] | [hello](skills/01-hello/README.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 new file mode 100644 index 00000000..11b4803c --- /dev/null +++ b/plugins/aidd-ui/skills/01-hello/README.md @@ -0,0 +1,29 @@ +← [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 new file mode 100644 index 00000000..2191c739 --- /dev/null +++ b/plugins/aidd-ui/skills/01-hello/SKILL.md @@ -0,0 +1,16 @@ +--- +name: 01-hello +description: 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. +--- + +# Skill: hello + +Confirm the aidd-ui plugin loads and is reachable. + +## Actions + +| # | Action | Role | +| --- | ------- | ------------------------------------------- | +| 01 | `greet` | Greet the user and confirm the skill works | + +Single action skill: run `greet` and return its message. diff --git a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md new file mode 100644 index 00000000..57b1aa82 --- /dev/null +++ b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md @@ -0,0 +1,15 @@ +# 01 - greet + +Greet the caller to confirm the skill is reachable. + +## Output + +A short greeting printed in the chat. + +## Process + +1. **Print.** Print "Hello from aidd-ui (alpha)." + +## Test + +- The chat shows the line "Hello from aidd-ui (alpha)." diff --git a/plugins/aidd-vcs/.claude-plugin/plugin.json b/plugins/aidd-vcs/.claude-plugin/plugin.json index fc109aa6..36f72f53 100644 --- a/plugins/aidd-vcs/.claude-plugin/plugin.json +++ b/plugins/aidd-vcs/.claude-plugin/plugin.json @@ -2,12 +2,13 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-vcs", "version": "2.0.0", - "description": "External artifacts: commit, pull-request, release-tag, issue-create", + "description": "External artifacts: repo-init, commit, pull-request, release-tag, issue-create", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, "skills": [ + "./skills/00-repo-init", "./skills/01-commit", "./skills/02-pull-request", "./skills/03-release-tag", @@ -15,6 +16,7 @@ ], "keywords": [ "git", + "repo-init", "commit", "pull-request", "release", diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 4cc8de8d..3a2333a6 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -8,6 +8,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) + - [`skills/00-repo-init`](#skills00-repo-init) - [`skills/01-commit`](#skills01-commit) - [`skills/02-pull-request`](#skills02-pull-request) - [`skills/03-release-tag`](#skills03-release-tag) @@ -23,43 +24,55 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai ### `skills` +#### `skills/00-repo-init` + +| Group | File | Description | +|-------|------|---| +| `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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-commit.md](skills/01-commit/actions/01-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 conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-collect.md](skills/01-commit/actions/01-collect.md) | - | +| `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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | - | -| `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | - | -| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | - | -| `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | - | -| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README 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. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-collect.md](skills/02-pull-request/actions/01-collect.md) | - | +| `actions` | [02-draft.md](skills/02-pull-request/actions/02-draft.md) | - | +| `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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `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 annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags.` | - | +| Group | File | Description | +|-------|------|---| +| `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` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `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 says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues.` | - | +| Group | File | Description | +|-------|------|---| +| `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/skills/00-repo-init/README.md b/plugins/aidd-vcs/skills/00-repo-init/README.md new file mode 100644 index 00000000..6c7ecd3b --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/README.md @@ -0,0 +1,34 @@ +← [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 new file mode 100644 index 00000000..3ebb58e2 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md @@ -0,0 +1,29 @@ +--- +name: 00-repo-init +description: 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. +argument-hint: init | publish +--- + +# Repo Init + +Initializes a project's repository locally and, on request, on the remote host, then returns the remote URL. + +## Actions + +| # | Action | Role | Input | +| --- | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------- | +| 01 | `init` | Resolve VCS config, `git init`, set the default branch, write `CONTRIBUTING.md`, bootstrap commit | cwd, default_branch, remote_url | +| 02 | `publish` | Create the remote repo on the resolved host and push, return its URL | cwd, non_interactive | + +Run `01 → 02`. `init` alone for local-only; `publish` after it to create the remote. + +## Transversal rules + +- The local step is idempotent. If the target is already a git work tree, `init` does nothing and reports. +- `init` makes one bootstrap commit (`--allow-empty`) so `HEAD` exists and is pushable. The project's real first commit stays the commit skill's job. +- `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. + +## Assets + +- `assets/CONTRIBUTING.md`: the project-root `CONTRIBUTING.md` template. diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md new file mode 100644 index 00000000..ffe29da6 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md @@ -0,0 +1,34 @@ +# 01 - Init + +Initialize a fresh local git repository on the resolved default branch. + +## Input + +- `cwd` (optional): directory to initialize. Defaults to the current directory. +- `default_branch` (optional): overrides the resolved branch. +- `remote_url` (optional): added as `origin` when given. + +## Output + +A report of the repo root, the resolved default branch and provider, and whether `origin` was added. Reports `created: false` and stops when the target is already a git work tree. + +## Process + +1. **Guard.** If `cwd` is already a git work tree, skip and report `created: false`. +2. **Resolve.** Resolve the default branch and provider; an explicit `default_branch` wins. +3. **Init.** Run `git init -b <default_branch> <cwd>`. +4. **Contribute.** Write `CONTRIBUTING.md` at the repo root from the template, filling `{{PROJECT_NAME}}`. Leave no raw `{{...}}`. + + ```markdown + @../assets/CONTRIBUTING.md + ``` + +5. **Bootstrap.** Commit once so `HEAD` exists and is pushable: `git -C <cwd> commit --allow-empty -m "chore: initialize repository"`. +6. **Remote.** If `remote_url` is given, run `git -C <cwd> remote add origin <remote_url>`. + +## Test + +- `git -C <cwd> rev-parse --is-inside-work-tree` prints `true`. +- `git -C <cwd> symbolic-ref --short HEAD` equals the resolved default branch. +- `CONTRIBUTING.md` exists at the repo root and contains no `{{`. +- `git -C <cwd> rev-parse HEAD` resolves to a commit. diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md new file mode 100644 index 00000000..87d19466 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md @@ -0,0 +1,24 @@ +# 02 - Publish + +Create the project's remote repository on the resolved host and push to it. Outward-facing; runs after `01-init`. + +## Input + +- `cwd` (optional): the initialized local repository. Defaults to the current directory. +- `non_interactive` (optional, default `false`): skip the confirmation prompt for scaffolder or auto runs. + +## Output + +A report of the created remote URL, the resolved provider, and the pushed default branch. + +## Process + +1. **Resolve.** Resolve the host and how to reach it. +2. **Confirm.** Unless `non_interactive`, confirm before creating the remote. The remote may be public, so create it private by default. +3. **Create.** Create the remote repository and push through the resolved host tooling. `01-init` already left a pushable `HEAD`. If no host tooling is available, stop and report. +4. **Return.** Report the remote URL to the user. + +## Test + +- The action prints a non-empty remote URL. +- `git -C <cwd> remote get-url origin` resolves to that URL. diff --git a/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md new file mode 100644 index 00000000..e13f1bbe --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md @@ -0,0 +1,18 @@ +# Contributing to {{PROJECT_NAME}} + +## Setup + +See `INSTALL.md`. + +## Workflow + +1. Branch off the default branch. +2. Implement against the wired route stubs - keep architecture boundaries (see `INSTALL.md`). +3. Add or extend tests alongside the code (see `INSTALL.md` for how to run them). +4. Run the suite before opening a request. + +## Conventions + +- Commits: conventional commits (`<type>(<scope>): description`). +- The CI pipeline runs the test suite on every push; keep it green. +- Do not put business logic in route stubs until you replace them with real handlers. diff --git a/plugins/aidd-vcs/skills/01-commit/README.md b/plugins/aidd-vcs/skills/01-commit/README.md index 0cba0c3f..5f4a992f 100644 --- a/plugins/aidd-vcs/skills/01-commit/README.md +++ b/plugins/aidd-vcs/skills/01-commit/README.md @@ -31,8 +31,9 @@ Or via the slash command: - `/commit` - stage, commit, stay local (`push: false`). - `/commit push` - stage, commit, then push the branch (`push: true`). -The skill runs a single action (`commit`) that stages, generates or accepts a -message, commits, and optionally pushes. +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 diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index e25cb790..0e03d244 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -1,47 +1,33 @@ --- name: 01-commit -description: Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging. +description: 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. +argument-hint: collect | message | commit --- # Commit -Generates atomic git commits with conventional messages, supporting interactive splits and agent-driven auto mode. +Stage the right changes, write the message, commit. `01 → 02 → 03`. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | -------- | ------------------------------------------------------------- | ------------------------------------------- | -| 01 | `commit` | Stage, generate or accept a message, commit, optionally push | mode, message, push, files | +| # | Action | Step | +| --- | --------- | ----------------------------------------------------- | +| 01 | `collect` | Review the change and stage what belongs in one commit | +| 02 | `message` | Write the conventional message | +| 03 | `commit` | Commit, and push when asked | -## Default flow - -Single action skill. The router dispatches to `commit` whenever a commit phrase or slash command appears. - -## Inline arguments - -When invoked as a slash command, the trailing argument controls the push behavior: - -- `/commit` → commits only, stays local (`push: false`) -- `/commit push` → commits then pushes the branch (`push: true`) +Several concerns means several commits: repeat the chain, one concern at a time. ## Transversal rules -- Commits stay atomic and focused on a single concern. -- Messages use imperative mood ("Add feature" not "Added feature"). -- Explain "why" not "what" in the body. -- Never `--force` push. `--force-with-lease` is acceptable when explicitly required. -- Follow the conventional commit format defined in `@assets/commit-template.md`. -- Reference issues in the commit body when applicable. -- `auto` mode never asks for confirmation. `interactive` mode requires user approval before staging and before committing splits. - -## References - -- None. +- Follow the project's convention in `aidd_docs/memory/vcs.md` when set, else `assets/commit-template.md`. +- One concern per commit. Imperative mood. The body says why, not what. +- Reference the issue in the body when there is one. +- Never `--force` push; `--force-with-lease` only when explicitly asked. +- A hook that rejects the commit is not this skill's job: report which hook and why, then stop. Re-stage only files a hook auto-formatted. +- `auto` never prompts. `interactive` confirms before staging and before each split. +- Commits locally by default; pushes as well only when the push option is set. ## Assets -- `@assets/commit-template.md`: Conventional commit format reference. - -## External data - -- None. +- `assets/commit-template.md`: Conventional commit format reference. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md new file mode 100644 index 00000000..ed6c1d34 --- /dev/null +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md @@ -0,0 +1,22 @@ +# 01 - Collect + +Review the working change and stage what belongs in one atomic commit. + +## Input + +Optional paths to restrict the commit, and the mode (`interactive` default, or `auto`). + +## Output + +The staged set for one commit, and the concern it covers. + +## Process + +1. **Read.** Look at the diff and group it by concern. +2. **Pick.** Stage the files for one concern. With explicit paths, stage exactly those; otherwise keep what is already staged, never adding unstaged files on your own. +3. **Split.** When several concerns are mixed, stage one at a time with `git add -p`. In `interactive`, propose each split (its scope and why) and wait for approval. + +## Test + +- The staged set covers one concern, nothing unrelated. +- Files the user did not name or stage are left untouched. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md deleted file mode 100644 index b0a8171a..00000000 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md +++ /dev/null @@ -1,55 +0,0 @@ -# 01 - Commit - -Stage files, generate or accept a commit message, run the commit, optionally push, and return the resulting sha. - -## Inputs - -```yaml -mode: interactive | auto # default: interactive -message: <imposed commit message> # optional; when set, used as-is, no generation -push: true | false # default: false -files: [<paths>] # optional; restrict staging to these paths -``` - -When invoked via slash command, parse `$ARGUMENTS`: - -- contains the word `push` → set `push: true` -- empty or anything else → leave `push: false` - -## Outputs - -```yaml -commit_sha: <full sha> -branch: <branch name> -pushed: true | false -``` - -## Process - -1. **Branch resolution**. Pick first match: - - branch already checked out -> use it - - `mode = auto` -> generate a conventional name from the change - - `mode = interactive` -> propose a name and wait for user approval -2. **Staging**. Pick first match: - - `files` set -> `git add` exactly those paths - - default -> use already-staged changes; do not add unstaged paths implicitly -3. **Message resolution**. Pick first match: - - `message` provided -> use it verbatim, skip steps 4 and 5 - - `mode = auto` -> inspect diff and `git log -5 --pretty=%B`, generate a message per `assets/commit-template.md`, no approval - - `mode = interactive` -> draft a message per the template, then proceed to steps 4 and 5 -4. **Interactive split** (when `mode = interactive` and multiple concerns are present). For each split, show: - - **Scope**: file list (proposal-only). - - **Draft message**: conventional subject; body explains "why", never lists files. - Wait for user approval. -5. **Interactive stage** (when `mode = interactive`). Run `git add -p` for each split. -6. **Commit**. Run `git commit` with the chosen message via heredoc. -7. **Hook recovery**. When a pre-commit hook fails, fix the underlying issue, re-stage, and create a new commit (do not amend). Loop until commit succeeds. -8. **Capture sha**. Read `git rev-parse HEAD`. -9. **Push**. When `push: true`, run `git push`. Use `--force-with-lease` only when explicitly required. Never `--force`. -10. **Return** the structured Outputs block. In interactive mode, also notify the user. - -## Test - -- **Sha match**: `git rev-parse HEAD` returns the new commit sha that matches the `commit_sha` field in Outputs. -- **Format**: `git log -1 --pretty=%s` matches the conventional commit regex `^(feat|fix|docs|style|refactor|perf|test|chore|build|ci)(\([^)]+\))?: .+`. -- **Push**: when `push: true`, `git ls-remote origin <branch>` lists a sha equal to `commit_sha`. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/02-message.md b/plugins/aidd-vcs/skills/01-commit/actions/02-message.md new file mode 100644 index 00000000..f4254a50 --- /dev/null +++ b/plugins/aidd-vcs/skills/01-commit/actions/02-message.md @@ -0,0 +1,22 @@ +# 02 - Message + +Write the commit message for the staged change. + +## Input + +The staged set from `01-collect`, and an optional imposed message. + +## Output + +The commit message, conventional unless the project sets another convention. + +## Process + +1. **Source.** Use an imposed message as-is, else write a conventional message following the project's convention. +2. **Write.** Draft from the staged diff: imperative subject, a body that says why when it is not obvious. +3. **Confirm.** In `interactive`, show it and wait for approval. In `auto`, proceed. + +## Test + +- The subject matches the project's convention (conventional commit by default). +- The message describes the staged change, not unrelated files. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md new file mode 100644 index 00000000..49d2a7aa --- /dev/null +++ b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md @@ -0,0 +1,23 @@ +# 03 - Commit + +Record the commit, and push when asked. + +## Input + +The staged set from `01-collect`, the message from `02-message`, and whether to push (a trailing `push` argument). + +## Output + +The commit sha, the branch, and whether it was pushed. + +## Process + +1. **Commit.** Run `git commit` with the message. +2. **Hook.** If a pre-commit hook rejects it, report which hook and why, then stop; fixing it is the caller's job. Re-stage and retry once only when the hook merely auto-formatted files. +3. **Push.** When asked, push the branch. Use `--force-with-lease` only when explicitly required, never `--force`. + +## Test + +- `git rev-parse HEAD` returns the new sha and its message matches the project convention. +- A rejecting hook leaves no commit and a clear report, not a retry loop. +- When pushed, the remote branch shows the sha. diff --git a/plugins/aidd-vcs/skills/02-pull-request/README.md b/plugins/aidd-vcs/skills/02-pull-request/README.md index 82dbe60f..8482dc0d 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/README.md +++ b/plugins/aidd-vcs/skills/02-pull-request/README.md @@ -29,9 +29,9 @@ Use skill aidd-vcs:02-pull-request Or via the slash command: `/pull-request`. -The skill runs a single action (`pull-request`) that detects the base -branch, fills the template, validates the title / body / base with the user, -then opens the request as a draft. +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 @@ -51,5 +51,5 @@ then opens the request as a draft. ## Technical details See [`SKILL.md`](SKILL.md) for the action contract. Templates ship in -[`assets/`](assets/): `pull_request.md` (request body), `branch.md` (naming -conventions), `CONTRIBUTING.md`, and `README.md`. +[`assets/`](assets/): `pull_request.md` (request body) and `branch.md` (naming +conventions). diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 638e29cb..44955ff2 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -1,41 +1,31 @@ --- name: 02-pull-request -description: Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits. +description: 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. +argument-hint: collect | draft | create --- # Pull Request -Drafts pull or merge requests from the current branch using the team's template, ready for the user to promote. +Collect the change, draft the request, create it as a draft. `01 → 02 → 03`. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | --------------- | ------------------------------------------------------------------- | ---------------------------------------------- | -| 01 | `pull-request` | Detect base, fill template, validate with user, open the draft request | base_branch (optional), template_overrides | - -## Default flow - -Single action skill. The router dispatches to `pull-request` whenever a PR/MR phrase or slash command appears. +| # | Action | Step | +| --- | --------- | ----------------------------------------------------------- | +| 01 | `collect` | Resolve the base and gather the commits since it | +| 02 | `draft` | Write the title and body from the template | +| 03 | `create` | Open the draft request, label it, return the URL | ## Transversal rules -- Detect the base branch from repo state. Do NOT assume `main` or `master` (common alternatives: `develop`, `staging`). -- Always ask the user to validate the title, body, and base branch before creating the request. -- Open the request as a draft. The user promotes it manually when ready. -- Never commit, never push the working branch, never create new branches inside this skill. -- Tool-agnostic: read the VCS tool from project memory; fall back to inspecting the remote URL. - -## References - -- None. +- Follow the project's request practices in `aidd_docs/memory/vcs.md` and the repo's own request template when set, else the bundled `assets/pull_request.md`. +- Resolve the base from the branch's prefix per the project's convention (`vcs.md`), else the repo's default branch. Never assume `main`. +- The request is always a draft; the user promotes it. +- Apply only the triage label the branch prefix maps to, when it exists. Labels never change the base. +- Read the VCS tool from project memory, else infer it from the remote URL. +- Never commit, push, or branch here. ## Assets -- `@assets/pull_request.md`: Request body template. -- `@assets/branch.md`: Branch naming conventions. -- `@assets/CONTRIBUTING.md`: Contribution guidelines template. -- `@assets/README.md`: README template. - -## External data - -- None. +- `assets/pull_request.md`: Request body template. +- `assets/branch.md`: Branch-naming convention, the fallback when project memory sets none. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-collect.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-collect.md new file mode 100644 index 00000000..ef5042d9 --- /dev/null +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-collect.md @@ -0,0 +1,22 @@ +# 01 - Collect + +Resolve the base branch and gather the change to describe. + +## Input + +An optional base branch, overriding the resolved one. + +## Output + +The VCS tool, the head and base branches, and the commits and changed files since the base. + +## Process + +1. **Tool.** Use the VCS tool from project memory, else infer it from the remote URL. +2. **Base.** Use a provided base, else resolve it per the project's branch convention, else the repo's default branch. Surface the base and why. +3. **Gather.** Summarize the commits and changed files since the base. + +## Test + +- The resolved base matches the branch prefix when one maps, not a blind `main`. +- The summary reflects the commits between base and head. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md deleted file mode 100644 index 995eb329..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ /dev/null @@ -1,43 +0,0 @@ -# 01 - Pull Request - -Detect the base branch, fill the request template with recent commits, validate with the user, and open a draft request via the configured VCS tool. - -## Inputs - -```yaml -base_branch: <branch name> # optional; auto-detect from repo state when omitted -template_overrides: # optional; override specific template sections - title: <imposed title> - body: <imposed body> -``` - -## Outputs - -```yaml -pr_url: <url> -pr_number: <int> -branch: <head branch> -base: <base branch> -is_draft: true -``` - -## Process - -1. **Tool resolution**. Pick first match: - - VCS tool declared in project memory -> use it - - default -> map `git remote get-url origin` to the matching configured tool -2. **Branch identity**. Read current head via `git rev-parse --abbrev-ref HEAD`. -3. **Base resolution**. Pick first match: - - `base_branch` provided -> use it - - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging`; surface the chosen value during validation -4. **Collect changes**. Run `git log <base>..HEAD --pretty=fuller` and `git diff <base>...HEAD --stat` to summarize commits and impacted files. -5. **Read template**. Load `assets/pull_request.md` and any contributing rules from `assets/CONTRIBUTING.md`. -6. **Fill template**. Generate a concise title and a body that follows the template structure, using the change summary from step 4. -7. **Validate with user**. Show title, body, and detected base branch. Apply `template_overrides` when provided. Wait for explicit user approval. -8. **Open draft**. Invoke the configured VCS tool to create the request as a draft, passing base, title, and body. Capture the returned URL and number. -9. **Return** the structured Outputs block. - -## Test - -- **Tool view**: querying the configured VCS tool for the created request returns a record where `url` equals `pr_url`, `base` equals the resolved base branch, and the draft flag is true. -- **Reachable**: the created request is reachable at `pr_url` and lists the head branch as the current branch. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md b/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md new file mode 100644 index 00000000..36b5c4e6 --- /dev/null +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md @@ -0,0 +1,22 @@ +# 02 - Draft + +Write the request title and body from the change. + +## Input + +The collected base, commits, and changed files from `01-collect`, and optional title or body overrides. + +## Output + +The proposed title, body, and base, approved by the user. + +## Process + +1. **Template.** Load the request template, the project's own when set, else the bundled `@../assets/pull_request.md`. +2. **Write.** Draft a concise title and a body following the template from the change summary. +3. **Confirm.** Show the title, body, and base, apply any overrides, and wait for approval. + +## Test + +- The body follows the project's template sections when one exists. +- The user approved the title, body, and base before creation. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md b/plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md new file mode 100644 index 00000000..54f86c08 --- /dev/null +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md @@ -0,0 +1,23 @@ +# 03 - Create + +Open the approved draft request and label it. + +## Input + +The approved title, body, and base from `02-draft`. + +## Output + +The draft request's URL and number, with its head and base. + +## Process + +1. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. +2. **Label.** When the head prefix maps to a triage label that exists, apply it; skip silently otherwise. +3. **Return.** Surface the URL, number, head, and base. + +## Test + +- The request exists as a draft with its base equal to the resolved base. +- A mapped, existing triage label is applied; an absent one is skipped without error. +- The request is reachable at its URL with the head branch as its source. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md deleted file mode 100644 index 516531f5..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: contributing -description: Project contribution guidelines template -argument-hint: N/A ---- - -# Contributing to [Project Name] - -Welcome to the [Project Name] contribution guide! We appreciate your interest in helping us improve and grow this project. This document outlines how you can contribute effectively. - -> [Vision Statement or Mission of the Project, our Why] - -## 📐 Contributing Guidelines - -- Who can contribute? -- Roles and responsibilities? -- Code of conduct... - -## ❓ What can YOU do to help? - -<!-- -- Report bugs -- Suggest features -- Write code -- Improve documentation -- ... ---> - -### <action> - -1. ... - -## 📌 Where are features to build? - -[...] - -## 💠 Onboarding in the Contributing flow - -### Documentation links - -- [<filename>](./) - -### Pre-requisites environment setup (optional) - -[...] - -### Steps to follow - -1. ... - -## 🌲 Branch naming - -- - -## 👌 Commit Guidelines - -- - -## 🧪 Testing Guidelines - -- ... - -## 🚀 Publishing (Maintainers Only) - -### Authentication Setup - -### Process to Publish diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md b/plugins/aidd-vcs/skills/02-pull-request/assets/README.md deleted file mode 100644 index 35c3efaa..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: readme -description: Project README template -argument-hint: N/A ---- - -# [Project Name] - -[Summary] - -## Installation Process - -## Usage - -## Access - -## Development Workflow - -## Documentation Structure - -| File | Description | -| ----- | ----------- | -| `...` | ... | - -## Common issues - -### Troubleshooting - -## 📄 License - -## Contributing - -We welcome contributions from the community. Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md b/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md index 2ef27410..70b0c16a 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md +++ b/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md @@ -18,7 +18,7 @@ type/ticket-short-description | ------------ | ------------------------- | | `feat/` | New feature | | `fix/` | Bug fix | -| `aidd_docs/` | Documentation only | +| `docs/` | Documentation only | | `refactor/` | Code change (no feat/fix) | | `chore/` | Build, config, deps | | `test/` | Add/update tests | diff --git a/plugins/aidd-vcs/skills/03-release-tag/SKILL.md b/plugins/aidd-vcs/skills/03-release-tag/SKILL.md index 884151f7..3fbe0ab5 100644 --- a/plugins/aidd-vcs/skills/03-release-tag/SKILL.md +++ b/plugins/aidd-vcs/skills/03-release-tag/SKILL.md @@ -1,39 +1,27 @@ --- name: 03-release-tag -description: Cut a semver release with annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags. +description: 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. --- # Release Tag Cuts annotated semver releases with notes derived from recent commits. -## Available actions +## Actions | # | Action | Role | Input | | --- | -------------- | -------------------------------------------------------------------------- | ---------------------------------- | | 01 | `release-tag` | Compute version, draft notes, validate, bump, tag, push | version (optional), notes_overrides| -## Default flow - -Single action skill. The router dispatches to `release-tag` whenever a release or tag phrase appears. - ## Transversal rules - Versions follow semver `major.minor.patch` strictly. No suffixes unless explicitly requested. - Tags are annotated (`git tag -a`), never lightweight. -- Release notes are mandatory and follow `@assets/release-template.md`. +- Release notes are mandatory and follow `assets/release-template.md`. - Always ask the user to validate the version, notes, and impacted files before tagging. - Never `--force` push tags. Use `--force-with-lease` only when explicitly required. - The bump commit only includes version-manager files (e.g. `package.json`, `pyproject.toml`). -## References - -- None. - ## Assets -- `@assets/release-template.md`: Release notes template. - -## External data - -- None. +- `assets/release-template.md`: Release notes template. diff --git a/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md b/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md index 0e14067b..b8c0dcf8 100644 --- a/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md +++ b/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md @@ -2,51 +2,30 @@ Compute the next semver version from recent commits, draft release notes from the template, validate with the user, create a bump commit, then tag and push. -## Inputs +## Input -```yaml -version: <semver> # optional; auto-computed from commits since last tag when omitted -notes_overrides: # optional; impose specific notes content - title: <imposed title> - body: <imposed body> -``` +An optional explicit semver version (auto-computed from commits since the last tag when omitted), and optional note overrides imposing a specific title and body. -## Outputs +## Output -```yaml -tag: v<semver> -commit_sha: <bump commit sha> -pushed: true -release_url: <url> -``` +The created `v<semver>` tag, its bump commit sha, and the release URL, with the tag pushed to the remote. ## Process -1. **Read current version**. Pick first match: - - version manager file present (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.) -> read its version field - - default -> `1.0.0` -2. **Read latest tag**. Pick first match: - - `git tag --sort=-version:refname | head -1` non-empty -> use it - - default -> treat as `v1.0.0` -3. **Collect commits**. Run `git log --oneline "<latest>..HEAD"`. -4. **Compute next version**. Pick first match: - - `version` input provided -> use it - - any commit body contains `BREAKING CHANGE` -> bump major - - any commit type is `feat` -> bump minor - - default -> bump patch -5. **Draft release notes**. Fill `assets/release-template.md` with the change list from step 3. Apply `notes_overrides` when provided. -6. **Validate**. Show full notes, computed version, and version-manager files about to change. Wait for explicit user approval. -7. **Bump commit**. Stage only version-manager files. Create a `chore: bump version to v<semver>` commit via heredoc. -8. **Create tag**. Run `git tag -a v<semver> -m <notes title>`. -9. **Push commit**. Run `git push`. -10. **Push tag**. Run `git push origin v<semver>`. -11. **Resolve release URL**. Pick first match: - - configured VCS tool exposes a release-view command -> capture the returned URL - - default -> compose URL from `git remote get-url origin` and the tag name +1. **Current.** Read the version from a version-manager file (`package.json`, `pyproject.toml`, `Cargo.toml`) when present, else `1.0.0`. +2. **Latest.** Take the latest tag from `git tag --sort=-version:refname | head -1`. When there are no tags, note that there is no prior tag, never inventing one. +3. **Collect.** With a prior tag, list the commits in `<latest>..HEAD`. With no prior tag, list every commit on the branch. +4. **Compute.** Use the provided version when given. Otherwise bump major on a `BREAKING CHANGE`, minor on any `feat`, else patch. +5. **Draft.** Fill `@../assets/release-template.md` with the change list, applying any note overrides. +6. **Validate.** Show the full notes, the computed version, and the version-manager files about to change. Wait for explicit approval. +7. **Bump.** Stage the version-manager files and create a `chore: bump version to v<semver>` commit. +8. **Tag.** Run `git tag -a v<semver> -m <notes title>`. +9. **Push.** Push the commit, then push the tag with `git push origin v<semver>`. +10. **URL.** Capture the release URL from the configured VCS tool's release view when it has one, else compose it from the remote URL and the tag. ## Test -- **Local tag**: `git tag -l v<semver>` returns the new tag exactly once. -- **Semver shape**: the tag matches `^v[0-9]+\.[0-9]+\.[0-9]+$`. -- **Remote tag**: `git ls-remote --tags origin "refs/tags/v<semver>"` returns one row, confirming the tag is on the remote. -- **Commit link**: `git rev-parse "v<semver>^{commit}"` resolves to the bump commit sha returned in Outputs. +- `git tag -l v<semver>` returns the new tag exactly once. +- The tag matches `^v[0-9]+\.[0-9]+\.[0-9]+$`. +- `git ls-remote --tags origin "refs/tags/v<semver>"` returns one row. +- `git rev-parse "v<semver>^{commit}"` resolves to the returned bump commit sha. diff --git a/plugins/aidd-vcs/skills/04-issue-create/SKILL.md b/plugins/aidd-vcs/skills/04-issue-create/SKILL.md index 0f28c566..60c074f3 100644 --- a/plugins/aidd-vcs/skills/04-issue-create/SKILL.md +++ b/plugins/aidd-vcs/skills/04-issue-create/SKILL.md @@ -1,40 +1,28 @@ --- name: 04-issue-create -description: Create an issue in the configured ticketing tool. Use when the user says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues. +description: 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. --- # Issue Create Files well-formed issues in the configured tracker after gathering enough context to be actionable. -## Available actions +## Actions | # | Action | Role | Input | | --- | --------------- | -------------------------------------------------------------------------- | -------------------------------------- | | 01 | `issue-create` | Detect tool, fill template, validate, open the issue | problem_description, labels, type | -## Default flow - -Single action skill. The router dispatches to `issue-create` whenever an issue or bug-report phrase appears. - ## Transversal rules -- Detect the ticketing tool from project memory first, then fall back to inspecting `git remote get-url origin`. +- Detect the ticketing tool from project memory first, then fall back to inferring it from the remote URL. - Tool-agnostic: invoke whichever ticketing tool is configured for the project. - Always wait for explicit user approval of title, body, labels, type, projects, and milestones before creating. -- Issue body follows `@assets/issue-template.md`. +- Issue body follows `assets/issue-template.md`. - Be thorough and concise. Short sentences. Focus on clarity, reproduction steps, and expected behavior. -- Read `@assets/CONTRIBUTING.md` for project-specific issue rules before drafting. - -## References - -- None. +- Read `assets/CONTRIBUTING.md` for project-specific issue rules before drafting. ## Assets -- `@assets/issue-template.md`: Issue / ticket body template. -- `@assets/CONTRIBUTING.md`: Contribution guidelines, including issue process. - -## External data - -- None. +- `assets/issue-template.md`: Issue / ticket body template. +- `assets/CONTRIBUTING.md`: Contribution guidelines, including issue process. diff --git a/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md b/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md index e81a921a..e0419bc5 100644 --- a/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md +++ b/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md @@ -2,42 +2,25 @@ Detect the ticketing tool, gather a thorough problem description, fill the issue template, validate with the user, then create the issue. -## Inputs - -```yaml -problem_description: <free text> # required -repo_url: <url> # optional; default: derived from `git remote get-url origin` -labels: [<label>] # optional -type: bug | feature | task | docs # optional; default: inferred from description -projects: [<project>] # optional -milestone: <milestone> # optional -``` - -## Outputs - -```yaml -tool: <configured ticketing tool> -issue_url: <url> -issue_number: <int> -title: <issue title> -labels: [<label>] -type: <type> -``` +## Input + +A problem description (required), plus optional labels, projects, a milestone, and a repo URL (inferred from the remote when omitted). + +## Output + +The created issue's URL and number, with its title and labels. ## Process -1. **Tool resolution**. Pick first match: - - ticketing tool declared in project memory -> use it - - default -> map `git remote get-url origin` to the matching configured tool -2. **Read context**. Load `assets/CONTRIBUTING.md` and `assets/issue-template.md`. Skim existing open issues via the configured tool to avoid duplicates. -3. **Gather details**. Combine `problem_description` with technical context (stack, repro steps, environment). Ask the user follow-up questions when required fields are missing. -4. **Web search**. Look up official documentation that backs the issue when applicable (e.g. linked errors, framework changelog). -5. **Fill template**. Generate a concise title and body that match the template structure. Pick a `type` (bug, feature, task, docs) when not provided. -6. **Validate**. Show title, body, labels, type, projects, and milestone. Wait for explicit user approval. -7. **Create**. Invoke the configured ticketing tool to open the issue, passing title, body, labels, projects, and milestone. -8. **Capture** the returned URL and number. Return the structured Outputs block. +1. **Tool.** Use the ticketing tool declared in project memory. Otherwise infer it from the remote URL. +2. **Context.** Load `@../assets/CONTRIBUTING.md` and `@../assets/issue-template.md`, and skim existing open issues via the tool to avoid duplicates. +3. **Gather.** Combine the problem description with technical context (stack, repro steps, environment). Ask follow-up questions when required fields are missing. +4. **Research.** Look up official documentation that backs the issue when applicable (linked errors, framework changelog). +5. **Fill.** Write a concise title and body matching the template. +6. **Validate.** Show the title, body, labels, projects, and milestone. Wait for explicit approval. +7. **Create.** Invoke the configured tool to open the issue, passing the title, body, labels, projects, and milestone, then capture the returned URL and number. ## Test -- **Tool view**: querying the configured ticketing tool for the created issue returns a record where `url` equals `issue_url`, `title` equals the validated title, and `labels` matches the validated labels. -- **Reachable**: the created issue is reachable at `issue_url` in the tracker UI. +- Querying the configured tool for the created issue returns a record whose URL, title, and labels match the validated values. +- The created issue is reachable at its URL in the tracker UI. diff --git a/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md b/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md index 57b2b8b8..0f7af87b 100644 --- a/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md +++ b/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md @@ -8,7 +8,7 @@ argument-hint: N/A AI instructions: -- be focused on creating clear, concise, and actionable GitHub issues. +- be focused on creating clear, concise, and actionable issues in the configured tracker. - no over-thinking nor over-complicating. --> diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2aaaa136..a848ebe5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -12,8 +12,8 @@ importers: specifier: ^21.0.2 version: 21.0.2(@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 @@ -21,8 +21,8 @@ importers: specifier: 3.0.1 version: 3.0.1(ajv@8.20.0) js-yaml: - specifier: 4.2.0 - version: 4.2.0 + specifier: 5.0.0 + version: 5.0.0 lefthook: specifier: ^2.1.9 version: 2.1.9 @@ -42,8 +42,8 @@ packages: engines: {node: '>=22.12.0'} hasBin: true - '@commitlint/config-conventional@21.0.2': - resolution: {integrity: sha512-P/ZRhryQmkj0Z0dY9FOoRwe3xkwJyyAdtXwt01NT2kuZttcG2CNYp1q5Ci3u+nDT2jcbJRw2kt13Czl1qKNPfg==} + '@commitlint/config-conventional@21.2.0': + resolution: {integrity: sha512-Qf8WRDVcyVd14if6VTWenebxFbKnVnbzPUJjlzjkyJGeHK2xCGd63Dr1XZzj0plXKQb9P0BfOxoc1HVeCo2BWQ==} engines: {node: '>=22.12.0'} '@commitlint/config-validator@21.0.1': @@ -106,6 +106,10 @@ packages: 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 +122,10 @@ packages: conventional-commits-parser: optional: true + '@conventional-changelog/template@1.2.0': + resolution: {integrity: sha512-12qHxvlKjHmP0PQ+17EREgC7lWyLwbph1RKcZQZ7k7ZWGmrxfxC9gadHGfvzr0g0u8BhiBGg3tks93txodlyRQ==} + engines: {node: '>=22'} + '@simple-libs/child-process-utils@1.0.2': resolution: {integrity: sha512-/4R8QKnd/8agJynkNdJmNw2MBxuFTRcNFnE5Sg/G+jkSsV8/UBgULMzhizWWW42p8L5H7flImV2ATi79Ove2Tw==} engines: {node: '>=18'} @@ -126,6 +134,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==} @@ -169,15 +181,20 @@ packages: resolution: {integrity: sha512-6gfI3otXK5Ph5DfCOI1dblr+kN3FAm5a97hYoQkqNZxOaYa5WKfXH+AnpsmS+iUH2mgVC2Cg2Qw9m5OKcmNrIg==} engines: {node: '>=18'} - conventional-changelog-conventionalcommits@9.3.1: - resolution: {integrity: sha512-dTYtpIacRpcZgrvBYvBfArMmK2xvIpv2TaxM0/ZI5CBtNUzvF2x0t15HsbRABWprS6UPmvj+PzHVjSx4qAVKyw==} - engines: {node: '>=18'} + conventional-changelog-conventionalcommits@10.2.0: + resolution: {integrity: sha512-UtlM9GqolY7OmlQh5L/UEVoKsTUpTgUVy1PU8JN5gl5Ydaejb7WRklGliG1SKPxxj7hzA173eG3Kt5fYWE2pmg==} + engines: {node: '>=22'} conventional-commits-parser@6.4.0: resolution: {integrity: sha512-tvRg7FIBNlyPzjdG8wWRlPHQJJHI7DylhtRGeU9Lq+JuoPh5BKpPRX83ZdLrvXuOSu5Eo/e7SzOQhU4Hd2Miuw==} engines: {node: '>=18'} hasBin: true + conventional-commits-parser@7.0.0: + resolution: {integrity: sha512-dZe/p+FgGQLNJFqaCgNdl8j6a7gI8xuaN30Wy5g7nvyK3jqOpNUEUZ3pGJ5D68h89uRh038FtkeOk/bnGmYkmg==} + engines: {node: '>=22'} + hasBin: true + cosmiconfig-typescript-loader@6.3.0: resolution: {integrity: sha512-Akr82WH1Wfqatyiqpj8HDkO2o2KmJRu1FhKfSNJP3K4IdXwHfEyL7MOb62i1AGQVLtIQM+iCE9CGOtrfhR+mmA==} engines: {node: '>=v18'} @@ -233,6 +250,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: @@ -269,6 +287,10 @@ packages: resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==} hasBin: true + js-yaml@5.0.0: + resolution: {integrity: sha512-GSvaPUbk1U+FMZ7rJzF+F8e5YVtu7KnD40et/5rBXXRBv2jCO9L3qCewvIDDdudC0QycTFlf6EAA+h3kxBsuUw==} + hasBin: true + json-parse-even-better-errors@2.3.1: resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==} @@ -336,6 +358,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'} @@ -425,19 +451,19 @@ snapshots: - conventional-commits-parser - typescript - '@commitlint/config-conventional@21.0.2': + '@commitlint/config-conventional@21.2.0': dependencies: - '@commitlint/types': 21.0.1 - conventional-changelog-conventionalcommits: 9.3.1 + '@commitlint/types': 21.2.0 + conventional-changelog-conventionalcommits: 10.2.0 '@commitlint/config-validator@21.0.1': dependencies: - '@commitlint/types': 21.0.1 + '@commitlint/types': 21.2.0 ajv: 8.20.0 '@commitlint/ensure@21.0.1': dependencies: - '@commitlint/types': 21.0.1 + '@commitlint/types': 21.2.0 es-toolkit: 1.47.0 '@commitlint/execute-rule@21.0.1': {} @@ -495,7 +521,7 @@ snapshots: '@commitlint/resolve-extends@21.0.1': dependencies: '@commitlint/config-validator': 21.0.1 - '@commitlint/types': 21.0.1 + '@commitlint/types': 21.2.0 es-toolkit: 1.47.0 global-directory: 5.0.0 resolve-from: 5.0.0 @@ -518,6 +544,11 @@ snapshots: conventional-commits-parser: 6.4.0 picocolors: 1.1.1 + '@commitlint/types@21.2.0': + dependencies: + conventional-commits-parser: 7.0.0 + 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 @@ -526,12 +557,16 @@ snapshots: optionalDependencies: conventional-commits-parser: 6.4.0 + '@conventional-changelog/template@1.2.0': {} + '@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 @@ -572,15 +607,20 @@ snapshots: dependencies: compare-func: 2.0.0 - conventional-changelog-conventionalcommits@9.3.1: + conventional-changelog-conventionalcommits@10.2.0: dependencies: - compare-func: 2.0.0 + '@conventional-changelog/template': 1.2.0 conventional-commits-parser@6.4.0: dependencies: '@simple-libs/stream-utils': 1.2.0 meow: 13.2.0 + conventional-commits-parser@7.0.0: + 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.1(typescript@5.9.3))(typescript@5.9.3): dependencies: '@types/node': 25.3.5 @@ -654,6 +694,10 @@ snapshots: dependencies: argparse: 2.0.1 + js-yaml@5.0.0: + dependencies: + argparse: 2.0.1 + json-parse-even-better-errors@2.3.1: {} json-schema-traverse@1.0.0: {} @@ -705,6 +749,8 @@ snapshots: meow@13.2.0: {} + meow@14.1.0: {} + parent-module@1.0.1: dependencies: callsites: 3.1.0 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" + } + ] } } } diff --git a/scripts/__tests__/check-markdown-links.test.js b/scripts/__tests__/check-markdown-links.test.js new file mode 100644 index 00000000..4ccaeb28 --- /dev/null +++ b/scripts/__tests__/check-markdown-links.test.js @@ -0,0 +1,200 @@ +const assert = require("node:assert/strict"); +const { spawnSync } = require("node:child_process"); +const fs = require("node:fs"); +const path = require("node:path"); +const test = require("node:test"); + +const { + formatIssue, + reportProblems, +} = require("../check-markdown-links.js"); + +const root = path.resolve(__dirname, "../.."); +const script = path.join(root, "scripts/check-markdown-links.js"); + +test("formatIssue includes correction details", () => { + assert.equal( + formatIssue({ + raw: "./courses/intro.md", + reason: "cross-repo-relative-link", + suggestion: "https://github.com/ai-driven-dev/framework/blob/main/courses/intro.md", + }), + "./courses/intro.md (cross-repo relative link; suggestion: https://github.com/ai-driven-dev/framework/blob/main/courses/intro.md)", + ); +}); + +test("reportProblems writes a markdown source issue table", () => { + const lines = []; + const originalConsoleError = console.error; + console.error = (line = "") => lines.push(line); + + try { + reportProblems( + [ + { + file: path.join(root, "CLAUDE.md"), + line: 34, + raw: "@aidd_docs/memory/architecture.md", + reason: "local-path-not-found", + }, + ], + 339, + ); + } finally { + console.error = originalConsoleError; + } + + assert.deepEqual(lines, [ + "| source | issue |", + "| - | - |", + "| CLAUDE.md:34 | @aidd_docs/memory/architecture.md (local path not found) |", + "", + "❌ Links: 1 broken in 339 files", + ]); +}); + +test("reportProblems writes a success summary when there are no problems", () => { + const lines = []; + + const status = reportProblems([], 42, () => { + throw new Error("unexpected error logger call"); + }, (line) => lines.push(line)); + + assert.equal(status, 0); + assert.deepEqual(lines, ["✅ Links: 0 broken in 42 files"]); +}); + +test("--help documents supported links, exclusions, fixes, and examples", () => { + const result = spawnSync(process.execPath, [script, "--help"], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /node scripts\/check-markdown-links\.js \[--ignore path\]/u); + assert.match(result.stdout, /Markdown links and images/u); + assert.match(result.stdout, /@path/u); + assert.match(result.stdout, /src: path/u); + assert.match(result.stdout, /Anchor-only links/u); + assert.match(result.stdout, /mailto:/u); + assert.match(result.stdout, /tel:/u); + assert.match(result.stdout, /HTML angle-bracket/u); + assert.match(result.stdout, /\.git and node_modules/u); + assert.match(result.stdout, /Runtime variables, glob patterns, and bare words/u); + assert.match(result.stdout, /\| Need \| Use \|/u); + assert.match(result.stdout, /\| Include\/import a file in agent context \| @path\/to\/file\.md \|/u); + assert.match(result.stdout, /\| Reference a file for the reader \| \[label\]\(path\/to\/file\.md\) \|/u); + assert.match(result.stdout, /\| Case \| Example \|/u); + assert.match(result.stdout, /@plugins\/aidd-context\/skills\/11-explore\/SKILL\.md/u); + assert.match(result.stdout, /\[explore skill\]\(plugins\/aidd-context\/skills\/11-explore\/SKILL\.md\)/u); +}); + +test("CLI checks one markdown file covering supported, ignored, and broken forms", () => { + const tempDir = fs.mkdtempSync(path.join(root, "scripts/__tests__/.tmp-check-markdown-links-")); + const fixture = path.join(tempDir, "all-cases.md"); + const readmePath = path.relative(tempDir, path.join(root, "README.md")); + const logoPath = path.relative(tempDir, path.join(root, "docs/assets/logo.png")); + const claudePath = path.relative(tempDir, path.join(root, "CLAUDE.md")); + const contributingPath = path.relative(tempDir, path.join(root, "CONTRIBUTING.md")); + const outsidePath = path.relative(tempDir, path.resolve(root, "..", "outside.md")); + const outsideSuggestion = "https://github.com/ai-driven-dev/framework/blob/main/outside.md"; + + fs.writeFileSync( + fixture, + [ + "# Link checker fixture", + "", + "## Supported existing forms", + `See [README](${readmePath}).`, + `![Logo](${logoPath})`, + `@${claudePath}`, + `src: ${contributingPath}`, + "", + "## Ignored forms", + "[Anchor only](#local-heading)", + "[Mail](mailto:security@example.com)", + "[Phone](tel:+33123456789)", + "<https://example.com>", + `<img src="${logoPath}" alt="Logo">`, + "src: $ARGUMENTS", + "src: plugins/*/README.md", + "src: README", + "[External URL](https://example.com/not-checked.md)", + "", + "## Broken forms", + "[Missing markdown](./missing.md)", + "@./missing-agent.md", + "src: ./missing-source.md", + `[Cross repo](${outsidePath})`, + "", + ].join("\n"), + "utf8", + ); + + try { + const result = spawnSync(process.execPath, [script, fixture], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.match(result.stderr, /\| source \| issue \|/u); + assert.match(result.stderr, /\| - \| - \|/u); + assert.match(result.stderr, /missing\.md \(local path not found\)/u); + assert.match(result.stderr, /@\.\/missing-agent\.md \(local path not found\)/u); + assert.match(result.stderr, /\.\/missing-source\.md \(local path not found\)/u); + assert.ok( + result.stderr.includes(`${outsidePath} (cross-repo relative link; suggestion: ${outsideSuggestion})`), + result.stderr, + ); + assert.match(result.stderr, /❌ Links: 4 broken in 1 files/u); + + assert.doesNotMatch(result.stderr, /local-heading/u); + assert.doesNotMatch(result.stderr, /mailto:security@example\.com/u); + assert.doesNotMatch(result.stderr, /tel:\+33123456789/u); + assert.doesNotMatch(result.stderr, /(?:^|\s)https?:\/\/example\.com\/not-checked(?:\s|$)/u); + assert.doesNotMatch(result.stderr, /\$ARGUMENTS/u); + assert.doesNotMatch(result.stderr, /plugins\/\*\/README\.md/u); + } finally { + fs.rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("CLI without paths scans the repository and prints a summary", () => { + const result = spawnSync(process.execPath, [script], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /✅ Links: 0 broken in \d+ files/u); +}); + +test("CLI fails when an explicit input path does not exist", () => { + const result = spawnSync(process.execPath, [script, "DOES_NOT_EXIST.md"], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 1); + assert.match(result.stderr, /❌ Path not found: DOES_NOT_EXIST\.md/u); +}); + +test("repository scan ignores interrupted test temp directories", () => { + const tempDir = fs.mkdtempSync(path.join(root, "scripts/__tests__/.tmp-check-markdown-links-")); + + try { + fs.writeFileSync(path.join(tempDir, "leftover.md"), "[Missing](./missing.md)\n", "utf8"); + + const result = spawnSync(process.execPath, [script], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /✅ Links: 0 broken in \d+ files/u); + } finally { + fs.rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/scripts/check-markdown-links.js b/scripts/check-markdown-links.js new file mode 100644 index 00000000..15b7dde6 --- /dev/null +++ b/scripts/check-markdown-links.js @@ -0,0 +1,466 @@ +#!/usr/bin/env node + +const fs = require("node:fs"); +const path = require("node:path"); + +const ROOT = path.resolve(__dirname, ".."); + +const HELP_TEXT = `Usage: + node scripts/check-markdown-links.js [--ignore path] + +Supported link forms: + - Markdown links and images: [label](path), ![alt](path) + - Agent context includes/imports: @path/to/file.md + - Source declarations: src: path/to/file.md + +Ignored / excluded forms: + - Anchor-only links such as #usage + - mailto: and tel: links + - HTML angle-bracket links and HTML attributes + - .git and node_modules directories + - Runtime variables, glob patterns, and bare words + +How to fix broken links: + | Need | Use | + | - | - | + | Include/import a file in agent context | @path/to/file.md | + | Reference a file for the reader | [label](path/to/file.md) | + +Examples: + | Case | Example | + | - | - | + | Agent include/import | @plugins/aidd-context/skills/11-explore/SKILL.md | + | Reader reference | See [explore skill](plugins/aidd-context/skills/11-explore/SKILL.md). | +`; + +const SKIPPED_DIRS = new Set([".git", "node_modules", "worktrees", ".specstory"]); +const SKIPPED_DIR_PREFIXES = [".tmp-check-markdown-links-"]; +const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]); +function normalizePathForDisplay(filePath) { + const relative = path.relative(ROOT, filePath).replaceAll(path.sep, "/"); + return relative || "."; +} + +function normalizeForMatch(filePath) { + return path.resolve(ROOT, filePath); +} + +function pathStartsWith(candidate, parent) { + const relative = path.relative(parent, candidate); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +} + +function parseArgs(argv) { + const paths = []; + const ignores = []; + + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + + if (arg === "--help" || arg === "-h") { + return { help: true, paths, ignores }; + } + + if (arg === "--ignore") { + const ignoredPath = argv[index + 1]; + if (!ignoredPath || ignoredPath.startsWith("--")) { + throw new Error("--ignore requires a path"); + } + ignores.push(ignoredPath); + index += 1; + continue; + } + + paths.push(arg); + } + + return { help: false, paths: paths.length > 0 ? paths : ["."], ignores }; +} + +function isIgnored(filePath, ignoredPaths) { + const absolute = path.resolve(filePath); + return ignoredPaths.some((ignoredPath) => pathStartsWith(absolute, ignoredPath)); +} + +function collectMarkdownFiles(inputPaths, ignoredPaths = []) { + const files = []; + const normalizedIgnores = ignoredPaths.map((ignoredPath) => normalizeForMatch(ignoredPath)); + const missingInputs = inputPaths.filter((inputPath) => !fs.existsSync(path.resolve(ROOT, inputPath))); + + if (missingInputs.length > 0) { + throw new Error(`Path not found: ${missingInputs.join(", ")}`); + } + + function visit(currentPath) { + const absolute = path.resolve(ROOT, currentPath); + if (!fs.existsSync(absolute)) { + return; + } + + if (isIgnored(absolute, normalizedIgnores)) { + return; + } + + const stat = fs.statSync(absolute); + if (stat.isDirectory()) { + const basename = path.basename(absolute); + if (SKIPPED_DIRS.has(basename) || SKIPPED_DIR_PREFIXES.some((prefix) => basename.startsWith(prefix))) { + return; + } + + for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) { + visit(path.join(absolute, entry.name)); + } + return; + } + + if (stat.isFile() && MARKDOWN_EXTENSIONS.has(path.extname(absolute).toLowerCase())) { + files.push(absolute); + } + } + + for (const inputPath of inputPaths) { + visit(inputPath); + } + + return files.sort((a, b) => normalizePathForDisplay(a).localeCompare(normalizePathForDisplay(b))); +} + +function gatherMarkdownFiles(inputs, cwd = ROOT) { + return collectMarkdownFiles(inputs.length > 0 ? inputs : ["."], []).map((file) => path.resolve(cwd, path.relative(ROOT, file))); +} + +function filterIgnoredFiles(files, ignore = [], root = ROOT) { + if (ignore.length === 0) { + return files; + } + + const ignoredPaths = ignore.map((ignoredPath) => path.resolve(root, ignoredPath)); + return files.filter((file) => !isIgnored(file, ignoredPaths)); +} + +function lineNumberAt(content, index) { + return content.slice(0, index).split("\n").length; +} + +function stripTrailingPunctuation(target) { + return target.replace(/[.,;:]+$/u, ""); +} + +function splitMarkdownTarget(rawTarget) { + const trimmed = rawTarget.trim(); + if (trimmed.startsWith("<") && trimmed.endsWith(">")) { + return trimmed; + } + return trimmed.split(/\s+/u)[0]; +} + +function extractLinks(content) { + const links = []; + const markdownLinkPattern = /!?\[[^\]\n]*\]\(([^)\n]+)\)/gu; + const atPathPattern = /(^|[\n\r][ \t>*-]*)@([^\s`)\]},;]+)/gu; + const srcPathPattern = /\bsrc:\s*([^\s`)\]},;]+)/gu; + + for (const match of content.matchAll(markdownLinkPattern)) { + links.push({ + raw: splitMarkdownTarget(match[1]), + index: match.index, + kind: "markdown", + }); + } + + for (const match of content.matchAll(atPathPattern)) { + links.push({ + raw: `@${stripTrailingPunctuation(match[2])}`, + index: match.index + match[1].length, + kind: "agent-import", + }); + } + + for (const match of content.matchAll(srcPathPattern)) { + links.push({ + raw: stripTrailingPunctuation(match[1]), + index: match.index, + kind: "src", + }); + } + + return links; +} + +function isIgnoredTarget(target) { + if (!target) { + return true; + } + + if (target.startsWith("<") && target.endsWith(">")) { + return true; + } + + if (/[<>]/u.test(target)) { + return true; + } + + if (target.startsWith("#")) { + return true; + } + + if (/^(mailto|tel):/iu.test(target)) { + return true; + } + + if (/[*?[\]]/u.test(target)) { + return true; + } + + if (/^\$[\w_]+/u.test(target)) { + return true; + } + + if (/\{\{[^}]+\}\}/u.test(target)) { + return true; + } + + if (!target.includes("/") && !target.includes(".") && !target.startsWith("..")) { + return true; + } + + return false; +} + +function stripAnchor(target) { + const hashIndex = target.indexOf("#"); + return hashIndex === -1 ? target : target.slice(0, hashIndex); +} + +function safeDecodeUri(target) { + try { + return decodeURI(target); + } catch { + return target; + } +} + +function isRemoteUrl(target) { + return /^https?:\/\//iu.test(target); +} + +function resolveLocalPath(target, sourceFile) { + const withoutAnchor = stripAnchor(target); + if (!withoutAnchor) { + return { ignored: true }; + } + + const decoded = safeDecodeUri(withoutAnchor); + if (path.isAbsolute(decoded)) { + return { absolute: path.resolve(ROOT, decoded.slice(1)) }; + } + + const absolute = path.resolve(path.dirname(sourceFile), decoded); + const sourceRelative = normalizePathForDisplay(sourceFile); + const assetTemplateMatch = sourceRelative.match(/^(plugins\/[^/]+\/skills\/[^/]+\/assets)\/.+$/u); + if (assetTemplateMatch) { + const generatedTemplateAbsolute = path.resolve(ROOT, assetTemplateMatch[1], "templates", decoded); + if (!fs.existsSync(absolute) && fs.existsSync(generatedTemplateAbsolute)) { + return { absolute: generatedTemplateAbsolute }; + } + // A *-template.md scaffold links to files emitted next to the generated + // output at runtime (e.g. ./plan.md, ./phase-1.md), which never exist in + // the repo. A dot-relative target that resolves nowhere is an intentional + // placeholder for that generated sibling, not a broken link. + if (!fs.existsSync(absolute) && /-template\.md$/u.test(sourceRelative) && /^\.\.?\//u.test(decoded)) { + return { ignored: true }; + } + } + + if (normalizePathForDisplay(sourceFile).startsWith(".github/")) { + const repoRootAbsolute = path.resolve(ROOT, decoded); + if (!fs.existsSync(absolute) && fs.existsSync(repoRootAbsolute)) { + return { absolute: repoRootAbsolute }; + } + } + + return { absolute }; +} + +function problemForTarget(target, sourceFile) { + const validationTarget = target.startsWith("@") ? target.slice(1) : target; + + if (isIgnoredTarget(validationTarget)) { + return null; + } + + if (isRemoteUrl(validationTarget)) { + return null; + } + + const resolved = resolveLocalPath(validationTarget, sourceFile); + if (resolved.ignored) { + return null; + } + + if (!pathStartsWith(resolved.absolute, ROOT)) { + const repoRelative = path.relative(ROOT, resolved.absolute).replaceAll(path.sep, "/"); + return { + raw: target, + reason: "cross-repo-relative-link", + suggestion: `https://github.com/ai-driven-dev/framework/blob/main/${repoRelative.replace(/^(\.\.\/)+/u, "")}`, + }; + } + + if (!fs.existsSync(resolved.absolute)) { + return { raw: target, reason: "local-path-not-found" }; + } + + return null; +} + +function checkFile(filePath) { + const content = fs.readFileSync(filePath, "utf8"); + const links = extractLinks(content); + const problems = []; + + for (const link of links) { + const problem = problemForTarget(link.raw, filePath); + if (!problem) { + continue; + } + + problems.push({ + ...problem, + file: filePath, + line: lineNumberAt(content, link.index), + kind: link.kind, + }); + } + + return problems; +} + +function checkMarkdownLinks(pathsToCheck, ignoredPaths = []) { + const files = collectMarkdownFiles(pathsToCheck, ignoredPaths); + const problems = files.flatMap((file) => checkFile(file)); + return { files, problems }; +} + +function findBrokenLinks(files) { + return files.flatMap((file) => checkFile(file)); +} + +function issueLink(problem) { + return problem.raw ?? problem.link; +} + +function issueReason(problem) { + if (problem.reason) { + return problem.reason; + } + + switch (problem.type) { + case "cross-repo": + return "cross-repo-relative-link"; + case "broken-remote": + return "remote-url-not-found"; + case "broken-template": + return "template-path-not-found"; + default: + return problem.type; + } +} + +function formatIssue(problem) { + const link = issueLink(problem); + + switch (issueReason(problem)) { + case "cross-repo-relative-link": + return `${link} (cross-repo relative link; suggestion: ${problem.suggestion})`; + case "remote-url-not-found": + return `${link} (remote URL not found locally)`; + case "template-path-not-found": + return `${link} (template path not found in framework source)`; + case "local-path-not-found": + return `${link} (local path not found)`; + default: + return `${link} (file not found)`; + } +} + +function escapeMarkdownTableCell(value) { + return String(value).replaceAll("\\", "\\\\").replaceAll("|", "\\|").replaceAll("\n", " "); +} + +function reportProblems(problems, checkedFileCount, logger = console.error, successLogger = console.log) { + if (problems.length === 0) { + successLogger(`✅ Links: 0 broken in ${checkedFileCount} files`); + return 0; + } + + logger("| source | issue |"); + logger("| - | - |"); + + for (const problem of problems) { + const source = `${normalizePathForDisplay(problem.file)}:${problem.line}`; + logger(`| ${escapeMarkdownTableCell(source)} | ${escapeMarkdownTableCell(formatIssue(problem))} |`); + } + + logger(""); + logger(`❌ Links: ${problems.length} broken in ${checkedFileCount} files`); + return 1; +} + +function runCli(argv = process.argv.slice(2)) { + let parsed; + try { + parsed = parseArgs(argv); + } catch (error) { + console.error(error.message); + console.error("Run with --help for usage."); + return 1; + } + + if (parsed.help) { + console.log(HELP_TEXT); + return 0; + } + + try { + const { files, problems } = checkMarkdownLinks(parsed.paths, parsed.ignores); + reportProblems(problems, files.length); + return problems.length === 0 ? 0 : 1; + } catch (error) { + console.error(`❌ ${error.message}`); + return 1; + } +} + +function run(inputs, { ignore = [] } = {}) { + try { + const { files, problems } = checkMarkdownLinks(inputs && inputs.length > 0 ? inputs : ["."], ignore); + reportProblems(problems, files.length); + return problems.length === 0 ? 0 : 1; + } catch (error) { + console.error(`❌ ${error.message}`); + return 1; + } +} + +if (require.main === module) { + process.exitCode = runCli(); +} + +module.exports = { + HELP_TEXT, + checkFile, + checkMarkdownLinks, + collectMarkdownFiles, + extractLinks, + filterIgnoredFiles, + formatIssue, + gatherMarkdownFiles, + findBrokenLinks, + parseArgs, + problemForTarget, + reportProblems, + run, + runCli, +}; diff --git a/scripts/skill-eval.mjs b/scripts/skill-eval.mjs new file mode 100644 index 00000000..ab66e1f7 --- /dev/null +++ b/scripts/skill-eval.mjs @@ -0,0 +1,140 @@ +#!/usr/bin/env node +// Behavioral eval harness for aidd-refine skills. +// +// Each case runs the skill for real through a headless `claude -p`, in an +// isolated temp project where the skill is installed under a unique name as a +// project skill (`.claude/skills/<evalName>/`). The unique name guarantees the +// worktree copy runs, never a globally-installed plugin of the same name. +// +// Usage: +// node scripts/skill-eval.mjs # run every case (deterministic checks) +// node scripts/skill-eval.mjs 04-shadow-areas # run cases for one skill +// node scripts/skill-eval.mjs --judge # also run LLM-judge criteria (metered) +// node scripts/skill-eval.mjs --keep # keep temp dirs for inspection +// +// Local / opt-in only: needs an authenticated `claude` CLI and spends tokens. +// Not a CI gate. + +import { mkdtempSync, mkdirSync, writeFileSync, cpSync, rmSync, readFileSync, existsSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname, resolve } from "node:path"; +import { spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const ROOT = resolve(HERE, ".."); +const SKILLS_DIR = join(ROOT, "plugins", "aidd-refine", "skills"); +const CASES = JSON.parse(readFileSync(join(HERE, "skill-eval", "cases.json"), "utf8")); + +const args = process.argv.slice(2); +const JUDGE = args.includes("--judge"); +const KEEP = args.includes("--keep"); +const filter = args.find((a) => !a.startsWith("--")); +const cases = CASES.filter((c) => !filter || c.skill === filter); + +if (cases.length === 0) { + console.error(`No cases match ${filter ? `"${filter}"` : "(any)"}.`); + process.exit(2); +} + +function runClaude(prompt, cwd) { + const res = spawnSync( + "claude", + // --setting-sources project,local isolates the run from the user's global + // settings (hooks, output modes) so results are reproducible across machines. + ["-p", prompt, "--setting-sources", "project,local", "--add-dir", cwd, "--dangerously-skip-permissions"], + { cwd, input: "", encoding: "utf8", timeout: 600000, maxBuffer: 10 * 1024 * 1024 }, + ); + if (res.error) throw res.error; + return (res.stdout || "") + (res.stderr || ""); +} + +function has(haystack, needle) { + return haystack.toLowerCase().includes(String(needle).toLowerCase()); +} + +// One assertion = { ok: boolean, label: string } +function evaluate(expect, ctx) { + const checks = []; + const fileText = (name) => (existsSync(join(ctx.tmp, name)) ? readFileSync(join(ctx.tmp, name), "utf8") : null); + + for (const name of expect.filesExist || []) { + checks.push({ ok: existsSync(join(ctx.tmp, name)), label: `file exists: ${name}` }); + } + for (const [name, subs] of Object.entries(expect.fileContains || {})) { + const text = fileText(name); + for (const s of subs) checks.push({ ok: text != null && has(text, s), label: `${name} contains "${s}"` }); + } + for (const [name, subs] of Object.entries(expect.fileNotContains || {})) { + const text = fileText(name); + for (const s of subs) checks.push({ ok: text != null && !has(text, s), label: `${name} omits "${s}"` }); + } + for (const s of expect.stdoutContains || []) { + checks.push({ ok: has(ctx.stdout, s), label: `stdout contains "${s}"` }); + } + for (const s of expect.stdoutNotContains || []) { + checks.push({ ok: !has(ctx.stdout, s), label: `stdout omits "${s}"` }); + } + for (const re of expect.stdoutMatches || []) { + checks.push({ ok: new RegExp(re, "i").test(ctx.stdout), label: `stdout matches /${re}/` }); + } + + if (expect.judge) { + if (!JUDGE) { + checks.push({ ok: true, skipped: true, label: `judge (skipped, pass --judge): ${expect.judge}` }); + } else { + const evidence = [ctx.stdout, ...(expect.judgeFiles || []).map((n) => fileText(n) || "")].join("\n\n"); + const verdict = runClaude( + `You grade a test. Criterion: "${expect.judge}". Output under test follows between <<< and >>>.\n` + + `Reply with exactly PASS or FAIL on the first line, then one line of reason.\n<<<\n${evidence}\n>>>`, + ctx.tmp, + ); + checks.push({ ok: /^\s*pass\b/i.test(verdict), label: `judge: ${expect.judge}`, note: verdict.split("\n")[0].trim() }); + } + } + return checks; +} + +function setupCase(c) { + const tmp = mkdtempSync(join(tmpdir(), "skilleval-")); + const skillDst = join(tmp, ".claude", "skills", c.evalName); + mkdirSync(skillDst, { recursive: true }); + cpSync(join(SKILLS_DIR, c.skill), skillDst, { recursive: true }); + // Rewrite the frontmatter name so it matches the unique eval folder. + const skillMd = join(skillDst, "SKILL.md"); + const rewritten = readFileSync(skillMd, "utf8").replace(/^name:.*$/m, `name: ${c.evalName}`); + writeFileSync(skillMd, rewritten); + for (const [rel, content] of Object.entries(c.setup?.files || {})) { + const dst = join(tmp, rel); + mkdirSync(dirname(dst), { recursive: true }); + writeFileSync(dst, content); + } + return tmp; +} + +console.log(`Running ${cases.length} case(s)${JUDGE ? " with --judge" : ""}.\n`); +let failed = 0; +for (const c of cases) { + const tmp = setupCase(c); + let checks; + try { + const prompt = c.prompt.replaceAll("{{SKILL}}", c.evalName); + const stdout = runClaude(prompt, tmp); + checks = evaluate(c.expect, { tmp, stdout }); + } catch (err) { + checks = [{ ok: false, label: `run error: ${err.message}` }]; + } + const caseFailed = checks.some((k) => !k.ok); + if (caseFailed) failed++; + console.log(`${caseFailed ? "FAIL" : "PASS"} ${c.skill} :: ${c.name}`); + for (const k of checks) { + const mark = k.skipped ? "~" : k.ok ? "✓" : "✗"; + console.log(` ${mark} ${k.label}${k.note ? ` (${k.note})` : ""}`); + } + if (KEEP) console.log(` tmp: ${tmp}`); + else rmSync(tmp, { recursive: true, force: true }); + console.log(""); +} + +console.log(`${cases.length - failed}/${cases.length} cases passed.`); +process.exit(failed ? 1 : 0); diff --git a/scripts/skill-eval/README.md b/scripts/skill-eval/README.md new file mode 100644 index 00000000..663cda8e --- /dev/null +++ b/scripts/skill-eval/README.md @@ -0,0 +1,78 @@ +# skill-eval + +Behavioral eval harness for the `aidd-refine` skills. Runs each skill for real +through a headless `claude -p` and asserts the outcomes its action `## Test` +blocks describe. + +## Run + +```bash +node scripts/skill-eval.mjs # every case, deterministic checks +node scripts/skill-eval.mjs 04-shadow-areas # one skill +node scripts/skill-eval.mjs --judge # also run LLM-judge criteria (metered) +node scripts/skill-eval.mjs --keep # keep temp dirs to inspect +``` + +Local and opt-in. Needs an authenticated `claude` CLI and spends tokens, so it +is not a CI gate. + +## How it works + +Each case runs in a throwaway temp project. The skill under test is copied into +`.claude/skills/<evalName>/` and its frontmatter `name` is rewritten to a unique +`xeval-*` value. The unique name guarantees the worktree copy runs, never a +globally-installed plugin of the same name. The harness writes the case setup +files, runs `claude -p` in that project, then checks the written files and the +output. + +## Cases + +`cases.json` holds the cases. Each one: + +```json +{ + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "short description", + "setup": { "files": { "prd.md": "..." } }, + "prompt": "Use the {{SKILL}} skill on ./prd.md ...", + "expect": { + "filesExist": ["prd-shadow-report.md"], + "fileContains": { "prd-shadow-report.md": ["## Gaps by Category"] }, + "fileNotContains": { "report.md": ["..."] }, + "stdoutContains": ["..."], + "stdoutNotContains": ["tier 1"], + "stdoutMatches": ["\\d+%"], + "judge": "natural-language criterion, only checked under --judge", + "judgeFiles": ["prd-shadow-report.md"] + } +} +``` + +`{{SKILL}}` is replaced with the case `evalName`. Deterministic checks run +always; `judge` criteria run only with `--judge` and use a second `claude -p` +as grader, for outcomes that cannot be matched literally. + +## Coverage and limits + +- Deterministic where possible (file written, filename rule, required sections, + hedged unverified claim, forbidden mechanics absent). Fuzzy outcomes + (claim-extraction quality, terseness) go to `--judge` and can flake. +- `01-brainstorm` is interactive (multi-turn Q&A) and is not covered here; a + single headless turn cannot exercise its loop. + +## Known findings + +The harness surfaced two limitations worth tracking: + +- **condense's `Condense: ON (<level>).` line is model-emitted, not guaranteed.** + `02-stats` and the `condense-stats.js` hook parse that exact line from the + transcript, but the model paraphrases it ("Condense mode on, level full") + even when the action mandates the literal. So the condense case gates on + semantics (mentions condense + the level), not the literal, and stats + detection is best-effort. A robust fix would emit the marker from the hook + rather than rely on model output. +- **empty-source scanning varies.** Most runs produce exactly one blocker, but + the exact count/header drifts between runs. The case asserts deterministically + only that a report is written, and gates the "exactly one blocker" semantics + behind `--judge`. diff --git a/scripts/skill-eval/cases.json b/scripts/skill-eval/cases.json new file mode 100644 index 00000000..ad8bd4b8 --- /dev/null +++ b/scripts/skill-eval/cases.json @@ -0,0 +1,69 @@ +[ + { + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "scans a PRD and writes a structured report", + "setup": { + "files": { + "prd.md": "# Checkout PRD\n\nUsers can buy items. The system must respond quickly when the cart is submitted.\nOn submit, the order is created and a confirmation is shown.\n" + } + }, + "prompt": "Use the {{SKILL}} skill on ./prd.md to find blind spots and write the shadow report file next to it.", + "expect": { + "filesExist": ["prd-shadow-report.md"], + "fileContains": { "prd-shadow-report.md": ["# Shadow Areas Report", "## Gaps by Category", "Total gaps:", "[blocker]"] } + } + }, + { + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "filename rule keeps a dotless name (Makefile)", + "setup": { "files": { "Makefile": "build:\n\techo hi\n" } }, + "prompt": "Use the {{SKILL}} skill on ./Makefile to find blind spots and write the shadow report next to it.", + "expect": { "filesExist": ["Makefile-shadow-report.md"] } + }, + { + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "empty source yields a single blocker", + "setup": { "files": { "empty.md": "" } }, + "prompt": "Use the {{SKILL}} skill on ./empty.md to find blind spots and write the shadow report next to it.", + "expect": { + "filesExist": ["empty-shadow-report.md"], + "judge": "The report flags exactly one blocker gap, asking what content the (empty) artifact should contain.", + "judgeFiles": ["empty-shadow-report.md"] + } + }, + { + "skill": "05-fact-check", + "evalName": "xeval-factcheck", + "name": "verifies a real file, refutes a fake one, hedges the unknowable, hides mechanics", + "setup": { "files": { "src/auth.ts": "export const auth = true;\n" } }, + "prompt": "Use the {{SKILL}} skill to fact-check this text and rewrite it with citations: \"The file src/auth.ts exists in this repo. The file src/ghost9000.ts exists in this repo. The lead maintainer of this project owns exactly 47 cats.\"", + "expect": { + "stdoutContains": ["## Sources", "(unverified - no source found)"], + "stdoutNotContains": ["tier 1", "tier 2", "tier 3", "Cascade", "codebase inspection"], + "judge": "src/auth.ts is confirmed with a citation; the src/ghost9000.ts claim is corrected as not present (never restated as true); the 47-cats claim is marked unverified; no shell commands or inspection methods appear.", + "judgeFiles": [] + } + }, + { + "skill": "03-condense", + "evalName": "xeval-condense", + "name": "turning on confirms condense at the full level", + "prompt": "Use the {{SKILL}} skill to turn condense mode on, set to the full level (not lite, not ultra).", + "expect": { + "stdoutContains": ["condense", "full"] + } + }, + { + "skill": "02-challenge", + "evalName": "xeval-challenge", + "name": "flags a plan violation as a deal breaker with low confidence", + "prompt": "Use the {{SKILL}} skill. Agreed plan: the function must RETURN THE SUM of a and b. Work to review: function add(a, b) { return a - b }. Challenge the work against the plan and emit the report.", + "expect": { + "stdoutContains": ["confidence", "Deal breakers"], + "judge": "A confidence percentage below 75% is stated, and the subtraction (returning a - b instead of a + b) is listed as a deal breaker." + } + } +] diff --git a/scripts/summarize-markdown.js b/scripts/summarize-markdown.js index e3aa25c9..a589e12b 100755 --- a/scripts/summarize-markdown.js +++ b/scripts/summarize-markdown.js @@ -69,6 +69,8 @@ for (const arg of process.argv) { const fs = require("node:fs"); const path = require("node:path"); +const NON_TABLE_FRONTMATTER_KEYS = new Set(["argument-hint"]); + function parseFrontmatter(content) { const lines = content.split("\n"); @@ -242,6 +244,11 @@ function truncateText(text, maxLength = 50) { return `${text.substring(0, maxLength - 3)}...`; } +function formatFrontmatterValue(value) { + if (!value || value === "N/A") return "-"; + return `\`${value}\``; +} + /** * Group files by their first path component (subfolder) * @param {Array} files - Array of file objects @@ -326,7 +333,7 @@ function generateTable(files, outputFile) { } parsedFiles.push({ file, frontmatter }); for (const key of Object.keys(frontmatter)) { - if (key !== "name") allKeys.add(key); + if (key !== "name" && !NON_TABLE_FRONTMATTER_KEYS.has(key)) allKeys.add(key); } } catch (error) { console.warn( @@ -354,7 +361,7 @@ function generateTable(files, outputFile) { const fileLink = `[${template}](${relativePath})`; const values = extraColumns.map((key) => { const val = frontmatter[key]; - return val && val !== "N/A" ? `\`${val}\`` : "-"; + return formatFrontmatterValue(val); }); rows.push({ group, fileLink, values }); } diff --git a/scripts/sync-skill-argument-hints.mjs b/scripts/sync-skill-argument-hints.mjs new file mode 100755 index 00000000..d4b31bf6 --- /dev/null +++ b/scripts/sync-skill-argument-hints.mjs @@ -0,0 +1,119 @@ +#!/usr/bin/env node +// Keeps SKILL.md frontmatter argument-hint values in sync with action file names. +// Omits the field when a skill has zero or one action. +// Usage: +// node scripts/sync-skill-argument-hints.mjs # rewrite stale files +// node scripts/sync-skill-argument-hints.mjs --check # exit 1 if stale + +import { readdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; + +const ROOT = process.cwd(); +const PLUGINS_DIR = path.join(ROOT, "plugins"); +const CHECK = process.argv.includes("--check"); + +function actionName(file) { + return path.basename(file, path.extname(file)).replace(/^\d+-/, ""); +} + +async function existsDir(dir) { + try { + const entries = await readdir(dir, { withFileTypes: true }); + return entries; + } catch (error) { + if (error.code === "ENOENT") return null; + throw error; + } +} + +async function collectMarkdownFiles(dir) { + const entries = await existsDir(dir); + if (!entries) return []; + + const files = []; + for (const entry of entries) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + files.push(...(await collectMarkdownFiles(full))); + } else if (entry.isFile() && entry.name.endsWith(".md")) { + files.push(full); + } + } + return files.sort((a, b) => a.localeCompare(b)); +} + +async function skillDirs() { + const plugins = await existsDir(PLUGINS_DIR); + if (!plugins) return []; + + const dirs = []; + for (const plugin of plugins) { + if (!plugin.isDirectory()) continue; + const skillsDir = path.join(PLUGINS_DIR, plugin.name, "skills"); + const skills = await existsDir(skillsDir); + if (!skills) continue; + for (const skill of skills) { + if (skill.isDirectory()) dirs.push(path.join(skillsDir, skill.name)); + } + } + return dirs.sort((a, b) => a.localeCompare(b)); +} + +function splitFrontmatter(content) { + if (!content.startsWith("---\n")) return null; + const end = content.indexOf("\n---", 4); + if (end === -1) return null; + return { + frontmatter: content.slice(4, end), + body: content.slice(end), + }; +} + +function syncArgumentHint(content, hint) { + const parts = splitFrontmatter(content); + if (!parts) return content; + + const lines = parts.frontmatter.split("\n"); + const index = lines.findIndex((value) => value.startsWith("argument-hint:")); + if (!hint) { + if (index !== -1) lines.splice(index, 1); + return `---\n${lines.join("\n")}${parts.body}`; + } + + const line = `argument-hint: ${hint}`; + if (index === -1) { + const descriptionIndex = lines.findIndex((value) => value.startsWith("description:")); + const insertAt = descriptionIndex === -1 ? lines.length : descriptionIndex + 1; + lines.splice(insertAt, 0, line); + } else { + lines[index] = line; + } + + return `---\n${lines.join("\n")}${parts.body}`; +} + +const stale = []; +for (const dir of await skillDirs()) { + const skillPath = path.join(dir, "SKILL.md"); + const actionFiles = await collectMarkdownFiles(path.join(dir, "actions")); + const names = [...new Set(actionFiles.map(actionName))]; + const hint = names.length > 1 ? names.join(" | ") : null; + const before = await readFile(skillPath, "utf8"); + const after = syncArgumentHint(before, hint); + if (after !== before) { + const relative = path.relative(ROOT, skillPath); + stale.push(relative); + if (!CHECK) await writeFile(skillPath, after); + } +} + +if (stale.length > 0) { + if (CHECK) { + console.error(`Stale argument-hint frontmatter:\n${stale.join("\n")}`); + console.error("Run: node scripts/sync-skill-argument-hints.mjs"); + process.exit(1); + } + console.log(`Synced argument-hint frontmatter in ${stale.length} SKILL.md file(s).`); +} else { + console.log("All skill argument-hint frontmatter values are current."); +} diff --git a/scripts/validate-yaml.mjs b/scripts/validate-yaml.mjs index e667e2f3..043bcc4a 100755 --- a/scripts/validate-yaml.mjs +++ b/scripts/validate-yaml.mjs @@ -2,14 +2,14 @@ // Validates YAML syntax using the repository's Node dependency, avoiding Python in hooks. import { readFile } from "node:fs/promises"; -import yaml from "js-yaml"; +import { load } from "js-yaml"; const files = process.argv.slice(2).filter((file) => file !== "--"); const errors = []; for (const file of files) { try { - yaml.load(await readFile(file, "utf8"), { filename: file }); + load(await readFile(file, "utf8"), { filename: file }); } catch (error) { errors.push(`${file}: ${error.message}`); }