diff --git a/README.md b/README.md
index 7024076b..856c025d 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 · 38 skills · 3 agents · MIT
@@ -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..c77e374b 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -93,7 +93,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/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md
index 50076a6b..154f1f4a 100644
--- a/plugins/aidd-context/CATALOG.md
+++ b/plugins/aidd-context/CATALOG.md
@@ -54,16 +54,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`
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-orchestrator/.claude-plugin/plugin.json b/plugins/aidd-orchestrator/.claude-plugin/plugin.json
index 8d608758..1f7622fd 100644
--- a/plugins/aidd-orchestrator/.claude-plugin/plugin.json
+++ b/plugins/aidd-orchestrator/.claude-plugin/plugin.json
@@ -8,14 +8,16 @@
"url": "https://github.com/ai-driven-dev"
},
"skills": [
- "./skills/00-async-dev"
+ "./skills/00-async-dev",
+ "./skills/01-scaffold"
],
"keywords": [
"orchestration",
"async",
"pipeline",
"pull-request",
- "automation"
+ "automation",
+ "scaffold"
],
"repository": "https://github.com/ai-driven-dev/framework",
"homepage": "https://ai-driven.dev",
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.