{
  "markdown": "# doc-superpowers\n\nDocumentation orchestrator for AI-assisted development. Generates, audits, and maintains project documentation through parallel agent dispatch, agentic workflow discovery, Mermaid diagram generation, and formal spec lifecycle tracking.\n\nA superset of [obra/superpowers](https://github.com/obra/superpowers) documentation patterns — extends them with automated discovery of agentic pipelines (skills, commands, MCP tools), multi-scope parallel auditing, architecture diagram generation, formal specification tracking through implementation, workflow hooks for automated freshness monitoring, and release notes management.\n\n## What It Does\n\ndoc-superpowers is a Claude Code skill that treats documentation as a first-class engineering artifact. It:\n\n- **Discovers** your project's doc tooling, directory structure, and agentic workflows automatically\n- **Generates** a complete documentation suite from scratch (`init`)\n- **Audits** existing docs against current code for staleness (`audit`)\n- **Reviews** PR-scoped documentation impact (`review-pr`)\n- **Updates** stale docs with agent-verified changes (`update`)\n- **Regenerates** architecture and workflow diagrams (`diagram`)\n- **Syncs** doc indexes with the filesystem (`sync`)\n- **Installs** opt-in workflow hooks for automated freshness monitoring (`hooks`)\n- **Tracks specifications** through implementation with formal spec lifecycle (`spec-generate`, `spec-inject`, `spec-verify`)\n- **Drafts release notes** from git history with agent-assisted diff review (`release`)\n- **Syncs CLAUDE.md and README.md** automatically across all write actions to prevent drift\n- **Tracks freshness** via bundled `scripts/doc-tools.sh` — content hashing for docs, commit SHA comparison for code\n\n## Installation\n\n### Claude Code (Skill)\n\nCopy or symlink into your Claude Code skills directory:\n\n```bash\n# Clone\ngit clone git@github.com:woodrowpearson/doc-superpowers.git ~/code/doc-superpowers\n\n# Symlink into Claude Code skills\nln -s ~/code/doc-superpowers ~/.claude/skills/doc-superpowers\n```\n\n### Manual\n\nCopy `skills/doc-superpowers/SKILL.md` and `references/` into `.claude/skills/doc-superpowers/` in any project.\n\n### Cursor\n\nUse Cursor's plugin system:\n\n```\n/add-plugin doc-superpowers\n```\n\nOr clone and point `.cursor-plugin/plugin.json` at the repo.\n\n### Codex\n\n```bash\ngit clone https://github.com/woodrowpearson/doc-superpowers.git ~/.codex/doc-superpowers\nmkdir -p ~/.agents/skills\nln -s ~/.codex/doc-superpowers ~/.agents/skills/doc-superpowers\n```\n\nSee `.codex/INSTALL.md` for details.\n\n### OpenCode\n\nAdd to your `opencode.json`:\n\n```json\n{\n  \"plugin\": [\"doc-superpowers@git+https://github.com/woodrowpearson/doc-superpowers.git\"]\n}\n```\n\nSee `.opencode/INSTALL.md` for details.\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/woodrowpearson/doc-superpowers\n```\n\n### skills.sh (Any Agent)\n\n```bash\nnpx skills add woodrowpearson/doc-superpowers\n```\n\nWorks with 40+ supported agents. See [skills.sh](https://skills.sh) for details.\n\n## Usage\n\n```\n/doc-superpowers <action> [scope]\n\nActions: init | audit | review-pr | update | diagram | sync | hooks | release | spec-generate | spec-inject | spec-verify\nScopes:  all | <auto-detected from docs/ structure>\n```\n\n### Actions\n\n| Action | Purpose | When to Use |\n|--------|---------|-------------|\n| `init` | Generate full doc suite from scratch | New project or missing docs |\n| `audit` | Check all docs, CLAUDE.md, README.md, and RELEASE-NOTES.md for staleness via parallel scope agents; writes a report to `docs/plans/` | Periodic health check |\n| `review-pr` | Check docs, CLAUDE.md, and README.md affected by PR changes | Before merging PRs |\n| `update` | Apply fixes from audit/review | After audit identifies stale docs |\n| `diagram` | Regenerate architecture diagrams | After structural changes |\n| `sync` | Sync doc index with filesystem, check CLAUDE.md and README.md currency | After adding/removing doc files |\n| `hooks` | Install workflow hooks (git, Claude Code, CI/CD) | Setting up automated freshness monitoring |\n| `release` | Draft release notes entry from git history | Cutting a new version |\n| `spec-generate` | Generate formal specs from design doc; scans overlapping specs for stale content | After brainstorming produces a design spec |\n| `spec-inject` | Inject spec tasks into plans, track during execution | During plan writing and after each chunk executes |\n| `spec-verify` | Verify spec compliance, review spec coverage | Before merging or during code review |\n\n### Examples\n\n```bash\n# Generate docs for a new project\n/doc-superpowers init\n\n# Audit all documentation (writes report to docs/plans/)\n/doc-superpowers audit\n\n# Check docs before merging a PR\n/doc-superpowers review-pr\n\n# Regenerate diagrams\n/doc-superpowers diagram\n\n# Draft release notes from git history\n/doc-superpowers release\n\n# Override the starting commit\n/doc-superpowers release --from=v2.2.0\n```\n\n### Spec Lifecycle\n\n```bash\n# Generate formal specs from a design doc\n/doc-superpowers spec-generate --design-doc=docs/superpowers/specs/2026-03-14-feature-design.md\n\n# Inject spec tasks into an implementation plan\n/doc-superpowers spec-inject --phase=plan --plan=docs/superpowers/plans/2026-03-14-feature.md --specs=docs/specs/SPEC-AUTH-001-oauth-flow.md\n\n# Check spec freshness after a chunk executes\n/doc-superpowers spec-inject --phase=execute --specs=docs/specs/SPEC-AUTH-001-oauth-flow.md\n\n# Final compliance check before merging\n/doc-superpowers spec-verify --mode=post-execute --specs=docs/specs/SPEC-AUTH-001-oauth-flow.md --design-doc=docs/superpowers/specs/2026-03-14-feature-design.md\n\n# Spec coverage check during review\n/doc-superpowers spec-verify --mode=review --changed-files=src/auth/oauth.py,src/auth/session.py\n\n# Declare spec roles explicitly (v2.13.0+) — a target is advanced, a constraint is never written\n/doc-superpowers spec-inject --phase=execute --specs=docs/specs/SPEC-UI-010-collection-view.md:target,docs/specs/SPEC-API-006-backend.md:constraint\n```\n\nThe `:target` / `:constraint` / `:amends` suffix is optional — unsuffixed paths remain valid and are role-inferred at execution time (inference never yields `:amends`; an amendment is declared, never inferred). Pass `--plan=<path>` to `spec-verify` so an `:amends` spec's landed-check can verify the amendment cites the plan; without it the check degrades to block-present and warns.\n\nFor wrapper skill integration, see `references/spec-lifecycle-protocol.md`.\n\n### Workflow Integration\n\nInstall opt-in hooks for automated freshness monitoring:\n\n```bash\n# Install all hook tiers\n/doc-superpowers hooks install --all\n\n# Or pick specific tiers\n/doc-superpowers hooks install --git           # Git hooks\n/doc-superpowers hooks install --claude        # Claude Code hooks\n/doc-superpowers hooks install --ci            # GitHub Actions (all 9 workflows)\n\n# Granular CI install (v2.12.0+) — pick specific workflows\n/doc-superpowers hooks install --ci --workflows=doc-pr-release,doc-index-update\n/doc-superpowers hooks install --ci --workflows=none   # only vendor doc-tools.sh\n/doc-superpowers hooks install --ci --force            # override \"intentionally removed\"\n\n# CI tuning flags\n/doc-superpowers hooks install --ci --base-branch develop   # target branch (default: main)\n/doc-superpowers hooks install --ci --cron \"0 6 * * 1\"      # weekly audit schedule (default: 0 9 * * 1)\n/doc-superpowers hooks install --ci --ci-strict             # PR check fails on stale docs instead of warning\n/doc-superpowers hooks install --ci --helpers=false         # skip the doc-pr-release helpers (default: true)\n\n# Standalone tool install (v2.12.0+) — doc-tools.sh only, no workflows\n$DOC_TOOLS tools install                       # → .github/scripts/doc-tools.sh\n$DOC_TOOLS tools install --with-helpers        # +doc-pr-release helpers\n$DOC_TOOLS tools status\n\n# Check what's installed\n/doc-superpowers hooks status\n\n# Remove hooks\n/doc-superpowers hooks uninstall --all\n/doc-superpowers hooks uninstall --ci --workflows=doc-release  # remove ONE workflow\n```\n\n**State tracking (v2.12.0+):** install choices persist via `.claude/doc-superpowers/installed.json` (committed to the repo). A subsequent `install --ci` respects prior intentional uninstalls; pass `--workflows=<name>` to override, `--force` to ignore state, or `uninstall --ci --transient` so the next install re-installs.\n\n**Git hooks (5):** Pre-commit warns when staged files affect stale docs. Post-merge and post-checkout alert on branch switches. Prepare-commit-msg injects freshness comments. Pre-push reminds about unreleased commits.\n\n**Claude Code hooks (3):** Pre-commit gate catches Claude-initiated commits. Post-commit sync auto-runs `update-index` after commits. Session summary reminds about stale docs when ending a session.\n\n**CI/CD (9 workflows — 3 shell-based, 6 Claude-powered):** PR freshness check comments on PRs. Weekly cron detects drift. Post-merge workflow keeps the doc index in sync. Claude-powered workflows provide AI audit+update on feature branches, AI PR doc review with @claude interactive support, AI release notes drafting on release branches, AI spec compliance checks on PRs, AI PR full-cycle orchestration (review, update, diagram, sync), and AI per-PR release-notes fragment producer (drafts `RELEASE-NOTES.next/PR-<N>.md` on every push, consumed by the release workflow at release time). Claude-powered workflows require one of `CLAUDE_CODE_OAUTH_TOKEN` (preferred) or `ANTHROPIC_API_KEY` as a GitHub Actions secret; if both are set, `CLAUDE_CODE_OAUTH_TOKEN` takes precedence.\n\nSet `DOC_SUPERPOWERS_STRICT=1` to make pre-commit block instead of warn. Set `DOC_SUPERPOWERS_QUIET=1` to suppress hook output while still enforcing checks. Set `DOC_SUPERPOWERS_SKIP=1` to bypass all hooks temporarily.\n\n## Generated Documentation\n\nThe `init` action generates a structured documentation suite in `docs/`:\n\n| Directory/File | Content | When Generated |\n|----------------|---------|---------------|\n| `architecture/system-overview.md` | System overview, C4 diagrams, tech stack | Always |\n| `architecture/{component}.md` | Per major component/domain | `application` scope |\n| `architecture/diagrams/` | C4, component, ERD diagrams | Always |\n| `specs/README.md` + `template.md` | Spec index and template | Always |\n| `adr/README.md` + `template.md` | ADR log and template | Always |\n| `workflows/{name}.md` | Process flows, CI/CD | Always |\n| `workflows/agentic/{skill}.md` | Agentic workflow docs | `agentic` scope |\n| `workflows/diagrams/` | Workflow, sequence, state diagrams | Always |\n| `guides/getting-started.md` | Prerequisites, installation, verification | Always |\n| `api-contracts.md` | Endpoints, schemas, request/response | `api-contracts` scope |\n| `data-layer.md` | Data models, ERD, storage | `data-layer` scope |\n| `ci-cd.md` | Pipeline overview, triggers, environments | `ci-cd` scope |\n| `infra.md` | Infrastructure topology, components | `infrastructure` scope |\n| `codebase-guide.md` | Directory map, key files, code flow | Always |\n| `conventions.md` | Code style, naming, git conventions | Always |\n| `.doc-index.json` | Machine-readable freshness index | Always |\n\n## Agentic Workflow Discovery\n\ndoc-superpowers automatically discovers Claude Code artifacts that define agentic pipelines:\n\n- **Skills** (`.claude/skills/*/SKILL.md`) — sub-agents, scripts, user gates\n- **Commands** (`.claude/commands/*.md`) — which skills they invoke\n- **MCP tools** (MCP config files) — server names and tool purposes\n- **Scripts** (`scripts/`) — roles in pipelines (dispatch, validate, merge)\n\nEach discovered workflow gets documented with:\n- Pipeline overview flowchart\n- Phase/session subgraph diagrams\n- Multi-actor sequence diagrams with sub-agent lifelines\n- State diagrams for pipelines with recovery flows\n\n## Audit Severity Levels\n\n| Level | Meaning |\n|-------|---------|\n| **P0 Critical** | Doc describes behavior code no longer implements |\n| **P1 Stale** | Code changed, doc probably needs updating |\n| **P2 Incomplete** | Doc missing sections for new functionality |\n| **P3 Style** | Formatting, broken links, outdated terminology |\n\n## Architecture\n\ndoc-superpowers uses a hub-and-spoke architecture:\n\n1. **Discovery phase** runs first, building an inventory of the project\n2. **Action router** dispatches to the requested action\n3. **Parallel agents** handle scope-isolated reviews (one agent per doc scope)\n4. **Verification gates** ensure agent findings include evidence (exact doc vs code quotes)\n5. **Output** is a structured report with severity-ranked findings\n\n## Relationship to obra/superpowers\n\nThis skill is designed as a **documentation superset** of the [obra/superpowers](https://github.com/obra/superpowers) framework:\n\n- Uses the same skill structure conventions (SKILL.md frontmatter, description triggers)\n- Follows superpowers' verification-before-completion patterns\n- Extends with documentation-specific workflows not covered by the base framework\n- Compatible with superpowers' code review integration (callback pattern)\n\n## File Structure\n\n```\ndoc-superpowers/\n├── .gitignore            # Git ignore rules\n├── .claude/              # Self-installed Claude Code hook tier\n│   ├── settings.local.json   # Hook wiring (PreToolUse, PostToolUse, Stop)\n│   └── hooks/\n│       └── doc-superpowers/  # pre-commit-gate.sh, post-commit-sync.sh, session-summary.sh\n├── .claude-plugin/       # Claude Code plugin manifest + marketplace\n│   ├── plugin.json\n│   └── marketplace.json\n├── .cursor-plugin/       # Cursor plugin manifest + installation guide\n│   ├── plugin.json\n│   └── INSTALL.md\n├── .codex/               # Codex installation guide\n│   └── INSTALL.md\n├── .github/              # Self-installed CI tier — 3 of the 9 workflow templates\n│   └── workflows/\n│       ├── doc-freshness-pr.yml\n│       ├── doc-freshness-schedule.yml\n│       └── doc-index-update.yml\n├── .opencode/            # OpenCode plugin + installation guide\n│   ├── INSTALL.md\n│   └── plugins/\n│       └── doc-superpowers.js\n├── skills/\n│   └── doc-superpowers/\n│       └── SKILL.md      # Main skill definition\n├── AGENTS.md             # Cross-client agent instructions\n├── GEMINI.md             # Gemini CLI context redirect\n├── claude-code.json      # Claude Code skill manifest\n├── gemini-extension.json # Gemini CLI extension manifest\n├── package.json          # npm/OpenCode package metadata\n├── scripts/\n│   ├── doc-tools.sh      # Bundled freshness tooling\n│   ├── test-doc-tools.sh # Test suite for doc-tools.sh\n│   ├── test-helpers.sh   # Shared test utilities\n│   ├── test-hooks.sh     # Test suite for hooks installer\n│   ├── test-spec-status-model.sh # Test suite for the Spec Status Model + call sites\n│   ├── test-doc-pr-release.sh    # Test suite for doc-pr-release helpers\n│   ├── merge-doc-index.sh        # Custom git merge driver for .doc-index.json\n│   ├── test-merge-driver.sh      # Test suite for merge driver\n│   └── hooks/\n│       ├── install.sh        # Hook installer engine\n│       ├── state.sh          # Install-state tracking\n│       ├── git/              # Git hook scripts (pre-commit, post-merge, etc.)\n│       ├── claude/           # Claude Code hook scripts\n│       └── ci/               # GitHub Actions workflow templates\n├── references/\n│   ├── doc-spec.md       # Templates and conventions\n│   ├── agent-prompt-template.md   # Review agent prompt template + scope focus areas\n│   ├── output-templates.md        # Audit report format + plan template\n│   ├── spec-lifecycle-actions.md  # Detailed procedures for spec lifecycle actions\n│   ├── spec-lifecycle-protocol.md # Spec lifecycle integration guide\n│   ├── integration-patterns.md    # Code review, commit review, wrapper skill integration\n│   └── tool-mappings.md           # Cross-framework tool name mappings\n├── evals/                # Evaluation test cases\n│   └── evals.json        # Test prompts and assertions\n├── docs/                 # Documentation about this skill\n│   ├── architecture/\n│   │   ├── system-overview.md\n│   │   └── diagrams/\n│   ├── workflows/\n│   │   ├── doc-superpowers.md\n│   │   └── diagrams/\n│   ├── guides/\n│   │   └── getting-started.md\n│   ├── superpowers/\n│   │   ├── specs/        # Design specs from brainstorming\n│   │   └── plans/        # Implementation plans from writing-plans\n│   ├── .doc-index.json   # Machine-readable freshness index\n│   ├── issues/           # Bug reports and enhancement requests\n│   ├── plans/            # Audit reports and update plans\n│   ├── archive/          # Archived docs\n│   ├── codebase-guide.md\n│   └── conventions.md\n├── README.md\n├── LICENSE               # MIT\n├── RELEASE-NOTES.md\n└── CLAUDE.md\n```\n\n## Dependencies\n\nThe skill itself (`skills/doc-superpowers/SKILL.md` + `references/`) has zero dependencies. The bundled tooling in `scripts/` requires:\n\n| Dependency | Required | Notes |\n|-----------|----------|-------|\n| `git` | Yes | Already required by doc-superpowers |\n| `jq` | Yes | `brew install jq` / `apt install jq` |\n| `sha256sum` or `shasum` | Yes | Standard on Linux/macOS respectively |\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes to `skills/doc-superpowers/SKILL.md` or `references/doc-spec.md`\n4. Test with `/doc-superpowers init` on a sample project\n5. Submit a PR\n\n## License\n\nMIT License. See [LICENSE](LICENSE).\n",
  "bytes": 17369,
  "sha": "5dcb86ab5e297d100447ae5624f613dbee1342f334ac049e41da03fb9634ff7d",
  "repo_slug": "woodrowpearson/doc-superpowers",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_woodrowpearson_doc_superpowers_143f46f0/readme"
}