docs(framework): add GOVERNANCE, ROADMAP, and skills.json aggregator

Wave 2 of the audit response. Adds the three highest-impact OSS surfaces
the multi-agent audit flagged as missing:

- GOVERNANCE.md: documents the lazy-consensus / explicit-consensus
  rules, how a plugin is added, deprecated, or removed, the breaking-
  change policy (including prompt-only breaking changes), and the
  conflict-of-interest convention.
- ROADMAP.md: public direction split into Now / Next / Later / Done
  with a closing 'How to influence' block pointing at issues, Discord,
  and sponsorship. Intent, not commitments; reality stays in CHANGELOG.
- skills.json: repo-root machine-readable aggregator listing all 31
  skills across the 6 plugins (id, description, path, evals_count) so
  third-party indexes can consume the marketplace without scraping
  per-plugin SKILL.md frontmatter.

The root README Documentation table now links the three new surfaces
alongside the existing docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: blafourcade

GOVERNANCE.md

@@ -0,0 +1,56 @@
+# Governance
+
+How decisions get made in the AI-Driven Dev Framework.
+
+## Project structure
+
+- **Maintainers**: a small group with merge rights on `main`. Listed in [`.github/CODEOWNERS`](./.github/CODEOWNERS) and on the GitHub organisation page.
+- **Plugin owners**: maintainers responsible for the day-to-day of a specific plugin (`aidd-context`, `aidd-dev`, etc.). They merge per-plugin PRs and triage per-plugin issues.
+- **Contributors**: anyone who opens a PR or issue. The contribution flow is documented in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+- **Community**: the wider AIDD community on Discord, YouTube, and LinkedIn. Sets direction by feedback, votes on roadmap items, and proposes new use cases.
+
+## How decisions are made
+
+The default is **lazy consensus**. Any maintainer can move forward on a PR if:
+
+1. No other maintainer has expressed an objection within 72 hours.
+2. The PR has at least one approval from a maintainer (or from a plugin owner for plugin-scoped changes).
+3. The PR passes CI and lefthook checks.
+
+Anyone can pause a PR by leaving a `request-changes` review or a `block` comment explaining the concern. The PR cannot merge until the concern is resolved.
+
+For changes that affect more than one plugin, the contract surface (skill frontmatter, marketplace.json schema), or the project's licensing / governance, lazy consensus is replaced with **explicit consensus**: at least two maintainers approve, no maintainer objects.
+
+## Adding a new plugin
+
+A new plugin lands through a regular pull request that:
+
+1. Follows the layout described in [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md).
+2. Includes a `description` frontmatter on every skill clear enough that a Claude session can discover it from intent alone.
+3. Declares at least one `evals/scenarios.json` fixture per skill.
+4. Adds the plugin entry to `.claude-plugin/marketplace.json` and registers it in `release-please-config.json`.
+5. Has a plugin owner ready to take ongoing responsibility for issues and PRs against the plugin.
+
+A new plugin starts at `status: experimental`. It moves to `release candidate` once at least one external user has installed and reported a successful run, and to `stable` after a maintainer review of the eval coverage and the documentation.
+
+## Removing or deprecating a plugin
+
+A plugin can be deprecated by any maintainer with a one-paragraph rationale and at least one alternative path (a sibling plugin, an external project) for users to migrate to. Deprecation moves the plugin to `status: deprecated` in the README table and adds a banner in the plugin's own README. After 90 days the plugin can be removed entirely; until then it stays installable.
+
+## Breaking changes
+
+Breaking changes follow Conventional Commits with the `!` suffix (`feat!:`, `refactor!:`, etc.). Major bumps trigger an automatic release-please PR. The release notes must document the migration path for any user-visible contract (skill name, manifest field, public env variable).
+
+Prompt-only changes that alter how a skill behaves without changing its name or inputs still constitute breaking changes from the user's perspective. They should be flagged in the PR description and announced on Discord before merge.
+
+## Conflicts of interest
+
+A maintainer or plugin owner with a direct stake in a PR (e.g. their employer or a paid integration) should disclose it in the PR description and abstain from being the sole approver. The lazy-consensus window stays the same, but a second maintainer approval becomes mandatory.
+
+## Code of Conduct
+
+All decisions and interactions are bound by the [Code of Conduct](./CODE_OF_CONDUCT.md). Enforcement contacts are listed there.
+
+## Amendments
+
+This document is itself versioned. Changes to governance follow the same explicit-consensus rule above.

README.md

@@ -136,10 +136,13 @@ If you spot a vulnerability, please report it privately via [SECURITY.md](./SECU
 | -------- | ----- |
 | Architecture overview | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
 | Skills catalog (all plugins) | [`docs/CATALOG.md`](docs/CATALOG.md) |
+| Skills aggregator (JSON) | [`skills.json`](skills.json) |
 | Glossary | [`docs/GLOSSARY.md`](docs/GLOSSARY.md) |
 | Build your own plugin | [`docs/CREATE_PLUGIN.md`](docs/CREATE_PLUGIN.md) |
 | Frequently asked questions | [`docs/FAQ.md`](docs/FAQ.md) |
 | Contribution guide | [`CONTRIBUTING.md`](./CONTRIBUTING.md) |
+| Governance | [`GOVERNANCE.md`](./GOVERNANCE.md) |
+| Roadmap | [`ROADMAP.md`](./ROADMAP.md) |
 | Code of Conduct | [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) |
 | Security policy | [`SECURITY.md`](./SECURITY.md) |
 | Changelog | [`CHANGELOG.md`](./CHANGELOG.md) (see also [GitHub Releases](https://github.com/ai-driven-dev/aidd-framework/releases)) |

ROADMAP.md

@@ -0,0 +1,39 @@
+# Roadmap
+
+Public direction for the AI-Driven Dev Framework. Items here are intent, not commitments; reality is set by what ships in `CHANGELOG.md`.
+
+## Now (in progress)
+
+- **`aidd-orchestrator` use case maturity.** `async-dev` is stable; the next two use cases on the orchestrator roadmap are `agentic-orchestration` (multi-agent hand-offs) and `flow-orchestration` (branching pipelines with human gates).
+- **Schema-validated CI.** `lefthook` already validates marketplace, plugin, and settings JSON locally; lifting the same check into a GitHub Actions workflow so external contributors get the same gate without installing pipx.
+- **Per-plugin release tagging.** `release-please` configured for `aidd-context`, `aidd-dev`, `aidd-vcs`, `aidd-pm`, `aidd-orchestrator`, `aidd-refine`. Tag format: `aidd-<plugin>-vX.Y.Z`.
+
+## Next (planned)
+
+- **Skill frontmatter extensions.** Standardise optional `model:`, `effort:`, and `allowed-tools:` keys per skill so cost and safety surfaces become machine-parseable.
+- **`skills.json` aggregator.** Single repo-root JSON file listing every skill across every plugin, with description, version, model tier, and eval count. Stable URL for third-party indexes to consume.
+- **Author and ownership metadata.** Plugin-level `authors:` array surfaced in plugin README and `marketplace.json` so end users can see who owns what.
+- **Snapshot evaluation pipeline.** Run each plugin's `evals/scenarios.json` against a pinned model on every release-please PR; fail when the expected action drifts.
+- **Demo asciinema cast** in the root README hero.
+
+## Later (intent)
+
+- **Native `aidd-pm` ticketing integrations** beyond Jira (Linear, GitHub Projects v2, Notion).
+- **Cost transparency badges** ("low / medium / high" tier per skill) backed by snapshot evals.
+- **Cross-tool runtime parity.** The [`aidd-cli`](https://github.com/ai-driven-dev/aidd-cli) project packages skills for Cursor, GitHub Copilot, OpenCode; align the test surface so the same scenarios pass on every tool.
+- **Localisation.** A French-translated README + selected docs for the French-speaking community.
+- **GitHub App for write operations** (replacing the PAT pattern used by `aidd-orchestrator` in remote mode) so commits get bot attribution and finer-grained scopes.
+
+## Done (recent highlights)
+
+- Multi-plugin marketplace with 6 plugins and 31 skills, all with per-skill README and populated `evals/scenarios.json`.
+- Marketplace schema validation in pre-commit.
+- Async-dev orchestration pipeline (label an issue, get a PR), including review loop.
+- OSS scaffolding: LICENSE, SECURITY, CoC, CONTRIBUTING, PR template, issue templates, CODEOWNERS, FUNDING, dependabot.
+
+## How to influence the roadmap
+
+- Open an issue with the `feat:` template describing the use case.
+- Drop a thumbs-up on existing issues; we use reaction counts as a coarse priority signal.
+- Join the [Discord](https://discord.gg/ai-driven-dev) for design discussions.
+- For sponsored work, see [`.github/FUNDING.yml`](./.github/FUNDING.yml).