docs(framework): rework the documentation — install-first, concise, emoji-styled#407
Merged
Merged
Conversation
…tent Restructure the README to lead with installation (Claude Code first, other tools folded into one section), moving community context below. Fix cross-doc anchor rot in FAQ/TROUBLESHOOTING, reconcile stale plugin/skill/package counts against the filesystem (7 plugins, 40 skills, 2 agents, 8 release packages), and add the missing aidd-ui, aidd-vcs 00-repo-init, and aidd-dev 10-todo entries. Collapse duplication: delete the orphaned docs/RELEASE.md (duplicated the canonical root RELEASE.md) after moving its unique promote/recovery content into MAINTAINERS; make MAINTAINERS the single home for the per-tool bundle list and point CONTRIBUTING at it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…sites, flat-only other tools Rework the README around the "best repo" pattern: one-line what, a two-phase visual quick start (onboard → project memory once, then the feature loop), install with explicit prerequisites (Claude Code + Node for plugin hooks), and marketing collapsed to a short community line. Other tools now install from the flat archive only (unzip, no CLI); the CLI-registered marketplace flow is marked as coming, since the CLI is not yet available. List the two bundled Node hooks in ARCHITECTURE and tie them to prerequisites + Trust and safety. Fix cross-doc anchors to the real GitHub slugs (emoji headings carry a leading hyphen). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Split into a dedicated Prerequisites section, a clear Claude Code install, a tool-compatibility table, and per-tool collapsible install blocks (flat archive). Quick start now offers three explicit entry points: guided onboard, manual project-memory, or the full feature flow. Group Recipes and docs into one readable "Learn more" block, and tighten Trust and safety to two lines. Link to owning docs instead of restating scopes, versioning, or hook details. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
README: move the tool-support table under Prerequisites (framed as "an AI tool we support"), drop the inline scopes/versioning pointer (now only in Learn more), and give each other-tool a marketplace + flat split in its collapsible. Quick start now shows the three entry points (onboard / project-memory / feature flow) as a scannable table above the flow diagram. Contribute line just links CONTRIBUTING. CONTRIBUTING: refactor dense paragraphs into scannable bullets, fix the stale Node version (22.12+), and let it own the PR-rights rule the README delegates. No duplication — link to vcs.md, GOVERNANCE, RELEASE, and MAINTAINERS for the details they own. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the guessed "aidd marketplace add" steps with each tool's actual native mechanism, verified against official docs and the release archives: - Cursor: copy plugins into ~/.cursor/plugins/local/ (all plans; only team marketplaces are Teams/Enterprise-gated). - GitHub Copilot: .github/ customization files (skills, agents); Copilot CLI plugin marketplace noted. - Codex: native `codex plugin marketplace add` / `codex plugin add`, or skills via .codex/skills/. - OpenCode: file-based, unzip into .opencode/. The compatibility table now shows only Flat/Marketplace dist availability; how-to lives in each collapsible. FAQ and TROUBLESHOOTING no longer claim a universal flat-unzip. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Codex and Copilot install via their native `<tool> plugin marketplace add ai-driven-dev/framework` + install commands, mirroring Claude Code and using the same plugin names. Cursor via Customize → Plugins (local fallback for plans without team marketplaces). OpenCode stays file-based. Drops the archive-download clutter for the marketplace tools. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…se archives Every other-tool collapsible now follows one shape: a Marketplace block (release zip + install commands) and a Flat block (release zip + target dir), so each format is explicit. OpenCode is Flat only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rewrite each other-tool collapsible as terse Marketplace/Flat subheads with numbered steps, cutting prose. OpenCode marked Flat-only in its summary. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… commands Add a Claude-format line to the Cursor and Copilot install blocks (Copilot auto-detects .claude/skills and .claude/agents; Cursor reads .claude/skills), and move the install commands into fenced code blocks for readability. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Each other-tool block is now one fenced recipe: download steps as comments, Marketplace and Flat inline, with a one-line Claude-format / docs note underneath. Much lighter to scan than the prose + inline codespans. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… blocks Restore the two categories as bold subheads, each with its own fenced code block on its own lines. Merging them into one block had hidden the distinction. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Move the download/unzip step to a short prose line per category and keep only actual commands inside the code fences. Flat entries with no command are a plain line, no empty comment block. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Each category (Marketplace / Flat) is a bare bold title on its own line, followed by numbered steps; commands sit in a fence as a step. Notes (plan, Claude format) move to one italic line under the steps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Show both official paths: the /plugin slash commands in a session and the equivalent `claude plugin marketplace add` / `claude plugin install` shell commands. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rtical diagram
- Bring back the fuller intro (marketplace one-liner + SDLC blockquote).
- Separate Prerequisites (an AI tool + Node) from a dedicated
Compatibility section holding the tool table.
- Reword the Other-tools intro onto its own lines ("bundle" not
"archives").
- Flip the quick-start diagram to top-down.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add two at-a-glance command-sequence recipes via the cook template: start-a-project (greenfield setup) and ship-a-feature (idea → PR). Index them in recipes/README.md, surface them in the README, and point the contributing note at the shipped /aidd-context:12-cook skill. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…bootstrap) Upsert start-a-project through the /aidd-context:12-cook template: the greenfield sequence now runs brainstorm → PRD → bootstrap → project memory → onboard → first feature. Refresh its recipes index goal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Onboard is the guided path, not a manual step: drop it from the greenfield sequence and add a "prefer guided?" note pointing to it in both recipes. Ship-a-feature prerequisite now points at Start a project. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Point readers from the quick-start diagram to the recipes for other flows (start a project, ship a feature). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…inter README: bring back the "The AI-Driven Dev" community section (R&D + Discord/programme/ecosystem) alongside a slim Contributing. CONTRIBUTING: replace the profile mermaid + restated rights with a "where each starts" table that defers role definitions to GOVERNANCE (no duplication of the responsible file). Repoint the FAQ community link. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…facts - CREATE_PLUGIN: drop the restated toolchain (stale "Node 20+") and dead "Development setup" anchor → link CONTRIBUTING #1-set-up; point the orthogonality bullet at ARCHITECTURE instead of restating it. - MARKETPLACE: fix the wrong tag format (aidd-<plugin> double prefix) → <plugin>-vX.Y.Z with the tooling link to vcs.md; trim the marketing paragraph to one line. - MAINTAINERS: People and branch-protection policy now link GOVERNANCE instead of restating roles/promotion/merge rules; split the back-merge run-on into bullets. - GLOSSARY: include aidd-ui in the plugin domain list. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Emoji + lighter prose across ARCHITECTURE, MARKETPLACE, CREATE_PLUGIN, CONTRIBUTING, GOVERNANCE, RELEASE, GLOSSARY, MAINTAINERS, CATALOG — every ## section heading now carries a fitting emoji, matching the README. Cross-doc link-target headings use variation-selector-free emoji so their GitHub slug stays a clean leading-hyphen form; inbound links updated to the new #-slug anchors. Verified: 0 broken fragment links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Merge TROUBLESHOOTING into a single emoji-headed docs/FAQ.md (FAQ & Troubleshooting) and drop the separate file; repoint the README docs row. Add three flow diagrams: contribution flow (CONTRIBUTING), plugin build lifecycle (CREATE_PLUGIN), and marketplace resolution (MARKETPLACE). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Drop the verbose scaffolding/SKILL.md/action code examples that duplicated ARCHITECTURE's anatomy; keep only what lives nowhere else — marketplace registration, release-please config, local testing, ship guardrails — and link ARCHITECTURE for the model. No skill scaffolds a full plugin, so this stays the home for the registration steps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Condense the ~53-line Project board setup to ~18 (drop redundant CLI snippets and the checklist that restated the field bullets). Cut the Daily "Review PRs" merge-rule restatement (link GOVERNANCE) and the "Build your own plugin" registration line (now owned by CREATE_PLUGIN). 174 → 140 lines. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… usage
Cross-plugin orthogonality was overstated as absolute ("plugins do not
reference each other by name"), but aidd-orchestrator deliberately names
the aidd-dev pipeline it drives. Reframe: recipes delegate by capability;
the orchestrator is the named exception. Also note commands/rules/MCP are
schema-supported but currently unused by any bundled plugin. Verified
correct against the codebase otherwise.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The rule holds for all plugins, orchestrators included; an orchestrator naming a sibling by aidd-<plugin>:... is a violation, not an exception. Note it is not yet mechanically enforced, which is how such a hardcode slips through today. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…-documentation # Conflicts: # docs/CREATE_PLUGIN.md # plugins/aidd-dev/README.md # plugins/aidd-vcs/README.md
This was referenced Jul 9, 2026
blafourcade
added a commit
that referenced
this pull request
Jul 10, 2026
…moji-styled (#407) * docs(framework): rework docs to be install-first, concise, and consistent Restructure the README to lead with installation (Claude Code first, other tools folded into one section), moving community context below. Fix cross-doc anchor rot in FAQ/TROUBLESHOOTING, reconcile stale plugin/skill/package counts against the filesystem (7 plugins, 40 skills, 2 agents, 8 release packages), and add the missing aidd-ui, aidd-vcs 00-repo-init, and aidd-dev 10-todo entries. Collapse duplication: delete the orphaned docs/RELEASE.md (duplicated the canonical root RELEASE.md) after moving its unique promote/recovery content into MAINTAINERS; make MAINTAINERS the single home for the per-tool bundle list and point CONTRIBUTING at it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): make README essential — visual quick start, prerequisites, flat-only other tools Rework the README around the "best repo" pattern: one-line what, a two-phase visual quick start (onboard → project memory once, then the feature loop), install with explicit prerequisites (Claude Code + Node for plugin hooks), and marketing collapsed to a short community line. Other tools now install from the flat archive only (unzip, no CLI); the CLI-registered marketplace flow is marked as coming, since the CLI is not yet available. List the two bundled Node hooks in ARCHITECTURE and tie them to prerequisites + Trust and safety. Fix cross-doc anchors to the real GitHub slugs (emoji headings carry a leading hyphen). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): restructure README install/quick-start for clarity Split into a dedicated Prerequisites section, a clear Claude Code install, a tool-compatibility table, and per-tool collapsible install blocks (flat archive). Quick start now offers three explicit entry points: guided onboard, manual project-memory, or the full feature flow. Group Recipes and docs into one readable "Learn more" block, and tighten Trust and safety to two lines. Link to owning docs instead of restating scopes, versioning, or hook details. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): refine README install/quick-start and slim CONTRIBUTING README: move the tool-support table under Prerequisites (framed as "an AI tool we support"), drop the inline scopes/versioning pointer (now only in Learn more), and give each other-tool a marketplace + flat split in its collapsible. Quick start now shows the three entry points (onboard / project-memory / feature flow) as a scannable table above the flow diagram. Contribute line just links CONTRIBUTING. CONTRIBUTING: refactor dense paragraphs into scannable bullets, fix the stale Node version (22.12+), and let it own the PR-rights rule the README delegates. No duplication — link to vcs.md, GOVERNANCE, RELEASE, and MAINTAINERS for the details they own. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): document real per-tool install methods Replace the guessed "aidd marketplace add" steps with each tool's actual native mechanism, verified against official docs and the release archives: - Cursor: copy plugins into ~/.cursor/plugins/local/ (all plans; only team marketplaces are Teams/Enterprise-gated). - GitHub Copilot: .github/ customization files (skills, agents); Copilot CLI plugin marketplace noted. - Codex: native `codex plugin marketplace add` / `codex plugin add`, or skills via .codex/skills/. - OpenCode: file-based, unzip into .opencode/. The compatibility table now shows only Flat/Marketplace dist availability; how-to lives in each collapsible. FAQ and TROUBLESHOOTING no longer claim a universal flat-unzip. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): use each tool's official marketplace commands Codex and Copilot install via their native `<tool> plugin marketplace add ai-driven-dev/framework` + install commands, mirroring Claude Code and using the same plugin names. Cursor via Customize → Plugins (local fallback for plans without team marketplaces). OpenCode stays file-based. Drops the archive-download clutter for the marketplace tools. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): structure each tool as Marketplace + Flat with release archives Every other-tool collapsible now follows one shape: a Marketplace block (release zip + install commands) and a Flat block (release zip + target dir), so each format is explicit. OpenCode is Flat only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): recipe-style per-tool install blocks Rewrite each other-tool collapsible as terse Marketplace/Flat subheads with numbered steps, cutting prose. OpenCode marked Flat-only in its summary. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): note Claude-format support for Cursor/Copilot, fence commands Add a Claude-format line to the Cursor and Copilot install blocks (Copilot auto-detects .claude/skills and .claude/agents; Cursor reads .claude/skills), and move the install commands into fenced code blocks for readability. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): collapse per-tool install into a single code block each Each other-tool block is now one fenced recipe: download steps as comments, Marketplace and Flat inline, with a one-line Claude-format / docs note underneath. Much lighter to scan than the prose + inline codespans. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): split each tool back into visible Marketplace / Flat blocks Restore the two categories as bold subheads, each with its own fenced code block on its own lines. Merging them into one block had hidden the distinction. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): fenced blocks hold real commands only, not comments Move the download/unzip step to a short prose line per category and keep only actual commands inside the code fences. Flat entries with no command are a plain line, no empty comment block. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): per-tool install as title-only heads + numbered recipe Each category (Marketplace / Flat) is a bare bold title on its own line, followed by numbered steps; commands sit in a fence as a step. Notes (plan, Claude format) move to one italic line under the steps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): Claude Code install in-session and by command line Show both official paths: the /plugin slash commands in a session and the equivalent `claude plugin marketplace add` / `claude plugin install` shell commands. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): restore intro, split Prerequisites/Compatibility, vertical diagram - Bring back the fuller intro (marketplace one-liner + SDLC blockquote). - Separate Prerequisites (an AI tool + Node) from a dedicated Compatibility section holding the tool table. - Reword the Other-tools intro onto its own lines ("bundle" not "archives"). - Flip the quick-start diagram to top-down. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): add cookbook recipes for greenfield and feature flow Add two at-a-glance command-sequence recipes via the cook template: start-a-project (greenfield setup) and ship-a-feature (idea → PR). Index them in recipes/README.md, surface them in the README, and point the contributing note at the shipped /aidd-context:12-cook skill. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): enrich greenfield recipe via cook (brainstorm, PRD, bootstrap) Upsert start-a-project through the /aidd-context:12-cook template: the greenfield sequence now runs brainstorm → PRD → bootstrap → project memory → onboard → first feature. Refresh its recipes index goal. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): frame onboard as the guided alternative in recipes Onboard is the guided path, not a manual step: drop it from the greenfield sequence and add a "prefer guided?" note pointing to it in both recipes. Ship-a-feature prerequisite now points at Start a project. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): add recipes CTA under the quick-start diagram Point readers from the quick-start diagram to the recipes for other flows (start a project, ship a feature). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): restore The AI-Driven Dev section; roles as a nav pointer README: bring back the "The AI-Driven Dev" community section (R&D + Discord/programme/ecosystem) alongside a slim Contributing. CONTRIBUTING: replace the profile mermaid + restated rights with a "where each starts" table that defers role definitions to GOVERNANCE (no duplication of the responsible file). Repoint the FAQ community link. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): apply no-duplication audit — link owners, fix stale facts - CREATE_PLUGIN: drop the restated toolchain (stale "Node 20+") and dead "Development setup" anchor → link CONTRIBUTING #1-set-up; point the orthogonality bullet at ARCHITECTURE instead of restating it. - MARKETPLACE: fix the wrong tag format (aidd-<plugin> double prefix) → <plugin>-vX.Y.Z with the tooling link to vcs.md; trim the marketing paragraph to one line. - MAINTAINERS: People and branch-protection policy now link GOVERNANCE instead of restating roles/promotion/merge rules; split the back-merge run-on into bullets. - GLOSSARY: include aidd-ui in the plugin domain list. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): bring all docs into the README's emoji-headed style Emoji + lighter prose across ARCHITECTURE, MARKETPLACE, CREATE_PLUGIN, CONTRIBUTING, GOVERNANCE, RELEASE, GLOSSARY, MAINTAINERS, CATALOG — every ## section heading now carries a fitting emoji, matching the README. Cross-doc link-target headings use variation-selector-free emoji so their GitHub slug stays a clean leading-hyphen form; inbound links updated to the new #-slug anchors. Verified: 0 broken fragment links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): merge FAQ+Troubleshooting, add flow diagrams Merge TROUBLESHOOTING into a single emoji-headed docs/FAQ.md (FAQ & Troubleshooting) and drop the separate file; repoint the README docs row. Add three flow diagrams: contribution flow (CONTRIBUTING), plugin build lifecycle (CREATE_PLUGIN), and marketplace resolution (MARKETPLACE). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): slim CREATE_PLUGIN to a lean reference (185 → 38 lines) Drop the verbose scaffolding/SKILL.md/action code examples that duplicated ARCHITECTURE's anatomy; keep only what lives nowhere else — marketplace registration, release-please config, local testing, ship guardrails — and link ARCHITECTURE for the model. No skill scaffolds a full plugin, so this stays the home for the registration steps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): trim MAINTAINERS — dedup + condense the board runbook Condense the ~53-line Project board setup to ~18 (drop redundant CLI snippets and the checklist that restated the field bullets). Cut the Daily "Review PRs" merge-rule restatement (link GOVERNANCE) and the "Build your own plugin" registration line (now owned by CREATE_PLUGIN). 174 → 140 lines. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): correct ARCHITECTURE orthogonality claim and surface usage Cross-plugin orthogonality was overstated as absolute ("plugins do not reference each other by name"), but aidd-orchestrator deliberately names the aidd-dev pipeline it drives. Reframe: recipes delegate by capability; the orchestrator is the named exception. Also note commands/rules/MCP are schema-supported but currently unused by any bundled plugin. Verified correct against the codebase otherwise. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(framework): keep orthogonality absolute — orchestrators included The rule holds for all plugins, orchestrators included; an orchestrator naming a sibling by aidd-<plugin>:... is a violation, not an exception. Note it is not yet mechanically enforced, which is how such a hardcode slips through today. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Merged
This was referenced Jul 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
End-to-end rework of the framework documentation for an easy install and a consistent, scannable style.
README
docs/
docs/FAQ.md.Correctness & no-duplication
How it was verified
node scripts/check-markdown-links.js— 0 broken.github-slugger— 0 broken (emoji headings that are link targets use variation-selector-free emoji for clean#-sluganchors).node scripts/sync-readme-counts.mjs --check— passes.🤖 Generated with Claude Code