← back to Cli Printing Press

fix(skill): enforce 5-phase loop with inlined research and phase gates v1.0.0

44daea3a2821eb3db9f2eb1925ec1c6bc71e11bc · 2026-03-25 15:25:46 -0700 · Matt Van Horn

Three root causes fixed:
1. Installed skill was v0.3.0 (no loop) - now symlinked to repo
2. Skill-within-skill invocation (Skill tool removed from allowed-tools) -
   research and audit are now inlined with explicit WebSearch/Read/Edit calls
3. No phase gates - each phase now has MANDATORY markers and artifact requirements

Expected run time: 10-20 minutes (was 1m42s with the old skill).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Files touched

• A docs/plans/2026-03-25-fix-printing-press-skill-loop-enforcement-plan.md
• M skills/printing-press/SKILL.md

Diff

commit 44daea3a2821eb3db9f2eb1925ec1c6bc71e11bc
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date:   Wed Mar 25 15:25:46 2026 -0700

    fix(skill): enforce 5-phase loop with inlined research and phase gates v1.0.0
    
    Three root causes fixed:
    1. Installed skill was v0.3.0 (no loop) - now symlinked to repo
    2. Skill-within-skill invocation (Skill tool removed from allowed-tools) -
       research and audit are now inlined with explicit WebSearch/Read/Edit calls
    3. No phase gates - each phase now has MANDATORY markers and artifact requirements
    
    Expected run time: 10-20 minutes (was 1m42s with the old skill).
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ...x-printing-press-skill-loop-enforcement-plan.md | 264 +++++++++++
 skills/printing-press/SKILL.md                     | 511 +++++++++++++++------
 2 files changed, 630 insertions(+), 145 deletions(-)

diff --git a/docs/plans/2026-03-25-fix-printing-press-skill-loop-enforcement-plan.md b/docs/plans/2026-03-25-fix-printing-press-skill-loop-enforcement-plan.md
new file mode 100644
index 00000000..b75fc247
--- /dev/null
+++ b/docs/plans/2026-03-25-fix-printing-press-skill-loop-enforcement-plan.md
@@ -0,0 +1,264 @@
+---
+title: "Fix Printing Press Skill: Enforce the 5-Phase Loop"
+type: fix
+status: completed
+date: 2026-03-25
+---
+
+# Fix: Printing Press Skill Loop Enforcement
+
+## Problem Statement
+
+The printing-press skill is supposed to run a 5-phase loop that takes 15-20 minutes:
+
+```
+ce:plan (RESEARCH) -> ce:work (GENERATE) -> ce:plan (AUDIT) -> ce:work (FIX) -> SCORE
+```
+
+Instead, it completes in 1m42s by finding a spec, running the generator, and presenting results. No research, no audit, no fixes, no scoring. The output is "dumb" - it compiles but hasn't been compared against competitors, polished, or scored.
+
+## Root Cause Analysis
+
+There are **three cascading failures**, not one:
+
+### RC1: Version mismatch (the installed skill is v0.3.0, not v0.6.0)
+
+The installed skill at `~/.claude/skills/printing-press/SKILL.md` is **v0.3.0**. It has zero awareness of the plan-execute-plan-execute loop. It just searches for a spec, runs `printing-press generate`, and presents the output.
+
+The v0.6.0 skill with the loop exists only in the repo at `~/cli-printing-press/skills/printing-press/SKILL.md`. The commit `68f63167` ("restore plan-execute-plan-execute loop") updated the repo copy but **never synced it to the installed location**.
+
+This is the primary reason the Notion run took 1m42s - it literally followed v0.3.0 instructions, which have no loop.
+
+### RC2: Skill-within-skill invocation is fragile
+
+Even v0.6.0 has a structural problem. It instructs Claude to call:
+```
+Skill("compound-engineering:ce:plan", "docs/plans/<date>-feat-<api>-cli-research-plan.md")
+```
+
+This is a skill invoking another skill via the Skill tool. In practice, Claude shortcuts through this because:
+- The printing-press skill is already loaded and executing
+- Claude treats the `Skill()` call as a suggestion, not a hard gate
+- There's no structural enforcement that ce:plan actually ran before proceeding to the next phase
+- Claude optimizes for speed and skips phases it thinks are optional
+
+### RC3: No phase gates or timing enforcement
+
+The skill says "always do phases 1-5" but provides no way to verify each phase completed. There are no:
+- Phase completion markers (files that must exist before the next phase starts)
+- Minimum time expectations (a 2-minute run should be flagged as suspicious)
+- Output requirements (each phase must produce a specific artifact)
+- Blocking checks (don't start Phase 3 until Phase 2's output directory exists)
+
+## Proposed Solution
+
+### Fix 1: Sync the skill (immediate)
+
+Copy v0.6.0+ from the repo to the installed location:
+```bash
+cp ~/cli-printing-press/skills/printing-press/SKILL.md ~/.claude/skills/printing-press/SKILL.md
+```
+
+Add a sync reminder to CLAUDE.md or create a sync script.
+
+### Fix 2: Inline the loop instead of calling sub-skills
+
+Replace `Skill("compound-engineering:ce:plan", ...)` calls with **inline instructions that do the research and audit directly**. The printing-press skill already has WebSearch, WebFetch, Read, Write, Edit, and Agent in its allowed-tools. It doesn't need to delegate to ce:plan - it can do the research itself.
+
+This eliminates the fragile skill-within-skill invocation entirely.
+
+### Fix 3: Add phase gates with artifact requirements
+
+Each phase must produce a specific artifact file. The next phase cannot start until the previous artifact exists and is non-empty.
+
+| Phase | Artifact | Minimum Content |
+|-------|----------|----------------|
+| 1: RESEARCH | `docs/plans/<date>-feat-<api>-cli-research.md` | Spec URL or docs URL, competitor list with command counts, auth method |
+| 2: GENERATE | `<api>-cli/cmd/<api>-cli/main.go` | Generated CLI directory with passing quality gates |
+| 3: AUDIT | `docs/plans/<date>-fix-<api>-cli-audit.md` | Audit checklist with findings, specific fix list with file paths |
+| 4: FIX | Compilation passes after edits | `go build ./...` succeeds in the CLI directory |
+| 5: SCORE | Score output presented to user | Steinberger dimensions, grade, competitor comparison |
+
+### Fix 4: Make phases explicit and unambiguous in the skill
+
+Rewrite the skill with a rigid phase structure. Each phase has:
+1. A **STOP** marker that says "DO NOT PROCEED until this phase is complete"
+2. Explicit tool calls to make (not suggestions)
+3. Required outputs that must be produced
+4. A phase transition check
+
+## Acceptance Criteria
+
+- [ ] Installed skill at `~/.claude/skills/printing-press/SKILL.md` matches repo version
+- [ ] Skill does NOT call `Skill("compound-engineering:ce:plan", ...)` - research/audit are inlined
+- [ ] Phase 1 (RESEARCH) performs at least 3 WebSearches and produces a research artifact
+- [ ] Phase 2 (GENERATE) runs the printing-press binary and produces a compiled CLI
+- [ ] Phase 3 (AUDIT) reads generated code, compares against competitors, writes specific fixes
+- [ ] Phase 4 (FIX) edits generated code and verifies compilation
+- [ ] Phase 5 (SCORE) runs scorecard or presents a structured quality assessment
+- [ ] A `/printing-press Notion` run takes 10-20 minutes, not under 5
+- [ ] Each phase produces a visible output to the user (not silent)
+- [ ] Sync script or instructions exist so installed version doesn't drift from repo again
+
+## Technical Approach
+
+### New SKILL.md Structure (v1.0.0)
+
+The rewritten skill will have this structure:
+
+```
+# Phase 1: RESEARCH
+## MANDATORY - DO NOT SKIP
+### Step 1.1: Search for OpenAPI spec
+### Step 1.2: Search for competing CLIs
+### Step 1.3: Fetch and analyze competitor READMEs
+### Step 1.4: Write research summary
+### PHASE GATE: Verify research artifact exists
+
+# Phase 2: GENERATE
+## MANDATORY - DO NOT SKIP
+### Step 2.1: Download spec or write from docs
+### Step 2.2: Run printing-press generate
+### Step 2.3: Verify quality gates pass
+### PHASE GATE: Verify CLI directory exists and compiles
+
+# Phase 3: AUDIT
+## MANDATORY - DO NOT SKIP
+### Step 3.1: Read all generated Go files
+### Step 3.2: Check command count vs competitors
+### Step 3.3: Review help descriptions for jargon
+### Step 3.4: Check for missing endpoints
+### Step 3.5: Write audit findings
+### PHASE GATE: Verify audit artifact has specific fixes
+
+# Phase 4: FIX
+## MANDATORY - DO NOT SKIP
+### Step 4.1: Execute each fix from the audit
+### Step 4.2: Verify compilation after fixes
+### PHASE GATE: go build ./... passes
+
+# Phase 5: SCORE + REPORT
+## MANDATORY - DO NOT SKIP
+### Step 5.1: Run scorecard or manual quality assessment
+### Step 5.2: Present final report with all required sections
+```
+
+### Key Design Decisions
+
+1. **Inline research, not delegated** - The skill does its own WebSearches and WebFetches directly. No calling ce:plan as a sub-skill. This is more reliable because the instructions execute in the same context.
+
+2. **Agent tool for parallel research** - Phase 1 can use the Agent tool to run parallel research queries (spec search, competitor search, demand signals) for speed without sacrificing thoroughness.
+
+3. **Explicit file reads in audit** - Phase 3 must `Read` the generated files, not just run `go vet`. It needs to actually read `root.go`, `command.go` files, the `readme.md`, and compare against competitor command lists.
+
+4. **Edit tool for fixes** - Phase 4 uses the Edit tool to make targeted improvements to help text, examples, and README. Not regeneration - surgical fixes.
+
+5. **Scorecard is optional but quality assessment is not** - If the Go scorecard test exists and works, run it. If not, do a manual structured assessment against the 8 Steinberger dimensions. Either way, a score must be presented.
+
+### Research Phase Detail (Phase 1)
+
+The research phase should take 3-5 minutes and produce:
+
+```markdown
+# Research: <API> CLI
+
+## Spec Discovery
+- Official OpenAPI spec: <url> (or "none found")
+- Source: <where it was found>
+- Version: <API version>
+- Endpoints: <count>
+
+## Competitors
+| Name | Stars | Language | Commands | Notable Features |
+|------|-------|----------|----------|-----------------|
+| ... | ... | ... | ... | ... |
+
+## Auth Method
+- Type: <api_key/oauth2/bearer_token>
+- Header: <header name>
+- Env var convention: <what competitors use>
+
+## Demand Signals
+- <any Reddit/HN/X posts asking for a CLI for this API>
+
+## Recommendation
+- Spec source: <OpenAPI vs write from docs>
+- Target command count: <match or beat best competitor>
+- Key differentiator: <what our CLI should do that competitors don't>
+```
+
+### Audit Phase Detail (Phase 3)
+
+The audit phase should take 3-5 minutes and produce:
+
+```markdown
+# Audit: <API> CLI
+
+## Command Comparison
+- Our CLI: <N> commands across <M> resources
+- Best competitor: <name> with <N> commands
+- Gap: <what we're missing>
+
+## Help Text Quality
+- [ ] Descriptions are developer-friendly (not raw spec jargon)
+- [ ] Examples use realistic values (not "string" or "0")
+- [ ] Resource descriptions explain WHAT the resource is
+
+## Agent-Native Checklist
+- [ ] --json flag present
+- [ ] --select flag present
+- [ ] --dry-run flag present
+- [ ] --stdin flag present
+- [ ] Typed exit codes documented
+- [ ] doctor command works
+
+## Specific Fixes Needed
+1. File: <path> - Change: <what to fix>
+2. File: <path> - Change: <what to fix>
+...
+```
+
+## Sync Strategy
+
+To prevent installed/repo drift:
+
+**Option A: Symlink** (preferred)
+```bash
+ln -sf ~/cli-printing-press/skills/printing-press/SKILL.md ~/.claude/skills/printing-press/SKILL.md
+```
+
+**Option B: Sync script** (add to existing workflow)
+```bash
+# In ~/cli-printing-press/scripts/sync-skill.sh
+cp skills/printing-press/SKILL.md ~/.claude/skills/printing-press/SKILL.md
+echo "Synced printing-press skill v$(grep 'version:' skills/printing-press/SKILL.md | awk '{print $2}')"
+```
+
+**Option C: Post-commit hook** (automatic)
+Add to `.git/hooks/post-commit`:
+```bash
+if git diff --name-only HEAD~1 HEAD | grep -q "skills/printing-press/SKILL.md"; then
+  cp skills/printing-press/SKILL.md ~/.claude/skills/printing-press/SKILL.md
+fi
+```
+
+## Implementation Steps
+
+1. **Rewrite SKILL.md to v1.0.0** with inlined phases, phase gates, and explicit instructions
+2. **Sync to installed location** using symlink (Option A)
+3. **Test with `/printing-press Notion`** - verify it takes 10-20 minutes and produces all 5 phase artifacts
+4. **Test with `/printing-press Stripe`** - verify it works with a known-spec API too
+5. **Commit and push**
+
+## Success Metrics
+
+- A `/printing-press <API>` run takes 10-20 minutes
+- Research artifact is produced with competitor analysis
+- Audit artifact is produced with specific fix list
+- Generated CLI has polished help text and realistic examples
+- Final report includes competitor comparison and quality score
+- User can see each phase's progress as it happens (not silent)
+
+## Risk: Over-engineering the enforcement
+
+The skill could become so rigid that it breaks on edge cases (API with no competitors, already-perfect generation, etc.). Mitigation: each phase has a "nothing to fix" fast path that still produces the artifact but notes "no issues found."
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index aca60b0f..8793d412 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -1,265 +1,486 @@
 ---
 name: printing-press
-description: Generate production Go CLIs from any API. Uses ce:plan for deep research before generating, then ce:plan again to audit the output, then ce:work to fix it. Plan-execute-plan-execute loop.
-version: 0.6.0
+description: Generate production Go CLIs from any API. 5-phase loop - research, generate, audit, fix, score. Each phase is mandatory with artifact gates.
+version: 1.0.0
 allowed-tools:
   - Bash
   - Read
   - Write
+  - Edit
   - Glob
   - Grep
   - WebFetch
   - WebSearch
   - AskUserQuestion
-  - Skill
   - Agent
-  - Edit
-  - CronCreate
-  - CronList
-  - CronDelete
 ---
 
 # /printing-press
 
-Generate a production Go CLI from any API. Claude Code is the brain. The Go binary is the template engine.
-
-**The loop:** ce:plan (research) -> ce:work (generate) -> ce:plan (audit) -> ce:work (fix) -> report
-
-## Quick Start
+Generate a production Go CLI from any API. Five mandatory phases. No shortcuts.
 
 ```
 /printing-press Notion
 /printing-press Plaid payments API
 /printing-press --spec ./openapi.yaml
+/printing-press --spec https://raw.githubusercontent.com/.../openapi.json
 ```
 
 ## Prerequisites
 
 - Go 1.21+ installed
 - The printing-press repo at `~/cli-printing-press`
-- Build: `cd ~/cli-printing-press && go build -o ./printing-press ./cmd/printing-press`
+- Build binary if missing: `cd ~/cli-printing-press && go build -o ./printing-press ./cmd/printing-press`
 
-## Workflow 0: Natural Language (Primary)
+## How This Works
 
-When the user provides an API name:
+Every run goes through 5 mandatory phases. You cannot skip phases. Each phase produces an artifact that the next phase needs.
 
-### Phase 1: RESEARCH (ce:plan does this)
+```
+PHASE 1: RESEARCH  ->  PHASE 2: GENERATE  ->  PHASE 3: AUDIT  ->  PHASE 4: FIX  ->  PHASE 5: SCORE
+ (3-5 min)              (1-2 min)               (3-5 min)           (2-3 min)          (1 min)
+```
 
-Write a research plan file, then let ce:plan expand it with deep research.
+Total expected time: 10-20 minutes. If a run completes in under 5 minutes, something was skipped.
 
-**Step 1: Write the research plan seed**
+---
 
-```bash
-mkdir -p ~/cli-printing-press/docs/plans
-```
+## Workflow: `--spec` shortcut
+
+When the user provides `--spec <path-or-url>`, skip Phase 1 (spec is provided). Run Phases 2-5.
+
+## Workflow: Natural Language (Primary)
+
+When the user provides an API name, run ALL five phases.
+
+### Step 0: Parse intent and check known specs
+
+Extract the API name from the user's message. Check `~/cli-printing-press/skills/printing-press/references/known-specs.md` for a known spec URL.
+
+If found in registry: note the URL for Phase 2, but STILL run Phase 1 research (competitors, demand signals).
+If not found: Phase 1 will also search for the spec.
+
+---
+
+# PHASE 1: RESEARCH
+
+## THIS PHASE IS MANDATORY. DO NOT SKIP IT.
+
+Research the API landscape before generating anything. You need to know what exists so you can beat it.
+
+### Step 1.1: Search for the OpenAPI spec
+
+If not found in known-specs registry:
+
+1. **WebSearch**: `"<API name>" openapi spec site:github.com`
+2. **WebSearch**: `"<API name>" openapi.yaml OR openapi.json specification`
+3. Try common URL patterns:
+   - `https://raw.githubusercontent.com/<org>/openapi/main/openapi.yaml`
+   - `https://api.<domain>/openapi.json`
+4. If a URL is found, **WebFetch** the first 500 bytes to verify it contains `openapi:` or `"openapi"` or `swagger:`
+
+If no spec found after these searches: plan to write one from docs in Phase 2.
+
+### Step 1.2: Search for competing CLIs
+
+**WebSearch**: `"<API name>" CLI tool github`
+**WebSearch**: `"<API name>" command line client`
+
+For each competitor found:
+- Note the repo URL, star count, language
+- **WebFetch** their README to count commands and note features
+- Look for: how many resources/commands, what auth methods, output formats, any unique features
+
+### Step 1.3: Check demand signals
+
+**WebSearch**: `"<API name>" "need a CLI" OR "command line" OR "CLI tool" site:reddit.com OR site:news.ycombinator.com`
+
+Note any posts asking for a CLI for this API. This tells us there's demand.
+
+### Step 1.4: Write the research artifact
+
+**Write** to `~/cli-printing-press/docs/plans/<today>-feat-<api>-cli-research.md`:
 
-Write to `docs/plans/<date>-feat-<api>-cli-research-plan.md`:
 ```markdown
 ---
-title: "Research for <API> CLI generation"
+title: "Research: <API> CLI"
 type: feat
 status: active
 date: <today>
 ---
 
-# Research for <API> CLI
+# Research: <API> CLI
 
-## What to Find
-1. OpenAPI spec (search GitHub, apis-guru, common URLs)
-2. Competing CLIs (GitHub search: "<api> cli", note stars, language, commands)
-3. API documentation URL
-4. Auth method
-5. Community demand signals (Reddit, HN mentions of needing a CLI)
+## Spec Discovery
+- Official OpenAPI spec: <url or "none found - will write from docs">
+- Source: <where found - registry, GitHub search, etc.>
+- Format: <OpenAPI 3.x / Swagger 2.0 / internal YAML>
 
-## What to Produce
-- Spec URL (or determination that we need to write one from docs)
-- List of competitors with command counts
-- Recommendation: use OpenAPI spec vs write from docs
-```
+## Competitors
+| Name | Stars | Language | Commands | Notable Features |
+|------|-------|----------|----------|-----------------|
+| <name> | <stars> | <lang> | <count> | <features> |
+
+## Auth Method
+- Type: <api_key / oauth2 / bearer_token>
+- Header: <name>
+- Env var convention: <what competitors use, e.g. NOTION_API_KEY>
 
-**Step 2: Run ce:plan to expand the research**
+## Demand Signals
+- <Reddit/HN posts, or "none found">
 
+## Recommendation
+- Spec source: <OpenAPI URL / write from docs>
+- Target command count: <N - match or beat best competitor>
+- Key differentiator: agent-native (--json, --select, --dry-run, --stdin, typed exit codes)
 ```
-Skill("compound-engineering:ce:plan", "docs/plans/<date>-feat-<api>-cli-research-plan.md")
+
+### PHASE GATE 1
+
+**STOP.** Before proceeding to Phase 2, verify:
+1. The research artifact file exists at `docs/plans/<today>-feat-<api>-cli-research.md`
+2. It has a Spec Discovery section with a URL or "write from docs" decision
+3. It has at least one competitor listed (or explicitly "no competitors found")
+
+Tell the user: "Phase 1 complete: Found [spec/no spec], [N] competitors. Best competitor: [name] with [N] commands. Proceeding to generation."
+
+---
+
+# PHASE 2: GENERATE
+
+## THIS PHASE IS MANDATORY. DO NOT SKIP IT.
+
+Generate the CLI using the printing-press binary.
+
+### Step 2.1: Get the spec ready
+
+**If OpenAPI spec was found:**
+```bash
+curl -sL -o /tmp/printing-press-spec-<api>.json "<spec-url>" && head -c 200 /tmp/printing-press-spec-<api>.json
 ```
 
-ce:plan will WebSearch, WebFetch competitor READMEs, analyze the landscape, and produce a comprehensive research plan with findings.
+**If no spec (write from docs):**
+1. **WebFetch** the API documentation URL
+2. **Read** `~/cli-printing-press/skills/printing-press/references/spec-format.md`
+3. Write a YAML spec to `/tmp/<api>-spec.yaml` following the format exactly
+4. Include ALL endpoints found in the docs - resources, methods, paths, params, body fields, auth
 
-**Step 3: Execute the research (manual - read ce:plan output)**
+### Step 2.2: Check for existing output directory
 
-Read the expanded plan. Extract:
-- The spec URL (OpenAPI or docs)
-- Competitor list with command counts
-- Auth method and base URL
+```bash
+cd ~/cli-printing-press && ls -la <api>-cli 2>/dev/null && echo "EXISTS" || echo "CLEAN"
+```
 
-### Phase 2: GENERATE (ce:work does this)
+If EXISTS: remove it first (`rm -rf <api>-cli`).
 
-**Step 4: Generate the CLI**
+### Step 2.3: Run the generator
 
-If OpenAPI spec was found:
 ```bash
 cd ~/cli-printing-press && ./printing-press generate \
-  --spec "<spec-url>" \
+  --spec /tmp/printing-press-spec-<api>.json \
   --output ./<api>-cli \
-  --force --lenient
+  --force --lenient --validate 2>&1
+```
+
+If the binary doesn't exist:
+```bash
+cd ~/cli-printing-press && go build -o ./printing-press ./cmd/printing-press
+```
+
+### Step 2.4: Handle quality gate failures
+
+If gates fail: read the error output carefully. Common fixes:
+- Spec description issues: clean the spec, retry
+- Module errors: `cd <api>-cli && go mod tidy`
+- Template errors: check if the spec has unusual types
+
+Max 3 retries. If still failing, present the error to the user.
+
+### PHASE GATE 2
+
+**STOP.** Before proceeding to Phase 3, verify:
+1. The directory `~/cli-printing-press/<api>-cli/` exists
+2. `cd ~/cli-printing-press/<api>-cli && go build ./...` succeeds
+3. All 7 quality gates passed (or you know which warnings are acceptable)
+
+Tell the user: "Phase 2 complete: Generated <api>-cli with [N] resources, [M] endpoints. All quality gates passed. Proceeding to audit."
+
+---
+
+# PHASE 3: AUDIT
+
+## THIS PHASE IS MANDATORY. DO NOT SKIP IT.
+
+Code-review the generated CLI against the research findings. This is where you find problems.
+
+### Step 3.1: Read the generated code
+
+You MUST actually read these files (not just check they exist):
+
 ```
+Read ~/cli-printing-press/<api>-cli/internal/cli/root.go
+Read ~/cli-printing-press/<api>-cli/README.md
+```
+
+Also read at least 2 resource command files:
+```
+Read ~/cli-printing-press/<api>-cli/internal/cli/<resource1>.go
+Read ~/cli-printing-press/<api>-cli/internal/cli/<resource2>.go
+```
+
+### Step 3.2: Count commands and compare
+
+Run:
+```bash
+cd ~/cli-printing-press/<api>-cli && grep -r "Use:" internal/cli/*.go | grep -v "root.go" | wc -l
+```
+
+Compare this count against the best competitor from Phase 1 research.
 
-If no spec (docs only): Claude Code reads the docs (WebFetch), writes a YAML spec, and generates from it. See "Writing Specs from Docs" section below.
+### Step 3.3: Check help text quality
 
-If quality gates fail: read error, fix spec, retry (max 3).
+Read the command files and check:
+- Are descriptions developer-friendly or raw OpenAPI spec jargon?
+- Do examples use realistic values or placeholder garbage like "string", "0", "example"?
+- Does the root command description explain what the API does?
 
-### Phase 3: AUDIT (ce:plan does this)
+### Step 3.4: Check for missing endpoints
 
-After the CLI is generated, write an audit plan and run ce:plan to expand it into a full code review.
+Compare the API's actual endpoints (from spec or docs) against what was generated. Look for:
+- Major resources that are missing entirely
+- Important CRUD operations that were skipped
+- Pagination endpoints that were missed
 
-**Step 5: Write the audit plan seed**
+### Step 3.5: Check agent-native features
+
+Verify these are present in root.go:
+- `--json` flag
+- `--select` flag
+- `--dry-run` flag
+- `--stdin` flag
+- `--yes` flag
+- `--no-cache` flag
+- `doctor` subcommand
+
+### Step 3.6: Review README quality
+
+Read the generated README.md. Check:
+- Does it explain how to install?
+- Does it have realistic examples?
+- Does it mention auth setup?
+- Does it document output formats?
+- Would you actually use this CLI based on the README?
+
+### Step 3.7: Write the audit artifact
+
+**Write** to `~/cli-printing-press/docs/plans/<today>-fix-<api>-cli-audit.md`:
 
-Write to `docs/plans/<date>-fix-<api>-cli-audit-plan.md`:
 ```markdown
 ---
-title: "Audit <API> CLI against competitors and quality bar"
+title: "Audit: <API> CLI"
 type: fix
 status: active
 date: <today>
 ---
 
-# Audit <API> CLI
+# Audit: <API> CLI
 
-## Generated CLI Location
-<output-dir>
+## Command Comparison
+- Our CLI: <N> commands across <M> resources
+- Best competitor: <name> with <N> commands
+- Gap: <what we're missing, or "we match/beat them">
 
-## Competitors Found
-<list from Phase 1 research>
+## Help Text Quality
+- [ ] Descriptions are developer-friendly: <PASS/FAIL + details>
+- [ ] Examples use realistic values: <PASS/FAIL + details>
+- [ ] Resource descriptions explain what the resource is: <PASS/FAIL + details>
 
-## Audit Checklist
-1. Command count: do we match or beat competitors?
-2. Help descriptions: are they developer-friendly or spec jargon?
-3. Examples: are they realistic or placeholder values?
-4. README: does it sell the tool or just describe it?
-5. Agent-native: --json, --select, --dry-run, --stdin, --yes all present?
-6. Missing endpoints: any important API operations we missed?
-7. Auth: does doctor validate credentials correctly?
+## Agent-Native Checklist
+- [x/] --json flag present
+- [x/] --select flag present
+- [x/] --dry-run flag present
+- [x/] --stdin flag present
+- [x/] Typed exit codes
+- [x/] doctor command
 
-## What to Produce
-- List of specific fixes needed (file path + what to change)
-- Honest assessment: is this CLI better than the competitors?
-```
+## README Quality
+- <honest assessment>
 
-**Step 6: Run ce:plan to do the audit**
+## Specific Fixes Needed
+1. File: `internal/cli/<file>.go` - Change: <what to fix and why>
+2. File: `README.md` - Change: <what to fix and why>
+...
 
-```
-Skill("compound-engineering:ce:plan", "docs/plans/<date>-fix-<api>-cli-audit-plan.md")
+## Fixes NOT Needed (Regeneration Required)
+- <anything that can't be fixed with Edit and requires re-running the generator>
 ```
 
-ce:plan will read the generated code, compare against competitors, check every item on the audit checklist, and write specific fix instructions.
+### PHASE GATE 3
 
-### Phase 4: FIX (ce:work does this)
+**STOP.** Before proceeding to Phase 4, verify:
+1. The audit artifact exists at `docs/plans/<today>-fix-<api>-cli-audit.md`
+2. It has specific fixes listed (file paths + what to change)
+3. You actually Read the generated code files (not just ran commands)
 
-**Step 7: Execute the fixes**
+Tell the user: "Phase 3 complete: Found [N] issues to fix. [summary of top issues]. Proceeding to fixes."
 
-```
-Skill("compound-engineering:ce:work", "docs/plans/<date>-fix-<api>-cli-audit-plan.md")
-```
+If the audit found ZERO issues (rare but possible): still write the artifact noting "No fixes needed - generated output meets quality bar." Then proceed to Phase 5 (skip Phase 4).
+
+---
+
+# PHASE 4: FIX
+
+## THIS PHASE IS MANDATORY (unless audit found zero issues).
+
+Execute the specific fixes identified in Phase 3's audit.
+
+### Step 4.1: Fix each issue from the audit
 
-ce:work will:
-- Edit help descriptions to be developer-friendly
-- Add realistic examples
-- Rewrite README to sell the tool
-- Add any missing endpoints noted in the audit
-- Verify fixes compile: `cd <output> && go build ./... && go vet ./...`
+For each fix listed in the audit artifact:
 
-### Phase 5: SCORE + REPORT
+1. **Read** the file that needs fixing
+2. **Edit** the specific lines (use the Edit tool, not Write - surgical changes)
+3. Verify the edit is correct
 
-**Step 8: Run the scorecard**
+Common fixes:
+- **Help text jargon**: Edit `Short` and `Long` descriptions in command files to be developer-friendly
+- **Bad examples**: Edit `Example` fields with realistic API values
+- **Missing resource description**: Edit the resource command's `Short` field
+- **README weak**: Edit sections of README.md to be more useful
+- **Missing endpoints**: Add new command entries (this may require more extensive edits)
+
+### Step 4.2: Verify compilation after ALL fixes
 
 ```bash
-cd ~/cli-printing-press && SCORECARD_CLI_DIR=./<api>-cli SCORECARD_PIPELINE_DIR=/tmp/<api>-score \
-  go test ./internal/pipeline/ -run TestScorecardOnRealCLI -v 2>&1 | tail -20
+cd ~/cli-printing-press/<api>-cli && go build ./... && go vet ./... && echo "FIXES VERIFIED"
 ```
 
-**Step 9: Present the final result**
+If compilation fails after edits: read the error, fix it, retry.
 
-Show ALL of these:
-1. Resources and commands (table)
-2. Steinberger score and grade
-3. Competitor comparison:
-   - "Found N competing CLIs"
-   - "Best competitor: X (Y stars, Z commands)"
-   - "We beat them on: ..."
-   - "We're missing: ..."
-4. Example commands with realistic values
-5. How to install
-6. Spec source
-7. Any limitations (skipped complex body fields, etc.)
+### PHASE GATE 4
 
-## Workflow 1: From Spec File
+**STOP.** Before proceeding to Phase 5, verify:
+1. All fixes from the audit have been applied
+2. `go build ./...` passes in the CLI directory
+3. `go vet ./...` passes
 
-`/printing-press --spec <path>`
+Tell the user: "Phase 4 complete: Applied [N] fixes. Compilation verified. Proceeding to scoring."
 
-Skip Phase 1 research (spec is provided). Run Phases 2-5.
+---
 
-## Workflow 2: From URL
+# PHASE 5: SCORE + REPORT
 
-`/printing-press --spec <url>`
+## THIS PHASE IS MANDATORY. DO NOT SKIP IT.
 
-Skip Phase 1 research. Run Phases 2-5.
+### Step 5.1: Quality assessment
 
-## Workflow 3: Submit to Catalog
+Score the CLI against these 8 dimensions (0-10 each):
 
-`/printing-press submit <name>`
+| Dimension | What to check | Score |
+|-----------|---------------|-------|
+| Output modes | --json, --select, --plain, --human-friendly all present? | /10 |
+| Auth | Correct auth type, doctor validates credentials, env var convention? | /10 |
+| Error handling | Typed exit codes (0,2,3,4,5,7,10), helpful error messages? | /10 |
+| Terminal UX | Color support, pagination, progress indicators? | /10 |
+| README | Install instructions, examples, troubleshooting, sells the tool? | /10 |
+| Doctor | Health check validates auth, API reachability? | /10 |
+| Agent-native | Non-interactive, pipeable, cacheable, idempotent creates/deletes? | /10 |
+| Breadth | Command count vs competitors, missing major endpoints? | /10 |
 
-1. Gather metadata
-2. Write `catalog/<name>.yaml`
-3. `git checkout -b catalog/<name> && git add && git commit && gh pr create`
+Total: /80. Grade: 65+ = A, 50-64 = B, <50 = needs work.
 
-## Workflow 4: Autonomous Pipeline
+Optionally, also try running the Go scorecard:
+```bash
+cd ~/cli-printing-press && SCORECARD_CLI_DIR=./<api>-cli SCORECARD_PIPELINE_DIR=/tmp/<api>-score \
+  go test ./internal/pipeline/ -run TestScorecardOnRealCLI -v -timeout 60s 2>&1 | tail -30
+```
 
-`/printing-press print <api-name>`
+### Step 5.2: Present the final report
 
-Full 8-phase pipeline with session chaining:
-preflight -> research -> scaffold -> enrich -> regenerate -> review -> comparative -> ship
+Show ALL of these sections to the user:
 
-Each phase: read seed plan -> ce:plan expands it -> ce:work executes -> chain to next session.
+**1. Summary table:**
+```
+Generated <api>-cli with <N> resources and <M> endpoints.
 
-Budget gate: 3 hours max. Morning report on completion.
+Resources: <comma-separated list>
+```
 
-See state.json and pipeline directory for phase tracking.
+**2. Quality score:**
+```
+Steinberger Score: <total>/80 (Grade <A/B/C>)
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| Output modes | X/10 | ... |
+| Auth | X/10 | ... |
+...
+```
+
+**3. Competitor comparison:**
+```
+Found <N> competing CLIs.
+Best competitor: <name> (<stars> stars, <commands> commands)
+We beat them on: <what we do better>
+We're missing: <what they have that we don't, or "nothing - we match or beat">
+```
+
+**4. Example commands:**
+```bash
+cd ~/cli-printing-press/<api>-cli
+go install ./cmd/<api>-cli
+
+export <AUTH_ENV_VAR>="..."
+
+<api>-cli --help
+<api>-cli <resource> list
+<api>-cli <resource> get --<id_param> <realistic_value>
+<api>-cli doctor
+```
+
+**5. Spec source:**
+```
+Spec: <source description and URL>
+```
+
+**6. Limitations (if any):**
+- Complex body fields skipped as CLI flags
+- Any endpoints that couldn't be represented
+- GraphQL APIs wrapped in YAML spec
+
+---
 
 ## Writing Specs from Docs
 
-When no OpenAPI spec exists and Claude Code needs to write one:
+When no OpenAPI spec exists and you need to write one:
 
-1. WebFetch the API documentation URL
-2. Read `~/cli-printing-press/skills/printing-press/references/spec-format.md`
-3. Claude Code reads the docs and identifies EVERY endpoint:
-   - Method, path, description, params, body fields, auth
-4. Write YAML spec to `/tmp/<api>-spec.yaml`
+1. **WebFetch** the API documentation URL
+2. **Read** `~/cli-printing-press/skills/printing-press/references/spec-format.md`
+3. Read the docs and identify EVERY endpoint: method, path, description, params, body fields, auth
+4. Write YAML spec to `/tmp/<api>-spec.yaml` following the format exactly
 5. Generate from it
 
-This is where Claude Code IS the brain. No regex. No shelling out.
+This is where you ARE the brain. No shelling out to an LLM. Read the docs yourself and write the spec.
 
-## Key Principle
+## Submit to Catalog
 
-**Plan-execute-plan-execute.** Never just generate and present. Always:
-1. Plan (research the API and competitors)
-2. Execute (generate the CLI)
-3. Plan again (audit the output, find problems)
-4. Execute again (fix the problems)
-5. Score and report
+`/printing-press submit <name>`
 
-This is what makes the press smart, not just fast.
+1. Gather metadata (name, description, category, spec_url, tier)
+2. Write `catalog/<name>.yaml`
+3. `git checkout -b catalog/<name> && git add catalog/<name>.yaml && git commit && gh pr create`
 
 ## Safety Gates
 
-- Preview before generating
-- Output directory conflict: ask before overwrite
-- Untrusted specs: note if not in known-specs registry
-- Max 3 retries on quality gate failure
+- **Preview before generating**: Show API name, base URL, estimated resource count before running
+- **Output directory conflict**: Check before overwriting
+- **Untrusted specs**: Note if not from known-specs registry
+- **Max 3 retries** on quality gate failure
 
 ## Limitations
 
-- Go CLIs only
-- OpenAPI 3.0+ and Swagger 2.0
+- Go CLIs only (no Bash, Python, etc.)
+- OpenAPI 3.0+ and Swagger 2.0 supported
 - 50 resources / 50 endpoints per resource limit
-- No GraphQL (but can wrap GraphQL in YAML spec, like Linear)
-- ce:plan and ce:work require Compound Engineering plugin
+- No native GraphQL support (but can wrap GraphQL in YAML spec)
+- Complex body fields (nested objects, arrays) skipped as CLI flags

← 68f63167 feat(skill): restore plan-execute-plan-execute loop - the pr  ·  back to Cli Printing Press  ·  feat(skill): v1.1.0 dual Steinberger analysis, deep research bb0acf37 →