🇫🇷 The first French open-source framework for AI-driven development.
- 7 plugins · 41 skills · 2 agents · MIT + 7 plugins · 40 skills · 2 agents · MIT
[](LICENSE) @@ -189,7 +189,7 @@ Commits, pull / merge requests, release tags, issue creation. ### 📋 [aidd-pm](plugins/aidd-pm/README.md) -`5 skills` · stable +`4 skills` · stable Ticket info, user stories, PRD, spec drafting. diff --git a/UPGRADE.md b/UPGRADE.md index 509ece6e..941f0bf6 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -95,7 +95,7 @@ Invocation in v4 is `plugin:NN-action`. Where a column says "sub-flow", the old |---|---| | `/brainstorm` | `aidd-refine:01-brainstorm` | | `/challenge` | `aidd-refine:02-challenge` | -| `/create_user_stories` | `aidd-pm:02-user-stories-create` | +| `/create_user_stories` | `aidd-pm:02-user-stories` | | `/ticket_info` | `aidd-pm:01-ticket-info` | ### plan diff --git a/aidd_docs/README.md b/aidd_docs/README.md index 166a8e4d..d4de7c2a 100644 --- a/aidd_docs/README.md +++ b/aidd_docs/README.md @@ -38,7 +38,7 @@ Skills are grouped into plugins by domain. Install only the plugins you need. | ----------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------- | | aidd-context | Bootstrap, project init, generation of context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces), mermaid diagrams, learn, discovery | `02-project-memory`, `03-context-generate`, `09-mermaid` | | aidd-refine | Meta-cognition: brainstorm, challenge prior work, condensed communication mode | `01-brainstorm`, `02-challenge`, `03-condense` | -| aidd-pm | Product management: ticket info, user stories, PRD, spec | `01-ticket-info`, `02-user-stories-create`, `03-prd`, `04-spec` | +| aidd-pm | Product management: ticket info, user stories, PRD, spec | `01-ticket-info`, `02-user-stories`, `03-prd`, `04-spec` | | aidd-dev | Code transformation: Dev SDLC orchestrator, plan, implement, assert, audit, review, test, refactor, debug, for-sure | `00-sdlc`, `01-plan`, `02-implement`, `05-review`, `06-test` | | aidd-vcs | VCS workflows: commit, pull/merge request, release tag, issue creation | `01-commit`, `02-pull-request`, `04-issue-create` | | aidd-orchestrator | Async orchestration of the SDLC on labeled issues (optional, extra) | `00-async-dev` (router with setup / run / review sub-flows) | @@ -102,7 +102,7 @@ AIDD is delivered as a plugin marketplace. Pick what you need; do not install ev | aidd-refine | 01-brainstorm, 02-challenge, 03-condense, 04-shadow-areas, 05-fact-check | | aidd-dev | 00-sdlc, 01-plan, 02-implement, 03-assert, 04-audit, 05-review, 06-test, 07-refactor, 08-debug, 09-for-sure | | aidd-vcs | 01-commit, 02-pull-request, 03-release-tag, 04-issue-create | -| aidd-pm | 01-ticket-info, 02-user-stories-create, 03-prd, 04-spec | +| aidd-pm | 01-ticket-info, 02-user-stories, 03-prd, 04-spec | Each plugin is independently installable; install incrementally. Smaller surface, fewer triggers competing. @@ -112,7 +112,7 @@ A typical change cycles through skills from several plugins. The order below is 1. **Bootstrap** (only for a brand-new project): `aidd-context:01-bootstrap` imagines the stack and architecture, comparing candidate stacks and writing an `INSTALL.md`. Skip this step on an existing project. 2. **Project init** (once per project, re-runnable to refresh): `aidd-context:02-project-memory` scaffolds `aidd_docs/`, the memory bank, and the AI context files for the tools you use. Re-running later refreshes the scaffold without overwriting your customizations. -3. **Frame the request**: `aidd-refine:01-brainstorm` to clarify, `aidd-pm:01-ticket-info` to pull tracker data, `aidd-pm:02-user-stories-create` and `aidd-pm:03-prd` or `aidd-pm:04-spec` to formalize scope. +3. **Frame the request**: `aidd-refine:01-brainstorm` to clarify, `aidd-pm:01-ticket-info` to pull tracker data, `aidd-pm:02-user-stories` and `aidd-pm:03-prd` or `aidd-pm:04-spec` to formalize scope. 4. **Plan**: `aidd-dev:01-plan` produces the technical plan, component behavior model, or design-image extraction. 5. **Implement and assert**: `aidd-dev:02-implement` writes code against the plan; `aidd-dev:03-assert` verifies the result. 6. **Review**: `aidd-dev:05-review` for code and functional review; `aidd-refine:02-challenge` to stress-test the result. diff --git a/aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md b/aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md new file mode 100644 index 00000000..fb56ee00 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_29-memory-duplication-diagnosis.md @@ -0,0 +1,145 @@ +# Diagnostic — duplications mémoire (skill 02-project-memory) + +> Statut : diagnostic read-only. Aucun fichier de skill modifié. Ce doc = base de validation avant fix. + +## Contexte + +Retour Alex : la génération de mémoire produit des duplications, et Codex 5.5 +n'arrive pas à l'initialiser. Deux symptômes investigués séparément. + +## Symptôme A — Codex ne peut pas init (le `@`) + +**Vérifié, puis rétracté en partie.** + +- Le `@` n'est PAS le standard Agent Skills. Standard = chemin relatif depuis + la racine du skill (`reference/guide.md`, lien md `[x](x)`). Le `@` = import + CLAUDE.md. Source : docs Anthropic + agentskills.io. +- **`aidd framework build --target codex` CONVERTIT** `@../x` → un lien `x` vers `../x` + (lien md, `@` retiré). → Codex reçoit des chemins résolvables. OK. +- **`aidd plugin install
-audit_report:
-constraints:
- - keep input and output identical
- - keep code readable and maintainable
-```
-
-## Outputs
-
-```yaml
-hotspots_found:
-changes_applied:
- - { file: , change: , severity: "🔴|🟡|🟢", gain: }
-followups:
- -
- -
- -
-```
+## Input
-## Process
+The code region to optimize, a file path or inline snippet. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings.
+
+## Output
-1. **Source findings.** Two modes:
- - If `audit_report` is provided: extract the performance-axis findings from that report and use them as the fix list. Skip the standalone scan below.
- - Else (standalone): scan the selection for the main performance issues (allocations, redundant work, blocking calls, N+1 patterns, unnecessary I/O). Rate each hotspot with the 3-level severity scale: 🔴 critical, 🟡 warning, 🟢 minor.
-2. **List necessary steps** to address each hotspot, ordered by expected gain.
-3. **Apply changes.** Refactor the selected region. Preserve readability and maintainability; do not change logic; keep inputs and outputs identical.
-4. **Verify equivalence.** Confirm behavior is unchanged via tests, type checks, or a side-by-side run.
-5. **Propose three follow-up optimizations** not yet applied, sorted by importance.
+The hotspots addressed and the changes applied (file, one-line summary, severity, gain), plus three follow-up optimizations not yet applied.
+
+## Process
-Boundary note: test creation belongs to the test skill; dependency upgrades and UI redesign are out of scope for this action.
+1. **Source.** When an audit report is pushed, take its performance-axis findings as the fix list and skip the scan. Otherwise scan the selection for the main performance issues (allocations, redundant work, blocking calls, N+1 patterns, unnecessary I/O) and rate each with the shared severity scale.
+2. **Order.** List the steps to address each hotspot, ordered by expected gain.
+3. **Apply.** Refactor the selected region. Preserve readability and logic, keep inputs and outputs identical.
+4. **Verify.** Confirm behavior is unchanged via tests, type checks, or a side-by-side run.
+5. **Followup.** Propose three follow-up optimizations not yet applied, sorted by importance.
## Test
-Existing tests on the selection still pass; the public inputs and outputs of the refactored code are byte-identical to the pre-change version on representative inputs; the follow-up list contains exactly three actionable items.
+- Existing tests on the selection still pass.
+- The refactored code's public inputs and outputs are identical to the pre-change version on representative inputs.
+- The follow-up list contains exactly three actionable items.
diff --git a/plugins/aidd-dev/skills/07-refactor/actions/02-security.md b/plugins/aidd-dev/skills/07-refactor/actions/02-security.md
index a4d1f2c8..bf281d80 100644
--- a/plugins/aidd-dev/skills/07-refactor/actions/02-security.md
+++ b/plugins/aidd-dev/skills/07-refactor/actions/02-security.md
@@ -1,42 +1,27 @@
# 02 - Security
-Identify and fix security vulnerabilities, then strengthen the codebase by adding test coverage and documentation for the fixes. Security may change observable behavior to close a vulnerability - this is expected and must be called out explicitly.
+Find and fix security vulnerabilities, then add test coverage and documentation for the fixes. A security fix may change observable behavior to close a hole, which must be called out explicitly.
-## Inputs
+## Input
-```yaml
-scope: # optional; defaults to the entire codebase
-audit_report:
-focus_areas:
- - input_validation
- - authentication_authorization
- - injection
- - secrets_handling
-```
+An optional scope, a directory or file glob, defaulting to the entire codebase. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings.
-## Outputs
+## Output
-```yaml
-findings:
- - { id: , file: , severity: "🔴 critical | 🟡 warning | 🟢 minor", summary: }
-fixes_applied:
- - { id: , file: , change: , behavior_change: , test_added: true|false }
-```
+The vulnerabilities found and the fixes applied (file, one-line summary, whether behavior changed, whether a test was added).
## Process
-1. **Source findings.** Two modes:
- - If `audit_report` is provided: extract the security-axis findings from that report and use them as the fix list. Skip steps 2-4 below.
- - Else (standalone): scan the scope for vulnerabilities using static analysis where available and a manual pass against OWASP Top 10. Continue with steps 2-4.
-2. **Check input validation** at every external boundary (HTTP handlers, CLI args, file parsers, IPC).
-3. **Review authentication and authorization** paths; flag missing checks and broken role propagation.
-4. **Identify injection risks** (SQL, command, template, XSS, SSRF).
-5. **Apply fixes**, preferring secure functions, least privilege, and parameterized APIs over ad-hoc sanitization. If a fix changes observable behavior, set `behavior_change: true` and explain the change inline.
-6. **Add security test coverage** for each fix (regression unit or integration tests).
-7. **Document the security measures** added or changed (inline doc strings, ADRs, or `aidd_docs/memory/` entries) so they are not regressed by future refactors.
-
-Note: CVE dependency upgrades and version maintenance are out of scope for this action; they belong to dependency maintenance (a separate audit pillar). Route those findings there.
+1. **Source.** When an audit report is pushed, take its security-axis findings as the fix list and skip to Apply. Otherwise scan the scope with static analysis where available and a manual pass against the OWASP Top 10.
+2. **Inputs.** Check input validation at every external boundary (HTTP handlers, CLI args, file parsers, IPC).
+3. **Access.** Review authentication and authorization paths, flagging missing checks and broken role propagation.
+4. **Injection.** Identify injection risks (SQL, command, template, XSS, SSRF).
+5. **Apply.** Fix with secure functions, least privilege, and parameterized APIs over ad-hoc sanitization. When a fix changes observable behavior, mark it and explain the change inline.
+6. **Cover.** Add a regression test, unit or integration, for each fix.
+7. **Document.** Record the security measures added or changed (doc strings, ADRs, or `aidd_docs/memory/` entries) so a later refactor does not regress them.
## Test
-Every entry in `findings` has a matching entry in `fixes_applied` or a documented reason for deferral; every entry in `fixes_applied` with `test_added: true` has a regression test that fails on the pre-fix code; the project's security linter (when configured) exits zero on the changed scope.
+- Every finding has a matching fix or a documented reason for deferral.
+- Each fix with a test added has a regression test that fails on the pre-fix code.
+- The project's security linter, when configured, exits zero on the changed scope.
diff --git a/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md b/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md
index 3a4c4bd6..bb11c189 100644
--- a/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md
+++ b/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md
@@ -1,47 +1,35 @@
# 03 - Cleanup
-Improve code quality and reduce technical debt by applying clean-code principles and removing structural rot - without changing observable behavior.
+Improve code quality and reduce technical debt by applying clean-code principles and removing structural rot, without changing observable behavior.
-## Inputs
+## Input
-```yaml
-scope: # optional; defaults to the entire codebase
-audit_report:
-constraints:
- - keep public inputs and outputs identical
- - preserve existing test coverage
-```
+An optional scope, a directory or file glob, defaulting to the entire codebase. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings.
-## Outputs
+## Output
-```yaml
-changes_applied:
- - { file: , change: , severity: "🔴|🟡|🟢", category: }
-verification:
-```
+The changes applied (file, one-line summary, severity, clean-code or tech-debt), with a verification summary confirming no behavioral regression.
## Process
-1. **Source findings.** Two modes:
- - If `audit_report` is provided: extract the code-quality-axis findings from that report and use them as the fix list. Skip the standalone scan below.
- - Else (standalone): scan the scope with the cleanup lens below. Rate each issue with the 3-level severity scale: 🔴 critical, 🟡 warning, 🟢 minor.
-2. **Apply clean-code fixes** from the finding list:
+1. **Source.** When an audit report is pushed, take its code-quality-axis findings as the fix list and skip the scan. Otherwise scan the scope with the cleanup lens and rate each issue with the shared severity scale.
+2. **Clean.** Apply the clean-code fixes from the list:
- Rename symbols for clarity (misleading names, abbreviations, single-letter variables outside tight loops).
- Extract functions or modules where a block does more than one thing.
- - Deduplicate repeated logic (DRY).
+ - Deduplicate repeated logic.
- Raise abstraction to replace low-level mechanics with intention-revealing calls.
- Replace magic numbers and inline strings with named constants.
- - Remove dead, misleading, or out-of-date comments; add a brief comment only where intent is genuinely non-obvious.
-3. **Apply tech-debt fixes** from the finding list:
- - Delete dead code and unused exports, and sweep for the orphaned references a deletion leaves behind.
- - Reduce cyclomatic complexity by extracting early returns, guard clauses, and helper functions.
+ - Remove dead, misleading, or out-of-date comments, adding one only where intent is genuinely non-obvious.
+3. **Debt.** Apply the tech-debt fixes from the list:
+ - Delete dead code and unused exports, sweeping for the orphaned references a deletion leaves behind.
+ - Reduce cyclomatic complexity with early returns, guard clauses, and helper functions.
- Shorten oversized files and functions to a single responsibility.
- Flatten excessive nesting.
- - Fix error handling caught at the wrong boundary (swallowed errors, wrong abstraction level).
-4. **Verify behavior is preserved.** Run tests and type checks; confirm public inputs and outputs are identical to pre-change.
-
-Boundary note: test creation belongs to the test skill; dependency upgrades and UI redesign are out of scope for this action.
+ - Fix error handling caught at the wrong boundary.
+4. **Verify.** Run tests and type checks, confirming public inputs and outputs are identical to pre-change.
## Test
-All existing tests pass after changes; type checks exit zero; no public API surface has changed; each entry in `changes_applied` maps to a concrete line-level edit in the diff.
+- All existing tests pass and type checks exit zero.
+- No public API surface has changed.
+- Each change applied maps to a concrete line-level edit in the diff.
diff --git a/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md b/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md
index 44358ad0..2db707f1 100644
--- a/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md
+++ b/plugins/aidd-dev/skills/07-refactor/actions/04-architecture.md
@@ -1,44 +1,31 @@
# 04 - Architecture
-Enforce documented boundaries, fix wrong-direction dependencies, and decouple structural problems - in small, verifiable steps that preserve observable behavior where possible.
+Enforce documented boundaries, fix wrong-direction dependencies, and decouple structural problems, in small verifiable steps that preserve observable behavior where possible.
-## Inputs
+## Input
-```yaml
-scope: # optional; defaults to the entire codebase
-audit_report:
-constraints:
- - keep public inputs and outputs identical where structurally possible
- - proceed in small verified steps
-```
+An optional scope, a directory or file glob, defaulting to the entire codebase. Optionally a pushed audit report, a path under `aidd_docs/tasks/audits/` or pasted findings.
-## Outputs
+## Output
-```yaml
-changes_applied:
- - { file: , change: , severity: "🔴|🟡|🟢" }
-verification:
-deferred_to_plan:
- -
-```
+The changes applied (file, one-line summary, severity), a verification summary, and a deferred list of structural moves too large to execute atomically, each flagged as needing a plan first.
## Process
-1. **Source findings.** Two modes:
- - If `audit_report` is provided: extract the architecture-axis findings from that report and use them as the fix list. Skip the standalone scan below.
- - Else (standalone): scan the scope against documented boundaries (C4 diagrams or ADRs in `aidd_docs/memory/`). Identify wrong-direction dependencies, god-modules, missing layer abstractions, and violated isolation contracts. Rate each issue with the 3-level severity scale: 🔴 critical, 🟡 warning, 🟢 minor.
-2. **Triage findings.** Separate changes that are safe to apply atomically now from those that require broad coordinated moves. Place the latter in `deferred_to_plan`.
-3. **Apply changes** in small, independently verifiable steps:
+1. **Source.** When an audit report is pushed, take its architecture findings as the fix list and skip the scan. Otherwise scan against the documented boundaries (C4 diagrams, ADRs in `aidd_docs/memory/`) for wrong-direction dependencies, god-modules, missing layers, and broken isolation, rating each with the shared severity scale.
+2. **Triage.** Separate changes safe to apply atomically now from those needing broad coordinated moves. Defer the latter, flagged as needing a plan first.
+3. **Apply.** Make the safe changes in small, independently verifiable steps:
- Extract or restore layers (separate domain, infrastructure, and presentation concerns).
- - Fix wrong-direction dependency arrows (introduce an interface or inversion point; do not let infrastructure reach into domain).
+ - Fix wrong-direction dependencies by introducing an interface or inversion point, never letting infrastructure reach into the domain.
- Decouple god-modules by splitting responsibilities along natural seams.
- Enforce documented boundaries by moving code, adjusting exports, and updating internal references.
-4. **Verify after each step.** Run tests and type checks; confirm the import graph still respects documented boundaries; confirm public inputs and outputs are unchanged.
+4. **Verify.** After each step run tests and type checks, confirm the import graph still respects documented boundaries, and confirm public inputs and outputs are unchanged.
-CAUTION: a large architectural change often needs a plan before code moves. If `deferred_to_plan` is non-empty, recommend running the planning skill before proceeding with those items.
-
-Boundary note: dependency upgrades, test creation, and UI redesign are out of scope for this action.
+When the deferred list is non-empty, recommend planning those structural moves before any code moves.
## Test
-All existing tests pass after each applied step; type checks exit zero; the import graph has no new boundary violations; each entry in `changes_applied` maps to a concrete edit in the diff; `deferred_to_plan` is populated for any structural move not safe to execute atomically.
+- All existing tests pass after each applied step and type checks exit zero.
+- The import graph has no new boundary violations.
+- Each change applied maps to a concrete edit in the diff.
+- Any structural move not safe to execute atomically is in the deferred list.
diff --git a/plugins/aidd-dev/skills/08-debug/SKILL.md b/plugins/aidd-dev/skills/08-debug/SKILL.md
index 1c5a1f1d..e74d6591 100644
--- a/plugins/aidd-dev/skills/08-debug/SKILL.md
+++ b/plugins/aidd-dev/skills/08-debug/SKILL.md
@@ -1,34 +1,34 @@
---
name: 08-debug
-description: Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation.
+description: Reproduce and fix a known bug, or find an unknown root cause by hypothesis validation. Use when the user wants to fix a bug, find why something breaks, or reopen a stuck investigation. Not for building a feature or reviewing a diff.
argument-hint: reproduce | debug | reflect-issue
model: opus
---
# Skill: debug
-Diagnoses issues through structured hypothesis validation, root cause analysis, and test-driven bug fixing from issue creation to PR.
+Diagnose and fix issues through structured hypothesis validation, root-cause analysis, and a test-driven fix.
-## Available actions
+## Actions
| # | Action | When to use |
| --- | --------------- | ----------------------------------------------------------------------------- |
| 01 | `reproduce` | A known bug must be fixed end to end: reproduce, test-driven fix, branch, PR |
| 02 | `debug` | Root cause unknown: enumerate hypotheses, validate each, confirm the cause |
-| 03 | `reflect-issue` | Stuck or prior fixes failed: re-open the search space, instrument logs first |
+| 03 | `reflect-issue` | Stuck or prior fixes failed: reopen the search space, instrument logs first |
-## Routing (run first)
+Pick the one action matching the intent; never default to `01`. Triggers like "reproduce and fix" route to `01`, "why does this happen" to `02`, "I'm stuck" or "previous fixes didn't work" to `03`. Ask one question when the intent is ambiguous.
-This skill offers three distinct actions. Pick the ONE matching the user's intent; do NOT default to action 01.
+## Transversal rules
-- "fix this bug", "reproduce and fix", "from issue to PR" -> `01-reproduce`
-- "why does this happen", "find the root cause", "debug this", "what's causing X" -> `02-debug`
-- "I'm stuck", "previous fixes didn't work", "rethink the causes", "add logs to narrow it down" -> `03-reflect-issue`
+- One action per run: follow only the matching action file.
+- Scope each fix to its bug: never bundle drive-by refactors.
+- Confirm the root cause before fixing; the diagnostic actions stop at a confirmed cause.
-If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file.
+## Assets
-## Actions
+- `assets/task-template.md`: the per-hypothesis tracking file the debug action fills.
+
+## References
-- `@actions/01-reproduce.md`
-- `@actions/02-debug.md`
-- `@actions/03-reflect-issue.md`
+- `references/mermaid-conventions.md`: the project's Mermaid conventions for the action-path flowchart.
diff --git a/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md b/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md
index 808204cc..e11f12d5 100644
--- a/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md
+++ b/plugins/aidd-dev/skills/08-debug/actions/01-reproduce.md
@@ -1,36 +1,30 @@
# 01 - Reproduce
-Fix a bug systematically with a test-driven workflow that goes from issue creation to pull request, one bug per branch.
+Fix a bug with a test-driven workflow that goes from issue creation to pull request, one bug per branch.
-## Inputs
+## Input
-```yaml
-bug:
-```
+The bug, a free-form description or issue number, from the arguments.
-## Outputs
+## Output
-```yaml
-issue_id:
-branch:
-test_file:
-pr_url:
-status: opened
-```
+The opened pull request (its URL), the fix branch, the failing test added before the fix, and the tracker issue id it links.
## Process
-1. **Open the ticket.** Create a ticket in the configured ticketing tool with a short, descriptive title.
-2. **Create the fix branch** dedicated to this bug.
-3. **Reproduce the issue.** Confirm the symptom and capture the minimal trigger; pin down the root cause hypothesis.
-4. **Write a failing test** that demonstrates the bug.
-5. **Commit** the failing test, linking the issue id.
-6. **Implement the minimal fix.** Keep changes scoped to the bug; do not bundle drive-by refactors.
-7. **Verify.** Confirm the new test passes; run the full suite.
-8. **Commit** the fix, linking the issue id.
-9. **Review for scope creep.** If the diff drifted, split or revert; commit again as needed.
-10. **Push the branch** and create a PR linking the issue with `Fixes #`.
+1. **Ticket.** Create a ticket in the configured ticketing tool with a short, descriptive title.
+2. **Branch.** Create a fix branch dedicated to this bug.
+3. **Reproduce.** Confirm the symptom, capture the minimal trigger, and pin down the root-cause hypothesis.
+4. **Test.** Write a test that demonstrates the bug.
+5. **Commit.** Commit the failing test, linking the issue id.
+6. **Fix.** Implement the minimal fix, scoped to the bug.
+7. **Verify.** Confirm the new test passes, then run the full suite.
+8. **Commit.** Commit the fix, linking the issue id.
+9. **Scope.** Review for scope creep. When the diff drifted, split or revert and commit again.
+10. **Open.** Push the branch and open a PR linking the issue with `Fixes #`.
## Test
-A PR exists with the URL emitted in `pr_url`; its diff includes the failing test introduced in step 4 and the minimal fix from step 6; the PR description contains `Fixes #` referencing the ticket created in step 1; the full test suite passes on the head of the fix branch.
+- A PR exists at the reported URL, its diff carrying the failing test and the minimal fix.
+- The PR description references the ticket with `Fixes #`.
+- The full test suite passes on the head of the fix branch.
diff --git a/plugins/aidd-dev/skills/08-debug/actions/02-debug.md b/plugins/aidd-dev/skills/08-debug/actions/02-debug.md
index 4abe432a..30b011ce 100644
--- a/plugins/aidd-dev/skills/08-debug/actions/02-debug.md
+++ b/plugins/aidd-dev/skills/08-debug/actions/02-debug.md
@@ -1,38 +1,32 @@
# 02 - Debug
-Debug an issue in the codebase by enumerating hypotheses, validating each one, and arriving at a root cause that the user signs off on.
+Find the root cause of an issue by enumerating hypotheses, validating each, and arriving at a cause the user signs off on.
-## Inputs
+## Input
-```yaml
-issue:
-```
+The issue, a free-form description of the symptom or error.
-## Outputs
+## Output
-```yaml
-root_cause:
-hypotheses:
- - { id: 1, description: , confidence: 1-10, status: validated|invalidated, evidence: }
-flowchart_path:
-next_steps:
- -
-```
+A one-line root cause, the 3 to 5 hypotheses with their confidence and validated or invalidated status plus evidence, an action-path flowchart, and the next steps.
## Process
-1. **Summarize the issue** in your own words.
-2. **Map action paths** with a Mermaid flowchart (e.g. user clicks button -> calls function in file1 -> updates state in file2). Apply `@../references/mermaid-conventions.md`.
-3. **Apply 5 Whys.** Start from the symptom and ask "why" iteratively (minimum 3, up to 5). Document each level in a numbered list.
-4. **Identify inspection tools** (MCP, CLI commands, logs, traces).
-5. **Locate relevant files** in the codebase based on the issue.
-6. **List 3-5 potential causes** in a table with columns: Analysis, Evidence, Confidence (1-10).
-7. **Track hypotheses** using the project task system and `@../assets/task-template.md`. One task per hypothesis.
-8. **Validate one by one.** Tick each task when validated or invalidated. Add evidence inside the task. Stop when the root cause is found.
-9. **State conclusions and next steps.**
-10. **Wait for user validation** before moving on.
-11. **Fallback.** If all hypotheses are invalidated, invoke the `reflect_issue` action of this skill for new sources.
+1. **Summarize.** Restate the issue in your own words.
+2. **Map.** Draw the action paths as a Mermaid flowchart (a click calls a function in one file that updates state in another), per `@../references/mermaid-conventions.md`.
+3. **Whys.** Start from the symptom and ask "why" iteratively, three to five levels, each documented in a numbered list.
+4. **Tools.** Identify the inspection tools available (MCP, CLI commands, logs, traces).
+5. **Locate.** Find the relevant files in the codebase for the issue.
+6. **Causes.** List 3 to 5 potential causes in a table: analysis, evidence, confidence (1 to 10).
+7. **Track.** Record one task per hypothesis in the project task system, filling `@../assets/task-template.md`.
+8. **Validate.** Work the hypotheses one by one, ticking each as validated or invalidated with evidence in the task. Stop when the root cause is found.
+9. **Conclude.** State the conclusion and next steps.
+10. **Confirm.** Wait for user validation before moving on.
+11. **Fallback.** When every hypothesis is invalidated, hand off to the `reflect-issue` action for fresh sources.
## Test
-The hypotheses list contains 3-5 entries; every entry has a `validated` or `invalidated` status; if any is `validated`, its evidence is non-empty and `root_cause` is a one-line statement consistent with that evidence; if every hypothesis is `invalidated`, `next_steps` cites the `reflect_issue` action.
+- The hypotheses list has 3 to 5 entries, each with a validated or invalidated status.
+- A validated hypothesis has non-empty evidence and a one-line root cause consistent with it.
+- The output includes a Mermaid action-path flowchart and a confidence score per hypothesis.
+- When every hypothesis is invalidated, the next steps cite the `reflect-issue` action.
diff --git a/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md b/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md
index bbcf3138..85564f0f 100644
--- a/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md
+++ b/plugins/aidd-dev/skills/08-debug/actions/03-reflect-issue.md
@@ -1,32 +1,24 @@
# 03 - Reflect Issue
-Re-open the search space by reflecting on 5-7 fresh possible sources, distilling them down to the 1-2 most likely, and instrumenting the code with logs that will confirm or refute the picks before any fix.
+Reopen the search space: reflect on 5 to 7 fresh sources, distill to the 1 or 2 most likely, and instrument logs to confirm or refute them before any fix.
-## Inputs
+## Input
-```yaml
-issue:
-prior_hypotheses:
-```
+The issue carried over from the debug action, and optionally the hypotheses already invalidated.
-## Outputs
+## Output
-```yaml
-new_sources:
- - { id: , description: , rationale: }
-most_likely:
- - { id: , description: , confidence: 1-10 }
-logs_added:
- - { file: , location: , log_message: , purpose: }
-```
+The 5 to 7 fresh sources with their rationale, the 1 or 2 most likely with a confidence score, and the validation logs added (file, location, message, what each confirms or refutes).
## Process
-1. **List 5-7 fresh possible sources** of the problem, distinct from those already invalidated.
-2. **Distill to 1-2 most likely** sources based on consistency with the symptom, recent code changes, and confidence in available evidence.
-3. **Add validation logs.** Instrument the relevant code paths with logs that will confirm or refute each of the most-likely sources. Each log has a clear purpose; remove temporary logs after the root cause is found.
+1. **Broaden.** List 5 to 7 fresh possible sources, distinct from those already invalidated.
+2. **Distill.** Narrow to the 1 or 2 most likely, weighing consistency with the symptom, recent code changes, and available evidence.
+3. **Instrument.** Add logs on the relevant code paths that confirm or refute each likely source, each with a clear purpose. Remove the temporary logs once the root cause is found.
4. **Boundary.** Do not implement the fix yet. The goal is to confirm the source first.
## Test
-`new_sources` contains 5-7 entries; `most_likely` contains 1-2 entries selected from `new_sources` with a confidence score; `logs_added` is non-empty and every entry cites a real file path and a concrete `purpose` tied to one of the most-likely sources.
+- The fresh sources list has 5 to 7 entries.
+- The most-likely list has 1 or 2 entries drawn from them, each with a confidence score.
+- The logs added are non-empty, each citing a real file path and a concrete purpose tied to a most-likely source.
diff --git a/plugins/aidd-dev/skills/08-debug/assets/task-template.md b/plugins/aidd-dev/skills/08-debug/assets/task-template.md
index cdc9e1db..5f71ea95 100644
--- a/plugins/aidd-dev/skills/08-debug/assets/task-template.md
+++ b/plugins/aidd-dev/skills/08-debug/assets/task-template.md
@@ -7,7 +7,7 @@ description: Task tracking system to ensure all tasks are categorized and addres
{{Full description}}
-## Main step 1}
+## Main step 1
- [ ] {Task 1}
- [ ] {Task 2}
diff --git a/plugins/aidd-dev/skills/09-for-sure/SKILL.md b/plugins/aidd-dev/skills/09-for-sure/SKILL.md
index 989821e3..ba542107 100644
--- a/plugins/aidd-dev/skills/09-for-sure/SKILL.md
+++ b/plugins/aidd-dev/skills/09-for-sure/SKILL.md
@@ -1,50 +1,36 @@
---
name: 09-for-sure
-description: Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.
+description: Run an iterative agent loop that retries until a runnable success condition passes. Use when the user says "for sure", "keep trying until", or wants guaranteed completion against a success command. Not for one-shot tasks or uncheckable goals.
argument-hint: init-tracking | auto-accept | autonomous-loop
---
-# For Sure
+# Skill: for-sure
-Autonomous loop that runs until a success condition is verified. Two phases: interactive pre-flight (human present), then autonomous execution (human gone). The agent auto-accepts everything, acts as the user, and never stops until success.
+Run an autonomous loop until a success condition is verified. An interactive pre-flight (human present) sets it up, then autonomous execution (human gone) retries until success, acting as the user and never stopping early.
-## Context
-
-- **Goal**: Task's `success_condition` verified by running a command. All steps/acceptance criteria checked. `status` set to `implemented`.
-- **Tools required**: Agent tool (spawning iterations), Read/Write/Edit (tracking file), task-specific tools.
-- **Trigger**: Manual - `/for-sure`.
-- **Tracking file format**: Uses the local `plan-template.md` (`@assets/plan-template.md`). Filename: `aidd_docs/tasks/.md` (state lives in the `status` frontmatter field).
+## Actions
-## Environment
+| # | Action | Phase | Role |
+| --- | ----------------- | ---------------------- | -------------------------------------------------------------------------- |
+| 01 | `init-tracking` | interactive pre-flight | validate the goal, build the journey map, create the tracking file, spawn the loop |
+| 02 | `auto-accept` | autonomous | decide and act as the user, stopping only on money or destructive actions |
+| 03 | `autonomous-loop` | autonomous | spawn one worker per step, verify, retry, evaluate the success condition |
-None - task secrets are validated during pre-flight and documented in the tracking file.
+Run `01` interactively; it spawns `03`, which runs unattended under the `02` auto-accept rules until the success condition passes.
## Transversal rules
-1. **Single source of truth**: IF information about the task exists THEN it lives in `aidd_docs/tasks/.md` and nowhere else.
-2. **No repeated failures**: IF approach X failed THEN do not try X again without a meaningful change.
-3. **Honesty over escape**: IF success condition is not genuinely met THEN do not set `status: implemented`.
-4. **Auto-accept**: IF a decision, approval, or action is needed THEN act as the user. Create accounts, generate keys, approve prompts, install tools. Do not ask, do not hesitate, just do it.
-
-## Execution flow
-
-### Phase 1 - Interactive (human present)
+- Single source of truth: all task state lives in `aidd_docs/tasks/.md` and nowhere else.
+- No repeated failures: never retry a failed approach without a meaningful change.
+- Honesty over escape: never set `status: implemented` until the success condition genuinely passes.
+- Auto-accept: when a decision or approval is needed, act as the user (create accounts, generate keys, approve prompts, install tools), never asking. Stop only on a payment or a destructive action.
+- The loop spawns one worker agent per step and never does the work itself.
-1. `@actions/01-init-tracking.md` - Pre-flight, create tracking file, spawn first autonomous agent.
-
-### Phase 2 - Autonomous (human gone)
-
-2. `@actions/02-auto-accept.md` - Auto-accept mode activation (Phase 3).
-3. `@actions/03-autonomous-loop.md` - Orchestrator: spawns one worker per step, verifies, checks/retries, evaluates success.
-
-## Actions
+## Assets
-```markdown
-@actions/01-init-tracking.md
-@actions/02-auto-accept.md
-@actions/03-autonomous-loop.md
-```
+- `assets/plan-template.md`: the tracking file format (frontmatter, phases, acceptance criteria, Log).
+- `assets/autonomous-loop-worker-prompt.md`: the prompt the loop spawns each per-step worker with.
## References
-- `@assets/plan-template.md` - tracking file format (frontmatter, phases, acceptance criteria, Log)
+- `references/autonomous-loop-log-format.md`: the Log entry format the loop appends per attempt.
diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md b/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md
index 91c26034..371ff9e8 100644
--- a/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md
+++ b/plugins/aidd-dev/skills/09-for-sure/actions/01-init-tracking.md
@@ -1,53 +1,33 @@
# 01 - Init tracking
-Pre-flight, validate prerequisites, build a journey map, create the tracking file, and hand off to the autonomous loop. This is the last interactive step before the loop runs unattended.
+Validate prerequisites, build a journey map, create the tracking file, and hand off to the autonomous loop. The last interactive step before the loop runs unattended.
-## Inputs
+## Input
-```yaml
-task: # required
-description: # optional
-success_condition: # required; must exit 0 on success
-rules: # optional
-```
+The task name (required), an optional free-form description, a runnable success condition that exits 0 on success (required), and optional rules.
-## Outputs
+## Output
-```yaml
-tracking_file: aidd_docs/tasks/.md
-state: resumed | created
-preflight_blockers: [] # non-empty halts before spawn
-```
+The tracking file at `aidd_docs/tasks/.md`, marked created or resumed, with any pre-flight blocker halting before the spawn.
## Process
-### Resume flow (existing task)
-
-1. Check `aidd_docs/tasks/` for a file matching the task name, and read its frontmatter `status`:
- - `status: pending` or `in-progress` -> report status (iteration, steps remaining), then skip to step 10 to resume.
- - `status: implemented` -> report "Task already completed." Stop.
- - No file -> continue to step 2.
-
-### New task flow
-
-2. **Collect from user**: task name, description, success condition, rules.
-3. **Research approach.** Before planning steps, read the relevant documentation (README, official guides). Identify the recommended method; do not default to what you already know.
-4. **Validate goal.** Ask "could I execute this with zero ambiguity?" If NO -> ask the user to reformulate. Examples:
- - "Make the code better" -> reject. "What metric?"
- - "All tests pass after `npm test`" -> accept.
-5. **Validate success condition.** It must be a runnable command. Examples:
- - `npm test exits 0` -> valid.
- - "The code is clean" -> invalid -> push back to `eslint . exits 0`.
-6. **Pre-flight checklist.** For each step, list tools, secrets, API access, data, permissions. Markers:
- - `[✓]` already satisfied
- - `[~]` SOFT - the agent will self-serve (sign up, generate key, install tool)
- - `[!]` HARD - only the user can provide it (DB id, channel id, env var, owned API key)
- - Collect every `[!]` now. If any `[!]` remains unresolved, STOP - do not proceed to step 7.
-7. **Build the ASCII journey map.** Project the entire path with steps, dependencies, tools, blockers. Ask the user to confirm. Iterate until "does this map look correct? Anything missing?" returns confirmation.
-8. **Load the plan template** from `@../assets/plan-template.md`. Create `aidd_docs/tasks/` when missing.
-9. **Create `aidd_docs/tasks/.md`** using the plan template. Fill frontmatter (`objective`, `success_condition`, `iteration: 0`, `status: pending`), Phases with Tasks and Acceptance criteria (the steps), and include the journey map.
-10. **Spawn the autonomous loop.** Read the Orchestrator prompt from `@./03-autonomous-loop.md` and pass it to the Agent tool with `` filled in.
+1. **Resume.** Check `aidd_docs/tasks/` for a file matching the task name and read its frontmatter `status`.
+ - `pending` or `in-progress`: report the status (iteration, steps remaining), then skip to Spawn to resume.
+ - `implemented`: report "Task already completed" and stop.
+ - No file: continue to Collect.
+2. **Collect.** Gather the task name, description, success condition, and rules from the user.
+3. **Research.** Before planning steps, read the relevant documentation (README, official guides) and identify the recommended method. Do not default to what you already know.
+4. **Goal.** Ask "could I execute this with zero ambiguity?" When no, ask the user to reformulate. "Make the code better" is rejected ("what metric?"); "all tests pass after `npm test`" is accepted.
+5. **Condition.** It must be a runnable command. `npm test exits 0` is valid; "the code is clean" is invalid and is pushed back to `eslint . exits 0`.
+6. **Pre-flight.** For each step, list tools, secrets, API access, data, and permissions. Mark `[✓]` already satisfied, `[~]` soft (the agent self-serves), `[!]` hard (only the user can provide it). Collect every `[!]` now; when any stays unresolved, stop before the next step.
+7. **Map.** Project the whole path as an ASCII map of steps, dependencies, tools, and blockers. Ask the user to confirm and iterate until they do.
+8. **Scaffold.** Load `@../assets/plan-template.md`, creating `aidd_docs/tasks/` when missing.
+9. **Create.** Write `aidd_docs/tasks/.md` from the template. Fill the frontmatter (`objective`, `success_condition`, `iteration: 0`, `status: pending`), the phases with their tasks and acceptance criteria, and the journey map.
+10. **Spawn.** Read the orchestrator recipe from `@./03-autonomous-loop.md` and hand it to the Agent tool with `` filled in.
## Test
-After step 10: the file at `tracking_file` exists with frontmatter `status` (`pending` at creation), its `success_condition` field is a runnable command, the journey map is present, every `[!]` blocker has been resolved before spawn, and an autonomous agent has been launched.
+- The tracking file exists with frontmatter `status: pending` at creation.
+- Its `success_condition` is a runnable command and the journey map is present.
+- Every `[!]` blocker was resolved before the spawn, and an autonomous agent was launched.
diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md b/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md
index 72c800e1..ccdcb53d 100644
--- a/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md
+++ b/plugins/aidd-dev/skills/09-for-sure/actions/02-auto-accept.md
@@ -1,33 +1,28 @@
# 02 - Auto-accept
-Operate autonomously: do not ask for confirmation, decide and act, only stop on money or destructive actions.
+Operate autonomously: do not ask for confirmation, decide and act, and stop only on money or destructive actions.
-## Inputs
+## Input
-```yaml
-task:
-```
+The task to handle end-to-end, a free-form description.
-## Outputs
+## Output
-```yaml
-status: completed | stopped_payment | stopped_destructive | stopped_out_of_scope
-actions_taken:
- -
-stopped_reason:
-```
+An exit status, completed or one of stopped-payment, stopped-destructive, or stopped-out-of-scope, with the actions taken and a one-sentence reason when stopped.
## Process
-Apply these rules in order to every prompt, dialog, checkbox, Y/n, license screen, cookie banner, or confirmation encountered while handling the task.
+Apply these rules in order to every prompt, dialog, checkbox, Y/n, license screen, cookie banner, or confirmation met while handling the task.
-1. **Accept everything by default.** Acknowledge and move on.
-2. **Choose defaults.** When an installer offers options, pick the recommended or standard one.
-3. **Fix problems yourself.** When something fails (missing dependency, wrong version, config error), fix it and retry. Do not ask.
-4. **Stop only when it costs money.** When an action involves payment, subscription, or upgrade to a paid tier, stop and report.
-5. **Stop on destructive actions.** When an action deletes data, drops a database, removes files recursively, force-pushes, resets git history, or overwrites uncommitted work, stop and report.
-6. **Stay scoped.** When an instruction would lead outside the original task (unrelated tools, external signups, rabbit holes), skip it. Only do what the user asked for, nothing more.
+1. **Accept.** Accept everything by default, acknowledge, and move on.
+2. **Default.** When an installer offers options, pick the recommended or standard one.
+3. **Self-fix.** When something fails (missing dependency, wrong version, config error), fix it and retry. Do not ask.
+4. **Money.** Stop and report when an action involves payment, subscription, or an upgrade to a paid tier.
+5. **Destructive.** Stop and report when an action deletes data, drops a database, removes files recursively, force-pushes, resets git history, or overwrites uncommitted work.
+6. **Scope.** Skip anything leading outside the original task (unrelated tools, external signups, rabbit holes). Do only what the user asked.
## Test
-`status` matches the actual exit path: `completed` only when the task was carried out end-to-end with no money or destructive action gate hit; `stopped_payment` / `stopped_destructive` / `stopped_out_of_scope` are accompanied by a non-empty `stopped_reason`.
+- The status matches the actual exit path.
+- `completed` appears only when the task ran end-to-end with no money or destructive gate hit.
+- Each stopped status carries a non-empty reason.
diff --git a/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md b/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md
index dc296039..6778259c 100644
--- a/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md
+++ b/plugins/aidd-dev/skills/09-for-sure/actions/03-autonomous-loop.md
@@ -1,71 +1,29 @@
# 03 - Autonomous loop
-Orchestrates the loop. For each unchecked step: spawns a worker agent, verifies the result, checks the box or retries. One step = one agent = one log entry. The orchestrator never does the work itself.
+Orchestrate the loop: for each unchecked step spawn a worker, verify the result, then check the box or retry. One step is one agent is one log entry, and the orchestrator never does the work itself.
-## Inputs
+## Input
-```yaml
-tracking_file: aidd_docs/tasks/.md # produced by 01-init-tracking
-```
+The tracking file `aidd_docs/tasks/.md` produced by `01-init-tracking`. The loop runs with no human interaction, reading and writing through that file.
-## Outputs
+## Output
-```yaml
-iterations:
-steps_completed:
-log_entries:
-```
+The success condition verified and the plan's `status` set to `implemented`, with every step checked and one Log entry per attempt.
## Process
-The loop runs with no human interaction. Inputs and outputs are read from / written to the tracking file.
-
-1. **Read the entire file.** Frontmatter, journey map, steps, full Log.
-2. **Increment `iteration`** in frontmatter, and set `status: in-progress` if still `pending`.
-3. **Read the Log** to learn from prior attempts.
-4. **Find the next unchecked step.**
-5. **Spawn a worker agent** for that step with the Worker prompt template (below). Pass the step description and the relevant context (objective, rules, prior Log entries for this step).
-6. **Read the worker's result.**
-7. **Verify concretely.** Run a check command, read a file, test the output. Do not trust the worker's claim alone.
-8. **On verified ✓**: tick the step `[x]` and append a Log entry.
-9. **On not verified ✗**: append a Log entry with the failure reason; spawn another worker with the error context.
-10. **Move to the next unchecked step.** Loop from step 1.
-
-### After every step is checked
-
-11. **Run the success_condition command** and verify the result yourself.
-12. **On TRUE**: set `status: implemented` in the frontmatter and stop.
-13. **On FALSE**: add new steps to address the root cause and continue the loop.
-
-## Worker prompt template
-
-```text
-Execute this step. Auto-accept everything - act as the user, make every
-decision yourself (approve prompts, generate keys, install tools, click
-buttons). Do not ask for permission. Just do it.
-
-Signing in via existing accounts (Google Sign-in, GitHub OAuth, SSO) is NOT
-account creation - it uses the user's active browser session. Do it.
-
-STEP:
-CONTEXT:
-
-Report:
-- What you did (specific: commands, files, URLs).
-- The concrete result (paste output, screenshot, evidence).
-```
-
-## Log entry format
-
-One entry per step attempt:
-
-```text
-### # -
-> -
-= <✓|✗>
-->
-```
+1. **Read.** Read the entire file: frontmatter, journey map, steps, and full Log.
+2. **Mark.** Increment `iteration` in the frontmatter, setting `status: in-progress` when still `pending`.
+3. **Learn.** Read the Log to learn from prior attempts.
+4. **Next.** Find the next unchecked step.
+5. **Spawn.** Spawn a worker for that step with `@../assets/autonomous-loop-worker-prompt.md`, passing the step description and the relevant context (objective, rules, prior Log entries for the step).
+6. **Verify.** Read the worker's result, then verify concretely by running a check command, reading a file, or testing the output. Never trust the worker's claim alone.
+7. **Record.** Read the worker's outcome. When it stopped at a money or destructive gate, surface the reason to the user and stop the loop; never retry, which would re-trigger the action. On verified success, tick the step `[x]`. On a plain failure, spawn another worker with the error context. Append a Log entry per `@../references/autonomous-loop-log-format.md`.
+8. **Loop.** Move to the next unchecked step and repeat from Read.
+9. **Evaluate.** Once every step is checked, run the `success_condition` command and verify the result yourself. On success, set `status: implemented` and stop. On failure, add new steps addressing the root cause and continue the loop.
## Test
-Each step attempt has exactly one Log entry; every checked step (`[x]`) has a `= ✓` entry whose verification cites a concrete command or file; the loop only sets `status: implemented` after the `success_condition` command has been re-run and exits zero.
+- Each step attempt has exactly one Log entry.
+- Every checked step has a `= ✓` entry whose verification cites a concrete command or file.
+- `status: implemented` is set only after the `success_condition` command has been re-run and exits zero.
diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/autonomous-loop-worker-prompt.md b/plugins/aidd-dev/skills/09-for-sure/assets/autonomous-loop-worker-prompt.md
new file mode 100644
index 00000000..3e4a7e57
--- /dev/null
+++ b/plugins/aidd-dev/skills/09-for-sure/assets/autonomous-loop-worker-prompt.md
@@ -0,0 +1,21 @@
+
+
+Execute this step. Auto-accept everything, act as the user, and make every
+decision yourself (approve prompts, generate keys, install tools, click
+buttons). Do not ask for permission. Just do it.
+
+Signing in via an existing account (Google Sign-in, GitHub OAuth, SSO) is NOT
+account creation; it uses the user's active browser session. Do it.
+
+Stop and report instead, without proceeding, when an action would cost money (a
+payment, subscription, or paid upgrade) or is destructive (deletes data, drops a
+database, force-pushes, resets git history, removes files recursively, or
+overwrites uncommitted work). Stay inside the task; skip unrelated signups.
+
+STEP:
+CONTEXT:
+
+Report:
+- What you did, specifically: commands, files, URLs.
+- The concrete result: paste output, a screenshot, or evidence.
+- Whether you stopped at a money or destructive gate, and which.
diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md
index 83c22497..e5f274b2 100644
--- a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md
+++ b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md
@@ -1,7 +1,4 @@
---
-name: for-sure-tracking
-description: For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.
-argument-hint: N/A
objective: "{What must be true when done. One sentence.}"
success_condition: "{Runnable command that proves done. Example: 'npm test exits 0 AND coverage > 80%'}"
iteration: 0
diff --git a/plugins/aidd-dev/skills/09-for-sure/references/autonomous-loop-log-format.md b/plugins/aidd-dev/skills/09-for-sure/references/autonomous-loop-log-format.md
new file mode 100644
index 00000000..86e36a20
--- /dev/null
+++ b/plugins/aidd-dev/skills/09-for-sure/references/autonomous-loop-log-format.md
@@ -0,0 +1,15 @@
+# Autonomous loop: Log entry format
+
+The autonomous loop appends one entry to the tracking file's Log per step attempt, in this exact shape:
+
+```text
+### # -
+> -
+= <✓|✗>
+->
+```
+
+- `### #` numbers the attempt.
+- `>` records the worker's attempt.
+- `=` records the orchestrator's own verification (a command run or a file read), not the worker's claim.
+- `->` records the decision: the next step, or `RETRY` with the reason.
diff --git a/plugins/aidd-dev/skills/10-todo/SKILL.md b/plugins/aidd-dev/skills/10-todo/SKILL.md
index 51137ace..cf9e1e9b 100644
--- a/plugins/aidd-dev/skills/10-todo/SKILL.md
+++ b/plugins/aidd-dev/skills/10-todo/SKILL.md
@@ -1,6 +1,6 @@
---
name: 10-todo
-description: Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.
+description: Split the user prompt into independent todos and run one executor agent per todo in parallel, then report a minimal table. Use when the user says "todo" or asks to fan out a multi-part request into parallel implementations.
---
# Todo
@@ -10,5 +10,5 @@ Turn one prompt into N independent todos, implement them in parallel, report a t
## Actions
```markdown
-@actions/01-todo.md
+actions/01-todo.md
```
diff --git a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md
index 504a1140..222401dc 100644
--- a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md
+++ b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md
@@ -2,12 +2,10 @@
Categorize the user prompt into independent todos, implement each in parallel, report.
-## Inputs
-
+## Input
User's requirement.
-## Outputs
-
+## Output
```markdown
| Category | Launched | Output |
| -------- | -------- | ------ |
@@ -15,15 +13,15 @@ User's requirement.
## Process
-1. **Read.** Take `prompt` from `$ARGUMENTS`; if empty, ask the user.
-2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent, using template.
+1. **Read.** Take `prompt` from the arguments; if empty, ask the user.
+2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent.
3. **Launch.** Spawn one `executor` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order:
```markdown
- 1. Refine the todo first - discover at runtime a skill whose description covers refining or clarifying a request (never a hardcoded plugin name) and run it on the todo.
+ 1. Refine the todo first: run a non-interactive refine capability if one is available (discovered at runtime, never a hardcoded plugin name); otherwise restate the todo clearly and resolve obvious ambiguity inline. Never block on the user.
2. Implement the refined todo.
3. Return a one-line output summary.
```
-4. **Report.** Print exactly one table, nothing else:
+4. **Report.** Print exactly one table, nothing else.
## Test
diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md
index 16290f8f..404318d2 100644
--- a/plugins/aidd-orchestrator/CATALOG.md
+++ b/plugins/aidd-orchestrator/CATALOG.md
@@ -26,5 +26,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
|-------|------|---|
| `-` | [README.md](skills/00-async-dev/README.md) | - |
| `references` | [routing.md](skills/00-async-dev/references/routing.md) | - |
-| `-` | [SKILL.md](skills/00-async-dev/SKILL.md) | `Single entry point for the async-dev pipeline (setup, run, review). Hybrid router decides which sub-flow to execute from $ARGUMENTS keyword (`setup` / `run` / `review`), trigger source (label `to-implement` / `to-review`, comment `@claude /implement` / `/review`), repo state (workflow + config presence, PR linked to issue), or natural-language intent. Use when the user says "set up async dev", "run async dev on issue #N", "address review on PR #N", "/async-dev", "claude on issues", or when triggered by a webhook with the matching labels or comments. Do NOT use for plain status checks on the async pipeline or for SDLC orchestration unrelated to issue/PR automation.` |
+| `-` | [SKILL.md](skills/00-async-dev/SKILL.md) | `Drive the async-dev pipeline from one entry point: setup, run, or review. Use when the user wants to install async dev, run a ready issue, or address PR review comments, or on a webhook trigger. Not for plain status checks.` |
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/README.md b/plugins/aidd-orchestrator/skills/00-async-dev/README.md
index 14352618..32097d12 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/README.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/README.md
@@ -15,7 +15,7 @@ Single entry point for the async-dev pipeline. Hybrid router that picks one of t
- For plain status checks on the async pipeline (read labels / comments directly).
- For SDLC orchestration unrelated to issue / PR automation (use `aidd-dev:00-sdlc`).
-- From inside a sub-flow action — actions never re-enter the router.
+- From inside a sub-flow action, actions never re-enter the router.
## How to invoke
@@ -41,8 +41,7 @@ The router reads `$ARGUMENTS`, then trigger env, then repo state, then natural i
| Run | [`actions/run/01-poll-ready.md`](actions/run/01-poll-ready.md) | 6 actions, run once per ready issue |
| Review | [`actions/review/01-collect-comments.md`](actions/review/01-collect-comments.md) | 4 actions, looped on the PR until stop |
-## Outputs
-
+## Output
Each sub-flow defines its own outputs:
- **Setup**: workflow file, config file, scripts, labels, schedule routine id (if applicable).
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md
index d045bc2a..581cf338 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md
@@ -1,6 +1,6 @@
---
name: 00-async-dev
-description: Single entry point for the async-dev pipeline (setup, run, review). Hybrid router decides which sub-flow to execute from $ARGUMENTS keyword (`setup` / `run` / `review`), trigger source (label `to-implement` / `to-review`, comment `@claude /implement` / `/review`), repo state (workflow + config presence, PR linked to issue), or natural-language intent. Use when the user says "set up async dev", "run async dev on issue #N", "address review on PR #N", "/async-dev", "claude on issues", or when triggered by a webhook with the matching labels or comments. Do NOT use for plain status checks on the async pipeline or for SDLC orchestration unrelated to issue/PR automation.
+description: Drive the async-dev pipeline from one entry point: setup, run, or review. Use when the user wants to install async dev, run a ready issue, or address PR review comments, or on a webhook trigger. Not for plain status checks.
argument-hint: collect-comments | detect-stop | fix-iteration | finalize | poll-ready | resolve-deps | acquire-lock | check-sdlc | delegate-sdlc | write-audit | detect-context | ask-config | generate-workflow | generate-local-script | write-config | bootstrap-labels | install-user-scope-plugins | configure-remote-secrets | bootstrap-scheduling | commit-and-push | smoke-test
---
@@ -18,11 +18,11 @@ Single skill that drives the async development pipeline end to end. Three sub-fl
**You are the router until you commit to a sub-flow. Once committed, run that sub-flow's actions in order; do not jump back to routing mid-flow.**
-## Routing — hybrid contract
+## Routing: hybrid contract
Walk in order. First match wins.
-1. **`$ARGUMENTS` keyword override.** If `$ARGUMENTS` contains exactly `setup`, `run`, or `review` (case-insensitive, standalone token), route there immediately. This is the explicit override the CI workflow uses.
+1. **Argument override.** If the arguments contain exactly `setup`, `run`, or `review` (case-insensitive, standalone token), route there immediately. This is the explicit override the CI workflow uses.
2. **Trigger env.** When invoked from CI (`GITHUB_EVENT_NAME` set):
- Label payload `to-implement` → `run`.
- Label payload `to-review` → `review`.
@@ -43,7 +43,7 @@ Walk in order. First match wins.
**If repo state contradicts intent** (e.g. user says "run" but `.claude/aidd-orchestrator.json` is absent), surface the conflict before delegating; never silently switch.
-See `@references/routing.md` for the full decision tree, signal precedence, and edge cases.
+See `references/routing.md` for the full decision tree, signal precedence, and edge cases.
## Sub-flows
@@ -55,9 +55,9 @@ Sets up async-dev in a repo. Detects context, asks for runtime parameters, gener
| --- | --------------------------------- | --------------------------------------------------------------------------------------------- |
| 01 | `detect-context` | Identify repo, default branch, existing config, CI permissions |
| 02 | `ask-config` | Collect runtime parameters (mode, auth, labels, schedule, agents) |
-| 03 | `generate-workflow` | Emit `.github/workflows/aidd-async.yml` from `@assets/setup/workflow-template.yml` |
-| 04 | `generate-local-script` | Emit poll/daemon scripts (local mode only) from `@assets/setup/local-*-template.sh` |
-| 05 | `write-config` | Persist `.claude/aidd-orchestrator.json` from `@assets/setup/config-template.json` |
+| 03 | `generate-workflow` | Emit `.github/workflows/aidd-async.yml` from `assets/setup/workflow-template.yml` |
+| 04 | `generate-local-script` | Emit poll/daemon scripts (local mode only) from `assets/setup/local-*-template.sh` |
+| 05 | `write-config` | Persist `.claude/aidd-orchestrator.json` from `assets/setup/config-template.json` |
| 06 | `bootstrap-labels` | Create `to-implement` / `to-review` / `claude/*` labels via `gh` |
| 07 | `install-user-scope-plugins` | Install `aidd-orchestrator` + `aidd-dev` at user scope (local mode) |
| 08 | `configure-remote-secrets` | Sync `CLAUDE_CODE_OAUTH_TOKEN`, `AIDD_BOT_TOKEN`, etc. (remote mode) |
@@ -65,7 +65,7 @@ Sets up async-dev in a repo. Detects context, asks for runtime parameters, gener
| 10 | `commit-and-push` | Stage generated files, conventional-commit, push |
| 11 | `smoke-test` | Label a throwaway issue with `to-implement`; verify the pipeline reacts |
-Files: `@actions/setup/01-detect-context.md` ... `@actions/setup/11-smoke-test.md`.
+Files: `actions/setup/01-detect-context.md` ... `actions/setup/11-smoke-test.md`.
Default flow: `01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11`. Actions self-skip when their preconditions are not met (e.g. `07` skips in remote mode, `08` skips in local mode).
@@ -82,7 +82,7 @@ Executes one orchestration cycle on a fresh issue. Reads ready issues, resolves
| 05 | `delegate-sdlc` | Hand the issue to the SDLC capability; observe outcome |
| 06 | `write-audit` | Emit `run-result.json` for the workflow's post-job |
-Files: `@actions/run/01-poll-ready.md` ... `@actions/run/06-write-audit.md`.
+Files: `actions/run/01-poll-ready.md` ... `actions/run/06-write-audit.md`.
Default flow: `01 → 02 → 03 → 04 → 05 → 06`. One cycle per ready issue.
@@ -93,13 +93,13 @@ Closes the loop after a PR is opened by the run flow. Detects when to keep auto-
| # | Action | Role |
| --- | -------------------- | ------------------------------------------------------------------------------------------ |
| 01 | `collect-comments` | Read all PR + linked-issue comments newer than the last bot activity |
-| 02 | `detect-stop` | Decide stop vs continue using `@references/review/stop-conditions.md` |
+| 02 | `detect-stop` | Decide stop vs continue using `references/review/stop-conditions.md` |
| 03 | `fix-iteration` | Delegate fixes to the SDLC capability; reply to each addressed comment |
| 04 | `finalize` | Resolve threads, post the structured summary, set `claude/awaiting-review` or `blocked` |
-Files: `@actions/review/01-collect-comments.md` ... `@actions/review/04-finalize.md`.
+Files: `actions/review/01-collect-comments.md` ... `actions/review/04-finalize.md`.
-Default flow: `01 → 02 → (03 → 01 loop if continue) → 04`. Stop conditions in `@references/review/stop-conditions.md`.
+Default flow: `01 → 02 → (03 → 01 loop if continue) → 04`. Stop conditions in `references/review/stop-conditions.md`.
## Rules
@@ -111,20 +111,20 @@ Default flow: `01 → 02 → (03 → 01 loop if continue) → 04`. Stop conditio
## References
-- `@references/routing.md` - full decision tree, signal precedence, conflict resolution.
-- `@references/setup/auth-modes.md` - local vs remote auth contracts.
-- `@references/setup/claude-action-auth.md` - `claude-code-action` token setup.
-- `@references/setup/local-mode-scheduling.md` - poll routine options.
-- `@references/review/stop-conditions.md` - when the review loop hands off to a human.
+- `references/routing.md` - full decision tree, signal precedence, conflict resolution.
+- `references/setup/auth-modes.md` - local vs remote auth contracts.
+- `references/setup/claude-action-auth.md` - `claude-code-action` token setup.
+- `references/setup/local-mode-scheduling.md` - poll routine options.
+- `references/review/stop-conditions.md` - when the review loop hands off to a human.
## Assets
Setup-only templates copied into the target repo by the setup sub-flow:
-- `@assets/setup/workflow-template.yml` - `.github/workflows/aidd-async.yml` skeleton.
-- `@assets/setup/local-poll-template.sh` - local-mode poll script.
-- `@assets/setup/local-daemon-template.sh` - local-mode daemon script.
-- `@assets/setup/config-template.json` - `.claude/aidd-orchestrator.json` skeleton.
+- `assets/setup/workflow-template.yml` - `.github/workflows/aidd-async.yml` skeleton.
+- `assets/setup/local-poll-template.sh` - local-mode poll script.
+- `assets/setup/local-daemon-template.sh` - local-mode daemon script.
+- `assets/setup/config-template.json` - `.claude/aidd-orchestrator.json` skeleton.
## Test
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md
index 11922a9c..1a02d94a 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/01-collect-comments.md
@@ -2,16 +2,14 @@
Pulls new review comments since the last iteration and acknowledges the loop has started.
-## Inputs
-
+## Input
- `pr_number` (required) -- integer, target PR
- `trigger_comment_id` (optional) -- id of the comment that triggered the loop; receives an `eyes` reaction
- `trigger_comment_url` (optional) -- full URL of the triggering comment; lets the loop reply in the thread that fired the trigger
- `source_issue_number` (optional) -- issue number when the trigger was a comment on the linked issue (not the PR itself); enables fetching that thread alongside PR comments
- `since` (optional) -- ISO 8601 timestamp; defaults to the timestamp of the last iteration recorded in the audit record
-## Outputs
-
+## Output
```json
{
"pr_number": 117,
@@ -23,7 +21,7 @@ Pulls new review comments since the last iteration and acknowledges the loop has
}
```
-Each entry carries a `source` of `pr_review` (inline review thread), `pr_conversation` (top-level PR comment), or `issue` (comment on the linked issue). Issue comments have no `path`/`line` — Claude treats them as plain user direction.
+Each entry carries a `source` of `pr_review` (inline review thread), `pr_conversation` (top-level PR comment), or `issue` (comment on the linked issue). Issue comments have no `path`/`line`, Claude treats them as plain user direction.
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md
index 4629db12..96c26be0 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/02-detect-stop.md
@@ -2,14 +2,12 @@
Decides whether to keep iterating or hand control to a human.
-## Inputs
-
+## Input
- `collect_output` (required) -- output of `01-collect-comments`
- `config` (required) -- parsed `.claude/aidd-orchestrator.json`
- `issue_labels` (required) -- current labels on the linked issue
-## Outputs
-
+## Output
```json
{
"decision": "stop",
@@ -20,9 +18,6 @@ Decides whether to keep iterating or hand control to a human.
`decision` is `"stop"` or `"continue"`. `reason` is one of `max_iterations`, `blocked_label`, `human_reviewer`, or `null`.
-## Depends on
-
-- `01-collect-comments`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md
index fc10c1ac..4c49dc41 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/03-fix-iteration.md
@@ -2,15 +2,13 @@
Delegates one round of fixes to the SDLC capability discovered at runtime and pushes a new commit on the PR branch.
-## Inputs
-
+## Input
- `collect_output` (required) -- output of `01-collect-comments`
- `pr_number` (required) -- integer
- `discovered_skill` (required) -- skill name discovered by the same heuristic used in `02-run`
- `trigger_comment_id` (optional) -- id of the comment that triggered the loop (e.g. `@claude /review`); used to add a reaction
-## Outputs
-
+## Output
```json
{
"iteration": 2,
@@ -21,9 +19,6 @@ Delegates one round of fixes to the SDLC capability discovered at runtime and pu
}
```
-## Depends on
-
-- `02-detect-stop` (only when its `decision == "continue"`)
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md
index 10e17ccc..572e24e9 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/review/04-finalize.md
@@ -2,16 +2,14 @@
Emit a `run-result.json` artifact summarising the review loop's stop decision and iteration log. The workflow's post-job (CI YAML) reads this file and performs the lifecycle effects: append to the audit log, finalize the Check Run, post the summary comment, transition issue labels, post the completion marker.
-## Inputs
-
+## Input
- `pr_number`
- `stop_reason` -- one of `max_iterations`, `blocked_label`, `human_reviewer`, `no_comments`
- `iteration_log` -- entries from `03-fix-iteration`; may be empty when `stop_reason = "no_comments"`
- `trigger_comment_id` (optional)
- `run_id`
-## Outputs
-
+## Output
A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable):
```json
@@ -30,9 +28,6 @@ A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable):
}
```
-## Depends on
-
-- `02-detect-stop` (when `decision = "stop"`)
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md
index 9945379f..2a76392e 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/01-poll-ready.md
@@ -2,14 +2,12 @@
Lists candidate issues that the pipeline should process.
-## Inputs
-
+## Input
- `config` (required) -- parsed `.claude/aidd-orchestrator.json`
- `trigger_event` (optional) -- one of `label`, `mention`, `cron`. Defaults to `cron`
- `issue_hint` (optional) -- a specific issue number from the trigger event
-## Outputs
-
+## Output
```json
{
"candidates": [
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md
index d0ec3b86..7975d3ea 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/02-resolve-deps.md
@@ -2,13 +2,11 @@
Filters out blocked issues by checking three dependency sources in order.
-## Inputs
-
+## Input
- `candidates` (required) -- output of `01-poll-ready`
- `config` (required) -- parsed `.claude/aidd-orchestrator.json`
-## Outputs
-
+## Output
```json
{
"ready": [{ "number": 42, "title": "..." }],
@@ -18,9 +16,6 @@ Filters out blocked issues by checking three dependency sources in order.
}
```
-## Depends on
-
-- `01-poll-ready`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md
index e2ec40b1..e27a7415 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/03-acquire-lock.md
@@ -2,13 +2,11 @@
Marks an issue as in-progress so concurrent triggers do not double-run.
-## Inputs
-
+## Input
- `issue` (required) -- one entry from `ready` (output of `02-resolve-deps`)
- `config` (required) -- parsed `.claude/aidd-orchestrator.json`
-## Outputs
-
+## Output
```json
{
"issue_number": 42,
@@ -17,9 +15,6 @@ Marks an issue as in-progress so concurrent triggers do not double-run.
}
```
-## Depends on
-
-- `02-resolve-deps`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md
index ae105923..4de58a3e 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/04-check-sdlc.md
@@ -2,12 +2,10 @@
Discovers an active SDLC orchestration capability in the runtime before delegation.
-## Inputs
-
+## Input
- none (reads runtime skill catalog)
-## Outputs
-
+## Output
```json
{
"sdlc_available": true,
@@ -16,9 +14,6 @@ Discovers an active SDLC orchestration capability in the runtime before delegati
}
```
-## Depends on
-
-- `03-acquire-lock`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md
index 0be3d50f..a43fef34 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/05-delegate-sdlc.md
@@ -1,9 +1,8 @@
# 05 -- Delegate SDLC
-Invoke the SDLC capability with the issue request, then verify the outcome by observing the real state of git and the VCS host — never by parsing the SDLC's return shape.
-
-## Inputs
+Invoke the SDLC capability with the issue request, then verify the outcome by observing the real state of git and the VCS host, never by parsing the SDLC's return shape.
+## Input
- `issue` -- the locked issue object
- `run_id` -- identifier from `03-acquire-lock`
- `discovered_skill` -- skill name from `04-check-sdlc`
@@ -11,8 +10,7 @@ Invoke the SDLC capability with the issue request, then verify the outcome by ob
- `trigger_kind` (optional) -- `label` or `comment`
- `trigger_comment_url` (optional) -- when `trigger_kind = comment`
-## Outputs
-
+## Output
```json
{
"default_before": "",
@@ -30,9 +28,6 @@ Invoke the SDLC capability with the issue request, then verify the outcome by ob
Every field is the result of an observation against git or the VCS host. None is parsed from the SDLC's return text.
-## Depends on
-
-- `04-check-sdlc`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md
index 1891f58f..835cc80c 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/run/06-write-audit.md
@@ -1,15 +1,13 @@
# 06 -- Write Run Result
-Emit a single `run-result.json` artifact summarising the observation from `05-delegate-sdlc`. The workflow's post-job (CI YAML) reads this file and performs the lifecycle effects: persist the audit log, finalize the Check Run, transition issue labels, post the completion marker. Splitting those side effects out of the agent keeps them deterministic — the agent only needs to write a file.
-
-## Inputs
+Emit a single `run-result.json` artifact summarising the observation from `05-delegate-sdlc`. The workflow's post-job (CI YAML) reads this file and performs the lifecycle effects: persist the audit log, finalize the Check Run, transition issue labels, post the completion marker. Splitting those side effects out of the agent keeps them deterministic, the agent only needs to write a file.
+## Input
- `delegate_output` -- structured result from `05-delegate-sdlc`
- `run_record` -- merged data from `03-acquire-lock` and `05-delegate-sdlc`
- `config` -- parsed `.claude/aidd-orchestrator.json`
-## Outputs
-
+## Output
A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable):
```json
@@ -32,9 +30,6 @@ A single file at `$RUNNER_TEMP/run-result.json` (workflow-readable):
}
```
-## Depends on
-
-- `05-delegate-sdlc`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md
index 5e5d3e89..e4af1133 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/01-detect-context.md
@@ -2,12 +2,10 @@
Inspects the current repo and the active runtime to confirm preconditions.
-## Inputs
-
+## Input
- `cwd` (required) -- string, absolute path of the target repo
-## Outputs
-
+## Output
```json
{
"repo_root": "/abs/path",
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md
index aa1532b1..76c3eb70 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/02-ask-config.md
@@ -2,12 +2,10 @@
Interactively collects the small set of runtime parameters from the user.
-## Inputs
-
+## Input
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
```json
{
"mode": "both",
@@ -45,9 +43,6 @@ Interactively collects the small set of runtime parameters from the user.
}
```
-## Depends on
-
-- `01-detect-context`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md
index 930fd954..aa1ad101 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/03-generate-workflow.md
@@ -2,23 +2,18 @@
Renders the GitHub Actions workflow that triggers the async pipeline.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
A file at `.github/workflows/aidd-async.yml`.
-## Depends on
-
-- `02-ask-config`
## Process
1. Skip this action when `answers.mode == "local"`.
-2. Read `assets/workflow-template.yml`.
+2. Read `assets/setup/workflow-template.yml`.
3. Substitute placeholders:
- `__TO_IMPLEMENT_LABEL__` -> `answers.labels.to_implement`
- `__TO_REVIEW_LABEL__` -> `answers.labels.to_review`
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md
index cf08f212..73b28e2b 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/04-generate-local-script.md
@@ -2,23 +2,18 @@
Renders the local poll script. The script wraps `claude -p` invocations of the run and review skills.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
A file at `scripts/aidd-async-poll.sh` with mode `0755`.
-## Depends on
-
-- `02-ask-config`
## Process
1. Skip this action when `answers.mode == "remote"`.
-2. Read `assets/local-poll-template.sh`.
+2. Read `assets/setup/local-poll-template.sh`.
3. Substitute placeholders:
- `__TO_IMPLEMENT_LABEL__` -> `answers.labels.to_implement`
- `__TO_REVIEW_LABEL__` -> `answers.labels.to_review`
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md
index 10741a8c..d59ef2ba 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/05-write-config.md
@@ -2,21 +2,16 @@
Persists the plugin configuration to the repo.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
-## Outputs
-
+## Output
A file at `.claude/aidd-orchestrator.json`.
-## Depends on
-
-- `02-ask-config`
## Process
-1. Read `assets/config-template.json`.
+1. Read `assets/setup/config-template.json`.
2. Merge `answers` into the template, preserving template defaults for fields the user did not override.
3. Add a top-level `version` (the plugin version) and an ISO 8601 `created_at` timestamp.
4. If `.claude/aidd-orchestrator.json` already exists, diff against the new config and ask the user to confirm overwrite.
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md
index 287ad817..fb81caf5 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/06-bootstrap-labels.md
@@ -2,12 +2,10 @@
Creates the 5 lifecycle labels declared in the config if they do not already exist on the repo.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
-## Outputs
-
+## Output
```json
{
"created": ["to-implement", "claude/working"],
@@ -15,9 +13,6 @@ Creates the 5 lifecycle labels declared in the config if they do not already exi
}
```
-## Depends on
-
-- `04-write-config`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md
index 2310320a..4a97e57a 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/07-install-user-scope-plugins.md
@@ -2,13 +2,11 @@
Installs the orchestrator plugin and an SDLC-providing plugin at user scope so the local poll script can invoke them via `claude -p` from any cwd. Skips entirely when the plugins are already loaded (project scope or user scope).
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
```json
{
"skipped": true,
@@ -22,9 +20,6 @@ Installs the orchestrator plugin and an SDLC-providing plugin at user scope so t
When `skipped == false`, the response contains `marketplace_added` and `plugins_installed` instead of `found_at`.
-## Depends on
-
-- `06-bootstrap-labels`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md
index c333f566..a382643d 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/08-configure-remote-secrets.md
@@ -2,13 +2,11 @@
Walks the user through adding the GitHub Action secrets the workflow needs. For each required secret, prints inline a short "what / why / how" block with two or three concrete ways to generate the value, then reads the value from stdin and stores it via `gh secret set`.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
```json
{
"secrets_set": ["CLAUDE_CODE_OAUTH_TOKEN"],
@@ -16,9 +14,6 @@ Walks the user through adding the GitHub Action secrets the workflow needs. For
}
```
-## Depends on
-
-- `06-bootstrap-labels`
## Process
@@ -66,7 +61,7 @@ Paste the key when prompted.
Used by the GitHub Action to clone the marketplace repository so plugins can install at runtime. Read-only is enough.
Three ways to obtain:
-- **A. Fine-grained PAT (recommended)**: `https://github.com/settings/personal-access-tokens/new`. Resource owner = the marketplace repo's owner. Repository access = "Only select repositories" -> the marketplace repo. Permissions = `Repository -> Contents: Read-only`. Expiration: 90 days minimum (set a calendar reminder to rotate).
+- **A. Fine-grained PAT (recommended)**: `https://github.com/settings/personal-access-tokens/new`. Resource owner = the marketplace repo's owner. Repository access = "Only select repositories" → the marketplace repo. Permissions = `Repository -> Contents: Read-only`. Expiration: 90 days minimum (set a calendar reminder to rotate).
- **B. Classic PAT (fallback)**: `https://github.com/settings/tokens/new`. Scope = `repo` (read). Less granular; rotate every 90 days.
- **C. GitHub App installation token**: install a dedicated GitHub App on the org with "Contents: Read" on the marketplace repo. Mint short-lived tokens via the App's private key (rotates automatically). Heaviest setup, best for org compliance.
@@ -80,7 +75,7 @@ How to obtain (recommended):
- `https://github.com/settings/personal-access-tokens/new`
- **Resource owner**: the target repo's owner.
-- **Repository access**: "Only select repositories" -> the target repo.
+- **Repository access**: "Only select repositories" → the target repo.
- **Repository permissions** (all under "Repository permissions"):
- `Contents`: Read and Write
- `Pull requests`: Read and Write
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md
index 7f659f5e..d4f9b1f1 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/09-bootstrap-scheduling.md
@@ -2,13 +2,11 @@
Schedules `scripts/aidd-async-poll.sh` via the cheapest path that fits the user's needs. **Never recommends OS-level cron**, but for the local daemon path uses tmux/launchd/systemd so the user keeps Claude Code's Tasks quota for other things.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
```json
{
"path": "local_daemon",
@@ -20,9 +18,6 @@ Schedules `scripts/aidd-async-poll.sh` via the cheapest path that fits the user'
`path` is one of: `manual`, `local_daemon`, `desktop_task_pending`, `schedule_routine`.
-## Depends on
-
-- `04-generate-local-script`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md
index c43a9558..8dd50afe 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/10-commit-and-push.md
@@ -2,12 +2,10 @@
Stages every file generated by previous actions, asks the user for explicit confirmation, then commits and pushes the branch.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
-## Outputs
-
+## Output
```json
{
"committed": true,
@@ -17,9 +15,6 @@ Stages every file generated by previous actions, asks the user for explicit conf
}
```
-## Depends on
-
-- `09-bootstrap-scheduling`
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md
index b216f61b..46a22882 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/actions/setup/11-smoke-test.md
@@ -2,13 +2,11 @@
Triggers the pipeline once on a self-contained throwaway issue (created by this action) so the user sees the full setup work end-to-end before walking away. Never touches the user's real backlog.
-## Inputs
-
+## Input
- `answers` (required) -- config object from `02-ask-config`
- `detection` (required) -- detection report from `01-detect-context`
-## Outputs
-
+## Output
```json
{
"smoke_issue_number": 999,
@@ -20,10 +18,6 @@ Triggers the pipeline once on a self-contained throwaway issue (created by this
`run_outcome` is `pr_opened`, `blocked`, or `skipped`.
-## Depends on
-
-- `10-commit-and-push` (when `answers.mode != "local"`)
-- `09-bootstrap-scheduling` (when `answers.mode != "remote"`)
## Process
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md b/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md
index bd1013cb..c097d88c 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/references/review/stop-conditions.md
@@ -21,10 +21,10 @@ The human-reviewer stop **only fires from iteration 2 onwards**. On iteration 1,
From iteration 2 onwards, if any new comment authored since the previous iteration started is from a non-bot user, the loop stops with `reason = human_reviewer`. The Check Run conclusion is `success` if the last iteration's tests passed, else `neutral`.
Detection rules for "non-bot":
-- `author.type == "Bot"` from the GitHub API -> bot
-- author login ends with `[bot]` -> bot
-- author login is in `config.bot_allowlist` (optional) -> bot
-- otherwise -> human
+- `author.type == "Bot"` from the GitHub API → bot
+- author login ends with `[bot]` → bot
+- author login is in `config.bot_allowlist` (optional) → bot
+- otherwise → human
Use case: a reviewer wrote feedback during the loop. Claude must not loop on top of human input. The next pass requires an explicit re-trigger.
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md b/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md
index d6ec5573..2e4c86bd 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/references/routing.md
@@ -1,12 +1,12 @@
-# Routing — decision tree
+# Routing: decision tree
Full contract for picking a sub-flow inside `aidd-orchestrator:00-async-dev`. The router walks these signals in order; the first match wins.
---
-## 1. Explicit override — `$ARGUMENTS` keyword
+## 1. Explicit override: the arguments keyword
-If `$ARGUMENTS` contains exactly `setup`, `run`, or `review` as a standalone case-insensitive token, route there immediately. No fallback consideration.
+If the arguments contain exactly `setup`, `run`, or `review` as a standalone case-insensitive token, route there immediately. No fallback consideration.
This is the contract the bundled CI workflow relies on:
@@ -15,7 +15,7 @@ prompt: "Use skill aidd-orchestrator:00-async-dev with action=run on issue #..."
prompt: "Use skill aidd-orchestrator:00-async-dev with action=review on PR #..."
```
-The router parses `action=` from the prompt body. Plain `setup` / `run` / `review` words elsewhere in the body do NOT match — only the explicit `action=` form, or `$ARGUMENTS` set to exactly one of the three keywords.
+The router parses `action=` from the prompt body. Plain `setup` / `run` / `review` words elsewhere in the body do NOT match, only the explicit `action=` form, or the arguments set to exactly one of the three keywords.
---
@@ -62,17 +62,17 @@ Last-resort heuristic for free-form user input.
---
-## Tie-break — most-specific signal wins
+## Tie-break: most-specific signal wins
When multiple signals match across categories:
```text
-$ARGUMENTS keyword (1) > trigger env (2) > repo state (3) > NL intent (4)
+Arguments keyword (1) > trigger env (2) > repo state (3) > NL intent (4)
```
Within a category, the most specific concrete signal wins:
-- A PR number in `$ARGUMENTS` beats a label payload.
+- A PR number in the arguments beats a label payload.
- A label beats a free-text keyword.
- A specific config file presence beats a generic verb.
@@ -87,21 +87,21 @@ Examples:
- **User says "run" but config is absent.**
Surface the conflict and stop: `Setup must complete before run. Run /aidd-orchestrator:00-async-dev with action=setup first.`
- **Workflow webhook fires `to-implement` but the issue already has an open closing PR.**
- Route to `review` (the PR is the active surface). Comment on the issue: `Issue #N has open PR #M — routed to review instead of run. Apply the `to-review` label to PR #M to trigger review explicitly.`
+ Route to `review` (the PR is the active surface). Comment on the issue: `Issue #N has open PR #M, routed to review instead of run. Apply the `to-review` label to PR #M to trigger review explicitly.`
- **Label `to-implement` AND label `to-review` both present.**
Route to `review` (more specific to the PR lifecycle). Comment to clarify.
---
-## Unresolved — ask the human
+## Unresolved: ask the human
If none of the above produces a single match, surface the three sub-flows with their triggers and ask:
```text
Async-dev: which sub-flow?
- - setup — install / configure async-dev in this repo
- - run — implement a ready issue (labeled to-implement)
- - review — iterate on review comments for an open PR
+ - setup , install / configure async-dev in this repo
+ - run , implement a ready issue (labeled to-implement)
+ - review , iterate on review comments for an open PR
Reply with `setup`, `run`, or `review`.
```
diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md b/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md
index 80b13652..707a0b1f 100644
--- a/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md
+++ b/plugins/aidd-orchestrator/skills/00-async-dev/references/setup/local-mode-scheduling.md
@@ -92,7 +92,7 @@ The daemon is fully decoupled from Claude Code's Tasks system; cancel it by kill
Convenient when the backlog is small and you want everything inside Claude Code. **Counts against your Tasks quota; one tick = one task slot consumed**, so a 5-minute cadence may exhaust a daily/weekly limit faster than you expect.
-1. Open Claude Code Desktop -> Scheduled tasks -> New task.
+1. Open Claude Code Desktop → Scheduled tasks → New task.
2. Working directory: the absolute path of this repo.
3. Schedule: choose a cadence; remember the quota.
4. Prompt: `Run ./scripts/aidd-async-poll.sh and report what was processed.`
diff --git a/plugins/aidd-pm/.claude-plugin/plugin.json b/plugins/aidd-pm/.claude-plugin/plugin.json
index 85d082b9..3a7b6f51 100644
--- a/plugins/aidd-pm/.claude-plugin/plugin.json
+++ b/plugins/aidd-pm/.claude-plugin/plugin.json
@@ -2,14 +2,14 @@
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "aidd-pm",
"version": "2.0.0",
- "description": "Product management: ticket-info, user-stories-create, prd, spec",
+ "description": "Product management: ticket-info, user-stories, prd, spec",
"author": {
"name": "AI-Driven Dev",
"url": "https://github.com/ai-driven-dev"
},
"skills": [
"./skills/01-ticket-info",
- "./skills/02-user-stories-create",
+ "./skills/02-user-stories",
"./skills/03-prd",
"./skills/04-spec"
],
diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md
index d4a73cbd..a262047f 100644
--- a/plugins/aidd-pm/CATALOG.md
+++ b/plugins/aidd-pm/CATALOG.md
@@ -9,7 +9,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
- [`.claude-plugin`](#claude-plugin)
- [`skills`](#skills)
- [`skills/01-ticket-info`](#skills01-ticket-info)
- - [`skills/02-user-stories-create`](#skills02-user-stories-create)
+ - [`skills/02-user-stories`](#skills02-user-stories)
- [`skills/03-prd`](#skills03-prd)
- [`skills/04-spec`](#skills04-spec)
@@ -29,26 +29,32 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
|-------|------|---|
| `actions` | [01-ticket-info.md](skills/01-ticket-info/actions/01-ticket-info.md) | - |
| `-` | [README.md](skills/01-ticket-info/README.md) | - |
-| `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display ticket information from the configured ticketing tool. Use when the user says "ticket info", "show ticket", "get ticket", "ticket details", "what's ", or invokes `/ticket-info`. Do NOT use for creating issues, commenting on tickets, changing status, or reassigning.` |
+| `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display a ticket from the configured ticketing tool. Use when the user wants to see, show, or look up a ticket's details. Not for creating a ticket, or commenting on, transitioning, or reassigning one.` |
-#### `skills/02-user-stories-create`
+#### `skills/02-user-stories`
| Group | File | Description |
|-------|------|---|
-| `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.` |
+| `actions` | [01-clarify-scope.md](skills/02-user-stories/actions/01-clarify-scope.md) | - |
+| `actions` | [02-split-epic.md](skills/02-user-stories/actions/02-split-epic.md) | - |
+| `actions` | [03-draft-stories.md](skills/02-user-stories/actions/03-draft-stories.md) | - |
+| `actions` | [04-estimate-impact.md](skills/02-user-stories/actions/04-estimate-impact.md) | - |
+| `actions` | [05-prioritize.md](skills/02-user-stories/actions/05-prioritize.md) | - |
+| `actions` | [06-sync-tracker.md](skills/02-user-stories/actions/06-sync-tracker.md) | - |
+| `assets` | [user-story-template.md](skills/02-user-stories/assets/user-story-template.md) | - |
+| `-` | [README.md](skills/02-user-stories/README.md) | - |
+| `references` | [rating.md](skills/02-user-stories/references/rating.md) | - |
+| `-` | [SKILL.md](skills/02-user-stories/SKILL.md) | `Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog in the tracker. Use when the user wants to create, split, estimate, or prioritize user stories. Not for source code or a PRD.` |
#### `skills/03-prd`
| Group | File | Description |
|-------|------|---|
| `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` | [prd-template.md](skills/03-prd/assets/prd-template.md) | - |
| `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` |
| `-` | [README.md](skills/03-prd/README.md) | - |
-| `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a 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.` |
+| `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a need, idea, or brainstorm, confirmed before save. Use when the user wants to draft or generate a PRD or product requirements. Not for user stories or a technical plan.` |
#### `skills/04-spec`
diff --git a/plugins/aidd-pm/README.md b/plugins/aidd-pm/README.md
index acd14027..1edfea84 100644
--- a/plugins/aidd-pm/README.md
+++ b/plugins/aidd-pm/README.md
@@ -15,6 +15,6 @@ Covers ticket information retrieval, user story creation, product requirement do
| Bracket ID | Skill | Description |
|---|---|---|
| [4.1] | [ticket-info](skills/01-ticket-info/README.md) | Retrieve and display ticket information from the configured ticketing tool. |
-| [4.2] | [user-stories-create](skills/02-user-stories-create/README.md) | Generate INVEST-compliant user stories from a feature description. |
+| [4.2] | [user-stories](skills/02-user-stories/README.md) | Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog. |
| [4.3] | [prd](skills/03-prd/README.md) | Generate a structured Product Requirements Document. |
| [4.4] | [spec](skills/04-spec/README.md) | Generate and refine a project spec from a free-form human request. The spec is the immutable target a planner consumes. |
diff --git a/plugins/aidd-pm/skills/01-ticket-info/SKILL.md b/plugins/aidd-pm/skills/01-ticket-info/SKILL.md
index 9ef4743c..a9e72bcb 100644
--- a/plugins/aidd-pm/skills/01-ticket-info/SKILL.md
+++ b/plugins/aidd-pm/skills/01-ticket-info/SKILL.md
@@ -1,37 +1,21 @@
---
name: 01-ticket-info
-description: Retrieve and display ticket information from the configured ticketing tool. Use when the user says "ticket info", "show ticket", "get ticket", "ticket details", "what's ", or invokes `/ticket-info`. Do NOT use for creating issues, commenting on tickets, changing status, or reassigning.
+description: Retrieve and display a ticket from the configured ticketing tool. Use when the user wants to see, show, or look up a ticket's details. Not for creating a ticket, or commenting on, transitioning, or reassigning one.
---
# Ticket Info
Reads ticket details from the configured ticketing tool. Read-only and tool-agnostic.
-## Available actions
+## Actions
| # | Action | Role | Input |
| --- | -------------- | ------------------------------------------------------------- | ---------------------------------- |
| 01 | `ticket-info` | Resolve ticket id, query the configured tool, display fields | ticket_id (optional) |
-## Default flow
-
-Single action skill. The router dispatches to `ticket-info` whenever a ticket-lookup phrase appears.
-
## Transversal rules
- Read the configured ticketing tool from project memory first; otherwise inspect repo configuration or environment.
- Auto-detect the ticket identifier from the current branch name when none is provided.
- Format the identifier per project convention before querying.
- Read-only: never create, comment, transition, or reassign from this skill.
-
-## References
-
-- None.
-
-## Assets
-
-- None.
-
-## External data
-
-- None.
diff --git a/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md b/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md
index de7b228c..477b8aa7 100644
--- a/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md
+++ b/plugins/aidd-pm/skills/01-ticket-info/actions/01-ticket-info.md
@@ -2,38 +2,23 @@
Resolve the ticket identifier, query the configured ticketing tool, and display the relevant fields.
-## Inputs
+## Input
-```yaml
-ticket_id: # optional; auto-detect from current branch name when omitted
-```
+An optional ticket id or URL. When omitted, auto-detect it from the current branch name.
-## Outputs
+## Output
-```yaml
-ticket_id:
-title:
-description: <body>
-status: <status>
-assignee: <assignee>
-priority: <priority>
-url: <url>
-```
+The ticket's title, description, status, assignee, priority, and URL, displayed for the user.
## Process
-1. **Tool resolution**. Pick first match:
- - ticketing tool declared in project memory -> use it
- - default -> inspect repo configuration or environment for the configured tool
-2. **Ticket identifier**. Pick first match:
- - `ticket_id` provided -> use it
- - default -> extract from `git rev-parse --abbrev-ref HEAD` per project convention
-3. **Format**. Apply the project ticketing convention to the identifier (prefix, separator, casing).
-4. **Query**. Invoke the configured ticketing tool to fetch the ticket record.
-5. **Display**. Render title, description, status, assignee, priority, and URL for the user.
-6. **Return** the structured Outputs block.
+1. **Tool.** Use the ticketing tool declared in project memory. Otherwise inspect the repo configuration or environment for the configured tool.
+2. **Identifier.** Use the provided ticket id when given. Otherwise take it from the current branch name, per project convention.
+3. **Format.** Apply the project ticketing convention to the identifier (prefix, separator, casing).
+4. **Query.** Invoke the configured ticketing tool to fetch the ticket record.
+5. **Display.** Render the title, description, status, assignee, priority, and URL.
## Test
-- **Tool view**: querying the configured ticketing tool for the resolved id returns a record where `title`, `status`, `assignee`, and `url` match the displayed fields.
-- **Reachable**: the ticket is reachable at `url` in the tracker.
+- Querying the configured tool for the resolved id returns a record whose title, description, status, assignee, priority, and URL match the displayed fields.
+- The ticket is reachable at its URL in the tracker.
diff --git a/plugins/aidd-pm/skills/02-user-stories-create/README.md b/plugins/aidd-pm/skills/02-user-stories-create/README.md
deleted file mode 100644
index c0038ec5..00000000
--- a/plugins/aidd-pm/skills/02-user-stories-create/README.md
+++ /dev/null
@@ -1,52 +0,0 @@
-← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md)
-
-# 02 - Create User Stories
-
-Drafts INVEST-compliant user stories from a feature description through a
-short Product Owner clarification loop, then saves them to the configured
-ticketing tool once you validate the draft.
-
-## When to use
-
-- "user stories", "create user stories", "write user stories for X".
-- "INVEST stories", "draft stories".
-- Invoking `/user-stories-create`.
-- Right after a brainstorming session, when scope is clear enough to slice.
-
-## When NOT to use
-
-- To write source code - this skill produces stories, not implementation.
-- To draft a full PRD → use `03-prd`.
-- To refine a single existing story (edit the tracker directly).
-- To copy already-ready story text into a tracker (just paste it).
-
-## How to invoke
-
-```
-Use skill aidd-pm:02-user-stories-create for <feature description>
-```
-
-The skill clarifies in at most 3 questions per round, drafts the stories,
-shows them for explicit validation, then saves on confirmation.
-
-## Outputs
-
-- A set of INVEST-compliant user stories, each with acceptance criteria,
- dependencies, and story points.
-- Stories sorted by implementation priority.
-- One ticket per story created in the configured ticketing tool after
- explicit validation.
-
-## Prerequisites
-
-- Project memory declares the active ticketing tool with write access.
-- A clear-enough feature description; if too vague, the skill asks you to
- brainstorm first rather than fabricating stories.
-
-## Technical details
-
-See [`SKILL.md`](SKILL.md) for the action contract,
-[`actions/01-create-user-stories.md`](actions/01-create-user-stories.md) for
-the single atomic action, and
-[`assets/user-story-template.md`](assets/user-story-template.md) for the
-story body template.
diff --git a/plugins/aidd-pm/skills/02-user-stories-create/SKILL.md b/plugins/aidd-pm/skills/02-user-stories-create/SKILL.md
deleted file mode 100644
index 1286159a..00000000
--- a/plugins/aidd-pm/skills/02-user-stories-create/SKILL.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-name: 02-user-stories-create
-description: Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.
----
-
-# Create User Stories
-
-Drafts INVEST-compliant user stories from a feature description through Product Owner clarification.
-
-## Available actions
-
-| # | Action | Role | Input |
-| --- | ----------------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
-| 01 | `create-user-stories` | Clarify scope, draft stories, validate, save to the tracker | feature_description, existing_stories (optional) |
-
-## Default flow
-
-Single action skill. The router dispatches to `create-user-stories` whenever a story-generation phrase appears.
-
-## Transversal rules
-
-- **INVEST**: each story is Independent, Negotiable, Valuable, Estimable, Small, Testable.
-- **Definition of Ready**: acceptance criteria, dependencies, story points, and zero blocking questions before save.
-- **Lean clarification**: at most 3 questions per iteration; focus on user needs, not technical aspects.
-- Stories are sorted by implementation priority.
-- Always wait for explicit user validation before saving to the tracker.
-- The save target is the configured ticketing tool from project memory.
-
-## References
-
-- None.
-
-## Assets
-
-- `@assets/user-story-template.md`: User story body template.
-
-## External data
-
-- None.
diff --git a/plugins/aidd-pm/skills/02-user-stories-create/actions/01-create-user-stories.md b/plugins/aidd-pm/skills/02-user-stories-create/actions/01-create-user-stories.md
deleted file mode 100644
index d81d1506..00000000
--- a/plugins/aidd-pm/skills/02-user-stories-create/actions/01-create-user-stories.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# 01 - Create User Stories
-
-Clarify scope through iterative Product Owner questioning, draft INVEST-compliant user stories, validate with the user, then save them to the configured ticketing tool.
-
-## Inputs
-
-```yaml
-feature_description: <free text> # required; the feature or requirement to break into stories
-existing_stories: [<id>] # optional; ids of related stories to consider
-```
-
-## Outputs
-
-```yaml
-stories:
- - id: <tracker id>
- title: <user story title>
- story: As a <persona>, I want <goal>, so that <reason>.
- acceptance_criteria:
- - <criterion>
- story_points: <int>
- priority: <int>
- url: <tracker url>
-```
-
-## Process
-
-1. **Clarify**. Ask up to 3 questions per iteration to close gaps in problem, features, criteria, scope, and constraints. Skip technical detail.
-2. **Iterate**. Pick first match:
- - blocking question remains -> loop back to step 1
- - no blocking question -> proceed
-3. **Draft**. Format each story with `assets/user-story-template.md`. Sort by implementation priority.
-4. **Validate**. Show the full story list to the user. Wait for explicit approval.
-5. **Save**. Invoke the configured ticketing tool to create each story; capture the returned id and url.
-6. **Return** the structured Outputs block.
-
-## Test
-
-- **INVEST**: each story satisfies Independent, Negotiable, Valuable, Estimable, Small, Testable.
-- **Ready**: every story has acceptance criteria, dependencies addressed, and story points set.
-- **Persisted**: querying the configured ticketing tool returns each saved story id with matching title.
diff --git a/plugins/aidd-pm/skills/02-user-stories-create/assets/user-story-template.md b/plugins/aidd-pm/skills/02-user-stories-create/assets/user-story-template.md
deleted file mode 100644
index 91920632..00000000
--- a/plugins/aidd-pm/skills/02-user-stories-create/assets/user-story-template.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-name: user-story
-description: Template for defining user stories with estimation and acceptance criteria
-argument-hint: N/A
----
-
-# [Epic Name]
-
-## US-[ID]: "[User Story Title]"
-
-**As a** [role]
-**I want** [action]
-**So that** [outcome]
-
-### Acceptance Criteria
-
-```gherkin
-Scenario: [Error condition]
- Given [error context]
- When [error trigger]
- Then [graceful error handling]
-
-Scenario: [Boundary condition]
- Given [edge case context]
- When [edge action]
- Then [expected behavior]
-```
diff --git a/plugins/aidd-pm/skills/02-user-stories/README.md b/plugins/aidd-pm/skills/02-user-stories/README.md
new file mode 100644
index 00000000..95763b00
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/README.md
@@ -0,0 +1,58 @@
+← [aidd-framework](../../../../README.md) / [aidd-pm](../../README.md)
+
+# 02 - User Stories
+
+Turns a feature or epic into a prioritized backlog of INVEST-compliant user
+stories. Each story carries acceptance criteria, a pragmatic functional
+Definition of Done, an effort estimate, and an impact rating, then is saved to
+the project's configured tracker once you validate the draft.
+
+## When to use
+
+- "user stories", "create user stories", "write user stories for X".
+- "INVEST stories", "draft stories".
+- "split this epic", "break down this feature".
+- "estimate stories", "prioritize the backlog".
+- Invoking `/user-stories`.
+- Right after a brainstorming session, when scope is clear enough to slice.
+
+## When NOT to use
+
+- To write source code - this skill produces stories, not implementation.
+- To draft a full PRD → use `03-prd`.
+- To refine a single existing story (edit the tracker directly).
+- To copy already-ready story text into a tracker (just paste it).
+
+## How to invoke
+
+```
+Use skill aidd-pm:02-user-stories for <feature or epic description>
+```
+
+The skill clarifies in at most 3 questions per round, splits an epic into
+candidate stories, drafts them, estimates effort and impact, ranks the
+backlog, shows it for explicit validation, then saves on confirmation.
+
+## Outputs
+
+- A set of INVEST-compliant user stories, each with acceptance criteria, a
+ functional Definition of Done, dependencies, and story points.
+- An impact rating (minor, major, critic) per story.
+- The backlog ranked by value against effort and impact.
+- One ticket per story created in the configured tracker after explicit
+ validation.
+
+## Prerequisites
+
+- Project memory declares the active ticketing tool with write access.
+- A clear-enough feature description; if too vague, the skill asks you to
+ brainstorm first rather than fabricating stories.
+
+## Technical details
+
+See [`SKILL.md`](SKILL.md) for the action contract, the files under
+[`actions/`](actions) for each step of the chain,
+[`references/rating.md`](references/rating.md) for the INVEST, readiness,
+Definition of Done, impact, and prioritization definitions, and
+[`assets/user-story-template.md`](assets/user-story-template.md) for the story
+body template.
diff --git a/plugins/aidd-pm/skills/02-user-stories/SKILL.md b/plugins/aidd-pm/skills/02-user-stories/SKILL.md
new file mode 100644
index 00000000..07bc41b6
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: 02-user-stories
+description: Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog in the tracker. Use when the user wants to create, split, estimate, or prioritize user stories. Not for source code or a PRD.
+argument-hint: clarify-scope | split-epic | draft-stories | estimate-impact | prioritize | sync-tracker
+---
+
+# User Stories
+
+Produces a prioritized backlog of INVEST-compliant user stories, each estimated for effort and impact and carrying a pragmatic functional Definition of Done, then saved to the project's configured tracker.
+
+## Actions
+
+| # | Action | Role | Input |
+| --- | ----------------- | -------------------------------------------------------------------- | -------------------------------------- |
+| 01 | `clarify-scope` | Clarify the request through Product Owner questioning; decide epic vs single story | feature or epic description |
+| 02 | `split-epic` | Decompose the confirmed scope into candidate vertical-slice stories | confirmed scope from 01 |
+| 03 | `draft-stories` | Write each candidate as an INVEST story with acceptance criteria and a functional DoD | candidate stories from 02 |
+| 04 | `estimate-impact` | Rate each story for effort (points) and impact on the existing system | drafted stories from 03 |
+| 05 | `prioritize` | Rank the backlog by value against effort and impact | estimated stories from 04 |
+| 06 | `sync-tracker` | Gate on Definition of Ready, get explicit approval, save to the tracker | ranked backlog from 05 |
+
+Run `01 → 02 → 03 → 04 → 05 → 06`, passing each `## Test` first. A single story skips the epic split.
+
+## Transversal rules
+
+- **INVEST**: each story is Independent, Negotiable, Valuable, Estimable, Small, Testable.
+- **Definition of Ready**: acceptance criteria, dependencies, story points, and an impact rating are set, with zero blocking questions, before save.
+- **Definition of Done**: each story carries a pragmatic, functional DoD, observable user-facing conditions that mean the goal is met. Functional only, never technical delivery steps.
+- **Lean clarification**: at most 3 questions per iteration; focus on user needs, not technical aspects.
+- Always wait for explicit user validation before saving to the tracker.
+- The save target is the configured ticketing tool from project memory; never assume a specific tool.
+
+## References
+
+- `references/rating.md`: INVEST, the Definition of Ready and functional Definition of Done, the minor/major/critic impact scale, and the prioritization method.
+
+## Assets
+
+- `assets/user-story-template.md`: user story body template.
diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/01-clarify-scope.md b/plugins/aidd-pm/skills/02-user-stories/actions/01-clarify-scope.md
new file mode 100644
index 00000000..10f23943
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/actions/01-clarify-scope.md
@@ -0,0 +1,25 @@
+# 01 - Clarify scope
+
+Close the gaps in the request through Product Owner questioning, then decide whether it is an epic or a single story.
+
+## Input
+
+A free-text feature or epic description. Optionally, ids of related existing stories to consider.
+
+## Output
+
+A confirmed scope statement: the problem, the in-scope outcomes, the named constraints, and a flag marking the request as an epic (multiple stories) or a single story.
+
+## Process
+
+1. **Read.** Restate the request in one sentence to surface the implicit need.
+2. **Question.** Cover problem, outcomes, criteria, scope edges, and constraints.
+3. **Iterate.** If a blocking question remains, loop back to step 2. Otherwise proceed.
+4. **Classify.** Judge the breadth. Flag the request as an epic when it spans more than one independent outcome, otherwise as a single story.
+5. **Confirm.** Show the scope statement and the epic-or-single flag. Wait for the user to confirm before handing to `02-split-epic`.
+
+## Test
+
+- The output names the problem, the in-scope outcomes, and the constraints.
+- The output carries an explicit epic-or-single flag confirmed by the user.
+- No blocking question is left open when the action proceeds.
diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md b/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md
new file mode 100644
index 00000000..59817d81
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/actions/02-split-epic.md
@@ -0,0 +1,25 @@
+# 02 - Split epic
+
+Decompose the confirmed scope into candidate stories, each a vertical slice that delivers value on its own.
+
+## Input
+
+The confirmed scope statement and epic-or-single flag from `01-clarify-scope`.
+
+## Output
+
+An ordered list of candidate stories, each a title plus a one-line user goal. A single-story request yields exactly one candidate.
+
+## Process
+
+1. **Branch.** If the flag marks a single story, emit one candidate from the scope and stop. Otherwise continue.
+2. **Slice.** Cut the epic along user outcomes, not technical layers. Each slice must deliver something a user can perceive.
+3. **Check independence.** Reshape any slice that cannot ship without another, so each candidate stands alone (see `@../references/rating.md`).
+4. **Name.** Give each candidate a short title and a one-line goal in user terms.
+5. **Confirm.** Show the candidate list and wait for the user to confirm before handing to `03-draft-stories`.
+
+## Test
+
+- Each candidate is a vertical slice with a user-perceivable outcome.
+- A single-story input produces exactly one candidate.
+- No candidate depends on another candidate to deliver its value.
diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md b/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md
new file mode 100644
index 00000000..06943b70
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/actions/03-draft-stories.md
@@ -0,0 +1,25 @@
+# 03 - Draft stories
+
+Write each candidate as a full INVEST story with acceptance criteria and a pragmatic functional Definition of Done.
+
+## Input
+
+The confirmed candidate list from `02-split-epic`.
+
+## Output
+
+One drafted story per candidate, each filling `@../assets/user-story-template.md`: the As-a/I-want/So-that statement, Gherkin acceptance criteria, and a functional DoD.
+
+## Process
+
+1. **Frame.** Write the As-a/I-want/So-that statement, naming the role, the action, and the outcome.
+2. **Criteria.** Write Gherkin scenarios covering at least one nominal case and one error or boundary case.
+3. **Done.** Write the functional DoD per `@../references/rating.md`: observable, user-facing conditions only, never technical delivery steps.
+4. **Check INVEST.** Verify each story against the six criteria in `@../references/rating.md`. Reshape any story that fails.
+5. **Fill.** Render each story into `@../assets/user-story-template.md`, leaving estimation fields for `04-estimate-impact`.
+
+## Test
+
+- Each story has an As-a/I-want/So-that statement and at least one Gherkin scenario.
+- Each story has a functional DoD whose bullets are user-facing, with no technical delivery step.
+- Each story satisfies all six INVEST criteria.
diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md b/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md
new file mode 100644
index 00000000..cf37ce63
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/actions/04-estimate-impact.md
@@ -0,0 +1,23 @@
+# 04 - Estimate impact
+
+Rate each story for effort and for its impact on the existing system.
+
+## Input
+
+The drafted stories from `03-draft-stories`.
+
+## Output
+
+Each story annotated with story points, its dependencies (named or confirmed absent), an impact rating of minor, major, or critic, and a one-line rationale for the impact.
+
+## Process
+
+1. **Estimate effort.** Assign story points reflecting relative size. Flag any story too large to size and send it back to `02-split-epic`.
+2. **Rate impact.** Assign minor, major, or critic per the impact scale in `@../references/rating.md`.
+3. **Justify.** Write a one-line rationale for each impact rating.
+4. **Record.** Fill the estimation block in `@../assets/user-story-template.md` for each story.
+
+## Test
+
+- Each story carries a numeric story-point value.
+- Each story carries an impact rating in {minor, major, critic} with a one-line rationale.
diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md b/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md
new file mode 100644
index 00000000..ec5b98f2
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/actions/05-prioritize.md
@@ -0,0 +1,23 @@
+# 05 - Prioritize
+
+Rank the backlog by value against effort, breaking ties with impact.
+
+## Input
+
+The estimated stories from `04-estimate-impact`.
+
+## Output
+
+The stories as a single ordered list, each with a priority rank, ordered by the method in `@../references/rating.md`.
+
+## Process
+
+1. **Score.** For each story, weigh delivered value against its story points.
+2. **Order.** Sort by descending value-to-effort, then break ties with the lower impact first, per `@../references/rating.md`.
+3. **Override.** Pull a story earlier only when a later story depends on it. State that reason on the affected story.
+4. **Rank.** Write the priority rank into each story's estimation block.
+
+## Test
+
+- The output is a strictly ordered list with a unique rank per story.
+- The ranking key is stated, and any dependency-driven override names its reason.
diff --git a/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md b/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md
new file mode 100644
index 00000000..eb355962
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/actions/06-sync-tracker.md
@@ -0,0 +1,25 @@
+# 06 - Sync tracker
+
+Gate the backlog on the Definition of Ready, get explicit approval, then save each story to the configured tracker.
+
+## Input
+
+The ranked backlog from `05-prioritize`.
+
+## Output
+
+One ticket per story created in the configured tracker, each capturing the returned id and url.
+
+## Process
+
+1. **Resolve target.** Read the active ticketing tool from project memory. If none is declared, ask the user which tracker to use rather than assuming one.
+2. **Gate.** Check every story against the Definition of Ready in `@../references/rating.md`. Send any failing story back to its action. Do not proceed while one fails.
+3. **Present.** Show the full ranked backlog. Wait for explicit user approval before any write.
+4. **Save.** On approval, create one ticket per story in the resolved tracker. Capture the returned id and url for each.
+5. **Report.** Return the created stories with their ids and urls, in priority order.
+
+## Test
+
+- After approval, querying the configured tracker returns each saved story id with a matching title.
+- The Definition of Ready holds for every saved story.
+- No write happens before explicit user approval.
diff --git a/plugins/aidd-pm/skills/02-user-stories/assets/user-story-template.md b/plugins/aidd-pm/skills/02-user-stories/assets/user-story-template.md
new file mode 100644
index 00000000..f6583b2d
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/assets/user-story-template.md
@@ -0,0 +1,33 @@
+# [Epic name]
+
+## US-[ID]: "[User story title]"
+
+**As a** [role]
+**I want** [action]
+**So that** [outcome]
+
+### Acceptance criteria
+
+```gherkin
+Scenario: [Nominal case]
+ Given [context]
+ When [action]
+ Then [expected outcome]
+
+Scenario: [Error or boundary case]
+ Given [edge context]
+ When [edge trigger]
+ Then [graceful handling]
+```
+
+### Definition of Done (functional)
+
+- [User-facing condition the user can now confirm]
+- [Another observable outcome]
+
+### Estimation
+
+- **Story points**: [int]
+- **Impact**: [minor | major | critic] — [one-line rationale]
+- **Dependencies**: [story ids, or none]
+- **Priority**: [rank]
diff --git a/plugins/aidd-pm/skills/02-user-stories/references/rating.md b/plugins/aidd-pm/skills/02-user-stories/references/rating.md
new file mode 100644
index 00000000..2089d4a1
--- /dev/null
+++ b/plugins/aidd-pm/skills/02-user-stories/references/rating.md
@@ -0,0 +1,57 @@
+# Rating and readiness
+
+The definitions every action in this skill relies on. Read this before drafting, estimating, prioritizing, or saving.
+
+## INVEST
+
+Each story must satisfy all six:
+
+- **Independent**: it can ship without waiting on another story in the batch.
+- **Negotiable**: it states the need, not a frozen solution.
+- **Valuable**: it delivers an outcome a user or stakeholder can perceive.
+- **Estimable**: the team can size it without unresolved unknowns.
+- **Small**: it fits inside one iteration.
+- **Testable**: its acceptance criteria can be checked objectively.
+
+## Definition of Ready
+
+A story is ready to save when all hold:
+
+- Acceptance criteria are written and testable.
+- Dependencies are named or confirmed absent.
+- Story points are set.
+- An impact rating is assigned.
+- No blocking question remains open.
+
+## Functional Definition of Done
+
+Each story carries a pragmatic, functional DoD.
+
+- It lists observable, user-facing conditions that mean the goal is achieved.
+- It is phrased from the user's side: what the user can now do, see, or avoid.
+- It stays functional. It never lists technical delivery steps such as code review, test coverage, or deployment.
+- Keep it short: two to four bullets that a non-technical stakeholder can confirm.
+
+Example for a password-reset story:
+
+- The user requests a reset and receives the link within one minute.
+- Following the link lets the user set a new password and sign in with it.
+- An expired or reused link shows a clear message and offers a fresh request.
+
+## Impact scale
+
+Rate each story by its impact on the existing system. This is a risk signal, not the effort estimate.
+
+- **minor**: additive or isolated. It touches no existing behavior users already rely on.
+- **major**: it changes existing behavior, a shared component, or a public contract. Existing flows need re-checking.
+- **critic**: it touches a critical path (auth, payments, data integrity) or risks data loss or downtime. It needs explicit review before build.
+
+State a one-line rationale with every rating.
+
+## Prioritization
+
+Rank the backlog by value against effort, then break ties with impact.
+
+- Order by descending value-to-effort ratio.
+- On a tie, the lower-impact story ranks first, since it ships with less risk.
+- A `critic` story may be pulled earlier only when later stories depend on it; state that reason when it happens.
diff --git a/plugins/aidd-pm/skills/03-prd/README.md b/plugins/aidd-pm/skills/03-prd/README.md
index bb4576a3..9e1a59a3 100644
--- a/plugins/aidd-pm/skills/03-prd/README.md
+++ b/plugins/aidd-pm/skills/03-prd/README.md
@@ -16,7 +16,7 @@ Stays at the "what and why" level; never crosses into implementation detail.
## When NOT to use
-- To write user stories → use `02-user-stories-create`.
+- To write user stories → use `02-user-stories`.
- To draft a technical implementation plan (libraries, file layout,
algorithms) - those belong to the planning skill in your dev capability.
- To write source code.
diff --git a/plugins/aidd-pm/skills/03-prd/SKILL.md b/plugins/aidd-pm/skills/03-prd/SKILL.md
index d2e4b193..a43e12d0 100644
--- a/plugins/aidd-pm/skills/03-prd/SKILL.md
+++ b/plugins/aidd-pm/skills/03-prd/SKILL.md
@@ -1,39 +1,27 @@
---
name: 03-prd
-description: Generate a structured Product Requirements Document from a feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code.
+description: Generate a structured Product Requirements Document from a need, idea, or brainstorm, confirmed before save. Use when the user wants to draft or generate a PRD or product requirements. Not for user stories or a technical plan.
---
# PRD
Drafts a structured Product Requirements Document covering scope, goals, and acceptance criteria.
-## Available actions
+## Actions
| # | Action | Role | Input |
| --- | ------- | ---------------------------------------------------- | ----------------------------------------------- |
| 01 | `prd` | Parse input, draft per template, validate, save | feature_description, user_stories (optional) |
-## Default flow
-
-Single action skill. The router dispatches to `prd` whenever a PRD-generation phrase appears.
-
## Transversal rules
- Focus on what and why; never include technical implementation detail.
- Sections stay concise and actionable.
- Always wait for explicit user validation before saving.
- Save path: `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`.
-- Source of truth for structure: `@assets/prd-template.md`.
-
-## References
-
-- None.
+- Source of truth for structure: `assets/prd-template.md`.
## Assets
-- `@assets/prd-template.md`: PRD body template.
-- `@assets/task-template.md`: Lightweight task template referenced from the PRD when needed.
-
-## External data
-
-- None.
+- `assets/prd-template.md`: PRD body template.
+- `assets/task-template.md`: Lightweight task template referenced from the PRD when needed.
diff --git a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md
index 2fd0c8a2..2ad3ec9e 100644
--- a/plugins/aidd-pm/skills/03-prd/actions/01-prd.md
+++ b/plugins/aidd-pm/skills/03-prd/actions/01-prd.md
@@ -1,40 +1,24 @@
# 01 - PRD
-Parse the feature input, draft a structured PRD per the template, validate with the user, then save the file under `aidd_docs/tasks/`.
-
-## Inputs
-
-```yaml
-feature_description: <free text> # required
-user_stories: [<id or text>] # optional; existing stories to anchor the PRD
-```
-
-## Outputs
-
-```yaml
-prd_path: aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md
-feature_name: <kebab-case slug>
-sections_present:
- - overview
- - problem-statement
- - goals
- - non-goals
- - user-stories
- - acceptance-criteria
- - dependencies
- - open-questions
-```
+Parse the feature input, draft a structured PRD from the template, validate with the user, then save the file under `aidd_docs/tasks/`.
+
+## Input
+
+A feature description (required), and optionally existing user stories (ids or text) to anchor the PRD.
+
+## Output
+
+The saved PRD at `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`, carrying all eight sections.
## Process
-1. **Parse input**. Extract feature scope, goals, and constraints from `feature_description` (and `user_stories` when provided).
-2. **Draft**. Fill `assets/prd-template.md` with all 8 sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions.
-3. **Validate**. Show the full draft to the user. Wait for explicit approval. Apply revisions and re-show on each iteration.
-4. **Save**. Write the approved PRD to `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-<feature_name>-prd.md`. Create the month directory when missing.
-5. **Return** the structured Outputs block.
+1. **Parse.** Extract the feature scope, goals, and constraints from the description and any user stories.
+2. **Draft.** Fill `@../assets/prd-template.md` with its eight sections: overview, problem statement, goals, non-goals, user stories, acceptance criteria, dependencies, open questions.
+3. **Validate.** Show the full draft, wait for explicit approval, and re-show after each revision.
+4. **Save.** Write the approved PRD to its dated path, creating the month directory when missing.
## Test
-- **File saved**: `prd_path` exists on disk after the action completes.
-- **All sections**: the file contains the 8 required headings listed in `sections_present`.
-- **No implementation**: the file has no `## Implementation` heading and no source code blocks describing how to build the feature.
+- The PRD file exists on disk after the action completes.
+- It contains the eight headings: Overview, Problem Statement, Goals, Non-Goals, User Stories, Acceptance Criteria, Dependencies, Open Questions.
+- It has no solution detail: no tech-stack, data-model, or architecture section, no `## Implementation` heading, and no source code.
diff --git a/plugins/aidd-pm/skills/03-prd/assets/prd-template.md b/plugins/aidd-pm/skills/03-prd/assets/prd-template.md
index 2e5db7b2..65a93b9e 100644
--- a/plugins/aidd-pm/skills/03-prd/assets/prd-template.md
+++ b/plugins/aidd-pm/skills/03-prd/assets/prd-template.md
@@ -1,319 +1,37 @@
----
-name: prd
-description: Product Requirements Document template (15 sections)
-argument-hint: N/A
----
+<!-- Product Requirements Document template (8 sections). Solution-agnostic: what and why, never how. Fill the placeholders; do not copy this comment. -->
-# [Project name] - [version]
+# [Project name]
-[Full Summary of the app and features we are willing to code.]
+[One or two sentences: the product or feature and the problem it solves.]
-## 1. Executive Summary
+## Overview
-### Problem
+[The context and the value. Who it is for and why it matters now. No solution detail.]
-[What problem are we solving?]
+## Problem Statement
-### Solution
+[The user or business problem, stated as a need. The pain today and its cost. No proposed implementation.]
-[What are we building?]
+## Goals
-### Success Criteria
+[The outcomes this must achieve, each observable and measurable. What success looks like, not how to build it.]
-[How do we know we've succeeded?]
+## Non-Goals
-## 2. User Personas
+[What is explicitly out of scope, so the boundary is unambiguous.]
-### Primary Persona: [Name]
+## User Stories
-| Attribute | Description |
-| ------------------------- | ----------------------------- |
-| **Role** | [Job title or user type] |
-| **Goals** | [What they want to achieve] |
-| **Motivations** | [Why they use the product] |
-| **Frustrations** | [Current pain points] |
-| **Technical Environment** | [Devices, tools, constraints] |
+[The needs as user stories: "As a [persona], I want [goal], so that [reason]." One per line, no technical detail.]
-### Secondary Persona: [Name]
+## Acceptance Criteria
-| Attribute | Description |
-| ---------------- | --------------------------- |
-| **Role** | [Job title or user type] |
-| **Goals** | [What they want to achieve] |
-| **Motivations** | [Why they use the product] |
-| **Frustrations** | [Current pain points] |
+[The conditions that make the product correct, observable and user-facing. Behavior, not code.]
-## 3. Goals & Objectives
+## Dependencies
-### Business Goals
+[External constraints, data, approvals, or other work this depends on. Business and product dependencies, not a tech stack.]
-- BG1: [Revenue/growth goal]
-- BG2: [User acquisition/retention]
+## Open Questions
-### Technical Goals
-
-- TG1: [Performance/scalability]
-- TG2: [Security/reliability]
-
-### User Goals
-
-- UG1: [User experience improvement]
-- UG2: [Efficiency/productivity gain]
-
-## 4. Core Features
-
-Group of identified features to build:
-
-- **Feature 1**: [Short description]
-
-### [Feature/Module 1]
-
-- FR1.1: [Specific requirement]
-- FR1.2: [Specific requirement]
-
-#### User Stories
-
-- As a [user type], I want to [action] so that [benefit]
-
-## 5. Acceptance Criteria
-
-> Define testable criteria for each core feature using the Gherkin format (Given-When-Then).
-
-### Feature 1: [Feature Name]
-
-**Happy Path:**
-
-```gherkin
-Scenario: [Description]
- Given [initial context]
- When [action performed]
- Then [expected result]
- And [additional verification]
-```
-
-**Error Scenarios:**
-
-```gherkin
-Scenario: [Error case description]
- Given [error context]
- When [action that causes error]
- Then [error handling behavior]
-```
-
-**Edge Cases:**
-
-- [ ] [Edge case 1]
-- [ ] [Edge case 2]
-
-## 6. Non-Goals
-
-> What we are intentionally NOT building in this version. This prevents scope creep.
-
-| Non-Goal | Rationale |
-| ----------- | ------------------------------ |
-| [Feature X] | [Why we're not building it] |
-| [Feature Y] | [Why it's out of scope] |
-| [Feature Z] | [Why it's explicitly excluded] |
-
-## 7. Non-Functional Requirements
-
-For every given features:
-
-### Performance
-
-- NFR1: [Response time targets]
-- NFR2: [Throughput requirements]
-- NFR3: [Scalability needs]
-
-### Security
-
-- NFR4: [Authentication/authorization]
-- NFR5: [Data protection]
-- NFR6: [Compliance requirements]
-
-### Usability
-
-- NFR7: [Accessibility standards (WCAG)]
-- NFR8: [Browser/device support]
-
-## 8. Technical Architecture
-
-### Tech Stack
-
-- **Frontend**: [Framework, UI library]
-- **Backend**: [Language, framework]
-- **Database**: [Type, specific system]
-- **Infrastructure**: [Cloud, containers]
-- **External Services**: [APIs, SaaS]
-
-### Data Model
-
-```
-[Key entities and relationships]
-[Data flow diagram if needed]
-```
-
-### Integration Points
-
-- **Internal APIs**: [List]
-- **External APIs**: [List with rate limits]
-- **Data Sources**: [Databases, files, streams]
-
-## 9. User Experience
-
-### Information Architecture
-
-[Site map or app structure]
-
-### Key User Flows
-
-1. [Primary flow description]
-2. [Secondary flow description]
-
-### Design System
-
-- **Visual**: [Colors, typography, spacing]
-- **Components**: [Reusable UI elements]
-- **Patterns**: [Interaction patterns]
-- **Responsive**: [Breakpoints, mobile-first?]
-
-## 10. Success Metrics
-
-### Business KPIs
-
-| Metric | Current | Target | Date |
-| ---------- | ---------- | -------- | ------ |
-| [Metric 1] | [Baseline] | [Target] | [Date] |
-| [Metric 2] | [Baseline] | [Target] | [Date] |
-
-### Technical KPIs
-
-| Metric | Current | Target |
-| --------------- | ---------- | -------- |
-| [Response time] | [Baseline] | [Target] |
-| [Uptime] | [Baseline] | [Target] |
-
-### User KPIs
-
-| Metric | How Measured | Target |
-| ------------------- | ------------ | -------- |
-| [User satisfaction] | [Method] | [Target] |
-| [Task completion] | [Method] | [Target] |
-
-## 11. Dependencies
-
-> External dependencies that must be resolved or coordinated.
-
-### Technical Dependencies
-
-| Dependency | Owner | Status | Risk |
-| -------------------- | ------------- | ------------------- | ----------------- |
-| [API from Team X] | [Team/Person] | [Available/Pending] | [High/Medium/Low] |
-| [Database migration] | [Team/Person] | [Status] | [Risk level] |
-
-### External Dependencies
-
-| Dependency | Provider | Status | Fallback |
-| ------------------ | ---------- | ------------------- | --------------- |
-| [Third-party API] | [Provider] | [Available/Pending] | [Alternative] |
-| [SaaS integration] | [Provider] | [Status] | [Fallback plan] |
-
-## 12. Experiments / A/B Testing
-
-> Hypotheses to validate and experiments to run.
-
-| Hypothesis | Experiment | Metric | Success Criteria |
-| --------------------------------- | ---------------------- | ----------------- | -------------------- |
-| [If we do X, then Y will improve] | [A/B test description] | [Metric to track] | [Target improvement] |
-| [Users prefer X over Y] | [Test approach] | [Metric] | [Success threshold] |
-
-### Experiment Plan
-
-- **Phase 1**: [% of users] - [Duration]
-- **Phase 2**: [% of users] - [Duration]
-- **Full rollout criteria**: [Conditions for 100% rollout]
-
-## 13. Timeline & Milestones
-
-| Milestone | Objective | Deliverable | Target Date | Go/No-Go Criteria |
-| ---------- | ----------------- | ----------------- | ----------- | --------------------- |
-| M1: [Name] | [What we achieve] | [What we deliver] | [Date] | [Criteria to proceed] |
-| M2: [Name] | [What we achieve] | [What we deliver] | [Date] | [Criteria to proceed] |
-| M3: [Name] | [What we achieve] | [What we deliver] | [Date] | [Criteria to proceed] |
-
-### Critical Path
-
-```mermaid
-flowchart LR
- M1["M1: Foundation"] --> M2["M2: Core Features"]
- M2 --> M3["M3: Polish & Launch"]
-```
-
-## 14. Risks & Mitigations
-
-| Risk | Probability | Impact | Mitigation Plan | Owner |
-| ---------------- | --------------- | --------------- | ----------------------- | -------- |
-| [Technical risk] | High/Medium/Low | High/Medium/Low | [How to prevent/handle] | [Person] |
-| [Business risk] | High/Medium/Low | High/Medium/Low | [How to prevent/handle] | [Person] |
-| [Timeline risk] | High/Medium/Low | High/Medium/Low | [How to prevent/handle] | [Person] |
-
-### Contingency Plans
-
-- **If [Risk 1] occurs**: [Contingency action]
-- **If [Risk 2] occurs**: [Contingency action]
-
-## 15. Scope Boundaries (3 Tiers)
-
-### Tier 1 - MVP (Must Have)
-
-> What is included in the first release.
-
-| Feature | Rationale |
-| ----------- | -------------- |
-| [Feature 1] | [Why it's MVP] |
-| [Feature 2] | [Why it's MVP] |
-
-### Tier 2 - Next Release (Should/Could Have)
-
-> What is explicitly deferred to V2. Each feature has a promotion trigger.
-
-| Feature | Rationale | Promotion Trigger |
-| ----------- | -------------- | ------------------------------------------ |
-| [Feature X] | [Why deferred] | [Metric or condition to promote to Tier 1] |
-| [Feature Y] | [Why deferred] | [Metric or condition] |
-
-### Tier 3 - Never (Won't Have)
-
-> What we will never build.
-
-| Feature | Rationale |
-| ---------------- | ----------- |
-| [Anti-pattern X] | [Why never] |
-| [Anti-pattern Y] | [Why never] |
-
----
-
-## Appendix
-
-### Glossary
-
-- **Term**: Definition
-- **Acronym**: Full meaning
-
-### References
-
-- [Related documents]
-- [Design mockups]
-- [Technical specs]
-
-### Open Questions
-
-- [ ] [Question needing answer]
-- [ ] [Decision to be made]
-
----
-
-**Team**: [Size/roles]
-**Timeline**: [Total duration]
-**Priority**: [Critical/High/Medium/Low]
-**Status**: [Draft/Approved/In Progress]
+[Unresolved decisions and unknowns to settle before or during build.]
diff --git a/plugins/aidd-pm/skills/03-prd/assets/task-template.md b/plugins/aidd-pm/skills/03-prd/assets/task-template.md
index cdc9e1db..5f71ea95 100644
--- a/plugins/aidd-pm/skills/03-prd/assets/task-template.md
+++ b/plugins/aidd-pm/skills/03-prd/assets/task-template.md
@@ -7,7 +7,7 @@ description: Task tracking system to ensure all tasks are categorized and addres
{{Full description}}
-## Main step 1}
+## Main step 1
- [ ] {Task 1}
- [ ] {Task 2}
diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md
index 1b099bc2..a7621f49 100644
--- a/plugins/aidd-pm/skills/04-spec/SKILL.md
+++ b/plugins/aidd-pm/skills/04-spec/SKILL.md
@@ -22,7 +22,7 @@ Dispatch by input: a spec path with findings runs `refine`; a request or PRD pat
- Never invent. Mark every gap as `TBD: <precise question>` rather than guessing. When a request is too vague to draft anything useful, stop and ask for a clearer one.
- The spec holds intent, never implementation. It is solution-agnostic: no file, component, hook, route, library, pattern, or token, and no "how". The done-when conditions are outcome-level, not steps. Keep the acceptance criteria few. All of that belongs to the plan.
- Keep it readable: clear section headers, bulleted criteria, explicit non-goals.
-- Output: one `spec.md` in the feature folder (`aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/`), from `@assets/spec-template.md`. Reuse the folder when it exists.
+- Output: one `spec.md` in the feature folder (`aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<slug>/`), from `assets/spec-template.md`. Reuse the folder when it exists.
- Immutable once validated: never rewrite a spec that has been locked.
## Assets
diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md
index 0a177962..dd7a521f 100644
--- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md
+++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md
@@ -12,7 +12,7 @@ The path to `spec.md` in the feature folder, drafted from the template, with the
## Process
-1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. Do not explore the codebase or name any file, component, or API: the spec stays solution-agnostic, intent only.
+1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. Do not explore the codebase.
2. **Gaps.** Replace any missing required field with `TBD: <precise question>`. Never guess.
3. **Check.** Confirm every section the validator requires is present.
4. **Write.** Resolve the feature folder, reusing it when it exists, and save the spec there as `spec.md`.
@@ -21,5 +21,5 @@ The path to `spec.md` in the feature folder, drafted from the template, with the
## Test
- `spec.md` exists in the feature folder.
-- It contains every section listed in `@../assets/spec-validator.yml`.
+- It contains every section the validator marks required in `@../assets/spec-validator.yml`.
- It carries no library name, framework pattern, or source-file layout.
diff --git a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md
index 6783f0a9..a44844dd 100644
--- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md
+++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md
@@ -20,5 +20,5 @@ The refined spec at the same path, with the changes applied and any residual `TB
## Test
-- The spec still exists at its path and holds every section listed in `@../assets/spec-validator.yml`.
+- The spec still exists at its path and holds every required section in `@../assets/spec-validator.yml`.
- Every finding is reflected by a change, or by an explicit `TBD: <question>` when it cannot be resolved.
diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md
index 8f7cb4f7..bd5c4135 100644
--- a/plugins/aidd-refine/CATALOG.md
+++ b/plugins/aidd-refine/CATALOG.md
@@ -43,7 +43,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `assets` | [question-angles.md](skills/01-brainstorm/assets/question-angles.md) | - |
| `-` | [README.md](skills/01-brainstorm/README.md) | - |
| `references` | [probing.md](skills/01-brainstorm/references/probing.md) | - |
-| `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague idea through deep back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code.` |
+| `-` | [SKILL.md](skills/01-brainstorm/SKILL.md) | `Clarify a vague idea through deep questioning until it is precise enough to act on. Use when the user surfaces a half-formed idea or under-specified request, or asks to brainstorm or refine. Not for scanning an artifact for gaps or writing code.` |
#### `skills/02-challenge`
@@ -53,7 +53,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `assets` | [report-template.md](skills/02-challenge/assets/report-template.md) | - |
| `-` | [README.md](skills/02-challenge/README.md) | - |
| `references` | [confidence-rubric.md](skills/02-challenge/references/confidence-rubric.md) | - |
-| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink just-completed work against an agreed plan, classify findings as deal-breakers, suggestions, or correct, with a confidence score. Use to challenge a decision, criticize, or critically review recent work; not for line-by-line style review or writing code.` |
+| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.` |
#### `skills/03-condense`
@@ -63,7 +63,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `actions` | [02-stats.md](skills/03-condense/actions/02-stats.md) | - |
| `-` | [README.md](skills/03-condense/README.md) | - |
| `references` | [intensity-levels.md](skills/03-condense/references/intensity-levels.md) | - |
-| `-` | [SKILL.md](skills/03-condense/SKILL.md) | `Toggle terse output mode (lite, full, ultra) that drops filler while code, errors, and warnings stay verbatim, and report token savings for the session. Use to condense output, shorten answers, switch intensity, or check savings; not for editing prose or compressing code.` |
+| `-` | [SKILL.md](skills/03-condense/SKILL.md) | `Toggle terse output mode (lite, full, ultra) that drops filler while code and errors stay verbatim, and report token savings. Use to condense output, switch intensity, or check savings. Not for editing prose or compressing code.` |
#### `skills/04-shadow-areas`
@@ -78,7 +78,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `references` | [locked-sets.json](skills/04-shadow-areas/references/locked-sets.json) | - |
| `references` | [probe-style.md](skills/04-shadow-areas/references/probe-style.md) | - |
| `references` | [severity-rubric.md](skills/04-shadow-areas/references/severity-rubric.md) | - |
-| `-` | [SKILL.md](skills/04-shadow-areas/SKILL.md) | `Scan a markdown artifact (idea, user stories, PRD, spec) for blind spots and emit a structured shadow report grouped by category and sorted by severity. Use to find gaps, missing parts, or what's missing in a written artifact; not for interactive Q&A (use aidd-refine:01-brainstorm) or code review.` |
+| `-` | [SKILL.md](skills/04-shadow-areas/SKILL.md) | `Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow report grouped by category and severity. Use to find gaps or what is missing in a written artifact. Not for interactive Q&A or code review.` |
#### `skills/05-fact-check`
@@ -92,5 +92,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `references` | [claim-categories.md](skills/05-fact-check/references/claim-categories.md) | - |
| `references` | [report-output-discipline.md](skills/05-fact-check/references/report-output-discipline.md) | - |
| `references` | [verification-cascade.md](skills/05-fact-check/references/verification-cascade.md) | - |
-| `-` | [SKILL.md](skills/05-fact-check/SKILL.md) | `Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging anything unconfirmed. Use to fact-check, verify a claim, or cite sources on explicit request; not for judging code logic or clarifying vague requirements (use aidd-refine:01-brainstorm).` |
+| `-` | [SKILL.md](skills/05-fact-check/SKILL.md) | `Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging the unconfirmed. Use to fact-check, verify a claim, or cite sources on request. Not for judging code or clarifying requirements.` |
diff --git a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md
index 94b10962..9e095250 100644
--- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md
+++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md
@@ -1,6 +1,6 @@
---
name: 01-brainstorm
-description: Clarify a vague idea through deep back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code.
+description: Clarify a vague idea through deep questioning until it is precise enough to act on. Use when the user surfaces a half-formed idea or under-specified request, or asks to brainstorm or refine. Not for scanning an artifact for gaps or writing code.
argument-hint: capture | probe | integrate | finalize
---
@@ -17,9 +17,7 @@ Turns a vague idea into a precise one through a deep, natural conversation. Each
| 03 | `integrate` | Fold answers in, judge if real ambiguity remains | answers + the idea |
| 04 | `finalize` | Consolidate, flag open assumptions, offer to persist | the clarified idea |
-## Default flow
-
-`capture` once, then loop `probe → integrate` until no real ambiguity remains or the user is satisfied, then `finalize`. There is no fixed round count, the idea is done when it is clear, not on a timer. Run each action's `## Test` before the next.
+Run `capture`, loop `probe → integrate` until the idea is clear, then `finalize`.
## Transversal rules
diff --git a/plugins/aidd-refine/skills/02-challenge/SKILL.md b/plugins/aidd-refine/skills/02-challenge/SKILL.md
index 053694b9..6487af3c 100644
--- a/plugins/aidd-refine/skills/02-challenge/SKILL.md
+++ b/plugins/aidd-refine/skills/02-challenge/SKILL.md
@@ -1,6 +1,6 @@
---
name: 02-challenge
-description: Rethink just-completed work against an agreed plan, classify findings as deal-breakers, suggestions, or correct, with a confidence score. Use to challenge a decision, criticize, or critically review recent work; not for line-by-line style review or writing code.
+description: Rethink just-completed work against an agreed plan, classifying findings as deal-breaker, suggestion, or correct, with a confidence score. Use to challenge or critically review recent work. Not for line-by-line style review or writing code.
---
# Challenge
@@ -13,10 +13,6 @@ Rethink prior work and surface what is wrong, missing, or duplicated. Output a s
| --- | ----------- | ------------------------------------------------------------- | ------------------------------ |
| 01 | `challenge` | Rethink prior work, classify findings, score confidence | the work + agreed reference |
-## Default flow
-
-Single action skill. The router dispatches to `challenge` whenever the trigger phrases above appear.
-
## Transversal rules
- Reason from first principles, no logical gaps.
diff --git a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
index e7b0af23..a611f255 100644
--- a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
+++ b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md
@@ -2,8 +2,6 @@
My confidence level of correctness now: XX%
-# Previous work to review
-
# Correctness (100%)
-
diff --git a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
index ec220b4a..0d474d1b 100644
--- a/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
+++ b/plugins/aidd-refine/skills/02-challenge/references/confidence-rubric.md
@@ -4,7 +4,7 @@ The challenge action emits a confidence percentage. Pick the tier whose conditio
| Tier | Condition |
| --------- | ----------------------------------------------- |
-| `100%` | No deal breakers, no gaps, no missing parts. |
+| `100%` | No deal breakers, no gaps, no missing parts, no suggestions. |
| `75-95%` | Suggestions only, no blockers. |
| `50-74%` | Minor deal breakers, all fixable in place. |
| `<50%` | Major deal breakers, partial rework required. |
diff --git a/plugins/aidd-refine/skills/03-condense/SKILL.md b/plugins/aidd-refine/skills/03-condense/SKILL.md
index 93ea005f..0de0fbdb 100644
--- a/plugins/aidd-refine/skills/03-condense/SKILL.md
+++ b/plugins/aidd-refine/skills/03-condense/SKILL.md
@@ -1,6 +1,6 @@
---
name: 03-condense
-description: Toggle terse output mode (lite, full, ultra) that drops filler while code, errors, and warnings stay verbatim, and report token savings for the session. Use to condense output, shorten answers, switch intensity, or check savings; not for editing prose or compressing code.
+description: Toggle terse output mode (lite, full, ultra) that drops filler while code and errors stay verbatim, and report token savings. Use to condense output, switch intensity, or check savings. Not for editing prose or compressing code.
argument-hint: condense | stats
---
@@ -15,17 +15,12 @@ Toggles a terse output mode with three intensity levels (lite, full, ultra). Str
| 01 | `condense` | Toggle terse mode and apply intensity rules | current state + requested level |
| 02 | `stats` | Report real token usage and estimated savings for the current session | session messages + level timeline |
-## Default flow
-
-Router dispatches by intent:
-
-- Toggle phrase or intensity command (`condense`, `/condense full`, `stop condense`, `normal mode`, ...) → `01-condense`
-- Stats query (`/condense-stats`, `how much have we saved`, `token savings`, ...) → `02-stats`
+Dispatch by intent: a toggle phrase → `condense`, a savings query → `stats`.
## Transversal rules
- **Persistence**: once active, terse mode applies to EVERY response until explicitly turned off. Do not drift back to verbose prose after many turns, when uncertain, or when the task changes. The level remains active for the rest of the session unless changed or stopped.
-- **Off switch**: terse mode stops only on explicit user signal: `stop condense`, `normal mode`, `/condense off`, or invoking the skill again to toggle.
+- **Off switch**: terse mode stops only on explicit user signal: `stop condense`, `normal mode`, or invoking the skill again to toggle.
- **Toggle**: invoking the skill while active toggles it off; invoking while off turns it on at the default level (`full`) unless an explicit intensity is given.
- **Drop fluff**: drop articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), and hedging. Fragments are acceptable.
- **Short synonyms**: prefer short words (big not extensive, fix not "implement a solution for"). Technical terms stay exact. Code blocks are unchanged. Errors are quoted verbatim.
@@ -36,7 +31,3 @@ Router dispatches by intent:
## References
- `references/intensity-levels.md`: detailed per-level rules and side-by-side examples.
-
-## External data
-
-- `../hooks/condense-stats.js`: UserPromptSubmit hook that intercepts stats triggers, reads the session transcript, and returns the formatted savings report without invoking the model.
diff --git a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md
index dbdf45bb..92b3fa53 100644
--- a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md
+++ b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md
@@ -17,7 +17,7 @@ A single confirmation line: `Condense: ON (<level>).` when enabling, or `Condens
2. **Resolve.** Combine the current state with the request:
- Explicit level (`lite | full | ultra`) sets that level (or switches level if already on).
- `toggle` flips on/off; default level when turning on is `full`.
- - Off phrases (`stop condense`, `normal mode`, `/condense off`) force off.
+ - Off phrases (`stop condense`, `normal mode`) force off.
3. **Emit.** The reply MUST begin with this exact line, filled in and unaltered: `Condense: ON (<level>).` when enabling, or `Condense: OFF.` when disabling. The stats action and the hook parse this line from the transcript, so never paraphrase, decorate, or omit it.
4. **Apply.** Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules and auto-pause passages from `@../references/intensity-levels.md`.
diff --git a/plugins/aidd-refine/skills/03-condense/actions/02-stats.md b/plugins/aidd-refine/skills/03-condense/actions/02-stats.md
index 135f27ee..0501cf25 100644
--- a/plugins/aidd-refine/skills/03-condense/actions/02-stats.md
+++ b/plugins/aidd-refine/skills/03-condense/actions/02-stats.md
@@ -22,4 +22,5 @@ A stats block reporting, in order: mode, active turns and ratio, tokens out whil
## Test
-Output follows the `## Output` field order, every numeric field is filled (no `-`), and the active-turns ratio matches the detected intensity transitions.
+- The output follows the `## Output` field order, every numeric field filled (no `-`).
+- The active-turns ratio matches the detected intensity transitions.
diff --git a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md
index 1def8159..7aa637f9 100644
--- a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md
+++ b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md
@@ -1,6 +1,6 @@
---
name: 04-shadow-areas
-description: Scan a markdown artifact (idea, user stories, PRD, spec) for blind spots and emit a structured shadow report grouped by category and sorted by severity. Use to find gaps, missing parts, or what's missing in a written artifact; not for interactive Q&A (use aidd-refine:01-brainstorm) or code review.
+description: Scan a markdown artifact (idea, stories, PRD, spec) for blind spots into a shadow report grouped by category and severity. Use to find gaps or what is missing in a written artifact. Not for interactive Q&A or code review.
argument-hint: detect | render-report | diff
---
@@ -16,14 +16,7 @@ Analytically scans a written artifact for gaps the author has not addressed. Unl
| 02 | `render-report` | Render markdown grouped by category and sorted by severity, write report | gap list from detect |
| 03 | `diff` | Load prior report, classify gaps as closed / still-open / newly-introduced | gap list from detect + prior report path |
-## Default flow
-
-Router dispatches by context:
-
-- No prior report present: `01-detect` then `02-render-report`
-- Prior report present: `01-detect` then `03-diff` then `02-render-report`
-
-The `02-render-report` action always runs last and writes `<source>-shadow-report.md` next to the source.
+Dispatch by context: with no prior report run `detect` then `render-report`; with one, run `detect` then `diff`.
## Transversal rules
diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md
index 9460c674..3a7bdb83 100644
--- a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md
+++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md
@@ -14,7 +14,7 @@ A list of gaps, each with its category, severity, a probe question, and the quot
1. **Load.** Read the locked categories and their definitions from `@../references/locked-sets.json` and `@../references/categories.md`.
2. **Validate.** Check the source. Reject anything outside the working directory or already named `*-shadow-report.md`.
-3. **Handle edges.** An empty source emits one blocker gap asking what content the artifact should hold, then stops. A non-markdown source adds a warning that attribution may be imprecise, then continues.
+3. **Handle edges.** An empty source stops with a plain warning that there is nothing to scan, emitting no gap. A non-markdown source adds a warning that attribution may be imprecise, then continues.
4. **Scan.** Walk the seven categories in their locked order. Emit one gap per distinct issue, set its severity from `@../references/severity-rubric.md`, and write its question per `@../references/probe-style.md`.
5. **Dedupe.** Treat two gaps with the same category and snippet as one. A snippet-less gap falls back to its category plus severity.
6. **Return.** Hand the gaps and warnings to the next action: `03-diff` when a prior report exists, else `02-render-report`. Sorting happens there.
@@ -22,7 +22,7 @@ A list of gaps, each with its category, severity, a probe question, and the quot
## Test
- A path outside the working directory, or a file named `*-shadow-report.md`, is rejected with no gaps.
-- An empty source yields exactly one blocker gap about missing content.
+- An empty source stops with a warning and no gap.
- A non-markdown source adds one warning and keeps scanning.
- Every gap has a category and severity from the locked set and a question ending in `?`.
- A repeated gap (same category and snippet) appears once.
diff --git a/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md b/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md
index 595e5aa8..f8eb893b 100644
--- a/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md
+++ b/plugins/aidd-refine/skills/04-shadow-areas/assets/report-template.md
@@ -21,33 +21,12 @@ Total gaps: <total_count> | Blocker: <blocker_count> | Major: <major_count> | Mi
## Gaps by Category
-### unstated assumption
-
-No gaps in this category.
-
-### ambiguous term
-
-No gaps in this category.
-
-### missing edge case
-
-No gaps in this category.
-
-### missing actor
-
-No gaps in this category.
+<!-- Plain mode: one heading per category that has a gap, in locked order. A category with no gap is omitted. -->
-### missing failure mode
-
-No gaps in this category.
-
-### missing acceptance criterion
-
-No gaps in this category.
-
-### missing dependency
+### unstated assumption
-No gaps in this category.
+**[blocker]** What happens when the upstream service returns 429 with no Retry-After header?
+> retry_limit = env.get("RETRY_LIMIT", 3)
<!-- DIFF-MODE EXAMPLE (rendered only when 03-diff output is passed to 02-render-report)
diff --git a/plugins/aidd-refine/skills/05-fact-check/SKILL.md b/plugins/aidd-refine/skills/05-fact-check/SKILL.md
index 460737f8..89472839 100644
--- a/plugins/aidd-refine/skills/05-fact-check/SKILL.md
+++ b/plugins/aidd-refine/skills/05-fact-check/SKILL.md
@@ -1,6 +1,6 @@
---
name: 05-fact-check
-description: Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging anything unconfirmed. Use to fact-check, verify a claim, or cite sources on explicit request; not for judging code logic or clarifying vague requirements (use aidd-refine:01-brainstorm).
+description: Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging the unconfirmed. Use to fact-check, verify a claim, or cite sources on request. Not for judging code or clarifying requirements.
argument-hint: identify-claims | verify | report
---
@@ -16,9 +16,7 @@ Verifies the factual claims inside a target text and rewrites it grounded in evi
| 02 | `verify` | Run the verification cascade per claim, produce a verdict and sources | claim list from 01 |
| 03 | `report` | Rewrite the text with footnote citations, hedge unverified, surface conflicts | verdict list from 02 |
-## Default flow
-
-Sequential skill: `01 → 02 → 03`. No skipping. The router materializes the three actions as a task list on entry and closes each task only when its `## Test` passes.
+Run `01 → 02 → 03`; pass each `## Test` before the next.
## Transversal rules
@@ -30,7 +28,7 @@ Sequential skill: `01 → 02 → 03`. No skipping. The router materializes the t
- An unverified claim is never deleted and never asserted as fact: it is kept and marked `(unverified - no source found)`.
- Caching a verified fact is opt-in: propose it with a recommendation, never cache silently. The skill persists nothing; the mechanics live in action 03.
- The final report is reader-facing prose: the corrected text, `## Sources`, and `## Unverified claims`, nothing else. Internal mechanics never appear in the output: no cascade or tier trace (`Cascade:`, `tier 1/2/3`, `miss`, `resolved`), no category labels, no raw verdict words. State conclusions, not the process. Action 03 holds the exhaustive forbidden list.
-- The report is rendered in plain prose and is never restyled by an active session output mode (terse, caveman, condensed). The skill's output format is fixed by action 03 alone.
+- The report is rendered in plain prose and is never restyled by an active output mode. The skill's output format is fixed by action 03 alone.
## References
diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md
index e1c41cff..42e4b205 100644
--- a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md
+++ b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md
@@ -20,7 +20,7 @@ The rewritten answer per `@../assets/report-template.md`, obeying `@../reference
5. **Cite.** Build the `## Sources` block: one numbered entry per source, with its title or file path, location, and the claim it backs. Each side of a conflict gets its own entry.
6. **List.** Add the `## Unverified claims` section only when at least one claim is unverified; otherwise omit it.
7. **Suggest.** When a verified fact is stable (project paths, pinned-version APIs), append one cache-suggestion line with a yes/no recommendation. The skill stores nothing itself: on approval, restate the fact and its source so the user's own memory tooling can keep it. When nothing qualifies, omit the line silently.
-8. **Scrub.** Apply `@../references/report-output-discipline.md`, then deliver.
+8. **Scrub.** Before delivering, re-read the draft line by line against `@../references/report-output-discipline.md`: delete any line that carries a forbidden item, and re-render in plain prose any line an active output mode restyled. Ship plain prose whatever the surrounding style.
## Test
diff --git a/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md b/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md
index 05cf3955..8a9fc0ed 100644
--- a/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md
+++ b/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md
@@ -20,6 +20,6 @@ These belong to the earlier actions and never appear in the output:
- How a claim was checked: shell commands, `ls` / `find` / grep output, or phrases like "by inspection" or "codebase inspection". Cite the source and state the conclusion, not the method.
- Any sentence explaining why a cache line was or was not added.
-The report is plain prose. No active session output mode (terse, caveman, condensed) restyles it; render it normally however the surrounding conversation is styled.
+The report is plain prose. No active output mode restyles it; render it normally however the surrounding conversation is styled.
Before delivering, scan the draft: if a line carries any forbidden item, delete that line.
diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md
index 5b18635c..633d25f1 100644
--- a/plugins/aidd-ui/CATALOG.md
+++ b/plugins/aidd-ui/CATALOG.md
@@ -26,5 +26,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
|-------|------|---|
| `actions` | [01-greet.md](skills/01-hello/actions/01-greet.md) | - |
| `-` | [README.md](skills/01-hello/README.md) | - |
-| `-` | [SKILL.md](skills/01-hello/SKILL.md) | `Smoke-test skill that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Do NOT use for real UI or UX design work.` |
+| `-` | [SKILL.md](skills/01-hello/SKILL.md) | `Smoke-test that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Not for real UI or UX design work.` |
diff --git a/plugins/aidd-ui/skills/01-hello/SKILL.md b/plugins/aidd-ui/skills/01-hello/SKILL.md
index ce72346a..2191c739 100644
--- a/plugins/aidd-ui/skills/01-hello/SKILL.md
+++ b/plugins/aidd-ui/skills/01-hello/SKILL.md
@@ -1,14 +1,16 @@
---
name: 01-hello
-description: Smoke-test skill that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Do NOT use for real UI or UX design work.
+description: Smoke-test that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Not for real UI or UX design work.
---
-## Available actions
+# Skill: hello
-| ID | Name | Purpose |
-| --- | ----- | --------------------------------------------- |
-| 01 | greet | Greet the user and confirm the skill works. |
+Confirm the aidd-ui plugin loads and is reachable.
-## Default flow
+## Actions
-Run action `01-greet` and return its message.
+| # | Action | Role |
+| --- | ------- | ------------------------------------------- |
+| 01 | `greet` | Greet the user and confirm the skill works |
+
+Single action skill: run `greet` and return its message.
diff --git a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md
index 176cfcda..57b1aa82 100644
--- a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md
+++ b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md
@@ -1,15 +1,15 @@
# 01 - greet
-Greets the caller.
+Greet the caller to confirm the skill is reachable.
-## Inputs
+## Output
-- none
+A short greeting printed in the chat.
-## Outputs
+## Process
-- a short greeting printed in the chat
+1. **Print.** Print "Hello from aidd-ui (alpha)."
-## Process
+## Test
-1. Print "Hello from aidd-ui (alpha)."
+- The chat shows the line "Hello from aidd-ui (alpha)."
diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md
index d8f484c3..8ceb0414 100644
--- a/plugins/aidd-vcs/CATALOG.md
+++ b/plugins/aidd-vcs/CATALOG.md
@@ -32,26 +32,30 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `actions` | [02-publish.md](skills/00-repo-init/actions/02-publish.md) | - |
| `assets` | [CONTRIBUTING.md](skills/00-repo-init/assets/CONTRIBUTING.md) | - |
| `-` | [README.md](skills/00-repo-init/README.md) | - |
-| `-` | [SKILL.md](skills/00-repo-init/SKILL.md) | `Initialize a project's repository - resolve the default branch and VCS provider, run git init with a bootstrap commit, write CONTRIBUTING.md, and on request create the remote repository and push. Use when the user says "init a repo", "git init", "initialize version control", "set up a new repo", "start a project", "create the remote and push", or "publish this repo". Do NOT use for committing changes (use 01-commit), opening pull requests (use 02-pull-request), tagging releases (use 03-release-tag), or cloning an existing remote.` |
+| `-` | [SKILL.md](skills/00-repo-init/SKILL.md) | `Initialize a project repository: git init, default branch, bootstrap commit, CONTRIBUTING.md, optionally the remote. Use when the user wants to init or set up a new repo, or publish to a remote. Not for committing, opening a PR, or tagging.` |
#### `skills/01-commit`
| Group | File | Description |
|-------|------|---|
-| `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - |
+| `actions` | [01-collect.md](skills/01-commit/actions/01-collect.md) | - |
+| `actions` | [02-message.md](skills/01-commit/actions/02-message.md) | - |
+| `actions` | [03-commit.md](skills/01-commit/actions/03-commit.md) | - |
| `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` |
| `-` | [README.md](skills/01-commit/README.md) | - |
-| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release.` |
+| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.` |
#### `skills/02-pull-request`
| Group | File | Description |
|-------|------|---|
-| `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - |
+| `actions` | [01-collect.md](skills/02-pull-request/actions/01-collect.md) | - |
+| `actions` | [02-draft.md](skills/02-pull-request/actions/02-draft.md) | - |
+| `actions` | [03-create.md](skills/02-pull-request/actions/03-create.md) | - |
| `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` |
| `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` |
| `-` | [README.md](skills/02-pull-request/README.md) | - |
-| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch.` |
+| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use when the user wants to open a pull or merge request. Not for committing, pushing, or merging a branch.` |
#### `skills/03-release-tag`
@@ -60,7 +64,7 @@ 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.` |
+| `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with an annotated tag and release notes. Use when the user wants to release, tag a release, bump the version, or cut a version. Not for a plain commit, a pull request, or amending an existing tag.` |
#### `skills/04-issue-create`
@@ -70,5 +74,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
| `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.` |
+| `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user wants to file a bug, open an issue, or report a problem. Not for committing, opening a pull request, or commenting on an existing issue.` |
diff --git a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md
index a205e6dc..1374e47c 100644
--- a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md
+++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md
@@ -1,6 +1,6 @@
---
name: 00-repo-init
-description: Initialize a project's repository - resolve the default branch and VCS provider, run git init with a bootstrap commit, write CONTRIBUTING.md, and on request create the remote repository and push. Use when the user says "init a repo", "git init", "initialize version control", "set up a new repo", "start a project", "create the remote and push", or "publish this repo". Do NOT use for committing changes (use 01-commit), opening pull requests (use 02-pull-request), tagging releases (use 03-release-tag), or cloning an existing remote.
+description: Initialize a project repository: git init, default branch, bootstrap commit, CONTRIBUTING.md, optionally the remote. Use when the user wants to init or set up a new repo, or publish to a remote. Not for committing, opening a PR, or tagging.
argument-hint: init | publish
---
@@ -8,16 +8,14 @@ argument-hint: init | publish
Initializes a project's repository locally and, on request, on the remote host, then returns the remote URL.
-## Available actions
+## Actions
| # | Action | Role | Input |
| --- | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------- |
| 01 | `init` | Resolve VCS config, `git init`, set the default branch, write `CONTRIBUTING.md`, bootstrap commit | cwd, default_branch, remote_url |
| 02 | `publish` | Create the remote repo on the resolved host and push, return its URL | cwd, non_interactive |
-## Default flow
-
-Chain `01 → 02`, testing each before the next. The router runs `init` alone for a local-only request, and runs `publish` after an `init` when asked to create the remote.
+Run `01 → 02`. `init` alone for local-only; `publish` after it to create the remote.
## Transversal rules
@@ -29,7 +27,3 @@ Chain `01 → 02`, testing each before the next. The router runs `init` alone fo
## Assets
- `assets/CONTRIBUTING.md`: the project-root `CONTRIBUTING.md` template.
-
-## External data
-
-- `aidd_docs/memory/vcs.md`: the project's VCS config (default branch, provider), read by both actions when present and pointed to, never copied.
diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md
index 5ffc0b7c..ffe29da6 100644
--- a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md
+++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md
@@ -15,7 +15,7 @@ A report of the repo root, the resolved default branch and provider, and whether
## Process
1. **Guard.** If `cwd` is already a git work tree, skip and report `created: false`.
-2. **Resolve.** Read the default branch and provider from the project's VCS memory. If absent, infer the provider from the environment (an installed VCS CLI, a configured MCP, or an existing remote URL). Fall back to `main` when nothing resolves. An explicit `default_branch` wins.
+2. **Resolve.** Resolve the default branch and provider; an explicit `default_branch` wins.
3. **Init.** Run `git init -b <default_branch> <cwd>`.
4. **Contribute.** Write `CONTRIBUTING.md` at the repo root from the template, filling `{{PROJECT_NAME}}`. Leave no raw `{{...}}`.
diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md
index fe6a4499..87d19466 100644
--- a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md
+++ b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md
@@ -13,7 +13,7 @@ A report of the created remote URL, the resolved provider, and the pushed defaul
## Process
-1. **Resolve.** Read the host and how to reach it (CLI, MCP, or API) from the project's VCS memory. If absent, detect it from the VCS tooling available in the environment. Use no fixed provider list or fixed mechanism.
+1. **Resolve.** Resolve the host and how to reach it.
2. **Confirm.** Unless `non_interactive`, confirm before creating the remote. The remote may be public, so create it private by default.
3. **Create.** Create the remote repository and push through the resolved host tooling. `01-init` already left a pushable `HEAD`. If no host tooling is available, stop and report.
4. **Return.** Report the remote URL to the user.
diff --git a/plugins/aidd-vcs/skills/01-commit/README.md b/plugins/aidd-vcs/skills/01-commit/README.md
index 0cba0c3f..5f4a992f 100644
--- a/plugins/aidd-vcs/skills/01-commit/README.md
+++ b/plugins/aidd-vcs/skills/01-commit/README.md
@@ -31,8 +31,9 @@ Or via the slash command:
- `/commit` - stage, commit, stay local (`push: false`).
- `/commit push` - stage, commit, then push the branch (`push: true`).
-The skill runs a single action (`commit`) that stages, generates or accepts a
-message, commits, and optionally pushes.
+The skill chains three actions, collect then message then commit, that run
+end to end: stage one concern, write the conventional message, commit, and
+optionally push.
## Outputs
diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md
index 2f5168e8..0e03d244 100644
--- a/plugins/aidd-vcs/skills/01-commit/SKILL.md
+++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md
@@ -1,40 +1,33 @@
---
name: 01-commit
-description: Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release.
+description: Create an atomic git commit with a conventional message, optionally pushing. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.
+argument-hint: collect | message | commit
---
# Commit
-Runs interactive with split approval, or auto for agents.
+Stage the right changes, write the message, commit. `01 → 02 → 03`.
## Actions
-| # | Action | Role | Input |
-| --- | -------- | ------------------------------------------------------------- | ------------------------------------------- |
-| 01 | `commit` | Stage, generate or accept a message, commit, optionally push | mode, message, push, files |
+| # | Action | Step |
+| --- | --------- | ----------------------------------------------------- |
+| 01 | `collect` | Review the change and stage what belongs in one commit |
+| 02 | `message` | Write the conventional message |
+| 03 | `commit` | Commit, and push when asked |
-## Default flow
-
-Single action skill. The router dispatches to `commit` whenever a commit phrase or slash command appears.
-
-## Inline arguments
-
-When invoked as a slash command, the trailing argument controls the push behavior:
-
-- `/commit` → commits only, stays local (`push: false`)
-- `/commit push` → commits then pushes the branch (`push: true`)
+Several concerns means several commits: repeat the chain, one concern at a time.
## Transversal rules
-- Project first: follow `aidd_docs/memory/vcs.md` when it exists (message convention, scopes, branch naming); the rules below and the template are the fallback.
-- Commits stay atomic and focused on a single concern.
-- Messages use imperative mood ("Add feature" not "Added feature").
-- Explain "why" not "what" in the body.
-- Never `--force` push. `--force-with-lease` is acceptable when explicitly required.
-- Follow the conventional commit format defined in `@assets/commit-template.md` when the project sets none.
-- Reference issues in the commit body when applicable.
-- `auto` mode never asks for confirmation. `interactive` mode requires user approval before staging and before committing splits.
+- Follow the project's convention in `aidd_docs/memory/vcs.md` when set, else `assets/commit-template.md`.
+- One concern per commit. Imperative mood. The body says why, not what.
+- Reference the issue in the body when there is one.
+- Never `--force` push; `--force-with-lease` only when explicitly asked.
+- A hook that rejects the commit is not this skill's job: report which hook and why, then stop. Re-stage only files a hook auto-formatted.
+- `auto` never prompts. `interactive` confirms before staging and before each split.
+- Commits locally by default; pushes as well only when the push option is set.
## Assets
-- `@assets/commit-template.md`: Conventional commit format reference.
+- `assets/commit-template.md`: Conventional commit format reference.
diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md
new file mode 100644
index 00000000..ed6c1d34
--- /dev/null
+++ b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md
@@ -0,0 +1,22 @@
+# 01 - Collect
+
+Review the working change and stage what belongs in one atomic commit.
+
+## Input
+
+Optional paths to restrict the commit, and the mode (`interactive` default, or `auto`).
+
+## Output
+
+The staged set for one commit, and the concern it covers.
+
+## Process
+
+1. **Read.** Look at the diff and group it by concern.
+2. **Pick.** Stage the files for one concern. With explicit paths, stage exactly those; otherwise keep what is already staged, never adding unstaged files on your own.
+3. **Split.** When several concerns are mixed, stage one at a time with `git add -p`. In `interactive`, propose each split (its scope and why) and wait for approval.
+
+## Test
+
+- The staged set covers one concern, nothing unrelated.
+- Files the user did not name or stage are left untouched.
diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md
deleted file mode 100644
index 33238b71..00000000
--- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# 01 - Commit
-
-Stage the change, write or accept a conventional message, commit, optionally push, and return the sha.
-
-## Input
-
-The mode (`interactive` default, or `auto`), an optional imposed message, whether to push (default no, set by a trailing `push` in `$ARGUMENTS`), and optional paths to restrict staging.
-
-## Output
-
-The new commit sha, the branch, and whether it was pushed.
-
-## Process
-
-1. **Branch.** Use the checked-out branch. In `auto`, generate a conventional name from the change; in `interactive`, propose one and wait for approval.
-2. **Stage.** With explicit paths, `git add` exactly those. Otherwise commit the already-staged changes, never staging unstaged paths implicitly.
-3. **Message.** Use an imposed message verbatim. Else follow `aidd_docs/memory/vcs.md` when set, otherwise `@../assets/commit-template.md`. In `auto`, generate from the diff and log, no approval; in `interactive`, draft and confirm.
-4. **Split.** In `interactive` with several concerns, propose each split (its scope, and a draft message that explains why, never lists files), wait for approval, and stage each with `git add -p`.
-5. **Commit.** Run `git commit` with the chosen message.
-6. **Recover.** On a pre-commit hook failure, fix the cause, re-stage, and make a new commit, never amend. Loop until it succeeds.
-7. **Push.** When asked, `git push`. Use `--force-with-lease` only when explicitly required, never `--force`.
-8. **Return.** Surface the sha, branch, and push state.
-
-## Test
-
-- `git rev-parse HEAD` equals the returned sha.
-- `git log -1 --pretty=%s` matches the conventional-commit format.
-- When pushed, `git ls-remote origin <branch>` lists the sha.
diff --git a/plugins/aidd-vcs/skills/01-commit/actions/02-message.md b/plugins/aidd-vcs/skills/01-commit/actions/02-message.md
new file mode 100644
index 00000000..f4254a50
--- /dev/null
+++ b/plugins/aidd-vcs/skills/01-commit/actions/02-message.md
@@ -0,0 +1,22 @@
+# 02 - Message
+
+Write the commit message for the staged change.
+
+## Input
+
+The staged set from `01-collect`, and an optional imposed message.
+
+## Output
+
+The commit message, conventional unless the project sets another convention.
+
+## Process
+
+1. **Source.** Use an imposed message as-is, else write a conventional message following the project's convention.
+2. **Write.** Draft from the staged diff: imperative subject, a body that says why when it is not obvious.
+3. **Confirm.** In `interactive`, show it and wait for approval. In `auto`, proceed.
+
+## Test
+
+- The subject matches the project's convention (conventional commit by default).
+- The message describes the staged change, not unrelated files.
diff --git a/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md
new file mode 100644
index 00000000..49d2a7aa
--- /dev/null
+++ b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md
@@ -0,0 +1,23 @@
+# 03 - Commit
+
+Record the commit, and push when asked.
+
+## Input
+
+The staged set from `01-collect`, the message from `02-message`, and whether to push (a trailing `push` argument).
+
+## Output
+
+The commit sha, the branch, and whether it was pushed.
+
+## Process
+
+1. **Commit.** Run `git commit` with the message.
+2. **Hook.** If a pre-commit hook rejects it, report which hook and why, then stop; fixing it is the caller's job. Re-stage and retry once only when the hook merely auto-formatted files.
+3. **Push.** When asked, push the branch. Use `--force-with-lease` only when explicitly required, never `--force`.
+
+## Test
+
+- `git rev-parse HEAD` returns the new sha and its message matches the project convention.
+- A rejecting hook leaves no commit and a clear report, not a retry loop.
+- When pushed, the remote branch shows the sha.
diff --git a/plugins/aidd-vcs/skills/02-pull-request/README.md b/plugins/aidd-vcs/skills/02-pull-request/README.md
index 82dbe60f..8482dc0d 100644
--- a/plugins/aidd-vcs/skills/02-pull-request/README.md
+++ b/plugins/aidd-vcs/skills/02-pull-request/README.md
@@ -29,9 +29,9 @@ Use skill aidd-vcs:02-pull-request
Or via the slash command: `/pull-request`.
-The skill runs a single action (`pull-request`) that detects the base
-branch, fills the template, validates the title / body / base with the user,
-then opens the request as a draft.
+The skill chains three actions, collect then draft then create: collect
+resolves the base and gathers the commits, draft writes and validates the
+title and body, create opens the request as a draft.
## Outputs
@@ -51,5 +51,5 @@ then opens the request as a draft.
## Technical details
See [`SKILL.md`](SKILL.md) for the action contract. Templates ship in
-[`assets/`](assets/): `pull_request.md` (request body), `branch.md` (naming
-conventions), `CONTRIBUTING.md`, and `README.md`.
+[`assets/`](assets/): `pull_request.md` (request body) and `branch.md` (naming
+conventions).
diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md
index af224d27..44955ff2 100644
--- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md
+++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md
@@ -1,33 +1,31 @@
---
name: 02-pull-request
-description: Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch.
+description: Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use when the user wants to open a pull or merge request. Not for committing, pushing, or merging a branch.
+argument-hint: collect | draft | create
---
# Pull Request
-Drafts pull or merge requests from the current branch using the team's template, ready for the user to promote.
+Collect the change, draft the request, create it as a draft. `01 → 02 → 03`.
## Actions
-| # | Action | Role | Input |
-| --- | --------------- | ------------------------------------------------------------------- | ---------------------------------------------- |
-| 01 | `pull-request` | Detect base, fill template, validate with user, open the draft request | base_branch (optional), template_overrides |
-
-## Default flow
-
-Single action skill. The router dispatches to `pull-request` whenever a PR/MR phrase or slash command appears.
+| # | Action | Step |
+| --- | --------- | ----------------------------------------------------------- |
+| 01 | `collect` | Resolve the base and gather the commits since it |
+| 02 | `draft` | Write the title and body from the template |
+| 03 | `create` | Open the draft request, label it, return the URL |
## Transversal rules
-- Project first: follow `aidd_docs/memory/vcs.md` and the repo's own request-template file when they exist (body sections, base rules, labels); the rules below and the bundled templates are the fallback.
-- Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`).
-- Always ask the user to validate the title, body, and base branch before creating the request.
-- Open the request as a draft. The user promotes it manually when ready.
-- After opening, apply the triage label the branch prefix maps to, when that label exists; labels triage only, they never change the resolved base.
-- Never commit, never push the working branch, never create new branches inside this skill.
-- Tool-agnostic: read the VCS tool from project memory; fall back to inspecting the remote URL.
+- Follow the project's request practices in `aidd_docs/memory/vcs.md` and the repo's own request template when set, else the bundled `assets/pull_request.md`.
+- Resolve the base from the branch's prefix per the project's convention (`vcs.md`), else the repo's default branch. Never assume `main`.
+- The request is always a draft; the user promotes it.
+- Apply only the triage label the branch prefix maps to, when it exists. Labels never change the base.
+- Read the VCS tool from project memory, else infer it from the remote URL.
+- Never commit, push, or branch here.
## Assets
-- `@assets/pull_request.md`: Request body template.
-- `@assets/branch.md`: Branch-naming convention, the fallback when project memory sets none.
+- `assets/pull_request.md`: Request body template.
+- `assets/branch.md`: Branch-naming convention, the fallback when project memory sets none.
diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-collect.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-collect.md
new file mode 100644
index 00000000..ef5042d9
--- /dev/null
+++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-collect.md
@@ -0,0 +1,22 @@
+# 01 - Collect
+
+Resolve the base branch and gather the change to describe.
+
+## Input
+
+An optional base branch, overriding the resolved one.
+
+## Output
+
+The VCS tool, the head and base branches, and the commits and changed files since the base.
+
+## Process
+
+1. **Tool.** Use the VCS tool from project memory, else infer it from the remote URL.
+2. **Base.** Use a provided base, else resolve it per the project's branch convention, else the repo's default branch. Surface the base and why.
+3. **Gather.** Summarize the commits and changed files since the base.
+
+## Test
+
+- The resolved base matches the branch prefix when one maps, not a blind `main`.
+- The summary reflects the commits between base and head.
diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md
deleted file mode 100644
index e09f008e..00000000
--- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# 01 - Pull Request
-
-Detect the base branch, fill the request template from the recent commits, validate with the user, and open a draft request via the configured VCS tool.
-
-## Input
-
-An optional base branch (auto-detected when omitted), and optional title or body overrides.
-
-## Output
-
-The draft request's URL and number, with its head and resolved base branch.
-
-## Process
-
-1. **Tool.** Use the VCS tool declared in project memory, otherwise map `git remote get-url origin` to the matching configured tool.
-2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`.
-3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason.
-4. **Collect.** Summarize the commits and impacted files with `git log <base>..HEAD` and `git diff <base>...HEAD --stat`.
-5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's request-template file) over the bundled one, plus any contributing rules; write a concise title and body from the change summary.
-6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval.
-7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number.
-8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base.
-9. **Return.** Surface the URL, number, head, and base.
-
-## Test
-
-- The created request exists with `base` equal to the resolved base and the draft flag true.
-- A head branch whose prefix is mapped resolves the base to that target, not the `origin/HEAD` default.
-- When the head prefix maps to an existing triage label, the request carries it.
-- The request is reachable at its URL with the head branch as its source.
diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md b/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md
new file mode 100644
index 00000000..36b5c4e6
--- /dev/null
+++ b/plugins/aidd-vcs/skills/02-pull-request/actions/02-draft.md
@@ -0,0 +1,22 @@
+# 02 - Draft
+
+Write the request title and body from the change.
+
+## Input
+
+The collected base, commits, and changed files from `01-collect`, and optional title or body overrides.
+
+## Output
+
+The proposed title, body, and base, approved by the user.
+
+## Process
+
+1. **Template.** Load the request template, the project's own when set, else the bundled `@../assets/pull_request.md`.
+2. **Write.** Draft a concise title and a body following the template from the change summary.
+3. **Confirm.** Show the title, body, and base, apply any overrides, and wait for approval.
+
+## Test
+
+- The body follows the project's template sections when one exists.
+- The user approved the title, body, and base before creation.
diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md b/plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md
new file mode 100644
index 00000000..54f86c08
--- /dev/null
+++ b/plugins/aidd-vcs/skills/02-pull-request/actions/03-create.md
@@ -0,0 +1,23 @@
+# 03 - Create
+
+Open the approved draft request and label it.
+
+## Input
+
+The approved title, body, and base from `02-draft`.
+
+## Output
+
+The draft request's URL and number, with its head and base.
+
+## Process
+
+1. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body.
+2. **Label.** When the head prefix maps to a triage label that exists, apply it; skip silently otherwise.
+3. **Return.** Surface the URL, number, head, and base.
+
+## Test
+
+- The request exists as a draft with its base equal to the resolved base.
+- A mapped, existing triage label is applied; an absent one is skipped without error.
+- The request is reachable at its URL with the head branch as its source.
diff --git a/plugins/aidd-vcs/skills/03-release-tag/SKILL.md b/plugins/aidd-vcs/skills/03-release-tag/SKILL.md
index 884151f7..3fbe0ab5 100644
--- a/plugins/aidd-vcs/skills/03-release-tag/SKILL.md
+++ b/plugins/aidd-vcs/skills/03-release-tag/SKILL.md
@@ -1,39 +1,27 @@
---
name: 03-release-tag
-description: Cut a semver release with annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags.
+description: Cut a semver release with an annotated tag and release notes. Use when the user wants to release, tag a release, bump the version, or cut a version. Not for a plain commit, a pull request, or amending an existing tag.
---
# Release Tag
Cuts annotated semver releases with notes derived from recent commits.
-## Available actions
+## Actions
| # | Action | Role | Input |
| --- | -------------- | -------------------------------------------------------------------------- | ---------------------------------- |
| 01 | `release-tag` | Compute version, draft notes, validate, bump, tag, push | version (optional), notes_overrides|
-## Default flow
-
-Single action skill. The router dispatches to `release-tag` whenever a release or tag phrase appears.
-
## Transversal rules
- Versions follow semver `major.minor.patch` strictly. No suffixes unless explicitly requested.
- Tags are annotated (`git tag -a`), never lightweight.
-- Release notes are mandatory and follow `@assets/release-template.md`.
+- Release notes are mandatory and follow `assets/release-template.md`.
- Always ask the user to validate the version, notes, and impacted files before tagging.
- Never `--force` push tags. Use `--force-with-lease` only when explicitly required.
- The bump commit only includes version-manager files (e.g. `package.json`, `pyproject.toml`).
-## References
-
-- None.
-
## Assets
-- `@assets/release-template.md`: Release notes template.
-
-## External data
-
-- None.
+- `assets/release-template.md`: Release notes template.
diff --git a/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md b/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md
index 0e14067b..b8c0dcf8 100644
--- a/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md
+++ b/plugins/aidd-vcs/skills/03-release-tag/actions/01-release-tag.md
@@ -2,51 +2,30 @@
Compute the next semver version from recent commits, draft release notes from the template, validate with the user, create a bump commit, then tag and push.
-## Inputs
+## Input
-```yaml
-version: <semver> # optional; auto-computed from commits since last tag when omitted
-notes_overrides: # optional; impose specific notes content
- title: <imposed title>
- body: <imposed body>
-```
+An optional explicit semver version (auto-computed from commits since the last tag when omitted), and optional note overrides imposing a specific title and body.
-## Outputs
+## Output
-```yaml
-tag: v<semver>
-commit_sha: <bump commit sha>
-pushed: true
-release_url: <url>
-```
+The created `v<semver>` tag, its bump commit sha, and the release URL, with the tag pushed to the remote.
## Process
-1. **Read current version**. Pick first match:
- - version manager file present (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.) -> read its version field
- - default -> `1.0.0`
-2. **Read latest tag**. Pick first match:
- - `git tag --sort=-version:refname | head -1` non-empty -> use it
- - default -> treat as `v1.0.0`
-3. **Collect commits**. Run `git log --oneline "<latest>..HEAD"`.
-4. **Compute next version**. Pick first match:
- - `version` input provided -> use it
- - any commit body contains `BREAKING CHANGE` -> bump major
- - any commit type is `feat` -> bump minor
- - default -> bump patch
-5. **Draft release notes**. Fill `assets/release-template.md` with the change list from step 3. Apply `notes_overrides` when provided.
-6. **Validate**. Show full notes, computed version, and version-manager files about to change. Wait for explicit user approval.
-7. **Bump commit**. Stage only version-manager files. Create a `chore: bump version to v<semver>` commit via heredoc.
-8. **Create tag**. Run `git tag -a v<semver> -m <notes title>`.
-9. **Push commit**. Run `git push`.
-10. **Push tag**. Run `git push origin v<semver>`.
-11. **Resolve release URL**. Pick first match:
- - configured VCS tool exposes a release-view command -> capture the returned URL
- - default -> compose URL from `git remote get-url origin` and the tag name
+1. **Current.** Read the version from a version-manager file (`package.json`, `pyproject.toml`, `Cargo.toml`) when present, else `1.0.0`.
+2. **Latest.** Take the latest tag from `git tag --sort=-version:refname | head -1`. When there are no tags, note that there is no prior tag, never inventing one.
+3. **Collect.** With a prior tag, list the commits in `<latest>..HEAD`. With no prior tag, list every commit on the branch.
+4. **Compute.** Use the provided version when given. Otherwise bump major on a `BREAKING CHANGE`, minor on any `feat`, else patch.
+5. **Draft.** Fill `@../assets/release-template.md` with the change list, applying any note overrides.
+6. **Validate.** Show the full notes, the computed version, and the version-manager files about to change. Wait for explicit approval.
+7. **Bump.** Stage the version-manager files and create a `chore: bump version to v<semver>` commit.
+8. **Tag.** Run `git tag -a v<semver> -m <notes title>`.
+9. **Push.** Push the commit, then push the tag with `git push origin v<semver>`.
+10. **URL.** Capture the release URL from the configured VCS tool's release view when it has one, else compose it from the remote URL and the tag.
## Test
-- **Local tag**: `git tag -l v<semver>` returns the new tag exactly once.
-- **Semver shape**: the tag matches `^v[0-9]+\.[0-9]+\.[0-9]+$`.
-- **Remote tag**: `git ls-remote --tags origin "refs/tags/v<semver>"` returns one row, confirming the tag is on the remote.
-- **Commit link**: `git rev-parse "v<semver>^{commit}"` resolves to the bump commit sha returned in Outputs.
+- `git tag -l v<semver>` returns the new tag exactly once.
+- The tag matches `^v[0-9]+\.[0-9]+\.[0-9]+$`.
+- `git ls-remote --tags origin "refs/tags/v<semver>"` returns one row.
+- `git rev-parse "v<semver>^{commit}"` resolves to the returned bump commit sha.
diff --git a/plugins/aidd-vcs/skills/04-issue-create/SKILL.md b/plugins/aidd-vcs/skills/04-issue-create/SKILL.md
index 0f28c566..60c074f3 100644
--- a/plugins/aidd-vcs/skills/04-issue-create/SKILL.md
+++ b/plugins/aidd-vcs/skills/04-issue-create/SKILL.md
@@ -1,40 +1,28 @@
---
name: 04-issue-create
-description: Create an issue in the configured ticketing tool. Use when the user says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues.
+description: Create an issue in the configured ticketing tool. Use when the user wants to file a bug, open an issue, or report a problem. Not for committing, opening a pull request, or commenting on an existing issue.
---
# Issue Create
Files well-formed issues in the configured tracker after gathering enough context to be actionable.
-## Available actions
+## Actions
| # | Action | Role | Input |
| --- | --------------- | -------------------------------------------------------------------------- | -------------------------------------- |
| 01 | `issue-create` | Detect tool, fill template, validate, open the issue | problem_description, labels, type |
-## Default flow
-
-Single action skill. The router dispatches to `issue-create` whenever an issue or bug-report phrase appears.
-
## Transversal rules
-- Detect the ticketing tool from project memory first, then fall back to inspecting `git remote get-url origin`.
+- Detect the ticketing tool from project memory first, then fall back to inferring it from the remote URL.
- Tool-agnostic: invoke whichever ticketing tool is configured for the project.
- Always wait for explicit user approval of title, body, labels, type, projects, and milestones before creating.
-- Issue body follows `@assets/issue-template.md`.
+- Issue body follows `assets/issue-template.md`.
- Be thorough and concise. Short sentences. Focus on clarity, reproduction steps, and expected behavior.
-- Read `@assets/CONTRIBUTING.md` for project-specific issue rules before drafting.
-
-## References
-
-- None.
+- Read `assets/CONTRIBUTING.md` for project-specific issue rules before drafting.
## Assets
-- `@assets/issue-template.md`: Issue / ticket body template.
-- `@assets/CONTRIBUTING.md`: Contribution guidelines, including issue process.
-
-## External data
-
-- None.
+- `assets/issue-template.md`: Issue / ticket body template.
+- `assets/CONTRIBUTING.md`: Contribution guidelines, including issue process.
diff --git a/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md b/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md
index e81a921a..e0419bc5 100644
--- a/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md
+++ b/plugins/aidd-vcs/skills/04-issue-create/actions/01-issue-create.md
@@ -2,42 +2,25 @@
Detect the ticketing tool, gather a thorough problem description, fill the issue template, validate with the user, then create the issue.
-## Inputs
-
-```yaml
-problem_description: <free text> # required
-repo_url: <url> # optional; default: derived from `git remote get-url origin`
-labels: [<label>] # optional
-type: bug | feature | task | docs # optional; default: inferred from description
-projects: [<project>] # optional
-milestone: <milestone> # optional
-```
-
-## Outputs
-
-```yaml
-tool: <configured ticketing tool>
-issue_url: <url>
-issue_number: <int>
-title: <issue title>
-labels: [<label>]
-type: <type>
-```
+## Input
+
+A problem description (required), plus optional labels, projects, a milestone, and a repo URL (inferred from the remote when omitted).
+
+## Output
+
+The created issue's URL and number, with its title and labels.
## Process
-1. **Tool resolution**. Pick first match:
- - ticketing tool declared in project memory -> use it
- - default -> map `git remote get-url origin` to the matching configured tool
-2. **Read context**. Load `assets/CONTRIBUTING.md` and `assets/issue-template.md`. Skim existing open issues via the configured tool to avoid duplicates.
-3. **Gather details**. Combine `problem_description` with technical context (stack, repro steps, environment). Ask the user follow-up questions when required fields are missing.
-4. **Web search**. Look up official documentation that backs the issue when applicable (e.g. linked errors, framework changelog).
-5. **Fill template**. Generate a concise title and body that match the template structure. Pick a `type` (bug, feature, task, docs) when not provided.
-6. **Validate**. Show title, body, labels, type, projects, and milestone. Wait for explicit user approval.
-7. **Create**. Invoke the configured ticketing tool to open the issue, passing title, body, labels, projects, and milestone.
-8. **Capture** the returned URL and number. Return the structured Outputs block.
+1. **Tool.** Use the ticketing tool declared in project memory. Otherwise infer it from the remote URL.
+2. **Context.** Load `@../assets/CONTRIBUTING.md` and `@../assets/issue-template.md`, and skim existing open issues via the tool to avoid duplicates.
+3. **Gather.** Combine the problem description with technical context (stack, repro steps, environment). Ask follow-up questions when required fields are missing.
+4. **Research.** Look up official documentation that backs the issue when applicable (linked errors, framework changelog).
+5. **Fill.** Write a concise title and body matching the template.
+6. **Validate.** Show the title, body, labels, projects, and milestone. Wait for explicit approval.
+7. **Create.** Invoke the configured tool to open the issue, passing the title, body, labels, projects, and milestone, then capture the returned URL and number.
## Test
-- **Tool view**: querying the configured ticketing tool for the created issue returns a record where `url` equals `issue_url`, `title` equals the validated title, and `labels` matches the validated labels.
-- **Reachable**: the created issue is reachable at `issue_url` in the tracker UI.
+- Querying the configured tool for the created issue returns a record whose URL, title, and labels match the validated values.
+- The created issue is reachable at its URL in the tracker UI.
diff --git a/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md b/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md
index 57b2b8b8..0f7af87b 100644
--- a/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md
+++ b/plugins/aidd-vcs/skills/04-issue-create/assets/issue-template.md
@@ -8,7 +8,7 @@ argument-hint: N/A
AI instructions:
-- be focused on creating clear, concise, and actionable GitHub issues.
+- be focused on creating clear, concise, and actionable issues in the configured tracker.
- no over-thinking nor over-complicating.
-->