From 83c25577614ade7df22abc9e310ee9ff21782171 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sun, 7 Jun 2026 14:08:50 +0200 Subject: [PATCH 01/22] feat(repo-init): add repository initialization and publishing skills with detailed documentation --- CLAUDE.md | 15 ++++++++ README.md | 6 ++-- plugins/aidd-context/CATALOG.md | 5 +-- plugins/aidd-orchestrator/CATALOG.md | 14 ++++++++ plugins/aidd-vcs/.claude-plugin/plugin.json | 4 ++- plugins/aidd-vcs/CATALOG.md | 11 ++++++ .../aidd-vcs/skills/00-repo-init/README.md | 34 ++++++++++++++++++ plugins/aidd-vcs/skills/00-repo-init/SKILL.md | 36 +++++++++++++++++++ .../skills/00-repo-init/actions/01-init.md | 30 ++++++++++++++++ .../skills/00-repo-init/actions/02-publish.md | 29 +++++++++++++++ .../skills/00-repo-init/evals/scenarios.json | 15 ++++++++ 11 files changed, 193 insertions(+), 6 deletions(-) create mode 100644 plugins/aidd-vcs/skills/00-repo-init/README.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/SKILL.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/evals/scenarios.json diff --git a/CLAUDE.md b/CLAUDE.md index a9f9fd08..6a2c1ed5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,6 +13,21 @@ All instructions and information above are willing to be up to date, but always - Avoid flattery that feels like unnecessary praise - Don't anthropomorphize yourself +## Communication + +Go to the essential without loosing clarify. + +- **Less is more**: focus on the minimal output without loosing sense. +- Drop articles, fragments OK, short synonyms, no filler/hedging. +- Strip conjunctions, arrows for causality (X → Y), one word when one word enough. + +## Writing + +Avoid writing huge docs, this is mostly unnecessary. + +- Look for minimal but ultra-effective guidelines. +- Prefer removing than adding. + ## Technical guidelines - Do not commit or push yourself unless I ask you to. diff --git a/README.md b/README.md index 71353db9..cf1ccc7f 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 · 31 skills · 3 agents · MIT + 6 plugins · 33 skills · 3 agents · MIT

@@ -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/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index ca89f5a9..060e2b4b 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -70,7 +70,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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) | - | +| `actions` | [05-decide-architecture.md](skills/01-bootstrap/actions/05-decide-architecture.md) | - | +| `actions` | [06-write-install-md.md](skills/01-bootstrap/actions/06-write-install-md.md) | - | | `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | | `assets` | [install-template.md](skills/01-bootstrap/assets/install-template.md) | - | | `evals` | [scenarios.json](skills/01-bootstrap/evals/scenarios.json) | - | @@ -110,7 +111,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [rule.md](skills/03-context-generate/references/rule.md) | - | | `references` | [skill-authoring.md](skills/03-context-generate/references/skill-authoring.md) | - | | `references` | [tool-resolution.md](skills/03-context-generate/references/tool-resolution.md) | - | -| `-` | [SKILL.md](skills/03-context-generate/SKILL.md) | `Generate context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces) across the host AI tool(s) the project uses. Use when the user wants to create, refactor, add or remove actions in a skill, migrate a legacy slash command into a router-based skill, or generate a new agent, rule, command, hook, plugin, or marketplace. Do NOT use for editing a single action inside an existing skill (edit directly), writing MCP servers, or modifying project-level files.` | +| `-` | [SKILL.md](skills/03-context-generate/SKILL.md) | `Generate context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces) across the host AI tool(s) the project uses. Use when the user wants to create, refactor, add or remove something related to skill, rule, command, agent, hook, plugin or marketplace. Do NOT use for editing a single action inside an existing skill (edit directly), writing MCP servers, or modifying project-level files.` | #### `skills/04-mermaid` diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 711cf654..0ceb7fd0 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) --- @@ -29,3 +30,16 @@ 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` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-generate-architecture.md](skills/01-scaffold/actions/01-generate-architecture.md) | - | +| `actions` | [02-implement-and-test.md](skills/01-scaffold/actions/02-implement-and-test.md) | - | +| `actions` | [03-verify-green.md](skills/01-scaffold/actions/03-verify-green.md) | - | +| `actions` | [04-wire-ci.md](skills/01-scaffold/actions/04-wire-ci.md) | - | +| `evals` | [scenarios.json](skills/01-scaffold/evals/scenarios.json) | - | +| `-` | [README.md](skills/01-scaffold/README.md) | - | +| `references` | [project-doc-spec.md](skills/01-scaffold/references/project-doc-spec.md) | - | +| `-` | [SKILL.md](skills/01-scaffold/SKILL.md) | `Scaffold a brand-new project's running skeleton from an already-decided stack and architecture - generate the full folder and route tree (every page and API route wired with stub handlers), a swappable database-provider abstraction, an installed test harness, a minimal CI pipeline, the base project docs (README, CONTRIBUTING, INSTALL), the AIDD context layer, and an initialized git repository - then prove it against a final checklist. Use after the stack and architecture are decided, when the user says scaffold the project, initialize the project files, build the running skeleton, or set up the actual project from the INSTALL.md. Do NOT use for choosing the stack or designing the architecture (that decided design is this skill's input), adding features to an existing project, or generating business logic.` | + diff --git a/plugins/aidd-vcs/.claude-plugin/plugin.json b/plugins/aidd-vcs/.claude-plugin/plugin.json index 148e4001..96b574c5 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 1cc179a4..64bd8c72 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,16 @@ 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) | - | +| `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) | `Use when USER wants to initialize a repository or manually ask for skill: `00-repo-init`.` | + #### `skills/01-commit` | Group | File | Description | Argument Hint | 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..09abc251 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md @@ -0,0 +1,36 @@ +--- +name: 00-repo-init +description: Use when USER wants to initialize a repository or manually ask for skill: `00-repo-init`. +--- + +# 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 (local only) | 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. + +## 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..61c8f88b --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md @@ -0,0 +1,30 @@ +# 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. 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. +4. If `remote_url` is given, `git -C remote add origin `. + +## Test + +`git -C rev-parse --is-inside-work-tree` prints `true`, `git -C symbolic-ref --short HEAD` equals the resolved branch, and `git -C rev-list --count HEAD` prints `1` (the initial commit). diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md new file mode 100644 index 00000000..902ec3c1 --- /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 + +`git -C remote get-url origin` returns the created remote URL, the default branch exists on the remote, and the action printed the URL. 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 } +] From 97ea076ac67866cada33c84077161c06fcbb9c3b Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sun, 7 Jun 2026 14:13:15 +0200 Subject: [PATCH 02/22] feat(context-generate): enhance skills action plan output with file tree preview and approval gates --- .../actions/skills/03-decompose-actions.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md b/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md index 01f8a5e7..40946b64 100644 --- a/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md +++ b/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md @@ -9,7 +9,9 @@ Break the skill into atomic, testable actions - one action, one unambiguous job. ## Outputs -An `action_plan` table. Example for a hypothetical `slack` skill: +An `action_plan` table plus a `file_tree` preview of the complete proposed skill (SKILL.md + every action file + references/assets/evals), both gated before any write. + +Example for a hypothetical `slack` skill: | slug | description (input → output) | test | depends_on | | ---------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ---------- | @@ -29,7 +31,9 @@ Tests must be real-execution: status 200, artifact created, MCP returning the ex 4. Ordering: `sequential = true` → numbered prefixes `01-`, `02-` (see `references/skill-authoring.md` ## Naming). 5. Write the `test` cell row by row - concrete inputs, concrete assertion. Pick whichever fits: a command to run, an artifact check, or an API/MCP/state side-effect. 6. Present the table. **Validate the `test` column row by row with the user, in writing.** No silent acceptance. +7. **Preview gate (tree + human).** Render the full proposed `file_tree` of the skill - SKILL.md, every action file, and any references/assets/evals - so the user sees the complete structure before a single file is written. Get explicit written approval. No write in `04`+ proceeds without it. +8. **Preview gate (AI review).** Discover a review capability by matching loaded-skill descriptions for keywords such as `review`, `verify correctness against plan`, `find flaws`, `architecture conformance`. Have it review the `action_plan` + `file_tree` for gaps, naming, and R1-R10 conformance. Surface its findings; block on deal-breakers before `04` writes. ## Test -Every `expect_action` from evals (excluding `null`) appears in the table exactly once; every row has a non-empty `test` cell explicitly approved by the user in writing; no row depends on a downstream slug. +Every `expect_action` from evals (excluding `null`) appears in the table exactly once; every row has a non-empty `test` cell explicitly approved by the user in writing; no row depends on a downstream slug; and the full `file_tree` was both human-approved and AI-reviewed before any file was written. From d90c0f0e5b2ab0653a9c9d270807f3f3fb266c50 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sun, 7 Jun 2026 14:52:57 +0200 Subject: [PATCH 03/22] docs(contributing): clarify plugin reload process for editing and adding new skills --- CONTRIBUTING.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f42446ca..c1397bcf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,7 +62,14 @@ Register the checkout as a local marketplace, then install the plugins: /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. +After **editing** an existing `SKILL.md`, agent, or action, run `/reload-plugins` in the same session to pick up the change - no reinstall needed. + +**Adding a _new_ skill is different.** A new `skills[]` entry in a `plugin.json` is not discovered by `/reload-plugins` (it only refreshes skills already loaded). Reinstall the plugin to surface it: + +``` +/plugin uninstall aidd- +/plugin install aidd-@aidd-framework +``` To load the plugins into a personal project, point its `.claude/settings.local.json` at the checkout: @@ -102,7 +109,13 @@ codex plugin add aidd-refine@aidd-framework codex plugin list --marketplace aidd-framework # confirm every plugin is `installed, enabled` ``` -No live reload - run `codex plugin marketplace upgrade` after each change to refresh. +No live reload - run `codex plugin marketplace upgrade` after each change to refresh the marketplace snapshot. **A new skill needs a reinstall too** - Codex installs from a snapshot, so a fresh `skills[]` entry only surfaces after re-adding the plugin: + +```bash +codex plugin marketplace upgrade aidd-framework +codex plugin remove aidd- +codex plugin add aidd-@aidd-framework +``` ## 2. Commit From 7d0977070d5aff9827a366b41b6b9f28bac78249 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sun, 7 Jun 2026 14:55:23 +0200 Subject: [PATCH 04/22] docs(contributing): update plugin upgrade instructions to clarify git dependency --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c1397bcf..f556ddcf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,7 +112,7 @@ codex plugin list --marketplace aidd-framework # confirm every plugin is `inst No live reload - run `codex plugin marketplace upgrade` after each change to refresh the marketplace snapshot. **A new skill needs a reinstall too** - Codex installs from a snapshot, so a fresh `skills[]` entry only surfaces after re-adding the plugin: ```bash -codex plugin marketplace upgrade aidd-framework +# codex plugin marketplace upgrade aidd-framework # ❌ only works if git installed marketplace codex plugin remove aidd- codex plugin add aidd-@aidd-framework ``` From 8c254b14cff6a0bb87fa01e45cf98d93a18bb0b6 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sun, 7 Jun 2026 16:27:13 +0200 Subject: [PATCH 05/22] refactor(docs): streamline guidelines for simplicity --- CLAUDE.md | 42 +++++++++++++--------------- plugins/aidd-context/CATALOG.md | 2 ++ plugins/aidd-orchestrator/CATALOG.md | 2 +- plugins/aidd-vcs/CATALOG.md | 2 ++ 4 files changed, 25 insertions(+), 23 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6a2c1ed5..e54f7b86 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,40 +8,37 @@ All instructions and information above are willing to be up to date, but always remind yourself that USER can be wrong, be critical of the information provided, and verify it against the project's actual state. -- Be anti-sycophantic - don't fold arguments just because I push back -- Stop excessive validation - challenge my reasoning instead -- Avoid flattery that feels like unnecessary praise -- Don't anthropomorphize yourself +- **Simplicity First** (above all) +- Be anti-sycophantic +- Challenge my reasoning +- Avoid flattery +- No over-engineering, simple is better. + +## Action specific + +For every asked actions, define success criteria. Loop until verified. ## Communication Go to the essential without loosing clarify. -- **Less is more**: focus on the minimal output without loosing sense. +- **Less is more**: focus on the minimal output without loosing sense. - Drop articles, fragments OK, short synonyms, no filler/hedging. - Strip conjunctions, arrows for causality (X → Y), one word when one word enough. ## Writing -Avoid writing huge docs, this is mostly unnecessary. - -- Look for minimal but ultra-effective guidelines. -- Prefer removing than adding. +- No excessive docs, just the bare minimum needed. +- Minimal but effective guidelines. +- **Prefer removing over adding**. -## Technical guidelines - -- Do not commit or push yourself unless I ask you to. - -### Answering Guidelines +## Answering - 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. - -## Memory Management +- 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 @@ -55,5 +52,6 @@ Avoid writing huge docs, this is mostly unnecessary. - 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 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/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 060e2b4b..6df69add 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -74,6 +74,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [06-write-install-md.md](skills/01-bootstrap/actions/06-write-install-md.md) | - | | `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | | `assets` | [install-template.md](skills/01-bootstrap/assets/install-template.md) | - | +| `assets` | [INSTALL.md](skills/01-bootstrap/assets/INSTALL.md) | - | +| `assets` | [README.md](skills/01-bootstrap/assets/README.md) | - | | `evals` | [scenarios.json](skills/01-bootstrap/evals/scenarios.json) | - | | `-` | [README.md](skills/01-bootstrap/README.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 0ceb7fd0..2922aa3b 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -41,5 +41,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `evals` | [scenarios.json](skills/01-scaffold/evals/scenarios.json) | - | | `-` | [README.md](skills/01-scaffold/README.md) | - | | `references` | [project-doc-spec.md](skills/01-scaffold/references/project-doc-spec.md) | - | -| `-` | [SKILL.md](skills/01-scaffold/SKILL.md) | `Scaffold a brand-new project's running skeleton from an already-decided stack and architecture - generate the full folder and route tree (every page and API route wired with stub handlers), a swappable database-provider abstraction, an installed test harness, a minimal CI pipeline, the base project docs (README, CONTRIBUTING, INSTALL), the AIDD context layer, and an initialized git repository - then prove it against a final checklist. Use after the stack and architecture are decided, when the user says scaffold the project, initialize the project files, build the running skeleton, or set up the actual project from the INSTALL.md. Do NOT use for choosing the stack or designing the architecture (that decided design is this skill's input), adding features to an existing project, or generating business logic.` | +| `-` | [SKILL.md](skills/01-scaffold/SKILL.md) | `Build a brand-new project into a running, proven skeleton. Interactively drives the design first (clarifying needs, drafting a PRD, deciding the stack and architecture into an INSTALL.md), then generates the full folder and route tree (every page and API route wired with stub handlers), a swappable database-provider abstraction, an installed test harness, a minimal CI pipeline, the base project docs, the AIDD context layer, and an initialized git repository - then proves it against a final checklist. Use when the user says scaffold the project, build a new project, initialize the project files, or build the running skeleton. Do NOT use for producing design or architecture docs only (that is the design layer's role), adding features to an existing project, or generating business logic.` | diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 64bd8c72..1696a31c 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -30,6 +30,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `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-template.md](skills/00-repo-init/assets/contributing-template.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) | `Use when USER wants to initialize a repository or manually ask for skill: `00-repo-init`.` | From 44f01c5614b4eb011606d1842bf88012b3370a3d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 10:25:09 +0200 Subject: [PATCH 06/22] feat(repo-init): enhance repository initialization process and add CONTRIBUTING.md template --- plugins/aidd-context/CATALOG.md | 3 +-- plugins/aidd-orchestrator/CATALOG.md | 5 ++--- plugins/aidd-vcs/CATALOG.md | 5 ++--- plugins/aidd-vcs/skills/00-repo-init/SKILL.md | 8 ++++++-- .../skills/00-repo-init/actions/01-init.md | 8 +++++--- .../skills/00-repo-init/actions/02-publish.md | 2 +- .../skills/00-repo-init/assets/CONTRIBUTING.md | 18 ++++++++++++++++++ 7 files changed, 35 insertions(+), 14 deletions(-) create mode 100644 plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 6df69add..c7f9f71d 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -73,13 +73,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [05-decide-architecture.md](skills/01-bootstrap/actions/05-decide-architecture.md) | - | | `actions` | [06-write-install-md.md](skills/01-bootstrap/actions/06-write-install-md.md) | - | | `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | -| `assets` | [install-template.md](skills/01-bootstrap/assets/install-template.md) | - | | `assets` | [INSTALL.md](skills/01-bootstrap/assets/INSTALL.md) | - | | `assets` | [README.md](skills/01-bootstrap/assets/README.md) | - | | `evals` | [scenarios.json](skills/01-bootstrap/evals/scenarios.json) | - | | `-` | [README.md](skills/01-bootstrap/README.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | -| `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and an INSTALL.md output. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code).` | +| `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and two project-root documents: `INSTALL.md` (the technologies installed, why they were chosen, and how to install them) and a `README.md`. 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).` | #### `skills/02-project-init` diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index 2922aa3b..a9d2ce04 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -36,10 +36,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-generate-architecture.md](skills/01-scaffold/actions/01-generate-architecture.md) | - | | `actions` | [02-implement-and-test.md](skills/01-scaffold/actions/02-implement-and-test.md) | - | -| `actions` | [03-verify-green.md](skills/01-scaffold/actions/03-verify-green.md) | - | -| `actions` | [04-wire-ci.md](skills/01-scaffold/actions/04-wire-ci.md) | - | +| `actions` | [03-wire-ci.md](skills/01-scaffold/actions/03-wire-ci.md) | - | | `evals` | [scenarios.json](skills/01-scaffold/evals/scenarios.json) | - | | `-` | [README.md](skills/01-scaffold/README.md) | - | | `references` | [project-doc-spec.md](skills/01-scaffold/references/project-doc-spec.md) | - | -| `-` | [SKILL.md](skills/01-scaffold/SKILL.md) | `Build a brand-new project into a running, proven skeleton. Interactively drives the design first (clarifying needs, drafting a PRD, deciding the stack and architecture into an INSTALL.md), then generates the full folder and route tree (every page and API route wired with stub handlers), a swappable database-provider abstraction, an installed test harness, a minimal CI pipeline, the base project docs, the AIDD context layer, and an initialized git repository - then proves it against a final checklist. Use when the user says scaffold the project, build a new project, initialize the project files, or build the running skeleton. Do NOT use for producing design or architecture docs only (that is the design layer's role), adding features to an existing project, or generating business logic.` | +| `-` | [SKILL.md](skills/01-scaffold/SKILL.md) | `Build a brand-new project into a running, proven skeleton. Interactively drives the design first (the stack, the architecture, and the technical building blocks the app needs, via the design layer, into an INSTALL.md), then generates the full folder and route tree (every page and API route wired with stub handlers), the selected building blocks as swappable abstractions, an installed test harness, a minimal CI pipeline, the base project docs, the AIDD context layer, and an initialized git repository - proven against a final checklist. Use when the user says scaffold the project, build a new project, initialize the project files, or build the running skeleton. Do NOT use for producing design or architecture docs only (that is the design layer's role), adding features to an existing project, or generating business logic.` | diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 1696a31c..02bf0499 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -30,11 +30,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `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-template.md](skills/00-repo-init/assets/contributing-template.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) | `Use when USER wants to initialize a repository or manually ask for skill: `00-repo-init`.` | +| `-` | [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` @@ -57,7 +56,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | - | | `evals` | [scenarios.json](skills/02-pull-request/evals/scenarios.json) | - | - | | `-` | [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/SKILL.md b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md index 09abc251..b3d2d894 100644 --- a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md +++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md @@ -1,6 +1,6 @@ --- name: 00-repo-init -description: Use when USER wants to initialize a repository or manually ask for skill: `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 @@ -11,7 +11,7 @@ Initializes a project's repository - locally and, on request, on the remote host | # | Action | Role | Input | | --- | --------- | ------------------------------------------------------------------- | ------------------------------ | -| 01 | `init` | Resolve VCS config, `git init`, set the default branch (local only) | cwd, default_branch, remote_url | +| 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 @@ -25,6 +25,10 @@ The intent is to `01-init` then `02-publish`. - **`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 diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md index 61c8f88b..97710c3a 100644 --- a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md @@ -22,9 +22,11 @@ If `cwd` is already a git work tree, skip, return `created: false`, and report. 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. 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. -4. If `remote_url` is given, `git -C remote add origin `. +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 -C rev-parse --is-inside-work-tree` prints `true`, `git -C symbolic-ref --short HEAD` equals the resolved branch, and `git -C rev-list --count HEAD` prints `1` (the initial commit). +- [ ] 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 index 902ec3c1..f81ca30d 100644 --- a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md @@ -26,4 +26,4 @@ Create the project's remote repository on the resolved host and push to it. Outw ## Test -`git -C remote get-url origin` returns the created remote URL, the default branch exists on the remote, and the action printed the URL. +- [ ] 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. From 3c306849fd899709225c0daba719eeca89f855f1 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 10:25:18 +0200 Subject: [PATCH 07/22] fix(pull-request): simplify description for creating draft pull requests --- plugins/aidd-vcs/skills/02-pull-request/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From d54e459d802776f686302cda73b3951bb1319f26 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 10:39:08 +0200 Subject: [PATCH 08/22] docs(skill): update description for context artifact generation and enhance sequential flow details --- plugins/aidd-context/skills/03-context-generate/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/03-context-generate/SKILL.md b/plugins/aidd-context/skills/03-context-generate/SKILL.md index 0df0944f..87cef6f4 100644 --- a/plugins/aidd-context/skills/03-context-generate/SKILL.md +++ b/plugins/aidd-context/skills/03-context-generate/SKILL.md @@ -1,7 +1,7 @@ --- name: 03-context-generate model: opus -description: Generate context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces) across the host AI tool(s) the project uses. Use when the user wants to create, refactor, add or remove actions in a skill, migrate a legacy slash command into a router-based skill, or generate a new agent, rule, command, hook, plugin, or marketplace. Do NOT use for editing a single action inside an existing skill (edit directly), writing MCP servers, or modifying project-level files. +description: Generate context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces) across the host AI tool(s) the project uses. Use when the user wants to create, refactor, add or remove something related to skill, rule, command, agent, hook, plugin or marketplace. Do NOT use for editing a single action inside an existing skill (edit directly), writing MCP servers, or modifying project-level files. --- # Context Generate @@ -32,7 +32,7 @@ Each artifact type has its own sub-flow under `@actions//`. All sub- ## Default flow -For sequential sub-flows, run actions in order. After each action, run its `## Test` before moving to the next. In the `skills` sub-flow, action 02 self-skips when `01` outputs `invocation_mode = manual`. +For sequential sub-flows, run actions in order. After each action, run its `## Test` before moving to the next. In the `skills` sub-flow, action 02 self-skips when `01` outputs `invocation_mode = manual`. Also in the `skills` sub-flow, action `03` carries a mandatory preview gate before any file is written in `04`+: it presents the full proposed file tree for human validation AND runs an AI review capability over the plan. Both must pass; no write proceeds otherwise. ## Modify flow From d3f61cebba15d9fc9551db20512795e40206f35c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 10:43:15 +0200 Subject: [PATCH 09/22] refactor(docs): clarify behavior guidelines and action specifics in CLAUDE.md --- CLAUDE.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e54f7b86..f7cf525c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,15 +8,19 @@ 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. -- **Simplicity First** (above all) - Be anti-sycophantic -- Challenge my reasoning -- Avoid flattery -- No over-engineering, simple is better. +- Challenge USER reasoning +- No flattery, no over-engineering. +- Simple is better. ## Action specific -For every asked actions, define success criteria. Loop until verified. +For every asked actions: + +1. **Think Before**: Don't assume. Don't hide confusion. Surface tradeoffs. +2. **Simplicity First**: Minimum doing that solves the problem, anticipate in thoughts not in writing. +3. **Surgical Changes**: Touch only what you must. Always leave the place cleaner than when you arrived. +4. **Goal-Driven Execution**: Define success criteria, transform imperative tasks into verifiable goals, Loop until verified. ## Communication From 4ea163d35d41995099a3694a99f1b2a053566ba9 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 17:26:39 +0200 Subject: [PATCH 10/22] chore(framework): add make-based dev workflow (setup + reload) Makefile fronts the contributor workflow. 'make setup' installs deps + git hooks, then registers this checkout as a local marketplace and installs the plugins into Claude and Codex (user scope, after a y/N confirm; YES=1 / -y to bypass, CI skips). 'make reload' reinstalls from the checkout on each edit: purges each plugin's cache dir in both tools then reinstalls at the current version - always fresh, no version bump, no sprawl, clean working tree. Plus doctor / check / help. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: alexsoyes --- CONTRIBUTING.md | 86 +++++++------------------------------------- Makefile | 21 +++++++++++ scripts/dev-setup.sh | 38 ++++++++++++++++++++ scripts/dev-sync.sh | 51 ++++++++++++++++++++++++++ 4 files changed, 122 insertions(+), 74 deletions(-) create mode 100644 Makefile create mode 100755 scripts/dev-setup.sh create mode 100755 scripts/dev-sync.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f556ddcf..e43b2d75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,91 +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/aidd-framework ~/projects/aidd-framework -``` - -#### Claude Code - -Register the checkout as a local marketplace, then install the plugins: - -```text -/plugin marketplace add ~/projects/aidd-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** an existing `SKILL.md`, agent, or action, run `/reload-plugins` in the same session to pick up the change - no reinstall needed. +`make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks. -**Adding a _new_ skill is different.** A new `skills[]` entry in a `plugin.json` is not discovered by `/reload-plugins` (it only refreshes skills already loaded). Reinstall the plugin to surface it: - -``` -/plugin uninstall aidd- -/plugin install aidd-@aidd-framework -``` - -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/aidd-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/aidd-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 the marketplace snapshot. **A new skill needs a reinstall too** - Codex installs from a snapshot, so a fresh `skills[]` entry only surfaces after re-adding the plugin: - -```bash -# codex plugin marketplace upgrade aidd-framework # ❌ only works if git installed marketplace -codex plugin remove aidd- -codex plugin add aidd-@aidd-framework -``` +- 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/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." From c916fb9ee7f9913fc168ac642272b2811c0d7600 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 17:28:45 +0200 Subject: [PATCH 11/22] feat(aidd-context): add 07-design-system skill (Impeccable runbook) Manual router/playbook over the Impeccable skill. One action is a setup runbook - init -> document -> extract -> refine -> audit/critique - each step an Impeccable command with per-step checkboxes walked as a todo. The skill writes no design files of its own; Impeccable's DESIGN.md stays the single source of truth. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 +- plugins/aidd-context/CATALOG.md | 11 ++- .../skills/07-design-system/README.md | 19 +++++ .../skills/07-design-system/SKILL.md | 26 ++++++ .../actions/01-create-design-system.md | 80 +++++++++++++++++++ 5 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 plugins/aidd-context/skills/07-design-system/README.md create mode 100644 plugins/aidd-context/skills/07-design-system/SKILL.md create mode 100644 plugins/aidd-context/skills/07-design-system/actions/01-create-design-system.md diff --git a/README.md b/README.md index cf1ccc7f..9f47ee82 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 · 33 skills · 3 agents · MIT + 6 plugins · 34 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) -`7 skills` · stable +`8 skills` · stable Project init, architecture, generation of Claude Code context artifacts (skills, agents, rules, commands, hooks, plugins, marketplaces), diagrams, learning, discovery. diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index c7f9f71d..8c261f1c 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -17,6 +17,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`skills/04-mermaid`](#skills04-mermaid) - [`skills/05-learn`](#skills05-learn) - [`skills/06-discovery`](#skills06-discovery) + - [`skills/07-design-system`](#skills07-design-system) --- @@ -78,7 +79,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `evals` | [scenarios.json](skills/01-bootstrap/evals/scenarios.json) | - | | `-` | [README.md](skills/01-bootstrap/README.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | -| `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and two project-root documents: `INSTALL.md` (the technologies installed, why they were chosen, and how to install them) and a `README.md`. 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 and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and two project-root documents - `INSTALL.md` (the technologies installed, why they were chosen, and how to install them) and a `README.md`. 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).` | #### `skills/02-project-init` @@ -154,3 +155,11 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [ai-mapping.md](skills/06-discovery/references/ai-mapping.md) | - | | `-` | [SKILL.md](skills/06-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/07-design-system` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-create-design-system.md](skills/07-design-system/actions/01-create-design-system.md) | - | +| `-` | [README.md](skills/07-design-system/README.md) | - | +| `-` | [SKILL.md](skills/07-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/skills/07-design-system/README.md b/plugins/aidd-context/skills/07-design-system/README.md new file mode 100644 index 00000000..1a9b8b6a --- /dev/null +++ b/plugins/aidd-context/skills/07-design-system/README.md @@ -0,0 +1,19 @@ +# 07 - Design System + +Guided onboarding for authoring a **quality design system**, wrapping the [Impeccable](https://impeccable.design) 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:07-design-system +``` + +Manual only. One action walks the Impeccable setup runbook (`init` -> `document` -> `extract` -> refine -> `audit`/`critique`), ticking per-step checkboxes as each command produces its part. + +## Requires + +The **Impeccable** skill (the playbook checks and guides install if missing). + +## Not for + +UI/feature generation or redesign - use `impeccable` directly. diff --git a/plugins/aidd-context/skills/07-design-system/SKILL.md b/plugins/aidd-context/skills/07-design-system/SKILL.md new file mode 100644 index 00000000..7a4ff94b --- /dev/null +++ b/plugins/aidd-context/skills/07-design-system/SKILL.md @@ -0,0 +1,26 @@ +--- +name: 07-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.design) 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) | + +## Default flow + +Single action. It confirms Impeccable is available, then drives the playbook. diff --git a/plugins/aidd-context/skills/07-design-system/actions/01-create-design-system.md b/plugins/aidd-context/skills/07-design-system/actions/01-create-design-system.md new file mode 100644 index 00000000..977646fc --- /dev/null +++ b/plugins/aidd-context/skills/07-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. From 56d7deca20c69ca3288a20456105bb5fb034bb98 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 17:43:12 +0200 Subject: [PATCH 12/22] refactor(docs): update CLAUDE.md for clarity and consistency --- CLAUDE.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f7cf525c..4bc24036 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,11 +2,11 @@ > 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 - Challenge USER reasoning @@ -15,24 +15,25 @@ All instructions and information above are willing to be up to date, but always ## Action specific -For every asked actions: +For every asked action: 1. **Think Before**: Don't assume. Don't hide confusion. Surface tradeoffs. -2. **Simplicity First**: Minimum doing that solves the problem, anticipate in thoughts not in writing. -3. **Surgical Changes**: Touch only what you must. Always leave the place cleaner than when you arrived. -4. **Goal-Driven Execution**: Define success criteria, transform imperative tasks into verifiable goals, Loop until verified. +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 -Go to the essential without loosing clarify. +Essential without losing clarity. -- **Less is more**: focus on the minimal output without loosing sense. +- 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, just the bare minimum needed. +- No excessive docs, bare minimum. - Minimal but effective guidelines. - **Prefer removing over adding**. @@ -55,7 +56,7 @@ Go to the essential without loosing clarify. @aidd_docs/memory/vcs.md -- If memory is not loaded above: run `ls -1tr aidd_docs/memory/` then read each file +- 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 From f6220585d775ffac3f14b1a447c4a6a7177760b8 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 17:43:27 +0200 Subject: [PATCH 13/22] feat(scaffold): add initial scaffold skill with architecture generation --- .../skills/01-scaffold/README.md | 35 ++++++++++++ .../skills/01-scaffold/SKILL.md | 57 +++++++++++++++++++ .../actions/01-generate-architecture.md | 46 +++++++++++++++ .../actions/02-implement-and-test.md | 36 ++++++++++++ .../skills/01-scaffold/actions/03-wire-ci.md | 25 ++++++++ .../skills/01-scaffold/evals/scenarios.json | 7 +++ .../references/project-doc-spec.md | 42 ++++++++++++++ 7 files changed, 248 insertions(+) create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/README.md create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json create mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md 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..f90156cb --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/README.md @@ -0,0 +1,35 @@ +← [aidd-orchestrator](../../README.md) + +# 01-scaffold + +Builds a brand-new project into a running, proven skeleton. Drives the design with you (stack, architecture, technical building blocks), then generates the full folder + route tree (every page and API route wired with stub handlers), each selected building block as a swappable abstraction, an installed test harness, a minimal CI pipeline, the project docs, the AIDD context layer, and an initialized git repository. Architecture generated per project (not copied from a template), proven against a final checklist. + +> Status: experimental. + +## When to use + +- Starting a new project you want actually built and running - walks you through the design (stack, architecture, building blocks) then produces a green skeleton to start coding on. + +## When NOT to use + +- Producing only design or architecture docs (use the design layer on its own). +- 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" / "build the running skeleton". + +## Outputs + +- A running project tree (routes wired, each selected building block as a swappable abstraction, green tests, minimal CI). +- `INSTALL.md` (technologies, why, how to install) + root `README.md` / `CONTRIBUTING.md` + the initialized AIDD context layer. +- An initialized git repository with a conventional initial commit (and a remote on request). + +## Prerequisites + +- Design + finalization capabilities reachable for delegation (stack-and-architecture, blind-spot scan, test, assertion, project-init, repo-init, commit). + +## Technical details + +Sequential router: delegated design + finalization, owned greenfield generation, checklist-based verification. 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..9aae3e43 --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md @@ -0,0 +1,57 @@ +--- +name: 01-scaffold +model: opus +description: Build a brand-new project into a running, proven skeleton. Interactively drives the design first (the stack, the architecture, and the technical building blocks the app needs, via the design layer, into an INSTALL.md), then generates the full folder and route tree (every page and API route wired with stub handlers), the selected building blocks as swappable abstractions, an installed test harness, a minimal CI pipeline, the base project docs, the AIDD context layer, and an initialized git repository - proven against a final checklist. Use when the user says scaffold the project, build a new project, initialize the project files, or build the running skeleton. Do NOT use for producing design or architecture docs only (that is the design layer's role), adding features to an existing project, or generating business logic. +--- + +# Scaffold + +> Tell user the goal: idea -> running, proven skeleton. Design decided with them; build automated. + +Run every step in order; advance only when step test passes. Flow = human-AI conversation. + +| # | Step | Runs | Gate | +| -- | -------------------------------------- | ------------------------------------------------------ | ----------------------------- | +| 1 | Decide stack + architecture + blocks (writes `INSTALL.md` + root `README.md`) | skill: `aidd-context:01-bootstrap` | `INSTALL.md` validated by USER | +| 2 | Scan blind spots | skill: `aidd-refine:04-shadow-areas` | high-severity ↺ to 1 | +| 3 | Init repo (writes `CONTRIBUTING.md`) | skill: `aidd-vcs:00-repo-init` (init) | | +| 4 | Generate architecture (structure + stubs) | `actions/01-generate-architecture.md` | tree validated by the USER | +| 5 | Implement blocks + tests, then verify | `actions/02-implement-and-test.md` | checklist green ⇒ else halt | +| 6 | Wire minimal CI | `actions/03-wire-ci.md` | | +| 7 | Init AIDD context (vs real code) | skill: `aidd-context:02-project-init` | | +| 8 | Generate file-convention rule | skill: `aidd-context:03-context-generate` (rules, topic = step-4 file conventions) | rule written (`01`/`03`) | +| 9 | First commit + publish | skill: `aidd-vcs:01-commit` -> `aidd-vcs:00-repo-init` (publish) | | +| 10 | Handoff (report vs checklist) | router report (no file) | | + +## Available actions + +The three owned actions run as Flow steps 4 (`01`), 5 (`02`), 6 (`03`). Every other step is a delegated `skill:`. + +| # | Action | Role | Input | +| -- | ----------------------- | -------------------------------------------------------------------------- | --------------------------- | +| 01 | `generate-architecture` | Structure tree + file conventions + every route as a navigable stub (back + front) | INSTALL.md | +| 02 | `implement-and-test` | Wire each selected building block (swappable abstraction + smoke test), then run the full checklist green - hard gate | generated tree + INSTALL.md | +| 03 | `wire-ci` | Minimal CI that runs the tests | verified project | + +## Resume - show what's already done + +Before step 1, detect existing artifacts; present a done/remaining checklist of the flow to the human; resume interactively from the first unmet step. Never silently redo or skip. + +```markdown +@references/project-doc-spec.md +``` + +Render as `✓` / `◻` checklist; human decides where to pick up. + +## Rules + +- **Interactive design; never fabricate.** Steps 1-2 invoke their skills and **wait for the human** at every question and validation - never invent the stack, architecture, or building blocks. Do not start generation until the human has validated `INSTALL.md`. If a validated `INSTALL.md` exists, confirm it with the human instead of re-asking. Only a scaffolder pipeline run with `auto` may skip the prompts. +- **Architecture 100%, business 0%.** Routes carry only minimal behavior to pass their tests - no auth, no domain logic. +- **The checklist is the guarantee.** Action `02` ends by running the full assertive checklist (`references/project-doc-spec.md`); any unchecked item halts the run - never auto-patched. +- **File conventions decided once.** Decided at step 4, applied to stubs; persisted by step 7 (casing -> memory) and step 8 (placement -> rule). Never defined twice. + +## References + +- `references/project-doc-spec.md` - the assertive checklist action `02` runs (rendered in `## Resume`). + +Root docs are not scaffold's assets: `README.md` + `INSTALL.md` come from the design phase (`aidd-context:01-bootstrap`), `CONTRIBUTING.md` from `aidd-vcs:00-repo-init`. diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md b/plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md new file mode 100644 index 00000000..f4823d4a --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md @@ -0,0 +1,46 @@ +# 01 -- Generate Architecture + +Produce the architecture: + +- folder/route tree +- navigable stub skeleton covering every route, back and front. +- Structure and stubs only - no behavior, no tests. + +## Inputs + +- `install_md` (required) -- chosen stack, architecture pattern, selected building blocks. + +## Outputs + +A validated **tree** (the structure), the **file conventions** governing it, plus a reachable stub per route. Expressed at structure level - the host stack determines concrete files and language. + +``` +/ + /... +``` + +Conventions every generated file follows, derived from the stack's idioms (`INSTALL.md`): + +- **Naming** - casing and suffixes for files and folders (how routes, handlers, components are cased and named). +- **Tests** - where test files live and how named (colocated vs dedicated dir, the test suffix). +- **Colocation** - where a route's companions (component, handler, types, helpers) sit relative to the route. + +## Depends on + +- the router's design phase (provides `INSTALL.md`: stack, pattern, building blocks) + +## Process + +1. Establish the **route surface** (app's pages and API endpoints) with the USER, derived from purpose and building blocks in `INSTALL.md`. Derive folder tree from the architecture pattern, and **file conventions** (naming, tests, colocation) from the stack's idioms. + > Present route surface, tree, and conventions for inspection. Keep tree at structure level - no language, path, or tool assumptions; conventions follow the stack. +2. **Validate the tree and conventions with the USER**. +3. Once approved, create a reachable stub for every page route and every API route (back and front), following agreed conventions uniformly: navigation resolves, handlers empty. No behavior. +4. Add rule using `context-generate` skill for the architecture + naming convention. +5. Be sure everything is up-to-date (`README`, `CONTRIBUTING`, `INSTALL.md`) + +## Test + +- [ ] File tree is done +- [ ] Naming convention is defined and applied +- [ ] Rules are created (in `01-standards`, `03-frameworks-and-libraries`) +- [ ] Docs is updated (`README`, `CONTRIBUTING`, `INSTALL.md`) \ No newline at end of file diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md b/plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md new file mode 100644 index 00000000..e43e90a7 --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md @@ -0,0 +1,36 @@ +# 02 -- Implement And Test + +Bring the skeleton to life and prove it: wire each selected building block as a swappable abstraction with its smoke test, install the harness, write per-surface tests, then run the full assertive checklist green. Hard gate - the checklist is the guarantee. + +## Outputs + +Intent level (host stack determines language and files): + +- Each **selected building block** (per `INSTALL.md`) wired as swappable abstraction - dev stub + real provider, env-flag chosen - with a smoke test (e.g. data round-trips, test email dispatches, scheduled job fires once). +- Stack's **dependencies installed**, **test runner configured**. +- A **small test set written alongside code and passing**: each block's smoke test, plus one per surface proving API routes respond and front routes navigate. +- **Assertive checklist all green** (`@../references/project-doc-spec.md`). + +## Depends on + +- `01-generate-architecture` + +### Project doc spec + +```markdown +@../references/project-doc-spec.md +```` + +## Process + +1. For each items in "Project doc spec", make sure everything is well prepared showing a table to `USER`. +2. **Validate with the USER if necessary**. +3. Spawn an agent / group on to setup it correctly. +4. For each surface, write the minimal test proving this work. +5. Show report to `USER`. + +## Test + +- [ ] All checkboxes checked. +- [ ] All tests pass. +- [ ] No untested element. \ No newline at end of file diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md b/plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md new file mode 100644 index 00000000..1e431fe4 --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md @@ -0,0 +1,25 @@ +# 03 -- Wire CI + +Emit minimal CI pipeline running tests, for project's chosen CI platform. No platform assumed. + +## Outputs + +The URL of the working CI. + +## Depends on + +### Project doc spec + +```markdown +@../references/project-doc-spec.md +```` + +## Process + +1. Resolve CI platform from `INSTALL.md`. +2. Read "Project doc spec". +3. Configure everything correctly. + +## Test + +- [ ] CI is passing green. \ No newline at end of file diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json b/plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json new file mode 100644 index 00000000..99a6517c --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json @@ -0,0 +1,7 @@ +[ + { "prompt": "Scaffold the project from my INSTALL.md", "expect_action": "generate-architecture" }, + { "prompt": "Initialize the project files and build the running skeleton", "expect_action": "generate-architecture" }, + { "prompt": "Set up the actual project now that the stack and architecture are decided", "expect_action": "generate-architecture" }, + { "prompt": "Choose the best stack and architecture for my new SaaS", "expect_action": null }, + { "prompt": "Add a new settings page to my existing app", "expect_action": null } +] diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md b/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md new file mode 100644 index 00000000..ba8df39e --- /dev/null +++ b/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md @@ -0,0 +1,42 @@ +# Project doc spec + +Items to initialize when scaffolding a project. + +## Assertive checklist + +### Project + +- [ ] The architecture conforms to the chosen pattern. +- [ ] `aidd_docs` is initialized. +- [ ] `.git` and remote repo exist. +- [ ] Dependency manager chosen, deps install and the app boots. + +### Quality + +- [ ] Commit linter installed. +- [ ] Pre-commit gate passes (with quality under and unit tests). +- [ ] Auto formatting configured +- [ ] Lint passes +- [ ] Typecheck + +### Testing + +- [ ] A unit test passes. +- [ ] An end-to-end test passes. + +### Deployment + +- [ ] CI config commited and passing on server. +- [ ] If a container/runtime is used, it ups and downs cleanly. + +### App + +- [ ] `INSTALL.md` filled with proper chosen techs. + +#### Frontend only + +- [ ] A11y UI lib installed. +- [ ] A form submits with validator lib and tested. +- [ ] Lighthouse thresholds configured. +- [ ] Design System Created. +- [ ] Default pages: 404, 403 etc. From 87879f9b91760af12c0c2bc52f18c730e83d1904 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 17:48:10 +0200 Subject: [PATCH 14/22] refactor(bootstrap): actions and documentation structure --- plugins/aidd-context/README.md | 3 +- .../skills/01-bootstrap/README.md | 44 ++++------ .../aidd-context/skills/01-bootstrap/SKILL.md | 24 ++--- .../01-bootstrap/actions/01-gather-needs.md | 19 ++-- .../actions/04-pick-and-design.md | 56 ++---------- .../actions/05-decide-architecture.md | 43 +++++++++ .../actions/05-write-install-md.md | 57 ------------ .../actions/06-write-install-md.md | 39 +++++++++ .../skills/01-bootstrap/assets/INSTALL.md | 60 +++++++++++++ .../skills/01-bootstrap/assets/README.md | 24 +++++ .../01-bootstrap/assets/install-template.md | 63 -------------- .../references/stack-heuristics.md | 87 +++++-------------- .../actions/skills/02-design-evals.md | 2 +- .../actions/skills/03-decompose-actions.md | 4 +- .../actions/skills/04-draft-skill.md | 2 +- .../actions/skills/05-write-actions.md | 2 +- .../actions/skills/06-validate.md | 2 +- .../assets/rules/claude/rule-template.md | 12 ++- 18 files changed, 253 insertions(+), 290 deletions(-) create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/05-write-install-md.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/assets/INSTALL.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/assets/README.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/assets/install-template.md diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index 7077ec33..b0e64748 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, plugins, marketplaces), 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, plugins, marketplaces), 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/04-mermaid/README.md) | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow. | | [1.5] | [learn](skills/05-learn/README.md) | Capture and store learnings from recently implemented features into memory bank, decisions, or coding rules. | | [1.6] | [discovery](skills/06-discovery/README.md) | Help users discover installed skills and find the right one for their use case. | +| [1.7] | [design-system](skills/07-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 fcb129de..eb7bdecb 100644 --- a/plugins/aidd-context/skills/01-bootstrap/README.md +++ b/plugins/aidd-context/skills/01-bootstrap/README.md @@ -2,11 +2,7 @@ # 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 for a new SaaS project. Walks user through a 24-item checklist, proposes 2-3 candidate stacks, audits each via parallel agents, then produces a project-root `INSTALL.md` (ADR-style): technical vision, decisions, chosen stack, building blocks, architecture, install steps. Documentation only - no code, no scaffolding. ## When to use @@ -16,10 +12,9 @@ steps. Documentation only - no code, no scaffolding. ## 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 (audit too heavy for one swap-out). +- Database schema design or detailed data modeling. +- Scaffolding actual files - this skill produces docs only. ## How to invoke @@ -27,33 +22,24 @@ steps. Documentation only - no code, no scaffolding. Use skill aidd-context:01-bootstrap ``` -The skill walks 5 atomic actions in sequence: +The skill walks 6 atomic actions in sequence: -1. `gather-needs` - Q&A across the 24-item checklist (18 user-input, 6 - derived). -2. `propose-candidates` - derive 2-3 candidate stacks and render a - comparison table. -3. `audit-candidates` - spawn parallel agents to validate each candidate - and emit a verdict; if every candidate fails, loop back to `02` or `01`. -4. `pick-and-design` - user picks the winner, then generate the folder tree - and a Mermaid architecture diagram. -5. `write-install-md` - produce `aidd_docs/INSTALL.md`. +1. `gather-needs` - Q&A across the 24-item checklist (18 user-input, 6 derived) plus selected building blocks. +2. `propose-candidates` - derive 2-3 candidate stacks, render comparison table. +3. `audit-candidates` - spawn parallel agents to validate each candidate, emit verdict; if every candidate fails, loop back to `02` or `01`. +4. `pick-and-design` - user picks the winning stack. +5. `decide-architecture` - fact-checked top-3 patterns, human-picked, plus a Mermaid module diagram. +6. `write-install-md` - produce the project-root `INSTALL.md`. ## Outputs -- `aidd_docs/INSTALL.md` capturing vision, decisions, chosen stack, - architecture pattern, folder tree, install steps, and a Mermaid diagram. +- A project-root `INSTALL.md`: vision, decisions, chosen stack, building blocks, architecture (Mermaid diagram), install steps. ## Prerequisites -- A clear (or at least loosely-formed) product idea to discuss. -- A working directory where `aidd_docs/INSTALL.md` can be written. +- A clear (or loosely-formed) product idea to discuss. +- A working directory where `INSTALL.md` can be written. ## Technical details -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) -for each step, `references/stack-heuristics.md` for the input → recommended -stack-family heuristics, and `assets/checklist.md` + `assets/install-template.md` -for the canonical 24-item checklist and `INSTALL.md` skeleton. The Mermaid -architecture diagram in action 04 is rendered via the sibling -`04-mermaid` skill. +See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for each step, `references/stack-heuristics.md` for input → recommended stack-family heuristics, and `assets/checklist.md` + `assets/INSTALL.md` for the canonical 24-item checklist and `INSTALL.md` skeleton. The Mermaid architecture diagram in action 05 is rendered via the sibling `04-mermaid` skill. diff --git a/plugins/aidd-context/skills/01-bootstrap/SKILL.md b/plugins/aidd-context/skills/01-bootstrap/SKILL.md index 7430764a..7c28feb0 100644 --- a/plugins/aidd-context/skills/01-bootstrap/SKILL.md +++ b/plugins/aidd-context/skills/01-bootstrap/SKILL.md @@ -1,11 +1,11 @@ --- 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 and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and two project-root documents - `INSTALL.md` (the technologies installed, why they were chosen, and how to install them) and a `README.md`. 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). --- # 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 for a new SaaS. Walks user through a 24-item checklist (18 user-input + 6 derived), proposes 2-3 candidate stacks, audits each via parallel agents, then produces project-root `INSTALL.md` (technologies, why chosen, how to install) and `README.md`. Docs only - no source code, no scaffolding. ## Available actions @@ -14,19 +14,20 @@ Plays the role of technical architect for a new SaaS project. Walks the user thr | 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 | +| 04 | `pick-and-design` | User picks winning stack; fill block-4 stack choices | audit report | +| 05 | `decide-architecture` | Fact-checked top-3 architecture patterns, human-picked; Mermaid module diagram | chosen stack + needs | +| 06 | `write-install-md` | Produce `INSTALL.md` + project-root `README.md` | design + decisions | ## Default flow -`01 → 02 → 03 → 04 → 05`. Sequential. The audit (03) is a gate: if every candidate returns `❌`, loop back to 02 to revise candidates or 01 to revisit needs. +`01 → 02 → 03 → 04 → 05 → 06`. Sequential. Audit (03) is a gate: if every candidate returns `❌`, loop back to 02 (revise candidates) or 01 (revisit needs). Architecture decision (05) is a human-validation gate on a fact-checked top-3. ## 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. +- **Docs only, no code scaffolding.** Writes `INSTALL.md` and project-root `README.md`. Never creates `package.json`, source files, or empty directories. +- **Anti-sycophancy.** When user stack preference conflicts with needs (e.g. wants Mongo for heavily relational data), challenge before accepting: surface audit concerns, ask for mitigation plan. +- **Recommend opinionated, not encyclopedic.** Each action proposes 2-3 options max, never a long catalog. User leaves 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 - plus selected building blocks; the 6 derived items (block 4) are filled across actions 02, 04, 05 (architecture pattern). - **Apply heuristics from `@references/stack-heuristics.md`** when proposing candidates. ## References @@ -36,8 +37,9 @@ Plays the role of technical architect for a new SaaS project. Walks the user thr ## 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 (technologies, why chosen, how to install) +- `@assets/README.md` - the project-root `README.md` template ## External data -- `aidd-context/skills/04-mermaid/SKILL.md` - invoked from action 04 to render the architecture diagram +- `aidd-context/skills/04-mermaid/SKILL.md` - invoked from action 05 to render the architecture diagram diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md index 355d329c..dd2a4a00 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md @@ -1,6 +1,6 @@ # 01 - Gather needs -Walk the user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1-3) are filled. The 6 derived items (block 4) stay empty here - they are filled by actions 02 and 04. +Walk user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1-3) filled. The 6 derived items (block 4) stay empty here - filled by actions 02, 04, 05. ## Inputs @@ -8,7 +8,7 @@ Walk the user through the 24-item checklist via interactive Q&A until all 18 use ## 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. +Filled copy of `@../assets/checklist.md` held in conversation context (not yet on disk). Each user-input item has a concrete value replacing its `<...>` placeholder. ```markdown - [x] **Project name** - Acme Invoicing @@ -18,15 +18,18 @@ A filled copy of `@../assets/checklist.md` held in conversation context (not yet ... (all 18 input items filled) ``` +Plus selected **building blocks** - data, and any of auth, email, file storage, background jobs, scheduled jobs (CRON), payments, logging - recorded later in `INSTALL.md`. + ## 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? +1. Read `@../assets/checklist.md`. Print the four blocks as a single markdown checklist so user sees full scope upfront. +2. Ask block by block, one block per message. Within a block, ask all questions at once (user answers in batch). Do not ask block 4 - derived. +3. For each user answer, fill the matching item. If vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). +4. After block 1, sanity-check coherence: type matches user volume? 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. +6. Capture **technical building blocks** the app needs - data, and any of auth, email, file storage, background jobs, scheduled jobs (CRON), payments, logging/errors; select only those that apply. These feed provider decisions (actions 04-05) and the scaffold. +7. Print the filled checklist (blocks 1-3) + selected building blocks; ask 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. +The 18 user-input items in the in-memory checklist have no remaining `<...>` placeholders, the 6 block-4 items are still placeholders, the selected building blocks are captured, and the user has explicitly confirmed with "go" or equivalent before action 02 starts. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md b/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md index 0a1e0b1b..bc93c9bf 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md @@ -1,52 +1,15 @@ # 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. +User picks winning candidate (informed by audit). Fill checklist block 4 with concrete stack choices. Architecture pattern + folder tree decided next, in action 05. ## Inputs -- Augmented comparison table from action 03 (with verdicts and rationale). +- Augmented comparison table from action 03 (verdicts + 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] -`​`​` -``` +Checklist with **block 4 stack items filled** (front, back, DB, auth, final hosting). Architecture-pattern item left for action 05. ## Depends on @@ -54,14 +17,11 @@ graph TD ## 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:04-mermaid`. Pass it the list of modules and their relations derived from the folder tree. Verify the rendered diagram passes Mermaid syntax (no parser errors). -7. Print the tree + diagram together. Wait for user confirmation before action 05. +1. Print action 03 augmented table. Ask user to pick a candidate by letter (A / B / C). +2. If picked candidate verdict `⚠️`: surface audit concerns directly - list specific risks found in action 03, ask whether user has mitigation plan, loop until satisfied or candidate switched. +3. If picked candidate verdict `❌`: refuse pick, loop back to let user choose differently. (Do not proceed with known-broken stack.) +4. Fill block 4 stack items (front, back, DB, auth, final hosting) with picked candidate's concrete choices. Leave architecture-pattern item empty - action 05 decides it. Show user filled stack choices, ask them to confirm "go". ## Test -The checklist's block 4 has all 6 items filled with no remaining `<...>` placeholders; a folder-structure code block is rendered; a Mermaid code block tagged ` ```mermaid ` is present and parses without error; the user has confirmed in writing. +Block 4's five stack items (front, back, DB, auth, hosting) filled, no remaining `<...>` placeholders, architecture-pattern item still empty, user confirmed stack in writing. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md b/plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md new file mode 100644 index 00000000..f641d8b7 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md @@ -0,0 +1,43 @@ +# 05 - Decide architecture + +Propose modern, effective architecture patterns for chosen stack + needs as a fact-checked top-3; human picks one; derive module diagram. + +## Inputs + +- Chosen stack (block 4 stack items, from action 04). +- Filled checklist blocks 1-3 (needs and constraints). + +## Outputs + +Two artifacts held in conversation context (not yet written to disk): + +1. Checklist with **block 4's architecture-pattern item filled** (human-picked winner). +2. Mermaid diagram showing modules and relations. + +```markdown +## Architecture top-3 (for Next.js + Postgres, relational domain) + +| # | Pattern | Why it fits | +| - | ------------------ | ------------------------------------------------------- | +| 1 | Modular monolith | One deploy, clear module seams, easiest to evolve later | +| 2 | Clean architecture | Strong boundaries, swappable infra, more upfront cost | +| 3 | Vertical slice | Feature-first, low ceremony, weaker shared-core control | +``` + +## Depends on + +- `04-pick-and-design` + +## Process + +1. **Fact-check first.** Before proposing, verify candidate patterns are current best practice for this stack: discover a fact-check capability by matching loaded-skill descriptions for keywords such as `verify factual claims against authoritative sources`, `cite your sources` (do not match by hardcoded skill name), or spawn an audit agent as action 03 does. Discard anything stale. +2. Propose a **top-3** of architecture patterns ranked for chosen stack + needs, each with a one-line rationale. Opinionated, max 3 - never a catalogue. Apply heuristics from `@../references/stack-heuristics.md`. +3. **Human validation gate.** User picks one of the three (or asks to revise). Do not proceed on silence. +4. Fill block 4's architecture-pattern item with the picked winner. +5. Derive high-level modules from chosen pattern + selected building blocks (a module per block, plus the pattern's standard divisions). Concrete folder tree is the scaffold's job - not part of the ADR. +6. Generate the Mermaid module diagram by invoking `aidd-context:04-mermaid` with those modules and relations. Verify it parses (no parser errors). +7. Print top-3 rationale, chosen pattern, and diagram together. Wait for user confirmation before action 06. + +## Test + +A fact-checked top-3 of architecture patterns was presented; user picked one in writing; block 4's architecture-pattern item is filled with no `<...>` placeholder; a ` ```mermaid ` block is present and parses without error. 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-write-install-md.md b/plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md new file mode 100644 index 00000000..8680075a --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md @@ -0,0 +1,39 @@ +# 06 - Write INSTALL.md + +Produce `INSTALL.md` (technologies, why chosen, how to install) from the filled checklist, stack decisions, module diagram. Plus project-root `README.md` from its template. + +## Inputs + +- Filled checklist (stack items from action 04, architecture pattern from action 05). +- Mermaid diagram (from action 05). +- Audit verdicts (from action 03) - inform `Why` column, not a section. + +## Outputs + +New file `INSTALL.md` filled from `@../assets/INSTALL.md`. + +Plus two project-root docs: + +- `README.md` filled from `@../assets/README.md` + +## Depends on + +- `05-decide-architecture` + +## Process + +1. Read `@../assets/INSTALL.md`. 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 one-line `Why` derived from block 2-3 constraints + - **Stack summary**: concrete versions / SaaS plans where known + - **Building blocks table**: one row per selected block - the block, its chosen provider, its env flag (only blocks the app needs; Data always present) + - **Architecture**: paste Mermaid diagram from action 05 + 2-3 sentences explaining module boundaries + - **Install, configure, run, test**: prerequisites the developer handles manually (accounts, runtimes, secrets), then concrete install / configure / run / test commands for chosen stack. +3. Write filled content to `INSTALL.md` in project root. If file exists, ask before overwriting. +4. Write project-root `README.md`: fill `@../assets/README.md`. Source every `{{...}}`: frameworks / database / test framework from block 4; `{{SRC_DIR}}` from architecture pattern's source-root convention (e.g. `src/`). Drop conditional lines (no database) per choices. Leave no raw `{{...}}`. +5. Print relative paths of written files + short summary. + +## Test + +- [ ] `INSTALL.md` exists and filled. 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/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/03-context-generate/actions/skills/02-design-evals.md b/plugins/aidd-context/skills/03-context-generate/actions/skills/02-design-evals.md index f0316668..bd9e5378 100644 --- a/plugins/aidd-context/skills/03-context-generate/actions/skills/02-design-evals.md +++ b/plugins/aidd-context/skills/03-context-generate/actions/skills/02-design-evals.md @@ -25,7 +25,7 @@ files_written: 1. Ask the user for 3+ realistic prompts (verbatim, not invented). 2. For each prompt, map to an `expect_action` slug - or `null` if the skill must NOT trigger. -3. For each confirmed tool (skip any in `blocked_tools`), resolve the tool skills root from `@../../references/ai-mapping.md`. Write `evals/scenarios.json` to `//evals/scenarios.json`. If `target_base` is empty, the path is CWD-relative (e.g. `.claude/skills//evals/scenarios.json`); if non-empty, prepend it (e.g. `plugins/my-plugin/.claude/skills//evals/scenarios.json`). +3. For each confirmed tool (skip any in `blocked_tools`), resolve the tool skills root from `@../../references/ai-mapping.md`. Write `evals/scenarios.json` to `//evals/scenarios.json`. If `target_base` is empty, the path is CWD-relative (e.g. `.claude/skills//evals/scenarios.json`); if non-empty, prepend it using the plugin-source layout (e.g. `plugins/my-plugin/skills//evals/scenarios.json`, NOT `.claude/skills/`; see `@../../references/ai-mapping.md` ## Plugin-source vs project-root layout). 4. Read scenarios back to the user. Wait for written validation before action 03. 5. Apply the **write target validation** from `@../../references/tool-resolution.md` (## Write target validation). diff --git a/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md b/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md index 40946b64..7a1ed07e 100644 --- a/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md +++ b/plugins/aidd-context/skills/03-context-generate/actions/skills/03-decompose-actions.md @@ -21,7 +21,7 @@ Example for a hypothetical `slack` skill: The `test` cell of each row will be **transcribed verbatim** into the `## Test` section of the generated action file in 05. No transformation. Concrete inputs, concrete assertions, observable side-effect. -Tests must be real-execution: status 200, artifact created, MCP returning the expected value. Never a mocked `*.test.js` - the first successful run is the test. +Tests must be real-execution: status 200, artifact created, MCP returning the expected value. Never a mocked `*.test.js` - the first successful run is the test. For a **delegation/playbook action** (R11, see `@../../references/skill-authoring.md`), real-execution means the **external command's artifact** exists on disk / its side-effect is observable (e.g. `DESIGN.md` written by the delegated tool), or the correct command was surfaced - not an MCP call the skill never makes. ## Process @@ -29,7 +29,7 @@ Tests must be real-execution: status 200, artifact created, MCP returning the ex 2. Group by atomicity. Split if process > ~100 lines. Merge + parameterize if ≥ 80% logic shared. 3. One-shot configs (API key load, `.env` source, client init) stay inline in the consuming action's `## Process`. Create a dedicated action only if independently callable OR reused by ≥ 2 downstream actions. 4. Ordering: `sequential = true` → numbered prefixes `01-`, `02-` (see `references/skill-authoring.md` ## Naming). -5. Write the `test` cell row by row - concrete inputs, concrete assertion. Pick whichever fits: a command to run, an artifact check, or an API/MCP/state side-effect. +5. Write the `test` cell row by row - concrete inputs, concrete assertion. Pick whichever fits: a command to run, an artifact check, an API/MCP/state side-effect, or - for a delegation/playbook action (R11) - the artifact the delegated external command produced, or that the correct command was surfaced. 6. Present the table. **Validate the `test` column row by row with the user, in writing.** No silent acceptance. 7. **Preview gate (tree + human).** Render the full proposed `file_tree` of the skill - SKILL.md, every action file, and any references/assets/evals - so the user sees the complete structure before a single file is written. Get explicit written approval. No write in `04`+ proceeds without it. 8. **Preview gate (AI review).** Discover a review capability by matching loaded-skill descriptions for keywords such as `review`, `verify correctness against plan`, `find flaws`, `architecture conformance`. Have it review the `action_plan` + `file_tree` for gaps, naming, and R1-R10 conformance. Surface its findings; block on deal-breakers before `04` writes. diff --git a/plugins/aidd-context/skills/03-context-generate/actions/skills/04-draft-skill.md b/plugins/aidd-context/skills/03-context-generate/actions/skills/04-draft-skill.md index 4e1777cb..01548aeb 100644 --- a/plugins/aidd-context/skills/03-context-generate/actions/skills/04-draft-skill.md +++ b/plugins/aidd-context/skills/03-context-generate/actions/skills/04-draft-skill.md @@ -26,7 +26,7 @@ blocked_tools: 2. Fill the frontmatter per R5 and the naming constraints in `@../../references/skill-authoring.md`. **`name` MUST equal the skill's folder name**: kebab, lowercase letters/digits/hyphens only, `<=64` chars, NO colon, NO plugin prefix, NO namespace chain (never `plugin:NN:slug` - that silently fails to load on most hosts; the host builds the invocation token from plugin + folder itself). Per tool the folder, hence `name`, is `` for Claude Code / Cursor / OpenCode / GitHub Copilot, and `aidd-` for Codex CLI (its skills dir uses that prefix). If `invocation_mode = manual`, add `disable-model-invocation: true`. Apply field-level reconciliation from `@../../references/ai-mapping.md` for each tool (drop unsupported fields, rename as needed). 3. Write the action table from the plan: `#`, slug, role, required input. 4. Sequential → chain `01 → 02 → ...`; non-sequential → trigger-to-action mapping. -5. Render once per confirmed tool. For each confirmed tool, resolve the skills root from `@../../references/ai-mapping.md` (for example: Claude Code → `.claude/skills/`, Cursor → `.cursor/skills/`, Codex CLI → `.agents/skills/aidd-/`). Prepend `target_base` to the resolved path before writing (e.g. when `target_base = ""`: `.claude/skills//SKILL.md`; when `target_base = "plugins/my-plugin/"`: `plugins/my-plugin/.claude/skills//SKILL.md`). Never write relative to the plugin install directory. +5. Render once per confirmed tool. For each confirmed tool, resolve the skills root from `@../../references/ai-mapping.md` (for example: Claude Code → `.claude/skills/`, Cursor → `.cursor/skills/`, Codex CLI → `.agents/skills/aidd-/`). Prepend `target_base` to the resolved path before writing (e.g. when `target_base = ""`: `.claude/skills//SKILL.md`; when `target_base = "plugins/my-plugin/"`: `plugins/my-plugin/skills//SKILL.md` — plugin-source layout, NOT `.claude/skills/`; see `@../../references/ai-mapping.md` ## Plugin-source vs project-root layout). Never write relative to the plugin install directory. - Codex CLI path exception: the full CWD-relative path is `.agents/skills/aidd-/SKILL.md` (the `aidd-` prefix and skill name form the directory name directly - no additional `/` nesting under a separate root). - For any tool in `blocked_tools`, skip writing and carry the reason forward. 6. Apply the **write target validation** from `@../../references/tool-resolution.md` (## Write target validation). diff --git a/plugins/aidd-context/skills/03-context-generate/actions/skills/05-write-actions.md b/plugins/aidd-context/skills/03-context-generate/actions/skills/05-write-actions.md index b0d81274..c413eba7 100644 --- a/plugins/aidd-context/skills/03-context-generate/actions/skills/05-write-actions.md +++ b/plugins/aidd-context/skills/03-context-generate/actions/skills/05-write-actions.md @@ -33,7 +33,7 @@ Action files written under each confirmed tool's skills root. Example layout for ## Process -1. For each confirmed tool from `files_written`, resolve the skill root `//` from `@../../references/ai-mapping.md`. Prepend `target_base` to every write path (e.g. when `target_base = ""`: `.claude/skills//actions/`; when `target_base = "plugins/my-plugin/"`: `plugins/my-plugin/.claude/skills//actions/`). Paths are CWD-relative; write them directly under the workspace root. Never resolve paths relative to the plugin install directory. Skip any tool in `blocked_tools`. +1. For each confirmed tool from `files_written`, resolve the skill root `//` from `@../../references/ai-mapping.md`. Prepend `target_base` to every write path (e.g. when `target_base = ""`: `.claude/skills//actions/`; when `target_base = "plugins/my-plugin/"`: `plugins/my-plugin/skills//actions/` — plugin-source layout, NOT `.claude/skills/`; see `@../../references/ai-mapping.md` ## Plugin-source vs project-root layout). Paths are CWD-relative; write them directly under the workspace root. Never resolve paths relative to the plugin install directory. Skip any tool in `blocked_tools`. 2. For each action in the plan: copy `@../../assets/skills/action-template.md`, fill each `` per its inline annotation. Transcribe the `test` cell from 03 **verbatim** into the `## Test` section. Write the file to `//actions/-.md`. 3. Secrets are **per-skill, never at repo root**. Each skill owns `/.env` (gitignored, real keys, one `KEY=value` per line) and `/.env.local` (gitignored, for each key: generation URL + one-line how-to with scopes / plan tier / dashboard path). Add the `/.env` and `/.env.local` patterns to `.gitignore`. Non-secret data follows R7 (see `@../../references/skill-authoring.md`): cross-skill -> shared root folder; skill-specific -> `/assets/` or `/references/`. diff --git a/plugins/aidd-context/skills/03-context-generate/actions/skills/06-validate.md b/plugins/aidd-context/skills/03-context-generate/actions/skills/06-validate.md index c61a6bd0..382702db 100644 --- a/plugins/aidd-context/skills/03-context-generate/actions/skills/06-validate.md +++ b/plugins/aidd-context/skills/03-context-generate/actions/skills/06-validate.md @@ -26,7 +26,7 @@ A single markdown table delivered to the user. One row per action, in numeric or - **Every file referenced by `@` inside the action** - templates, references, helpers. - **A concrete value for each `## Inputs` field**, derived from the action's input declaration (or upstream action's outputs if depends_on). - **`cwd`** = repo root. - - **Instruction** : execute `## Process`, then run the `## Test`; report pass/fail and the cause if fail in ≤ 100 words. + - **Instruction** : execute `## Process`, then run the `## Test`; report pass/fail and the cause if fail in ≤ 100 words. For a **delegation/playbook action** (R11) the test verifies the external tool's artifact on disk (e.g. `DESIGN.md` exists); if that tool is not installed in the validation environment, mark the row ⏭️ with the reason rather than ❌. 2. Capture for each action: slug, the `## Test` sentence verbatim, status. Add a row. 3. On `❌`, the agent diagnoses the root cause, **resolves it in the real environment** (install MCP, generate API key per `.env.local`, authenticate, etc.), then **patches the action source file on disk** to point to the working solution. Re-run `## Test` via a fresh agent. Repeat until ✅. The patched action is the documentation - no separate change log. 4. If `disable-model-invocation: false` in `/SKILL.md`: for each scenario in `/evals/scenarios.json`, spawn one fresh agent that reproduces the prompt verbatim and reports whether the dispatched action matches `expect_action`. Add one row per scenario. diff --git a/plugins/aidd-context/skills/03-context-generate/assets/rules/claude/rule-template.md b/plugins/aidd-context/skills/03-context-generate/assets/rules/claude/rule-template.md index 321cf96d..11ae093e 100644 --- a/plugins/aidd-context/skills/03-context-generate/assets/rules/claude/rule-template.md +++ b/plugins/aidd-context/skills/03-context-generate/assets/rules/claude/rule-template.md @@ -1,8 +1,16 @@ --- +description: paths: - "{{glob1}}" --- -# {{rule_title}} +# Rule name -- {{rule_bullet}} +## Group 1 + +- Rule 1 +- Rule 2 + +``` +// +``` \ No newline at end of file From 61a59e224292cf1a7af03540b280f5862a91d4fd Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 8 Jun 2026 20:51:48 +0200 Subject: [PATCH 15/22] feat(docs): add coverage checklist item to project documentation --- .../skills/01-scaffold/references/project-doc-spec.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md b/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md index ba8df39e..36f15b59 100644 --- a/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md +++ b/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md @@ -2,6 +2,8 @@ Items to initialize when scaffolding a project. +> Beware to only use maintained stack libs. + ## Assertive checklist ### Project @@ -23,6 +25,7 @@ Items to initialize when scaffolding a project. - [ ] A unit test passes. - [ ] An end-to-end test passes. +- [ ] Coverage. ### Deployment @@ -38,5 +41,7 @@ Items to initialize when scaffolding a project. - [ ] A11y UI lib installed. - [ ] A form submits with validator lib and tested. - [ ] Lighthouse thresholds configured. +- [ ] Accessibility tests. +- [ ] Form system with validation. - [ ] Design System Created. - [ ] Default pages: 404, 403 etc. From 8e623d9e5d3be5bb505d1a6e38b4171524911ec7 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Sat, 6 Jun 2026 13:58:13 +0200 Subject: [PATCH 16/22] docs(framework): add plugin concern taxonomy and skill placement rules (#248) --- CLAUDE.md | 2 -- docs/ARCHITECTURE.md | 19 +++++++++++++++++++ docs/CREATE_PLUGIN.md | 9 +++++++++ 3 files changed, 28 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4bc24036..3e9fc4f1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,8 +15,6 @@ Treat instructions/info above as possibly stale. USER can be wrong; stay critica ## Action specific -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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 35ad270a..b64644a3 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -79,6 +79,25 @@ A plugin bundles **any subset** of the Claude Code surfaces (skills, agents, com The `plugin.json` is validated against [`claude-code-plugin-manifest`](https://www.schemastore.org/claude-code-plugin-manifest.json) by the `lefthook` pre-commit hook (when the JSON-schema validator, `pipx`/`check-jsonschema`, is available); the same hook validates `marketplace.json` against [`claude-code-marketplace`](https://www.schemastore.org/claude-code-marketplace.json). The `validate` workflow re-runs the hooks on every push and PR. +## Plugin concerns and layers + +Every capability lives in exactly one plugin, chosen by **concern**. This taxonomy decides placement; it is only implicit in each `plugin.json`, so it is canonical here. + +| Plugin | Concern | Layer | +| ------------------- | -------------------- | ------------ | +| `aidd-context` | Knowledge production | Knowledge | +| `aidd-pm` | Product management | Knowledge | +| `aidd-refine` | Meta-cognition | Knowledge | +| `aidd-dev` | Code transformation | Execution | +| `aidd-vcs` | Version control | External | +| `aidd-orchestrator` | Orchestration | Coordination | + +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. +- **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). + ## Skills are routers A skill's `SKILL.md` is a manifest plus an actions table. Claude Code loads the SKILL.md when the skill is invoked; the body decides which action(s) to run. diff --git a/docs/CREATE_PLUGIN.md b/docs/CREATE_PLUGIN.md index 85d04be4..a24af98a 100644 --- a/docs/CREATE_PLUGIN.md +++ b/docs/CREATE_PLUGIN.md @@ -4,6 +4,15 @@ This guide walks through building a new plugin for the AI-Driven Dev marketplace For broader OSS contribution rules (commit scopes, release flow), see [`../CONTRIBUTING.md`](../CONTRIBUTING.md). For the framework's architecture, see [`ARCHITECTURE.md`](ARCHITECTURE.md). +## Adding a skill to an existing plugin + +Most contributions add a *skill* to an existing plugin, not a new plugin. Decide two things first: + +- **Which plugin** - the owning concern decides; see the [concern taxonomy](ARCHITECTURE.md#plugin-concerns-and-layers). A capability owned by another concern goes in that plugin and you delegate to it. A skill that sequences across several concerns goes in `aidd-orchestrator`. +- **Which number** - `-` encodes the plugin's logical pipeline order, not a next-free counter. Inserting mid-flow means renumbering downstream folders, their `skills[]` entries, and every `:-name` invocation token - so weigh appending against inserting. + +The rest of this guide applies to the skill directory; skip the plugin-registration steps (the plugin already exists - you only edit its `plugin.json` `skills[]`). + ## Prerequisites The same toolchain as any framework contribution: From e11d71114996b0eff262387865fd5e41b95f44bc Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Sat, 6 Jun 2026 13:58:44 +0200 Subject: [PATCH 17/22] docs(framework): add a human self-review attestation to the PR template (#249) --- .github/PULL_REQUEST_TEMPLATE.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 51573a6b..bb6c821c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -38,6 +38,4 @@ Closes # -- [ ] Docs updated to match the new behaviour. -- [ ] I self-reviewed this PR. -- [ ] No cross-plugin references introduced. +- [ ] **I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.** From 395e83149e3ab560e8d38a504ddb1aff545e345d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Tue, 9 Jun 2026 11:24:40 +0200 Subject: [PATCH 18/22] refactor: migrate scaffold to bootstrap --- AGENTS.md | 66 ++++ README.md | 5 +- ...-scaffold-to-bootstrap-migration-master.md | 304 ++++++++++++++++++ docs/ARCHITECTURE.md | 2 +- plugins/aidd-context/CATALOG.md | 12 +- .../skills/01-bootstrap/README.md | 40 ++- .../aidd-context/skills/01-bootstrap/SKILL.md | 29 +- .../01-bootstrap/actions/07-init-structure.md | 20 ++ .../actions/08-init-dependencies.md | 20 ++ .../01-bootstrap/actions/09-init-env.md | 19 ++ .../01-bootstrap/actions/10-init-database.md | 21 ++ .../actions/11-init-quality-gate.md | 21 ++ .../01-bootstrap/actions/12-init-tests.md | 21 ++ .../actions/13-init-containers.md | 19 ++ .../actions/14-init-design-system.md | 17 + .../skills/01-bootstrap/actions/15-init-ci.md | 19 ++ .../skills/01-bootstrap/evals/scenarios.json | 17 - .../skills/07-design-system/README.md | 2 +- .../skills/07-design-system/SKILL.md | 2 + plugins/aidd-dev/CATALOG.md | 5 +- plugins/aidd-dev/agents/implementer.md | 1 + plugins/aidd-dev/skills/01-plan/README.md | 26 +- plugins/aidd-dev/skills/01-plan/SKILL.md | 21 +- .../01-plan/actions/02-components-behavior.md | 35 -- .../skills/01-plan/actions/02-design.md | 28 ++ .../actions/03-image-extract-details.md | 79 ----- .../skills/01-plan/evals/scenarios.json | 9 +- .../02-implement/actions/01-implement.md | 7 +- plugins/aidd-orchestrator/CATALOG.md | 13 +- .../skills/01-scaffold/README.md | 20 +- .../skills/01-scaffold/SKILL.md | 58 +--- .../actions/01-generate-architecture.md | 46 --- .../actions/02-implement-and-test.md | 36 --- .../skills/01-scaffold/actions/03-wire-ci.md | 25 -- .../skills/01-scaffold/evals/scenarios.json | 7 - .../references/project-doc-spec.md | 47 --- 36 files changed, 697 insertions(+), 422 deletions(-) create mode 100644 AGENTS.md create mode 100644 aidd_docs/tasks/2026_06/2026_06_09-scaffold-to-bootstrap-migration-master.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/08-init-dependencies.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/09-init-env.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/10-init-database.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/11-init-quality-gate.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/12-init-tests.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/13-init-containers.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/14-init-design-system.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/15-init-ci.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/evals/scenarios.json delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-design.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md delete mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md delete mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md delete mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md delete mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json delete mode 100644 plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md 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/README.md b/README.md index 9f47ee82..901c10ea 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,7 @@ flowchart TD - **New here?** Run `/aidd-context:00-onboard` - it inspects the project and guides you. - **Whole loop in one command?** `/aidd-dev:00-sdlc` runs plan → implement → review → ship. +- **Starting from zero?** `/aidd-orchestrator:01-scaffold` walks idea → running skeleton (repo, stack, build, CI, context). - **More plugins?** Browse the [catalog](#plugins) or the `/plugin` Discover tab. ### Another AI tool? @@ -184,9 +185,9 @@ Meta-cognition: brainstorm, challenge, condense, shadow-areas, fact-check. ### 🎼 [aidd-orchestrator](plugins/aidd-orchestrator/README.md) -`2 skills` · stable (`async-dev`) +`2 skills` · stable (`async-dev`) · experimental (`scaffold`) -Label an issue, get a PR; re-label, get the review applied. Router-based skill: one entry point, three sub-flows (setup, run, review). +Label an issue, get a PR (`async-dev`, router: setup / run / review). Scaffold a new project idea → running skeleton (`scaffold`, a pure-routing wizard). 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 b64644a3..c4672010 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -94,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/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 8c261f1c..7569f02e 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -73,13 +73,21 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-pick-and-design.md](skills/01-bootstrap/actions/04-pick-and-design.md) | - | | `actions` | [05-decide-architecture.md](skills/01-bootstrap/actions/05-decide-architecture.md) | - | | `actions` | [06-write-install-md.md](skills/01-bootstrap/actions/06-write-install-md.md) | - | +| `actions` | [07-init-structure.md](skills/01-bootstrap/actions/07-init-structure.md) | - | +| `actions` | [08-init-dependencies.md](skills/01-bootstrap/actions/08-init-dependencies.md) | - | +| `actions` | [09-init-env.md](skills/01-bootstrap/actions/09-init-env.md) | - | +| `actions` | [10-init-database.md](skills/01-bootstrap/actions/10-init-database.md) | - | +| `actions` | [11-init-quality-gate.md](skills/01-bootstrap/actions/11-init-quality-gate.md) | - | +| `actions` | [12-init-tests.md](skills/01-bootstrap/actions/12-init-tests.md) | - | +| `actions` | [13-init-containers.md](skills/01-bootstrap/actions/13-init-containers.md) | - | +| `actions` | [14-init-design-system.md](skills/01-bootstrap/actions/14-init-design-system.md) | - | +| `actions` | [15-init-ci.md](skills/01-bootstrap/actions/15-init-ci.md) | - | | `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.md) | - | | `assets` | [INSTALL.md](skills/01-bootstrap/assets/INSTALL.md) | - | | `assets` | [README.md](skills/01-bootstrap/assets/README.md) | - | -| `evals` | [scenarios.json](skills/01-bootstrap/evals/scenarios.json) | - | | `-` | [README.md](skills/01-bootstrap/README.md) | - | | `references` | [stack-heuristics.md](skills/01-bootstrap/references/stack-heuristics.md) | - | -| `-` | [SKILL.md](skills/01-bootstrap/SKILL.md) | `Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and two project-root documents - `INSTALL.md` (the technologies installed, why they were chosen, and how to install them) and a `README.md`. 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 through interactive Q&A, candidate-stack comparison, and multi-agent audit into a validated `INSTALL.md` + `README.md`; then materializes that `INSTALL.md` into a running, proven skeleton via atomic `init-*` actions (structure, dependencies, env, database, quality gate, tests, containers, design system). 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 eb7bdecb..2c138741 100644 --- a/plugins/aidd-context/skills/01-bootstrap/README.md +++ b/plugins/aidd-context/skills/01-bootstrap/README.md @@ -2,19 +2,19 @@ # 01 - Bootstrap -Technical architect for a new SaaS project. Walks user through a 24-item checklist, proposes 2-3 candidate stacks, audits each via parallel agents, then produces a project-root `INSTALL.md` (ADR-style): technical vision, decisions, chosen stack, building blocks, architecture, install steps. Documentation only - no code, no scaffolding. +Technical architect **and** builder for a new project. **Design** (actions 01-06): walk a 24-item checklist, propose 2-3 candidate stacks, audit each via parallel agents, and produce a validated project-root `INSTALL.md` + `README.md`. **Build** (actions 07-14): 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 -- Editing an existing project's stack (audit too heavy for one swap-out). +- Editing an existing project's stack (the audit is too heavy for one swap-out). - Database schema design or detailed data modeling. -- Scaffolding actual files - this skill produces docs only. +- Writing business logic (auth, domain rules, features). ## How to invoke @@ -22,24 +22,38 @@ Technical architect for a new SaaS project. Walks user through a 24-item checkli Use skill aidd-context:01-bootstrap ``` -The skill walks 6 atomic actions in sequence: +### Design phase → validated `INSTALL.md` -1. `gather-needs` - Q&A across the 24-item checklist (18 user-input, 6 derived) plus selected building blocks. -2. `propose-candidates` - derive 2-3 candidate stacks, render comparison table. -3. `audit-candidates` - spawn parallel agents to validate each candidate, emit verdict; if every candidate fails, loop back to `02` or `01`. +1. `gather-needs` - Q&A across the 24-item checklist plus selected building blocks. +2. `propose-candidates` - derive 2-3 candidate stacks, render a comparison table. +3. `audit-candidates` - parallel agents validate each candidate; if all fail, loop back to `02`/`01`. 4. `pick-and-design` - user picks the winning stack. 5. `decide-architecture` - fact-checked top-3 patterns, human-picked, plus a Mermaid module diagram. -6. `write-install-md` - produce the project-root `INSTALL.md`. +6. `write-install-md` - produce the project-root `INSTALL.md` + `README.md`. + +### Build phase → running skeleton + +No build action runs until `INSTALL.md` is validated; conditional actions skip per `INSTALL.md`. + +7. `init-structure` - folder tree + reachable route stubs. +8. `init-dependencies` - dependency manager + building blocks (swappable) + boot. +9. `init-env` - `.env.example` + config loading. +10. `init-database` - engine + baseline migration + seed fixtures + round-trip *(conditional)*. +11. `init-quality-gate` - typecheck + format + lint + commit-linter + pre-commit (one gate). +12. `init-tests` - runner + unit + e2e + coverage *(delegated)*. +13. `init-containers` - container ups & downs cleanly *(conditional)*. +14. `init-design-system` - design system *(front-only, delegated)*. +15. `init-ci` - pipeline runs the quality gate + tests, green on the server *(conditional)*. ## Outputs -- A project-root `INSTALL.md`: vision, decisions, chosen stack, building blocks, architecture (Mermaid diagram), install steps. +- A validated project-root `INSTALL.md` + `README.md`, then a running skeleton proven by each build action's gate. ## Prerequisites - A clear (or loosely-formed) product idea to discuss. -- A working directory where `INSTALL.md` can be written. +- A working directory. ## Technical details -See [`SKILL.md`](SKILL.md) for the action contract, [`actions/`](actions/) for each step, `references/stack-heuristics.md` for input → recommended stack-family heuristics, and `assets/checklist.md` + `assets/INSTALL.md` for the canonical 24-item checklist and `INSTALL.md` skeleton. The Mermaid architecture diagram in action 05 is rendered via the sibling `04-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 05) renders via the sibling `04-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 7c28feb0..cb704b4e 100644 --- a/plugins/aidd-context/skills/01-bootstrap/SKILL.md +++ b/plugins/aidd-context/skills/01-bootstrap/SKILL.md @@ -1,14 +1,16 @@ --- 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 two project-root documents - `INSTALL.md` (the technologies installed, why they were chosen, and how to install them) and a `README.md`. 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 through interactive Q&A, candidate-stack comparison, and multi-agent audit into a validated `INSTALL.md` + `README.md`; then materializes that `INSTALL.md` into a running, proven skeleton via atomic `init-*` actions (structure, dependencies, env, database, quality gate, tests, containers, design system). 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 -Technical architect for a new SaaS. Walks user through a 24-item checklist (18 user-input + 6 derived), proposes 2-3 candidate stacks, audits each via parallel agents, then produces project-root `INSTALL.md` (technologies, why chosen, how to install) and `README.md`. Docs only - no source code, no scaffolding. +Technical architect **and** builder for a new project. Two phases. **Design** (01-06): walk a 24-item checklist, propose 2-3 candidate stacks, audit each, produce a validated `INSTALL.md` + `README.md`. **Build** (07-14): 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 +**Design phase** - produces the validated `INSTALL.md` (docs only): + | # | Action | Role | Input | | --- | --------------------- | -------------------------------------------------------------- | ------------------ | | 01 | `gather-needs` | Q&A across the 24-item checklist | user intent | @@ -16,15 +18,32 @@ Technical architect for a new SaaS. Walks user through a 24-item checklist (18 u | 03 | `audit-candidates` | Spawn parallel agents to validate each candidate, emit verdict | candidates table | | 04 | `pick-and-design` | User picks winning stack; fill block-4 stack choices | audit report | | 05 | `decide-architecture` | Fact-checked top-3 architecture patterns, human-picked; Mermaid module diagram | chosen stack + needs | -| 06 | `write-install-md` | Produce `INSTALL.md` + project-root `README.md` | design + decisions | +| 06 | `write-install-md` | Produce `INSTALL.md` + project-root `README.md` | design + decisions | + +**Build phase** - materializes the validated `INSTALL.md` into a running skeleton. Each action reads `INSTALL.md`, names no technology, has its own gate: + +| # | Action | Role | Delegate | +| --- | -------------------- | --------------------------------------------------------------------- | ----------------- | +| 07 | `init-structure` | Folder tree + reachable route stubs from `INSTALL.md` | owns | +| 08 | `init-dependencies` | Dependency manager + building blocks (swappable) + boot | owns | +| 09 | `init-env` | `.env.example` + config loading | owns | +| 10 | `init-database` | Engine + baseline migration + fixtures + round-trip *(conditional)* | owns | +| 11 | `init-quality-gate` | typecheck + format + lint + commit-linter + pre-commit (one gate) | owns | +| 12 | `init-tests` | Runner + 1 unit + 1 e2e + coverage | testing capability | +| 13 | `init-containers` | Container/compose ups & downs clean *(conditional)* | owns | +| 14 | `init-design-system` | Design system *(front-only, conditional)* | design-system capability | +| 15 | `init-ci` | Pipeline runs the quality gate + tests, green on the server *(conditional)* | owns | ## Default flow -`01 → 02 → 03 → 04 → 05 → 06`. Sequential. Audit (03) is a gate: if every candidate returns `❌`, loop back to 02 (revise candidates) or 01 (revisit needs). Architecture decision (05) is a human-validation gate on a fact-checked top-3. +**Design** `01 → 02 → 03 → 04 → 05 → 06`, then **Build** `07 → 08 → 09 → 10 → 11 → 12 → 13 → 14 → 15`. Sequential. Audit (03) is a gate: if every candidate returns `❌`, loop back to 02 (revise candidates) or 01 (revisit needs). Architecture decision (05) is a human-validation gate on a fact-checked top-3. **No build action runs until `INSTALL.md` is validated** (end of 06). Conditional build actions (10, 13, 14, 15) skip when the project does not call for them. Each build action advances only when its own `## Test` gate is green. ## Transversal rules -- **Docs only, no code scaffolding.** Writes `INSTALL.md` and project-root `README.md`. Never creates `package.json`, source files, or empty directories. +- **Design before build; never fabricate.** No build action (07+) runs until the human has validated `INSTALL.md`. The design phase invents nothing - it waits for the human at every checklist and 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.** Every `init-*` action reads `INSTALL.md` and names no technology of its own. The chosen tools come from `INSTALL.md`, not 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 user stack preference conflicts with needs (e.g. wants Mongo for heavily relational data), challenge before accepting: surface audit concerns, ask for mitigation plan. - **Recommend opinionated, not encyclopedic.** Each action proposes 2-3 options max, never a long catalog. User leaves 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 - plus selected building blocks; the 6 derived items (block 4) are filled across actions 02, 04, 05 (architecture pattern). diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md new file mode 100644 index 00000000..30e4af83 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md @@ -0,0 +1,20 @@ +# 07 - Init structure + +Materialize the validated folder/route tree from `INSTALL.md` as real directories and reachable stubs. Structure only - no behavior. + +## Inputs + +- `INSTALL.md` - folder tree, architecture pattern, file conventions. + +## Process + +1. Create the directory tree exactly as `INSTALL.md` describes it. +2. For every route (front + back), create one reachable stub following the stack's conventions: 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/08-init-dependencies.md b/plugins/aidd-context/skills/01-bootstrap/actions/08-init-dependencies.md new file mode 100644 index 00000000..76865be8 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/08-init-dependencies.md @@ -0,0 +1,20 @@ +# 08 - 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` - dependency manager, stack, building blocks (with env flags). + +## 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/09-init-env.md b/plugins/aidd-context/skills/01-bootstrap/actions/09-init-env.md new file mode 100644 index 00000000..e1e9f96c --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/09-init-env.md @@ -0,0 +1,19 @@ +# 09 - Init env + +Environment and secrets. Enumerate every variable the project needs and wire config loading. No secret values committed. + +## Inputs + +- `INSTALL.md` - building blocks and providers that require configuration / secrets. + +## Process + +1. Derive the required env keys from `INSTALL.md` (each block's 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/10-init-database.md b/plugins/aidd-context/skills/01-bootstrap/actions/10-init-database.md new file mode 100644 index 00000000..e2686913 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/10-init-database.md @@ -0,0 +1,21 @@ +# 10 - Init database + +Stand up the database: connection, migration tool, a baseline migration, seed fixtures, and a proven round-trip. Conditional - skip when `INSTALL.md` declares no database. + +## Inputs + +- `INSTALL.md` - database engine and migration tool. + +## Process + +1. Configure the connection from the environment (see `09-init-env`). +2. Set up the migration tool declared in `INSTALL.md`. +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/11-init-quality-gate.md b/plugins/aidd-context/skills/01-bootstrap/actions/11-init-quality-gate.md new file mode 100644 index 00000000..ca6ae8dc --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/11-init-quality-gate.md @@ -0,0 +1,21 @@ +# 11 - Init quality gate + +Wire static quality as one cohesive gate: typecheck + format + lint + commit-message linter + a pre-commit hook that runs them. Reads `INSTALL.md`; names no tool of its own. + +## Inputs + +- `INSTALL.md` - language and stack (determines the concrete tools). + +## Process + +1. Configure typecheck, formatter, and linter for the stack. +2. Configure the commit-message linter. +3. Wire a pre-commit hook running format + lint + typecheck (and unit tests once `12-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/12-init-tests.md b/plugins/aidd-context/skills/01-bootstrap/actions/12-init-tests.md new file mode 100644 index 00000000..7ed94b8c --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/12-init-tests.md @@ -0,0 +1,21 @@ +# 12 - 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 structure (`07-init-structure`) - the code under test. +- The test framework (from `INSTALL.md`). + +## Process + +1. Install and configure the test runner + coverage reporting declared in `INSTALL.md`. +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/13-init-containers.md b/plugins/aidd-context/skills/01-bootstrap/actions/13-init-containers.md new file mode 100644 index 00000000..bb566b43 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/13-init-containers.md @@ -0,0 +1,19 @@ +# 13 - 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 + +- `INSTALL.md` - container / runtime choice and the datastores it needs. + +## Process + +1. Write the container / compose definition from `INSTALL.md` (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/14-init-design-system.md b/plugins/aidd-context/skills/01-bootstrap/actions/14-init-design-system.md new file mode 100644 index 00000000..14ac80b3 --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/14-init-design-system.md @@ -0,0 +1,17 @@ +# 14 - Init design system + +Establish the project's design system. Front-end only - skip when `INSTALL.md` declares no frontend. Delegates entirely; owns no design logic. + +## Inputs + +- Whether the project has a frontend (from `INSTALL.md`). The design system's content comes from the design tool, not from `INSTALL.md`. + +## 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/15-init-ci.md b/plugins/aidd-context/skills/01-bootstrap/actions/15-init-ci.md new file mode 100644 index 00000000..86d6507f --- /dev/null +++ b/plugins/aidd-context/skills/01-bootstrap/actions/15-init-ci.md @@ -0,0 +1,19 @@ +# 15 - 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 + +- The CI platform (from `INSTALL.md` / the project's VCS docs). +- A repository with a remote, the quality gate (`11`), and the tests (`12`). + +## Process + +1. Resolve the CI platform; never assume one. +2. Emit a minimal pipeline that runs the quality gate and the tests. +3. Commit, push, and 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/evals/scenarios.json b/plugins/aidd-context/skills/01-bootstrap/evals/scenarios.json deleted file mode 100644 index db495899..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/evals/scenarios.json +++ /dev/null @@ -1,17 +0,0 @@ -[ - { "prompt": "I want to bootstrap a new SaaS for managing client invoices", "expect_action": "gather-needs" }, - { "prompt": "Help me imagine the technical architecture for my project", "expect_action": "gather-needs" }, - { "prompt": "Generate INSTALL.md for my project", "expect_action": "gather-needs" }, - { "prompt": "Bootstrap a new SaaS project from scratch", "expect_action": "gather-needs" }, - { "prompt": "Choose a stack for my new SaaS", "expect_action": "gather-needs" }, - { "prompt": "Monolith vs microservices for my SaaS startup", "expect_action": "gather-needs" }, - { "prompt": "Validate the technical stack of my SaaS", "expect_action": "gather-needs" }, - { "prompt": "Bootstrap saas architecture from scratch", "expect_action": "gather-needs" }, - { "prompt": "Démarre une SaaS et conçois l'architecture", "expect_action": "gather-needs" }, - { "prompt": "Aide-moi à imaginer l'architecture de ma SaaS", "expect_action": "gather-needs" }, - { "prompt": "Génère le INSTALL.md de mon nouveau projet SaaS", "expect_action": "gather-needs" }, - { "prompt": "Valide mon stack SaaS monolith vs microservices", "expect_action": "gather-needs" }, - { "prompt": "Design my database schema for users and orders", "expect_action": null }, - { "prompt": "Set up my CI/CD pipeline", "expect_action": null }, - { "prompt": "Refactor my React component", "expect_action": null } -] diff --git a/plugins/aidd-context/skills/07-design-system/README.md b/plugins/aidd-context/skills/07-design-system/README.md index 1a9b8b6a..9c0cf0e2 100644 --- a/plugins/aidd-context/skills/07-design-system/README.md +++ b/plugins/aidd-context/skills/07-design-system/README.md @@ -16,4 +16,4 @@ The **Impeccable** skill (the playbook checks and guides install if missing). ## Not for -UI/feature generation or redesign - use `impeccable` directly. +Authoring 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 only founds the system; Impeccable does the work and `DESIGN.md` stays canonical. diff --git a/plugins/aidd-context/skills/07-design-system/SKILL.md b/plugins/aidd-context/skills/07-design-system/SKILL.md index 7a4ff94b..de2c5d36 100644 --- a/plugins/aidd-context/skills/07-design-system/SKILL.md +++ b/plugins/aidd-context/skills/07-design-system/SKILL.md @@ -24,3 +24,5 @@ Guided onboarding for authoring a quality design system. It does NOT generate th ## Default flow Single action. It confirms Impeccable is available, then drives the playbook. + +Authoring page code is **not** this skill's concern (Knowledge layer). A page's visual is produced at implementation time, where the implementer delegates the presentational layer to Impeccable against this `DESIGN.md`. diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index bb39669d..3decf560 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -56,15 +56,14 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | Argument Hint | |-------|------|---|---| | `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | -| `actions` | [02-components-behavior.md](skills/01-plan/actions/02-components-behavior.md) | - | - | -| `actions` | [03-image-extract-details.md](skills/01-plan/actions/03-image-extract-details.md) | - | - | +| `actions` | [02-design.md](skills/01-plan/actions/02-design.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` | [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).` | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` | - | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool.` | - | #### `skills/02-implement` diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md index 6895e728..c8489d33 100644 --- a/plugins/aidd-dev/agents/implementer.md +++ b/plugins/aidd-dev/agents/implementer.md @@ -84,6 +84,7 @@ Your output is complete when: - `aidd-dev:04-audit` - `aidd-dev:07-refactor` - `aidd-vcs:01-commit` +- `impeccable` (visual authoring of dumb components only - declared external design tool) Anything else is out of bounds. diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md index 9962491a..fce3eab4 100644 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -2,19 +2,18 @@ # 01 - plan -Generates technical implementation plans, defines component behaviors as -state machines, and extracts structured component inventories from design -images. The plan file is the single source of truth that downstream skills -(`02-implement`, `05-review`) consume. +Generates technical implementation plans, and defines a frontend page's +design - component behaviors as state machines plus the dumb/smart split that +delegates the visual to the design tool. The plan file is the single source of +truth that downstream skills (`02-implement`, `05-review`) consume. ## When to use - A validated spec or ticket exists and you need a phased plan with milestones, rules, and acceptance criteria before any code change. -- A frontend component needs its behavior pinned down as a state machine - before implementation. -- A design image (Figma export, mockup, screenshot) needs to be turned into - a hierarchical component inventory. +- A frontend page/feature needs its design pinned down before implementation: + component behavior (state machines), the dumb/smart split, and whether to + render it. ## When NOT to use @@ -30,19 +29,18 @@ images. The plan file is the single source of truth that downstream skills Use skill aidd-dev:01-plan ``` -The skill exposes 3 actions: +The skill exposes 2 actions: 1. `plan` - produce a phased implementation plan from a spec or ticket. -2. `components-behavior` - define a component's behavior as a state machine. -3. `image-extract-details` - analyze a design image and emit a hierarchical - component inventory. +2. `design` - define a frontend page's design: component behavior (state + machines), the dumb/smart split, and the render decision. ## Outputs - A plan file in `aidd_docs/plans/` with frontmatter, M/C/D (must / could / done), rules table, and ordered phases. -- A state-machine description (Mermaid) for the target component. -- A structured component inventory derived from the image source. +- A frontend page design: state machines (Mermaid), the dumb/smart split, and + the render flag. ## Prerequisites diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index a951e4fc..9ffbd894 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: 01-plan -description: Generate technical implementation plans, define component behaviors, and extract design details from images. +description: Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool. model: opus context: fork agent: planner @@ -8,7 +8,7 @@ agent: planner # Skill: plan -Produces implementation plans from requirements, state machines for component behavior, and structured component inventories from design images. +Produces implementation plans from requirements, and a frontend page's design: component behavior as state machines, the dumb/smart split, and the render decision. ## Agent delegation @@ -16,24 +16,21 @@ Spawn the `planner` agent to execute this skill. For tools that do not support ` ## Available actions -| # | Action | When to use | -| --- | ------------------------ | --------------------------------------------------------------------------- | -| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | -| 02 | `components-behavior` | Define a frontend component's behavior as a state machine (Mermaid) | -| 03 | `image-extract-details` | Analyze a design image into a hierarchical component inventory | +| # | Action | When to use | +| --- | ---------- | ------------------------------------------------------------------------------------ | +| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | +| 02 | `design` | Define a frontend page's design: component behavior (state machines) + dumb/smart split + render decision | ## Routing (run first) The planner auto-adapts to the INPUT - do not ask the user to choose. Detect the input type and route; do NOT always fall to action 01. -- A design image or mockup is provided -> `03-image-extract-details` (then feed the inventory into planning). -- The request is about a frontend component's behavior, states, or transitions -> `02-components-behavior`. +- The request is about a frontend page/feature's design - component behavior, states, the dumb/smart split, or whether to render -> `02-design`. - Anything else (requirements, a feature to build) -> `01-plan`. -Actions may chain (e.g. extract from image, then plan). Read and follow each selected action file. +Actions may chain (e.g. design the page, then plan its build). Read and follow each selected action file. ## Actions - `@actions/01-plan.md` -- `@actions/02-components-behavior.md` -- `@actions/03-image-extract-details.md` +- `@actions/02-design.md` diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md b/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md deleted file mode 100644 index 2f4efbc5..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md +++ /dev/null @@ -1,35 +0,0 @@ -# 02 - Components behavior - -Define the expected behavior of one or more frontend components as state machines, rendered in Mermaid syntax for user validation. - -## Inputs - -```yaml -components: -``` - -## Outputs - -```yaml -state_machines: - - component: - diagram: - states: [] - transitions: [{ from: , to: , event: , condition: }] -``` - -## Process - -Iterate over the steps below until each component is fully defined. - -1. **Parse the request.** Extract the list of components from `$ARGUMENTS`. -2. **Per component**: - - Identify the key states the component can be in. - - Determine the events or actions that trigger transitions between states. - - Define the state machine in Mermaid syntax, applying `@../references/mermaid-conventions.md`. -3. **Sanity-check the model.** Confirm the state machine captures every state and every transition relevant to the component's behavior. -4. **Present the final state machines** to the user for validation. Wait for an explicit OK before exiting. - -## Test - -For each component in `components`: the corresponding `state_machines` entry has a Mermaid block that parses, lists at least two states, and every transition references states that exist in the same diagram. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md new file mode 100644 index 00000000..2647ee5c --- /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: + - Build the smart layer in-house per the behaviors above. + - Author each dumb component's visual by calling the design tool with quotes: `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. + - If render was requested, run under `/goal` (`aidd-dev:09-for-sure`): loop build ↔ `Use skill "impeccable" with "critique "` until **zero P0**, then explicit user OK. +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/actions/03-image-extract-details.md b/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md deleted file mode 100644 index 8e985445..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md +++ /dev/null @@ -1,79 +0,0 @@ -# 03 - Image extract details - -Analyze an image to identify and extract the main components, group them by type, merge close variants, and emit a hierarchical inventory ready for planning. - -## Inputs - -```yaml -image: -``` - -## Outputs - -```yaml -main_reusable_components_with_variants: - - name: - variants: - - name: - style: -main_display_components: - - component_name:

- layouts: - - type: - style: - position_and_display: - components: [] -``` - -## Process - -1. **Identify reusable components.** Scan the image for repeatable UI atoms; group them by type. -2. **Extract variants.** For each reusable atom, collect distinct visual variants. Merge variants that are very close (same role, marginal styling differences). -3. **Remove duplicates.** Keep each unique component once. -4. **Hierarchical organization.** Place layout-level display components above the reusable atoms; nest layouts and their sub-components. -5. **Boundaries.** Emoji are not components. Do not detail photography. - -## Test - -`main_reusable_components_with_variants` lists each unique reusable atom exactly once with at least one variant; `main_display_components` covers every top-level section visible in the image; no entry references emoji or stock photography. - -## Output format example - -```yaml -main_reusable_components_with_variants: - - name: "Chip" - variants: - - name: "Generate" - style: "Purple text, rounded pill shape, small sparkle icon" - -main_display_components: - - component_name: Hero Section - layouts: - - type: Vertical Stack - style: "Centered alignment, full-width layout" - position_and_display: "Top of page" - components: - - type: Text Block - content: "For individuals, independent creators and tech companies" - variant: "Heading" - - type: Text Block - content: "Empowering individuals, creators, and tech innovators with cutting-edge AI solutions." - variant: "Subheading" - - - component_name: Feature Grid - layouts: - - type: Two-Column Layout - style: "Even 2-column grid, responsive layout" - position_and_display: "Below hero section" - components: - - component_name: Right Feature Card - position_and_display: "Right column" - layout: "Vertical stack" - sub_components: - - type: Text Block - content: "Don't write by yourself, it's boring. Instead, let AI" - variant: "Paragraph" - - type: Chip - content: "Enhance" - variant: "Enhance" -``` diff --git a/plugins/aidd-dev/skills/01-plan/evals/scenarios.json b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json index 6354a25b..d9f896d5 100644 --- a/plugins/aidd-dev/skills/01-plan/evals/scenarios.json +++ b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json @@ -2,15 +2,12 @@ { "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": "Design the checkout page", "expect_action": "design" }, + { "prompt": "Define component behavior and the dumb/smart split for the onboarding wizard", "expect_action": "design" }, { "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": "Conçois le design de la page checkout", "expect_action": "design" }, { "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/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md index fb944fa8..ddf96d68 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -24,9 +24,10 @@ notes: 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. +3. **Frontend render.** If the design (`01-plan:02-design`) produced a render delegation prompt, launch the `implementer` with it as-is. That prompt carries the dumb-visual delegation and, when render was requested, the `/goal` build↔`critique` loop with its **zero P0 + explicit user OK** success condition. Don't re-specify it here; don't ship the visual on iteration count alone. +4. **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. +5. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. +6. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. ## Test diff --git a/plugins/aidd-orchestrator/CATALOG.md b/plugins/aidd-orchestrator/CATALOG.md index a9d2ce04..0526a0c5 100644 --- a/plugins/aidd-orchestrator/CATALOG.md +++ b/plugins/aidd-orchestrator/CATALOG.md @@ -32,13 +32,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/01-scaffold` -| Group | File | Description | -|-------|------|---| -| `actions` | [01-generate-architecture.md](skills/01-scaffold/actions/01-generate-architecture.md) | - | -| `actions` | [02-implement-and-test.md](skills/01-scaffold/actions/02-implement-and-test.md) | - | -| `actions` | [03-wire-ci.md](skills/01-scaffold/actions/03-wire-ci.md) | - | -| `evals` | [scenarios.json](skills/01-scaffold/evals/scenarios.json) | - | -| `-` | [README.md](skills/01-scaffold/README.md) | - | -| `references` | [project-doc-spec.md](skills/01-scaffold/references/project-doc-spec.md) | - | -| `-` | [SKILL.md](skills/01-scaffold/SKILL.md) | `Build a brand-new project into a running, proven skeleton. Interactively drives the design first (the stack, the architecture, and the technical building blocks the app needs, via the design layer, into an INSTALL.md), then generates the full folder and route tree (every page and API route wired with stub handlers), the selected building blocks as swappable abstractions, an installed test harness, a minimal CI pipeline, the base project docs, the AIDD context layer, and an initialized git repository - proven against a final checklist. Use when the user says scaffold the project, build a new project, initialize the project files, or build the running skeleton. Do NOT use for producing design or architecture docs only (that is the design layer's role), adding features to an existing project, or generating business logic.` | +| 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 index f90156cb..845f2f18 100644 --- a/plugins/aidd-orchestrator/skills/01-scaffold/README.md +++ b/plugins/aidd-orchestrator/skills/01-scaffold/README.md @@ -2,34 +2,28 @@ # 01-scaffold -Builds a brand-new project into a running, proven skeleton. Drives the design with you (stack, architecture, technical building blocks), then generates the full folder + route tree (every page and API route wired with stub handlers), each selected building block as a swappable abstraction, an installed test harness, a minimal CI pipeline, the project docs, the AIDD context layer, and an initialized git repository. Architecture generated per project (not copied from a template), proven against a final checklist. +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 - walks you through the design (stack, architecture, building blocks) then produces a green skeleton to start coding on. +- Starting a new project you want actually built and running, end to end. ## When NOT to use -- Producing only design or architecture docs (use the design layer on its own). +- 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" / "build the running skeleton". +`aidd-orchestrator:01-scaffold`, or say "scaffold a new project". -## Outputs +## What it does -- A running project tree (routes wired, each selected building block as a swappable abstraction, green tests, minimal CI). -- `INSTALL.md` (technologies, why, how to install) + root `README.md` / `CONTRIBUTING.md` + the initialized AIDD context layer. -- An initialized git repository with a conventional initial commit (and a remote on request). - -## Prerequisites - -- Design + finalization capabilities reachable for delegation (stack-and-architecture, blind-spot scan, test, assertion, project-init, repo-init, commit). +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 -Sequential router: delegated design + finalization, owned greenfield generation, checklist-based verification. See [SKILL.md](SKILL.md). +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 index 9aae3e43..747abfbd 100644 --- a/plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md +++ b/plugins/aidd-orchestrator/skills/01-scaffold/SKILL.md @@ -1,57 +1,23 @@ --- name: 01-scaffold -model: opus -description: Build a brand-new project into a running, proven skeleton. Interactively drives the design first (the stack, the architecture, and the technical building blocks the app needs, via the design layer, into an INSTALL.md), then generates the full folder and route tree (every page and API route wired with stub handlers), the selected building blocks as swappable abstractions, an installed test harness, a minimal CI pipeline, the base project docs, the AIDD context layer, and an initialized git repository - proven against a final checklist. Use when the user says scaffold the project, build a new project, initialize the project files, or build the running skeleton. Do NOT use for producing design or architecture docs only (that is the design layer's role), adding features to an existing project, or generating business logic. +disable-model-invocation: true +description: Sequencing tutorial that launches the right skills, in order, to turn a project idea into a running skeleton. --- -# Scaffold +# Skill: scaffold -> Tell user the goal: idea -> running, proven skeleton. Design decided with them; build automated. +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 every step in order; advance only when step test passes. Flow = human-AI conversation. +Run each step, wait for it to return, then move to the next: -| # | Step | Runs | Gate | -| -- | -------------------------------------- | ------------------------------------------------------ | ----------------------------- | -| 1 | Decide stack + architecture + blocks (writes `INSTALL.md` + root `README.md`) | skill: `aidd-context:01-bootstrap` | `INSTALL.md` validated by USER | -| 2 | Scan blind spots | skill: `aidd-refine:04-shadow-areas` | high-severity ↺ to 1 | -| 3 | Init repo (writes `CONTRIBUTING.md`) | skill: `aidd-vcs:00-repo-init` (init) | | -| 4 | Generate architecture (structure + stubs) | `actions/01-generate-architecture.md` | tree validated by the USER | -| 5 | Implement blocks + tests, then verify | `actions/02-implement-and-test.md` | checklist green ⇒ else halt | -| 6 | Wire minimal CI | `actions/03-wire-ci.md` | | -| 7 | Init AIDD context (vs real code) | skill: `aidd-context:02-project-init` | | -| 8 | Generate file-convention rule | skill: `aidd-context:03-context-generate` (rules, topic = step-4 file conventions) | rule written (`01`/`03`) | -| 9 | First commit + publish | skill: `aidd-vcs:01-commit` -> `aidd-vcs:00-repo-init` (publish) | | -| 10 | Handoff (report vs checklist) | router report (no file) | | +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"`. -## Available actions - -The three owned actions run as Flow steps 4 (`01`), 5 (`02`), 6 (`03`). Every other step is a delegated `skill:`. - -| # | Action | Role | Input | -| -- | ----------------------- | -------------------------------------------------------------------------- | --------------------------- | -| 01 | `generate-architecture` | Structure tree + file conventions + every route as a navigable stub (back + front) | INSTALL.md | -| 02 | `implement-and-test` | Wire each selected building block (swappable abstraction + smoke test), then run the full checklist green - hard gate | generated tree + INSTALL.md | -| 03 | `wire-ci` | Minimal CI that runs the tests | verified project | - -## Resume - show what's already done - -Before step 1, detect existing artifacts; present a done/remaining checklist of the flow to the human; resume interactively from the first unmet step. Never silently redo or skip. - -```markdown -@references/project-doc-spec.md -``` - -Render as `✓` / `◻` checklist; human decides where to pick up. +Each skill validates its own work; do not re-verify here. When the last returns, report what was built. ## Rules -- **Interactive design; never fabricate.** Steps 1-2 invoke their skills and **wait for the human** at every question and validation - never invent the stack, architecture, or building blocks. Do not start generation until the human has validated `INSTALL.md`. If a validated `INSTALL.md` exists, confirm it with the human instead of re-asking. Only a scaffolder pipeline run with `auto` may skip the prompts. -- **Architecture 100%, business 0%.** Routes carry only minimal behavior to pass their tests - no auth, no domain logic. -- **The checklist is the guarantee.** Action `02` ends by running the full assertive checklist (`references/project-doc-spec.md`); any unchecked item halts the run - never auto-patched. -- **File conventions decided once.** Decided at step 4, applied to stubs; persisted by step 7 (casing -> memory) and step 8 (placement -> rule). Never defined twice. - -## References - -- `references/project-doc-spec.md` - the assertive checklist action `02` runs (rendered in `## Resume`). - -Root docs are not scaffold's assets: `README.md` + `INSTALL.md` come from the design phase (`aidd-context:01-bootstrap`), `CONTRIBUTING.md` from `aidd-vcs:00-repo-init`. +- **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-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md b/plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md deleted file mode 100644 index f4823d4a..00000000 --- a/plugins/aidd-orchestrator/skills/01-scaffold/actions/01-generate-architecture.md +++ /dev/null @@ -1,46 +0,0 @@ -# 01 -- Generate Architecture - -Produce the architecture: - -- folder/route tree -- navigable stub skeleton covering every route, back and front. -- Structure and stubs only - no behavior, no tests. - -## Inputs - -- `install_md` (required) -- chosen stack, architecture pattern, selected building blocks. - -## Outputs - -A validated **tree** (the structure), the **file conventions** governing it, plus a reachable stub per route. Expressed at structure level - the host stack determines concrete files and language. - -``` -/ - /... -``` - -Conventions every generated file follows, derived from the stack's idioms (`INSTALL.md`): - -- **Naming** - casing and suffixes for files and folders (how routes, handlers, components are cased and named). -- **Tests** - where test files live and how named (colocated vs dedicated dir, the test suffix). -- **Colocation** - where a route's companions (component, handler, types, helpers) sit relative to the route. - -## Depends on - -- the router's design phase (provides `INSTALL.md`: stack, pattern, building blocks) - -## Process - -1. Establish the **route surface** (app's pages and API endpoints) with the USER, derived from purpose and building blocks in `INSTALL.md`. Derive folder tree from the architecture pattern, and **file conventions** (naming, tests, colocation) from the stack's idioms. - > Present route surface, tree, and conventions for inspection. Keep tree at structure level - no language, path, or tool assumptions; conventions follow the stack. -2. **Validate the tree and conventions with the USER**. -3. Once approved, create a reachable stub for every page route and every API route (back and front), following agreed conventions uniformly: navigation resolves, handlers empty. No behavior. -4. Add rule using `context-generate` skill for the architecture + naming convention. -5. Be sure everything is up-to-date (`README`, `CONTRIBUTING`, `INSTALL.md`) - -## Test - -- [ ] File tree is done -- [ ] Naming convention is defined and applied -- [ ] Rules are created (in `01-standards`, `03-frameworks-and-libraries`) -- [ ] Docs is updated (`README`, `CONTRIBUTING`, `INSTALL.md`) \ No newline at end of file diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md b/plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md deleted file mode 100644 index e43e90a7..00000000 --- a/plugins/aidd-orchestrator/skills/01-scaffold/actions/02-implement-and-test.md +++ /dev/null @@ -1,36 +0,0 @@ -# 02 -- Implement And Test - -Bring the skeleton to life and prove it: wire each selected building block as a swappable abstraction with its smoke test, install the harness, write per-surface tests, then run the full assertive checklist green. Hard gate - the checklist is the guarantee. - -## Outputs - -Intent level (host stack determines language and files): - -- Each **selected building block** (per `INSTALL.md`) wired as swappable abstraction - dev stub + real provider, env-flag chosen - with a smoke test (e.g. data round-trips, test email dispatches, scheduled job fires once). -- Stack's **dependencies installed**, **test runner configured**. -- A **small test set written alongside code and passing**: each block's smoke test, plus one per surface proving API routes respond and front routes navigate. -- **Assertive checklist all green** (`@../references/project-doc-spec.md`). - -## Depends on - -- `01-generate-architecture` - -### Project doc spec - -```markdown -@../references/project-doc-spec.md -```` - -## Process - -1. For each items in "Project doc spec", make sure everything is well prepared showing a table to `USER`. -2. **Validate with the USER if necessary**. -3. Spawn an agent / group on to setup it correctly. -4. For each surface, write the minimal test proving this work. -5. Show report to `USER`. - -## Test - -- [ ] All checkboxes checked. -- [ ] All tests pass. -- [ ] No untested element. \ No newline at end of file diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md b/plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md deleted file mode 100644 index 1e431fe4..00000000 --- a/plugins/aidd-orchestrator/skills/01-scaffold/actions/03-wire-ci.md +++ /dev/null @@ -1,25 +0,0 @@ -# 03 -- Wire CI - -Emit minimal CI pipeline running tests, for project's chosen CI platform. No platform assumed. - -## Outputs - -The URL of the working CI. - -## Depends on - -### Project doc spec - -```markdown -@../references/project-doc-spec.md -```` - -## Process - -1. Resolve CI platform from `INSTALL.md`. -2. Read "Project doc spec". -3. Configure everything correctly. - -## Test - -- [ ] CI is passing green. \ No newline at end of file diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json b/plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json deleted file mode 100644 index 99a6517c..00000000 --- a/plugins/aidd-orchestrator/skills/01-scaffold/evals/scenarios.json +++ /dev/null @@ -1,7 +0,0 @@ -[ - { "prompt": "Scaffold the project from my INSTALL.md", "expect_action": "generate-architecture" }, - { "prompt": "Initialize the project files and build the running skeleton", "expect_action": "generate-architecture" }, - { "prompt": "Set up the actual project now that the stack and architecture are decided", "expect_action": "generate-architecture" }, - { "prompt": "Choose the best stack and architecture for my new SaaS", "expect_action": null }, - { "prompt": "Add a new settings page to my existing app", "expect_action": null } -] diff --git a/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md b/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md deleted file mode 100644 index 36f15b59..00000000 --- a/plugins/aidd-orchestrator/skills/01-scaffold/references/project-doc-spec.md +++ /dev/null @@ -1,47 +0,0 @@ -# Project doc spec - -Items to initialize when scaffolding a project. - -> Beware to only use maintained stack libs. - -## Assertive checklist - -### Project - -- [ ] The architecture conforms to the chosen pattern. -- [ ] `aidd_docs` is initialized. -- [ ] `.git` and remote repo exist. -- [ ] Dependency manager chosen, deps install and the app boots. - -### Quality - -- [ ] Commit linter installed. -- [ ] Pre-commit gate passes (with quality under and unit tests). -- [ ] Auto formatting configured -- [ ] Lint passes -- [ ] Typecheck - -### Testing - -- [ ] A unit test passes. -- [ ] An end-to-end test passes. -- [ ] Coverage. - -### Deployment - -- [ ] CI config commited and passing on server. -- [ ] If a container/runtime is used, it ups and downs cleanly. - -### App - -- [ ] `INSTALL.md` filled with proper chosen techs. - -#### Frontend only - -- [ ] A11y UI lib installed. -- [ ] A form submits with validator lib and tested. -- [ ] Lighthouse thresholds configured. -- [ ] Accessibility tests. -- [ ] Form system with validation. -- [ ] Design System Created. -- [ ] Default pages: 404, 403 etc. From 3873145835b2104d7443f78e2016091f53184bd2 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 11 Jun 2026 10:52:06 +0200 Subject: [PATCH 19/22] refactor(bootstrap): restructure flow around PRD check and stack choice The imagine phase had six overlapping actions; collapsing them into check-prd -> gather-needs -> choose-stack makes the runbook linear and renumbers the init actions accordingly. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 3 +- docs/CATALOG.md | 3 +- plugins/aidd-context/CATALOG.md | 33 +++++----- .../skills/01-bootstrap/README.md | 36 +++++------ .../aidd-context/skills/01-bootstrap/SKILL.md | 56 ++++++++--------- .../01-bootstrap/actions/01-check-prd.md | 17 +++++ .../01-bootstrap/actions/01-gather-needs.md | 35 ----------- .../01-bootstrap/actions/02-gather-needs.md | 20 ++++++ .../actions/02-propose-candidates.md | 37 ----------- .../actions/03-audit-candidates.md | 63 ------------------- .../01-bootstrap/actions/03-choose-stack.md | 19 ++++++ .../actions/04-init-install-md.md | 21 +++++++ .../actions/04-pick-and-design.md | 27 -------- .../actions/05-decide-architecture.md | 43 ------------- .../actions/05-init-architecture.md | 20 ++++++ ...ependencies.md => 06-init-dependencies.md} | 5 +- .../actions/06-write-install-md.md | 39 ------------ .../{09-init-env.md => 07-init-env.md} | 6 +- .../01-bootstrap/actions/07-init-structure.md | 20 ------ ...0-init-database.md => 08-init-database.md} | 11 ++-- ...uality-gate.md => 09-init-quality-gate.md} | 10 +-- .../{12-init-tests.md => 10-init-tests.md} | 7 +-- ...it-containers.md => 11-init-containers.md} | 7 ++- ...ign-system.md => 12-init-design-system.md} | 6 +- .../skills/01-bootstrap/actions/13-init-ci.md | 19 ++++++ .../skills/01-bootstrap/actions/15-init-ci.md | 19 ------ .../{assets => references}/checklist.md | 0 .../skills/01-plan/actions/02-design.md | 6 +- .../02-implement/actions/01-implement.md | 2 +- 29 files changed, 211 insertions(+), 379 deletions(-) create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/01-check-prd.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/02-gather-needs.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/02-propose-candidates.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/03-audit-candidates.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/03-choose-stack.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/04-init-install-md.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/05-init-architecture.md rename plugins/aidd-context/skills/01-bootstrap/actions/{08-init-dependencies.md => 06-init-dependencies.md} (70%) delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md rename plugins/aidd-context/skills/01-bootstrap/actions/{09-init-env.md => 07-init-env.md} (64%) delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md rename plugins/aidd-context/skills/01-bootstrap/actions/{10-init-database.md => 08-init-database.md} (62%) rename plugins/aidd-context/skills/01-bootstrap/actions/{11-init-quality-gate.md => 09-init-quality-gate.md} (65%) rename plugins/aidd-context/skills/01-bootstrap/actions/{12-init-tests.md => 10-init-tests.md} (69%) rename plugins/aidd-context/skills/01-bootstrap/actions/{13-init-containers.md => 11-init-containers.md} (51%) rename plugins/aidd-context/skills/01-bootstrap/actions/{14-init-design-system.md => 12-init-design-system.md} (67%) create mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/13-init-ci.md delete mode 100644 plugins/aidd-context/skills/01-bootstrap/actions/15-init-ci.md rename plugins/aidd-context/skills/01-bootstrap/{assets => references}/checklist.md (100%) diff --git a/CLAUDE.md b/CLAUDE.md index 3e9fc4f1..8d8d4c01 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,7 +22,7 @@ Treat instructions/info above as possibly stale. USER can be wrong; stay critica ## Communication -Essential without losing clarity. +Essential without losing clarity: always answer in min words. - Minimal words, like a caveman. - **Less is more**: minimal output without losing sense. @@ -37,6 +37,7 @@ Essential without losing clarity. ## 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. 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 7569f02e..4e7b5b28 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -67,27 +67,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-decide-architecture.md](skills/01-bootstrap/actions/05-decide-architecture.md) | - | -| `actions` | [06-write-install-md.md](skills/01-bootstrap/actions/06-write-install-md.md) | - | -| `actions` | [07-init-structure.md](skills/01-bootstrap/actions/07-init-structure.md) | - | -| `actions` | [08-init-dependencies.md](skills/01-bootstrap/actions/08-init-dependencies.md) | - | -| `actions` | [09-init-env.md](skills/01-bootstrap/actions/09-init-env.md) | - | -| `actions` | [10-init-database.md](skills/01-bootstrap/actions/10-init-database.md) | - | -| `actions` | [11-init-quality-gate.md](skills/01-bootstrap/actions/11-init-quality-gate.md) | - | -| `actions` | [12-init-tests.md](skills/01-bootstrap/actions/12-init-tests.md) | - | -| `actions` | [13-init-containers.md](skills/01-bootstrap/actions/13-init-containers.md) | - | -| `actions` | [14-init-design-system.md](skills/01-bootstrap/actions/14-init-design-system.md) | - | -| `actions` | [15-init-ci.md](skills/01-bootstrap/actions/15-init-ci.md) | - | -| `assets` | [checklist.md](skills/01-bootstrap/assets/checklist.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, validate, then stand up a new project. First designs the technical architecture through interactive Q&A, candidate-stack comparison, and multi-agent audit into a validated `INSTALL.md` + `README.md`; then materializes that `INSTALL.md` into a running, proven skeleton via atomic `init-*` actions (structure, dependencies, env, database, quality gate, tests, containers, design system). 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.` | +| `-` | [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` @@ -168,6 +166,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-create-design-system.md](skills/07-design-system/actions/01-create-design-system.md) | - | +| `actions` | [02-redesign-page.md](skills/07-design-system/actions/02-redesign-page.md) | - | | `-` | [README.md](skills/07-design-system/README.md) | - | | `-` | [SKILL.md](skills/07-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/skills/01-bootstrap/README.md b/plugins/aidd-context/skills/01-bootstrap/README.md index 2c138741..9beea8bd 100644 --- a/plugins/aidd-context/skills/01-bootstrap/README.md +++ b/plugins/aidd-context/skills/01-bootstrap/README.md @@ -2,7 +2,7 @@ # 01 - Bootstrap -Technical architect **and** builder for a new project. **Design** (actions 01-06): walk a 24-item checklist, propose 2-3 candidate stacks, audit each via parallel agents, and produce a validated project-root `INSTALL.md` + `README.md`. **Build** (actions 07-14): 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`). +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 @@ -24,26 +24,24 @@ Use skill aidd-context:01-bootstrap ### Design phase → validated `INSTALL.md` -1. `gather-needs` - Q&A across the 24-item checklist plus selected building blocks. -2. `propose-candidates` - derive 2-3 candidate stacks, render a comparison table. -3. `audit-candidates` - parallel agents validate each candidate; if all fail, loop back to `02`/`01`. -4. `pick-and-design` - user picks the winning stack. -5. `decide-architecture` - fact-checked top-3 patterns, human-picked, plus a Mermaid module diagram. -6. `write-install-md` - produce the project-root `INSTALL.md` + `README.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 validated; conditional actions skip per `INSTALL.md`. +No build action runs until `INSTALL.md` is written and validated; conditional actions skip per `INSTALL.md`. -7. `init-structure` - folder tree + reachable route stubs. -8. `init-dependencies` - dependency manager + building blocks (swappable) + boot. -9. `init-env` - `.env.example` + config loading. -10. `init-database` - engine + baseline migration + seed fixtures + round-trip *(conditional)*. -11. `init-quality-gate` - typecheck + format + lint + commit-linter + pre-commit (one gate). -12. `init-tests` - runner + unit + e2e + coverage *(delegated)*. -13. `init-containers` - container ups & downs cleanly *(conditional)*. -14. `init-design-system` - design system *(front-only, delegated)*. -15. `init-ci` - pipeline runs the quality gate + tests, green on the server *(conditional)*. +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 @@ -51,9 +49,9 @@ No build action runs until `INSTALL.md` is validated; conditional actions skip p ## Prerequisites -- A clear (or loosely-formed) product idea to discuss. +- 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`, and `assets/`. The Mermaid diagram (action 05) renders via the sibling `04-mermaid` skill; `init-tests` and `init-design-system` delegate to the capability that owns them, discovered by description. +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 `04-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 cb704b4e..7b627a7d 100644 --- a/plugins/aidd-context/skills/01-bootstrap/SKILL.md +++ b/plugins/aidd-context/skills/01-bootstrap/SKILL.md @@ -1,64 +1,62 @@ --- name: 01-bootstrap -description: Imagine, validate, then stand up a new project. First designs the technical architecture through interactive Q&A, candidate-stack comparison, and multi-agent audit into a validated `INSTALL.md` + `README.md`; then materializes that `INSTALL.md` into a running, proven skeleton via atomic `init-*` actions (structure, dependencies, env, database, quality gate, tests, containers, design system). 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. +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 -Technical architect **and** builder for a new project. Two phases. **Design** (01-06): walk a 24-item checklist, propose 2-3 candidate stacks, audit each, produce a validated `INSTALL.md` + `README.md`. **Build** (07-14): 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`). +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 **Design phase** - produces the validated `INSTALL.md` (docs only): -| # | 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 winning stack; fill block-4 stack choices | audit report | -| 05 | `decide-architecture` | Fact-checked top-3 architecture patterns, human-picked; Mermaid module diagram | chosen stack + needs | -| 06 | `write-install-md` | Produce `INSTALL.md` + project-root `README.md` | design + decisions | +| # | 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. Each action reads `INSTALL.md`, names no technology, has its own gate: +**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 | | --- | -------------------- | --------------------------------------------------------------------- | ----------------- | -| 07 | `init-structure` | Folder tree + reachable route stubs from `INSTALL.md` | owns | -| 08 | `init-dependencies` | Dependency manager + building blocks (swappable) + boot | owns | -| 09 | `init-env` | `.env.example` + config loading | owns | -| 10 | `init-database` | Engine + baseline migration + fixtures + round-trip *(conditional)* | owns | -| 11 | `init-quality-gate` | typecheck + format + lint + commit-linter + pre-commit (one gate) | owns | -| 12 | `init-tests` | Runner + 1 unit + 1 e2e + coverage | testing capability | -| 13 | `init-containers` | Container/compose ups & downs clean *(conditional)* | owns | -| 14 | `init-design-system` | Design system *(front-only, conditional)* | design-system capability | -| 15 | `init-ci` | Pipeline runs the quality gate + tests, green on the server *(conditional)* | owns | +| 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 -**Design** `01 → 02 → 03 → 04 → 05 → 06`, then **Build** `07 → 08 → 09 → 10 → 11 → 12 → 13 → 14 → 15`. Sequential. Audit (03) is a gate: if every candidate returns `❌`, loop back to 02 (revise candidates) or 01 (revisit needs). Architecture decision (05) is a human-validation gate on a fact-checked top-3. **No build action runs until `INSTALL.md` is validated** (end of 06). Conditional build actions (10, 13, 14, 15) skip when the project does not call for them. Each build action advances only when its own `## Test` gate is green. +**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 -- **Design before build; never fabricate.** No build action (07+) runs until the human has validated `INSTALL.md`. The design phase invents nothing - it waits for the human at every checklist and gate. +- **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.** Every `init-*` action reads `INSTALL.md` and names no technology of its own. The chosen tools come from `INSTALL.md`, not from the action prompt. +- **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 user stack preference conflicts with needs (e.g. wants Mongo for heavily relational data), challenge before accepting: surface audit concerns, ask for mitigation plan. -- **Recommend opinionated, not encyclopedic.** Each action proposes 2-3 options max, never a long catalog. User leaves 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 - plus selected building blocks; the 6 derived items (block 4) are filled across actions 02, 04, 05 (architecture pattern). +- **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.md` - the `INSTALL.md` skeleton (technologies, why chosen, how to install) +- `@assets/INSTALL.md` - the `INSTALL.md` skeleton - `@assets/README.md` - the project-root `README.md` template ## External data -- `aidd-context/skills/04-mermaid/SKILL.md` - invoked from action 05 to render the architecture diagram +- `aidd-context/skills/04-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 dd2a4a00..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/01-gather-needs.md +++ /dev/null @@ -1,35 +0,0 @@ -# 01 - Gather needs - -Walk user through the 24-item checklist via interactive Q&A until all 18 user-input items (blocks 1-3) filled. The 6 derived items (block 4) stay empty here - filled by actions 02, 04, 05. - -## Inputs - -- Free-form user request to bootstrap a new SaaS project. - -## Outputs - -Filled copy of `@../assets/checklist.md` held in conversation context (not yet on 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) -``` - -Plus selected **building blocks** - data, and any of auth, email, file storage, background jobs, scheduled jobs (CRON), payments, logging - recorded later in `INSTALL.md`. - -## Process - -1. Read `@../assets/checklist.md`. Print the four blocks as a single markdown checklist so user sees full scope upfront. -2. Ask block by block, one block per message. Within a block, ask all questions at once (user answers in batch). Do not ask block 4 - derived. -3. For each user answer, fill the matching item. If vague ("scalable", "fast"), ask one follow-up to make it concrete (numbers, examples). -4. After block 1, sanity-check coherence: type matches user volume? 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. Capture **technical building blocks** the app needs - data, and any of auth, email, file storage, background jobs, scheduled jobs (CRON), payments, logging/errors; select only those that apply. These feed provider decisions (actions 04-05) and the scaffold. -7. Print the filled checklist (blocks 1-3) + selected building blocks; ask 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, the selected building blocks are captured, and the user has explicitly confirmed 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 bc93c9bf..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/04-pick-and-design.md +++ /dev/null @@ -1,27 +0,0 @@ -# 04 - Pick and design - -User picks winning candidate (informed by audit). Fill checklist block 4 with concrete stack choices. Architecture pattern + folder tree decided next, in action 05. - -## Inputs - -- Augmented comparison table from action 03 (verdicts + rationale). -- Filled checklist blocks 1-3. - -## Outputs - -Checklist with **block 4 stack items filled** (front, back, DB, auth, final hosting). Architecture-pattern item left for action 05. - -## Depends on - -- `03-audit-candidates` - -## Process - -1. Print action 03 augmented table. Ask user to pick a candidate by letter (A / B / C). -2. If picked candidate verdict `⚠️`: surface audit concerns directly - list specific risks found in action 03, ask whether user has mitigation plan, loop until satisfied or candidate switched. -3. If picked candidate verdict `❌`: refuse pick, loop back to let user choose differently. (Do not proceed with known-broken stack.) -4. Fill block 4 stack items (front, back, DB, auth, final hosting) with picked candidate's concrete choices. Leave architecture-pattern item empty - action 05 decides it. Show user filled stack choices, ask them to confirm "go". - -## Test - -Block 4's five stack items (front, back, DB, auth, hosting) filled, no remaining `<...>` placeholders, architecture-pattern item still empty, user confirmed stack in writing. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md b/plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md deleted file mode 100644 index f641d8b7..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/05-decide-architecture.md +++ /dev/null @@ -1,43 +0,0 @@ -# 05 - Decide architecture - -Propose modern, effective architecture patterns for chosen stack + needs as a fact-checked top-3; human picks one; derive module diagram. - -## Inputs - -- Chosen stack (block 4 stack items, from action 04). -- Filled checklist blocks 1-3 (needs and constraints). - -## Outputs - -Two artifacts held in conversation context (not yet written to disk): - -1. Checklist with **block 4's architecture-pattern item filled** (human-picked winner). -2. Mermaid diagram showing modules and relations. - -```markdown -## Architecture top-3 (for Next.js + Postgres, relational domain) - -| # | Pattern | Why it fits | -| - | ------------------ | ------------------------------------------------------- | -| 1 | Modular monolith | One deploy, clear module seams, easiest to evolve later | -| 2 | Clean architecture | Strong boundaries, swappable infra, more upfront cost | -| 3 | Vertical slice | Feature-first, low ceremony, weaker shared-core control | -``` - -## Depends on - -- `04-pick-and-design` - -## Process - -1. **Fact-check first.** Before proposing, verify candidate patterns are current best practice for this stack: discover a fact-check capability by matching loaded-skill descriptions for keywords such as `verify factual claims against authoritative sources`, `cite your sources` (do not match by hardcoded skill name), or spawn an audit agent as action 03 does. Discard anything stale. -2. Propose a **top-3** of architecture patterns ranked for chosen stack + needs, each with a one-line rationale. Opinionated, max 3 - never a catalogue. Apply heuristics from `@../references/stack-heuristics.md`. -3. **Human validation gate.** User picks one of the three (or asks to revise). Do not proceed on silence. -4. Fill block 4's architecture-pattern item with the picked winner. -5. Derive high-level modules from chosen pattern + selected building blocks (a module per block, plus the pattern's standard divisions). Concrete folder tree is the scaffold's job - not part of the ADR. -6. Generate the Mermaid module diagram by invoking `aidd-context:04-mermaid` with those modules and relations. Verify it parses (no parser errors). -7. Print top-3 rationale, chosen pattern, and diagram together. Wait for user confirmation before action 06. - -## Test - -A fact-checked top-3 of architecture patterns was presented; user picked one in writing; block 4's architecture-pattern item is filled with no `<...>` placeholder; a ` ```mermaid ` block is present and parses without error. 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/08-init-dependencies.md b/plugins/aidd-context/skills/01-bootstrap/actions/06-init-dependencies.md similarity index 70% rename from plugins/aidd-context/skills/01-bootstrap/actions/08-init-dependencies.md rename to plugins/aidd-context/skills/01-bootstrap/actions/06-init-dependencies.md index 76865be8..3d5c6c62 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/08-init-dependencies.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/06-init-dependencies.md @@ -1,10 +1,11 @@ -# 08 - Init dependencies +# 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` - dependency manager, stack, building blocks (with env flags). +- `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 diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md b/plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md deleted file mode 100644 index 8680075a..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/06-write-install-md.md +++ /dev/null @@ -1,39 +0,0 @@ -# 06 - Write INSTALL.md - -Produce `INSTALL.md` (technologies, why chosen, how to install) from the filled checklist, stack decisions, module diagram. Plus project-root `README.md` from its template. - -## Inputs - -- Filled checklist (stack items from action 04, architecture pattern from action 05). -- Mermaid diagram (from action 05). -- Audit verdicts (from action 03) - inform `Why` column, not a section. - -## Outputs - -New file `INSTALL.md` filled from `@../assets/INSTALL.md`. - -Plus two project-root docs: - -- `README.md` filled from `@../assets/README.md` - -## Depends on - -- `05-decide-architecture` - -## Process - -1. Read `@../assets/INSTALL.md`. 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 one-line `Why` derived from block 2-3 constraints - - **Stack summary**: concrete versions / SaaS plans where known - - **Building blocks table**: one row per selected block - the block, its chosen provider, its env flag (only blocks the app needs; Data always present) - - **Architecture**: paste Mermaid diagram from action 05 + 2-3 sentences explaining module boundaries - - **Install, configure, run, test**: prerequisites the developer handles manually (accounts, runtimes, secrets), then concrete install / configure / run / test commands for chosen stack. -3. Write filled content to `INSTALL.md` in project root. If file exists, ask before overwriting. -4. Write project-root `README.md`: fill `@../assets/README.md`. Source every `{{...}}`: frameworks / database / test framework from block 4; `{{SRC_DIR}}` from architecture pattern's source-root convention (e.g. `src/`). Drop conditional lines (no database) per choices. Leave no raw `{{...}}`. -5. Print relative paths of written files + short summary. - -## Test - -- [ ] `INSTALL.md` exists and filled. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/09-init-env.md b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-env.md similarity index 64% rename from plugins/aidd-context/skills/01-bootstrap/actions/09-init-env.md rename to plugins/aidd-context/skills/01-bootstrap/actions/07-init-env.md index e1e9f96c..b722c133 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/09-init-env.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-env.md @@ -1,14 +1,14 @@ -# 09 - Init env +# 07 - Init env Environment and secrets. Enumerate every variable the project needs and wire config loading. No secret values committed. ## Inputs -- `INSTALL.md` - building blocks and providers that require configuration / secrets. +- The building blocks and runtime wired by `06-init-dependencies` - they determine the required env keys. ## Process -1. Derive the required env keys from `INSTALL.md` (each block's provider, the database, the runtime). +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. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md b/plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md deleted file mode 100644 index 30e4af83..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/07-init-structure.md +++ /dev/null @@ -1,20 +0,0 @@ -# 07 - Init structure - -Materialize the validated folder/route tree from `INSTALL.md` as real directories and reachable stubs. Structure only - no behavior. - -## Inputs - -- `INSTALL.md` - folder tree, architecture pattern, file conventions. - -## Process - -1. Create the directory tree exactly as `INSTALL.md` describes it. -2. For every route (front + back), create one reachable stub following the stack's conventions: 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/10-init-database.md b/plugins/aidd-context/skills/01-bootstrap/actions/08-init-database.md similarity index 62% rename from plugins/aidd-context/skills/01-bootstrap/actions/10-init-database.md rename to plugins/aidd-context/skills/01-bootstrap/actions/08-init-database.md index e2686913..b4913115 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/10-init-database.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/08-init-database.md @@ -1,15 +1,16 @@ -# 10 - Init database +# 08 - Init database -Stand up the database: connection, migration tool, a baseline migration, seed fixtures, and a proven round-trip. Conditional - skip when `INSTALL.md` declares no 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 -- `INSTALL.md` - database engine and migration tool. +- 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 `09-init-env`). -2. Set up the migration tool declared in `INSTALL.md`. +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. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/11-init-quality-gate.md b/plugins/aidd-context/skills/01-bootstrap/actions/09-init-quality-gate.md similarity index 65% rename from plugins/aidd-context/skills/01-bootstrap/actions/11-init-quality-gate.md rename to plugins/aidd-context/skills/01-bootstrap/actions/09-init-quality-gate.md index ca6ae8dc..2ff82dda 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/11-init-quality-gate.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/09-init-quality-gate.md @@ -1,16 +1,16 @@ -# 11 - Init quality gate +# 09 - Init quality gate -Wire static quality as one cohesive gate: typecheck + format + lint + commit-message linter + a pre-commit hook that runs them. Reads `INSTALL.md`; names no tool of its own. +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 -- `INSTALL.md` - language and stack (determines the concrete tools). +- 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 stack. +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 `12-init-tests` exists). +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 diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/12-init-tests.md b/plugins/aidd-context/skills/01-bootstrap/actions/10-init-tests.md similarity index 69% rename from plugins/aidd-context/skills/01-bootstrap/actions/12-init-tests.md rename to plugins/aidd-context/skills/01-bootstrap/actions/10-init-tests.md index 7ed94b8c..693ea723 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/12-init-tests.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/10-init-tests.md @@ -1,15 +1,14 @@ -# 12 - Init tests +# 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 structure (`07-init-structure`) - the code under test. -- The test framework (from `INSTALL.md`). +- 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 declared in `INSTALL.md`. +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. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/13-init-containers.md b/plugins/aidd-context/skills/01-bootstrap/actions/11-init-containers.md similarity index 51% rename from plugins/aidd-context/skills/01-bootstrap/actions/13-init-containers.md rename to plugins/aidd-context/skills/01-bootstrap/actions/11-init-containers.md index bb566b43..92e0a5c2 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/13-init-containers.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/11-init-containers.md @@ -1,14 +1,15 @@ -# 13 - Init containers +# 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 -- `INSTALL.md` - container / runtime choice and the datastores it needs. +- 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 from `INSTALL.md` (app + its datastores). +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. diff --git a/plugins/aidd-context/skills/01-bootstrap/actions/14-init-design-system.md b/plugins/aidd-context/skills/01-bootstrap/actions/12-init-design-system.md similarity index 67% rename from plugins/aidd-context/skills/01-bootstrap/actions/14-init-design-system.md rename to plugins/aidd-context/skills/01-bootstrap/actions/12-init-design-system.md index 14ac80b3..1f433fd4 100644 --- a/plugins/aidd-context/skills/01-bootstrap/actions/14-init-design-system.md +++ b/plugins/aidd-context/skills/01-bootstrap/actions/12-init-design-system.md @@ -1,10 +1,10 @@ -# 14 - Init design system +# 12 - Init design system -Establish the project's design system. Front-end only - skip when `INSTALL.md` declares no frontend. Delegates entirely; owns no design logic. +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 (from `INSTALL.md`). The design system's content comes from the design tool, not from `INSTALL.md`. +- Whether the project has a frontend (evident from the materialized project). The design system's content comes from the design tool. ## Process 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/actions/15-init-ci.md b/plugins/aidd-context/skills/01-bootstrap/actions/15-init-ci.md deleted file mode 100644 index 86d6507f..00000000 --- a/plugins/aidd-context/skills/01-bootstrap/actions/15-init-ci.md +++ /dev/null @@ -1,19 +0,0 @@ -# 15 - 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 - -- The CI platform (from `INSTALL.md` / the project's VCS docs). -- A repository with a remote, the quality gate (`11`), and the tests (`12`). - -## Process - -1. Resolve the CI platform; never assume one. -2. Emit a minimal pipeline that runs the quality gate and the tests. -3. Commit, push, and 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/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-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md index 2647ee5c..4e75310f 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/02-design.md +++ b/plugins/aidd-dev/skills/01-plan/actions/02-design.md @@ -18,9 +18,9 @@ The page, **described**: what it is, its components and their behavior, the dumb 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: - - Build the smart layer in-house per the behaviors above. - - Author each dumb component's visual by calling the design tool with quotes: `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. - - If render was requested, run under `/goal` (`aidd-dev:09-for-sure`): loop build ↔ `Use skill "impeccable" with "critique "` until **zero P0**, then explicit user OK. + - 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 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 ddf96d68..e798c7b0 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -24,7 +24,7 @@ notes: 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. **Frontend render.** If the design (`01-plan:02-design`) produced a render delegation prompt, launch the `implementer` with it as-is. That prompt carries the dumb-visual delegation and, when render was requested, the `/goal` build↔`critique` loop with its **zero P0 + explicit user OK** success condition. Don't re-specify it here; don't ship the visual on iteration count alone. +3. **Frontend render.** If the design (`01-plan:02-design`) produced a render delegation prompt, launch the `implementer` with it **as-is**. The prompt is self-contained - it names whatever design tool, verification, and loop to run, and carries its success condition. Don't inspect or re-specify its contents; just pass it through. Don't ship the visual on iteration count alone. 4. **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. 5. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. 6. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. From 086f03697e4288413289a8e97fd38b4475f46df8 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 11 Jun 2026 10:52:24 +0200 Subject: [PATCH 20/22] feat(aidd-context): add redesign-page action to design-system skill audit/critique/polish only converge: they remove defects, so a defect-free page can stay bland. The playbook has the AI invoke each Impeccable command itself, adds the divergent route (bolder/delight/overdrive/shape) next to the defect-fixing one, and gates on DESIGN.md quality since a generic system caps every command. Aligned with the official Impeccable core loop; docs links moved to impeccable.style (valid TLS). Co-Authored-By: Claude Opus 4.8 (1M context) --- .../skills/07-design-system/README.md | 9 +- .../skills/07-design-system/SKILL.md | 7 +- .../actions/01-create-design-system.md | 2 +- .../actions/02-redesign-page.md | 97 +++++++++++++++++++ 4 files changed, 108 insertions(+), 7 deletions(-) create mode 100644 plugins/aidd-context/skills/07-design-system/actions/02-redesign-page.md diff --git a/plugins/aidd-context/skills/07-design-system/README.md b/plugins/aidd-context/skills/07-design-system/README.md index 9c0cf0e2..76c332fa 100644 --- a/plugins/aidd-context/skills/07-design-system/README.md +++ b/plugins/aidd-context/skills/07-design-system/README.md @@ -1,6 +1,6 @@ # 07 - Design System -Guided onboarding for authoring a **quality design system**, wrapping the [Impeccable](https://impeccable.design) 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. +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 @@ -8,7 +8,10 @@ Guided onboarding for authoring a **quality design system**, wrapping the [Impec /aidd-context:07-design-system ``` -Manual only. One action walks the Impeccable setup runbook (`init` -> `document` -> `extract` -> refine -> `audit`/`critique`), ticking per-step checkboxes as each command produces its part. +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 @@ -16,4 +19,4 @@ The **Impeccable** skill (the playbook checks and guides install if missing). ## Not for -Authoring 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 only founds the system; Impeccable does the work and `DESIGN.md` stays canonical. +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/07-design-system/SKILL.md b/plugins/aidd-context/skills/07-design-system/SKILL.md index de2c5d36..42a9ceca 100644 --- a/plugins/aidd-context/skills/07-design-system/SKILL.md +++ b/plugins/aidd-context/skills/07-design-system/SKILL.md @@ -6,7 +6,7 @@ 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.design) 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. +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 @@ -20,9 +20,10 @@ Guided onboarding for authoring a quality design system. It does NOT generate th | # | 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 -Single action. It confirms Impeccable is available, then drives the playbook. +`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 page code is **not** this skill's concern (Knowledge layer). A page's visual is produced at implementation time, where the implementer delegates the presentational layer to Impeccable against this `DESIGN.md`. +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/07-design-system/actions/01-create-design-system.md b/plugins/aidd-context/skills/07-design-system/actions/01-create-design-system.md index 977646fc..6ab8c585 100644 --- a/plugins/aidd-context/skills/07-design-system/actions/01-create-design-system.md +++ b/plugins/aidd-context/skills/07-design-system/actions/01-create-design-system.md @@ -23,7 +23,7 @@ Run the commands in order. **Each step IS an Impeccable command**; tick its chec ### Step 0 - Ensure the engine -- [ ] `/impeccable` responds (installed). If absent, guide install (), then stop. Never emulate it. +- [ ] `/impeccable` responds (installed). If absent, guide install (), then stop. Never emulate it. ### Step 1 - `/impeccable init` diff --git a/plugins/aidd-context/skills/07-design-system/actions/02-redesign-page.md b/plugins/aidd-context/skills/07-design-system/actions/02-redesign-page.md new file mode 100644 index 00000000..b2487ffd --- /dev/null +++ b/plugins/aidd-context/skills/07-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. From 6ea47d60e6f13ac05819629d98de50df42749a8f Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 11 Jun 2026 21:04:14 +0200 Subject: [PATCH 21/22] chore(framework): drop DCO sign-off requirement Remove the DCO check (workflow + required status check in the main ruleset) and the contributor-facing references to it (CONTRIBUTING, README, PR template, MAINTAINERS). The live ruleset has been updated to match. Sign-off added friction for occasional community PRs without practical benefit for this project. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- .github/rulesets/main.json | 3 +- .github/workflows/dco.yml | 66 -------------------------------- CONTRIBUTING.md | 17 +++----- README.md | 2 +- docs/MAINTAINERS.md | 4 +- 6 files changed, 10 insertions(+), 84 deletions(-) delete mode 100644 .github/workflows/dco.yml diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index bb6c821c..4826b442 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -14,7 +14,7 @@ Walk a reviewer through the technical resolution: the approach you took, why this way over the alternatives, and anything non-obvious (trade-offs, edge cases, follow-ups). This narrative is the point of the PR. The conventional -title, DCO sign-off, and pre-commit hooks are already enforced by CI, so don't +title and pre-commit hooks are already enforced by CI, so don't re-assert them here. Spend your words on the *how*. --> diff --git a/.github/rulesets/main.json b/.github/rulesets/main.json index 5d54e7a3..6df743e1 100644 --- a/.github/rulesets/main.json +++ b/.github/rulesets/main.json @@ -29,8 +29,7 @@ "strict_required_status_checks_policy": false, "required_status_checks": [ {"context": "lefthook (framework-local checks)"}, - {"context": "Commitlint"}, - {"context": "Verify Developer Certificate of Origin sign-off"} + {"context": "Commitlint"} ] } }, diff --git a/.github/workflows/dco.yml b/.github/workflows/dco.yml deleted file mode 100644 index b99656a3..00000000 --- a/.github/workflows/dco.yml +++ /dev/null @@ -1,66 +0,0 @@ -name: DCO - -# Verifies every commit in a pull request carries a Developer Certificate of -# Origin sign-off (a `Signed-off-by:` trailer). See CONTRIBUTING.md > "Sign your -# work (DCO)". Self-contained, no third-party action. - -on: - pull_request: - types: [opened, synchronize, reopened] - -permissions: - contents: read - -jobs: - dco-check: - name: Verify Developer Certificate of Origin sign-off - runs-on: ubuntu-latest - steps: - - name: Check out full history - uses: actions/checkout@v6 - with: - fetch-depth: 0 - ref: ${{ github.event.pull_request.head.sha }} - - - name: Verify Signed-off-by on every commit - env: - BASE_SHA: ${{ github.event.pull_request.base.sha }} - HEAD_SHA: ${{ github.event.pull_request.head.sha }} - run: | - set -euo pipefail - fail=0 - commits="$(git rev-list "${BASE_SHA}..${HEAD_SHA}")" - if [ -z "${commits}" ]; then - echo "No commits to check." - exit 0 - fi - for sha in ${commits}; do - # Skip merge commits (more than one parent). - parents="$(git rev-list --parents -n 1 "${sha}" | wc -w)" - if [ "${parents}" -gt 2 ]; then - echo "skip merge commit ${sha}" - continue - fi - # Skip commits authored by a bot (release-please, dependabot, ...); - # the DCO applies to human contributions. - author_name="$(git show -s --format='%an' "${sha}")" - case "${author_name}" in - *"[bot]") echo "skip bot commit ${sha} (${author_name})"; continue ;; - esac - if git show -s --format='%B' "${sha}" | grep -qiE "^Signed-off-by: .+ <.+@.+>"; then - echo "ok ${sha}" - else - author="$(git show -s --format='%an <%ae>' "${sha}")" - echo "::error::Commit ${sha} (${author}) is missing a 'Signed-off-by' line." - fail=1 - fi - done - if [ "${fail}" -ne 0 ]; then - echo "" - echo "Sign your commits, then push again:" - echo " git commit --amend --signoff # last commit" - echo " git rebase --signoff origin/main # a whole branch" - echo "See CONTRIBUTING.md > 'Sign your work (DCO)'." - exit 1 - fi - echo "All commits signed off." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e43b2d75..11b426ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ flowchart TD Who{"Your profile?"} Pub["Public - discuss, react, upvote"] Core["Core Team - vote on roadmap priority"] - Cert["Certifie AIDD - branch, commit (DCO), open PR"] + Cert["Certifie AIDD - branch, commit, open PR"] Rev["Habilite AIDD - review (CODEOWNERS)"] Merge["Habilite AIDD - merge, release-please ships"] @@ -57,10 +57,10 @@ make reload # all plugins; or PLUGIN="aidd-refine aidd-pm ## 2. Commit -Format: `(): description`, **signed off** for the [DCO](https://developercertificate.org/). +Format: `(): description`. ```bash -git commit -s -m "feat(aidd-dev): add for-sure skill" +git commit -m "feat(aidd-dev): add for-sure skill" ``` **Scope** - one per commit (split cross-plugin changes): @@ -76,19 +76,12 @@ git commit -s -m "feat(aidd-dev): add for-sure skill" - `feat` → minor · `fix` / `perf` → patch · `!` or `BREAKING CHANGE:` → major - `docs` / `refactor` / `style` / `test` / `build` / `ci` / `chore` → no release -**DCO** - `-s` adds the `Signed-off-by` trailer. Forgot one? - -```bash -git commit --amend --signoff # last commit -git rebase --signoff origin/main # whole branch -``` - -The [`DCO`](./.github/workflows/dco.yml) check fails any unsigned commit. Versioning and the release bundles are automated - see [Releases](#releases). +Versioning and the release bundles are automated - see [Releases](#releases). ## 3. Open a pull request - Work on a branch, not `main`. -- **Fill the PR template** (applied automatically): explain *what* changed and *how* you resolved it technically - that narrative is the point of the PR. The conventional title, DCO sign-off, and pre-commit hooks are already enforced by CI, so don't spend the description re-asserting them. +- **Fill the PR template** (applied automatically): explain *what* changed and *how* you resolved it technically - that narrative is the point of the PR. The conventional title and pre-commit hooks are already enforced by CI, so don't spend the description re-asserting them. - **Label the PR** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance: | Label | When to use | diff --git a/README.md b/README.md index 901c10ea..25b8b3e8 100644 --- a/README.md +++ b/README.md @@ -295,7 +295,7 @@ Install issues, load problems, and the framework's current limits → [`docs/TRO ## Contributing -Everyone can shape this project. **Anyone** can open issues, react, and upvote ideas in [Discussions](https://github.com/ai-driven-dev/aidd-framework/discussions) (a signal); a counted roadmap vote is a benefit of **Core Team** membership in the [AIDD](https://www.ai-driven-dev.fr/) programme (training/community/coaching) and up, and **pull-request rights** are held by [Certifié and Habilité contributors](./GOVERNANCE.md#roles) so the standard stays consistent. Contributions are made under the [DCO](./CONTRIBUTING.md#2-commit) (sign off with `git commit -s`). See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the contribution flow, the commit scope discipline, and the templates each surface (skill, agent, rule, command) follows, and [`GOVERNANCE.md`](./GOVERNANCE.md) for the roles and how decisions get made. +Everyone can shape this project. **Anyone** can open issues, react, and upvote ideas in [Discussions](https://github.com/ai-driven-dev/aidd-framework/discussions) (a signal); a counted roadmap vote is a benefit of **Core Team** membership in the [AIDD](https://www.ai-driven-dev.fr/) programme (training/community/coaching) and up, and **pull-request rights** are held by [Certifié and Habilité contributors](./GOVERNANCE.md#roles) so the standard stays consistent. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the contribution flow, the commit scope discipline, and the templates each surface (skill, agent, rule, command) follows, and [`GOVERNANCE.md`](./GOVERNANCE.md) for the roles and how decisions get made. To build and ship a brand-new plugin through this marketplace, see [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md). diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index 0336b457..406c7998 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -17,7 +17,7 @@ How to operate this repository day to day. For **who** may do what and the decis - **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority` / `Work Type`; link under an epic (native sub-issues) if relevant. - **Roadmap.** Priority is set by the community vote (mechanism in `GOVERNANCE.md`). Accepted items live on board #8 - keep `ROADMAP.md` as a pointer, do not maintain a second list. -- **Review PRs.** Every PR needs a Habilité (CODEOWNERS) approval; checks `lefthook`, `Commitlint`, `DCO` must pass; squash-merge. +- **Review PRs.** Every PR needs a Habilité (CODEOWNERS) approval; checks `lefthook`, `Commitlint` must pass; squash-merge. ## Releases @@ -38,7 +38,7 @@ Versions live in `.release-please-manifest.json`. Forcing a version / pre-releas ## Branch protection & the bot bypass -`main` accepts only PRs (no direct push, no force-push, no deletion) with a CODEOWNERS review and passing `lefthook` / `Commitlint` / `DCO`. +`main` accepts only PRs (no direct push, no force-push, no deletion) with a CODEOWNERS review and passing `lefthook` / `Commitlint`. Two bypass actors (both `pull_request` mode, so neither can push directly to `main`): - the **aidd-bot GitHub App** (`Integration`) - release-please and the Dependabot auto-merge mint a token from it (`actions/create-github-app-token`), so their PRs trigger the required checks *and* the App merges them past the human-review rule. From 3683307f988651ce771b14bc1a01fea8b98b4bf2 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 15 Jun 2026 15:00:46 +0200 Subject: [PATCH 22/22] fix(aidd-context): align design-system skill name after 07->12 renumber Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-context/skills/12-design-system/README.md | 2 +- plugins/aidd-context/skills/12-design-system/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/12-design-system/README.md b/plugins/aidd-context/skills/12-design-system/README.md index 76c332fa..a74807f5 100644 --- a/plugins/aidd-context/skills/12-design-system/README.md +++ b/plugins/aidd-context/skills/12-design-system/README.md @@ -5,7 +5,7 @@ Guided onboarding for authoring a **quality design system**, wrapping the [Impec ## Usage ``` -/aidd-context:07-design-system +/aidd-context:12-design-system ``` Manual only. Two actions, both Impeccable runbooks with per-step checkboxes: diff --git a/plugins/aidd-context/skills/12-design-system/SKILL.md b/plugins/aidd-context/skills/12-design-system/SKILL.md index 42a9ceca..3adc4d38 100644 --- a/plugins/aidd-context/skills/12-design-system/SKILL.md +++ b/plugins/aidd-context/skills/12-design-system/SKILL.md @@ -1,5 +1,5 @@ --- -name: 07-design-system +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 ---