docs(contributing): local testing guide, PR template overhaul, and label guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,29 +1,43 @@
-# Summary
+<!--
+🤖 RULES (filling this template):
+1. Less is more. Reviewers scan hundreds of PRs - keep every section short, concrete, skimmable. Cut anything readable from the diff or CI. Delete any section that adds nothing.
+2. Point to a file with a real markdown link and its line number, GitHub-style: [README.md:119](README.md#L119).
+-->
 
-<!-- One or two sentences describing the change and why it matters. -->
+## 🎯 What & why
 
-## Changes
+<!-- One or two sentences: what this changes and the problem it solves. -->
 
-<!-- Bullet list of the concrete edits. Group by plugin or area when relevant. -->
+## 🛠️ How it works
 
-- 
+<!--
+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
+re-assert them here. Spend your words on the *how*.
+-->
 
-## Test plan
+## 🧪 How to verify
 
-<!-- How you verified this change. Commands, screenshots, manual steps. -->
+<!-- Concrete steps, commands, or screenshots a reviewer can run to see it work. -->
 
-- [ ] 
+-
 
-## Related issues
+## ⚠️ Heads-up
 
-<!-- "Closes #N" auto-links and closes the issue on merge. Use "Refs #N" for related-but-not-closing links. -->
+<!-- Deferred work, known gaps, or anything a reviewer should track. Delete if none. -->
+
+## 🔗 Linked issue
+
+<!-- "Closes #N" auto-closes the issue on merge; "Refs #N" links without closing. Delete this whole section if there is no issue. -->
 
 Closes #
 
-## Checklist
+## ✅ I certify
+
+<!-- The author ticks these on GitHub before merge. Not for the AI to fill or delete - these are the checks no CI job can make. -->
 
-- [ ] 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`).
+- [ ] Docs updated to match the new behaviour.
+- [ ] I self-reviewed this PR.
+- [ ] No cross-plugin references introduced.

CONTRIBUTING.md

@@ -40,6 +40,70 @@ 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, 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 a `SKILL.md`, an agent, or any action, run `/reload-plugins` in the same session to pick up the change - no reinstall needed.
+
+To load the plugins into a personal project, point its `.claude/settings.local.json` at the checkout:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "aidd-framework": {
+      "source": {
+        "source": "directory",
+        "path": "~/projects/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
+
+Register the checkout (pass an absolute path; `./` is rejected), then install the plugins:
+
+```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`
+```
+
+No live reload - run `codex plugin marketplace upgrade` after each change to refresh.
+
 ## 2. Commit
 
 Format: `<type>(<scope>): description`, **signed off** for the [DCO](https://developercertificate.org/).
@@ -73,8 +137,16 @@ 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.
+- **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. |
+- 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).