ai-driven-dev · blafourcade · Jul 7, 2026 · Jul 5, 2026 · Jul 5, 2026 · Jul 5, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md
+
+> On the first message of a conversation, tell the user: "AI-Driven Development ON - Date: {current_date}, TZ: {current_timezone}."
+
+## Behavior
+
+- **Stay critical.** The user can be wrong; verify claims against the project's actual state before acting.
+- **Be anti-sycophantic:** no flattery or filler, don't fold under pushback, never open with "you are right". Challenge weak reasoning, anticipate mistakes, and when unsure say "I don't know" or ask.
+- **Surface tradeoffs and evaluate their impact** instead of hiding them.
+
+## Communication
+
+- **Answer first:** result before reason. Drop pleasantries (sure, of course, happy to) and hedging.
+- **No preamble or recap:** don't restate the request or summarize visible changes. Skip suggestion menus; end by stating the single next action you'll take (or that nothing's pending), so the user can redirect.
+- **Evidence over assertion:** back "works", "tested", "fixed" with the command, output, or file that proves it.
+- **Quote the shortest decisive line** of an error or log, not the whole dump.
+- **No tool-call narration.** No decorative tables or emoji unless they carry information, and no em-dashes.
+- **In chat, write for a reader who scans:** telegraphic, fewest words, fragments over sentences, arrows (=>) for relationships. Cut any word that doesn't change meaning. Normal prose in authored docs and code. Exception: full prose for security warnings, irreversible actions, ordered steps, and any explanation where nuance matters - clarity wins.
+
+## Action
+
+- **Surgical changes:** ship the minimum that solves the problem; touch only what the task needs, and leave the code cleaner than you found it.
+- **Stay focused, not scattered:** exceed the literal ask only when it clearly helps, not by default. When you spot an unrelated issue, note it in one line and keep going; detour only if it blocks the task.
+- **Solve your own issues first:** genuinely try to resolve it yourself before escalating to the human.
+- **Do not commit or push** unless the user asks.
+- **Don't assume your knowledge is current.**
+- **Placement discipline:** for every plugin change, think hard about where responsibility belongs; follow `docs/ARCHITECTURE.md`.
+- **Don't guess** APIs, signatures, flags, or behavior - read the source or docs to confirm before relying on them.
+- **Ambiguous or expensive task:** ask one sharp question to pin down scope before building, rather than guess.
+- **Batch independent operations** in one pass, not one at a time.
+- **Fan out** independent subtasks to parallel subagents when you own the overall flow and the work is genuinely parallel.
+- **Before adding any instruction, finding, or rule, check whether an existing one already covers or contradicts it.** If so, don't add a parallel: delete it, merge it into the stronger one, or rewrite with explicit scope and priority.
+- **Name by intention, not mechanism:** describe the goal or responsibility, not the tool or file format.
+
+## Memory Management
+
+Project docs, memory, specs, and plans live in `aidd_docs/`.
+
+### Project memory
+
+<aidd_project_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
+</aidd_project_memory>
+
+- If the block above is empty, run `ls -1tr aidd_docs/memory/` and read each file.
+- Load `aidd_docs/memory/external/*` when the user asks.
+- Load `aidd_docs/memory/internal/*` when the task needs it.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,110 +1,61 @@
 # Contributing to the AIDD Framework
 
-The source of truth for AIDD skills, agents, rules, and templates. Authored in Claude Code syntax; at release time the CLI generates archives adapted to each supported tool.
-
-> Wider AIDD community, roles, and the training programme live at [ai-driven-dev.fr](https://www.ai-driven-dev.fr/). This file covers contributing to **this repository**.
-
-## Who does what (by profile)
+Source of truth for AIDD skills, agents, rules, and templates — authored in Claude Code syntax; the CLI adapts an archive per tool at release. This file covers contributing to **this repository**; the wider community, roles, and training programme live at [ai-driven-dev.fr](https://www.ai-driven-dev.fr/).
 
 ```mermaid
----
-title: Contribution by profile
----
-flowchart TD
-    Start["Anyone: open an issue, idea or question"]
-    Who{"Your profile?"}
-    Pub["Public - discuss, react, upvote"]
-    Core["Core Team - vote on roadmap priority"]
-    Cert["Certifie AIDD - branch, commit, open PR"]
-    Rev["Habilite AIDD - review (CODEOWNERS)"]
-    Merge["Habilite AIDD - merge, release-please ships"]
-
-    Start --> Who
-    Who -->|Public| Pub
-    Who -->|Core Team| Core
-    Who -->|Certifie| Cert
-    Cert --> Rev
-    Rev --> Merge
+flowchart LR
+    Issue["💡 Issue / idea"] --> Branch["🌿 Branch off next"] --> PR["🔀 Open PR"] --> Review["🛡️ Habilité review"] --> Merge["✅ Squash-merge → next"] --> Release["🚀 Weekly promote → release-please ships"]
 ```
 
-**Pull-request rights are held by Certifié and Habilité only** (Certifié via [certification](https://www.ai-driven-dev.fr/), Habilité by promotion). Full role ladder, voting weights, and promotion: [`GOVERNANCE.md`](./GOVERNANCE.md#roles). The rest of this guide is the *how* for those opening PRs.
-
-## 1. Set up
+## 👥 Who can contribute
 
-Needs **Node 20+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional). Then:
+Roles and their rights are defined in [`GOVERNANCE.md`](./GOVERNANCE.md#-roles). Where each starts:
 
-```bash
-make setup
-```
-
-- 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)
+| Role | Start here |
+| --- | --- |
+| 👤 **Public** | [Open an issue](https://github.com/ai-driven-dev/framework/issues) or [discussion](https://github.com/ai-driven-dev/framework/discussions) |
+| 🗳️ **Core Team** | Vote on roadmap priority |
+| 🌱 **Certifié** | Open a pull request → [Set up](#-1-set-up) |
+| 🛡️ **Habilité** | Review and merge |
 
-`make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks.
+The rest of this guide is the *how* for those opening PRs.
 
-### Markdown links
+## 🔧 1. Set up
 
-Lefthook runs the Markdown link checker during pre-commit. `make setup` installs the hooks; if dependencies are already installed and you only need the hook wiring, run:
+Requires **Node 22.12+**, **pnpm**, **jq**, **python3**, and **pipx** (`gh` and the Claude/Codex CLI optional).
 
 ```bash
-pnpm exec lefthook install --force
+make setup   # deps + git hooks, registers a local marketplace, installs plugins into Claude + Codex
 ```
 
-Run `node scripts/check-markdown-links.js` to scan the repository. Detailed usage, supported forms, exclusions, and fix guidance live in `node scripts/check-markdown-links.js --help`.
-
-### Test your changes locally
-
-Exercise the skills you touched before opening a PR. Neither tool hot-reloads the checkout (both serve a copied cache), so after editing:
-
-```bash
-make reload                        # all plugins; or PLUGIN="aidd-refine aidd-pm" for a subset
-```
-
-- reinstalls each plugin from the checkout (current versions, no bump - nothing to revert)
-- Claude installs straight from the raw repo (already native Claude format); Codex installs from a tree the `aidd` CLI builds (Claude syntax -> Codex, e.g. agents -> TOML)
-- refreshes the cache in Claude + Codex; Codex agents are copied to `~/.codex/agents/` (Codex does not load plugin-bundled agents yet)
-- restart the session to load it (`/reload-plugins` covers a Claude-only edit to an existing skill)
-
-## 2. Commit
-
-Format: `<type>(<scope>): description`.
-
-```bash
-git commit -m "feat(aidd-dev): add for-sure skill"
-```
+`make` lists every target; `make doctor` and `make check` verify the environment and run the pre-commit checks (including the Markdown link checker).
 
-One scope per commit (split cross-plugin changes). The types, the scopes, and the rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) - it mirrors `commitlint.config.cjs`, the source of truth. **Type** drives the release; see [`RELEASE.md`](./RELEASE.md) for what each type produces.
+## ✏️ 2. Make your change
 
-## 3. Open a pull request
+- **Test locally** — neither tool hot-reloads the checkout (both serve a cached copy). After editing, run `make reload` (or `PLUGIN="aidd-refine aidd-pm"` for a subset), then restart the session — `/reload-plugins` covers a Claude-only edit to an existing skill.
+- **Commit** — `<type>(<scope>): description`, one scope per commit (split cross-plugin changes). The types, scopes, and rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) (mirrors `commitlint.config.cjs`); the **type** drives the release → [`RELEASE.md`](./RELEASE.md).
 
-- Branch off `next` and target `next` (the integration branch); only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target — the full prefix → label → target table is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types).
-- **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. The triage label follows your branch kind and the PR skill applies it automatically; the label per kind is in that same [routing table](aidd_docs/memory/vcs.md#types) (`security` is cross-cutting — add it to any kind).
-- The PR title follows the same conventional format (the **Commitlint** CI job enforces it); PRs are squash-merged using that title.
-- A **Habilité** review gates every merge ([`CODEOWNERS`](./.github/CODEOWNERS)); Certifié contributors cannot self-merge.
-- Decision rules (lazy consensus, explicit consensus for cross-plugin/contract changes, the quality veto) live in [`GOVERNANCE.md`](./GOVERNANCE.md#code-decisions-merging).
+## 🔀 3. Open a pull request
 
-## Releases
+- **Branch off `next`, target `next`** — only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target → [routing table](aidd_docs/memory/vcs.md#types).
+- **Fill the PR template** — explain *what* changed and *how* you solved it; skip re-asserting the conventional title and hooks (CI already enforces them).
+- **Label** follows your branch kind (the PR skill applies it automatically); add `security` when relevant.
+- **A Habilité review gates every merge** ([`CODEOWNERS`](./.github/CODEOWNERS)) — Certifié contributors cannot self-merge. PRs squash-merge on the conventional title. Decision rules → [`GOVERNANCE.md`](./GOVERNANCE.md#-code-decisions-merging).
 
-How releases flow (the `main`/`next` model, weekly cadence, hotfix, auto-merge) is in [`RELEASE.md`](./RELEASE.md); the release tooling is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md). What a release produces, for contributors:
+## 🚀 Releases
 
-- **7 independently-versioned packages** (root `aidd-framework` + the 6 plugins).
-- On release, CI attaches the bundles:
-  - `aidd-framework-marketplace-X.Y.Z.zip` - the Claude Code marketplace (`.claude-plugin/` + `plugins/`); kept as the legacy Claude alias of `aidd-framework-claude-marketplace-X.Y.Z.zip`.
-  - `<plugin>-vX.Y.Z.zip` - per released plugin.
-  - `aidd-framework-<tool>-<mode>-X.Y.Z.zip` - **per-tool distributions** built by `aidd-cli` (`framework build`) on the root release: 4 marketplace (claude/cursor/copilot/codex) + 5 flat (+opencode, flat-only) = 9 archives. Produced by the `build-per-tool` matrix job in `.github/workflows/ci.yml`, pinned to a specific `@ai-driven-dev/cli` version.
+The `main`/`next` model, weekly cadence, and hotfix flow → [`RELEASE.md`](./RELEASE.md). A release ships **8 independently-versioned packages** (root `aidd-framework` + the 7 plugins; `aidd-ui` is alpha) plus per-tool archives; full breakdown → [`MAINTAINERS.md`](docs/MAINTAINERS.md#-releases).
 
-## Reporting issues
+## 🐛 Reporting issues
 
-[Open an issue](https://github.com/ai-driven-dev/framework/issues/new/choose) (🐛 Bug or ✨ Feature). New issues are auto-added to the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). For **usage questions**, use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)).
+[Open an issue](https://github.com/ai-driven-dev/framework/issues/new/choose) (🐛 Bug or ✨ Feature) — auto-added to the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). For usage questions use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)).
 
-## Reference
+## 📚 Reference
 
-- **Build a plugin** - [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md)
-- **Architecture & terms** - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/GLOSSARY.md`](docs/GLOSSARY.md)
-- **Patterns to follow**: a minimal plugin [`aidd-refine`](plugins/aidd-refine/), a router skill [`00-onboard`](plugins/aidd-context/skills/00-onboard/), agents [`aidd-dev/agents`](plugins/aidd-dev/agents/).
-- **Syntax & per-tool builds**: source files use Claude Code syntax; at release time the `aidd-cli` generates an archive per supported tool, mapping each surface to that tool's equivalent. In frontmatter, `name` / `description` / `argument-hint` are universal; other keys (`model`, `color`, `paths`, …) are tool-specific and ignored where unsupported.
+- **Build a plugin** → [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md)
+- **Architecture & terms** → [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/GLOSSARY.md`](docs/GLOSSARY.md)
+- **Patterns to follow** → a minimal plugin [`aidd-refine`](plugins/aidd-refine/), a router skill [`00-onboard`](plugins/aidd-context/skills/00-onboard/), agents [`aidd-dev/agents`](plugins/aidd-dev/agents/)
+- **Per-tool builds** → source files use Claude Code syntax; the `aidd-cli` maps each surface to its per-tool equivalent at release. `name` / `description` / `argument-hint` are universal; other frontmatter keys (`model`, `color`, `paths`, …) are tool-specific and ignored where unsupported.
 
 ---
 

diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -18,7 +18,7 @@ flowchart LR
     Certifie -- promoted --> Habilite
 ```
 
-## Roles
+## 👥 Roles
 
 | Tier | How you get there | Adds (on top of the rung below) | Team |
 | ---- | ----------------- | ------------------------------- | ---- |
@@ -30,7 +30,7 @@ flowchart LR
 **Plugin owners** are Habilité scoped to one plugin (`aidd-context`, `aidd-dev`,
 …): they merge and triage for that plugin only.
 
-## Roadmap voting
+## 📊 Roadmap voting
 
 - **Public** reacts (👍 / upvote). This is a **signal**, not a counted vote; it
   promotes an item to a formal vote.
@@ -41,18 +41,14 @@ flowchart LR
 - A poll runs **≥ 7 days**. Accepted items land on the
   [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8).
 
-## Code decisions (merging)
+## ✅ Code decisions (merging)
 
-Merge authority is **Habilité only**. Default is **lazy consensus**: a Habilité
-may merge if no other Habilité objects within 72h, there is ≥1 Habilité approval,
-and CI passes. Any Habilité can block with a `request-changes` review (the
-**quality veto**) until resolved.
+- Merge authority is **Habilité only**.
+- **Lazy consensus** (default): a Habilité may merge if no other Habilité objects within 72h, there is ≥1 Habilité approval, and CI passes.
+- **Quality veto**: any Habilité can block with a `request-changes` review until resolved.
+- **Explicit consensus** — for cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`), or licensing/governance changes: ≥2 Habilité approve, none object.
 
-Cross-plugin changes, contract changes (skill frontmatter, `marketplace.json`),
-or licensing/governance changes need **explicit consensus**: ≥2 Habilité approve,
-none object.
-
-## Promotion and inactivity
+## 📈 Promotion and inactivity
 
 - **→ Certifié**: pass the AIDD certification → added to `certified`.
 - **→ Habilité**: a Habilité nominates a Certifié with a track record of merged,
@@ -61,7 +57,7 @@ none object.
 - A Core Team / Habilité member inactive **6 months** may be moved to **emeritus**
   by a Habilité majority (keeps recognition, loses vote/merge until they return).
 
-## Plugins, breaking changes, conflicts
+## 🧩 Plugins, breaking changes, conflicts
 
 - **New plugin**: lands via PR following [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md)
   (description on every skill, registered in
@@ -76,21 +72,12 @@ none object.
 - **Conflict of interest**: a Habilité with a stake in a PR discloses it and is
   not the sole approver (a second Habilité approval becomes mandatory).
 
-## Branch protection on `main` and `next`
-
-`main` is production: no direct push, no force-push, no deletion; every change is
-a PR with ≥1 Habilité (CODEOWNERS) approval, passing checks (`lefthook
-(framework-local checks)`, `Commitlint`), and resolved threads. Machine-readable
-form: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once
-the repo is public / on a paid plan).
+## 🔒 Branch protection on `main` and `next`
 
-`next` is the integration branch: PRs with ≥1 review and passing checks, no
-direct push or deletion. The release bot bypasses to push the automated
-back-merge, and the `admin` team may merge without a second review. Machine-readable form:
-[`.github/rulesets/next.json`](.github/rulesets/next.json). The release flow is in
-[`RELEASE.md`](RELEASE.md).
+- **`main`** (production): no direct push, force-push, or deletion. Every change is a PR with ≥1 Habilité (CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`, `Commitlint`), and resolved threads. Rules: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo is public / on a paid plan).
+- **`next`** (integration): PRs with ≥1 review and passing checks, no direct push or deletion. The release bot bypasses to push the automated back-merge; the `admin` team may merge without a second review. Rules: [`.github/rulesets/next.json`](.github/rulesets/next.json). Release flow: [`RELEASE.md`](RELEASE.md).
 
-## Code of Conduct & amendments
+## 📜 Code of Conduct & amendments
 
-All interactions follow the [Code of Conduct](./CODE_OF_CONDUCT.md). Changes to
-this document follow the explicit-consensus rule above.
+- All interactions follow the [Code of Conduct](./CODE_OF_CONDUCT.md).
+- Changes to this document follow the explicit-consensus rule above.