diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..eacfdb50 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,66 @@ +# AGENTS.md + +> IMPORTANT: On first conversation message: +> +> - say "AI-Driven Development (v4.x.001) - Date: {current_date}, TZ: {current_timezone}." to User. + +## Behavior Guidelines + +Treat instructions/info above as possibly stale. USER can be wrong; stay critical, verify against project's actual state. + +- Be anti-sycophantic +- Challenge USER reasoning +- No flattery, no over-engineering. +- Simple is better. + +## Action specific + +- Do not commit or push yourself unless I ask you to. +- For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. +- Never duplicate across docs - link to the canonical home. + +For every asked action: + +1. **Think Before**: Don't assume. Don't hide confusion. Surface tradeoffs. +2. **Simplicity First**: Minimum that solves the problem; anticipate in thoughts, not in writing. +3. **Surgical Changes**: Touch only what you must. Leave the place cleaner than you found it. +4. **Goal-Driven Execution**: Define success criteria, turn imperative tasks into verifiable goals, loop until verified. + +## Communication + +Essential without losing clarity. + +- Minimal words, like a caveman. +- **Less is more**: minimal output without losing sense. +- Drop articles, fragments OK, short synonyms, no filler/hedging. +- Strip conjunctions, arrows for causality (X → Y), one word when one word enough. + +## Writing + +- No excessive docs, bare minimum. +- Minimal but effective guidelines. +- **Prefer removing over adding**. + +## Answering + +- Don't assume your knowledge is up to date. +- If unsure, say "I don't know". +- You are super smart, try to solve your own issues. + +## Memory + + +@aidd_docs/memory/architecture.md +@aidd_docs/memory/browsing.md +@aidd_docs/memory/codebase-map.md +@aidd_docs/memory/coding-assertions.md +@aidd_docs/memory/deployment.md +@aidd_docs/memory/project-brief.md +@aidd_docs/memory/testing.md +@aidd_docs/memory/vcs.md + + +- If memory not loaded above: run `ls -1tr aidd_docs/memory/` then read each file +- If needed: load files from: + - `aidd_docs/memory/external/*` when user request it + - `aidd_docs/memory/internal/*`, you have to think about it diff --git a/CLAUDE.md b/CLAUDE.md index bf7514c5..a651c526 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,33 +2,50 @@ > IMPORTANT: On first conversation message: > -> - say "AI-Driven Development ON - Date: {current_date}, TZ: {current_timezone}." to User. +> - say "AI-Driven Development (v4.x.001) - Date: {current_date}, TZ: {current_timezone}." to User. ## Behavior Guidelines -All instructions and information above are willing to be up to date, but always remind yourself that USER can be wrong, be critical of the information provided, and verify it against the project's actual state. +Treat instructions/info above as possibly stale. USER can be wrong; stay critical, verify against project's actual state. -- Be anti-sycophantic - don't fold arguments just because I push back -- Stop excessive validation - challenge my reasoning instead -- Avoid flattery that feels like unnecessary praise -- Don't anthropomorphize yourself +- Be anti-sycophantic +- Challenge USER reasoning +- No flattery, no over-engineering. +- Simple is better. -## Technical guidelines +## Action specific -- Do not commit or push yourself unless I ask you to. -- For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. -- Never duplicate across docs - link to the canonical home. +1. **Think Before**: Don't assume. Don't hide confusion. Surface tradeoffs. +2. **Simplicity First**: Minimum that solves the problem; anticipate in thoughts, not in writing. +3. **Surgical Changes**: Touch only what you must. Leave the place cleaner than you found it. +4. **Goal-Driven Execution**: Define success criteria, turn imperative tasks into verifiable goals, loop until verified. +5. **Do not commit or push** yourself unless I ask you to. +6. **Placement discipline**: for every plugin change, think hard about where responsibility belongs; follow `docs/ARCHITECTURE.md`. +7. **Never duplicate across docs** - link to the canonical home. -### Answering Guidelines +## Communication -- Don't assume your knowledge is up to date. -- Be 100% sure of your answers. -- If unsure, say "I don't know" or ask for clarification. -- Never say "you are right!", prefer anticipating mistakes. +Essential without losing clarity: always answer in min words. + +- Minimal words, like a caveman. +- **Less is more**: minimal output without losing sense. +- Drop articles, fragments OK, short synonyms, no filler/hedging. +- Strip conjunctions, arrows for causality (X → Y), one word when one word enough. + +## Writing -## Memory Management +- No excessive docs, bare minimum. +- Minimal but effective guidelines. +- **Prefer removing over adding**. + +## Answering + +- Before answer a tech question, ask yourself if this is a good practice. +- Don't assume your knowledge is up to date. +- If unsure, say "I don't know". +- You are super smart, try to solve your own issues. -### Project memory +## Memory @aidd_docs/memory/architecture.md @@ -41,6 +58,7 @@ All instructions and information above are willing to be up to date, but always @aidd_docs/memory/vcs.md -- If memory is not loaded above: run `ls -1tr aidd_docs/memory/` then read each file -- If needed: load files from `aidd_docs/memory/external/*` when user request it -- If needed: load files from `aidd_docs/memory/internal/*`, you have to think about it +- If memory not loaded above: run `ls -1tr aidd_docs/memory/` then read each file +- If needed: load files from: + - `aidd_docs/memory/external/*` when user request it + - `aidd_docs/memory/internal/*`, you have to think about it diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b051d232..939f108c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,78 +31,29 @@ flowchart TD ## 1. Set up -Needs **Node 20+** and **pnpm**, plus **jq**, **python3**, and **pipx** for the pre-commit hooks (`gh` optional). Then: +Needs **Node 20+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). Then: ```bash -pnpm install -pnpm exec lefthook install +make setup ``` -Every commit then runs the framework checks (json/yaml validity, schema validation, SKILL.md frontmatter, CATALOG regeneration, commitlint). Check your environment anytime with `./scripts/doctor.sh`. +- installs deps + git hooks +- registers this checkout as a local marketplace +- installs the plugins into Claude + Codex (`y/N` confirm, since it writes your global config; `YES=1` skips) -### Test your changes locally - -Before opening a PR, exercise the skills you touched in a real session. Clone the framework, then point your assistant at the checkout instead of a published release: - -```bash -git clone https://github.com/ai-driven-dev/framework ~/projects/framework -``` - -#### Claude Code +`make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks. -Register the checkout as a local marketplace, then install the plugins: - -```text -/plugin marketplace add ~/projects/framework -/plugin install aidd-context@aidd-framework -/plugin install aidd-dev@aidd-framework -/plugin install aidd-vcs@aidd-framework -/plugin install aidd-pm@aidd-framework -/plugin install aidd-orchestrator@aidd-framework -/plugin install aidd-refine@aidd-framework -``` - -After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in the same session to pick up the change - no reinstall needed. - -To load the plugins into a personal project, point its `.claude/settings.local.json` at the checkout: - -```json -{ - "extraKnownMarketplaces": { - "aidd-framework": { - "source": { - "source": "directory", - "path": "~/projects/framework" - } - } - }, - "enabledPlugins": { - "aidd-context@aidd-framework": true, - "aidd-dev@aidd-framework": true, - "aidd-vcs@aidd-framework": true, - "aidd-pm@aidd-framework": true, - "aidd-orchestrator@aidd-framework": true, - "aidd-refine@aidd-framework": true - } -} -``` - -#### Codex +### Test your changes locally -Register the checkout (pass an absolute path; `./` is rejected), then install the plugins: +Exercise the skills you touched before opening a PR. Neither tool hot-reloads the checkout (both serve a copied cache), so after editing: ```bash -codex plugin marketplace add ~/projects/framework -codex plugin add aidd-context@aidd-framework -codex plugin add aidd-dev@aidd-framework -codex plugin add aidd-vcs@aidd-framework -codex plugin add aidd-pm@aidd-framework -codex plugin add aidd-orchestrator@aidd-framework -codex plugin add aidd-refine@aidd-framework -codex plugin list --marketplace aidd-framework # confirm every plugin is `installed, enabled` +make reload # all plugins; or PLUGIN="aidd-refine aidd-pm" for a subset ``` -No live reload - run `codex plugin marketplace upgrade` after each change to refresh. +- reinstalls each plugin from the checkout (current versions, no bump - nothing to revert) +- purges + refreshes the cache in Claude + Codex +- restart the session to load it (`/reload-plugins` covers a Claude-only edit to an existing skill) ## 2. Commit diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..fe725583 --- /dev/null +++ b/Makefile @@ -0,0 +1,21 @@ +PLUGIN ?= all + +.DEFAULT_GOAL := help +.PHONY: help setup doctor check reload + +help: ## List targets + @grep -hE '^[a-z-]+:.*##' $(MAKEFILE_LIST) | sed 's/:.*## /\t/' | sort + +setup: ## Install deps, git hooks, and register+install the plugins in Claude/Codex + pnpm install + pnpm exec lefthook install + scripts/dev-setup.sh + +doctor: ## Check the local toolchain + ./scripts/doctor.sh + +check: ## Run the pre-commit checks + pnpm exec lefthook run pre-commit + +reload: ## Dev: reinstall plugins into Claude+Codex from the checkout (PLUGIN="aidd-refine aidd-pm", default all) + scripts/dev-sync.sh $(PLUGIN) diff --git a/README.md b/README.md index 7024076b..417ef52e 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ### A community-maintained marketplace of skills, agents, and rules for Claude Code.

- 6 plugins · 37 skills · 3 agents · MIT + 6 plugins · 40 skills · 3 agents · MIT

@@ -137,7 +137,7 @@ that tool's model via the **LLM tier reference** below. ### 🧭 [aidd-context](plugins/aidd-context/README.md) -`12 skills` · stable +`13 skills` · stable Project init, architecture, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), diagrams, learning, discovery. @@ -155,7 +155,7 @@ SDLC loop: sdlc, plan, implement, assert, audit, review, test, refactor, debug, ### 🌿 [aidd-vcs](plugins/aidd-vcs/README.md) -`4 skills` · stable +`5 skills` · stable Commits, pull / merge requests, release tags, issue creation. @@ -184,7 +184,7 @@ Meta-cognition: brainstorm, challenge, condense, shadow-areas, fact-check. ### 🎼 [aidd-orchestrator](plugins/aidd-orchestrator/README.md) -`1 skill` · stable (`async-dev`) +`2 skills` · stable (`async-dev`) Label an issue, get a PR; re-label, get the review applied. Router-based skill: one entry point, three sub-flows (setup, run, review). diff --git a/aidd_docs/tasks/2026_06/2026_06_09-scaffold-to-bootstrap-migration-master.md b/aidd_docs/tasks/2026_06/2026_06_09-scaffold-to-bootstrap-migration-master.md new file mode 100644 index 00000000..025d3d05 --- /dev/null +++ b/aidd_docs/tasks/2026_06/2026_06_09-scaffold-to-bootstrap-migration-master.md @@ -0,0 +1,304 @@ +--- +objective: "Dissolve aidd-orchestrator:01-scaffold's three fat owned actions into two clean layers - aidd-context:01-bootstrap becomes the build unit (design + skeleton, agnostic init-* actions) and aidd-orchestrator:01-scaffold becomes a pure-glue auto|interactive wizard with zero owned actions, todo-list driven." +success_condition: "All seven phases verified: docs/ARCHITECTURE.md firewall reconciled (P0); bootstrap ships actions 01-13 with the tree designed exactly once in 04 (P1-P2); scaffold/SKILL.md has an empty actions/ dir and an auto|interactive mode line (P3); aidd-vcs ships an init-ci capability (P4); the agnostic assertive checklist lives in the wizard as step 8 and no longer in scaffold/references (P5); root README points to the flow without duplicating a tutorial (P6); a grep for cross-plugin literal plugin names across the changed prompts returns zero hits and the eval scenarios pass (P7)." +iteration: 0 +created_at: "2026-06-09T07:46:25Z" +plan_kind: master +confidence: 9 +--- + +# Master Plan - scaffold -> bootstrap + pure-glue orchestrator wizard + +## Context and ground truth (verified against the repo, not the brief) + +This worktree (`worktree-fizzy-crunching-wave`, off `main` @ `c3beb5d`) does **NOT** contain the +scaffold skill or the repo-init skill. Both live only on branch **`feat/scafolding`**: + +- `plugins/aidd-orchestrator/skills/01-scaffold/**` -> only on `feat/scafolding` (3 owned actions: `01-generate-architecture`, `02-implement-and-test`, `03-wire-ci`). +- `plugins/aidd-vcs/skills/00-repo-init/**` -> only on `feat/scafolding`. + +**BLOCKER-0 (execution branch):** this migration MUST be executed on `feat/scafolding` +(or a branch cut from it), not on this worktree's branch. The plan below assumes work happens +on `feat/scafolding`. First action of execution is to confirm the working branch contains +`plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md`. + +Verified current state of the two layers: + +- **Bootstrap (`aidd-context:01-bootstrap`)** currently ships exactly 5 actions: `01-gather-needs`, + `02-propose-candidates`, `03-audit-candidates`, `04-pick-and-design`, `05-write-install-md`. + The folder tree + Mermaid diagram are **already produced in `04-pick-and-design`** (SKILL.md + row 04: "User picks winner; generate folder tree + Mermaid diagram"). So "the tree is designed + once, in 04" is already largely true and only needs to be made explicit and protected. + Bootstrap writes `aidd_docs/INSTALL.md` (not project-root `INSTALL.md`). +- **Scaffold (`feat/scafolding`)** is a 10-step flow; steps 4/5/6 are the three owned actions, + every other step delegates to a skill. It already references `aidd-vcs:00-repo-init`, + `aidd-refine:04-shadow-areas`, `aidd-context:01/02/03` **by literal plugin name** in its step + table - which violates the Cross-plugin orthogonality rule; the migration must fix this. +- **Firewall:** `docs/ARCHITECTURE.md` -> section "Plugin concerns and layers" (the canonical + taxonomy table) places `aidd-context` in layer **Knowledge production / Knowledge**, and the + first of the three rules states: *"Knowledge vs execution is a firewall. Knowledge plugins + produce artifacts you read ... and never write or run application source - `aidd-context`'s + bootstrap deliberately creates no `package.json` or source files."* This directly contradicts + the migration (bootstrap will now materialize the tree, install deps, run quality gates). This + is **BLOCKER-1**, addressed in Phase 0. + +Two gaps the brief assumes but the repo does not have: + +- **No `aidd-context:07-design-system` skill exists.** Context ships skills `00-onboard` .. + `06-discovery` only. The brief's `13-init-design-system` says "delegate aidd-context:07-design-system". + Design-system capability today is the top-level **`impeccable`** skill (separate plugin). The plan + resolves this by delegation-via-description-matching (no literal name), and flags creating + `07-design-system` as an out-of-scope prerequisite if a dedicated context skill is required. +- The bootstrap **checklist asset names concrete techs** as examples (Vercel, Stripe, Clerk, + Supabase...). Asset examples are acceptable; the agnostic rule applies to *action prompts*. + +## Risk and impact score + +| Criterion | Points | +| ------------------------------- | ------ | +| Breaking changes to public APIs (skill contracts: scaffold loses 3 actions, bootstrap gains 8) | +3 | +| 5+ modules affected (aidd-context, aidd-orchestrator, aidd-vcs, docs, aidd-refine/aidd-pm references) | +3 | +| Major refactoring (responsibility re-layering across two plugins) | +2 | + +Score = 8 (>= 3) -> **master plan** with independent child phases. + +Each phase is designed to land independently and leave the repo coherent (no half-migrated state +that breaks an existing flow), per the "independent phases for compatibility" rule. + +## User journey (target end-state) + +```mermaid +flowchart TD + U[Human: scaffold the project] --> W{scaffold wizard\nmode auto or interactive} + W --> S1[1 PRD - delegate PM prd, skip if exists] + S1 --> S2[2 Shadow areas - delegate refine shadow-areas] + S2 --> S3[3 Init repo - delegate vcs repo-init init] + S3 --> S4[4 Bootstrap - delegate context bootstrap\ndesign 01-05 + build 06-13] + S4 --> S5[5 Init CI - delegate vcs init-ci] + S5 --> S6[6 Init context - delegate context project-init + context-generate] + S6 --> S7[7 Commit + publish - delegate vcs commit then repo-init publish] + S7 --> S8[8 VERIFY agnostic assertive checklist + handoff report] + S8 --> Done[Running, proven skeleton] +``` + +## Architecture projection + +### Modify + +- `docs/ARCHITECTURE.md - reconcile the Knowledge/execution firewall with bootstrap now writing+running code (Phase 0).` +- `plugins/aidd-context/skills/01-bootstrap/SKILL.md - extend actions table 01-13, split "design" vs "build", update description (no longer "docs only"), add delegation notes.` +- `plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md - TRIM: treat PRD as input, only ask block-2 technical constraints.` +- `plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md - make "tree designed here, and ONLY here" explicit and load-bearing.` +- `plugins/aidd-context/skills/01-bootstrap/assets/checklist.md - mark PRD-sourced block-1 items as inputs; keep block-2 as the gather focus.` +- `plugins/aidd-context/skills/01-bootstrap/README.md - reflect the build phase and new actions.` +- `plugins/aidd-context/.claude-plugin/plugin.json - bump version / description if the manifest carries the docs-only claim.` +- `plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md - strip to pure glue: empty actions, auto|interactive mode line, todo-list-driven 8-step sequence, agnostic delegation by description.` +- `plugins/aidd-orchestrator/skills/01-scaffold/README.md - reflect zero owned actions + wizard role.` +- `plugins/aidd-vcs/skills/00-repo-init/SKILL.md - decide: host init-ci here vs a new sibling skill (Phase 4 decision).` +- `aidd_docs/memory/architecture.md - if it restates the firewall, keep it consistent with docs/ARCHITECTURE.md.` +- `README.md (repo root) - pointer to the scaffold wizard, no duplicated tutorial (Phase 6).` + +### Create + +- `plugins/aidd-context/skills/01-bootstrap/actions/06-init-structure.md - materialize INSTALL.md tree + stubs.` +- `plugins/aidd-context/skills/01-bootstrap/actions/07-init-dependencies.md - install deps + relevant building blocks.` +- `plugins/aidd-context/skills/01-bootstrap/actions/08-init-env.md - env/config wiring.` +- `plugins/aidd-context/skills/01-bootstrap/actions/09-init-database.md - DB init + data building block.` +- `plugins/aidd-context/skills/01-bootstrap/actions/10-init-quality-gate.md - typecheck+format+lint+commit-linter+pre-commit in ONE action.` +- `plugins/aidd-context/skills/01-bootstrap/actions/11-init-tests.md - delegate the test capability (aidd-dev:06-test) by description.` +- `plugins/aidd-context/skills/01-bootstrap/actions/12-init-containers.md - container/runtime up-down.` +- `plugins/aidd-context/skills/01-bootstrap/actions/13-init-design-system.md - front-only, delegate design-system capability by description.` +- `plugins/aidd-vcs/skills/00-repo-init/actions/03-init-ci.md OR plugins/aidd-vcs/skills/-init-ci/** - the new CI capability (Phase 4 decision).` +- `(possibly) plugins/aidd-context/skills/01-bootstrap/references/install-md-contract.md - the seam contract every init-* reads from INSTALL.md.` + +### Delete + +- `plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md - logic absorbed by bootstrap 06.` +- `plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md - logic absorbed by bootstrap 07-12 + wizard step 8 verify.` +- `plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md - logic moves to aidd-vcs init-ci.` +- `plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md - moved (agnostified) into the wizard as step 8; delete from scaffold/references.` + +### Applicable rules + +No machine-readable `rules/*` files with `description`/`paths` frontmatter govern these prompt +files. The governing constraints are documentation-level and load-bearing: + +| Source | Rule | Why it applies | +| --- | --- | --- | +| `docs/ARCHITECTURE.md` "Plugin concerns and layers" | Knowledge/execution firewall | Bootstrap moving to write+run code violates it as written - must be reconciled first (P0). | +| `docs/ARCHITECTURE.md` "Cross-plugin orthogonality" | No literal cross-plugin names; discover by description | Every wizard step and every delegating init-* action must use description matching, not `aidd-vcs:...`. | +| `CLAUDE.md` (worktree) | "For every plugin change, think hard about where responsibility belongs" + "Never duplicate across docs - link to canonical home" | Drives the layer split and the no-duplicate-checklist + README-pointer decisions. | +| `docs/CREATE_PLUGIN.md` | Skill scoped to one concern; orchestrator = sequencing across concerns | Confirms scaffold = pure glue, init-* = build concern under context. | + +## Phases (independent, ordered) + +### Phase 0 - Firewall taxonomy reconciliation (BLOCKING, do first) + +Resolve the contradiction before any code-writing action lands in bootstrap. + +Tasks: +- Re-read `docs/ARCHITECTURE.md` "Plugin concerns and layers": the table row `aidd-context | Knowledge production | Knowledge` and the "Knowledge vs execution is a firewall" rule that explicitly cites bootstrap creating no `package.json`/source. +- Decide and apply ONE of two reconciliations (recommend option A): + - **Option A (recommended): refine the firewall wording.** Keep `aidd-context` as Knowledge, but redefine the firewall so it forbids *authoring business/domain source*, while permitting *materializing an already-validated design* (the INSTALL.md tree, stubs, dependency install, quality-gate config) as a deterministic projection of a knowledge artifact. Update the bootstrap sentence accordingly ("bootstrap materializes the validated INSTALL.md into a running skeleton but writes no business logic - that is `aidd-dev`'s concern"). This preserves the architecture-100%/business-0% invariant that scaffold already enforced. + - **Option B: relocate bootstrap's build phase.** Keep the firewall literal and move init-* into an Execution-layer home. Rejected unless A proves untenable - it fragments the design->build seam the brief wants unified. +- Update any echo of the firewall in `aidd_docs/memory/architecture.md`. + +Gate / test: a grep for "deliberately creates no" / "never write or run application source" in +`docs/ARCHITECTURE.md` no longer contradicts bootstrap; the taxonomy table still assigns every +plugin exactly one concern; the "architecture yes, business logic no" boundary is stated explicitly. + +### Phase 1 - Tree designed exactly once (in bootstrap action 04) + +Tasks: +- Edit `04-pick-and-design.md`: state that the folder/route tree + Mermaid + file conventions + (naming, tests, colocation) are decided HERE and nowhere else, validated by the user, and persisted + into `INSTALL.md` (via 05). Pull in the route-surface + conventions detail currently in scaffold's + deleted `01-generate-architecture` (steps 1-2: route surface, tree, conventions) so no design + knowledge is lost. +- Edit `05-write-install-md.md` so INSTALL.md carries the tree + conventions as the seam contract. +- Optionally add `references/install-md-contract.md` documenting which INSTALL.md sections each + init-* action consumes (single source of the seam). + +Gate / test: the string "folder tree" / "route surface" / "file conventions" appears in exactly one +design action (04); no later init-* action re-designs the tree (they read it from INSTALL.md). + +### Phase 2 - Write the agnostic build actions 06-13 + +Each action: agnostic prompt (no tech named - read `aidd_docs/INSTALL.md`), self-contained +inputs/outputs/depends-on/process/test, its own inline gate, and delegates where an executor exists +(by description matching, never literal plugin name). Building blocks are dispersed (per brief) into +06/07/09, not a standalone action. + +Tasks (one per file): +- `06-init-structure` - materialize the INSTALL.md tree + reachable stub per route (back+front), + applying the file conventions; absorbs scaffold `01-generate-architecture` steps 3-5. +- `07-init-dependencies` - resolve + install the stack's dependency manager and deps; wire the + relevant building blocks (auth/email/storage/jobs/payments/logging) as swappable abstractions + with smoke tests, per their INSTALL.md selection. +- `08-init-env` - environment/config/secrets scaffolding (`.env.example`, config loader), + env-flag selection between dev stub and real provider for blocks. +- `09-init-database` - initialize the data building block (engine bootstrap, migration tooling, + one round-trip smoke test). No schema design (that stays a later dev concern). +- `10-init-quality-gate` - ONE action: typecheck + auto-format + lint + commit-linter + pre-commit + hook wiring, all green. Absorbs the Quality block of the old project-doc-spec. +- `11-init-tests` - delegate the test-authoring capability (matches `aidd-dev:06-test` by + description); ensure a unit test and an e2e test pass and coverage is configured. +- `12-init-containers` - if a container/runtime is in INSTALL.md, ensure it ups and downs cleanly; + no-op + report otherwise. +- `13-init-design-system` - front-only; delegate the design-system capability by description + (today: `impeccable`); no-op for backend-only projects. Document the `07-design-system` gap. +- Update `SKILL.md`: actions table 01-13 split into "Design (01-05)" and "Build (06-13)"; + default flow `01 -> ... -> 13`; description no longer says "docs only, no code"; add the + delegation/agnostic transversal rules; bump `plugin.json` if it restates docs-only. +- Update bootstrap `README.md`. + +Gate / test: each new action file has the five required sections and a `## Test`; no action body +contains a concrete tech name or a literal cross-plugin name (grep); `SKILL.md` lists 01-13 and the +flow is sequential with the audit (03) gate preserved. + +### Phase 3 - Strip scaffold to pure glue (auto|interactive, todo-list driven) + +Tasks: +- Delete the three owned actions and the empty owned-actions concept from `01-scaffold` (the + `actions/` dir ends empty or is removed). +- Rewrite `SKILL.md` as pure glue: an 8-step sequence (PRD -> shadow-areas -> repo-init -> + bootstrap[design+all init-*] -> init-ci -> init-context -> commit/publish -> VERIFY+handoff), + every step delegating by description matching (strip all literal `aidd-*` names from the step + table - this also fixes the pre-existing orthogonality violation). +- Add the `auto|interactive` modes section, reusing the exact convention from `aidd-dev:00-sdlc`: + mode detected from `$ARGUMENTS` at entry; gates pause only in interactive; `auto` never asks. +- Make it todo-list driven: materialize the 8 steps as a task list at entry; a step closes only + when its delegated capability returns success (reuse sdlc's "Runtime tracking" wording). +- Keep the "Resume" behavior (detect done steps, present check/uncheck list). +- Update scaffold `README.md`. + +Gate / test: `01-scaffold/actions/` is empty/absent; `SKILL.md` contains a `## Modes` table with +`auto`/`interactive`; no literal `aidd-` plugin name appears in `SKILL.md`; the 8-step sequence +matches the target journey. + +### Phase 4 - New CI capability in aidd-vcs + +Decision first: host `init-ci` as **`00-repo-init/actions/03-init-ci.md`** (CI is part of repo +setup, smallest surface) vs a **new sibling skill `aidd-vcs:NN-init-ci`**. Recommend the action +inside repo-init unless CI warrants its own router. Document the choice. + +Tasks: +- Port the agnostified logic of the deleted scaffold `03-wire-ci` (resolve CI platform from + INSTALL.md, emit minimal pipeline that runs the tests, no platform assumed, output the CI URL). +- If a new skill: add `SKILL.md` + `plugin.json` skills entry + `README.md` + `evals/`. +- Wire scaffold wizard step 5 to discover this capability by description. + +Gate / test: the CI capability is reachable, agnostic (no CI platform named in the prompt), reads +INSTALL.md, and its `## Test` asserts a green pipeline; `plugin.json` validates against the manifest +schema (lefthook hook). + +### Phase 5 - Move + agnostify the assertive checklist into wizard step 8 + +Tasks: +- Take `scaffold/references/project-doc-spec.md`, strip tech-specific items to capability level: + "Lighthouse thresholds configured" -> "Performance budget enforced (front-only)"; + "A11y UI lib installed" / "Accessibility tests" -> "Accessibility checks pass (front-only)"; + keep Project/Quality/Testing/Deployment/App buckets as capability assertions. +- Relocate it to the wizard (e.g. `01-scaffold/references/verify-checklist.md` or inline in step 8), + because the final verify spans repo + build + CI + context, which bootstrap alone cannot see. +- Delete the old `project-doc-spec.md` from scaffold and remove the `@../references/project-doc-spec.md` + includes from the (now deleted) scaffold actions. +- Confirm each init-* keeps its OWN inline gate (Phase 2) - step 8 is the union verify, not a + replacement for per-action gates. + +Gate / test: wizard step 8 references the agnostic checklist; no Lighthouse / a11y-library literal +remains; no orphan include of `project-doc-spec.md` anywhere (grep); the checklist asserts repo, +build, CI, and context artifacts together. + +### Phase 6 - Root README pointer (no duplicate tutorial) + +Tasks: +- Add/adjust a single pointer in the repo-root `README.md` to "scaffold a new project" -> the + scaffold wizard, linking the canonical home; do NOT duplicate a step-by-step tutorial (honors + "Never duplicate across docs - link to canonical home"). + +Gate / test: README has one pointer, no reproduced step list; link resolves to the scaffold skill. + +### Phase 7 - Validate on eval scenarios + +Tasks: +- Update/extend `plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json` and + `plugins/aidd-context/skills/01-bootstrap/evals/scenarios.json` to cover: auto vs interactive, + PRD-exists skip, front-only (design-system + a11y) vs backend-only (skip 12/13 cleanly), + and resume mid-flow. +- Run the project validation hooks (lefthook / `validate` workflow equivalents) and the eval + scenarios. +- Run the cross-plugin literal-name grep across all changed prompts (the orthogonality guard). + +Gate / test (this is the master success_condition): all phase gates green; eval scenarios pass; +literal-name grep returns zero across changed files. + +## Open decisions to confirm with the human before execution + +1. **Execution branch** - confirm work lands on `feat/scafolding` (this worktree lacks scaffold + + repo-init). BLOCKING. +2. **Firewall reconciliation** - Option A (refine wording) vs Option B (relocate). Recommend A. +3. **`07-design-system`** - delegate to existing `impeccable` by description (recommended, no new + skill) vs create a dedicated `aidd-context:07-design-system` (out of scope, adds a phase). +4. **CI home** - `repo-init/actions/03-init-ci` vs new `aidd-vcs:NN-init-ci` skill. Recommend the + action inside repo-init. +5. **Building-blocks dispersion** - confirm the 06/07/09 split matches intent (data->09, + providers->07, structure->06) vs a different grouping. + +## Confidence: 9/10 + +Reasons (checks): +- Ground truth verified directly against the filesystem and `feat/scafolding` (not the brief); + the bootstrap action count, the firewall location, the missing repo-init/07-design-system, and + the scaffold orthogonality violation are all confirmed. +- The layer split maps cleanly onto the existing seam (INSTALL.md) and reuses an established + convention (sdlc auto|interactive) verbatim. +- Phases are independently landable and each carries a concrete gate. + +Risks (checks against): +- The firewall reconciliation is a doc-judgement call the human must approve (Phase 0 decision). +- `07-design-system` gap means step 13 depends on description-matching to `impeccable`, which is a + different plugin layer - acceptable but worth confirming. +- The brief's "action 01 TRIM (PRD is input)" assumes the wizard always runs PRD first; in + bootstrap-standalone use (no wizard) the PRD may be absent - action 01 must degrade gracefully + (ask block-1 too when no PRD is provided). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bbdeb4bd..c4672010 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -66,7 +66,8 @@ plugins// │ ├── README.md # human-facing skill landing │ ├── actions/ # atomic actions invoked by the router │ ├── assets/ # templates and static files -│ └── references/ # extended docs the skill links into +│ ├── references/ # extended docs the skill links into +│ └── evals/ # scenario fixtures ├── agents/ # named AI agents (optional) ├── commands/ # slash commands (optional) ├── hooks/hooks.json # lifecycle hooks (optional) @@ -93,7 +94,7 @@ Every capability lives in exactly one plugin, chosen by **concern**. This taxono Three rules follow: -- **Knowledge vs execution is a firewall.** Knowledge plugins produce artifacts you *read* (docs, plans, memory) and never write or run application source - `aidd-context`'s bootstrap deliberately creates no `package.json` or source files. Real code belongs to `aidd-dev` or an orchestrator's own setup actions. +- **Knowledge vs execution is a firewall.** Knowledge plugins produce artifacts you *read* (docs, plans, memory) and never author business logic. One scoped exception: `aidd-context`'s bootstrap may *materialize a validated `INSTALL.md`* into a running skeleton - folder structure, swappable building blocks, tooling (typecheck/lint/format, tests, containers), smoke tests - staying **architecture-100% / business-0%**. Application logic still belongs to `aidd-dev`; an orchestrator owns only the sequencing across concerns. - **Concern decides placement, not existence.** A missing capability goes in the plugin whose concern owns it, then the caller delegates. Never reimplement it in the calling plugin because the right home lacks it today. - **Orchestration = sequencing across multiple concerns** with little domain logic. Any skill may delegate a sub-step ([Cross-plugin orthogonality](#cross-plugin-orthogonality)); doing so once does not make it an orchestrator. The orchestrator owns only glue and delegates the depth, handing off through a seam artifact (e.g. an `INSTALL.md` one plugin produces and another consumes). diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 6e06a072..dd27f8f9 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -18,7 +18,7 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and di | Skill | Role | Actions | | ---------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | `00-onboard` | Detect project state and open a hub of project actions | `01-detect-state`, `02-recommend-next`, `03-execute-or-handoff` | -| `01-bootstrap` | Imagine and validate a new SaaS architecture, output an `INSTALL.md` | `01-gather-needs`, `02-propose-candidates`, `03-audit-candidates`, `04-pick-and-design`, `05-write-install-md` | +| `01-bootstrap` | Design the stack into `INSTALL.md`, then materialize a running, proven skeleton | `01-check-prd`, `02-gather-needs`, `03-choose-stack`, `04-init-install-md`, `05-init-architecture`, `06-init-dependencies`, `07-init-env`, `08-init-database`, `09-init-quality-gate`, `10-init-tests`, `11-init-containers`, `12-init-design-system`, `13-init-ci` | | `02-project-init` | Initialize or refresh the memory bank and AI context files | `01-init-context-file`, `02-scaffold-docs`, `03-generate-memory`, `04-review-memory`, `05-sync-memory` | | `03-context-generate` | Generate context artifacts across the host AI tool(s) | sub-generators: `agents`, `commands`, `hooks`, `marketplaces`, `plugins`, `rules`, `skills` | | `04-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | @@ -83,3 +83,4 @@ Optional. Runs the SDLC asynchronously on labeled issues (webhook or cron). Most | Skill | Role | Sub-flows | | ---------------- | ----------------------------------------------------- | ------------------------- | | `00-async-dev` | Single entry point for the async-dev pipeline | `setup`, `run`, `review` | +| `01-scaffold` | Sequencing tutorial: idea → running skeleton by launching other skills | — | diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 50076a6b..79635e34 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -21,6 +21,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`skills/09-mermaid`](#skills09-mermaid) - [`skills/10-learn`](#skills10-learn) - [`skills/11-discovery`](#skills11-discovery) + - [`skills/12-design-system`](#skills12-design-system) --- @@ -54,16 +55,25 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| -| `actions` | [01-gather-needs.md](skills/01-bootstrap/actions/01-gather-needs.md) | - | -| `actions` | [02-propose-candidates.md](skills/01-bootstrap/actions/02-propose-candidates.md) | - | -| `actions` | [03-audit-candidates.md](skills/01-bootstrap/actions/03-audit-candidates.md) | - | -| `actions` | [04-pick-and-design.md](skills/01-bootstrap/actions/04-pick-and-design.md) | - | -| `actions` | [05-write-install-md.md](skills/01-bootstrap/actions/05-write-install-md.md) | - | -| `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | -| `assets` | [install-template.md](skills/01-bootstrap/assets/install-template.md) | - | +| `actions` | [01-check-prd.md](skills/01-bootstrap/actions/01-check-prd.md) | - | +| `actions` | [02-gather-needs.md](skills/01-bootstrap/actions/02-gather-needs.md) | - | +| `actions` | [03-choose-stack.md](skills/01-bootstrap/actions/03-choose-stack.md) | - | +| `actions` | [04-init-install-md.md](skills/01-bootstrap/actions/04-init-install-md.md) | - | +| `actions` | [05-init-architecture.md](skills/01-bootstrap/actions/05-init-architecture.md) | - | +| `actions` | [06-init-dependencies.md](skills/01-bootstrap/actions/06-init-dependencies.md) | - | +| `actions` | [07-init-env.md](skills/01-bootstrap/actions/07-init-env.md) | - | +| `actions` | [08-init-database.md](skills/01-bootstrap/actions/08-init-database.md) | - | +| `actions` | [09-init-quality-gate.md](skills/01-bootstrap/actions/09-init-quality-gate.md) | - | +| `actions` | [10-init-tests.md](skills/01-bootstrap/actions/10-init-tests.md) | - | +| `actions` | [11-init-containers.md](skills/01-bootstrap/actions/11-init-containers.md) | - | +| `actions` | [12-init-design-system.md](skills/01-bootstrap/actions/12-init-design-system.md) | - | +| `actions` | [13-init-ci.md](skills/01-bootstrap/actions/13-init-ci.md) | - | +| `assets` | [INSTALL.md](skills/01-bootstrap/assets/INSTALL.md) | - | +| `assets` | [README.md](skills/01-bootstrap/assets/README.md) | - | | `-` | [README.md](skills/01-bootstrap/README.md) | - | +| `references` | [checklist.md](skills/01-bootstrap/references/checklist.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | -| `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and an INSTALL.md output. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code).` | +| `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Imagine, validate, then stand up a new project. First designs the technical architecture - checks the PRD, gathers technical needs, chooses & audits the stack - into a validated `INSTALL.md` + `README.md`; then materializes that `INSTALL.md` into a running, proven skeleton via atomic `init-*` actions (architecture, dependencies, env, database, quality gate, tests, containers, design system, CI). Stack-agnostic - every build action reads `INSTALL.md` and names no technology. Architecture-100% / business-0%: never writes business logic. Use when starting a new project, choosing a stack, or standing up the running skeleton. Do NOT use to add features to an existing project or to write business logic.` | #### `skills/02-project-init` @@ -195,3 +205,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [ai-mapping.md](skills/11-discovery/references/ai-mapping.md) | - | | `-` | [SKILL.md](skills/11-discovery/SKILL.md) | `Enumerate installed surfaces of the AI tool (skills, agents, commands, plugins, MCP servers, rules, hooks, memory files) and recommend the best match for the user's stated intent. Use proactively whenever the user asks the model to list, show, enumerate, find, or pick among any of these surfaces - including imperative phrasings ("list hooks", "show me the rules", "enumerate skills", "find a memory file", "which agent reviews code"), question phrasings ("what's available?", "what hooks do we have?", "which rule applies here?", "what memory files do we have?"), and indirect phrasings ("what can I use for X?", "do we have something that does Y?"). Always pick this skill over scanning the filesystem with grep, find, ls, or reading action files directly when the user is enumerating a surface. Do NOT use for picking a specific item inside one plugin (the plugin's own onboard handles that), creating a new surface, or executing a recommended item (this skill only points; the user invokes).` | +#### `skills/12-design-system` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-create-design-system.md](skills/12-design-system/actions/01-create-design-system.md) | - | +| `actions` | [02-redesign-page.md](skills/12-design-system/actions/02-redesign-page.md) | - | +| `-` | [README.md](skills/12-design-system/README.md) | - | +| `-` | [SKILL.md](skills/12-design-system/SKILL.md) | `Initialize a project's design system through a guided, ordered playbook that routes each step to the right Impeccable command - register and color strategy, palette with accessibility validation, typography, spacing, elevation, motion, components, and the canonical DESIGN.md.` | + diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index 6b2f0a17..56284f8e 100644 --- a/plugins/aidd-context/README.md +++ b/plugins/aidd-context/README.md @@ -8,7 +8,7 @@ Knowledge production plugin for the AI-Driven Development framework. First time? Install with `/plugin install aidd-context@aidd-framework`, then run `aidd-context:00-onboard`. -Covers project bootstrap, project initialisation, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), Mermaid diagrams, learning, discovery, and a state-aware onboarding loop. +Covers project bootstrap, project initialisation, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks), Mermaid diagrams, learning, discovery, design-system onboarding, and a state-aware onboarding loop. ## Skills @@ -21,6 +21,7 @@ Covers project bootstrap, project initialisation, generation of Claude Code cont | [1.4] | [mermaid](skills/09-mermaid/README.md) | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow. | | [1.5] | [learn](skills/10-learn/README.md) | Capture and store learnings from recently implemented features into memory bank, decisions, or coding rules. | | [1.6] | [discovery](skills/11-discovery/README.md) | Help users discover installed skills and find the right one for their use case. | +| [1.7] | [design-system](skills/12-design-system/README.md) | Guided playbook to author a quality design system by wrapping the Impeccable skill; routes each step to the right Impeccable command. Produces no files of its own - Impeccable's DESIGN.md stays canonical. | ## Onboarding diff --git a/plugins/aidd-context/skills/01-bootstrap/README.md b/plugins/aidd-context/skills/01-bootstrap/README.md index 15ae57b0..2bfae3fb 100644 --- a/plugins/aidd-context/skills/01-bootstrap/README.md +++ b/plugins/aidd-context/skills/01-bootstrap/README.md @@ -2,24 +2,19 @@ # 01 - Bootstrap -Plays the role of technical architect for a new SaaS project. Walks the user -through a 24-item checklist, proposes 2-3 candidate stacks, audits each via -parallel agents, then produces `aidd_docs/INSTALL.md` capturing the technical -vision, decisions, stack, architecture pattern, folder tree, and install -steps. Documentation only - no code, no scaffolding. +Technical architect **and** builder for a new project. **Design** (actions 01-04): check the PRD, gather technical needs, choose & audit the stack, and produce a validated project-root `INSTALL.md` + `README.md`. **Build** (actions 05-13): materialize that validated `INSTALL.md` into a running, proven skeleton through atomic, stack-agnostic `init-*` actions. Architecture-100% / business-0% - never writes business logic (per the firewall in `docs/ARCHITECTURE.md`). ## When to use -- Starting a brand-new SaaS project and choosing a stack. +- Starting a brand-new project and choosing a stack. - Deciding the architecture pattern (monolith vs microservices vs serverless). -- Producing a project's `INSTALL.md` from a fresh idea. +- Standing up the running skeleton from a fresh idea. ## When NOT to use -- To edit an existing project's stack (the audit is too heavy for one - swap-out). -- For database schema design or detailed data modeling. -- To scaffold actual files - this skill produces docs only. +- Editing an existing project's stack (the audit is too heavy for one swap-out). +- Database schema design or detailed data modeling. +- Writing business logic (auth, domain rules, features). ## How to invoke @@ -27,33 +22,36 @@ steps. Documentation only - no code, no scaffolding. Use skill aidd-context:01-bootstrap ``` -The skill walks 5 atomic actions in sequence: +### Design phase → validated `INSTALL.md` -1. `gather-needs` - Q&A across the 24-item checklist (18 user-input, 6 - derived). -2. `propose-candidates` - derive 2-3 candidate stacks and render a - comparison table. -3. `audit-candidates` - spawn parallel agents to validate each candidate - and emit a verdict; if every candidate fails, loop back to `02` or `01`. -4. `pick-and-design` - user picks the winner, then generate the folder tree - and a Mermaid architecture diagram. -5. `write-install-md` - produce `aidd_docs/INSTALL.md`. +1. `check-prd` - verify a PRD exists; if not, stop and ask the user to create one (bootstrap can't start without it). +2. `gather-needs` - ask the technical questions; product facts come from the PRD. +3. `choose-stack` - propose 2-3 candidate stacks, audit each in parallel, user picks the winner, settle the architecture pattern + Mermaid diagram. +4. `init-install-md` - write the project-root `INSTALL.md` + `README.md`. **`INSTALL.md` is born here.** + +### Build phase → running skeleton + +No build action runs until `INSTALL.md` is written and validated; conditional actions skip per `INSTALL.md`. + +5. `init-architecture` - folder tree + reachable route stubs from the chosen pattern. +6. `init-dependencies` - dependency manager + building blocks (swappable) + boot. +7. `init-env` - `.env.example` + config loading. +8. `init-database` - engine + baseline migration + seed fixtures + round-trip *(conditional)*. +9. `init-quality-gate` - typecheck + format + lint + commit-linter + pre-commit (one gate). +10. `init-tests` - runner + unit + e2e + coverage *(delegated)*. +11. `init-containers` - container ups & downs cleanly *(conditional)*. +12. `init-design-system` - design system *(front-only, delegated)*. +13. `init-ci` - pipeline runs the quality gate + tests, green on the server *(conditional)*. ## Outputs -- `aidd_docs/INSTALL.md` capturing vision, decisions, chosen stack, - architecture pattern, folder tree, install steps, and a Mermaid diagram. +- A validated project-root `INSTALL.md` + `README.md`, then a running skeleton proven by each build action's gate. ## Prerequisites -- A clear (or at least loosely-formed) product idea to discuss. -- A working directory where `aidd_docs/INSTALL.md` can be written. +- A PRD / product brief (required - `check-prd` halts without it). +- A working directory. ## Technical details -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) -for each step, `references/stack-heuristics.md` for the input → recommended -stack-family heuristics, and `assets/checklist.md` + `assets/install-template.md` -for the canonical 24-item checklist and `INSTALL.md` skeleton. The Mermaid -architecture diagram in action 04 is rendered via the sibling -`09-mermaid` skill. +See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for each step, `references/stack-heuristics.md`, and `assets/`. The Mermaid diagram (action 03) renders via the sibling `09-mermaid` skill; `init-tests` and `init-design-system` delegate to the capability that owns them, discovered by description. diff --git a/plugins/aidd-context/skills/01-bootstrap/SKILL.md b/plugins/aidd-context/skills/01-bootstrap/SKILL.md index d5f8efa2..27239232 100644 --- a/plugins/aidd-context/skills/01-bootstrap/SKILL.md +++ b/plugins/aidd-context/skills/01-bootstrap/SKILL.md @@ -1,43 +1,62 @@ --- name: 01-bootstrap -description: Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and an INSTALL.md output. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code). +description: Imagine, validate, then stand up a new project. First designs the technical architecture - checks the PRD, gathers technical needs, chooses & audits the stack - into a validated `INSTALL.md` + `README.md`; then materializes that `INSTALL.md` into a running, proven skeleton via atomic `init-*` actions (architecture, dependencies, env, database, quality gate, tests, containers, design system, CI). Stack-agnostic - every build action reads `INSTALL.md` and names no technology. Architecture-100% / business-0%: never writes business logic. Use when starting a new project, choosing a stack, or standing up the running skeleton. Do NOT use to add features to an existing project or to write business logic. --- # Bootstrap -Plays the role of technical architect for a new SaaS project. Walks the user through a 24-item checklist (18 user-input + 6 derived), proposes 2-3 candidate stacks, audits each via parallel agents, then produces `aidd_docs/INSTALL.md` capturing the technical vision, decisions, stack, architecture pattern, folder tree, and install steps. Documentation only - no code, no scaffolding. +Technical architect **and** builder for a new project. Two phases. **Design** (01-04): check the PRD, gather technical needs, choose & audit the stack, write a validated `INSTALL.md` + `README.md`. **Build** (05-13): materialize that validated `INSTALL.md` into a running, proven skeleton through atomic, stack-agnostic `init-*` actions. Architecture-100% / business-0% - never writes business logic (per the firewall in `docs/ARCHITECTURE.md`). ## Available actions -| # | Action | Role | Input | -| --- | --------------------- | -------------------------------------------------------------- | ------------------ | -| 01 | `gather-needs` | Q&A across the 24-item checklist | user intent | -| 02 | `propose-candidates` | Derive 2-3 candidate stacks, render comparison table | filled checklist | -| 03 | `audit-candidates` | Spawn parallel agents to validate each candidate, emit verdict | candidates table | -| 04 | `pick-and-design` | User picks winner; generate folder tree + Mermaid diagram | audit report | -| 05 | `write-install-md` | Produce `aidd_docs/INSTALL.md` | design + decisions | +**Design phase** - produces the validated `INSTALL.md` (docs only): + +| # | Action | Role | Input | +| --- | ----------------- | ----------------------------------------------------------------------------- | ------------------ | +| 01 | `check-prd` | Verify a PRD exists; if not, stop and ask the user to create one | project | +| 02 | `gather-needs` | Ask the technical questions; product facts come from the PRD | PRD | +| 03 | `choose-stack` | Propose 2-3 candidates + audit (parallel) + user picks + architecture pattern | needs | +| 04 | `init-install-md` | Write `INSTALL.md` + project-root `README.md`. **INSTALL.md is born here.** | chosen stack | + +**Build phase** - materializes the validated `INSTALL.md` into a running skeleton. `05`-`06` read `INSTALL.md` (design → code); each later action builds on the previous one's output - the materialized project, where the stack is already concrete. No action names a technology; each has its own gate: + +| # | Action | Role | Delegate | +| --- | -------------------- | --------------------------------------------------------------------- | ----------------- | +| 05 | `init-architecture` | Folder tree + reachable route stubs from `INSTALL.md`'s pattern | owns | +| 06 | `init-dependencies` | Dependency manager + building blocks (swappable) + boot | owns | +| 07 | `init-env` | `.env.example` + config loading | owns | +| 08 | `init-database` | Engine + baseline migration + fixtures + round-trip *(conditional)* | owns | +| 09 | `init-quality-gate` | typecheck + format + lint + commit-linter + pre-commit (one gate) | owns | +| 10 | `init-tests` | Runner + 1 unit + 1 e2e + coverage | testing capability | +| 11 | `init-containers` | Container/compose ups & downs clean *(conditional)* | owns | +| 12 | `init-design-system` | Design system *(front-only, conditional)* | design-system capability | +| 13 | `init-ci` | Pipeline runs the quality gate + tests, green on the server *(conditional)* | owns | ## Default flow -`01 → 02 → 03 → 04 → 05`. Sequential. The audit (03) is a gate: if every candidate returns `❌`, loop back to 02 to revise candidates or 01 to revisit needs. +**Design** `01 → 02 → 03 → 04`, then **Build** `05 → 06 → 07 → 08 → 09 → 10 → 11 → 12 → 13`. Sequential. `01-check-prd` is a hard gate: no PRD → stop. The audit inside `03` is a gate: if every candidate is `❌`, revise candidates and re-audit. **No build action runs until `INSTALL.md` is written and validated** (end of `04`). Conditional build actions (08, 11, 12, 13) skip when the project does not call for them. Each build action advances only when its own `## Test` gate is green. ## Transversal rules -- **No file scaffolding.** This skill writes only `aidd_docs/INSTALL.md`. It never creates `package.json`, source files, or empty directories. -- **Anti-sycophancy.** When the user expresses a stack preference that conflicts with their needs (e.g. wants Mongo for heavily relational data), challenge it before accepting: surface audit concerns and ask whether the user has a mitigation plan. -- **Recommend opinionated, not encyclopedic.** Each action proposes 2-3 options max, never a long catalog. The user should leave with a concrete decision, not a research paper. -- **Stop on full checklist.** Action 01 keeps asking until the 18 user-input items (blocks 1-3) are filled; the 6 derived items (block 4) are filled across actions 02 and 04. +- **PRD first.** `01-check-prd` halts the whole skill when no PRD exists - bootstrap never starts without product context. +- **Design before build; never fabricate.** No build action (05+) runs until the human has validated `INSTALL.md`. The design phase invents nothing - it waits for the human at every gate. +- **Architecture-100% / business-0%.** The build phase materializes a *validated* `INSTALL.md` - structure, building blocks, tooling, smoke tests - but never business logic (auth, domain rules, real features). Per the firewall in `docs/ARCHITECTURE.md`. +- **Stack-agnostic build.** No `init-*` action names a technology of its own. The stack comes from `INSTALL.md` (read by `05`-`06`) and from the materialized project thereafter - never from the action prompt. +- **Delegate, don't reinvent.** `init-tests` and `init-design-system` delegate to the capability that owns them (discovered by description, never a hardcoded plugin name). +- **Anti-sycophancy.** When a user stack preference conflicts with the needs (e.g. wants Mongo for heavily relational data), challenge before accepting: surface the audit concerns, ask for a mitigation plan. +- **Recommend opinionated, not encyclopedic.** Propose 2-3 options max, never a long catalog. The user leaves with a concrete decision, not a research paper. - **Apply heuristics from `@references/stack-heuristics.md`** when proposing candidates. ## References +- `@references/checklist.md` - the needs checklist walked in `02-gather-needs` - `@references/stack-heuristics.md` - input → recommended-stack-family heuristics ## Assets -- `@assets/checklist.md` - the 24-item checklist (4 blocks) -- `@assets/install-template.md` - the `INSTALL.md` skeleton +- `@assets/INSTALL.md` - the `INSTALL.md` skeleton +- `@assets/README.md` - the project-root `README.md` template ## External data -- `aidd-context/skills/09-mermaid/SKILL.md` - invoked from action 04 to render the architecture diagram +- `aidd-context/skills/09-mermaid/SKILL.md` - invoked from `03-choose-stack` to render the architecture diagram diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/01-check-prd.md b/plugins/aidd-context/skills/01-bootstrap/actions/01-check-prd.md new file mode 100644 index 00000000..20f1d172 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/01-check-prd.md @@ -0,0 +1,17 @@ +# 01 - Check PRD + +Verify a PRD (product brief) exists before anything else. Without it, bootstrap cannot start - stop and ask the user to create one. + +## Inputs + +- The project's product brief / PRD, if any. + +## Process + +1. Look for a PRD / product brief - the product's *what* and *why*. +2. If absent: **stop**. Tell the user to create one first (`run skill "aidd-pm:03-prd"`), then re-run bootstrap. +3. If present: read it. It is the product context for the rest of the flow. + +## Test + +- [ ] A PRD exists and has been read, OR the flow halted with a clear instruction to create one. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md deleted file mode 100644 index 355d329c..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md +++ /dev/null @@ -1,32 +0,0 @@ -# 01 - Gather needs - -Walk the user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1-3) are filled. The 6 derived items (block 4) stay empty here - they are filled by actions 02 and 04. - -## Inputs - -- Free-form user request to bootstrap a new SaaS project. - -## Outputs - -A filled copy of `@../assets/checklist.md` held in conversation context (not yet written to disk). Each user-input item has a concrete value replacing its `<...>` placeholder. - -```markdown -- [x] **Project name** - Acme Invoicing -- [x] **One-liner** - Smart invoice tracker for freelancers, syncs with Airtable -- [x] **Type** - B2B SaaS -- [x] **Target users** - solo freelancers and 2-5 person agencies, ~500 active at 6 months -... (all 18 input items filled) -``` - -## Process - -1. Read `@../assets/checklist.md`. Print the four blocks as a single markdown checklist for the user to see the full scope upfront. -2. Ask block by block, one block per message. Within a block, ask all questions at once (the user answers in batch). Do not ask block 4 - it's derived. -3. For each user answer, fill the corresponding item. If an answer is vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). -4. After block 1, sanity-check coherence: does the type match the user volume? Are the integrations realistic for the platform target? -5. After block 3, surface conflicts (e.g. budget < 50€/mo + AWS preference + heavy backend → impossible). Force a re-answer on the conflicting item. -6. Print the filled checklist (blocks 1-3 only) and ask the user to confirm "go" before passing to action 02. - -## Test - -The 18 user-input items in the in-memory checklist have no remaining `<...>` placeholders, the 6 block-4 items are still placeholders, and the user has explicitly confirmed the filled checklist with "go" or equivalent before action 02 starts. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/02-gather-needs.md b/plugins/aidd-context/skills/01-bootstrap/actions/02-gather-needs.md new file mode 100644 index 00000000..1a06847a --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/02-gather-needs.md @@ -0,0 +1,20 @@ +# 02 - Gather needs + +Ask the user the **technical** questions bootstrap needs. Product facts (name, users, features) come from the PRD - never re-ask them. + +## Inputs + +- The PRD (product context, from `01-check-prd`). +- `@../references/checklist.md` - the question checklist. + +## Process + +1. Read the PRD; pre-fill every checklist item it already answers (the product block). +2. Ask only the remaining **technical** questions - constraints (real-time, multi-tenant, data sensitivity, volume, performance, SEO, offline) and team / hosting preferences. One block per message, batched. +3. Capture the technical **building blocks** the app needs (data, plus any of auth, email, storage, background jobs, CRON, payments, logging). +4. Surface conflicts (e.g. budget vs hosting vs load) and force a re-answer. +5. Print the gathered needs + building blocks; wait for the user's "go". + +## Test + +- [ ] Product facts taken from the PRD (not re-asked); technical constraints + building blocks captured; user confirmed "go". diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md b/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md deleted file mode 100644 index dd7a539c..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md +++ /dev/null @@ -1,37 +0,0 @@ -# 02 - Propose candidates - -Derive 2-3 candidate stacks from the filled checklist using the heuristics in `@../references/stack-heuristics.md`, then render a markdown comparison table for the user. - -## Inputs - -- Filled checklist (blocks 1-3) from action 01. - -## Outputs - -A markdown comparison table with 2-3 rows. - -```markdown -| Candidate | Front | Back | DB | Hosting | Auth | Archi | Cost/mo | Risks | -|-----------|-------|------|------|---------|------|-------|---------|-------| -| **A. Vercel-native** | Next.js SSR | Next.js API routes | Supabase Postgres | Vercel + Supabase | NextAuth | Modular monolith | ~30€ | Vercel lock-in, cold starts on serverless functions | -| **B. Self-hosted** | Vite + React SPA | NestJS | Postgres on VPS | Coolify on Hetzner VPS | Clerk | Modular monolith | ~15€ | Manual ops, single point of failure | -| **C. Serverless AWS** | Next.js SSR | AWS Lambda + API Gateway | DynamoDB | AWS + CloudFront | Cognito | Serverless | ~50€ at low volume, scales linearly | Vendor lock-in, learning curve | -``` - -## Depends on - -- `01-gather-needs` - -## Process - -1. Read the filled checklist from action 01. -2. Apply each rule from `@../references/stack-heuristics.md` to derive the recommended family for: archi pattern, front, back, DB, auth, hosting. -3. Build 2-3 candidates that span the trade-off space - they must differ on at least one of: hosting model (PaaS vs self-host vs serverless), back-end language, or archi pattern. Never propose 3 near-identical candidates. -4. For each candidate, estimate monthly cost at the user's volume target (Block 2 item: "Volume at 6 months"). Use rough public-pricing numbers; flag uncertainty. -5. List 1-3 risks per candidate (lock-in, ops burden, learning curve, scaling limit). Be honest - risks are non-negotiable, no candidate has zero. -6. Render the comparison table. Bold the candidate's name (`**A.**`). -7. Print the table to the user. Do not pick a winner - that's action 04, after audit. - -## Test - -The output is a markdown table with at least 2 rows; the columns include `Front`, `Back`, `DB`, `Hosting`, `Auth`, `Archi`, `Cost`, `Risks`; each row has a non-empty value in every column; at least two rows differ on hosting model, back-end language, or archi pattern. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md b/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md deleted file mode 100644 index 6394bf0e..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md +++ /dev/null @@ -1,63 +0,0 @@ -# 03 - Audit candidates - -Spawn one parallel agent per candidate to validate the proposed stack: tech compatibility, ecosystem maturity, known gotchas. Returns a verdict (`✅ / ⚠️ / ❌`) plus a 3-bullet rationale per candidate. - -## Inputs - -- Comparison table from action 02. -- Filled checklist from action 01 (for context). - -## Outputs - -The same table from action 02, augmented with a `Verdict` column and a per-candidate rationale block below. - -```markdown -| Candidate | Verdict | Notes | -|-----------|---------|-------| -| **A. Vercel-native** | ✅ | All components mature, well-documented integration, no gotchas at this scale | -| **B. Self-hosted** | ⚠️ | Coolify is recent (< 2 years); ops burden underestimated for solo dev | -| **C. Serverless AWS** | ❌ | DynamoDB is the wrong fit for relational invoice data; Cognito has known UX friction | -``` - -Per-candidate rationale (3 bullets): - -```markdown -### A. Vercel-native - ✅ -- Next.js + Supabase is the most documented stack in 2026; copy-paste examples exist for every checklist requirement -- Vercel's Hobby tier plus Supabase free tier covers the 6-month volume target; cost forecast holds -- Cold start is the only concrete risk - irrelevant for a B2B SaaS with predictable load patterns - -### B. Self-hosted - ⚠️ -- ... -``` - -## Depends on - -- `02-propose-candidates` - -## Process - -1. For each candidate row in the table, spawn a parallel `general-purpose` Agent with this brief: - - ``` - Audit the following candidate stack for a SaaS project. Validate three dimensions: - 1. Tech compatibility - do the components integrate cleanly? Any deprecated combos? - 2. Ecosystem maturity - are the components stable (≥ 2 years prod-tested) and well-documented? - 3. Known gotchas - search recent (last 12 months) issues, blog posts, HN discussions for blockers. - - Project context: - Candidate: - - Return: - - Verdict: ✅ (no blocker) / ⚠️ (minor concerns) / ❌ (deal-breaker) - - Three bullet points justifying the verdict - concrete, citing specific tech facts - - Cost estimate confirmation: agree / disagree with the proposed monthly cost - ``` - -2. Wait for all agents to return. Aggregate verdicts into the table. -3. If **every** candidate returns `❌`: print the verdicts, surface the common blocker, and loop back to action 02 with explicit guidance on what to change. Do not proceed to action 04. -4. If **at least one** candidate is `✅` or `⚠️`: print the augmented table + per-candidate rationale to the user. Pass control to action 04. - -## Test - -Each candidate row from action 02 has a corresponding verdict in `{✅, ⚠️, ❌}` and a rationale block with exactly 3 bullets; if all verdicts are ❌, the flow does not advance to action 04 and a guidance message back to 02 is printed. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/03-choose-stack.md b/plugins/aidd-context/skills/01-bootstrap/actions/03-choose-stack.md new file mode 100644 index 00000000..2a347e4c --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/03-choose-stack.md @@ -0,0 +1,19 @@ +# 03 - Choose stack + +Propose candidate stacks, audit them, let the user pick, and settle the architecture pattern. Pure decision-making - writes nothing to disk (that is `04-init-install-md`). + +## Inputs + +- Gathered needs + building blocks (from `02-gather-needs`). +- `@../references/stack-heuristics.md`. + +## Process + +1. Derive 2-3 candidate stacks from the needs using the heuristics; they must span the trade-off space (hosting model / back-end language / pattern). Render a comparison table (front, back, DB, hosting, auth, pattern, cost, risks). +2. **Audit each candidate in parallel** (one agent per candidate): tech compatibility, ecosystem maturity, known gotchas → verdict ✅ / ⚠️ / ❌ + a 3-bullet rationale. If every candidate is ❌, revise the candidates and re-audit. +3. **User picks the winner** by letter. Refuse a ❌ pick; for a ⚠️ pick, surface the risks and require a mitigation. +4. Settle the **architecture pattern** for the chosen stack (fact-checked top-3, user picks one), then derive the high-level modules and a Mermaid diagram (via the mermaid capability). + +## Test + +- [ ] A comparison table with ≥2 audited candidates; user picked a non-❌ winner in writing; an architecture pattern is chosen; a Mermaid diagram parses without error. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/04-init-install-md.md b/plugins/aidd-context/skills/01-bootstrap/actions/04-init-install-md.md new file mode 100644 index 00000000..9bafb3e4 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/04-init-install-md.md @@ -0,0 +1,21 @@ +# 04 - Init INSTALL.md + +Write the project's `INSTALL.md` (and project-root `README.md`) from the chosen stack, needs, and architecture. **This is where `INSTALL.md` is born** - every build action reads it. + +## Inputs + +- Chosen stack + architecture pattern + Mermaid diagram (from `03-choose-stack`). +- Gathered needs + building blocks (from `02-gather-needs`). +- `@../assets/INSTALL.md`, `@../assets/README.md` - the skeletons. + +## Process + +1. Fill the `INSTALL.md` skeleton: vision, decisions (+ a one-line *why* each), stack summary, building-blocks table, architecture (paste the Mermaid diagram + module boundaries), and install / configure / run / test steps. +2. Write `INSTALL.md` at the project root. If it already exists, ask before overwriting. +3. Fill and write the project-root `README.md` from its template; leave no raw `{{...}}`. +4. Print the written paths. + +## Test + +- [ ] `INSTALL.md` exists and is filled (vision, decisions, stack, building blocks, architecture with a Mermaid block, steps). +- [ ] `README.md` exists with no raw placeholders. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md b/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md deleted file mode 100644 index a6c8d3d8..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md +++ /dev/null @@ -1,67 +0,0 @@ -# 04 - Pick and design - -User picks the winning candidate (informed by audit). Generate the folder structure tree and a Mermaid module diagram. Fill block 4 of the checklist with the concrete choices. - -## Inputs - -- Augmented comparison table from action 03 (with verdicts and rationale). -- Filled checklist blocks 1-3. - -## Outputs - -Three artifacts held in conversation context (not yet written to disk): - -1. The checklist with **block 4 filled** (architecture pattern, front, back, DB, auth, final hosting). -2. A folder-structure code block showing the project root tree. -3. A Mermaid diagram showing modules and their relations. - -```markdown -## Folder structure - -`​`​` -acme-invoicing/ -├── apps/ -│ ├── web/ # Next.js app -│ └── workers/ # Background jobs (BullMQ) -├── packages/ -│ ├── db/ # Drizzle schema + migrations -│ ├── api/ # tRPC routers shared between web and workers -│ └── ui/ # shared React components -├── infra/ -│ └── supabase/ # Supabase project config + RLS policies -├── aidd_docs/ -│ └── INSTALL.md -└── package.json -`​`​` - -## Architecture diagram - -`​`​`mermaid -graph TD - User --> Web[Next.js Web] - Web --> API[tRPC API] - API --> DB[(Supabase Postgres)] - API --> Airtable[Airtable SDK] - Web --> Auth[NextAuth] - Workers[BullMQ Workers] --> DB - Workers --> Slack[Slack API] -`​`​` -``` - -## Depends on - -- `03-audit-candidates` - -## Process - -1. Print the action 03 augmented table. Ask the user to pick a candidate by letter (A / B / C). -2. If the picked candidate has verdict `⚠️`, surface the audit concerns directly: list the specific risks found in action 03, ask whether the user has a mitigation plan, and loop until satisfied or candidate is switched. -3. If the picked candidate has verdict `❌`, refuse the pick and loop back to letting the user choose differently. (Do not proceed with a known-broken stack.) -4. Fill block 4 of the checklist with the picked candidate's concrete choices. Show the user the full filled checklist and ask them to confirm "go". -5. Generate the folder-structure tree following conventions from the picked stack: monorepo (`apps/`, `packages/`) for modular monolith; flat `src/` for monolith; `services/` per service for microservices; `functions/` for serverless. Reflect every component listed in block 4. -6. Generate the Mermaid module diagram by invoking `aidd-context:09-mermaid`. Pass it the list of modules and their relations derived from the folder tree. Verify the rendered diagram passes Mermaid syntax (no parser errors). -7. Print the tree + diagram together. Wait for user confirmation before action 05. - -## Test - -The checklist's block 4 has all 6 items filled with no remaining `<...>` placeholders; a folder-structure code block is rendered; a Mermaid code block tagged ` ```mermaid ` is present and parses without error; the user has confirmed in writing. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/05-init-architecture.md b/plugins/aidd-context/skills/01-bootstrap/actions/05-init-architecture.md new file mode 100644 index 00000000..26442c9c --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/05-init-architecture.md @@ -0,0 +1,20 @@ +# 05 - Init architecture + +Materialize the architecture from `INSTALL.md` (produced by `04-init-install-md`): the folder/route tree and reachable stubs, following the chosen pattern. Structure only - no behavior. + +## Inputs + +- `INSTALL.md` (produced by `04-init-install-md`) - folder tree, architecture pattern, conventions. + +## Process + +1. Create the directory tree exactly as `INSTALL.md` describes, following the chosen pattern. +2. For every route (front + back), create one reachable stub: navigation resolves, handlers respond empty. No business logic. +3. Apply naming / colocation conventions uniformly. + +## Test + +- [ ] Tree matches `INSTALL.md`; architecture conforms to the chosen pattern. +- [ ] Every route is reachable (front navigates, API responds). +- [ ] *(frontend)* Default pages exist: 404, 403. +- [ ] No business logic present (architecture-100% / business-0%). diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md b/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md deleted file mode 100644 index 73347fd1..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md +++ /dev/null @@ -1,57 +0,0 @@ -# 05 - Write INSTALL.md - -Produce `aidd_docs/INSTALL.md` from the filled checklist, folder tree, diagram, and audit summary. This is the only file this skill writes to disk. - -## Inputs - -- Filled checklist (from action 04). -- Folder structure code block (from action 04). -- Mermaid diagram (from action 04). -- Augmented audit table (from action 03). - -## Outputs - -A new file at `aidd_docs/INSTALL.md` filled from `@../assets/install-template.md`. - -```markdown -# INSTALL.md - acme-invoicing - -Technical vision and installation guide. - -## Vision -... -## Decisions -... -## Stack summary -... -## Architecture -... -## Folder structure -... -## Install steps -... -## Audit summary -... -``` - -## Depends on - -- `04-pick-and-design` - -## Process - -1. Read `@../assets/install-template.md`. This is the skeleton. -2. Fill each placeholder from upstream artifacts: - - **Vision**: project name + one-liner from block 1 - - **Decisions table**: each row from block 4 paired with a one-line `Why` derived from block 2-3 constraints - - **Stack summary**: concrete versions / SaaS plans where known - - **Architecture**: paste the Mermaid diagram from action 04 + 2-3 sentences explaining module boundaries - - **Folder structure**: paste the tree from action 04 verbatim - - **Install steps**: 3-7 imperative steps the user runs to bring up the empty project (init repo, install runtimes, create cloud accounts, set env vars). No code generation - this is a checklist, not a script. - - **Audit summary**: paste the augmented table from action 03, keep verdicts + one-line notes -3. Write the filled content to `aidd_docs/INSTALL.md` in the user's project root. If the file already exists, ask before overwriting. -4. Print the relative path of the written file and a short summary (which sections were filled, total length). - -## Test - -`aidd_docs/INSTALL.md` exists and parses as markdown; it contains exactly these `## ` H2 headings in order: `Vision`, `Decisions`, `Stack summary`, `Architecture`, `Folder structure`, `Install steps`, `Audit summary`; the `Architecture` section contains a fenced ` ```mermaid ` block; the `Folder structure` section contains a fenced code block with at least 5 lines. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/06-init-dependencies.md b/plugins/aidd-context/skills/01-bootstrap/actions/06-init-dependencies.md new file mode 100644 index 00000000..3d5c6c62 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/06-init-dependencies.md @@ -0,0 +1,21 @@ +# 06 - Init dependencies + +Set up the chosen dependency manager, wire each building block, install, and prove the app boots. Reads `INSTALL.md`; names no technology of its own. + +## Inputs + +- `INSTALL.md` - the dependency manager, stack, and building blocks to install (still design-only at this point - not yet in code). +- The materialized structure (`05-init-architecture`) to install into. + +## Process + +1. Initialize the dependency manager declared in `INSTALL.md`. +2. Add the stack plus each building block as a **swappable abstraction** - dev stub + real provider, chosen by env flag. +3. Install dependencies. +4. Boot the app. + +## Test + +- [ ] Dependencies install clean. +- [ ] App boots. +- [ ] Each building block resolves through its abstraction (stub by default). diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/07-init-env.md b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-env.md new file mode 100644 index 00000000..b722c133 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-env.md @@ -0,0 +1,19 @@ +# 07 - Init env + +Environment and secrets. Enumerate every variable the project needs and wire config loading. No secret values committed. + +## Inputs + +- The building blocks and runtime wired by `06-init-dependencies` - they determine the required env keys. + +## Process + +1. Derive the required env keys from the building blocks wired in `06` (each provider, the database, the runtime). +2. Write `.env.example` listing every key with a placeholder - never a real value. +3. Wire config loading so the app reads from the environment. + +## Test + +- [ ] `.env.example` lists every required key. +- [ ] App reads its config from the environment. +- [ ] No secret value committed. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/08-init-database.md b/plugins/aidd-context/skills/01-bootstrap/actions/08-init-database.md new file mode 100644 index 00000000..b4913115 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/08-init-database.md @@ -0,0 +1,22 @@ +# 08 - Init database + +Stand up the database: connection, migration tool, a baseline migration, seed fixtures, and a proven round-trip. Conditional - skip when the project has no database (no DB driver was installed in `06`). + +## Inputs + +- The database driver and migration tool installed by `06-init-dependencies`. +- The connection config from `07-init-env`. + +## Process + +1. Configure the connection from the environment (see `07-init-env`). +2. Set up the migration tool installed in `06`. +3. Create and run a baseline migration. +4. Add seed **fixtures** (minimal sample data) behind a repeatable, idempotent load command. +5. Prove a round-trip: load the fixtures, then connect and query them back. + +## Test + +- [ ] Baseline migration runs. +- [ ] Fixtures load idempotently (re-running the loader is safe). +- [ ] Connection round-trips: a query returns the seeded data. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/09-init-quality-gate.md b/plugins/aidd-context/skills/01-bootstrap/actions/09-init-quality-gate.md new file mode 100644 index 00000000..2ff82dda --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/09-init-quality-gate.md @@ -0,0 +1,21 @@ +# 09 - Init quality gate + +Wire static quality as one cohesive gate: typecheck + format + lint + commit-message linter + a pre-commit hook that runs them. Names no tool of its own - they follow the project's stack. + +## Inputs + +- The materialized project's language and stack (from `06-init-dependencies`) - they determine the concrete tools. + +## Process + +1. Configure typecheck, formatter, and linter for the project's stack. +2. Configure the commit-message linter. +3. Wire a pre-commit hook running format + lint + typecheck (and unit tests once `10-init-tests` exists). +4. Prove the hook blocks a deliberately bad commit. + +## Test + +- [ ] Typecheck, format, lint each run clean on the stub tree. +- [ ] Commit-message linter rejects a malformed message. +- [ ] Pre-commit hook blocks a bad commit and passes a clean one. +- [ ] *(frontend)* Accessibility tooling and a performance budget are configured. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/10-init-tests.md b/plugins/aidd-context/skills/01-bootstrap/actions/10-init-tests.md new file mode 100644 index 00000000..693ea723 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/10-init-tests.md @@ -0,0 +1,20 @@ +# 10 - Init tests + +Install the test harness and prove it: one unit test, one end-to-end test, coverage on. Delegate the test-writing to the testing capability. + +## Inputs + +- The materialized project: the structure under test (`05-init-architecture`) and the stack installed (`06-init-dependencies`). + +## Process + +1. Install and configure the test runner + coverage reporting for the project's stack. +2. Delegate to the **testing capability** (discovered by description) to write one passing unit test and one passing end-to-end test (a per-surface smoke). +3. Run the suite. + +## Test + +- [ ] Unit test passes. +- [ ] End-to-end test passes. +- [ ] Coverage is reported. +- [ ] *(frontend)* A form submits through its validation layer and is covered by a test. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/11-init-containers.md b/plugins/aidd-context/skills/01-bootstrap/actions/11-init-containers.md new file mode 100644 index 00000000..92e0a5c2 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/11-init-containers.md @@ -0,0 +1,20 @@ +# 11 - Init containers + +Make the project's runtime reproducible: a container/compose definition that ups and downs cleanly. Conditional - skip when `INSTALL.md` declares no container/runtime. + +## Inputs + +- Whether the project is containerized - a deployment decision in `INSTALL.md` (no Dockerfile exists yet to read it from). +- The running app and its datastores (`06-init-dependencies`, `08-init-database`) to containerize. + +## Process + +1. Write the container / compose definition for the project's runtime (app + its datastores). +2. Bring it up. +3. Prove the app responds. +4. Bring it down cleanly. + +## Test + +- [ ] Up: app responds. +- [ ] Down: clean teardown, no orphaned container/volume. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/12-init-design-system.md b/plugins/aidd-context/skills/01-bootstrap/actions/12-init-design-system.md new file mode 100644 index 00000000..1f433fd4 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/12-init-design-system.md @@ -0,0 +1,17 @@ +# 12 - Init design system + +Establish the project's design system. Front-end only - skip when the project has no frontend. Delegates entirely; owns no design logic. + +## Inputs + +- Whether the project has a frontend (evident from the materialized project). The design system's content comes from the design tool. + +## Process + +1. If no frontend, skip and record why. +2. Otherwise delegate to the **design-system capability** (discovered by description; it routes to the design tool) to establish color strategy, typography, spacing, and tokens into the canonical design document. + +## Test + +- [ ] Frontend project: the design document exists (single source of truth). +- [ ] Backend-only project: explicitly skipped, with the reason recorded. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/13-init-ci.md b/plugins/aidd-context/skills/01-bootstrap/actions/13-init-ci.md new file mode 100644 index 00000000..74492edb --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/13-init-ci.md @@ -0,0 +1,19 @@ +# 13 - Init CI + +Wire continuous integration: a minimal pipeline that runs the project's quality gate and tests, green on the server. Conditional - skip when the project declares no CI platform. + +## Inputs + +- `INSTALL.md` +- `aidd_docs/vcs/memory` + +## Process + +1. Emit a minimal pipeline that runs the quality gate and the tests. +2. Commit, push +3. Confirm the run is green on the server. + +## Test + +- [ ] CI config committed. +- [ ] Pipeline is green on the server. diff --git a/plugins/aidd-context/skills/01-bootstrap/assets/INSTALL.md b/plugins/aidd-context/skills/01-bootstrap/assets/INSTALL.md new file mode 100644 index 00000000..6395e1ad --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/assets/INSTALL.md @@ -0,0 +1,60 @@ +# INSTALL.md - `` + +Architecture decisions + install guide (ADR-style: what chosen, why, how to install). + +## Vision + +`` + +`<2-3 sentences expanding on the value proposition, target users, and core differentiator>` + +## Stack + +| Decision | Choice | Why | +| ------------ | ------------- | ------------------------------------------- | +| Architecture | `` | `` | +| Front-end | `` | `` | +| Back-end | `` | `` | +| Database | `` | `` | +| Auth | `` | `` | +| Hosting | `` | `` | + +## Building blocks + +Technical capabilities wired for this project - only ones the app needs. + +| Block | Tech | +| ------------------------- | ---- | +| **Data** | | +| **Auth** | | +| **Email** | | +| **File storage** | | +| **Background jobs** | | +| **Scheduled jobs** (CRON) | | +| **Payments** | | +| **Logging/errors** | | + +## Architecture + +```mermaid + +``` + +`<2-3 sentences explaining the diagram: which modules talk to which, where the boundary is>` + +## Install, configure, run, test + +Prerequisites: ``, ``, ``, ``. + +```bash + +``` + +- Configure: set env vars the project needs (``); set data-provider flag (``) to `in-memory` (local) or the real provider. + +```bash + + +``` + +Unit tests run against in-memory provider; end-to-end tests use the real one. diff --git a/plugins/aidd-context/skills/01-bootstrap/assets/README.md b/plugins/aidd-context/skills/01-bootstrap/assets/README.md new file mode 100644 index 00000000..0aa57d6f --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/assets/README.md @@ -0,0 +1,24 @@ +# {{PROJECT_NAME}} + +> Scaffolded with AIDD. Architecture skeleton only - business logic to follow. + +## Stack + +- Front-end: {{FRONTEND_FRAMEWORK}} +- Back-end: {{BACKEND_FRAMEWORK}} +- Tests: {{TEST_FRAMEWORK}} +- Database: {{DATABASE}} + +Each technical building block (data, plus any of email, auth, storage, jobs, CRON, payments, logging the app uses) wired as a swappable abstraction - see [`INSTALL.md`](INSTALL.md). + +## Getting started + +Install, configure, run, test instructions: [`INSTALL.md`](INSTALL.md). + +## Project docs + +- [`INSTALL.md`](INSTALL.md) - technologies, why chosen, how to install / run / test. + +## Status + +Routes wired with stub handlers (no business logic). Start your first feature in `{{SRC_DIR}}`. diff --git a/plugins/aidd-context/skills/01-bootstrap/assets/install-template.md b/plugins/aidd-context/skills/01-bootstrap/assets/install-template.md deleted file mode 100644 index cb2c22e5..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/assets/install-template.md +++ /dev/null @@ -1,63 +0,0 @@ -# INSTALL.md - `` - -Technical vision and installation guide. - -## Vision - -`` - -`<2-3 sentences expanding on the value proposition, target users, and core differentiator>` - -## Decisions - -| Decision | Choice | Why | -| ------------------ | ----------------- | -------------------------------------------------- | -| Architecture | `` | `` | -| Front-end | `` | `` | -| Back-end | `` | `` | -| Database | `` | `` | -| Auth | `` | `` | -| Hosting | `` | `` | - -## Stack summary - -- **Front-end:** `` -- **Back-end:** `` -- **Database:** `` -- **Auth:** `` -- **Hosting:** `` -- **Key integrations:** `` - -## Architecture - -```mermaid - -``` - -`<2-3 sentences explaining the diagram: which modules talk to which, where the boundary is>` - -## Folder structure - -``` -/ -├── ... -└── ... -``` - -## Install steps - -Manual install - the framework does not yet scaffold these automatically. - -1. `` -2. `` -3. `` - -## Audit summary - -Results of the multi-agent audit run during action 03: - -| Candidate | Verdict | Notes | -| -------------------- | ------- | ------------------------------ | -| `` | ✅ / ⚠️ / ❌ | `` | -| `` | ✅ / ⚠️ / ❌ | `` | -| `` | ✅ / ⚠️ / ❌ | `` | diff --git a/plugins/aidd-context/skills/01-bootstrap/assets/checklist.md b/plugins/aidd-context/skills/01-bootstrap/references/checklist.md similarity index 100% rename from plugins/aidd-context/skills/01-bootstrap/assets/checklist.md rename to plugins/aidd-context/skills/01-bootstrap/references/checklist.md diff --git a/plugins/aidd-context/skills/01-bootstrap/references/stack-heuristics.md b/plugins/aidd-context/skills/01-bootstrap/references/stack-heuristics.md index ee8632e4..6400ad0d 100644 --- a/plugins/aidd-context/skills/01-bootstrap/references/stack-heuristics.md +++ b/plugins/aidd-context/skills/01-bootstrap/references/stack-heuristics.md @@ -1,75 +1,32 @@ -# Stack heuristics +# Stack choice guide -Mapping rules from checklist signals to recommended stack families. Use these when proposing candidates in action 02. Heuristics, not laws - override when audit (action 03) flags a conflict. +Reason about a stack from checklist signals - **axes to decide, not products to impose**. Never name one right answer. Any product mentioned is one illustration, never a default. When axes conflict, surface the trade-off to the user; don't choose silently. -## Architecture pattern +## Decide along these axes -| Signal (from checklist) | Pattern | -| ---------------------------------------------------------------------- | ---------------------- | -| Solo or 2-dev team, < 10k users, < 5 features, no real-time | **Monolith** | -| Mid-size team, growing features, want clean modules | **Modular monolith** | -| Many decoupled domains, each with its own scaling profile | **Microservices** | -| Bursty traffic, low ops budget, short-lived requests, no persistent connections | **Serverless** | -| Real-time + low latency required + WebSockets | **Monolith / serverless edge** (avoid pure microservices) | +1. **Form factor** - what's being built? Web app, mobile (native or cross-platform), desktop, CLI, library/SDK, API-only service, data pipeline. Decides almost everything downstream; settle first. +2. **Product type** - SaaS, internal tool, marketing/content site, prototype, API product. Drives need for multi-tenancy, auth, SEO, billing. +3. **Front-end** (if any) - rendering need (server-rendered vs single-page vs static), interactivity, SEO requirement, accessibility, offline. Pick rendering model first, framework second. +4. **Back-end** (if any) - compute profile (request/response, long-running, real-time, heavy compute), team language expertise, throughput. Expertise usually beats "best tool" when learning curve is long. +5. **Tests** - which layers matter (unit, integration, end-to-end), what each must prove. Test framework follows language and layers, not fashion. +6. **Data** (if any) - persistence needed at all? Shape (relational, document, key-value, search, event log), consistency, compliance/region. "No database" is a valid, common answer. -## Front-end +## How to weigh conflicts -| Signal | Recommendation | -| ----------------------------------------------------------------- | --------------------------------- | -| SEO important + content-heavy | **Next.js SSR** or **Astro SSR** | -| SEO not important + interactive dashboard | **Vite + React SPA** | -| Mobile native required | **React Native / Expo** + web app | -| Marketing site + product app | **Astro (marketing) + Next.js (app)** or **Next.js everything** | -| Offline-first (PWA, local sync) | **Next.js + service worker** or **RxDB-based stack** | +Prioritize in this order, let the rest follow: -## Back-end +1. **Compliance / data sensitivity** (GDPR, health) - caps hosting region and data choices. +2. **Hard functional needs** (real-time, offline, multi-tenant) - rule out incompatible options early. +3. **Team expertise** - a stack the team can't operate is the wrong stack. +4. **Budget and ops capacity** - prune anything the team can't afford to run. -| Signal | Recommendation | -| ----------------------------------------------------------------- | --------------------------------- | -| Team knows TypeScript, no exotic perf needs | **Next.js API routes** or **NestJS** | -| Team knows Python, ML/data-heavy | **FastAPI** | -| Team knows Go, high-throughput backend | **Echo / Fiber** | -| Real-time chat, websockets, live sync | **Node + Socket.io** or **Phoenix (Elixir)** | -| Heavy compute (video, ML inference) | **FastAPI + worker queue (Celery / BullMQ)** | +## Architecture patterns (generic, language-agnostic) -## Database +Patterns, not products - applicable in any language: -| Signal | Recommendation | -| ----------------------------------------------------------------- | --------------------------------- | -| Relational data, transactions, GDPR | **PostgreSQL** (Supabase, Neon, RDS) | -| Document-shaped data, schema fluctuates often | **MongoDB** or **Postgres JSONB** | -| Existing Airtable as source of truth | **Airtable SDK + Postgres cache layer** | -| Search-heavy (full-text, faceted) | **Postgres + tsvector** OR **Postgres + Meilisearch** | -| Real-time pub/sub | **Supabase Realtime** or **Redis pub/sub** | -| Event sourcing | **Postgres + outbox pattern** | +- **Monolith** - one deployable; simplest to build and operate; default until a constraint forces otherwise. +- **Modular monolith** - one deployable with enforced internal module boundaries; good when team wants future extractability. +- **Microservices** - many independently deployable services; justified by independent scaling or team boundaries, not by default. +- **Serverless / functions** - per-request units; fits bursty, short-lived, low-ops workloads; avoid when long-lived connections are core. -## Auth - -| Signal | Recommendation | -| ----------------------------------------------------------------- | --------------------------------- | -| Next.js + Postgres | **NextAuth (Auth.js)** | -| Need polished UI, magic links, OAuth, no time to build | **Clerk** | -| Already on Supabase | **Supabase Auth** | -| Enterprise SSO required | **Auth0** or **WorkOS** | -| B2B with org-level access control | **Clerk Organizations** or **WorkOS** | - -## Hosting - -| Signal | Recommendation | -| ----------------------------------------------------------------- | --------------------------------- | -| Next.js + low ops budget | **Vercel** | -| Solo dev + Postgres + bootstrap budget | **Vercel + Supabase** or **Railway** | -| Heavy backend, custom infra | **AWS (ECS / Fargate)** or **GCP Cloud Run** | -| EU data residency required | **Scaleway**, **OVH**, or AWS eu-west-3 | -| Self-hosted preference | **Coolify** or **Dokku** on VPS | - -## Conflicting-signal triage - -When two signals push to different stacks, prioritize in this order: - -1. **Data sensitivity (GDPR/health)** - overrides hosting region preference -2. **Real-time + multi-tenant** - overrides cost preference (forces non-trivial backend) -3. **Team language expertise** - overrides "best tool" if learning curve > 2 weeks -4. **Budget** - caps everything else; prune candidates that exceed it - -When still ambiguous, surface the trade-off to the user in the comparison table (action 02) instead of choosing silently. +Match pattern to real constraints (team size, scaling profile, ops budget), not trend. When ambiguous, propose two candidates and let the user choose. diff --git a/plugins/aidd-context/skills/12-design-system/README.md b/plugins/aidd-context/skills/12-design-system/README.md new file mode 100644 index 00000000..a74807f5 --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/README.md @@ -0,0 +1,22 @@ +# 07 - Design System + +Guided onboarding for authoring a **quality design system**, wrapping the [Impeccable](https://impeccable.style) skill. Impeccable does the work (palette, typography, tokens, `DESIGN.md`); this skill adds the ordered playbook so no essential step is skipped. It writes **no design files of its own** - Impeccable's `DESIGN.md` stays canonical. + +## Usage + +``` +/aidd-context:12-design-system +``` + +Manual only. Two actions, both Impeccable runbooks with per-step checkboxes: + +- `01-create-design-system` - setup: `init` -> `document` -> `extract` -> refine -> `audit`/`critique`. +- `02-redesign-page` - improve an existing page. The AI invokes every Impeccable command itself; the user only answers questions and validates: `critique` (baseline score) -> ask what hurts -> axis commands (`layout`/`typeset`/`colorize`/`bolder`/`quieter`/`distill`/`animate`) -> show & validate -> `polish`/`audit`/re-`critique`, looping until no P0/P1 and the score beats the baseline. New patterns fold back via `extract`. + +## Requires + +The **Impeccable** skill (the playbook checks and guides install if missing). + +## Not for + +Authoring **new** page or component code - that is an implementation concern (Execution layer), where the implementer delegates the visual to Impeccable against this `DESIGN.md`. This skill founds the system and routes redesigns; Impeccable does the work and `DESIGN.md` stays canonical. diff --git a/plugins/aidd-context/skills/12-design-system/SKILL.md b/plugins/aidd-context/skills/12-design-system/SKILL.md new file mode 100644 index 00000000..3adc4d38 --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/SKILL.md @@ -0,0 +1,29 @@ +--- +name: 12-design-system +description: Initialize a project's design system through a guided, ordered playbook that routes each step to the right Impeccable command - register and color strategy, palette with accessibility validation, typography, spacing, elevation, motion, components, and the canonical DESIGN.md. +disable-model-invocation: true +--- + +# Skill: design-system + +Guided onboarding for authoring a quality design system. It does NOT generate the system - the [Impeccable](https://impeccable.style) skill already does (palette, typography, tokens, `DESIGN.md`). It adds the missing piece: an ordered playbook that routes each step to the right Impeccable command. Impeccable executes; `DESIGN.md` stays the single source of truth. + +## Transversal rules + +- **One source of truth**: Impeccable's root `DESIGN.md` (+ `.impeccable/design.json`). Never write a competing design file or a copy. Point, never copy. +- **Impeccable is a declared external dependency** - naming its commands is allowed; if absent, the playbook guides install. +- Per-step criteria are inline checkboxes in the action (walked as an AI-driven todo). No assets - the skill keeps no derived copy of `DESIGN.md`. +- English-only. + +## Available actions + +| # | Action | Role | Input | +| --- | ---------------------- | ---------------------------------------------------------- | ------------------ | +| 01 | `create-design-system` | Walk the playbook to a quality design system via Impeccable | project (optional) | +| 02 | `redesign-page` | Critique → fix weak axes → loop until the score holds | page (required) | + +## Default flow + +`01` founds the system (run once); `02` redesigns an existing page against it (run anytime, requires `DESIGN.md`). Both confirm Impeccable is available, then drive its commands. + +Authoring **new** page code is not this skill's concern (Knowledge layer) - that happens at implementation time, where the implementer delegates the presentational layer to Impeccable against this `DESIGN.md`. Redesigning an **existing** page's visual (action 02) is routing, not authoring: Impeccable executes, this skill orders the loop. diff --git a/plugins/aidd-context/skills/12-design-system/actions/01-create-design-system.md b/plugins/aidd-context/skills/12-design-system/actions/01-create-design-system.md new file mode 100644 index 00000000..6ab8c585 --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/actions/01-create-design-system.md @@ -0,0 +1,80 @@ +# 01 - Create design system + +A setup runbook: run Impeccable's commands in sequence, each setting up part of the design system. Output is Impeccable's canonical `DESIGN.md` (+ `PRODUCT.md` + `.impeccable/design.json`); this action only adds the ordering, the routing, and the per-step checks. Walk it as a todo: tick each checkbox once the command has produced it. + +## Inputs + +- `project` (optional, default: CWD) - project root to set the design system up in. +- `brand_intent` (optional) - a brand/product phrase if the user already has one; otherwise Impeccable's interview gathers it. + +## Outputs + +Impeccable-owned, at the project root (this action drives the commands, it doesn't write them): + +``` +PRODUCT.md # strategy: register, users, brand, anti-references +DESIGN.md # the single source of truth: tokens + 6 Stitch sections +.impeccable/design.json # sidecar: ramps, shadows, motion, components +``` + +## Process + +Run the commands in order. **Each step IS an Impeccable command**; tick its checkboxes once they hold. + +### Step 0 - Ensure the engine + +- [ ] `/impeccable` responds (installed). If absent, guide install (), then stop. Never emulate it. + +### Step 1 - `/impeccable init` + +Strategic foundation every later command reads. `init` defers all visual choices to `document` - it does not touch colors, fonts, or radii. + +- [ ] Register chosen: brand (design IS the product) vs product (design SERVES it) +- [ ] `PRODUCT.md` written: users, brand personality, anti-references, principles + +### Step 2 - `/impeccable document` + +The visual system, written to the canonical `DESIGN.md` + `.impeccable/design.json` sidecar (scan mode if code exists, seed mode if not). + +- [ ] Color strategy (Restrained / Committed / Full / Drenched) + one concrete mood sentence (not "modern/clean") +- [ ] Brand seed as OKLCH anchor (`palette.mjs` runs at Impeccable setup for new projects) +- [ ] Colors: semantic roles (primary/secondary/tertiary/neutral), OKLCH, descriptive slugs +- [ ] 8-step tonal ramp per major color (sidecar) +- [ ] Typography: pairing on a contrast axis, <=3 families +- [ ] Type scale + hierarchy (display/headline/title/body/label), step ratio >=1.25 +- [ ] Readability: line 65-75ch, clamp <=6rem, letter-spacing >=-0.04em, no all-caps body +- [ ] Spacing + radius token scales +- [ ] Elevation strategy stated (flat / tonal / shadows) +- [ ] Motion tokens + `prefers-reduced-motion` alternative +- [ ] Components documented with all states (default/hover/focus/active/disabled/loading/error) +- [ ] `DESIGN.md`: the six Stitch sections in order + token frontmatter +- [ ] Do's & Don'ts (section 6) tie to `PRODUCT.md` anti-references + +### Step 3 - `/impeccable extract` (existing codebases only) + +- [ ] Repeated patterns + hard-coded values consolidated into reusable tokens/components, folded into `DESIGN.md` + +### Step 4 - Refine the weak axis (only what the baseline flags; skip sound axes) + +- [ ] Weak axis addressed: `typeset` (type) - `colorize` (color) - `layout` (rhythm) - `animate` (motion) + +### Step 5 - `/impeccable audit` + `/impeccable critique` + +Validate and capture the backlog. + +- [ ] Contrast: body >=4.5:1, large >=3:1, placeholder >=4.5:1, UI >=3:1; no gray-on-tint; color-blind safe +- [ ] `audit` reports no P0 (a11y, responsive, anti-patterns) +- [ ] `critique` score snapshot + P0/P1 backlog captured + +### Step 6 - Showcase & sign-off + +See the whole system rendered, then validate it. + +- [ ] Design system reviewed visually - `/impeccable live` (in-browser panel: color tiles + component primitives from `DESIGN.md`/sidecar; needs a dev server, renders even day-zero) OR `/impeccable craft "design-system styleguide page"` for a built, shareable showcase +- [ ] Tokens + components match the intended brand; signed off + +**Ongoing (later, not this flow):** evolve via `/impeccable shape` / `craft` / `live` / `harden` / `polish`, re-`critique` to track the trend. + +## Test + +After running: `DESIGN.md` exists at the project root with the six section headers (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) + a token frontmatter block, and `/impeccable audit` reports no P0 contrast failure. Real-execution on disk, never mocked. diff --git a/plugins/aidd-context/skills/12-design-system/actions/02-redesign-page.md b/plugins/aidd-context/skills/12-design-system/actions/02-redesign-page.md new file mode 100644 index 00000000..b2487ffd --- /dev/null +++ b/plugins/aidd-context/skills/12-design-system/actions/02-redesign-page.md @@ -0,0 +1,97 @@ +# 02 - Redesign a page + +An executable playbook: **you (the AI) invoke each Impeccable command yourself** - the user never types one. The user only answers questions and validates results between steps. Walk the steps in order as a todo; each step says what to invoke, what to ask, and when to move on. Impeccable writes the code; `DESIGN.md` stays the single source of truth. + +## Inputs + +- `page` (required) - the page to redesign: a route (`/pricing`), a source path (`src/pages/pricing.tsx`), or a dev-server URL. Prefer a source path; ports drift, paths do not. If missing, ask for it first. + +## Outputs + +- The page restyled by Impeccable against the canonical `DESIGN.md`. +- A `critique` snapshot trail (baseline → final) proving the improvement. +- `DESIGN.md` updated **only via `extract`** - never by hand. + +## Process + +### Step 1 - Check the ground + +**Do:** verify `/impeccable` responds and `DESIGN.md` exists at the project root - and that it has a point of view. + +- If Impeccable is absent: guide install (), then stop. Never emulate it. +- If `DESIGN.md` is absent: run action [01-create-design-system](01-create-design-system.md) first - redesigning without a system just produces new drift. +- If `DESIGN.md` is **generic**, fix it before redesigning - every command aligns the page to it, so a bland system caps the ceiling (polished garbage stays garbage). Generic means any of: no anti-references in `PRODUCT.md`, color strategy Restrained-by-default when the brief wants impact, mood sentence that says "modern/clean". Route to action 01 steps 1-2 (`init` / `document`) to re-found it, then come back. + +### Step 2 - Measure: invoke `/impeccable critique ` + +**Do:** invoke it now - it is the measurement, not an option. It scores Nielsen's 10 heuristics 0-4 (total /40; real interfaces land 20-32), persists a snapshot, and returns the P0/P1 backlog. + +Critique's own flow ends by presenting findings and asking the user targeted questions (it STOPs and calls AskUserQuestion itself). **Let it** - don't summarize over it or re-ask. + +### Step 3 - Complete the brief + +**Do:** critique's questions cover what is broken; add only what they don't, in one AskUserQuestion: + +1. Is the page wrong (structure, content order) or just ugly (style)? - this decides Step 4's route +2. Any direction already in mind? (bolder, calmer, simpler...) + +Critique's answers + these two are the brief for everything below. + +### Step 4 - Fix: invoke one command per weak axis + +**Do:** route from the critique backlog + the user's answers, top severity first. Impeccable's own rule applies: a command is a suggestion the user confirms - name the command and the reason, get a yes, then invoke. One command, show the result, then the next. Skip sound axes. + +**Fix defects** (convergent - removes what is broken): + +| Symptom (critique + user) | Invoke | +| ------------------------------------------- | ----------------------------- | +| Score low across the board, many small P1s | `/impeccable polish ` - it reads the critique snapshot as its backlog | +| Hierarchy flat, spacing off, crowded | `/impeccable layout ` | +| Type generic, sizes arbitrary, hard to read | `/impeccable typeset ` | +| Gray, dull, monochrome | `/impeccable colorize ` | +| Loud, garish, overwhelming | `/impeccable quieter ` | +| Cluttered, competing for attention | `/impeccable distill ` | +| Copy confusing, labels unclear | `/impeccable clarify ` | +| Breaks on mobile / other viewports | `/impeccable adapt ` | + +**Add ambition** (divergent - the score won't flag these; only the user's "still ugly" does): + +| Symptom (critique + user) | Invoke | +| ------------------------------------------- | ------------------------------- | +| Bland, safe, no personality | `/impeccable bolder ` | +| Correct but forgettable, nothing memorable | `/impeccable delight ` | +| Static, lifeless | `/impeccable animate ` | +| "Wow" is the brief, push past conventional | `/impeccable overdrive ` | + +**Convergent vs divergent - the trap:** `critique`/`audit`/`polish` only remove defects. A page can score 30+/40 with zero P0 and still be boring; another polish loop will never fix that. When the score is fine but the user finds the page bland, take the divergent table - and check Step 1's `DESIGN.md` quality gate first, since a bland system caps every command. + +**If the user said "the page is wrong" in Step 3:** invoke `/impeccable shape " redesign"` instead - it runs its own discovery interview and produces a confirmed brief. Don't stack axis commands on a broken foundation. + +Constraint: changes stay within `DESIGN.md` tokens - no new one-off colors, fonts, or spacing values. + +### Step 5 - Show and ask: good direction? + +**Do:** show the result (screenshot, or offer `/impeccable live` for in-browser variant picking if a dev server runs). Ask: keep, adjust, or revert? + +- Adjust → back to Step 4 with the feedback. +- Keep → next weak axis, or Step 6 when the backlog is done. + +### Step 6 - Verify: invoke the quality gates + +**Do:** invoke in order, yourself: + +1. `/impeccable polish ` - alignment, spacing, micro-details (skip if Step 4 already ran it) +2. `/impeccable audit ` - must report no P0 (a11y, contrast, responsive) +3. `/impeccable critique ` - score must beat the Step 2 baseline, no P0/P1 left + +**If a gate fails:** back to Step 4 with the new backlog. Two stalled loops in a row → the problem is structural, go through `shape`. + +### Step 7 - Fold back: keep the doc impeccable + +**Do:** if the redesign produced repeated patterns or new token needs, invoke `/impeccable extract ` so they fold into `DESIGN.md`. Never edit `DESIGN.md` by hand, never create a competing design file (point, never copy). + +**Then tell the user:** baseline → final score, what changed, what was folded back. + +## Test + +After running: the `critique` snapshot trail shows final score > baseline with zero P0, `audit` reports no P0, and `git diff DESIGN.md` is either empty or produced exclusively by `extract`/`document`. Real-execution on disk, never mocked. diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json index b960944a..8c4521cf 100644 --- a/plugins/aidd-dev/.claude-plugin/plugin.json +++ b/plugins/aidd-dev/.claude-plugin/plugin.json @@ -17,8 +17,7 @@ "./skills/06-test", "./skills/07-refactor", "./skills/08-debug", - "./skills/09-for-sure", - "./skills/10-todo" + "./skills/09-for-sure" ], "agents": [ "./agents/implementer.md", @@ -33,7 +32,7 @@ "refactor", "debug" ], - "repository": "https://github.com/ai-driven-dev/framework", + "repository": "https://github.com/ai-driven-dev/aidd-framework", "homepage": "https://ai-driven.dev", "license": "MIT" } diff --git a/plugins/aidd-dev/.mcp.json b/plugins/aidd-dev/.mcp.json new file mode 100644 index 00000000..39727257 --- /dev/null +++ b/plugins/aidd-dev/.mcp.json @@ -0,0 +1,16 @@ +{ + "mcpServers": { + "playwright": { + "disabled": true, + "type": "stdio", + "command": "npx", + "args": ["@playwright/mcp@latest"], + "env": {} + }, + "figma": { + "disabled": true, + "url": "https://mcp.figma.com/mcp", + "type": "http" + } + } +} diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 770f3553..0dd4f89b 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -48,6 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-implement.md](skills/00-sdlc/actions/03-implement.md) | - | | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | +| `evals` | [scenarios.json](skills/00-sdlc/evals/scenarios.json) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | | `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated.` | @@ -57,12 +58,15 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---|---| | `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | | `actions` | [02-components-behavior.md](skills/01-plan/actions/02-components-behavior.md) | - | - | +| `actions` | [02-design.md](skills/01-plan/actions/02-design.md) | - | - | | `actions` | [03-image-extract-details.md](skills/01-plan/actions/03-image-extract-details.md) | - | - | | `assets` | [master-plan-template.md](skills/01-plan/assets/master-plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | -| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file.` | - | +| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and acceptance criteria.` | - | | `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - | +| `evals` | [scenarios.json](skills/01-plan/evals/scenarios.json) | - | - | | `-` | [README.md](skills/01-plan/README.md) | - | - | | `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | - | +| `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | - | | `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` | - | #### `skills/02-implement` @@ -70,7 +74,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-implement.md](skills/02-implement/actions/01-implement.md) | - | +| `evals` | [scenarios.json](skills/02-implement/evals/scenarios.json) | - | | `-` | [README.md](skills/02-implement/README.md) | - | +| `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | | `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness.` | #### `skills/03-assert` @@ -81,6 +87,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-assert-architecture.md](skills/03-assert/actions/02-assert-architecture.md) | - | | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | | `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `evals` | [scenarios.json](skills/03-assert/evals/scenarios.json) | - | | `-` | [README.md](skills/03-assert/README.md) | - | | `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert features work as intended - general assertions, architecture conformance, and frontend UI validation.` | @@ -96,6 +103,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | - | | `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | - | | `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | - | +| `evals` | [scenarios.json](skills/04-audit/evals/scenarios.json) | - | - | | `-` | [README.md](skills/04-audit/README.md) | - | - | | `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert).` | - | @@ -107,6 +115,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | - | | `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | - | | `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | - | +| `evals` | [scenarios.json](skills/05-review/evals/scenarios.json) | - | - | | `-` | [README.md](skills/05-review/README.md) | - | - | | `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | - | @@ -116,6 +125,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-test.md](skills/06-test/actions/01-test.md) | - | | `actions` | [02-test-journey.md](skills/06-test/actions/02-test-journey.md) | - | +| `evals` | [scenarios.json](skills/06-test/evals/scenarios.json) | - | | `-` | [README.md](skills/06-test/README.md) | - | | `-` | [SKILL.md](skills/06-test/SKILL.md) | `Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser.` | @@ -127,6 +137,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-security.md](skills/07-refactor/actions/02-security.md) | - | | `actions` | [03-cleanup.md](skills/07-refactor/actions/03-cleanup.md) | - | | `actions` | [04-architecture.md](skills/07-refactor/actions/04-architecture.md) | - | +| `evals` | [scenarios.json](skills/07-refactor/evals/scenarios.json) | - | | `-` | [README.md](skills/07-refactor/README.md) | - | | `-` | [SKILL.md](skills/07-refactor/SKILL.md) | `Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill).` | @@ -138,20 +149,22 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-debug.md](skills/08-debug/actions/02-debug.md) | - | | `actions` | [03-reflect-issue.md](skills/08-debug/actions/03-reflect-issue.md) | - | | `assets` | [task-template.md](skills/08-debug/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `evals` | [scenarios.json](skills/08-debug/evals/scenarios.json) | - | | `-` | [README.md](skills/08-debug/README.md) | - | | `references` | [mermaid-conventions.md](skills/08-debug/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `-` | [SKILL.md](skills/08-debug/SKILL.md) | `Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation.` | #### `skills/09-for-sure` -| Group | File | Description | -|-------|------|---| -| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | -| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | -| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | -| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | - | -| `-` | [README.md](skills/09-for-sure/README.md) | - | -| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` | +| Group | File | Description | Argument Hint | +|-------|------|---|---| +| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | - | +| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | - | +| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | - | +| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | `For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.` | - | +| `evals` | [scenarios.json](skills/09-for-sure/evals/scenarios.json) | - | - | +| `-` | [README.md](skills/09-for-sure/README.md) | - | - | +| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` | - | #### `skills/10-todo` diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md index 6895e728..ae744ae0 100644 --- a/plugins/aidd-dev/agents/implementer.md +++ b/plugins/aidd-dev/agents/implementer.md @@ -95,6 +95,7 @@ Anything else is out of bounds. - No TODOs in code, no skipped tests, no placeholder mocks. - No silent workarounds. If you bypass a constraint, declare it in `notes`. +- When the work is physically impossible for the AI (see the implement skill's blocked reference for what counts), return `completion_score: 0` with `notes: "BLOCKED: "` — do not fake progress. You decide this block; the implement layer writes `status: blocked`. - Stay strictly inside the input scope. - Never modify the spec. - Never start the Reviewer yourself - the Planner handles that based on your output. diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index 21dc2abf..1d39a91a 100644 --- a/plugins/aidd-dev/agents/planner.md +++ b/plugins/aidd-dev/agents/planner.md @@ -36,7 +36,6 @@ decisions_blocked: topic: blocker: needs: human_approval | clarification | external_input -plan_status: in_progress | done | blocked notes: ``` @@ -88,14 +87,14 @@ The plan is complete when: - `aidd-refine:01-brainstorm` - `aidd-refine:02-challenge` - `aidd-context:09-mermaid` -- `aidd-context:10-learn` +- `aidd-context:05-learn` - `aidd-dev:01-plan` Anything else is out of bounds. # Handoffs -- Return `plan_path`, `child_paths`, `decisions_made`, `decisions_blocked`, and `plan_status`. +- Return `plan_path`, `child_paths`, `decisions_made`, and `decisions_blocked`. - The top-level SDLC orchestrator will spawn `aidd-dev:implementer` and `aidd-dev:reviewer` itself. - If a decision can be made conservatively, make it and record it. Prefer progress over escalation. - Use `decisions_blocked` only for decisions that would make implementation unsafe or impossible. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md index 05d98246..18cd89ed 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md @@ -16,7 +16,6 @@ plan_path: child_paths: [] decisions_made: [...] decisions_blocked: [...] -plan_status: in_progress | done | blocked ``` ## Process @@ -27,4 +26,4 @@ plan_status: in_progress | done | blocked ## Test -`plan_path` exists on disk; its frontmatter contains `objective`, runnable `success_condition`, `iteration: 0`, `created_at`; `plan_status` is one of `in_progress | done | blocked`; the plan's `objective` matches the spec's `objective` (or the request when spec was skipped). +`plan_path` exists on disk; its frontmatter contains `objective`, `status: pending`; the plan's `objective` matches the spec's `objective` (or the request when spec was skipped). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 01bb0d26..11e4c071 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,6 +1,6 @@ # 03 - Implement -Build a milestone, apply a fix list, or finish a remaining scope via the implementer agent. +Build a milestone, apply a fix list, or finish a remaining scope via the implementer agent. Mandatory. ## Inputs @@ -19,10 +19,13 @@ completion_score: 0-100 ## Process -1. **Spawn implementer** (`implementer` agent) with the inputs above. Brief: run `implement` for the milestone or fix list, then `assert` + `test`. -2. **On failure**, run `debug` and re-spawn the implementer with the diagnostic notes until tests pass. -3. **Return** the implementer's YAML as-is to the SDLC orchestrator. +1. **Mark in-progress.** Set `status: in-progress` in the plan frontmatter at `plan_path` (skip if already set). +2. **Spawn implementer** (`implementer` agent) with the inputs above. Brief: run `implement` for the milestone or fix list, then `assert` + `test`. +3. **On failure**, run `debug` and re-spawn the implementer with the diagnostic notes until tests pass. +4. **Blocked.** If the implementer surfaces `BLOCKED` in `notes`, write `status: blocked` in the plan frontmatter at `plan_path`, stop (do NOT proceed to 04), and escalate to a human. +5. **Mark implemented.** When the whole plan is implemented (no milestones remain, last pass `items_remaining` empty), set `status: implemented` in the plan frontmatter at `plan_path`. +6. **Return** the implementer's YAML as-is to the SDLC orchestrator. ## Test -`completion_score` is an integer between 0 and 100; `items_implemented` and `items_remaining` are both present; the validation commands declared in the input return exit code 0 after the run. +`completion_score` is an integer between 0 and 100; `items_implemented` and `items_remaining` are present; the validation commands return exit code 0; when fully implemented the plan's frontmatter `status` is `implemented` (or `blocked` if it surfaced a blocker, stopping before 04). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 7e660438..3d6e8906 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -22,8 +22,9 @@ quality_score: 0-100 1. **Spawn reviewer** (`reviewer` agent) with the inputs above. Brief: run `review` (code + functional) and return the YAML. 2. **Map verdict.** All checks pass → `verdict = ship`. Any blocking finding → `verdict = iterate`. -3. **Iterate loop.** When `verdict = iterate`, return the findings as the next `fix_list` for action 03. +3. **Write status.** `ship` → set `status: reviewed` in the plan frontmatter at `plan_path`. `iterate` → set `status: in-progress` before looping back. +4. **Iterate loop.** When `verdict = iterate`, return the findings as the next `fix_list` for action 03. ## Test -`verdict` is `ship` or `iterate`; `completion_score` and `quality_score` are integers between 0 and 100; `findings` is non-empty when `verdict = iterate`. +`verdict` is `ship` or `iterate`; `completion_score` and `quality_score` are integers between 0 and 100; `findings` is non-empty when `verdict = iterate`; the plan's frontmatter `status` is `reviewed` on `ship`, `in-progress` on `iterate`. diff --git a/plugins/aidd-dev/skills/00-sdlc/evals/scenarios.json b/plugins/aidd-dev/skills/00-sdlc/evals/scenarios.json new file mode 100644 index 00000000..f52252ee --- /dev/null +++ b/plugins/aidd-dev/skills/00-sdlc/evals/scenarios.json @@ -0,0 +1,15 @@ +[ + { "prompt": "/sdlc add a /health endpoint", "expect_action": "spec" }, + { "prompt": "Run the full dev flow on this request", "expect_action": "spec" }, + { "prompt": "Ship this feature from idea to PR", "expect_action": "spec" }, + { "prompt": "/sdlc interactive add a /health endpoint", "expect_action": "spec" }, + { "prompt": "Run the SDLC in interactive mode on this request", "expect_action": "spec" }, + { "prompt": "Interactive sdlc, pause at every gate", "expect_action": "spec" }, + { "prompt": "Plan this ticket end to end", "expect_action": "plan" }, + { "prompt": "Resume the SDLC run from this plan", "expect_action": "implement" }, + { "prompt": "Review the milestone output", "expect_action": "review" }, + { "prompt": "Open the PR for this branch", "expect_action": "ship" }, + { "prompt": "Commit my changes", "expect_action": null }, + { "prompt": "Draft a PRD for billing", "expect_action": null }, + { "prompt": "Implement milestone M3 in isolation", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index a951e4fc..9fd3e2d9 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -37,3 +37,7 @@ Actions may chain (e.g. extract from image, then plan). Read and follow each sel - `@actions/01-plan.md` - `@actions/02-components-behavior.md` - `@actions/03-image-extract-details.md` + +## References + +- `@references/plan-status.md` - plan lifecycle `status` values, meaning, and who writes each. All actions inherit it; do not re-specify the table elsewhere. diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md index f5ff4230..15863fcf 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md @@ -58,7 +58,7 @@ applicable_rules: [{ tool: , name: , path: < - Determine the feature name from the requirements. - Insert the user journey as Mermaid syntax in the plan (apply `@../references/mermaid-conventions.md`). - Fill the chosen template, including the validated architecture projection and applicable rules. - - Fill execution frontmatter (required - the plan IS the For Sure tracking file): `objective`, `success_condition` (a runnable command; reject vague conditions), `iteration: 0`, `created_at` (ISO 8601 from step 1). + - Fill execution frontmatter (required): `objective`, `status: pending`. - Save to disk: - Simple plan: `aidd_docs/tasks//-?<#ticket_number>-.md` - Master plan: `aidd_docs/tasks//-?<#ticket_number>--master.md` @@ -69,4 +69,4 @@ applicable_rules: [{ tool: , name: , path: < ## Test -The plan file exists at `plan_path`; its frontmatter contains `objective`, a runnable `success_condition`, `iteration: 0`, and a valid `created_at`; the architecture projection (M / C / D) is non-empty and matches the validated lists; the applicable rules table is consistent with the project's rules inventory; confidence is `>= 9`. +The plan file exists at `plan_path`; its frontmatter contains `objective` and `status: pending`; the architecture projection (M / C / D) is non-empty and matches the validated lists; the applicable rules table is consistent with the project's rules inventory; confidence is `>= 9`. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md new file mode 100644 index 00000000..4e75310f --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/02-design.md @@ -0,0 +1,28 @@ +# 02 - Design + +Describe a frontend page's design before code - its components and their behavior, the dumb/smart split, the render decision - then write the **delegation prompt** that tells the implementer how to build it. + +This action describes and delegates. It writes no code, and (running under the `planner`) it does **not** spawn the implementer - the implementation side launches it with the prompt written here. + +## Input + +The page or feature to design (free text). Nothing else. + +## Output + +The page, **described**: what it is, its components and their behavior, the dumb/smart split. Plus a bullet list (or small table) of the elements covered, and the delegation prompt for the implementer. + +## Process + +1. **Describe the page.** Purpose, sections, components. Per component, its behavior (states + transitions) - the SMART layer, owned in-house. +2. **Dumb/smart split.** Mark the **presentational (dumb)** components - props in, UI out, no data/logic/routing/state. Their visual is delegated to the design tool; its `shape` defines the visual behaviors (one line, not re-specified here). +3. **Render decision.** Ask the user once: see the page rendered, or not? +4. **Write the delegation prompt** for the implementer. It must: + - Keep the smart layer (data, state, routing, wiring) in your own code. Author the visual via the design tool with quotes - never `craft` (that builds the feature): `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. + - **If render was requested - visual-first.** Craft the page's visual **end-to-end first**, then **verify it in-browser before any wiring**: `Use skill "impeccable" with "live"` to iterate variants until visually good, with `Use skill "impeccable" with "critique "` as the gate. Run under `/goal` (`aidd-dev:09-for-sure`): loop until **zero P0**, then explicit user OK. Only then **attach the verified visual to the code** (wire the smart layer onto it). + - **If not.** Author the dumb visuals inline and wire as you go - no `live`, no loop. +5. **Present** the description + element list + delegation prompt. Wait for an explicit OK before exiting. + +## Test + +The page is described with its components and their behavior; the dumb components are marked; the render decision is recorded; and a delegation prompt exists that builds the smart layer in-house and delegates each dumb visual to the design tool via quoted skill calls. diff --git a/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md index 3005ee9e..eaee3ebe 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md @@ -10,7 +10,7 @@ argument-hint: N/A - Text is straight to the point, no emojis, no style, use bullet points. - Replace placeholders (`{variables}`) with actual user inputs. - Each child plan uses the standard `plan.md` template format. -- Execution is sequential: next child blocked until previous validated. +- Execution is sequential: next child gated until previous validated. - Validation is manual via checkbox approval. --> @@ -27,10 +27,10 @@ argument-hint: N/A | # | Plan | File | Status | Validated | | --- | ----------- | --------------- | ------- | --------- | | 1 | {plan-name} | `./*-part-1.md` | pending | [ ] | -| 2 | {plan-name} | `./*-part-2.md` | blocked | [ ] | +| 2 | {plan-name} | `./*-part-2.md` | pending | [ ] | - - + + ## Validation Protocol diff --git a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md index 6a66d3f0..a883d334 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md @@ -1,11 +1,9 @@ --- name: plan -description: Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file. +description: Living implementation plan - frozen objective, phases, and acceptance criteria. 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 -created_at: "{YYYY-MM-DDTHH:MM:SSZ}" +status: pending --- diff --git a/plugins/aidd-dev/skills/01-plan/evals/scenarios.json b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json new file mode 100644 index 00000000..6354a25b --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json @@ -0,0 +1,17 @@ +[ + { "prompt": "Generate a technical plan for the authentication feature", "expect_action": "plan" }, + { "prompt": "Create an implementation plan from the spec", "expect_action": "plan" }, + { "prompt": "Plan the refactoring of the payment module", "expect_action": "plan" }, + { "prompt": "Define component behavior for the checkout flow", "expect_action": "components-behavior" }, + { "prompt": "Create a state machine for the onboarding wizard", "expect_action": "components-behavior" }, + { "prompt": "Extract component details from this design screenshot", "expect_action": "image-extract-details" }, + { "prompt": "Analyze this Figma image and list all components", "expect_action": "image-extract-details" }, + { "prompt": "Rédige un plan technique pour l'auth", "expect_action": "plan" }, + { "prompt": "Génère le plan d'implémentation depuis la spec", "expect_action": "plan" }, + { "prompt": "Crée le plan d'implémentation phase par phase", "expect_action": "plan" }, + { "prompt": "Définis le comportement du composant checkout", "expect_action": "components-behavior" }, + { "prompt": "Extrais les composants de cette image Figma", "expect_action": "image-extract-details" }, + { "prompt": "Write the code for the login page", "expect_action": null }, + { "prompt": "Review my pull request", "expect_action": null }, + { "prompt": "Debug the failing test in auth.test.ts", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md new file mode 100644 index 00000000..58dbde4b --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md @@ -0,0 +1,23 @@ +--- +name: plan-status +description: Plan lifecycle status field - values, meaning, who writes each, and when. +--- + +# Plan status lifecycle + +The plan's `status` frontmatter field tracks its lifecycle for kanban views. The FILENAME carries no status suffix - status lives in frontmatter only. + +| status | meaning | written by | when | +| ------------- | ----------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | +| `pending` | created, not started | `01-plan` | at plan creation | +| `in-progress` | implementation started | implement layer (SDLC `03-implement`; standalone `02-implement`) | when implementation starts | +| `implemented` | implemented, not yet reviewed | implement layer | all phases complete / all acceptance criteria ticked | +| `reviewed` | reviewed and approved | review layer (SDLC `04-review`) | review verdict = ship / approve | +| `blocked` | cannot proceed; needs a human | implement layer | a blocking condition holds (see the implement skill's blocked reference) | + +## Rules + +- Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state. +- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed` → status returns to `in-progress`. +- `implemented` ≠ reviewed. Only the review layer sets `reviewed`. +- The reviewer and implementer agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 2f5c4efa..eeff95ff 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -18,3 +18,7 @@ Spawn the `implementer` agent to execute this skill. For tools that do not suppo ```markdown @actions/01-implement.md ``` + +## References + +- `@references/blocked.md` - conditions that make a plan `blocked` (needs a human). All actions inherit it. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md index fb944fa8..da7eb16a 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -20,14 +20,16 @@ notes: ## Process -1. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). +1. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). Set `status: in-progress` on the plan. 2. **Phase loop.** For each phase listed in the plan, in order: - Spawn the `implementer` agent via the `Task` tool, passing the phase scope and acceptance criteria. - Wait for the agent's structured output. If `completion_score < 100`, re-spawn with `items_remaining` until the phase reaches 100 %. 3. **Plan amendments.** If a phase is incorrect, incomplete, or blocked by missing information, amend the plan directly. Mark every change with 🤖 and a brief rationale. 4. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. 5. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. +6. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. +7. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. ## Test -After the loop terminates: every phase in the plan has its acceptance criteria checked off, validation commands exit zero, and no plan section is left in a `TBD` or `BLOCKED` state. +After the loop terminates: every phase has its acceptance criteria checked off, validation commands exit zero, and the plan's frontmatter `status` is `implemented` — OR, if a blocking condition held, the loop stopped and it is `blocked`. diff --git a/plugins/aidd-dev/skills/02-implement/evals/scenarios.json b/plugins/aidd-dev/skills/02-implement/evals/scenarios.json new file mode 100644 index 00000000..09a198da --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/evals/scenarios.json @@ -0,0 +1,17 @@ +[ + { "prompt": "Implement the plan for the payment feature", "expect_action": "implement" }, + { "prompt": "Execute this implementation plan phase by phase", "expect_action": "implement" }, + { "prompt": "Run the plan end-to-end", "expect_action": "implement" }, + { "prompt": "Implement phase 2 of the auth plan", "expect_action": "implement" }, + { "prompt": "Start implementing from the plan file in aidd_docs/plans/", "expect_action": "implement" }, + { "prompt": "Execute the implementation plan phase by phase", "expect_action": "implement" }, + { "prompt": "Implement from the plan in aidd_docs/plans", "expect_action": "implement" }, + { "prompt": "Run the implementation plan end-to-end", "expect_action": "implement" }, + { "prompt": "Implement the plan via the implementer agent", "expect_action": "implement" }, + { "prompt": "Exécute le plan d'implémentation phase par phase", "expect_action": "implement" }, + { "prompt": "Lance l'implémentation depuis le plan", "expect_action": "implement" }, + { "prompt": "Implémente le plan via l'agent implementer", "expect_action": "implement" }, + { "prompt": "Create a plan for the notifications feature", "expect_action": null }, + { "prompt": "Review the code I just wrote", "expect_action": null }, + { "prompt": "Fix the bug in the payment service", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md new file mode 100644 index 00000000..3bdd7dc6 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md @@ -0,0 +1,9 @@ +--- +name: blocked +description: Conditions that make a plan blocked (needs a human). +--- + +# When a plan is blocked +`blocked` = implementation cannot proceed; only a human can unblock. Stop, set `status: blocked`, escalate. + +Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA. diff --git a/plugins/aidd-dev/skills/03-assert/evals/scenarios.json b/plugins/aidd-dev/skills/03-assert/evals/scenarios.json new file mode 100644 index 00000000..286f4815 --- /dev/null +++ b/plugins/aidd-dev/skills/03-assert/evals/scenarios.json @@ -0,0 +1,17 @@ +[ + { "prompt": "Assert the login feature works as intended", "expect_action": "assert" }, + { "prompt": "Verify the payment flow is correctly implemented", "expect_action": "assert" }, + { "prompt": "Check that this feature matches the acceptance criteria", "expect_action": "assert" }, + { "prompt": "Assert architecture conformance for the new module", "expect_action": "assert-architecture" }, + { "prompt": "Check that the code follows the layered architecture rules", "expect_action": "assert-architecture" }, + { "prompt": "Validate the frontend UI against the design", "expect_action": "assert-frontend" }, + { "prompt": "Assert the checkout page looks correct in the browser", "expect_action": "assert-frontend" }, + { "prompt": "Vérifie que la feature login fonctionne comme prévu", "expect_action": "assert" }, + { "prompt": "Assert conformité architecturale du module", "expect_action": "assert-architecture" }, + { "prompt": "Valide la conformité de l'UI au design", "expect_action": "assert-frontend" }, + { "prompt": "Assert acceptance criteria for the auth feature", "expect_action": "assert" }, + { "prompt": "Verify feature works against intended behavior", "expect_action": "assert" }, + { "prompt": "Write tests for the login feature", "expect_action": null }, + { "prompt": "Review my code for quality issues", "expect_action": null }, + { "prompt": "Generate a plan for the dashboard", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/04-audit/evals/scenarios.json b/plugins/aidd-dev/skills/04-audit/evals/scenarios.json new file mode 100644 index 00000000..e60ea226 --- /dev/null +++ b/plugins/aidd-dev/skills/04-audit/evals/scenarios.json @@ -0,0 +1,21 @@ +[ + { "prompt": "Audit code quality and tech debt in the auth module", "expect_action": "code-quality" }, + { "prompt": "Find dead code, duplication and complexity hotspots", "expect_action": "code-quality" }, + { "prompt": "Trouve le code mort et la duplication", "expect_action": "code-quality" }, + { "prompt": "Audit the architecture conformance against our ADRs", "expect_action": "architecture" }, + { "prompt": "Check module coupling and layering violations", "expect_action": "architecture" }, + { "prompt": "Security audit of the API endpoints", "expect_action": "security" }, + { "prompt": "Audit for OWASP risks, authz gaps and committed secrets", "expect_action": "security" }, + { "prompt": "Audit de securite du projet", "expect_action": "security" }, + { "prompt": "Audit dependencies for known CVEs and outdated packages", "expect_action": "dependencies" }, + { "prompt": "Check vulnerable and unused dependencies", "expect_action": "dependencies" }, + { "prompt": "Performance audit: find N+1 queries and hot paths", "expect_action": "performance" }, + { "prompt": "Audit bundle size and slow render paths", "expect_action": "performance" }, + { "prompt": "Audit test coverage on critical paths", "expect_action": "tests" }, + { "prompt": "Where are tests flaky or missing", "expect_action": "tests" }, + { "prompt": "Audit the UI for accessibility and missing loading states", "expect_action": "ui" }, + { "prompt": "Check design-system drift and responsive gaps", "expect_action": "ui" }, + { "prompt": "Implement the auth feature", "expect_action": null }, + { "prompt": "Commit my changes", "expect_action": null }, + { "prompt": "Fix this specific bug in checkout", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/05-review/evals/scenarios.json b/plugins/aidd-dev/skills/05-review/evals/scenarios.json new file mode 100644 index 00000000..260793d8 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/evals/scenarios.json @@ -0,0 +1,16 @@ +[ + { "prompt": "Review the code I just implemented", "expect_action": "review-code" }, + { "prompt": "Do a code review of the PR changes", "expect_action": "review-code" }, + { "prompt": "Check code quality against project rules", "expect_action": "review-code" }, + { "prompt": "Review whether the feature behavior matches the plan", "expect_action": "review-functional" }, + { "prompt": "Validate the implementation against the acceptance criteria in the plan", "expect_action": "review-functional" }, + { "prompt": "Functional review of the checkout feature", "expect_action": "review-functional" }, + { "prompt": "Code review against project conventions", "expect_action": "review-code" }, + { "prompt": "Functional review against the plan specification", "expect_action": "review-functional" }, + { "prompt": "Revue de code contre les règles du projet", "expect_action": "review-code" }, + { "prompt": "Revue fonctionnelle contre le plan d'implémentation", "expect_action": "review-functional" }, + { "prompt": "Vérifie la qualité du code selon nos rules", "expect_action": "review-code" }, + { "prompt": "Generate an implementation plan for the dashboard", "expect_action": null }, + { "prompt": "Write unit tests for the auth module", "expect_action": null }, + { "prompt": "Fix the bug in the payment service", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/06-test/evals/scenarios.json b/plugins/aidd-dev/skills/06-test/evals/scenarios.json new file mode 100644 index 00000000..cc9bdba3 --- /dev/null +++ b/plugins/aidd-dev/skills/06-test/evals/scenarios.json @@ -0,0 +1,19 @@ +[ + { "prompt": "Write tests for the authentication module", "expect_action": "test" }, + { "prompt": "Add unit tests for the payment service", "expect_action": "test" }, + { "prompt": "Iterate on tests until they pass", "expect_action": "test" }, + { "prompt": "Write and run tests for this feature", "expect_action": "test" }, + { "prompt": "Validate the user journey for the checkout flow in the browser", "expect_action": "test-journey" }, + { "prompt": "Test the end-to-end user registration flow", "expect_action": "test-journey" }, + { "prompt": "Write unit tests for the auth module", "expect_action": "test" }, + { "prompt": "Add coverage tests for the payment service", "expect_action": "test" }, + { "prompt": "Test end-to-end user journey via the browser", "expect_action": "test-journey" }, + { "prompt": "List untested behaviors and iterate on test creation", "expect_action": "test" }, + { "prompt": "Écris les tests unitaires du module auth", "expect_action": "test" }, + { "prompt": "Test le parcours user en bout-en-bout dans le browser", "expect_action": "test-journey" }, + { "prompt": "Itère sur les tests jusqu'à ce qu'ils passent", "expect_action": "test" }, + { "prompt": "Valide le user journey du checkout", "expect_action": "test-journey" }, + { "prompt": "Review my code for quality issues", "expect_action": null }, + { "prompt": "Debug the failing login test", "expect_action": null }, + { "prompt": "Optimize the database queries", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/07-refactor/evals/scenarios.json b/plugins/aidd-dev/skills/07-refactor/evals/scenarios.json new file mode 100644 index 00000000..887dab55 --- /dev/null +++ b/plugins/aidd-dev/skills/07-refactor/evals/scenarios.json @@ -0,0 +1,19 @@ +[ + { "prompt": "Optimize the performance of the product listing query", "expect_action": "performance" }, + { "prompt": "Profile and fix slow database calls in the dashboard", "expect_action": "performance" }, + { "prompt": "Improve performance of the image upload pipeline", "expect_action": "performance" }, + { "prompt": "Optimise la performance du module produit", "expect_action": "performance" }, + { "prompt": "Fix security vulnerabilities in the auth module", "expect_action": "security" }, + { "prompt": "Run an OWASP audit and harden the API endpoints", "expect_action": "security" }, + { "prompt": "Corrige les vulnerabilites OWASP du module auth", "expect_action": "security" }, + { "prompt": "Clean up this module: rename, extract, remove dead code", "expect_action": "cleanup" }, + { "prompt": "Reduce the complexity and duplication in the checkout service", "expect_action": "cleanup" }, + { "prompt": "Refactor this file for readability, kill the magic numbers", "expect_action": "cleanup" }, + { "prompt": "Nettoie le code mort et la duplication du service paiement", "expect_action": "cleanup" }, + { "prompt": "Restructure the layers, the views import the database directly", "expect_action": "architecture" }, + { "prompt": "Decouple this god-module and fix the dependency direction", "expect_action": "architecture" }, + { "prompt": "Enforce the documented architecture boundaries", "expect_action": "architecture" }, + { "prompt": "Write tests for the payment service", "expect_action": null }, + { "prompt": "Review my pull request", "expect_action": null }, + { "prompt": "Debug the failing authentication test", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/08-debug/evals/scenarios.json b/plugins/aidd-dev/skills/08-debug/evals/scenarios.json new file mode 100644 index 00000000..c406a334 --- /dev/null +++ b/plugins/aidd-dev/skills/08-debug/evals/scenarios.json @@ -0,0 +1,19 @@ +[ + { "prompt": "Reproduce the bug reported in issue #42", "expect_action": "reproduce" }, + { "prompt": "Write a failing test that reproduces the login crash", "expect_action": "reproduce" }, + { "prompt": "Debug the payment service error", "expect_action": "debug" }, + { "prompt": "Figure out what is causing the checkout to fail", "expect_action": "debug" }, + { "prompt": "Find and fix the root cause of the auth token expiration issue", "expect_action": "debug" }, + { "prompt": "Reflect on what caused the issue and document learnings", "expect_action": "reflect-issue" }, + { "prompt": "Post-mortem: what went wrong with the deployment bug", "expect_action": "reflect-issue" }, + { "prompt": "Find the root cause of this crash", "expect_action": "debug" }, + { "prompt": "Investigate why the test fails", "expect_action": "debug" }, + { "prompt": "Reproduce the failing checkout in a test", "expect_action": "reproduce" }, + { "prompt": "Trouve la cause racine de ce crash", "expect_action": "debug" }, + { "prompt": "Reproduis le bug login dans un test", "expect_action": "reproduce" }, + { "prompt": "Investigue la cause du test qui échoue", "expect_action": "debug" }, + { "prompt": "Post-mortem du bug deployment", "expect_action": "reflect-issue" }, + { "prompt": "Write unit tests for the auth module", "expect_action": null }, + { "prompt": "Review my code quality", "expect_action": null }, + { "prompt": "Create an implementation plan for the dashboard", "expect_action": null } +] diff --git a/plugins/aidd-dev/skills/09-for-sure/README.md b/plugins/aidd-dev/skills/09-for-sure/README.md index 6bf6d26b..9bee2507 100644 --- a/plugins/aidd-dev/skills/09-for-sure/README.md +++ b/plugins/aidd-dev/skills/09-for-sure/README.md @@ -43,11 +43,13 @@ The skill exposes 3 actions across two phases: ## Outputs -- A tracking file at `aidd_docs/tasks/..md` following - the plan template format from [01-plan](../01-plan/README.md). +- A tracking file at `aidd_docs/tasks/.md` (state in the + `status` frontmatter field) from For Sure's own plan template, which + extends the [01-plan](../01-plan/README.md) format with + `success_condition` and `iteration`. - Per-attempt log entries inside the tracking file. -- The tracking file renamed to `.done.md` once and only once - the success condition genuinely verifies. +- The tracking file's `status` set to `implemented` once and only once the + success condition genuinely verifies. ## Prerequisites @@ -61,4 +63,4 @@ The skill exposes 3 actions across two phases: See [`SKILL.md`](SKILL.md) for the iron rules (single source of truth, no repeated failures, honesty over escape, auto-accept) and [`actions/`](actions/) for the per-phase contracts. The tracking file -uses the plan template asset from the `01-plan` skill. +uses For Sure's own plan template asset (`@assets/plan-template.md`). diff --git a/plugins/aidd-dev/skills/09-for-sure/SKILL.md b/plugins/aidd-dev/skills/09-for-sure/SKILL.md index f558d744..f4f5fcac 100644 --- a/plugins/aidd-dev/skills/09-for-sure/SKILL.md +++ b/plugins/aidd-dev/skills/09-for-sure/SKILL.md @@ -9,10 +9,10 @@ Autonomous loop that runs until a success condition is verified. Two phases: int ## Context -- **Goal**: Task's `success_condition` verified by running a command. All steps/acceptance criteria checked. File renamed to `.done.md`. +- **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`. +- **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). ## Environment @@ -20,9 +20,9 @@ None - task secrets are validated during pre-flight and documented in the tracki ## Transversal rules -1. **Single source of truth**: IF information about the task exists THEN it lives in `aidd_docs/tasks/..md` and nowhere else. +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 rename to `.done.md`. +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 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 772abc10..91c26034 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 @@ -14,7 +14,7 @@ rules: # optional ## Outputs ```yaml -tracking_file: aidd_docs/tasks/.in-progress.md +tracking_file: aidd_docs/tasks/.md state: resumed | created preflight_blockers: [] # non-empty halts before spawn ``` @@ -23,9 +23,9 @@ preflight_blockers: [] # non-empty halts before spawn ### Resume flow (existing task) -1. Check `aidd_docs/tasks/` for files matching the task name: - - `*.in-progress.md` -> report status (iteration, steps remaining), then skip to step 10 to resume. - - `*.done.md` -> report "Task already completed." Stop. +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 @@ -45,9 +45,9 @@ preflight_blockers: [] # non-empty halts before spawn - 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/.in-progress.md`** using the plan template. Fill frontmatter (`objective`, `success_condition`, `iteration: 0`, `created_at`), Phases with Tasks and Acceptance criteria (the steps), and include the journey map. +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. ## Test -After step 10: the file at `tracking_file` exists with `.in-progress.md` suffix, 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. +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. 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 eb32f597..dc296039 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 @@ -5,13 +5,12 @@ Orchestrates the loop. For each unchecked step: spawns a worker agent, verifies ## Inputs ```yaml -tracking_file: aidd_docs/tasks/.in-progress.md # produced by 01-init-tracking +tracking_file: aidd_docs/tasks/.md # produced by 01-init-tracking ``` ## Outputs ```yaml -final_file: aidd_docs/tasks/.done.md # renamed once success_condition holds iterations: steps_completed: log_entries: @@ -22,7 +21,7 @@ log_entries: 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. +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). @@ -35,7 +34,7 @@ The loop runs with no human interaction. Inputs and outputs are read from / writ ### After every step is checked 11. **Run the success_condition command** and verify the result yourself. -12. **On TRUE**: rename the file to `.done.md` and stop. +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 @@ -69,4 +68,4 @@ One entry per step attempt: ## 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 exits to `.done.md` after the `success_condition` command has been re-run and exits zero. +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. 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 4419d285..c8e1aad0 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,13 +1,11 @@ -# NOTE: synced from skills/01-plan/assets/plan-template.md. Keep in sync when the source changes. - --- -name: plan -description: Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file. +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 -created_at: "{YYYY-MM-DDTHH:MM:SSZ}" +status: pending --- diff --git a/plugins/aidd-dev/skills/09-for-sure/evals/scenarios.json b/plugins/aidd-dev/skills/09-for-sure/evals/scenarios.json new file mode 100644 index 00000000..abc7d486 --- /dev/null +++ b/plugins/aidd-dev/skills/09-for-sure/evals/scenarios.json @@ -0,0 +1,17 @@ +[ + { "prompt": "For sure make all tests pass", "expect_action": "init-tracking" }, + { "prompt": "Make sure the deployment succeeds", "expect_action": "init-tracking" }, + { "prompt": "Keep trying until the CI pipeline is green", "expect_action": "init-tracking" }, + { "prompt": "Loop until done: get the linter to exit 0", "expect_action": "init-tracking" }, + { "prompt": "Don't stop until all tests pass and coverage is above 80%", "expect_action": "init-tracking" }, + { "prompt": "For sure fix this until tests are green", "expect_action": "init-tracking" }, + { "prompt": "Keep looping until the build succeeds", "expect_action": "init-tracking" }, + { "prompt": "Loop until done: all assertions pass", "expect_action": "init-tracking" }, + { "prompt": "Make sure the lint exits zero, retry until it does", "expect_action": "init-tracking" }, + { "prompt": "Ne lâche pas tant que les tests ne passent pas", "expect_action": "init-tracking" }, + { "prompt": "Boucle jusqu'à ce que le CI soit vert", "expect_action": "init-tracking" }, + { "prompt": "For sure jusqu'à ce que ça marche", "expect_action": "init-tracking" }, + { "prompt": "Write a plan for the authentication feature", "expect_action": null }, + { "prompt": "Review my code for quality issues", "expect_action": null }, + { "prompt": "Run the tests once and report results", "expect_action": null } +] diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 16290f8f..a0be5aa8 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -9,6 +9,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) - [`skills/00-async-dev`](#skills00-async-dev) + - [`skills/01-scaffold`](#skills01-scaffold) --- @@ -28,3 +29,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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.` | +#### `skills/01-scaffold` + +| File | Description | +|------|---| +| [README.md](skills/01-scaffold/README.md) | - | +| [SKILL.md](skills/01-scaffold/SKILL.md) | `Sequencing tutorial that launches the right skills, in order, to turn a project idea into a running skeleton.` | + diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/README.md b/plugins/aidd-orchestrator/skills/01-scaffold/README.md new file mode 100644 index 00000000..845f2f18 --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/README.md @@ -0,0 +1,29 @@ +← [aidd-orchestrator](../../README.md) + +# 01-scaffold + +Turns a project idea into a running skeleton by launching the right skills in order. A simple sequencing tutorial for the AI - it owns no logic and builds nothing itself; every step is another skill's job. + +> Status: experimental. + +## When to use + +- Starting a new project you want actually built and running, end to end. + +## When NOT to use + +- Producing only design or architecture docs (use `aidd-context:01-bootstrap`). +- Adding features or business logic to an existing project. +- Editing context documentation or memory files directly. + +## How to invoke + +`aidd-orchestrator:01-scaffold`, or say "scaffold a new project". + +## What it does + +Launches, in order: product context → repository → bootstrap (designs the stack, then builds the skeleton) → AIDD context. Each launched skill validates its own work. + +## Technical details + +A single `SKILL.md` - no actions, no checklist of its own. See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md b/plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md new file mode 100644 index 00000000..747abfbd --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md @@ -0,0 +1,23 @@ +--- +name: 01-scaffold +disable-model-invocation: true +description: Sequencing tutorial that launches the right skills, in order, to turn a project idea into a running skeleton. +--- + +# Skill: scaffold + +A tutorial for you (the AI): take a project idea to a running skeleton by launching the right skills, in order. You orchestrate; you build nothing yourself. + +Run each step, wait for it to return, then move to the next: + +1. **Product context** - `run skill "aidd-pm:03-prd"` (skip if a product brief already exists). +2. **Repository** - `run skill "aidd-vcs:00-repo-init"`. +3. **Bootstrap** - `run skill "aidd-context:01-bootstrap"`: designs the stack into `INSTALL.md`, then builds the skeleton. The bulk of the work. +4. **AIDD context** - `run skill "aidd-context:02-project-init"`. + +Each skill validates its own work; do not re-verify here. When the last returns, report what was built. + +## Rules + +- **You sequence, you don't build.** Every step is another skill's job. +- **Resume-aware.** If an artifact already exists (repository, `INSTALL.md`, context), skip its step and continue from the first one still missing. diff --git a/plugins/aidd-vcs/.claude-plugin/plugin.json b/plugins/aidd-vcs/.claude-plugin/plugin.json index f847341a..d83ae1f3 100644 --- a/plugins/aidd-vcs/.claude-plugin/plugin.json +++ b/plugins/aidd-vcs/.claude-plugin/plugin.json @@ -2,12 +2,13 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-vcs", "version": "1.0.2", - "description": "External artifacts: commit, pull-request, release-tag, issue-create", + "description": "External artifacts: repo-init, commit, pull-request, release-tag, issue-create", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, "skills": [ + "./skills/00-repo-init", "./skills/01-commit", "./skills/02-pull-request", "./skills/03-release-tag", @@ -15,6 +16,7 @@ ], "keywords": [ "git", + "repo-init", "commit", "pull-request", "release", diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 4cc8de8d..5c249d20 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -8,6 +8,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) + - [`skills/00-repo-init`](#skills00-repo-init) - [`skills/01-commit`](#skills01-commit) - [`skills/02-pull-request`](#skills02-pull-request) - [`skills/03-release-tag`](#skills03-release-tag) @@ -23,6 +24,17 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai ### `skills` +#### `skills/00-repo-init` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-init.md](skills/00-repo-init/actions/01-init.md) | - | +| `actions` | [02-publish.md](skills/00-repo-init/actions/02-publish.md) | - | +| `assets` | [CONTRIBUTING.md](skills/00-repo-init/assets/CONTRIBUTING.md) | - | +| `evals` | [scenarios.json](skills/00-repo-init/evals/scenarios.json) | - | +| `-` | [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 provider from the project's VCS docs or installed CLI, run git init with an initial commit, write CONTRIBUTING.md, and on request create the remote repository and push. Use when the user ask to init a project.` | + #### `skills/01-commit` | Group | File | Description | Argument Hint | @@ -42,7 +54,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | - | | `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | - | | `-` | [README.md](skills/02-pull-request/README.md) | - | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | - | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`.` | - | #### `skills/03-release-tag` diff --git a/plugins/aidd-vcs/skills/00-repo-init/README.md b/plugins/aidd-vcs/skills/00-repo-init/README.md new file mode 100644 index 00000000..63db8ec5 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/README.md @@ -0,0 +1,34 @@ +← [aidd-vcs](../../README.md) + +# 00-repo-init + +Initializes a project's repository locally and, on request, on the remote host: `git init`, sets the default branch, resolves the provider, and can create the remote repository and push, returning its URL. + +> Status: experimental. + +## When to use + +- Starting version control on a new project (e.g. right after scaffolding it). +- Creating the remote repository and pushing the initial state. + +## When NOT to use + +- Cloning an existing remote, opening pull requests, or tagging releases. +- Re-initializing a directory that is already a repository (the local step no-ops there). + +## How to invoke + +`aidd-vcs:00-repo-init`, or say "initialize a git repository here" / "create the remote and publish". + +## Outputs + +- `init`: an initialized `.git`, the default branch set, the resolved provider, and `origin` added when a remote URL is given. +- `publish`: the created remote repository and a push, returning its URL. + +## Prerequisites + +- `git` on the PATH. For `publish`, the host CLI (`gh` / `glab`) authenticated. + +## Technical details + +Two actions: `init` (local) and `publish` (remote, outward-facing, confirms first). See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md new file mode 100644 index 00000000..b3d2d894 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md @@ -0,0 +1,40 @@ +--- +name: 00-repo-init +description: Initialize a project's repository - resolve the default branch and provider from the project's VCS docs or installed CLI, run git init with an initial commit, write CONTRIBUTING.md, and on request create the remote repository and push. Use when the user ask to init a project. +--- + +# Repo Init + +Initializes a project's repository - locally and, on request, on the remote host. Resolves the VCS config (default branch + provider) from the project's VCS memory, runs `git init`, and can create the remote repository and push, returning its URL. + +## Available actions + +| # | Action | Role | Input | +| --- | --------- | ------------------------------------------------------------------- | ------------------------------ | +| 01 | `init` | Resolve VCS config, `git init`, set the default branch, write `CONTRIBUTING.md` | 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 + +The intent is to `01-init` then `02-publish`. + +## Transversal rules + +- **Idempotent locally:** if the target is already a git work tree, `init` does nothing and reports. +- **`init` makes one bootstrap initial commit** (`--allow-empty`) so `HEAD` exists and is pushable; the project's real first commit (staged content) stays the commit skill's job. +- **`publish` is outward-facing:** confirm before creating the remote unless `non_interactive` is set. +- **Provider is open.** Resolve the host and its CLI from the VCS memory (see External data) when present, else from the installed VCS CLI; never restrict to a fixed list. `main` is the default-branch fallback. + +## Assets + +- `assets/CONTRIBUTING.md` - the project-root `CONTRIBUTING.md` template. + +## External data + +### Project VSC config + +Read by the actions when present; pointed to, never copied. + +```markdown +@aidd_docs/memory/vcs.md +``` diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md new file mode 100644 index 00000000..97710c3a --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md @@ -0,0 +1,32 @@ +# 01 -- Init + +Initialize a fresh local git repository and set its default branch. + +## Inputs + +- `cwd` (optional) -- absolute path of the directory to initialize (default is current dir). +- `default_branch` (optional) -- overrides the resolved branch. +- `remote_url` (optional) -- added as `origin` if given. + +## Outputs + +```json +{ "repo_root": "", "default_branch": "main", "platform": "", "cli": "", "remote": "", "created": true } +``` + +## Rules + +If `cwd` is already a git work tree, skip, return `created: false`, and report. + +## Process + +1. Resolve the default branch and provider from the project's VCS memory (if existing); otherwise detect the provider from the installed VCS CLI on PATH. `main` if nothing resolves. An explicit `default_branch` overrides. +2. `git init -b `. +3. Write `CONTRIBUTING.md` at the project root from `@../assets/CONTRIBUTING.md`, filling `{{PROJECT_NAME}}`. Leave no raw `{{...}}`. +4. Create an initial bootstrap commit so `HEAD` exists: `git -C commit --allow-empty -m "chore: initialize repository"`. The project's real first commit (staged content) stays the commit skill's job. +5. If `remote_url` is given, `git -C remote add origin `. + +## Test + +- [ ] Git dir initialized. +- [ ] `CONTRIBUTING.md` exists with filled placeholders. diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md new file mode 100644 index 00000000..f81ca30d --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md @@ -0,0 +1,29 @@ +# 02 -- Publish + +Create the project's remote repository on the resolved host and push to it. Outward-facing. + +## Inputs + +- `cwd` (optional) -- the initialized local repository (default is current dir). +- `non_interactive` (optional, default: `false`) -- skip the confirmation prompt (scaffolder / auto runs). + +## Outputs + +```json +{ "remote_url": "//", "platform": "", "default_branch": "main", "pushed": true } +``` + +## Depends on + +- `01-init` + +## Process + +1. Resolve the host and its CLI/MCP from the VCS memory or the installed CLI - whatever the project declares, no fixed provider list. +2. Confirm before creating the remote (it may be public), unless `non_interactive`. Create as private by default. +3. Create the remote repository via the resolved host CLI and push (its repo-create + push). `01-init` already left a pushable `HEAD`. If no host CLI is available, stop and report. +4. Return the remote URL. + +## Test + +- [ ] Remote URL printed to the user. diff --git a/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md new file mode 100644 index 00000000..0872b9e8 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md @@ -0,0 +1,18 @@ +# Contributing to {{PROJECT_NAME}} + +## Setup + +See [`INSTALL.md`](INSTALL.md). + +## Workflow + +1. Branch off the default branch. +2. Implement against the wired route stubs - keep architecture boundaries (see `INSTALL.md`). +3. Add or extend tests alongside the code (see [`INSTALL.md`](INSTALL.md) for how to run them). +4. Run the suite before opening a request. + +## Conventions + +- Commits: conventional commits (`(): description`). +- The CI pipeline runs the test suite on every push; keep it green. +- Do not put business logic in route stubs until you replace them with real handlers. diff --git a/plugins/aidd-vcs/skills/00-repo-init/evals/scenarios.json b/plugins/aidd-vcs/skills/00-repo-init/evals/scenarios.json new file mode 100644 index 00000000..fcdf826f --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/evals/scenarios.json @@ -0,0 +1,15 @@ +[ + { "prompt": "Initialize a git repository here", "expect_action": "init" }, + { "prompt": "git init", "expect_action": "init" }, + { "prompt": "Set up version control for this new project", "expect_action": "init" }, + { "prompt": "Create a local git repo with default branch develop", "expect_action": "init" }, + { "prompt": "Initialise le dépôt git en local", "expect_action": "init" }, + { "prompt": "Create the remote repository and push it", "expect_action": "publish" }, + { "prompt": "Publish the repo to a new private GitHub repository", "expect_action": "publish" }, + { "prompt": "Set up the repo and push it to a new remote", "expect_action": "publish" }, + { "prompt": "Crée le dépôt distant et pousse dessus", "expect_action": "publish" }, + { "prompt": "Commit my changes", "expect_action": null }, + { "prompt": "Open a pull request", "expect_action": null }, + { "prompt": "Tag this release v1.2.0", "expect_action": null }, + { "prompt": "Clone the remote repository", "expect_action": null } +] diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 638e29cb..4a01ea01 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -1,6 +1,6 @@ --- name: 02-pull-request -description: Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits. +description: Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`. --- # Pull Request diff --git a/scripts/dev-setup.sh b/scripts/dev-setup.sh new file mode 100755 index 00000000..f7e307ab --- /dev/null +++ b/scripts/dev-setup.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +# dev-setup.sh - register this checkout as a local marketplace, then install every plugin +# into Claude and Codex (delegates the install to dev-sync.sh, current versions, no bump). +# This mutates your GLOBAL (user-scope) config, so it asks to confirm first. Bypass with +# `-y` / `--yes` / `YES=1`; a non-interactive shell skips rather than hangs. Called by +# `make setup`. For iterating after edits use `make reload`. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FW="${FW:-$(dirname "$SCRIPT_DIR")}" # repo root = parent of scripts/ +MKT="${MKT:-aidd-framework}" + +HAVE_CODEX=0; command -v codex >/dev/null 2>&1 && HAVE_CODEX=1 +HAVE_CLAUDE=0; command -v claude >/dev/null 2>&1 && HAVE_CLAUDE=1 +[ "$HAVE_CODEX" = 1 ] || echo "codex CLI not found - skipping Codex" +[ "$HAVE_CLAUDE" = 1 ] || echo "claude CLI not found - skipping Claude" +if [ "$HAVE_CODEX" = 0 ] && [ "$HAVE_CLAUDE" = 0 ]; then + echo "Neither CLI found - nothing to install."; exit 0 +fi + +# Confirm before touching the global config (skip with -y / --yes / YES=1). +if [ "${YES:-}" != "1" ] && [ "${1:-}" != "-y" ] && [ "${1:-}" != "--yes" ]; then + echo "About to register '$MKT' and install its plugins into your GLOBAL Claude/Codex config (user scope)." + if [ -t 0 ]; then + printf "Continue? [y/N] "; read -r ans + case "$ans" in + y | Y | yes | YES) ;; + *) echo "Skipped. (deps + git hooks are already done; re-run with: YES=1 make setup)"; exit 0 ;; + esac + else + echo "Non-interactive shell - skipped. Re-run with: YES=1 make setup"; exit 0 + fi +fi + +# Register the marketplace (no-op if already registered), then install via dev-sync. +[ "$HAVE_CODEX" = 1 ] && codex plugin marketplace add "$FW" >/dev/null 2>&1 || true +[ "$HAVE_CLAUDE" = 1 ] && claude plugin marketplace add "$FW" >/dev/null 2>&1 || true +exec "$SCRIPT_DIR/dev-sync.sh" all diff --git a/scripts/dev-sync.sh b/scripts/dev-sync.sh new file mode 100755 index 00000000..ed1904ad --- /dev/null +++ b/scripts/dev-sync.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +# dev-sync.sh - reinstall plugins into Claude and Codex from the live checkout, at their +# CURRENT versions (no bump). Purges each plugin's cache dir first so the copy is always +# fresh and a single version dir survives (no sprawl, no stale broken versions). +# Idempotent; each tool is skipped if its CLI is absent. +# +# scripts/dev-sync.sh aidd-refine # one plugin +# scripts/dev-sync.sh aidd-refine aidd-pm # several +# scripts/dev-sync.sh all # every plugin (default) +# +# Why purge: `codex plugin remove` does not delete the cached version dir, and +# `claude plugin install` skips the copy when that version is already cached - so without +# the purge an edit would not reach the cache. Restart the session afterwards to load it. +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FW="${FW:-$(dirname "$SCRIPT_DIR")}" # repo root = parent of scripts/ +MKT="${MKT:-aidd-framework}" +CODEX_CACHE="${CODEX_CACHE:-$HOME/.codex/plugins/cache}" +CLAUDE_CACHE="${CLAUDE_CACHE:-$HOME/.claude/plugins/cache}" + +HAVE_CODEX=0; command -v codex >/dev/null 2>&1 && HAVE_CODEX=1 +HAVE_CLAUDE=0; command -v claude >/dev/null 2>&1 && HAVE_CLAUDE=1 + +sync_one() { + local name="$1" dir + dir="$FW/plugins/$name" + [ -f "$dir/.claude-plugin/plugin.json" ] || { echo "skip $name (no plugin.json)"; return; } + printf '%-22s' "$name" + + if [ "$HAVE_CODEX" = 1 ]; then + codex plugin remove "$name" >/dev/null 2>&1 || true + rm -rf "$CODEX_CACHE/$MKT/$name" + codex plugin add "$name@$MKT" >/dev/null 2>&1 && printf ' codex:ok' || printf ' codex:FAIL' + fi + if [ "$HAVE_CLAUDE" = 1 ]; then + rm -rf "$CLAUDE_CACHE/$MKT/$name" + claude plugin install "$name@$MKT" --scope user >/dev/null 2>&1 && printf ' claude:ok' || printf ' claude:FAIL' + fi + echo +} + +targets=() +if [ $# -eq 0 ] || [ "${1:-}" = "all" ]; then + for d in "$FW"/plugins/*/; do targets+=("$(basename "$d")"); done +else + targets=("$@") +fi +for t in "${targets[@]}"; do sync_one "$t"; done + +echo "Done. Restart the Claude/Codex session to load the refreshed files."