doc-superpowers
Documentation orchestrator: generates, audits, and maintains project docs through parallel agent dispatch, agentic workflow discovery, diagr
Open source Open in the app JSON README (API)
About
Documentation orchestrator: generates, audits, and maintains project docs through parallel agent dispatch, agentic workflow discovery, diagram generation, and spec lifecycle tracking
Details
- Kind
- Plugins
- Topic
- Media, design & games
- Publisher
- woodrowpearson
- Origin
- gemini
- Category
- ferramentas
- Version
- 2.15.0
- Forks
- 1
- Open pull requests
- 1
- Last push
- 2026-09-02T06:21:25Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-09-02 12:01:22
- Origin id
woodrowpearson/doc-superpowers
README
# doc-superpowers
Documentation 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.
A 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.
## What It Does
doc-superpowers is a Claude Code skill that treats documentation as a first-class engineering artifact. It:
- **Discovers** your project's doc tooling, directory structure, and agentic workflows automatically
- **Generates** a complete documentation suite from scratch (`init`)
- **Audits** existing docs against current code for staleness (`audit`)
- **Reviews** PR-scoped documentation impact (`review-pr`)
- **Updates** stale docs with agent-verified changes (`update`)
- **Regenerates** architecture and workflow diagrams (`diagram`)
- **Syncs** doc indexes with the filesystem (`sync`)
- **Installs** opt-in workflow hooks for automated freshness monitoring (`hooks`)
- **Tracks specifications** through implementation with formal spec lifecycle (`spec-generate`, `spec-inject`, `spec-verify`)
- **Drafts release notes** from git history with agent-assisted diff review (`release`)
- **Syncs CLAUDE.md and README.md** automatically across all write actions to prevent drift
- **Tracks freshness** via bundled `scripts/doc-tools.sh` — content hashing for docs, commit SHA comparison for code
## Installation
### Claude Code (Skill)
Copy or symlink into your Claude Code skills directory:
```bash
# Clone
git clone git@github.com:woodrowpearson/doc-superpowers.git ~/code/doc-superpowers
# Symlink into Claude Code skills
ln -s ~/code/doc-superpowers ~/.claude/skills/doc-superpowers
```
### Manual
Copy `skills/doc-superpowers/SKILL.md` and `references/` into `.claude/skills/doc-superpowers/` in any project.
### Cursor
Use Cursor's plugin system:
```
/add-plugin doc-superpowers
```
Or clone and point `.cursor-plugin/plugin.json` at the repo.
### Codex
```bash
git clone https://github.com/woodrowpearson/doc-superpowers.git ~/.codex/doc-superpowers
mkdir -p ~/.agents/skills
ln -s ~/.codex/doc-superpowers ~/.agents/skills/doc-superpowers
```
See `.codex/INSTALL.md` for details.
### OpenCode
Add to your `opencode.json`:
```json
{
"plugin": ["doc-superpowers@git+https://github.com/woodrowpearson/doc-superpowers.git"]
}
```
See `.opencode/INSTALL.md` for details.
### Gemini CLI
```bash
gemini extensions install https://github.com/woodrowpearson/doc-superpowers
```
### skills.sh (Any Agent)
```bash
npx skills add woodrowpearson/doc-superpowers
```
Works with 40+ supported agents. See [skills.sh](https://skills.sh) for details.
## Usage
```
/doc-superpowers <action> [scope]
Actions: init | audit | review-pr | update | diagram | sync | hooks | release | spec-generate | spec-inject | spec-verify
Scopes: all | <auto-detected from docs/ structure>
```
### Actions
| Action | Purpose | When to Use |
|--------|---------|-------------|
| `init` | Generate full doc suite from scratch | New project or missing docs |
| `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 |
| `review-pr` | Check docs, CLAUDE.md, and README.md affected by PR changes | Before merging PRs |
| `update` | Apply fixes from audit/review | After audit identifies stale docs |
| `diagram` | Regenerate architecture diagrams | After structural changes |
| `sync` | Sync doc index with filesystem, check CLAUDE.md and README.md currency | After adding/removing doc files |
| `hooks` | Install workflow hooks (git, Claude Code, CI/CD) | Setting up automated freshness monitoring |
| `release` | Draft release notes entry from git history | Cutting a new version |
| `spec-generate` | Generate formal specs from design doc; scans overlapping specs for stale content | After brainstorming produces a design spec |
| `spec-inject` | Inject spec tasks into plans, track during execution | During plan writing and after each chunk executes |
| `spec-verify` | Verify spec compliance, review spec coverage | Before merging or during code review |
### Examples
```bash
# Generate docs for a new project
/doc-superpowers init
# Audit all documentation (writes report to docs/plans/)
/doc-superpowers audit
# Check docs before merging a PR
/doc-superpowers review-pr
# Regenerate diagrams
/doc-superpowers diagram
# Draft release notes from git history
/doc-superpowers release
# Override the starting commit
/doc-superpowers release --from=v2.2.0
```
### Spec Lifecycle
```bash
# Generate formal specs from a design doc
/doc-superpowers spec-generate --design-doc=docs/superpowers/specs/2026-03-14-feature-design.md
# Inject spec tasks into an implementation plan
/doc-superpowers spec-inject --phase=plan --plan=docs/superpowers/plans/2026-03-14-feature.md --specs=docs/specs/SPEC-AUTH-001-oauth-flow.md
# Check spec freshness after a chunk executes
/doc-superpowers spec-inject --phase=execute --specs=docs/specs/SPEC-AUTH-001-oauth-flow.md
# Final compliance check before merging
/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
# Spec coverage check during review
/doc-superpowers spec-verify --mode=review --changed-files=src/auth/oauth.py,src/auth/session.py
# Declare spec roles explicitly (v2.13.0+) — a target is advanced, a constraint is never written
/doc-superpowers spec-inject --phase=execute --specs=docs/specs/SPEC-UI-010-collection-view.md:target,docs/specs/SPEC-API-006-backend.md:constraint
```
The `: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.
For wrapper skill integration, see `references/spec-lifecycle-protocol.md`.
### Workflow Integration
Install opt-in hooks for automated freshness monitoring:
```bash
# Install all hook tiers
/doc-superpowers hooks install --all
# Or pick specific tiers
/doc-superpowers hooks install --git # Git hooks
/doc-superpowers hooks install --claude # Claude Code hooks
/doc-superpowers hooks install --ci # GitHub Actions (all 9 workflows)
# Granular CI install (v2.12.0+) — pick specific workflows
/doc-superpowers hooks install --ci --workflows=doc-pr-release,doc-index-update
/doc-superpowers hooks install --ci --workflows=none # only vendor doc-tools.sh
/doc-superpowers hooks install --ci --force # override "intentionally removed"
# CI tuning flags
/doc-superpowers hooks install --ci --base-branch develop # target branch (default: main)
/doc-superpowers hooks install --ci --cron "0 6 * * 1" # weekly audit schedule (default: 0 9 * * 1)
/doc-superpowers hooks install --ci --ci-strict # PR check fails on stale docs instead of warning
/doc-superpowers hooks install --ci --helpers=false # skip the doc-pr-release helpers (default: true)
# Standalone tool install (v2.12.0+) — doc-tools.sh only, no workflows
$DOC_TOOLS tools install # → .github/scripts/doc-tools.sh
$DOC_TOOLS tools install --with-helpers # +doc-pr-release helpers
$DOC_TOOLS tools status
# Check what's installed
/doc-superpowers hooks status
# Remove hooks
/doc-superpowers hooks uninstall --all
/doc-superpowers hooks uninstall --ci --workflows=doc-release # remove ONE workflow
```
**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.
**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.
**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.
**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.
Set `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.
## Generated Documentation
The `init` action generates a structured documentation suite in `docs/`:
| Directory/File | Content | When Generated |
|----------------|---------|---------------|
| `architecture/system-overview.md` | System overview, C4 diagrams, tech stack | Always |
| `architecture/{component}.md` | Per major component/domain | `application` scope |
| `architecture/diagrams/` | C4, component, ERD diagrams | Always |
| `specs/README.md` + `template.md` | Spec index and template | Always |
| `adr/README.md` + `template.md` | ADR log and template | Always |
| `workflows/{name}.md` | Process flows, CI/CD | Always |
| `workflows/agentic/{skill}.md` | Agentic workflow docs | `agentic` scope |
| `workflows/diagrams/` | Workflow, sequence, state diagrams | Always |
| `guides/getting-started.md` | Prerequisites, installation, verification | Always |
| `api-contracts.md` | Endpoints, schemas, request/response | `api-contracts` scope |
| `data-layer.md` | Data models, ERD, storage | `data-layer` scope |
| `ci-cd.md` | Pipeline overview, triggers, environments | `ci-cd` scope |
| `infra.md` | Infrastructure topology, components | `infrastructure` scope |
| `codebase-guide.md` | Directory map, key files, code flow | Always |
| `conventions.md` | Code style, naming, git conventions | Always |
| `.doc-index.json` | Machine-readable freshness index | Always |
## Agentic Workflow Discovery
doc-superpowers automatically discovers Claude Code artifacts that define agentic pipelines:
- **Skills** (`.claude/skills/*/SKILL.md`) — sub-agents, scripts, user gates
- **Commands** (`.claude/commands/*.md`) — which skills they invoke
- **MCP tools** (MCP config files) — server names and tool purposes
- **Scripts** (`scripts/`) — roles in pipelines (dispatch, validate, merge)
Each discovered workflow gets documented with:
- Pipeline overview flowchart
- Phase/session subgraph diagrams
- Multi-actor sequence diagrams with sub-agent lifelines
- State diagrams for pipelines with recovery flows
## Audit Severity Levels
| Level | Meaning |
|-------|---------|
| **P0 Critical** | Doc describes behavior code no longer implements |
| **P1 Stale** | Code changed, doc probably needs updating |
| **P2 Incomplete** | Doc missing sections for new functionality |
| **P3 Style** | Formatting, broken links, outdated terminology |
## Architecture
doc-superpowers uses a hub-and-spoke architecture:
1. **Discovery phase** runs first, building an inventory of the project
2. **Action router** dispatches to the requested action
3. **Parallel agents** handle scope-isolated reviews (one agent per doc scope)
4. **Verification gates** ensure agent findings include evidence (exact doc vs code quotes)
5. **Output** is a structured report with severity-ranked findings
## Relationship to obra/superpowers
This skill is designed as a **documentation superset** of the [obra/superpowers](https://github.com/obra/superpowers) framework:
- Uses the same skill structure conventions (SKILL.md frontmatter, description triggers)
- Follows superpowers' verification-before-completion patterns
- Extends with documentation-specific workflows not covered by the base framework
- Compatible with superpowers' code review integration (callback pattern)
## File Structure
```
doc-superpowers/
├── .gitignore # Git ignore rules
├── .claude/ # Self-installed Claude Code hook tier
│ ├── settings.local.json # Hook wiring (PreToolUse, PostToolUse, Stop)
│ └── hooks/
│ └── doc-superpowers/ # pre-commit-gate.sh, post-commit-sync.sh, session-summary.sh
├── .claude-plugin/ # Claude Code plugin manifest + marketplace
│ ├── plugin.json
│ └── marketplace.json
├── .cursor-plugin/ # Cursor plugin manifest + installation guide
│ ├── plugin.json
│ └── INSTALL.md
├── .codex/ # Codex installation guide
│ └── INSTALL.md
├── .github/ # Self-installed CI tier — 3 of the 9 workflow templates
│ └── workflows/
│ ├── doc-freshness-pr.yml
│ ├── doc-freshness-schedule.yml
│ └── doc-index-update.yml
├── .opencode/ # OpenCode plugin + installation guide
│ ├── INSTALL.md
│ └── plugins/
│ └── doc-superpowers.js
├── skills/
│ └── doc-superpowers/
│ └── SKILL.md # Main skill definition
├── AGENTS.md # Cross-client agent instructions
├── GEMINI.md # Gemini CLI context redirect
├── claude-code.json # Claude Code skill manifest
├── gemini-extension.json # Gemini CLI extension manifest
├── package.json # npm/OpenCode package metadata
├── scripts/
│ ├── doc-tools.sh # Bundled freshness tooling
│ ├── test-doc-tools.sh # Test suite for doc-tools.sh
│ ├── test-helpers.sh # Shared test utilities
│ ├── test-hooks.sh # Test suite for hooks installer
│ ├── test-spec-status-model.sh # Test suite for the Spec Status Model + call sites
│ ├── test-doc-pr-release.sh # Test suite for doc-pr-release helpers
│ ├── merge-doc-index.sh # Custom git merge driver for .doc-index.json
│ ├── test-merge-driver.sh # Test suite for merge driver
│ └── hooks/
│ ├── install.sh # Hook installer engine
│ ├── state.sh # Install-state tracking
│ ├── git/ # Git hook scripts (pre-commit, post-merge, etc.)
│ ├── claude/ # Claude Code hook scripts
│ └── ci/ # GitHub Actions workflow templates
├── references/
│ ├── doc-spec.md # Templates and conventions
│ ├── agent-prompt-template.md # Review agent prompt template + scope focus areas
│ ├── output-templates.md # Audit report format + plan template
│ ├── spec-lifecycle-actions.md # Detailed procedures for spec lifecycle actions
│ ├── spec-lifecycle-protocol.md # Spec lifecycle integration guide
│ ├── integration-patterns.md # Code review, commit review, wrapper skill integration
│ └── tool-mappings.md # Cross-framework tool name mappings
├── evals/ # Evaluation test cases
│ └── evals.json # Test prompts and assertions
├── docs/ # Documentation about this skill
│ ├── architecture/
│ │ ├── system-overview.md
│ │ └── diagrams/
│ ├── workflows/
│ │ ├── doc-superpowers.md
│ │ └── diagrams/
│ ├── guides/
│ │ └── getting-started.md
│ ├── superpowers/
│ │ ├── specs/ # Design specs from brainstorming
│ │ └── plans/ # Implementation plans from writing-plans
│ ├── .doc-index.json # Machine-readable freshness index
│ ├── issues/ # Bug reports and enhancement requests
│ ├── plans/ # Audit reports and update plans
│ ├── archive/ # Archived docs
│ ├── codebase-guide.md
│ └── conventions.md
├── README.md
├── LICENSE # MIT
├── RELEASE-NOTES.md
└── CLAUDE.md
```
## Dependencies
The skill itself (`skills/doc-superpowers/SKILL.md` + `references/`) has zero dependencies. The bundled tooling in `scripts/` requires:
| Dependency | Required | Notes |
|-----------|----------|-------|
| `git` | Yes | Already required by doc-superpowers |
| `jq` | Yes | `brew install jq` / `apt install jq` |
| `sha256sum` or `shasum` | Yes | Standard on Linux/macOS respectively |
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make changes to `skills/doc-superpowers/SKILL.md` or `references/doc-spec.md`
4. Test with `/doc-superpowers init` on a sample project
5. Submit a PR
## License
MIT License. See [LICENSE](LICENSE).