<p align="center">
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:4B0082,100:6A5ACD&height=200§ion=header&text=Writing%20With%20Agents&fontSize=42&fontColor=ffffff&animation=fadeIn&fontAlignY=35" width="100%" alt="Writing With Agents" />
</p>
<p align="center">
<!-- SKILL_COUNT -->10<!-- /SKILL_COUNT --> Skills · <!-- REFERENCE_COUNT -->35<!-- /REFERENCE_COUNT --> References · <!-- WORKFLOW_COUNT -->5<!-- /WORKFLOW_COUNT --> Workflows
</p>
<p align="center">
<img src="https://img.shields.io/badge/version-0.3.2-blue.svg" alt="Version" />
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" />
<img src="https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet.svg" alt="Claude Code Plugin" />
<a href="https://claude.ai/customize/plugins/id/f54e0a10-f5d3-48c4-addb-2c74360c8130%40anthropic-plugin-directory"><img src="https://img.shields.io/badge/Claude_Plugin_Directory-listed-D97757" alt="Claude Plugin Directory: Listed" /></a>
<a href="https://github.com/Jeffallan/writing-with-agents/stargazers"><img src="https://img.shields.io/github/stars/Jeffallan/writing-with-agents" alt="GitHub Stars" /></a>
</p>
## Why this exists
Most AI writing tools mix brainstorming, structuring, and editing into a single prompt. The result is flat, mediocre output that sounds like everything else. Betty Flowers identified in 1981 that writing requires four distinct cognitive modes. Mixing them produces internal conflict: your inner critic shuts down your inner generator before it can produce anything worth editing.
This plugin gives each mode its own skill, workflow, and quality gates. The AI and human trade leadership at every phase: AI generates raw volume when quantity matters, human decides structure when judgment matters.
## What this is
A Claude Code plugin that separates the writing process into five phases, each with a defined lead and support role:
| Phase | Lead | Support | Deliverable |
|-------|------|---------|-------------|
| Madman | AI generates | Human seeds with experience | Raw material dump |
| Whirlybird | AI generates options | Human selects and combines | Chosen mindmap diagram |
| Architect | Human decides | AI formulates | Structured blueprint |
| Carpenter | AI builds | Human spot-checks | Complete draft |
| Judge | AI detects | Human decides | Polished final piece |
This project calls the lead and support split the **collaborative oscillation model**.
## Installation
### Option 1: From the Claude plugin directory
Writing With Agents is listed in the Claude plugin directory for Claude Code, Cowork, and the Claude apps.
- **claude.ai (Cowork and the Claude apps):** open Customize, then Plugins, and search for "Writing With Agents". You can also open the [directory listing](https://claude.ai/customize/plugins/id/f54e0a10-f5d3-48c4-addb-2c74360c8130%40anthropic-plugin-directory) directly; it requires a claude.ai sign-in.
- **Claude Code:** run `/plugin`, open Discover, search for "Writing With Agents" (Anthropic Directory), and install it at user, project, or local scope.
Directory installs receive a new version after Anthropic reviews it, so they can trail the GitHub release by a few days.
### Option 2: Claude Code plugin marketplace (native)
Inside Claude Code, add this repo as a plugin marketplace and install the plugin:
```
/plugin marketplace add Jeffallan/writing-with-agents
/plugin install writing-with-agents@writing-with-agents
```
If you're already in a session, run `/reload-plugins` to activate.
### Option 3: skills.sh via npx
```bash
npx skills add Jeffallan/writing-with-agents
```
Add `-g` to install globally across all projects.
The full documentation is at [jeffallan.github.io/writing-with-agents](https://jeffallan.github.io/writing-with-agents).
## Quick start
### Write a single article
```
/writing-with-agents:flowers-cycle "API-first identity verification for fintech"
```
This runs the full Flowers cycle: Madman, Whirlybird, Architect, Carpenter, Judge, Quality Rubric.
### With SEO optimization
```
/writing-with-agents:flowers-cycle "API-first identity verification" --seo
```
### Plan a multi-article strategy
```
/writing-with-agents:content-strategy /path/to/research/notes
```
### Capture a research source
```
/writing-with-agents:capture /path/to/note.md https://example.com/article
```
### Configure session defaults
```
/writing-with-agents:writing-setup
```
## Final Prose rule
Add this rule to a `CLAUDE.md` file so Claude runs `human-voice` in embedded mode on finished deliverables before handing them over:
```markdown
## Final Prose
Before delivering a final deliverable, run the
writing-with-agents:human-voice command on it in embedded mode and deliver
its output. Final deliverables are finished content intended to be read
by humans, such as READMEs, documentation pages, articles, release notes,
and PR descriptions.
Does not apply to commit messages, code comments, changelog entries, code,
command output, drafts in progress, or conversational replies.
```
Put it in a project's `CLAUDE.md` to cover one repository, or in `~/.claude/CLAUDE.md` to cover every project. The rule runs once, on the finished deliverable.
Each run reads the full human-voice catalog (about 5,000 words), which is why the list covers finished deliverables only. Commit messages, code comments, and changelog entries are small and frequent, and the cost of a pass on each one outweighs the gain.
The rule calls the plugin's `human-voice` command, so the writing-with-agents plugin must be installed.
## Skills
### Inner loop (single article)
| Skill | Domain | What it does |
|-------|--------|-------------|
| `madman` | generation | Generates 3-5x raw material from human-seeded topics across 8 dimensions, putting quantity ahead of quality at this stage. |
| `whirlybird` | structure | Produces nonlinear Mermaid mindmaps. Human selects and combines branches into a working outline. |
| `architect` | structure | Builds a throughline and section blueprint from the chosen outline. Human leads structural decisions. |
| `carpenter` | craft | Constructs full prose from the blueprint. Human spot-checks voice, tone, and accuracy. |
| `judge` | quality | Runs 5 editing passes (AI voice from a vendored human-voice catalog, Strunk & White, readability, consistency, SEO). Human approves changes before any edits. |
| `quality-rubric` | quality | Scores across 10 dimensions (1-5 scale). Routes any dimension below 4 back to the responsible phase for targeted rework. |
### Cross-cutting
| Skill | Domain | What it does |
|-------|--------|-------------|
| `seo-writer` | seo | Integrates during Architect (keyword mapping), Carpenter (natural placement), and Judge (validation), so SEO shapes the article from the outline onward. |
### Outer loop (multi-article)
| Skill | Domain | What it does |
|-------|--------|-------------|
| `research-intake` | research | Ingests sources into structured research notes and identifies gaps in coverage. |
| `content-strategist` | strategy | Maps a domain into a multi-article content plan with prioritized topics and linking strategy. |
| `knowledge-harvester` | research | Captures insights from completed articles back into the research vault for future use. |
## Workflow commands
| Command | Description |
|---------|-------------|
| `/writing-with-agents:flowers-cycle` | Single-article inner loop (6 phases) |
| `/writing-with-agents:content-strategy` | Multi-article outer loop (6 phases) |
| `/writing-with-agents:capture` | Capture source into structured research note |
| `/writing-with-agents:writing-setup` | Configure session defaults |
| `/writing-with-agents:human-voice` | Remove AI-voice tells from a draft, README, docstring, or commit message; `--embedded` returns only the final text |
## Architecture
### Two loops
```
Outer Loop (runs once per domain):
Intake --> Gap Analysis --> Domain Mapping --> Content Plan --> [Inner Loop per article] --> Knowledge Harvest
Inner Loop (runs once per article):
Madman --> Whirlybird --> Architect --> Carpenter --> Judge --> Quality Rubric
```
### Progressive disclosure
Each skill loads in two tiers:
- Tier 1 (SKILL.md): ~80-100 lines with role, triggers, workflow, constraints, routing table
- Tier 2 (references/): Detailed procedural content loaded only when context requires
This reduces initial token usage by ~50%. In practice, each skill conversation starts with ~80-100 lines instead of 400+, so more of your context window is left for the content you are writing.
## Project structure
```
writing-with-agents/
.claude-plugin/
marketplace.json
plugin/ (everything the plugin ships)
.claude-plugin/
plugin.json
LICENSE
README.md
skills/
madman/ (SKILL.md + 3 references)
whirlybird/ (SKILL.md + 3 references)
architect/ (SKILL.md + 3 references)
carpenter/ (SKILL.md + 4 references)
judge/ (SKILL.md + 6 references)
quality-rubric/ (SKILL.md + 2 references)
seo-writer/ (SKILL.md + 7 references)
content-strategist/ (SKILL.md + 3 references)
research-intake/ (SKILL.md + 2 references)
knowledge-harvester/ (SKILL.md + 2 references)
commands/
writing/
flowers-cycle/ (COMMAND.md + yaml)
content-strategy/ (COMMAND.md + yaml)
capture/ (COMMAND.md + yaml)
utilities/
writing-setup/ (COMMAND.md + yaml)
human-voice/ (COMMAND.md + yaml)
workflow-manifest.yaml
references/
capture/ (capture-note-template.md)
scripts/
validate-skills.py
validate-markdown.py
update-docs.py
docs/workflow/
CLAUDE.md
version.json
```
## Author
Built by [**jeffallan**](https://jeffallan.github.io) [<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/linkedin/linkedin-original.svg" width="16" height="16" alt="LinkedIn"/>](https://www.linkedin.com/in/jeff-smolinski/)
**Principal Consultant** at [**Synergetic Solutions**](https://synergetic.solutions) [<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/linkedin/linkedin-original.svg" width="16" height="16" alt="LinkedIn"/>](https://www.linkedin.com/company/synergetic-holdings)
Fullstack engineering, security engineering, compliance, and technical due diligence.
## Attribution
Based on Betty S. Flowers' "Madman, Architect, Carpenter, Judge: Roles and the Writing Process" (*Language Arts*, Vol. 58, No. 7, October 1981). Extended with Bryan Garner's whirlybird technique from *The Winning Brief*.
Collaborative oscillation model developed through dialectic conversation between the maintainer ([@jeffallan](https://github.com/jeffallan)) and Claude (Anthropic).
Plugin structure adapted from [fullstack-dev-skills](https://github.com/jeffallan/claude-skills) by [@jeffallan](https://github.com/jeffallan).
The Judge's human-voice pattern catalog is vendored from [humanizer](https://github.com/blader/humanizer) v3.1.0 by Siqi Chen (MIT License), based on Wikipedia's [Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing).
## License
MIT