README

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, each demanding a different kind of thinking. 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 is the collaborative oscillation model: not AI-only automation, not human-only writing. Each phase leverages what each party does best.

Installation

Option 1: 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@Jeffallan/writing-with-agents

If you’re already in a session, run /reload-plugins to activate.

Option 2: skills.sh via npx

npx skills add Jeffallan/writing-with-agents

Add -g to install globally across all projects.

Full documentation: 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

Skills

Inner Loop (Single Article)

Skill	Domain	What It Does
`madman`	generation	Generates 3-5x raw material from human-seeded topics across 8 dimensions. Quantity over quality.
`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, 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). Not a post-draft bolt-on.

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

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+, preserving your context window for actual content.

Project Structure

writing-with-agents/
  .claude-plugin/
    plugin.json
    marketplace.json
  skills/
    madman/          (SKILL.md + 3 references)
    whirlybird/      (SKILL.md + 3 references)
    architect/       (SKILL.md + 3 references)
    carpenter/       (SKILL.md + 3 references)
    judge/           (SKILL.md + 5 references)
    quality-rubric/  (SKILL.md + 2 references)
    seo-writer/      (SKILL.md + 5 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 + references/)
    utilities/
      writing-setup/    (COMMAND.md + yaml)
    workflow-manifest.yaml
  scripts/
    validate-skills.py
    validate-markdown.py
    update-docs.py
  docs/workflow/
  CLAUDE.md
  version.json

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 Jeff (Synergetic Solutions) and Claude (Anthropic).

Plugin structure adapted from fullstack-dev-skills by Jeff Allan (@jeffallan).

License

MIT