A complete document writing workflow for your AI writing agents, inspired by obra/superpowers code development methodology.
Document Superpowers transforms your AI from a "just write something" tool into a systematic writing partner. It enforces a proven four-stage process that produces higher-quality articles, blog posts, and documentation.
When you ask your AI to write something, it doesn't just start typing. Instead:
-
Brainstorming - It steps back and asks what you're really trying to communicate. Who's the audience? What's the core message? What should readers do after reading?
-
Planning - Once it understands the topic, it creates a detailed outline breaking the article into manageable sections (150-400 words each), complete with key points, evidence needs, and transitions.
-
Execution - It writes section by section, with self-checks and validation at each step. You get checkpoints every 2-3 sections to review progress.
-
Review - Systematic four-pass review covering logic, evidence, flow, and polish. Every issue gets categorized, documented, and fixed.
The result? Professional-quality writing that's actually readable, well-structured, and achieves its purpose.
💡 Brainstorming → 📋 Planning → ✍️ Execution → 🔍 Review
Each stage has strict gates - you can't skip ahead without completing the previous stage. No more "I'll just wing it" articles.
- brainstorming - Socratic topic exploration and brief creation
- writing-article-plan - Detailed section-by-section outline with research checklist
- executing-article-plan - Batch writing with human checkpoints
- reviewing-article - Multi-pass systematic review (logic → evidence → flow → polish)
- subagent-driven-writing - Fast iteration with fresh subagent per section and two-stage review
- Structured over ad-hoc - Process prevents wasted effort
- Incremental validation - Catch issues early with frequent checkpoints
- Evidence-based - Every claim needs support
- Reader-first - Always know who you're writing for and what they need
- YAGNI for content - Cut ruthlessly, say only what matters
# Clone to Claude Code global skills directory
git clone https://github.com/binbinao/document-superpowers.git ~/.claude/skills/document-superpowersAfter cloning, add skill references in ~/.claude/CLAUDE.md or your project's .claude/CLAUDE.md:
## Skills
- ~/.claude/skills/document-superpowers/skills/brainstorming/SKILL.md
- ~/.claude/skills/document-superpowers/skills/writing-article-plan/SKILL.md
- ~/.claude/skills/document-superpowers/skills/executing-article-plan/SKILL.md
- ~/.claude/skills/document-superpowers/skills/reviewing-article/SKILL.md
- ~/.claude/skills/document-superpowers/skills/subagent-driven-writing/SKILL.md# Clone to Cursor global skills directory
git clone https://github.com/binbinao/document-superpowers.git ~/.cursor/skills/document-superpowers
# Or clone to project-level directory
git clone https://github.com/binbinao/document-superpowers.git .cursor/skills/document-superpowersAfter cloning, add the skill paths in Cursor's Rules or Agent Settings.
# Clone to Codebuddy global skills directory
git clone https://github.com/binbinao/document-superpowers.git ~/.codebuddy/skills/document-superpowers
# Or clone to project-level directory
git clone https://github.com/binbinao/document-superpowers.git .codebuddy/skills/document-superpowersAfter cloning, add the skill paths in Codebuddy's configuration.
# Clone to Gemini CLI config directory
git clone https://github.com/binbinao/document-superpowers.git ~/.gemini/skills/document-superpowersAdd skill references in ~/.gemini/GEMINI.md or your project's GEMINI.md:
## Skills
- ~/.gemini/skills/document-superpowers/skills/brainstorming/SKILL.md
- ~/.gemini/skills/document-superpowers/skills/writing-article-plan/SKILL.md
- ~/.gemini/skills/document-superpowers/skills/executing-article-plan/SKILL.md
- ~/.gemini/skills/document-superpowers/skills/reviewing-article/SKILL.md
- ~/.gemini/skills/document-superpowers/skills/subagent-driven-writing/SKILL.md# Option 1: Clone to your workspace skills directory
git clone https://github.com/binbinao/document-superpowers.git ~/.openclaw/skills/document-superpowers
# Option 2: Install via OpenClaw skills manager (if available)
openclaw skills install document-superpowersCopy the skills/ directory into your AI agent's skills folder according to your platform's documentation.
"I want to write about [topic]"
Your agent will automatically invoke the brainstorming skill and start asking questions.
The agent asks one question at a time to understand:
- Who's your audience?
- What's the main message?
- What action should readers take?
- Any constraints (length, tone, format)?
Once it understands your topic, it presents a brief covering:
- Audience persona
- Purpose and core message
- Key supporting points
- Tone and style
Approve or request revisions.
After brief approval, it creates a detailed outline:
- Section breakdown with word counts
- Key points per section
- Supporting evidence needs
- Transitions between sections
Batch execution (default):
- Write 2-3 sections at a time
- Checkpoint for review
- Continue until complete
- Good for: straightforward articles, focused writing sessions
Subagent-driven (advanced):
- Fresh subagent per section
- Two-stage review (spec + quality)
- Tight feedback loop
- Good for: complex articles, high-stakes content
Systematic four-pass review:
- Logic - Is the argument sound?
- Evidence - Are claims supported?
- Flow - Does it read smoothly?
- Polish - Grammar, formatting, style
Issues get categorized (critical/moderate/minor) and fixed systematically.
Your final article is saved with:
- Full review log documenting all changes
- Metadata (word count, reading time, audience)
- Ready-to-publish format
User: "I want to write a blog post about why engineers should write documentation"
Agent: [invokes brainstorming]
"Let me understand what you're building. Who's your target audience - junior engineers, senior engineers, or engineering managers?"
User: "Senior engineers who hate writing docs"
Agent: "Got it. What do you want them to do after reading - start writing better docs, advocate for documentation culture, or something else?"
User: "Change their mind that documentation is valuable"
Agent: [continues questions...]
Agent: [presents brief...]
Agent: [gets approval...]
Agent: [creates plan...]
Agent: [offers execution choice...]
User: "Batch execution"
Agent: [writes sections 1-3...]
Agent: "Checkpoint: Sections 1-3 complete (612 words). Continue?"
User: "Yes"
Agent: [writes sections 4-5...]
Agent: "Draft complete! Ready for review?"
User: "Yes"
Agent: [runs four-pass review...]
Agent: "Review complete. 2 critical issues found and fixed. Final article ready!"
Additional documentation is available in the docs/ directory:
docs/
├── DEVELOPMENT.md # Development overview & architecture details
├── SUMMARY.md # Implementation summary & project statistics
└── examples/
└── typescript-blog-post.md # Complete end-to-end writing walkthrough
| Document | Description |
|---|---|
| DEVELOPMENT.md | In-depth development guide covering project architecture, skill design, workflow details, and extension points |
| SUMMARY.md | Implementation summary with project statistics, file inventory, and feature highlights |
| typescript-blog-post.md | A complete example walkthrough: writing a TypeScript blog post from brainstorming to final review |
During a writing project, the workflow generates the following files:
docs/writing/
├── YYYY-MM-DD-topic-brief.md # Approved topic brief
├── YYYY-MM-DD-topic-plan.md # Detailed outline
├── drafts/
│ └── YYYY-MM-DD-topic/
│ ├── section-1-intro.md # Individual section drafts
│ ├── section-2-argument.md
│ └── ...
├── YYYY-MM-DD-topic-draft.md # Merged full draft
├── YYYY-MM-DD-topic-review.md # Review log
└── YYYY-MM-DD-topic-final.md # Published version
Everything is version-controlled and traceable.
| Code (superpowers) | Content (document-superpowers) |
|---|---|
| brainstorming → design doc | brainstorming → topic brief |
| writing-plans → implementation plan | writing-article-plan → article outline |
| executing-plans → code | executing-article-plan → draft |
| requesting-code-review | reviewing-article |
| TDD (red-green-refactor) | write-check-revise |
| Git worktrees | Section drafts |
| Subagent per task | Subagent per section |
Every article goes through the full process, even "simple" blog posts. Simple topics can have short briefs (a few sentences), but you MUST present and approve the brief before writing.
The agent never overwhelms you with multiple questions. Brainstorming is a conversation, not a form to fill out.
Sections are 150-400 words - small enough to write in one sitting (15-30 minutes), large enough to develop an idea.
Review after every 2-3 sections. Catch issues early rather than discovering problems in a 3000-word wall of text.
Each pass focuses on one dimension:
- Logic (is it sound?)
- Evidence (is it supported?)
- Flow (is it smooth?)
- Polish (is it clean?)
Mixing concerns makes issues harder to spot.
Every stage produces artifacts:
- Brief (topic understanding)
- Plan (writing blueprint)
- Section drafts (incremental progress)
- Review log (all issues and fixes)
- Final article (publication-ready)
Trust the process - It feels slower at first, but produces better results faster than iterative rewrites.
Be specific in brainstorming - The clearer your answers, the better the brief.
Review checkpoints seriously - Don't just rubber-stamp. Actually read the sections.
Save the review log - It's valuable documentation of your writing decisions.
Enforce the gates - Never skip brainstorming, even for "simple" articles.
Ask better questions - Multiple choice > open-ended when possible.
Self-check rigorously - Catch your own issues before human review.
Preserve what works - Don't over-edit during review. Fix problems, keep strengths.
Create templates for specific document types:
skills/brainstorming/templates/
├── blog-post.md
├── technical-guide.md
├── api-documentation.md
└── research-paper.md
Add organization-specific style guidelines:
skills/reviewing-article/style-guides/
├── ap-style.md
├── company-voice.md
└── technical-writing.md
Use with other skills:
- research skills - Gather evidence during planning
- SEO skills - Optimize during review
- publishing skills - Deploy after finalization
Skills live directly in this repository. To contribute:
- Fork the repository
- Create a branch for your improvement
- Follow the existing skill structure (see
skills/writing-skills/in obra/superpowers for guidelines) - Test with real writing projects
- Submit a PR
Agent skips brainstorming:
- Check that skill descriptions are properly registered
- Ensure HARD-GATE instructions are present in SKILL.md
Sections too long/short:
- Adjust word targets in the plan
- Review if key points need more/less development
Review finds nothing:
- This might indicate shallow review
- Try providing specific examples of what to look for
Subagent fails repeatedly:
- Plan may be unclear - revise specifications
- Task brief may need more context
- Consider switching to batch execution
MIT License - see LICENSE file for details
This project is heavily inspired by obra/superpowers by Jesse Vincent. The systematic, gate-driven approach from code development translates beautifully to content creation.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Happy writing! 📝