diff --git a/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-1.md b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-1.md new file mode 100644 index 00000000..7400c489 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-1.md @@ -0,0 +1,76 @@ +--- +status: done +--- + +# Instruction: Convert Existing Skill READMEs + +Part of [`plan.md`](./plan.md). + +## Architecture projection + +```txt +plugins/ + aidd-*/ + README.md + skills/ + / + README.md -> SKILL.md + SKILL.md + actions/ + references/ + assets/ + README.md # unchanged when present +``` + +## Tasks to do + +### `1)` Inventory direct skill README files + +> Build the exact direct-skill README target list without accidentally including nested asset/template READMEs. + +1. Use a filesystem-depth scan for `plugins//skills//README.md`. +2. Confirm each owning `plugins//README.md` exists. +3. Record any direct skill README that is already a symlink and preserve it if it resolves correctly. + +### `2)` Replace direct README files with symlinks + +> Convert every direct skill README landing page into the local SKILL.md symlink convention. + +1. For every direct regular file at `plugins//skills//README.md`, remove the file and create a symlink named `README.md` targeting `SKILL.md`. +2. Do not touch deeper README files under `assets/`, `references/`, templates, or generated-project templates. +3. Ensure Git records the symlink mode change rather than a copied README file. + +### `3)` Refresh generated catalogs if required + +> Bring catalog output into sync with the converted tree. + +1. Run the plugin catalog generation command used by `lefthook`. +2. Review catalog diffs for expected changes only. +3. If catalogs still list direct skill README entries as ordinary files, leave that for Phase 3 validation/catalog handling. + +## Acceptance criteria + +| Task | Acceptance criteria | +| --- | --- | +| 1 | The direct target list includes only paths exactly shaped as `plugins//skills//README.md`; nested asset/template READMEs are excluded. | +| 2 | Each direct skill `README.md` is a symlink whose `readlink` target is `SKILL.md`, and `realpath` resolves to the local `SKILL.md`. | +| 2 | `git status --short` shows mode/content changes for direct skill README paths only, with no accidental deletion of nested asset README files. | +| 3 | Regenerated catalogs are either unchanged or changed only in ways explained by symlink handling. | + +## Validation commands + +```sh +find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -print | sort +find plugins -mindepth 5 -path 'plugins/*/skills/*/README.md' -print | sort +while IFS= read -r f; do expected="$(cd "$(dirname "$f")" && pwd -P)/SKILL.md"; test -L "$f" || { echo "not symlink: $f"; exit 1; }; target="$(readlink "$f")"; test "$target" = "SKILL.md" || { echo "bad target: $f -> $target"; exit 1; }; actual="$(cd "$(dirname "$f")" && realpath "$target")"; test "$actual" = "$expected" || { echo "bad resolution: $f -> $actual, expected $expected"; exit 1; }; done < <(find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -print | sort) +find plugins -mindepth 5 -path 'plugins/*/skills/*/README.md' -type f -print | sort +for plugin in plugins/*/; do name=$(basename "$plugin"); node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" --depth=4 --fields=description,argument-hint --title="$name catalog" --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." >/dev/null; done +``` + +## Dependencies + +- None. + +## Expected commit boundary + +Commit after every direct per-skill README has been converted to a symlink and any immediately required catalog refresh is complete. diff --git a/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-2.md b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-2.md new file mode 100644 index 00000000..0bfc3952 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-2.md @@ -0,0 +1,80 @@ +--- +status: done +--- + +# Instruction: Update Generation And Documentation Assumptions + +Part of [`plan.md`](./plan.md). + +## Architecture projection + +```txt +plugins/aidd-context/skills/04-skill-generate/ + SKILL.md + actions/ + 01-capture-intent.md + 03-draft-skill.md + 05-validate.md + references/ + skill-authoring.md + tool-paths.md + assets/ + skill-template.md + +plugins//skills// + README.md -> SKILL.md # plugin-source mode only + SKILL.md + actions/ +``` + +## Tasks to do + +### `1)` Update skill-generation write behavior + +> Make plugin-source skill generation create or preserve the symlink convention without writing substantive per-skill README prose. + +1. Update `plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md` so plugin-source rendering writes `SKILL.md` and ensures `README.md -> SKILL.md`. +2. Keep host-project skill generation focused on the target tool's `SKILL.md`; do not require a README. +3. In modify mode, preserve a correct symlink, replace only a direct regular per-skill README in plugin-source mode, and avoid touching nested README templates. + +### `2)` Update capture, authoring, and seed guidance + +> Remove stale assumptions that a new skill needs dedicated README prose. + +1. Update skill-generate capture/reference wording if it asks for or implies substantive per-skill README content. +2. Add seed guidance in `03-draft-skill.md` or the relevant reference so new plugin-source skills create `README.md` as a symlink to `SKILL.md` immediately after `SKILL.md` is written. +3. Keep asset README references in unrelated skills intact when they describe generated project docs or templates. + +### `3)` Update plugin/docs references that describe per-skill READMEs as content surfaces + +> Align documentation with `SKILL.md` as the canonical skill file. + +1. Search `plugins/`, `scripts/`, `aidd_docs/`, and root docs for wording like `skill README`, `per-skill README`, or links that imply unique per-skill content. +2. Rewrite stale prose to reference `SKILL.md`, catalog entries, or the symlink convention. +3. Leave historical changelog entries unchanged unless they are part of generated current docs. + +## Acceptance criteria + +| Task | Acceptance criteria | +| --- | --- | +| 1 | Plugin-source skill generation instructions explicitly ensure `README.md -> SKILL.md` and do not ask the user for README prose. | +| 1 | Host-project skill generation instructions do not create or require README files. | +| 2 | Creation guidance explicitly seeds the plugin-source skill README symlink before the action reports files written. | +| 2 | References to asset README templates remain intact where they are not direct skill landing pages. | +| 3 | Current docs no longer claim direct skill READMEs contain distinct per-skill documentation. | + +## Validation commands + +```sh +rg -n "skill README|per-skill README|substantive per-skill|skills/.*/README.md" plugins scripts aidd_docs README.md -g '!**/CHANGELOG.md' +rg -n "README" plugins/aidd-context/skills/04-skill-generate +pnpm exec lefthook run pre-commit --all-files --force +``` + +## Dependencies + +- Phase 1 should be complete so docs/generator updates can refer to the actual symlink convention. + +## Expected commit boundary + +Commit after skill generation instructions and current docs consistently describe the symlink convention. diff --git a/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-3.md b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-3.md new file mode 100644 index 00000000..0a67bb32 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-3.md @@ -0,0 +1,82 @@ +--- +status: done +--- + +# Instruction: Validate Catalogs, Distribution, And Checks + +Part of [`plan.md`](./plan.md). + +## Architecture projection + +```txt +scripts/ + summarize-markdown.js # may need symlink-aware catalog behavior + validate-*.mjs +.github/workflows/ + validate.yml # runs lefthook over all files +plugins/ + / + CATALOG.md # generated, deterministic + README.md + skills//README.md -> SKILL.md +``` + +## Tasks to do + +### `1)` Make cataloging symlink-aware where needed + +> Ensure generated catalogs and docs do not misrepresent symlinked skill READMEs as unique source files. + +1. Run catalog generation for every plugin and inspect how direct skill README symlinks appear. +2. If catalog rows are misleading or duplicate `SKILL.md` metadata through the symlink, update `scripts/summarize-markdown.js` to handle symlinked direct skill READMEs deliberately. +3. Preserve catalog coverage for nested asset/template README files, because those remain substantive files. + +### `2)` Confirm generator seeding is the durable guardrail + +> Ensure new plugin-source skills seed the README symlink at creation instead of relying on a repository-wide validator. + +1. Keep `lefthook.yml` free of a dedicated skill README symlink validator. +2. Confirm `04-skill-generate` seeds `README.md -> SKILL.md` in plugin-source creation mode. +3. Confirm modify mode preserves a correct symlink and does not touch nested asset/template README files. + +### `3)` Validate repository and build-relevant surfaces + +> Prove the change works with the repository's available checks and release packaging assumptions. + +1. Run the same local check path CI uses. +2. Run a one-off symlink assertion across all direct skill README paths for this migration. +3. If practical in the environment, smoke-test the framework build command used by release packaging for at least one target; otherwise record why it was skipped. +4. Review `git diff --stat` and `git diff --check`. + +## Acceptance criteria + +| Task | Acceptance criteria | +| --- | --- | +| 1 | `plugins/*/CATALOG.md` files are deterministic after regeneration and do not depend on stale per-skill README contents. | +| 1 | Nested asset/template README entries still appear when catalog rules include them. | +| 2 | `04-skill-generate` creation guidance seeds `README.md -> SKILL.md` at creation time. | +| 2 | No dedicated repository validator script or lefthook command is committed for this convention. | +| 3 | `pnpm exec lefthook run pre-commit --all-files --force` passes. | +| 3 | One-off symlink assertion passes for every direct skill README in this migration. | +| 3 | `git diff --check` passes, and any skipped build smoke test is justified in the implementation notes. | + +## Validation commands + +```sh +pnpm exec lefthook run pre-commit --all-files --force +while IFS= read -r f; do expected="$(cd "$(dirname "$f")" && pwd -P)/SKILL.md"; test -L "$f" || { echo "not symlink: $f"; exit 1; }; target="$(readlink "$f")"; test "$target" = "SKILL.md" || { echo "bad target: $f -> $target"; exit 1; }; actual="$(cd "$(dirname "$f")" && realpath "$target")"; test "$actual" = "$expected" || { echo "bad resolution: $f -> $actual, expected $expected"; exit 1; }; done < <(find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -print | sort) +find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -type f -print | grep . && { echo "regular direct skill README remains"; exit 1; } || true +find plugins -mindepth 5 -path 'plugins/*/skills/*/README.md' -type f -print | sort +git diff --check +git diff --stat +npx --yes @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out "$(mktemp -d)" --flat +``` + +## Dependencies + +- Phase 1 must provide the symlinked tree. +- Phase 2 must update generation/docs assumptions before final validation. + +## Expected commit boundary + +Commit after validation/catalog handling is complete and all checks have been run or explicitly documented as skipped. diff --git a/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/plan.md b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/plan.md new file mode 100644 index 00000000..57269219 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/plan.md @@ -0,0 +1,77 @@ +--- +objective: "Remove substantive per-skill README files and standardize direct skill README.md entries as symlinks to SKILL.md." +status: reviewed +--- + +# Plan: Remove Skill READMEs + +## Overview + +| Field | Value | +| --- | --- | +| **Goal** | Direct skill directories keep `README.md` only as a symlink to local `SKILL.md`, and generators/catalogs/docs stop treating per-skill READMEs as substantive files. | +| **Source** | Inline SDLC request from 2026-06-26. | + +## Scope + +Target: + +- Replace committed files matching direct skill README paths (`plugins//skills//README.md`) with symlinks resolving to the same directory's `SKILL.md`. +- Update skill generation behavior so plugin-source skill creation creates or preserves the symlink convention without asking for or writing substantive per-skill README content. +- Update cataloging and docs that assume direct skill READMEs contain unique content. +- Validate with repository checks plus a one-off migration assertion for the current symlink tree. + +Hard constraints: + +- Do not edit nested asset/template READMEs such as `plugins/*/skills/*/assets/README.md`; those are not direct per-skill README landing pages. +- Use a local symlink target of `SKILL.md` for every direct skill README so plugin directories remain relocatable. +- Keep generated catalogs deterministic and compatible with `pnpm exec lefthook run pre-commit`. + +Non-goals: + +- Do not remove or rewrite plugin-level `plugins/*/README.md` files except link/reference updates required by the symlink convention. +- Do not remove asset README templates used by skills to generate project docs. +- Do not change skill runtime semantics unrelated to README generation and discovery. + +Done when: + +- Every direct skill README in committed plugin skill directories is a symlink resolving to the same directory's `SKILL.md`. +- No direct committed skill README remains a regular file. +- Skill generation no longer asks for or writes standalone per-skill README prose, and plugin-source generation seeds the symlink at creation time. +- Catalogs/docs reflect the symlink convention and no stale per-skill README assumption remains. +- Repository checks pass. + +## Phases + +| # | Phase | File | +| --- | --- | --- | +| 1 | Convert Existing Skill READMEs | [`phase-1.md`](./phase-1.md) | +| 2 | Update Generation And Documentation Assumptions | [`phase-2.md`](./phase-2.md) | +| 3 | Validate Catalogs, Distribution, And Checks | [`phase-3.md`](./phase-3.md) | + +## Resources + +| Source | Verified | +| --- | --- | +| `plugins/*/skills/*/README.md` direct filesystem scan | There were 37 direct skill README regular files to convert and one direct skill directory missing the symlink. | +| `plugins/*/skills/*/assets/**/README.md` scan | Nested asset/template READMEs exist and are outside the conversion scope. | +| `plugins/aidd-context/skills/04-skill-generate/**` | Skill generation writes `SKILL.md` and actions; plugin-source behavior needs explicit README symlink handling and docs. | +| `scripts/summarize-markdown.js` | Catalog generation currently scans symlink targets via `fs.statSync`; cataloging must account for the symlink convention. | +| `.github/workflows/validate.yml` | CI runs `pnpm exec lefthook run pre-commit --all-files --force` after install. | + +## Decisions + +| Decision | Why | +| --- | --- | +| Use `SKILL.md` as the symlink target for direct skill READMEs. | The README alias stays local to the skill directory and follows the canonical skill file. | +| Keep nested asset/template READMEs as regular files. | They are templates or documentation for generated assets, not per-skill landing pages. | +| Keep plugin README skill-table links pointing at `skills//README.md` unless implementation discovers a tool incompatibility. | The path remains valid through the local `SKILL.md` symlink while preserving existing public link shape. | +| Do not add a dedicated repository validator. | The durable guarantee belongs in skill generation seeding; repository checks should stay focused on existing JSON, YAML, frontmatter, catalogs, and counts. | + +## Expected Commit Boundaries + +| Commit | Contents | +| --- | --- | +| 1 | Convert existing direct skill README files to symlinks and update generated catalogs if needed. | +| 2 | Update skill generation instructions/templates and any stale docs or catalog assumptions. | +| 3 | Adjust catalog handling for the symlink convention and refresh generated outputs after checks. | diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bbdeb4bd..a2dc8fae 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -63,7 +63,7 @@ plugins// ├── skills/ # router-based skills │ └── -/ │ ├── SKILL.md # contract (name, description, actions table) -│ ├── README.md # human-facing skill landing +│ ├── README.md # symlink to SKILL.md │ ├── actions/ # atomic actions invoked by the router │ ├── assets/ # templates and static files │ └── references/ # extended docs the skill links into diff --git a/docs/CREATE_PLUGIN.md b/docs/CREATE_PLUGIN.md index dce4d5b6..e64e7e32 100644 --- a/docs/CREATE_PLUGIN.md +++ b/docs/CREATE_PLUGIN.md @@ -41,7 +41,7 @@ plugins/aidd-example/ ├── skills/ │ └── 01-hello/ │ ├── SKILL.md -│ ├── README.md +│ ├── README.md -> SKILL.md │ └── actions/ │ └── 01-greet.md ├── agents/ # optional @@ -97,7 +97,13 @@ Run action `01-greet` and return its message. ### `skills/01-hello/README.md` -Mirror the sibling pattern: title, paragraph, When to use, When NOT to use, How to invoke, Outputs, Prerequisites, Technical details (link to SKILL.md). ~30-50 lines. +Create this as a local symlink to the skill file: + +```sh +ln -s SKILL.md plugins/aidd-example/skills/01-hello/README.md +``` + +Do not write standalone per-skill README prose. Keep execution details in `SKILL.md`, `actions/`, `references/`, and `assets/`. ### `skills/01-hello/actions/01-greet.md` @@ -166,7 +172,7 @@ Once the PR merges to `main`, `release-please` will propose a release PR for you - English only in committed prose. - No em-dash characters in text (hyphen instead). -- No cross-plugin references in skill descriptions or READMEs. +- No cross-plugin references in skill descriptions or plugin README prose. - One sentence per `Use when ... / Do NOT use for ...` cue in `description` frontmatter. - A skill's `name:` is the **folder slug** (`01-hello`), not a prefixed id. The **invocation** token is `:` with a single colon, e.g. `aidd-example:01-hello`. diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 3ce4b47f..db1ee9bf 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -47,7 +47,6 @@ 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) | - | -| `-` | [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).` | @@ -62,7 +61,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-write-install-md.md](skills/01-bootstrap/actions/05-write-install-md.md) | - | | `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | | `assets` | [install-template.md](skills/01-bootstrap/assets/install-template.md) | - | -| `-` | [README.md](skills/01-bootstrap/README.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | | `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `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).` | @@ -79,7 +77,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [CONTRIBUTING.md](skills/02-project-memory/assets/CONTRIBUTING.md) | - | | `assets` | [GUIDELINES.md](skills/02-project-memory/assets/GUIDELINES.md) | - | | `assets` | [README.md](skills/02-project-memory/assets/README.md) | - | -| `-` | [README.md](skills/02-project-memory/README.md) | - | | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - | | `references` | [mapping-ai-context-file.md](skills/02-project-memory/references/mapping-ai-context-file.md) | - | | `-` | [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).` | @@ -88,7 +85,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [README.md](skills/03-context-generate/README.md) | - | | [SKILL.md](skills/03-context-generate/SKILL.md) | `Route a request to generate a context artifact (skill, rule, agent, command, or hook) to its 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).` | #### `skills/04-skill-generate` @@ -102,7 +98,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-validate.md](skills/04-skill-generate/actions/05-validate.md) | - | | `assets` | [action-template.md](skills/04-skill-generate/assets/action-template.md) | - | | `assets` | [skill-template.md](skills/04-skill-generate/assets/skill-template.md) | `. Use when . , use " only when a sibling skill could mis-trigger.> (<= 1024 chars, third person, no XML tags; all "when" lives here, not in the body.)` | -| `-` | [README.md](skills/04-skill-generate/README.md) | - | | `references` | [skill-authoring.md](skills/04-skill-generate/references/skill-authoring.md) | - | | `references` | [tool-paths.md](skills/04-skill-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/04-skill-generate/SKILL.md) | `Generate a router-based skill across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a skill, or turn a workflow into one. Not for other artifacts like rules, agents, commands, hooks.` | @@ -115,7 +110,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write-rule.md](skills/05-rule-generate/actions/02-write-rule.md) | - | | `actions` | [03-validate.md](skills/05-rule-generate/actions/03-validate.md) | - | | `assets` | [rule-template.md](skills/05-rule-generate/assets/rule-template.md) | - | -| `-` | [README.md](skills/05-rule-generate/README.md) | - | | `references` | [rule-authoring.md](skills/05-rule-generate/references/rule-authoring.md) | - | | `references` | [tool-paths.md](skills/05-rule-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/05-rule-generate/SKILL.md) | `Generate a coding rule that governs editor and agent behavior, across the host AI tools 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.` | @@ -128,7 +122,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write-agent.md](skills/06-agent-generate/actions/02-write-agent.md) | - | | `actions` | [03-validate.md](skills/06-agent-generate/actions/03-validate.md) | - | | `assets` | [agent-template.md](skills/06-agent-generate/assets/agent-template.md) | ` # required, third person` | -| `-` | [README.md](skills/06-agent-generate/README.md) | - | | `references` | [agent-authoring.md](skills/06-agent-generate/references/agent-authoring.md) | - | | `references` | [tool-paths.md](skills/06-agent-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/06-agent-generate/SKILL.md) | `Generate an agent across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor an agent, subagent or specialized role. Not for other artifacts like skills, rules, commands, hooks.` | @@ -141,7 +134,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-write-command.md](skills/07-command-generate/actions/02-write-command.md) | - | | `actions` | [03-validate.md](skills/07-command-generate/actions/03-validate.md) | - | | `assets` | [command-template.md](skills/07-command-generate/assets/command-template.md) | - | -| `-` | [README.md](skills/07-command-generate/README.md) | - | | `references` | [command-authoring.md](skills/07-command-generate/references/command-authoring.md) | - | | `references` | [tool-paths.md](skills/07-command-generate/references/tool-paths.md) | - | | `-` | [SKILL.md](skills/07-command-generate/SKILL.md) | `Generate a flat slash command across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a one-shot slash command. Not for multi-step skills or other artifacts like rules, agents, hooks.` | @@ -164,7 +156,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-mermaid.md](skills/09-mermaid/actions/01-mermaid.md) | - | -| `-` | [README.md](skills/09-mermaid/README.md) | - | | `references` | [mermaid-conventions.md](skills/09-mermaid/references/mermaid-conventions.md) | - | | `-` | [SKILL.md](skills/09-mermaid/SKILL.md) | `Generate a valid, 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.` | @@ -177,7 +168,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-write.md](skills/10-learn/actions/03-write.md) | - | | `actions` | [04-sync.md](skills/10-learn/actions/04-sync.md) | - | | `assets` | [decision-template.md](skills/10-learn/assets/decision-template.md) | - | -| `-` | [README.md](skills/10-learn/README.md) | - | | `-` | [SKILL.md](skills/10-learn/SKILL.md) | `Capture durable project learnings from the conversation or 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.` | #### `skills/11-explore` @@ -186,7 +176,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-survey.md](skills/11-explore/actions/01-survey.md) | - | | `actions` | [02-drill.md](skills/11-explore/actions/02-drill.md) | - | -| `-` | [README.md](skills/11-explore/README.md) | - | | `references` | [ai-mapping.md](skills/11-explore/references/ai-mapping.md) | - | | `-` | [SKILL.md](skills/11-explore/SKILL.md) | `Explore the current project across its tooling, context, and codebase. Use to survey what is installed 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).` | @@ -197,6 +186,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-list.md](skills/12-cook/actions/01-list.md) | - | | `actions` | [02-upsert.md](skills/12-cook/actions/02-upsert.md) | - | | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - | -| `-` | [README.md](skills/12-cook/README.md) | - | | `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ 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".` | diff --git a/plugins/aidd-context/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md deleted file mode 100644 index 7c68cbff..00000000 --- a/plugins/aidd-context/skills/00-onboard/README.md +++ /dev/null @@ -1,35 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 00 - Onboard - -A plain-language guide to the AIDD framework for the current project. It reads the project lightly, explains where the project sits in the AIDD flow, and suggests the next logical step, using only the plugins that are installed. It teaches as it goes and never assumes you already know the framework. - -## When to use - -- "Where do I start?" / "Onboard me to this project." -- "What should I do next?" -- "How does AIDD work?" -- After a partial setup, to figure out the next move. - -## When not to use - -- To list every installed surface. Use the explore skill in this plugin. -- To run a specific skill you already know you need. Invoke it directly. - -## Flow - -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`. - -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. - -## Requires - -Only the `aidd-context` plugin installed and enabled, and a working directory rooted in the target project. The `aidd_docs/` memory bank is **not** required: on a project without it, onboard's first suggestion is to set it up (the Context step). Onboard is the entry point, so it works before anything else exists. - -## 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. diff --git a/plugins/aidd-context/skills/00-onboard/README.md b/plugins/aidd-context/skills/00-onboard/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/00-onboard/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/01-bootstrap/README.md b/plugins/aidd-context/skills/01-bootstrap/README.md deleted file mode 100644 index 15ae57b0..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/README.md +++ /dev/null @@ -1,59 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 01 - Bootstrap - -Plays the role of technical architect for a new SaaS project. Walks the user -through a 24-item checklist, proposes 2-3 candidate stacks, audits each via -parallel agents, then produces `aidd_docs/INSTALL.md` capturing the technical -vision, decisions, stack, architecture pattern, folder tree, and install -steps. Documentation only - no code, no scaffolding. - -## When to use - -- Starting a brand-new SaaS project and choosing a stack. -- Deciding the architecture pattern (monolith vs microservices vs serverless). -- Producing a project's `INSTALL.md` from a fresh idea. - -## When NOT to use - -- To edit an existing project's stack (the audit is too heavy for one - swap-out). -- For database schema design or detailed data modeling. -- To scaffold actual files - this skill produces docs only. - -## How to invoke - -``` -Use skill aidd-context:01-bootstrap -``` - -The skill walks 5 atomic actions in sequence: - -1. `gather-needs` - Q&A across the 24-item checklist (18 user-input, 6 - derived). -2. `propose-candidates` - derive 2-3 candidate stacks and render a - comparison table. -3. `audit-candidates` - spawn parallel agents to validate each candidate - and emit a verdict; if every candidate fails, loop back to `02` or `01`. -4. `pick-and-design` - user picks the winner, then generate the folder tree - and a Mermaid architecture diagram. -5. `write-install-md` - produce `aidd_docs/INSTALL.md`. - -## Outputs - -- `aidd_docs/INSTALL.md` capturing vision, decisions, chosen stack, - architecture pattern, folder tree, install steps, and a Mermaid diagram. - -## Prerequisites - -- A clear (or at least loosely-formed) product idea to discuss. -- A working directory where `aidd_docs/INSTALL.md` can be written. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) -for each step, `references/stack-heuristics.md` for the input → recommended -stack-family heuristics, and `assets/checklist.md` + `assets/install-template.md` -for the canonical 24-item checklist and `INSTALL.md` skeleton. The Mermaid -architecture diagram in action 04 is rendered via the sibling -`09-mermaid` skill. diff --git a/plugins/aidd-context/skills/01-bootstrap/README.md b/plugins/aidd-context/skills/01-bootstrap/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/02-project-memory/README.md b/plugins/aidd-context/skills/02-project-memory/README.md deleted file mode 100644 index e39929b4..00000000 --- a/plugins/aidd-context/skills/02-project-memory/README.md +++ /dev/null @@ -1,31 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 02 - Project Memory - -Bootstraps the project's context layer: the AI context files with the `` block, the `aidd_docs/` structure, and the memory bank. - -## When to use - -- The first `aidd init` on a repo. -- A new project with no `aidd_docs/` yet. -- A re-run on an existing project to refresh missing memory files. - -## When not to use - -- Updating one memory file after it exists: use `aidd-context:10-learn`. -- Editing a single rule: edit the file directly. -- Generating a new artifact: use `aidd-context:03-context-generate`. - -## Flow - -Five actions, in order: - -1. `init-context-file`: resolve the tools, then upsert the memory block. -2. `scaffold-docs`: create the `aidd_docs/` structure. -3. `generate-memory`: detect the project's capabilities and fill the memory templates. -4. `review-memory`: review the memory files for consistency. -5. `sync-memory`: fill each memory block with references to the generated files. - -## Details - -See [`SKILL.md`](SKILL.md), [`actions/`](actions/), `references/mapping-ai-context-file.md` for the per-tool context-file path, and `assets/templates/memory/` for the memory templates. diff --git a/plugins/aidd-context/skills/02-project-memory/README.md b/plugins/aidd-context/skills/02-project-memory/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/03-context-generate/README.md b/plugins/aidd-context/skills/03-context-generate/README.md deleted file mode 100644 index fa358087..00000000 --- a/plugins/aidd-context/skills/03-context-generate/README.md +++ /dev/null @@ -1,24 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 03 - Context Generate - -A router. It sends a request to generate a context artifact to the dedicated generator for that kind, and holds no generation logic of its own. - -## Routing - -| Artifact | Generator | -| -------- | ---------------------------------- | -| skill | `aidd-context:04-skill-generate` | -| rule | `aidd-context:05-rule-generate` | -| agent | `aidd-context:06-agent-generate` | -| command | `aidd-context:07-command-generate` | -| hook | `aidd-context:08-hook-generate` | - -## When to use - -- The user wants to generate a context artifact but has not said which kind. - -## When not to use - -- A named kind: the dedicated generator triggers directly. -- Surveying or listing existing artifacts: use `aidd-context:11-explore`. diff --git a/plugins/aidd-context/skills/03-context-generate/README.md b/plugins/aidd-context/skills/03-context-generate/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/03-context-generate/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/04-skill-generate/README.md b/plugins/aidd-context/skills/04-skill-generate/README.md deleted file mode 100644 index c53887ad..00000000 --- a/plugins/aidd-context/skills/04-skill-generate/README.md +++ /dev/null @@ -1,21 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 07 - skill-generate - -Build one canonical skill from intent (a SKILL.md router plus chained actions) and render it once per confirmed host tool. This skill is its own reference implementation: it obeys every rule it ships in `references/skill-authoring.md`. - -## When to use - -- The user wants to create, scaffold, or refactor a skill. -- Turn an existing workflow into a router-based skill. -- Not for other artifacts (rules, agents, commands, hooks). - -## Actions - -| # | Action | Purpose | -| --- | ----------------------------------------------------- | --------------------------------------------- | -| 01 | [capture-intent](actions/01-capture-intent.md) | Clarify intent + tools, inventory overlaps. | -| 02 | [decompose-actions](actions/02-decompose-actions.md) | Break the skill into atomic testable actions. | -| 03 | [draft-skill](actions/03-draft-skill.md) | Write the SKILL.md router. | -| 04 | [write-actions](actions/04-write-actions.md) | Write each action file from the template. | -| 05 | [validate](actions/05-validate.md) | Run each action's Test, aggregate pass/fail. | diff --git a/plugins/aidd-context/skills/04-skill-generate/README.md b/plugins/aidd-context/skills/04-skill-generate/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/04-skill-generate/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file 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..39c47d39 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,7 +8,7 @@ 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 confirmed tool, the plugin-source README symlink when applicable, and the list of files written. ## Process @@ -23,8 +23,9 @@ One SKILL.md per confirmed tool, and the list of files written. - Delegates: add "spawn the named agent". - External call or secrets: state it here, leave the wiring to the user. 4. **Render.** Per the write mode: - - **Host**: once per confirmed tool at its path (`@../references/tool-paths.md`). - - **Plugin source**: once at `plugins//skills//`. + - **Host**: once per confirmed tool at its path (`@../references/tool-paths.md`). Do not create or require a README. + - **Plugin source**: once at `plugins//skills//`. On create, seed `README.md` immediately after writing `SKILL.md` as a symlink whose target is exactly `SKILL.md`. + Preserve a correct symlink in modify mode. Replace only a direct regular `README.md` in the skill root. Do not touch nested README files under `assets/`, `references/`, templates, or generated project docs. 5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). ## Test @@ -32,3 +33,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. +- In plugin-source mode, the direct skill `README.md` is a symlink whose target is exactly `SKILL.md`. diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/05-validate.md b/plugins/aidd-context/skills/04-skill-generate/actions/05-validate.md index 5b8f5bb5..50dd1941 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/05-validate.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/05-validate.md @@ -21,9 +21,15 @@ A table for the user, one row per action: name, test, status (pass, fail, or ski Then have it run the process and the test, and report pass or fail with the cause. 2. **Record.** Capture the name, the test, and the status per action. 3. **Fix.** On a fail, fix the cause for real, patch the action on disk, and re-run in a fresh context until it passes. -4. **Report.** Deliver the table, even when all pass. +4. **Symlink.** For plugin-source skills only, verify the direct skill README convention: + - `README.md` in the skill root is a symlink. + - Its target is exactly `SKILL.md`. + - Its resolved path is the skill's own `SKILL.md`. + Host-project skills do not need a README. +5. **Report.** Deliver the table, even when all pass. ## Test - One table covers every action, with name, test, and status. - Each row that passed after a fix has its source modified on disk. +- Plugin-source validation fails if the direct skill `README.md` is a regular file or points anywhere other than `SKILL.md`. diff --git a/plugins/aidd-context/skills/04-skill-generate/references/tool-paths.md b/plugins/aidd-context/skills/04-skill-generate/references/tool-paths.md index 7ea8d624..890c8106 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/tool-paths.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/tool-paths.md @@ -46,8 +46,8 @@ Several signals can be present at once. ## Write targets -- **Host project**: one file per confirmed tool, at the paths above. -- **Plugin source**: one canonical skill at `plugins//skills//SKILL.md`. No per-tool fan-out. Per-tool resolution happens at install. +- **Host project**: one file per confirmed tool, at the paths above. Do not create or require a README. +- **Plugin source**: one canonical skill at `plugins//skills//SKILL.md`, plus `plugins//skills//README.md` seeded at creation as a symlink to `SKILL.md`. No per-tool fan-out. Per-tool resolution happens at install. The mode is chosen in the capture action. Never pick one silently. @@ -55,3 +55,4 @@ The mode is chosen in the capture action. Never pick one silently. - **Asset-access precheck**: before writing, confirm this reference is readable. If not, stop: the plugin is not installed in this host. Do not guess paths. - **Write-target validation**: after writing, confirm every path is relative, under the workspace, never under the plugin install directory, and under the chosen scope. Otherwise stop and report the bad path. +- **Plugin-source README seed check**: after writing a new plugin-source skill, confirm `plugins//skills//README.md` is a symlink, `readlink` returns `SKILL.md`, and the resolved target is the skill's own `SKILL.md`. diff --git a/plugins/aidd-context/skills/05-rule-generate/README.md b/plugins/aidd-context/skills/05-rule-generate/README.md deleted file mode 100644 index a0e3b07f..00000000 --- a/plugins/aidd-context/skills/05-rule-generate/README.md +++ /dev/null @@ -1,19 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 08 - rule-generate - -Write one canonical coding rule from intent and render it once per host AI tool that supports rules. A sibling of `04-skill-generate` for the rule artifact. - -## When to use - -- The user wants to write, add, or refactor a rule, a convention, or a coding standard. -- Scan a codebase and propose rules. -- Not for other artifacts (skills, agents, commands, hooks). - -## Actions - -| # | Action | Purpose | -| --- | ----------------------------------------- | -------------------------------------------- | -| 01 | [capture-rule](actions/01-capture-rule.md) | Capture the topic, pick category and slug. | -| 02 | [write-rule](actions/02-write-rule.md) | Write the rule file per supported tool. | -| 03 | [validate](actions/03-validate.md) | Check each rule file. | diff --git a/plugins/aidd-context/skills/05-rule-generate/README.md b/plugins/aidd-context/skills/05-rule-generate/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/05-rule-generate/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/06-agent-generate/README.md b/plugins/aidd-context/skills/06-agent-generate/README.md deleted file mode 100644 index a26fad72..00000000 --- a/plugins/aidd-context/skills/06-agent-generate/README.md +++ /dev/null @@ -1,18 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 09 - agent-generate - -Write one canonical subagent from intent and render it once per host AI tool, converting to each tool's shape (markdown, or Codex TOML). A sibling of `04-skill-generate` for the agent artifact. - -## When to use - -- The user wants to create, scaffold, or refactor an agent or subagent. -- Not for other artifacts (skills, rules, commands, hooks). - -## Actions - -| # | Action | Purpose | -| --- | -------------------------------------------- | ---------------------------------------------- | -| 01 | [capture-agent](actions/01-capture-agent.md) | Gather the role, propose names, pick the model. | -| 02 | [write-agent](actions/02-write-agent.md) | Render the agent per tool and write. | -| 03 | [validate](actions/03-validate.md) | Check each agent file. | diff --git a/plugins/aidd-context/skills/06-agent-generate/README.md b/plugins/aidd-context/skills/06-agent-generate/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/06-agent-generate/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/07-command-generate/README.md b/plugins/aidd-context/skills/07-command-generate/README.md deleted file mode 100644 index 8fe6196d..00000000 --- a/plugins/aidd-context/skills/07-command-generate/README.md +++ /dev/null @@ -1,18 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-context](../../README.md) - -# 10 - command-generate - -Write one canonical slash command from intent and render it once per host AI tool that supports commands. A sibling of `04-skill-generate` for the command artifact. - -## When to use - -- The user wants to create, scaffold, or refactor a one-shot slash command. -- Not for multi-step skills (use the skill generator) or other artifacts (rules, agents, hooks). - -## Actions - -| # | Action | Purpose | -| --- | ----------------------------------------------- | ------------------------------------------ | -| 01 | [capture-command](actions/01-capture-command.md) | Capture the goal, location, and arguments. | -| 02 | [write-command](actions/02-write-command.md) | Write the command file per supported tool. | -| 03 | [validate](actions/03-validate.md) | Check each command file. | diff --git a/plugins/aidd-context/skills/07-command-generate/README.md b/plugins/aidd-context/skills/07-command-generate/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/07-command-generate/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/08-hook-generate/README.md b/plugins/aidd-context/skills/08-hook-generate/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/08-hook-generate/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/09-mermaid/README.md b/plugins/aidd-context/skills/09-mermaid/README.md deleted file mode 100644 index 237a3503..00000000 --- a/plugins/aidd-context/skills/09-mermaid/README.md +++ /dev/null @@ -1,29 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 09 - Mermaid - -Generates a valid, high-quality Mermaid diagram from a written source through a plan, confirm, generate, review loop. - -## When to use - -- Turning a written description (architecture, lifecycle, flow) into a Mermaid diagram. -- Producing a diagram to embed in an `INSTALL.md`, a decision record, or a memory file. -- When another skill needs a diagram (for example `01-bootstrap` calls it). - -## When not to use - -- For other diagram formats (PlantUML, Graphviz, draw.io). -- To freehand a diagram without a written source to plan from. -- To render or export to an image. This skill produces fenced Mermaid text only. - -## Flow - -One action with a six-step loop: get the source, plan, confirm the plan, generate, offer a review, review on confirm. The diagram is generated only from the confirmed plan, and never adds an element the user did not confirm. - -## Requires - -A written source (a paragraph, a list, or a section) describing what to diagram. - -## Details - -See [`SKILL.md`](SKILL.md) for the contract, [`actions/01-mermaid.md`](actions/01-mermaid.md) for the process, and [`references/mermaid-conventions.md`](references/mermaid-conventions.md) for the conventions and defaults every diagram follows. diff --git a/plugins/aidd-context/skills/09-mermaid/README.md b/plugins/aidd-context/skills/09-mermaid/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/09-mermaid/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/10-learn/README.md b/plugins/aidd-context/skills/10-learn/README.md deleted file mode 100644 index d091b63c..00000000 --- a/plugins/aidd-context/skills/10-learn/README.md +++ /dev/null @@ -1,43 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 10 - Learn - -Distills what a piece of work taught into the project's lasting context. It picks a source, scores each candidate learning, asks the user what to do with each one, writes only the approved lessons, and refreshes the memory block so the next session starts from them. - -## When to use - -- The user states a lasting rule or convention ("from now on", "always", "going forward"). -- A decision is made and worth recording with its rationale. -- Something is deprecated, or a piece of work is worth distilling before moving on. - -## When not to use - -- For personal or AI-preference reminders. Those belong in user memory, not the project. -- For routine edits, minor fixes, or anything already captured. -- To stand up the memory bank itself. Use `aidd-context:02-project-memory`. - -## Requires - -An existing memory bank (`aidd_docs/memory/`). If it is missing, run `aidd-context:02-project-memory` first. - -## Flow - -Four actions, in order: - -1. `gather`: pick a source (the conversation, the git history, or one the user names), collect candidates, drop the noise. -2. `assess`: score each candidate from 0 to 10 with a reason, propose a destination, and ask the user what to do with each. -3. `write`: write the lessons the user approved to their destinations. -4. `sync`: refresh the memory block in every context file. - -## Destinations - -- **Memory**: a fact or convention, into the matching memory file. -- **Decision**: a choice with a rationale, a record in `aidd_docs/memory/internal/decisions/` from `assets/decision-template.md`. -- **Rule**: a convention to enforce, handed to `aidd-context:05-rule-generate`. -- **Skill**: a reusable workflow, handed to `aidd-context:04-skill-generate`. - -The score is the brake (bar 6 of 10), and the user decides every item before anything is written. - -## Details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/). diff --git a/plugins/aidd-context/skills/10-learn/README.md b/plugins/aidd-context/skills/10-learn/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/10-learn/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/11-explore/README.md b/plugins/aidd-context/skills/11-explore/README.md deleted file mode 100644 index 7a8eb5c0..00000000 --- a/plugins/aidd-context/skills/11-explore/README.md +++ /dev/null @@ -1,31 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 11 - Explore - -Surveys the current project across three axes so you see what is there, then lets you dig into any of them. It maps the project, it never tells you the next step (that is onboard's job). - -## When to use - -- "What do we have here?" / "What is installed?" / "What is set up?" -- Browsing the AIDD capabilities, the context layer, or the project shape. -- Finding which skill, agent, rule, or hook fits a goal. - -## When not to use - -- For the next logical step to take. Use `aidd-context:00-onboard`. -- To run a found item. Explore points, the user invokes. -- To create a new skill, rule, or agent. Use the generators. - -## The three axes - -- **Tooling**: the installed skills, agents, commands, rules, hooks, MCP servers, and plugins. What you can run. -- **Context**: the memory bank, specs, plans, and the AI context files. What the AI knows. -- **Codebase**: the stack and the high-level structure. What the project is. - -## Flow - -It detects your AI tools first, then routes by what you asked. Name nothing and `survey` reads the three axes and presents a compact map, then proposes one axis or all. Name an axis (or all) and `drill` goes straight in. `drill` lists the level in full, recommends the single best match with its invocation path when you name a goal, and descends one level deeper on request, a skill into its actions, a memory file into its sections, until a leaf or a stop. - -## Details - -See [`SKILL.md`](SKILL.md) for the contract, [`actions/`](actions/) for the two actions, and [`references/ai-mapping.md`](references/ai-mapping.md) for the per-tool scan paths. diff --git a/plugins/aidd-context/skills/11-explore/README.md b/plugins/aidd-context/skills/11-explore/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/11-explore/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-context/skills/12-cook/README.md b/plugins/aidd-context/skills/12-cook/README.md deleted file mode 100644 index d4d04135..00000000 --- a/plugins/aidd-context/skills/12-cook/README.md +++ /dev/null @@ -1,12 +0,0 @@ -← [framework](../../../../README.md) / [aidd-context](../../README.md) - -# 12 - cook - -Maintain the project's `recipes/` how-to sheets: list them, or create and update one from the canonical template. The recipes are the short runbooks at the root of whatever project the skill runs in. - -| # | Action | Purpose | -| --- | ------------------------------ | ---------------------------------------------- | -| 01 | [list](actions/01-list.md) | List every recipe as a table. | -| 02 | [upsert](actions/02-upsert.md) | Create or update one recipe from the template. | - -See [`SKILL.md`](SKILL.md) for the router and [`assets/recipe-template.md`](assets/recipe-template.md) for the recipe shape. diff --git a/plugins/aidd-context/skills/12-cook/README.md b/plugins/aidd-context/skills/12-cook/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index ec41b86e..f6b32387 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -48,7 +48,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-implement.md](skills/00-sdlc/actions/03-implement.md) | - | | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | -| `-` | [README.md](skills/00-sdlc/README.md) | - | | `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `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.` | #### `skills/01-plan` @@ -61,7 +60,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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.` | - | @@ -71,7 +69,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-implement.md](skills/02-implement/actions/01-implement.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.` | @@ -83,7 +80,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-assert-architecture.md](skills/03-assert/actions/02-assert-architecture.md) | - | | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | | `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | -| `-` | [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.` | #### `skills/04-audit` @@ -98,7 +94,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | - | | `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | - | | `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | - | -| `-` | [README.md](skills/04-audit/README.md) | - | - | | `-` | [SKILL.md](skills/04-audit/SKILL.md) | `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).` | - | #### `skills/05-review` @@ -109,7 +104,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | - | | `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).` | - | #### `skills/06-test` @@ -118,7 +112,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-test.md](skills/06-test/actions/01-test.md) | - | | `actions` | [02-test-journey.md](skills/06-test/actions/02-test-journey.md) | - | -| `-` | [README.md](skills/06-test/README.md) | - | | `-` | [SKILL.md](skills/06-test/SKILL.md) | `Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser.` | #### `skills/07-refactor` @@ -129,7 +122,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-security.md](skills/07-refactor/actions/02-security.md) | - | | `actions` | [03-cleanup.md](skills/07-refactor/actions/03-cleanup.md) | - | | `actions` | [04-architecture.md](skills/07-refactor/actions/04-architecture.md) | - | -| `-` | [README.md](skills/07-refactor/README.md) | - | | `-` | [SKILL.md](skills/07-refactor/SKILL.md) | `Improve code 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).` | #### `skills/08-debug` @@ -140,7 +132,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-debug.md](skills/08-debug/actions/02-debug.md) | - | | `actions` | [03-reflect-issue.md](skills/08-debug/actions/03-reflect-issue.md) | - | | `assets` | [task-template.md](skills/08-debug/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | -| `-` | [README.md](skills/08-debug/README.md) | - | | `references` | [mermaid-conventions.md](skills/08-debug/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `-` | [SKILL.md](skills/08-debug/SKILL.md) | `Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation.` | @@ -152,7 +143,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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.` | - | #### `skills/10-todo` @@ -160,6 +150,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-todo.md](skills/10-todo/actions/01-todo.md) | - | -| `-` | [README.md](skills/10-todo/README.md) | - | | `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, 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.` | diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md deleted file mode 100644 index ee150af0..00000000 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ /dev/null @@ -1,67 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 00 - sdlc - -Pure orchestrator for the full AIDD development flow. Takes a free-form request -from idea to shipped code by composing the other skills in this plugin (and any -VCS-providing capabilities loaded at runtime, e.g. commit and pull-request). -Holds no business logic of its own; every step is delegated. - -## When to use - -- A human (or upstream orchestrator) hands over a free-form request and you - need to drive it end-to-end: spec, plan, implement, review, ship. -- You want the default autonomous run (`auto` mode) with no human prompts. -- You want the same flow but with confirmation gates (`interactive` mode). - -## When NOT to use - -- A single SDLC step is enough → call that skill directly - ([01-plan](../01-plan/README.md), [02-implement](../02-implement/README.md), - [05-review](../05-review/README.md), etc.). -- You need to audit, refactor, debug, test, or assert outside of a shipping - pipeline → see [04-audit](../04-audit/README.md), - [07-refactor](../07-refactor/README.md), [08-debug](../08-debug/README.md), - [06-test](../06-test/README.md), [03-assert](../03-assert/README.md). -- The task has an explicit retry-until-success contract → use - [09-for-sure](../09-for-sure/README.md). - -## How to invoke - -``` -/sdlc # auto mode (default) -/sdlc interactive # pauses at each gate for human confirmation -``` - -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 - `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 pull request with title, body, base branch, and draft state. -- Findings + completion + quality scores from the reviewer. - -## 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. -- A VCS-providing capability is loaded at runtime for the ship step - (commit + pull-request creation). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the orchestration contract, the iron rule -("you are the conductor, not a player"), the mode detection logic, and the -five interactive gate definitions. Per-action contracts live in -[`actions/`](actions/). diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md deleted file mode 100644 index 9962491a..00000000 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ /dev/null @@ -1,56 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 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. - -## 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. - -## When NOT to use - -- You already have a plan and need to write code → use - [02-implement](../02-implement/README.md). -- The task is a single fix with no planning surface → use - [08-debug](../08-debug/README.md) or edit directly. -- You want spec drafting, not planning -> use the project's spec-drafting capability. - -## How to invoke - -``` -Use skill aidd-dev:01-plan -``` - -The skill exposes 3 actions: - -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. - -## Outputs - -- 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. - -## Prerequisites - -- A validated spec, ticket, or design source as input. -- Access to the plan template asset 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/). diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md deleted file mode 100644 index 8708a777..00000000 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 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. - -## 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. - -## 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). - -## How to invoke - -``` -Use skill aidd-dev:02-implement -``` - -Pass the plan path or content as `$ARGUMENTS`. The skill exposes 1 action: - -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. - -## 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. - -## 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. - -## 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). diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md deleted file mode 100644 index c0a9c069..00000000 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ /dev/null @@ -1,60 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 03 - assert - -Validates implementations through iterative assertion loops. Covers general -feature assertions, architecture conformance (ADRs, diagrams, project -structure), and browser-based frontend UI checks. - -## When to use - -- A feature is implemented and you need to assert it behaves as intended - before merging or shipping. -- You need to verify code conforms to documented architecture (ADRs, - diagrams, structure). -- A frontend change needs visual / behavioral validation in a real browser. - -## When NOT to use - -- The work isn't built yet → plan first with - [01-plan](../01-plan/README.md) and implement with - [02-implement](../02-implement/README.md). -- You want a rule-based code review → use - [05-review](../05-review/README.md). -- You're writing tests for the first time → use - [06-test](../06-test/README.md). - -## How to invoke - -``` -Use skill aidd-dev:03-assert -``` - -The skill exposes 3 actions: - -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. - -## 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. - -## Prerequisites - -- An explicit acceptance criterion, architecture artifact, or frontend - surface to validate against. -- A running dev server / preview when asserting frontend. -- Browser automation tooling available in the runtime for the frontend - variant. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action list. Per-action contracts live -in [`actions/`](actions/). diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/04-audit/README.md b/plugins/aidd-dev/skills/04-audit/README.md deleted file mode 100644 index f4cc8621..00000000 --- a/plugins/aidd-dev/skills/04-audit/README.md +++ /dev/null @@ -1,67 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 04 - audit - -Read-only codebase audit across seven quality pillars. Diagnoses and ranks -findings into a structured report; it never edits code. Each finding hands -off to the relevant act-skill (refactor, test, impeccable) when a fix is -wanted. - -## When to use - -- You want a global health check of the codebase, or a deep look at one - dimension (security, performance, dependencies, ...). -- You're preparing a refactor and need a prioritized, located list of issues. -- A new contributor (or a stale repo) needs hidden problems surfaced. - -## When NOT to use - -- A specific bug is already known → use [08-debug](../08-debug/README.md). -- You want to fix the problems → run the audit first, then 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 a per-PR code review → use [05-review](../05-review/README.md). -- You want to validate a feature works → use [03-assert](../03-assert/README.md). - -## How to invoke - -``` -Use skill aidd-dev:04-audit -``` - -Run-one or run-all: - -- Name a pillar (`audit security`, `perf audit`) → one pillar. -- Ask for a full audit (`/audit`, "health check") → the skill asks "full or a - specific pillar?", then scans all applicable pillars into one merged report. - -The seven pillars: - -1. `code-quality` - clean code (naming, SOLID, DRY, smells) + tech debt. -2. `architecture` - C4 / ADR conformance, coupling, boundaries, layering. -3. `security` - OWASP, authz, input validation, secrets. -4. `dependencies` - CVEs, licenses, outdated and unused deps. -5. `performance` - N+1, hot paths, bundle size, heavy operations. -6. `tests` - critical-path coverage, flakiness, pyramid balance. -7. `ui` - states, visual hierarchy, design-system drift, responsive, a11y. - -## Outputs - -- One structured report: a findings table (severity, pillar, `file:line`, - issue, fix, effort), a ranked Top-actions list, and a Coverage section - proving which pillars were scanned (and which were skipped, with reason). - -## Prerequisites - -- Project rules and architecture docs loaded in context (the audit grades - against them). -- Read access to the codebase. -- For tool/runtime pillars (dependencies, performance, tests, ui): the - relevant tool when available; otherwise that pillar degrades or is skipped - with a recorded reason. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the routing + output contract, the -`actions/0X-.md` files for each pillar's lens and method, and -[`assets/audit-template.md`](assets/audit-template.md) for the report shape. diff --git a/plugins/aidd-dev/skills/04-audit/README.md b/plugins/aidd-dev/skills/04-audit/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/04-audit/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md deleted file mode 100644 index 72003c6f..00000000 --- a/plugins/aidd-dev/skills/05-review/README.md +++ /dev/null @@ -1,64 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 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. - -## 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. - -## When NOT to use - -- You want to assert runtime behavior, not review code → use - [03-assert](../03-assert/README.md). -- You want to fix the issues, not surface them → use - [02-implement](../02-implement/README.md) or - [07-refactor](../07-refactor/README.md) after the review. -- You want a global codebase audit, not a per-feature review → use - [04-audit](../04-audit/README.md). - -## How to invoke - -``` -Use skill aidd-dev:05-review -``` - -The skill exposes 2 actions: - -1. `review-code` - grade the diff against project rules; surface - violations with file, line, and rule reference. -2. `review-functional` - verify the feature against the plan's acceptance - criteria; emit per-criterion pass / fail. - -## 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. - -## 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. - -## 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. diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/06-test/README.md b/plugins/aidd-dev/skills/06-test/README.md deleted file mode 100644 index 452e7826..00000000 --- a/plugins/aidd-dev/skills/06-test/README.md +++ /dev/null @@ -1,56 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 06 - test - -Writes and iterates on tests until they pass, and validates user journeys -end-to-end through browser automation. Identifies untested behaviors first, -then drives test creation until quality criteria are met. - -## When to use - -- A feature has insufficient test coverage and you want a list of - untested behaviors plus iteration toward passing tests. -- A user journey needs end-to-end validation in a real browser before - shipping. -- You want test-first iteration on an existing module. - -## When NOT to use - -- You want to assert a single criterion, not build a test suite → use - [03-assert](../03-assert/README.md). -- You're debugging a known failure → use - [08-debug](../08-debug/README.md). -- You want a rule-based code review of existing tests → use - [05-review](../05-review/README.md). - -## How to invoke - -``` -Use skill aidd-dev:06-test -``` - -The skill exposes 2 actions: - -1. `test` - list untested behaviors and iterate on test creation until - tests pass with best practices applied. -2. `test-journey` - navigate a user journey in the browser and validate - each step end-to-end. - -## Outputs - -- New or updated test files following project test conventions. -- A list of remaining untested behaviors when coverage is incomplete. -- A journey transcript with per-step verdicts for the browser variant. - -## Prerequisites - -- A test runner configured in the repo (Jest, Vitest, Playwright, etc.). -- A running app / preview when validating user journeys. -- Browser automation tooling available in the runtime for the journey - variant. - -## Technical details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two test -contracts. The journey action depends on browser tooling exposed by the -runtime. diff --git a/plugins/aidd-dev/skills/06-test/README.md b/plugins/aidd-dev/skills/06-test/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/06-test/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/07-refactor/README.md b/plugins/aidd-dev/skills/07-refactor/README.md deleted file mode 100644 index cedcd2da..00000000 --- a/plugins/aidd-dev/skills/07-refactor/README.md +++ /dev/null @@ -1,73 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 07 - refactor - -Improves code without breaking behavior across four axes: cleanup -(clean-code + tech debt), performance, security, and architecture. It is -the act-side counterpart of [04-audit](../04-audit/README.md) - audit -reports, refactor fixes. - -## When to use - -- You want to clean up, optimize, harden, or restructure existing code. -- An [04-audit](../04-audit/README.md) report flagged issues to fix now - - push the report into refactor and it fixes the listed findings. -- A profile, security review, or coupling problem points to a concrete - improvement. - -## When NOT to use - -- You only want a read-only diagnosis → run [04-audit](../04-audit/README.md). -- The task is a functional bug fix → use [08-debug](../08-debug/README.md). -- You want to add new behavior, not improve existing → use - [02-implement](../02-implement/README.md). -- You want to add tests → [06-test](../06-test/README.md). UI redesign → - the impeccable skill. - -## How to invoke - -``` -Use skill aidd-dev:07-refactor -``` - -Run-one or run-all: - -- Name an axis (`optimize`, `harden`, `clean up`, `restructure`) → that axis. -- Unscoped (`refactor this`) → the skill asks "all applicable axes, or a - specific one?", then runs the chosen one or all. - -The four axes (each maps to an audit pillar): - -1. `performance` - N+1, hot paths, batching, memoization. -2. `security` - OWASP, validation, authz, secrets (may change behavior to - close a hole). -3. `cleanup` - clean-code: rename, extract, DRY, dead-code, complexity. -4. `architecture` - extract layers, fix coupling, enforce boundaries. - -## Audit handoff (push, never pull) - -Refactor never loads the audit skill. Each axis runs **standalone** (scans -its lens, then fixes) or **audit-fed** when the caller pushes an -`audit_report` (path under `aidd_docs/tasks/audits/` or pasted findings) - -then it fixes that report's findings for its axis and skips its own scan. -The bridge is the report artifact, not a cross-skill dependency. - -## Outputs - -- Code changes scoped to the axis, with a list of `changes_applied`. -- Behavior-preserving verification (tests / types / side-by-side) for - cleanup, performance, architecture; an explicit behavior-change call-out - for security. - -## Prerequisites - -- Tests in place so the refactor is verifiable (or scheduled via - [06-test](../06-test/README.md)). -- For the architecture axis: the documented architecture (C4 / ADRs) in - `aidd_docs/memory/` to enforce against; large moves may need - [01-plan](../01-plan/README.md) first. - -## Technical details - -See [`SKILL.md`](SKILL.md) for routing + the push-not-pull audit handoff, -and [`actions/`](actions/) for each axis contract. diff --git a/plugins/aidd-dev/skills/07-refactor/README.md b/plugins/aidd-dev/skills/07-refactor/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/07-refactor/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/08-debug/README.md b/plugins/aidd-dev/skills/08-debug/README.md deleted file mode 100644 index 10775b76..00000000 --- a/plugins/aidd-dev/skills/08-debug/README.md +++ /dev/null @@ -1,58 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 08 - debug - -Reproduces and fixes bugs systematically using a test-driven workflow: -reproduce the failure, reflect on hypotheses, validate with logs, then -apply a targeted fix. Drives the loop from issue to PR. - -## When to use - -- A bug is reported and you want a disciplined reproduce → diagnose → - fix → verify loop. -- A flaky test or intermittent failure needs root-cause analysis backed by - validation logs. -- An issue exists in the tracker and you want to ship the fix as a PR. - -## When NOT to use - -- The work is new feature development → use - [00-sdlc](../00-sdlc/README.md) or - [02-implement](../02-implement/README.md). -- The fix is a refactor with no behavioral defect → use - [07-refactor](../07-refactor/README.md). -- You want broad coverage analysis, not one bug → use - [04-audit](../04-audit/README.md). - -## How to invoke - -``` -Use skill aidd-dev:08-debug -``` - -The skill exposes 3 actions: - -1. `reproduce` - produce a deterministic reproduction (failing test or - command). -2. `debug` - diagnose the root cause and apply the fix. -3. `reflect-issue` - enumerate likely causes, rank them, add validation - logs before committing to a hypothesis. - -## Outputs - -- A failing reproduction (test or script) that turns green after the fix. -- A root-cause note attached to the issue or PR. -- Targeted fix commits scoped to the defect. -- Updated tests covering the regression. - -## Prerequisites - -- An issue or report describing the failure (stack trace, repro steps, - expected vs observed). -- Test infrastructure able to host the reproduction. - -## Technical details - -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the three -debug contracts. The reflect-issue action explicitly mandates logs before -acting, to prevent jumping to the wrong hypothesis. diff --git a/plugins/aidd-dev/skills/08-debug/README.md b/plugins/aidd-dev/skills/08-debug/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/08-debug/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/09-for-sure/README.md b/plugins/aidd-dev/skills/09-for-sure/README.md deleted file mode 100644 index 9bee2507..00000000 --- a/plugins/aidd-dev/skills/09-for-sure/README.md +++ /dev/null @@ -1,66 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 09 - for-sure - -Autonomous loop that runs until a `success_condition` is verified. Two -phases: interactive pre-flight (human present), then autonomous execution -(human gone). The agent auto-accepts everything, acts as the user, and -never stops until the success condition holds. - -## When to use - -- The user says "for sure", "make sure", "keep trying until", "loop until - done", "don't stop until", or otherwise requests guaranteed completion. -- A long-running task with an explicit, verifiable success condition can - run unattended. -- You need a retry loop that tracks attempts in a durable tracking file. - -## When NOT to use - -- No verifiable success condition exists → define one first, or use a - one-shot skill. -- The task is part of a standard SDLC pipeline → use - [00-sdlc](../00-sdlc/README.md). -- The task is a single bug fix → use [08-debug](../08-debug/README.md). -- The task needs human gates mid-loop - this skill auto-accepts and never - asks once it enters Phase 2. - -## How to invoke - -``` -/for-sure -``` - -The skill exposes 3 actions across two phases: - -1. `init-tracking` (Phase 1, interactive) - pre-flight validation, - create the tracking file, spawn the first autonomous agent. -2. `auto-accept` (Phase 2) - activate auto-accept mode for the - autonomous run. -3. `autonomous-loop` (Phase 2) - orchestrator that spawns one worker per - step, verifies output, retries on failure with a meaningful change, - evaluates the success condition. - -## Outputs - -- A tracking file at `aidd_docs/tasks/.md` (state in the - `status` frontmatter field) from For Sure's own plan template, which - extends the [01-plan](../01-plan/README.md) format with - `success_condition` and `iteration`. -- Per-attempt log entries inside the tracking file. -- The tracking file's `status` set to `implemented` once and only once the - success condition genuinely verifies. - -## Prerequisites - -- An explicit `success_condition` expressed as a command whose exit code - (or output) decides success. -- Acceptance criteria and steps documented in the tracking file. -- Task-specific secrets validated during pre-flight (Phase 1). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the iron rules (single source of truth, -no repeated failures, honesty over escape, auto-accept) and -[`actions/`](actions/) for the per-phase contracts. The tracking file -uses For Sure's own plan template asset (`@assets/plan-template.md`). diff --git a/plugins/aidd-dev/skills/09-for-sure/README.md b/plugins/aidd-dev/skills/09-for-sure/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/09-for-sure/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md deleted file mode 100644 index 727b75be..00000000 --- a/plugins/aidd-dev/skills/10-todo/README.md +++ /dev/null @@ -1,19 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 10 - todo - -Split one prompt into independent todos, run one implementer agent per -todo in parallel (each refines its todo before coding), and report a -minimal table: category, what was launched, output. - -## When to use - -- The user says "todo" or `/todo`. -- A single prompt bundles several independent tasks that can be - implemented in parallel. - -## Actions - -| # | Action | Purpose | -| --- | --------------------------------- | --------------------------------------------- | -| 01 | [todo](actions/01-todo.md) | Categorize, launch parallel agents, report. | diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-dev/skills/10-todo/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 16290f8f..09010570 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -24,7 +24,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| -| `-` | [README.md](skills/00-async-dev/README.md) | - | | `references` | [routing.md](skills/00-async-dev/references/routing.md) | - | | `-` | [SKILL.md](skills/00-async-dev/SKILL.md) | `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.` | diff --git a/plugins/aidd-orchestrator/README.md b/plugins/aidd-orchestrator/README.md index 3c90de17..bedef6b2 100644 --- a/plugins/aidd-orchestrator/README.md +++ b/plugins/aidd-orchestrator/README.md @@ -18,7 +18,7 @@ Composes capabilities into deterministic, auditable flows. Each skill is one orc |------------|-------|-------------| | [6.0] | [async-dev](skills/00-async-dev/README.md) | Single router-based skill covering the full pipeline — setup, run, and review — selected by `$ARGUMENTS` keyword, trigger source, repo state, or natural-language intent. | -See the [skill README](skills/00-async-dev/README.md) for the sub-flow inventory and invocation contract. +Use the skill table above and the generated catalog for the sub-flow inventory and invocation contract. ### Roadmap diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/README.md b/plugins/aidd-orchestrator/skills/00-async-dev/README.md deleted file mode 100644 index 14352618..00000000 --- a/plugins/aidd-orchestrator/skills/00-async-dev/README.md +++ /dev/null @@ -1,55 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-orchestrator](../../README.md) - -# 00 - Async-dev - -Single entry point for the async-dev pipeline. Hybrid router that picks one of three internal sub-flows (`setup`, `run`, `review`) from `$ARGUMENTS` keyword, trigger source, repo state, or natural-language intent, then runs that sub-flow to completion. - -## When to use - -- You want to install / configure async-dev in a repo. -- A GitHub event fires (`to-implement` / `to-review` label, `@claude /implement` or `/review` comment) and the workflow needs to react. -- You want to handle a ready issue or address review comments on an open PR. -- The user types "async dev", "/async-dev", or mixes phases ("set up async dev and run on issue 42"). - -## When NOT to use - -- For plain status checks on the async pipeline (read labels / comments directly). -- For SDLC orchestration unrelated to issue / PR automation (use `aidd-dev:00-sdlc`). -- From inside a sub-flow action — actions never re-enter the router. - -## How to invoke - -```text -Use skill aidd-orchestrator:00-async-dev -``` - -With an explicit sub-flow keyword (preferred from CI): - -```text -Use skill aidd-orchestrator:00-async-dev with action=setup -Use skill aidd-orchestrator:00-async-dev with action=run on issue #42 -Use skill aidd-orchestrator:00-async-dev with action=review on PR #17 -``` - -The router reads `$ARGUMENTS`, then trigger env, then repo state, then natural intent. See [`references/routing.md`](references/routing.md) for the full decision tree. - -## Sub-flows - -| Sub-flow | First action | Cardinality | -| -------- | -------------------------------------------------- | ------------------ | -| Setup | [`actions/setup/01-detect-context.md`](actions/setup/01-detect-context.md) | 11 actions, run once per install | -| Run | [`actions/run/01-poll-ready.md`](actions/run/01-poll-ready.md) | 6 actions, run once per ready issue | -| Review | [`actions/review/01-collect-comments.md`](actions/review/01-collect-comments.md) | 4 actions, looped on the PR until stop | - -## Outputs - -Each sub-flow defines its own outputs: - -- **Setup**: workflow file, config file, scripts, labels, schedule routine id (if applicable). -- **Run**: `run-result.json` artefact consumed by the workflow's post-job. -- **Review**: stop-reason + structured summary comment on the PR. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the hybrid routing contract, sub-flow indexes, and rules. -See [`references/routing.md`](references/routing.md) for the full decision tree. diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/README.md b/plugins/aidd-orchestrator/skills/00-async-dev/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-orchestrator/skills/00-async-dev/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index e2860668..52852e49 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -28,7 +28,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-ticket-info.md](skills/01-ticket-info/actions/01-ticket-info.md) | - | -| `-` | [README.md](skills/01-ticket-info/README.md) | - | | `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display 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.` | #### `skills/02-user-stories-create` @@ -37,7 +36,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---|---| | `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.` | - | #### `skills/03-prd` @@ -47,7 +45,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | - | | `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | `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.` | - | #### `skills/04-spec` @@ -57,6 +54,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-build.md](skills/04-spec/actions/01-build.md) | - | | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | -| `-` | [README.md](skills/04-spec/README.md) | - | | `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a 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.` | diff --git a/plugins/aidd-pm/skills/01-ticket-info/README.md b/plugins/aidd-pm/skills/01-ticket-info/README.md deleted file mode 100644 index fece34b3..00000000 --- a/plugins/aidd-pm/skills/01-ticket-info/README.md +++ /dev/null @@ -1,52 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 01 - Ticket Info - -Reads ticket details from the configured ticketing tool and displays them in -the chat. Read-only and tool-agnostic: the same skill works whether the -project is on Jira, Linear, GitHub Issues, or any other tracker recorded in -the project memory. - -## When to use - -- "ticket info", "show ticket", "get ticket", "ticket details". -- "what's " when `` looks like a ticket reference. -- Invoking `/ticket-info`. -- Pulling a ticket id from the current branch name when no id is supplied. - -## When NOT to use - -- To create a new issue, use a skill that advertises issue creation in its description (run `/plugin` and browse the **Discover** tab to find one). -- To comment on, transition, or reassign a ticket - this skill is read-only. -- For free-form ticket searches across a project; this skill targets one id. - -## How to invoke - -``` -Use skill aidd-pm:01-ticket-info on -``` - -Or, with no id, let the skill auto-detect from the current git branch: - -``` -Use skill aidd-pm:01-ticket-info -``` - -## Outputs - -- A chat-rendered summary of the ticket: id, title, status, assignee, type, - priority, and description, formatted per the configured tool's conventions. -- No files written. No tracker mutations. - -## Prerequisites - -- Project memory declares the active ticketing tool (or repo config / - environment makes it inferable). -- Auth for that tool is reachable from the runtime (MCP server, CLI, or API - token already configured at the project level). - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and -[`actions/01-ticket-info.md`](actions/01-ticket-info.md) for the single -atomic action that resolves the id, queries the tool, and formats output. diff --git a/plugins/aidd-pm/skills/01-ticket-info/README.md b/plugins/aidd-pm/skills/01-ticket-info/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-pm/skills/01-ticket-info/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file 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 -``` - -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/README.md b/plugins/aidd-pm/skills/02-user-stories-create/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories-create/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-pm/skills/03-prd/README.md b/plugins/aidd-pm/skills/03-prd/README.md deleted file mode 100644 index bb4576a3..00000000 --- a/plugins/aidd-pm/skills/03-prd/README.md +++ /dev/null @@ -1,52 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 03 - PRD - -Drafts a structured Product Requirements Document covering scope, goals, -and acceptance criteria from a feature description or a set of user stories. -Stays at the "what and why" level; never crosses into implementation detail. - -## When to use - -- "prd", "draft prd", "write prd". -- "product requirements for X", "generate a prd". -- Invoking `/prd`. -- After user stories are ready and you need a single document to align - stakeholders before planning starts. - -## When NOT to use - -- To write user stories → use `02-user-stories-create`. -- To draft a technical implementation plan (libraries, file layout, - algorithms) - those belong to the planning skill in your dev capability. -- To write source code. - -## How to invoke - -``` -Use skill aidd-pm:03-prd for -``` - -The skill parses the input, drafts each section per template, shows the -draft, and waits for explicit validation before saving. - -## Outputs - -- A PRD file saved at - `aidd_docs/tasks//--prd.md`. -- Sections: scope, goals, non-goals, user stories or personas, acceptance - criteria, and any task references needed. -- No tracker mutations. - -## Prerequisites - -- A feature description, a set of user stories, or both. -- Write access to `aidd_docs/tasks/` in the current repo. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, -[`actions/01-prd.md`](actions/01-prd.md) for the single atomic action, -[`assets/prd-template.md`](assets/prd-template.md) for the PRD structure, -and [`assets/task-template.md`](assets/task-template.md) for the lightweight -task template referenced from the PRD when needed. diff --git a/plugins/aidd-pm/skills/03-prd/README.md b/plugins/aidd-pm/skills/03-prd/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-pm/skills/03-prd/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md deleted file mode 100644 index 80d2829d..00000000 --- a/plugins/aidd-pm/skills/04-spec/README.md +++ /dev/null @@ -1,63 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md) - -# 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. - -## When to use - -- "draft spec", "spec for X", "generate spec from prd". -- "refine the spec" when reviewer findings come back. -- Invoking `/spec`. -- When an orchestrator needs a normalized contract before triggering a plan. - -## When NOT to use - -- To write source code. -- To draft a full PRD → use `03-prd`. -- To modify a spec that has already been validated and locked - the spec - is immutable past that point; open a new spec instead. - -## How to invoke - -Build a fresh spec from a request or an existing PRD: - -``` -Use skill aidd-pm:04-spec build for -``` - -Refine an existing spec from reviewer findings: - -``` -Use skill aidd-pm:04-spec refine on with -``` - -The router picks the action from the inputs: presence of `existing_spec` -and `findings` triggers `refine`; otherwise `build` runs. - -## Outputs - -- A spec file structured per [`assets/spec-template.md`](assets/spec-template.md), - with explicit non-goals, bulleted acceptance criteria, and `TBD: ` markers wherever information is missing. -- On `refine`: the same file rewritten to address the supplied findings. -- The skill never self-validates; 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. - -## Prerequisites - -- A free-form request, an existing PRD path, or an existing spec plus a - set of reviewer 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. diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-pm/skills/04-spec/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md index 153d6edd..dde04652 100644 --- a/plugins/aidd-refine/CATALOG.md +++ b/plugins/aidd-refine/CATALOG.md @@ -41,7 +41,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-integrate.md](skills/01-brainstorm/actions/03-integrate.md) | - | | `actions` | [04-finalize.md](skills/01-brainstorm/actions/04-finalize.md) | - | | `assets` | [question-angles.md](skills/01-brainstorm/assets/question-angles.md) | - | -| `-` | [README.md](skills/01-brainstorm/README.md) | - | | `references` | [probing.md](skills/01-brainstorm/references/probing.md) | - | | `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague idea through deep 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.` | @@ -50,7 +49,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-challenge.md](skills/02-challenge/actions/01-challenge.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.` | @@ -60,7 +58,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-condense.md](skills/03-condense/actions/01-condense.md) | - | | `actions` | [02-stats.md](skills/03-condense/actions/02-stats.md) | - | -| `-` | [README.md](skills/03-condense/README.md) | - | | `references` | [intensity-levels.md](skills/03-condense/references/intensity-levels.md) | - | | `-` | [SKILL.md](skills/03-condense/SKILL.md) | `Toggle terse output mode 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).` | @@ -72,7 +69,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-render-report.md](skills/04-shadow-areas/actions/02-render-report.md) | - | | `actions` | [03-diff.md](skills/04-shadow-areas/actions/03-diff.md) | - | | `assets` | [report-template.md](skills/04-shadow-areas/assets/report-template.md) | - | -| `-` | [README.md](skills/04-shadow-areas/README.md) | - | | `references` | [categories.md](skills/04-shadow-areas/references/categories.md) | - | | `references` | [locked-sets.json](skills/04-shadow-areas/references/locked-sets.json) | - | | `references` | [probe-style.md](skills/04-shadow-areas/references/probe-style.md) | - | @@ -87,7 +83,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-verify.md](skills/05-fact-check/actions/02-verify.md) | - | | `actions` | [03-report.md](skills/05-fact-check/actions/03-report.md) | - | | `assets` | [report-template.md](skills/05-fact-check/assets/report-template.md) | - | -| `-` | [README.md](skills/05-fact-check/README.md) | - | | `references` | [claim-categories.md](skills/05-fact-check/references/claim-categories.md) | - | | `references` | [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.` | diff --git a/plugins/aidd-refine/skills/01-brainstorm/README.md b/plugins/aidd-refine/skills/01-brainstorm/README.md deleted file mode 100644 index 74d23687..00000000 --- a/plugins/aidd-refine/skills/01-brainstorm/README.md +++ /dev/null @@ -1,32 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 01 - Brainstorm - -Turns a vague idea into a precise one through a deep, natural conversation, at whatever level the user is thinking, functional or technical. It asks pointed questions, follows the threads each answer opens, and challenges assumptions until the idea is clear enough to act on. It digs, it does not tick boxes. - -## When to use - -- The user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request. -- An idea would otherwise force the next step (plan, code, test) to rest on assumptions. -- The user asks to brainstorm, clarify, or refine before committing. - -## When not to use - -- To scan a written artifact for gaps. Use `aidd-refine:04-shadow-areas`. -- To critique finished work. Use `aidd-refine:02-challenge`. -- The idea is already concrete enough to plan or code. - -## The loop - -`capture` restates the idea and reads its altitude. Then `probe → integrate` repeats: each round asks pointed questions on the live thread, follows the forks the answers open, challenges assumptions, and folds the answers back in. It keeps going until no real ambiguity remains or the user is satisfied. There is no fixed round count, the idea is done when it is clear, not on a timer. `finalize` consolidates the refined idea, flags every open assumption and risk, and offers to persist it to a dated file under `aidd_docs/brainstorm/`, a ticket, or the session only. - -## What makes it dig - -- **Follows threads, not topics.** It pulls on the fork an answer opens (filename versus full-text search, for instance), where the depth is, instead of cycling a fixed list. -- **Works at your altitude.** A technical question gets technical probing, a fuzzy feature gets product probing, never one level finer than you opened. -- **Leans when the facts point.** When the answers favor one option it says so with the tradeoff, and keeps the implementation as a flagged assumption for planning. -- **Flags, never fakes.** Whatever stays open is reported as an assumption or risk, never dressed up as settled. - -## Details - -See [`SKILL.md`](SKILL.md) for the contract, [`actions/`](actions/) for the four actions, [`references/probing.md`](references/probing.md) for how to read altitude, follow threads, the tactics, and when to stop, and [`assets/question-angles.md`](assets/question-angles.md) for the topical prompt banks. diff --git a/plugins/aidd-refine/skills/01-brainstorm/README.md b/plugins/aidd-refine/skills/01-brainstorm/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-refine/skills/01-brainstorm/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-refine/skills/02-challenge/README.md b/plugins/aidd-refine/skills/02-challenge/README.md deleted file mode 100644 index c415880b..00000000 --- a/plugins/aidd-refine/skills/02-challenge/README.md +++ /dev/null @@ -1,57 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 02 - Challenge - -Rethinks just-completed work against an agreed plan, surfaces what is wrong, -missing, or duplicated, and classifies each finding as deal-breaker, -suggestion, or correct. Outputs a confidence score so the user knows whether -to ship, iterate, or rework. - -## When to use - -- The user says "challenge this", "rethink your plan", "is this correct", - "review my last decision", "challenge my decision", "challenge what you - did", "is my decision right", "criticize this", or "find flaws". -- A critical review of just-completed work is requested before shipping. -- A decision needs adversarial scrutiny before being committed to. - -## When NOT to use - -- Line-by-line code review against a style guide. -- Implementing features, writing tests, or generating new code. -- Reviewing a plan that has not yet been written. - -## How to invoke - -``` -Use skill aidd-refine:02-challenge -``` - -The skill is single-action - the router dispatches to `challenge` whenever -the trigger phrases above appear. - -1. `challenge` - rethink prior work, classify findings, score confidence - against the agreed plan. - -## Outputs - -- A structured verdict report with three classified buckets: - - **Deal-breakers** - issues that block shipping. - - **Suggestions** - improvements that are not blockers. - - **Correct** - explicit acknowledgement of what is already right. -- A confidence percentage based on the tiered rubric. -- No code edits. The report is informational; the user decides what to act on. - -## Prerequisites - -- A piece of recently completed work (plan, decision, implementation, diff) - to challenge. -- An agreed reference point (plan, spec, decision record) to challenge it - against. Without one, the skill challenges against stated user intent. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for -the single step, and -[`references/confidence-rubric.md`](references/confidence-rubric.md) for the -tiered rubric backing the confidence percentage. diff --git a/plugins/aidd-refine/skills/02-challenge/README.md b/plugins/aidd-refine/skills/02-challenge/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-refine/skills/02-challenge/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-refine/skills/03-condense/README.md b/plugins/aidd-refine/skills/03-condense/README.md deleted file mode 100644 index af75df33..00000000 --- a/plugins/aidd-refine/skills/03-condense/README.md +++ /dev/null @@ -1,64 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 03 - Condense - -Toggles a terse output mode with three intensity levels (`lite`, `full`, -`ultra`). Strips articles, filler, and pleasantries from prose while leaving -code blocks, quoted errors, and security warnings verbatim. Also reports real -token usage and estimated savings for the current session. - -## When to use - -- The user says "condense", "condense output", "be more concise", "shorter - answers", "tighten output", "/condense", "/condense full", "/condense - ultra", "stop condense", or "normal mode". -- The user asks for token-savings stats: "/condense-stats", "how much have we - saved", "token savings". -- A long session would benefit from compressed prose without losing technical - substance. - -## When NOT to use - -- Editing existing prose written by the user - only the assistant's own - output style is affected. -- Summarizing a long document into a shorter version. -- Compressing source code, commit messages, or pull request bodies - those - stay in normal English regardless of intensity. - -## How to invoke - -``` -Use skill aidd-refine:03-condense -``` - -The router dispatches by intent: - -- Toggle phrase or intensity command (`condense`, `/condense full`, `stop - condense`, `normal mode`, ...) → `01-condense`. -- Stats query (`/condense-stats`, `how much have we saved`, `token - savings`, ...) → `02-stats`. - -## Outputs - -- A toggled response mode for the rest of the session. No files are written. -- Intensity persists across turns until the user explicitly turns it off - (`stop condense`, `normal mode`, `/condense off`) or toggles the skill - again. -- Stats action returns a formatted report of real token usage and estimated - savings under condense mode for the session. - -## Prerequisites - -- None for the toggle. The skill operates on the assistant's output style. -- Stats action expects a session transcript readable by the - `condense-stats.js` hook. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for -both steps, and -[`references/intensity-levels.md`](references/intensity-levels.md) for -per-level rules and side-by-side examples. The stats action is backed by the -`condense-stats.js` UserPromptSubmit hook, which intercepts stats triggers, -reads the session transcript, and returns the formatted savings report -without invoking the model. diff --git a/plugins/aidd-refine/skills/03-condense/README.md b/plugins/aidd-refine/skills/03-condense/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-refine/skills/03-condense/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-refine/skills/04-shadow-areas/README.md b/plugins/aidd-refine/skills/04-shadow-areas/README.md deleted file mode 100644 index efb26a5d..00000000 --- a/plugins/aidd-refine/skills/04-shadow-areas/README.md +++ /dev/null @@ -1,69 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 04 - Shadow Areas - -Analytically scans a written artifact (idea, user stories, PRD, or spec) for -blind spots: unstated assumptions, missing actors, missing failure modes, -ambiguous terms, missing acceptance criteria, missing edge cases, and missing -dependencies. Each gap is classified by category and severity, paired with a -direct-question probe the author can act on, and written to a structured -`-shadow-report.md` next to the source. - -## When to use - -- The user asks to "find blind spots", "scan for gaps", "shadow report", or - "what's missing" in a written artifact. -- A PRD, spec, idea note, or user-story set needs an analytical pass before - planning or implementation starts. -- A prior shadow report exists and the user re-runs after editing the source, - wanting to see which gaps are closed, still open, or newly introduced. - -## When NOT to use - -- The artifact does not yet exist and the user needs to clarify a vague intent - through iterative questioning - use the `aidd-refine:01-brainstorm` skill. -- The request is to review code style or check implementation correctness. -- The user needs a general chat about what to do next, not a gap analysis. - -## How to invoke - -``` -Use skill aidd-refine:04-shadow-areas -``` - -Provide either a file path or inline text as the source: - -``` -Use skill aidd-refine:04-shadow-areas with -``` - -The router dispatches based on whether a prior report is already present: - -1. `detect` - parse the source, extract gaps, assign category and severity, - write a direct-question probe per gap. -2. `diff` (only when a prior report exists) - load the prior report and - classify each gap as closed, still open, or newly introduced. -3. `render-report` - write `-shadow-report.md` grouped by category - and sorted by severity (blockers first). - -## Outputs - -- A markdown report `-shadow-report.md` written next to the source. -- Each gap entry: `category`, `severity`, `probe`, optional quoted `snippet`. -- Report header carries `status: clean` when zero blockers and zero majors remain. -- On re-runs: three labeled sections (Closed, Still Open, Newly Introduced). - -## Prerequisites - -- A written artifact in markdown (or plain text) the skill can read. -- The file must be inside the working directory; outside-tree relative paths - are rejected. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and transversal rules. -Action implementations are under [`actions/`](actions/). -The locked taxonomy and severity rubric live in [`references/`](references/); -[`references/locked-sets.json`](references/locked-sets.json) is the single -source of truth reused by both docs and the validator. -The report skeleton is at [`assets/report-template.md`](assets/report-template.md). diff --git a/plugins/aidd-refine/skills/04-shadow-areas/README.md b/plugins/aidd-refine/skills/04-shadow-areas/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-refine/skills/04-shadow-areas/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-refine/skills/05-fact-check/README.md b/plugins/aidd-refine/skills/05-fact-check/README.md deleted file mode 100644 index 170d6a03..00000000 --- a/plugins/aidd-refine/skills/05-fact-check/README.md +++ /dev/null @@ -1,69 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-refine](../../README.md) - -# 05 - Fact-check - -Verifies the factual claims inside a target text and rewrites it grounded in -evidence. Each verifiable claim is extracted, classified, and checked against a -cheapest-first cascade (project memory and docs, then codebase inspection, then -web lookup). The rewritten answer carries a footnote citation on every confirmed -claim, an explicit hedge on every unconfirmed claim, and both sources whenever -they disagree. - -## When to use - -- The user asks to "fact-check this", "verify that claim", "are you sure", "is - that actually true", "cite your sources", or "where did you get that fact". -- A prior answer states versions, API behavior, dates, or repository facts that - must be confirmed before being trusted. -- The user wants a clear separation between what is sourced and what is a guess. - -## When NOT to use - -- To auto-guard the AI's own output - this skill only fires on an explicit - request. A permanent "always verify" guard belongs in an always-loaded rule. -- To judge code logic correctness or review code style. -- To clarify vague requirements through iterative Q&A - use the - `aidd-refine:01-brainstorm` skill. - -## How to invoke - -``` -Use skill aidd-refine:05-fact-check -``` - -Provide the text to check - the prior answer, a quoted passage, or a pasted -block: - -``` -Use skill aidd-refine:05-fact-check on -``` - -The skill runs a fixed three-step pipeline: - -1. `identify-claims` - extract verifiable claims, classify each, drop opinion. -2. `verify` - run the cascade per claim, assign a verdict and record sources. -3. `report` - rewrite the text with footnote citations, hedge unverified - claims, and surface conflicts with both sources. - -## Outputs - -- The rewritten answer with a `[n]` marker on every verified claim. -- A `## Sources` footnote block - one numbered entry per source. -- A `## Unverified claims` section listing every claim the cascade could not - resolve (omitted when none). -- An optional cache suggestion for stable verified facts, opt-in only. - -## Prerequisites - -- A piece of text whose claims need checking. -- Project memory, docs, and codebase available for the cheap cascade tiers; a - web lookup tool for the last-resort tier. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and transversal rules. -Action implementations are under [`actions/`](actions/). -The claim taxonomy and the verification cascade live in -[`references/`](references/). -The rewritten-answer skeleton is at -[`assets/report-template.md`](assets/report-template.md). diff --git a/plugins/aidd-refine/skills/05-fact-check/README.md b/plugins/aidd-refine/skills/05-fact-check/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-refine/skills/05-fact-check/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 4cc8de8d..108f9b86 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -29,7 +29,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---|---| | `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.` | - | #### `skills/02-pull-request` @@ -41,7 +40,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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.` | - | #### `skills/03-release-tag` @@ -50,7 +48,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---|---| | `actions` | [01-release-tag.md](skills/03-release-tag/actions/01-release-tag.md) | - | - | | `assets` | [release-template.md](skills/03-release-tag/assets/release-template.md) | `VCS release notes template` | - | -| `-` | [README.md](skills/03-release-tag/README.md) | - | - | | `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with 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.` | - | #### `skills/04-issue-create` @@ -60,6 +57,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-issue-create.md](skills/04-issue-create/actions/01-issue-create.md) | - | - | | `assets` | [CONTRIBUTING.md](skills/04-issue-create/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | - | | `assets` | [issue-template.md](skills/04-issue-create/assets/issue-template.md) | `VCS issue/ticket template` | - | -| `-` | [README.md](skills/04-issue-create/README.md) | - | - | | `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user 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.` | - | diff --git a/plugins/aidd-vcs/skills/01-commit/README.md b/plugins/aidd-vcs/skills/01-commit/README.md deleted file mode 100644 index 0cba0c3f..00000000 --- a/plugins/aidd-vcs/skills/01-commit/README.md +++ /dev/null @@ -1,52 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 01 - Commit - -Creates an atomic git commit with a conventional, imperative-mood message, -optionally pushing the branch when the caller asks for it. - -## When to use - -- The user says "commit", "git commit", "create a commit", "commit my - changes", or "commit and push". -- The user invokes the `/commit` slash command. -- An agent has finished a contained change and needs it recorded as a single - atomic commit. - -## When NOT to use - -- To amend an existing commit (this skill always creates a new one). -- To force-push or rebase the current branch. -- To open a pull or merge request → use `02-pull-request`. -- To cut a release tag → use `03-release-tag`. - -## How to invoke - -``` -Use skill aidd-vcs:01-commit -``` - -Or via the slash command: - -- `/commit` - stage, commit, stay local (`push: false`). -- `/commit push` - stage, commit, then push the branch (`push: true`). - -The skill runs a single action (`commit`) that stages, generates or accepts a -message, commits, and optionally pushes. - -## Outputs - -- One new git commit on the current branch with a conventional message. -- Optionally, a pushed branch on the remote when `push: true`. - -## Prerequisites - -- A git repository with at least one staged or unstaged change. -- A configured git identity (`user.name`, `user.email`). -- A writable remote when `push: true`. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract and -[`assets/commit-template.md`](assets/commit-template.md) for the conventional -commit format reference shipped with the skill. diff --git a/plugins/aidd-vcs/skills/01-commit/README.md b/plugins/aidd-vcs/skills/01-commit/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-vcs/skills/01-commit/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-vcs/skills/02-pull-request/README.md b/plugins/aidd-vcs/skills/02-pull-request/README.md deleted file mode 100644 index 82dbe60f..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/README.md +++ /dev/null @@ -1,55 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 02 - Pull Request - -Drafts a pull request (GitHub) or merge request (GitLab) from the current -branch using the team's template, validates it with the user, and opens it -as a draft for manual promotion. - -## When to use - -- The user says "open a pr", "open a pull request", "create a pr", "create a - merge request", "open mr", or "draft a pr for this branch". -- The user invokes the `/pull-request` slash command. -- A feature branch is ready for review and needs a request opened against - the detected base branch. - -## When NOT to use - -- To commit changes → use `01-commit`. -- To push the working branch on its own (no request created). -- To tag a release → use `03-release-tag`. -- To merge an existing request, or to amend commits. - -## How to invoke - -``` -Use skill aidd-vcs:02-pull-request -``` - -Or via the slash command: `/pull-request`. - -The skill 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. - -## Outputs - -- A new draft pull request on GitHub, or a draft merge request on GitLab, - pointing from the current branch to the detected base branch, with the - filled template as its body. - -## Prerequisites - -- A git repository with a remote on GitHub or GitLab. -- The current branch is pushed (or the skill will defer to the user). -- `gh` (GitHub) or `glab` (GitLab) CLI authenticated, depending on the - detected VCS tool. -- The base branch resolves from project memory or remote inspection; the - skill does not assume `main` / `master`. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract. Templates ship in -[`assets/`](assets/): `pull_request.md` (request body), `branch.md` (naming -conventions), `CONTRIBUTING.md`, and `README.md`. diff --git a/plugins/aidd-vcs/skills/02-pull-request/README.md b/plugins/aidd-vcs/skills/02-pull-request/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-vcs/skills/02-pull-request/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-vcs/skills/03-release-tag/README.md b/plugins/aidd-vcs/skills/03-release-tag/README.md deleted file mode 100644 index 7041cc93..00000000 --- a/plugins/aidd-vcs/skills/03-release-tag/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 03 - Release Tag - -Cuts a semver release: computes the next version, drafts notes from recent -commits, validates with the user, bumps version-manager files, creates an -annotated git tag, and pushes it. - -## When to use - -- The user says "release", "tag", "tag this release", "bump version", - "release v1.2.0", or "cut a release". -- The user invokes the `/release-tag` slash command. -- A release-ready commit exists on the release branch and needs a versioned - tag with notes. - -## When NOT to use - -- For plain commits without a tag → use `01-commit`. -- To open a pull or merge request → use `02-pull-request`. -- To push a branch only, with no tag created. -- To amend or move an existing tag (this skill never force-updates tags). - -## How to invoke - -``` -Use skill aidd-vcs:03-release-tag -``` - -Or via the slash command: `/release-tag`. - -The skill runs a single action (`release-tag`) that computes the version, -drafts notes, validates with the user, applies the version bump, creates the -annotated tag, and pushes it. - -## Outputs - -- A version-bump commit touching only version-manager files (e.g. - `package.json`, `pyproject.toml`). -- An annotated git tag (`git tag -a vX.Y.Z`) carrying the release notes. -- The bump commit and the tag pushed to the remote. - -## Prerequisites - -- A git repository with a writable remote. -- A version-manager file the skill can update (e.g. `package.json`, - `pyproject.toml`). -- A clean working tree, or changes the user is willing to bundle into the - bump commit when prompted. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract. The release notes -template ships at [`assets/release-template.md`](assets/release-template.md). diff --git a/plugins/aidd-vcs/skills/03-release-tag/README.md b/plugins/aidd-vcs/skills/03-release-tag/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-vcs/skills/03-release-tag/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/plugins/aidd-vcs/skills/04-issue-create/README.md b/plugins/aidd-vcs/skills/04-issue-create/README.md deleted file mode 100644 index 1aee05e6..00000000 --- a/plugins/aidd-vcs/skills/04-issue-create/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-vcs](../../README.md) - -# 04 - Issue Create - -Files a well-formed issue in the configured ticketing tool after gathering -enough context to be actionable, validated with the user before creation. - -## When to use - -- The user says "new issue", "create an issue", "file a bug", "file an - issue", "report bug", or "open an issue". -- The user invokes the `/issue-create` slash command. -- A bug or feature request surfaces during work and needs a tracked record - in whichever ticketing tool the project uses. - -## When NOT to use - -- To commit changes → use `01-commit`. -- To open a pull or merge request → use `02-pull-request`. -- To cut a release tag → use `03-release-tag`. -- To comment on an existing issue (this skill only creates new ones). - -## How to invoke - -``` -Use skill aidd-vcs:04-issue-create -``` - -Or via the slash command: `/issue-create`. - -The skill runs a single action (`issue-create`) that detects the ticketing -tool, fills the issue template, validates title / body / labels / type / -projects / milestones with the user, then creates the issue. - -## Outputs - -- A new issue in the configured tracker (GitHub Issues, GitLab Issues, Jira, - Linear, or whichever tool project memory points at) with the filled - template body, requested labels, type, projects, and milestones. - -## Prerequisites - -- The project memory identifies the ticketing tool, or the remote URL - reveals it via `git remote get-url origin`. -- The matching CLI is authenticated (`gh`, `glab`, etc.) or the tool's API - credentials are configured. -- The user is available to approve the draft before the issue is filed; - the skill always waits for explicit confirmation. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action contract. Templates ship in -[`assets/`](assets/): `issue-template.md` (issue body) and `CONTRIBUTING.md` -(project-specific issue rules consulted before drafting). diff --git a/plugins/aidd-vcs/skills/04-issue-create/README.md b/plugins/aidd-vcs/skills/04-issue-create/README.md new file mode 120000 index 00000000..d69512cf --- /dev/null +++ b/plugins/aidd-vcs/skills/04-issue-create/README.md @@ -0,0 +1 @@ +SKILL.md \ No newline at end of file diff --git a/scripts/summarize-markdown.js b/scripts/summarize-markdown.js index e3aa25c9..4da930b4 100755 --- a/scripts/summarize-markdown.js +++ b/scripts/summarize-markdown.js @@ -168,6 +168,19 @@ function isScannableFile(filename) { ); } +function isDirectSkillReadmeSymlink(itemPath, relativePath, filename) { + if (filename !== "README.md") { + return false; + } + if (path.basename(path.dirname(path.dirname(itemPath))) !== "skills") { + return false; + } + if (relativePath.split(path.sep).length !== 1) { + return false; + } + return fs.lstatSync(itemPath).isSymbolicLink() && fs.readlinkSync(itemPath) === "SKILL.md"; +} + /** * Recursively scan a directory for markdown files up to a maximum depth * @param {string} dir - Directory to scan @@ -187,6 +200,9 @@ function scanDirectoryRecursive(dir, currentDepth, maxScanDepth, relativePath = for (const item of items) { const itemPath = path.join(dir, item); + if (isDirectSkillReadmeSymlink(itemPath, relativePath, item)) { + continue; + } const stat = fs.statSync(itemPath); if (stat.isFile() && isScannableFile(item) && !ignoreNames.has(item)) {