From a23f1441eae8a4c4825a085fe3c5fe240a431bd0 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 08:39:16 +0200 Subject: [PATCH 01/14] docs(contributing): document how to test the framework locally Signed-off-by: alexsoyes --- CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5de7ddd..67d3177 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,6 +40,43 @@ pnpm exec lefthook install 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`. +### Test your changes locally + +Before opening a PR, load your working tree into a real project and exercise the skills you touched. This repository is itself a marketplace, so you point an assistant at your local checkout instead of a published release. + +**With Claude Code (recommended)** - register the checkout as a local marketplace, then install the plugins you are working on: + +```text +/plugin marketplace add . # from the repo root; or pass an absolute path +/plugin install aidd-dev@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. + +**Pin the checkout from a personal project** - to keep one of your own projects wired to your local framework while you develop, add a `directory` marketplace in that project's `.claude/settings.local.json` (the personal, machine-local settings file, not the team-shared `settings.json`): + +```json +{ + "extraKnownMarketplaces": { + "aidd-framework": { + "source": { + "source": "directory", + "path": "/absolute/path/to/aidd-framework" + } + } + }, + "enabledPlugins": { + "aidd-context@aidd-framework": true, + "aidd-dev@aidd-framework": true, + "aidd-vcs@aidd-framework": true, + "aidd-pm@aidd-framework": true, + "aidd-refine@aidd-framework": true + } +} +``` + +Claude Code then loads the plugins straight from your working tree: edit the framework, run `/reload-plugins`, and test the result in that project. The loop is edit - reload - try, with no publish step in between. + ## 2. Commit Format: `(): description`, **signed off** for the [DCO](https://developercertificate.org/). From 182f7089a5eb2e274f524ae6a0d9cb99f98a974a Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 08:47:21 +0200 Subject: [PATCH 02/14] docs(contributing): refocus the PR template on technical resolution and document labels Signed-off-by: alexsoyes --- .github/PULL_REQUEST_TEMPLATE.md | 34 ++++++++++++++++---------------- CONTRIBUTING.md | 5 +++-- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 424873f..5874ebe 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,29 +1,29 @@ -# Summary +## 🎯 What & why - + -## Changes +## 🛠️ How it works - + -- +## 🧪 How to verify -## Test plan + - +- -- [ ] +## 🔗 Linked issue -## Related issues - - + Closes # -## Checklist +--- -- [ ] Commit messages follow the conventional format and use a scope listed in `commitlint.config.cjs`. -- [ ] Every commit is signed off (`git commit -s`) per the [DCO](../CONTRIBUTING.md#2-commit). -- [ ] Documentation updated when behaviour or contracts changed (plugin README, skill README, references). -- [ ] No cross-plugin references introduced in plugin docs. -- [ ] Pre-commit hooks pass locally (`lefthook run pre-commit`). +🏷️ **Before submitting** - add the matching label (`documentation`, `enhancement`, `bug`, `security`, ...). Canonical list: [`labels.yml`](labels.yml). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67d3177..7026d49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -110,8 +110,9 @@ The [`DCO`](./.github/workflows/dco.yml) check fails any unsigned commit. Versio ## 3. Open a pull request - Work on a branch, not `main`. -- **Fill the PR template** (applied automatically): summary, changes, test plan, and the checklist (conventional title + correct scope, DCO sign-off, docs updated). -- The PR title follows the same conventional format (a `lint-pr` check enforces it); PRs are squash-merged using that title. +- **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. +- **Add the matching label** - `documentation`, `enhancement`, `bug`, `security`, ... The canonical list is [`.github/labels.yml`](./.github/labels.yml); it doubles as the triage signal for the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). +- 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). From fe0ee92f988b098278c2c07b64af9d0cc50ae6e6 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 08:53:21 +0200 Subject: [PATCH 03/14] docs(contributing): add an at-a-glance brevity rule atop the PR template Signed-off-by: alexsoyes --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5874ebe..9343b6f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,7 @@ + + ## 🎯 What & why From 0d64a774dcf770d381c67f1f0d96ddf152ce4c25 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:00:46 +0200 Subject: [PATCH 04/14] docs(contributing): add author certification checkboxes and PR label guide Signed-off-by: alexsoyes --- .github/PULL_REQUEST_TEMPLATE.md | 8 ++++++++ CONTRIBUTING.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9343b6f..72430aa 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -28,6 +28,14 @@ re-assert them here. Spend your words on the *how*. Closes # +## ✅ I certify + + + +- [ ] Docs updated to match the new behaviour. +- [ ] I self-reviewed this PR. +- [ ] No cross-plugin references introduced. + --- 🏷️ **Before submitting** - add the matching label (`documentation`, `enhancement`, `bug`, `security`, ...). Canonical list: [`labels.yml`](labels.yml). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7026d49..1b11248 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -111,7 +111,7 @@ The [`DCO`](./.github/workflows/dco.yml) check fails any unsigned commit. Versio - 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. -- **Add the matching label** - `documentation`, `enhancement`, `bug`, `security`, ... The canonical list is [`.github/labels.yml`](./.github/labels.yml); it doubles as the triage signal for the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). +- **Add the matching label** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance: `bug` (a fix), `enhancement` (a new skill, agent, or feature), `documentation` (docs only), `security` (security-sensitive). `dependencies` / `npm` / `github-actions` / `autorelease: *` are set by automation, not by hand. Full list: [`.github/labels.yml`](./.github/labels.yml). - 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). From a1d2b64c90eb487cebddf72e040a630278e876a5 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:09:50 +0200 Subject: [PATCH 05/14] docs(contributing): add Codex local-build flow and a PR label table Signed-off-by: alexsoyes --- CONTRIBUTING.md | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b11248..381ee2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,6 +77,16 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th Claude Code then loads the plugins straight from your working tree: edit the framework, run `/reload-plugins`, and test the result in that project. The loop is edit - reload - try, with no publish step in between. +**With Codex (or another non-Claude tool)** - the framework is authored in Claude Code syntax, so Codex loads a *built* distribution, not the working tree. Build the target-native marketplace from your checkout (the `--out` must sit outside `--source`), then register it the same way the [README install table](./README.md#another-ai-tool) does for a release asset: + +```bash +# CLI version is pinned in .github/workflows/ci.yml (build-per-tool job) +npx @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out /tmp/aidd-codex +aidd marketplace add aidd-framework /tmp/aidd-codex +``` + +No live reload here - rebuild and re-add after each change; that build step is exactly what Claude Code skips by reading the source directly. Swap `--target codex` for `cursor`, `copilot`, or `opencode` to test another tool. + ## 2. Commit Format: `(): description`, **signed off** for the [DCO](https://developercertificate.org/). @@ -111,7 +121,18 @@ The [`DCO`](./.github/workflows/dco.yml) check fails any unsigned commit. Versio - 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. -- **Add the matching label** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance: `bug` (a fix), `enhancement` (a new skill, agent, or feature), `documentation` (docs only), `security` (security-sensitive). `dependencies` / `npm` / `github-actions` / `autorelease: *` are set by automation, not by hand. Full list: [`.github/labels.yml`](./.github/labels.yml). +- **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 | + | ----- | ----------- | + | `bug` | A fix for broken behaviour. | + | `enhancement` | A new skill, agent, rule, or feature. | + | `documentation` | A docs-only change (README, CONTRIBUTING, skill docs). | + | `security` | A security-sensitive change or fix. | + | `dependencies` / `npm` / `github-actions` | Dependency or workflow bumps - usually set by Dependabot, not by hand. | + | `autorelease: pending` / `autorelease: tagged` | Set by release-please; never applied by hand. | + + Canonical list: [`.github/labels.yml`](./.github/labels.yml). - 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). From f8d4eab988abc2e8c32e55a3d50809d10d43a400 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:16:25 +0200 Subject: [PATCH 06/14] docs(contributing): use native Codex CLI for the local flow and trim labels to four Signed-off-by: alexsoyes --- CONTRIBUTING.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 381ee2a..73bd508 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,15 +77,16 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th Claude Code then loads the plugins straight from your working tree: edit the framework, run `/reload-plugins`, and test the result in that project. The loop is edit - reload - try, with no publish step in between. -**With Codex (or another non-Claude tool)** - the framework is authored in Claude Code syntax, so Codex loads a *built* distribution, not the working tree. Build the target-native marketplace from your checkout (the `--out` must sit outside `--source`), then register it the same way the [README install table](./README.md#another-ai-tool) does for a release asset: +**With Codex (or another non-Claude tool)** - the framework is authored in Claude Code syntax, so Codex needs a *built* distribution with codex-native plugin internals (`.codex-plugin/`, `codex-agents/`), not the working tree. Build it from your checkout (`--out` must sit outside `--source`), register the build with Codex's own CLI, then install the plugins: ```bash # CLI version is pinned in .github/workflows/ci.yml (build-per-tool job) npx @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out /tmp/aidd-codex -aidd marketplace add aidd-framework /tmp/aidd-codex +codex plugin marketplace add /tmp/aidd-codex +codex plugin add aidd-dev@aidd-framework # repeat per plugin; check `codex plugin list` ``` -No live reload here - rebuild and re-add after each change; that build step is exactly what Claude Code skips by reading the source directly. Swap `--target codex` for `cursor`, `copilot`, or `opencode` to test another tool. +Point Codex at the build, not the repo root: the root ships Claude-format internals, so Codex would list the plugins but fail to load their agents. No live reload - rebuild, then `codex plugin marketplace upgrade`, after each change. Swap `--target codex` for `cursor`, `copilot`, or `opencode` to target another tool. ## 2. Commit @@ -129,10 +130,8 @@ The [`DCO`](./.github/workflows/dco.yml) check fails any unsigned commit. Versio | `enhancement` | A new skill, agent, rule, or feature. | | `documentation` | A docs-only change (README, CONTRIBUTING, skill docs). | | `security` | A security-sensitive change or fix. | - | `dependencies` / `npm` / `github-actions` | Dependency or workflow bumps - usually set by Dependabot, not by hand. | - | `autorelease: pending` / `autorelease: tagged` | Set by release-please; never applied by hand. | - Canonical list: [`.github/labels.yml`](./.github/labels.yml). + The rest (`dependencies`, `npm`, `github-actions`, `autorelease: *`) are applied by automation, not by hand. Canonical list: [`.github/labels.yml`](./.github/labels.yml). - 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). From d0a5d4f30e98ab77e20958edbe68978d58cd0c60 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:19:10 +0200 Subject: [PATCH 07/14] docs(contributing): install and enable every plugin in the Codex local flow Signed-off-by: alexsoyes --- CONTRIBUTING.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73bd508..b62401e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,7 +83,12 @@ Claude Code then loads the plugins straight from your working tree: edit the fra # CLI version is pinned in .github/workflows/ci.yml (build-per-tool job) npx @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out /tmp/aidd-codex codex plugin marketplace add /tmp/aidd-codex -codex plugin add aidd-dev@aidd-framework # repeat per plugin; check `codex plugin list` + +# install + enable every plugin (same set as the Claude example above) +for p in aidd-context aidd-dev aidd-vcs aidd-pm aidd-refine; do + codex plugin add "$p@aidd-framework" +done +codex plugin list # STATUS -> installed, enabled ``` Point Codex at the build, not the repo root: the root ships Claude-format internals, so Codex would list the plugins but fail to load their agents. No live reload - rebuild, then `codex plugin marketplace upgrade`, after each change. Swap `--target codex` for `cursor`, `copilot`, or `opencode` to target another tool. From 9984c5a08c014c2fabca7dd8bc9477bf84267d8c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:22:29 +0200 Subject: [PATCH 08/14] docs(contributing): start the local guide at git clone and drop the Codex plugin loop Signed-off-by: alexsoyes --- CONTRIBUTING.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b62401e..6871ee3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,12 @@ Every commit then runs the framework checks (json/yaml validity, schema validati ### Test your changes locally -Before opening a PR, load your working tree into a real project and exercise the skills you touched. This repository is itself a marketplace, so you point an assistant at your local checkout instead of a published release. +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 +cd aidd-framework +``` **With Claude Code (recommended)** - register the checkout as a local marketplace, then install the plugins you are working on: @@ -77,18 +82,13 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th Claude Code then loads the plugins straight from your working tree: edit the framework, run `/reload-plugins`, and test the result in that project. The loop is edit - reload - try, with no publish step in between. -**With Codex (or another non-Claude tool)** - the framework is authored in Claude Code syntax, so Codex needs a *built* distribution with codex-native plugin internals (`.codex-plugin/`, `codex-agents/`), not the working tree. Build it from your checkout (`--out` must sit outside `--source`), register the build with Codex's own CLI, then install the plugins: +**With Codex (or another non-Claude tool)** - the framework is authored in Claude Code syntax, so Codex needs a *built* distribution with codex-native plugin internals (`.codex-plugin/`, `codex-agents/`), not the working tree. Build it from your checkout (`--out` must sit outside `--source`), register the build with Codex's own CLI, then install the plugins you are working on: ```bash # CLI version is pinned in .github/workflows/ci.yml (build-per-tool job) npx @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out /tmp/aidd-codex codex plugin marketplace add /tmp/aidd-codex - -# install + enable every plugin (same set as the Claude example above) -for p in aidd-context aidd-dev aidd-vcs aidd-pm aidd-refine; do - codex plugin add "$p@aidd-framework" -done -codex plugin list # STATUS -> installed, enabled +codex plugin add aidd-dev@aidd-framework # check status with `codex plugin list` ``` Point Codex at the build, not the repo root: the root ships Claude-format internals, so Codex would list the plugins but fail to load their agents. No live reload - rebuild, then `codex plugin marketplace upgrade`, after each change. Swap `--target codex` for `cursor`, `copilot`, or `opencode` to target another tool. From c440ac64d9075a35686f046f53ccda25986c1d37 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:28:24 +0200 Subject: [PATCH 09/14] docs(contributing): clone-direct Codex flow, all six plugins, verify with plugin list Signed-off-by: alexsoyes --- CONTRIBUTING.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6871ee3..0753926 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,8 +52,13 @@ cd aidd-framework **With Claude Code (recommended)** - register the checkout as a local marketplace, then install the plugins you are working on: ```text -/plugin marketplace add . # from the repo root; or pass an absolute path +/plugin marketplace add . # from the repo root +/plugin install aidd-context@aidd-framework /plugin install aidd-dev@aidd-framework +/plugin install aidd-vcs@aidd-framework +/plugin install aidd-pm@aidd-framework +/plugin install aidd-orchestrator@aidd-framework +/plugin install aidd-refine@aidd-framework ``` After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in the same session to pick up the change - no reinstall needed. @@ -75,6 +80,7 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th "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 } } @@ -82,16 +88,20 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th Claude Code then loads the plugins straight from your working tree: edit the framework, run `/reload-plugins`, and test the result in that project. The loop is edit - reload - try, with no publish step in between. -**With Codex (or another non-Claude tool)** - the framework is authored in Claude Code syntax, so Codex needs a *built* distribution with codex-native plugin internals (`.codex-plugin/`, `codex-agents/`), not the working tree. Build it from your checkout (`--out` must sit outside `--source`), register the build with Codex's own CLI, then install the plugins you are working on: +**With Codex** - Codex reads the same marketplace manifest, so register the cloned checkout with Codex's own CLI (pass an absolute path; `./` is rejected), then install the plugins: ```bash -# CLI version is pinned in .github/workflows/ci.yml (build-per-tool job) -npx @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out /tmp/aidd-codex -codex plugin marketplace add /tmp/aidd-codex -codex plugin add aidd-dev@aidd-framework # check status with `codex plugin list` +codex plugin marketplace add "$(pwd)" +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` ``` -Point Codex at the build, not the repo root: the root ships Claude-format internals, so Codex would list the plugins but fail to load their agents. No live reload - rebuild, then `codex plugin marketplace upgrade`, after each change. Swap `--target codex` for `cursor`, `copilot`, or `opencode` to target another tool. +No live reload - run `codex plugin marketplace upgrade` after each change to refresh. ## 2. Commit From 33dd7f0a778832f7c0064408eb7c90ed38f3d29d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:30:29 +0200 Subject: [PATCH 10/14] docs(contributing): use ~/projects/aidd-framework as the concrete clone-and-link path Signed-off-by: alexsoyes --- CONTRIBUTING.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0753926..2afdd2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,14 +45,13 @@ Every commit then runs the framework checks (json/yaml validity, schema validati 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 -cd aidd-framework +git clone https://github.com/ai-driven-dev/aidd-framework ~/projects/aidd-framework ``` **With Claude Code (recommended)** - register the checkout as a local marketplace, then install the plugins you are working on: ```text -/plugin marketplace add . # from the repo root +/plugin marketplace add ~/projects/aidd-framework /plugin install aidd-context@aidd-framework /plugin install aidd-dev@aidd-framework /plugin install aidd-vcs@aidd-framework @@ -71,7 +70,7 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th "aidd-framework": { "source": { "source": "directory", - "path": "/absolute/path/to/aidd-framework" + "path": "~/projects/aidd-framework" } } }, @@ -91,7 +90,7 @@ Claude Code then loads the plugins straight from your working tree: edit the fra **With Codex** - Codex reads the same marketplace manifest, so register the cloned checkout with Codex's own CLI (pass an absolute path; `./` is rejected), then install the plugins: ```bash -codex plugin marketplace add "$(pwd)" +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 From 4ae36de71308280714a6393559bc3dc2d997ea2e Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:44:41 +0200 Subject: [PATCH 11/14] docs(contributing): drop the automation-label filler under the label table Signed-off-by: alexsoyes --- CONTRIBUTING.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2afdd2c..4088969 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -144,8 +144,6 @@ The [`DCO`](./.github/workflows/dco.yml) check fails any unsigned commit. Versio | `enhancement` | A new skill, agent, rule, or feature. | | `documentation` | A docs-only change (README, CONTRIBUTING, skill docs). | | `security` | A security-sensitive change or fix. | - - The rest (`dependencies`, `npm`, `github-actions`, `autorelease: *`) are applied by automation, not by hand. Canonical list: [`.github/labels.yml`](./.github/labels.yml). - 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). From eeabd0122e7656625d5587f4564911cf5c4f041c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:45:30 +0200 Subject: [PATCH 12/14] docs(contributing): add an optional Heads-up section to the PR template Signed-off-by: alexsoyes --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 72430aa..ee34279 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -22,6 +22,10 @@ re-assert them here. Spend your words on the *how*. - +## ⚠️ Heads-up + + + ## 🔗 Linked issue From 274a058b046e58b39bb72287b217dc666c6a49dc Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:48:55 +0200 Subject: [PATCH 13/14] docs(contributing): require file references to be markdown links with line numbers Signed-off-by: alexsoyes --- .github/PULL_REQUEST_TEMPLATE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ee34279..f2104d3 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,7 @@ ## 🎯 What & why From d4ce2349b3b941a6af9b3912b225b8b620fd1ebb Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 6 Jun 2026 09:58:50 +0200 Subject: [PATCH 14/14] docs(contributing): markdown subheadings for Claude/Codex, drop label footer from template Signed-off-by: alexsoyes --- .github/PULL_REQUEST_TEMPLATE.md | 4 ---- CONTRIBUTING.md | 10 ++++++---- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f2104d3..51573a6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -41,7 +41,3 @@ Closes # - [ ] Docs updated to match the new behaviour. - [ ] I self-reviewed this PR. - [ ] No cross-plugin references introduced. - ---- - -🏷️ **Before submitting** - add the matching label (`documentation`, `enhancement`, `bug`, `security`, ...). Canonical list: [`labels.yml`](labels.yml). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4088969..f42446c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,9 @@ Before opening a PR, exercise the skills you touched in a real session. Clone th git clone https://github.com/ai-driven-dev/aidd-framework ~/projects/aidd-framework ``` -**With Claude Code (recommended)** - register the checkout as a local marketplace, then install the plugins you are working on: +#### Claude Code + +Register the checkout as a local marketplace, then install the plugins: ```text /plugin marketplace add ~/projects/aidd-framework @@ -62,7 +64,7 @@ git clone https://github.com/ai-driven-dev/aidd-framework ~/projects/aidd-framew 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. -**Pin the checkout from a personal project** - to keep one of your own projects wired to your local framework while you develop, add a `directory` marketplace in that project's `.claude/settings.local.json` (the personal, machine-local settings file, not the team-shared `settings.json`): +To load the plugins into a personal project, point its `.claude/settings.local.json` at the checkout: ```json { @@ -85,9 +87,9 @@ After editing a `SKILL.md`, an agent, or any action, run `/reload-plugins` in th } ``` -Claude Code then loads the plugins straight from your working tree: edit the framework, run `/reload-plugins`, and test the result in that project. The loop is edit - reload - try, with no publish step in between. +#### Codex -**With Codex** - Codex reads the same marketplace manifest, so register the cloned checkout with Codex's own CLI (pass an absolute path; `./` is rejected), then install the plugins: +Register the checkout (pass an absolute path; `./` is rejected), then install the plugins: ```bash codex plugin marketplace add ~/projects/aidd-framework