← back to Cli Printing Press

feat(skill): add 7-principle agent build checklist and Priority 1 review gate to Phase 3

6727b8603a8a2f2cbc3f3efc361954196531d89c · 2026-03-28 09:08:29 -0700 · Matt Van Horn

- Per-command checklist: non-interactive, structured output, progressive help,
  actionable errors, safe retries, composability, bounded responses
- Maps 1:1 to Phase 4.9 agent readiness reviewer principles
- Priority 1 Review Gate: test 3 random commands with --help/--dry-run/--json
  before proceeding to transcendence features
- Two-sided protection: principles guide build (Phase 3), agent reviews work (Phase 4.9)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Files touched

• A docs/plans/2026-03-28-refactor-skill-agent-decomposition-plan.md
• A docs/plans/2026-03-28-research-goat-agent-scoring-alignment-plan.md
• M skills/printing-press/SKILL.md

Diff

commit 6727b8603a8a2f2cbc3f3efc361954196531d89c
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date:   Sat Mar 28 09:08:29 2026 -0700

    feat(skill): add 7-principle agent build checklist and Priority 1 review gate to Phase 3
    
    - Per-command checklist: non-interactive, structured output, progressive help,
      actionable errors, safe retries, composability, bounded responses
    - Maps 1:1 to Phase 4.9 agent readiness reviewer principles
    - Priority 1 Review Gate: test 3 random commands with --help/--dry-run/--json
      before proceeding to transcendence features
    - Two-sided protection: principles guide build (Phase 3), agent reviews work (Phase 4.9)
    
    Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 ...3-28-refactor-skill-agent-decomposition-plan.md | 155 +++++++++++++++
 ...8-research-goat-agent-scoring-alignment-plan.md | 220 +++++++++++++++++++++
 skills/printing-press/SKILL.md                     |  27 ++-
 3 files changed, 401 insertions(+), 1 deletion(-)

diff --git a/docs/plans/2026-03-28-refactor-skill-agent-decomposition-plan.md b/docs/plans/2026-03-28-refactor-skill-agent-decomposition-plan.md
new file mode 100644
index 00000000..42516358
--- /dev/null
+++ b/docs/plans/2026-03-28-refactor-skill-agent-decomposition-plan.md
@@ -0,0 +1,155 @@
+---
+title: "Should We Decompose the Printing Press Skill Into Agents?"
+type: refactor
+status: active
+date: 2026-03-28
+---
+
+# Should We Decompose the Printing Press Skill Into Agents?
+
+## The Question
+
+The printing press SKILL.md is 435 lines with 33 sections covering research, ecosystem analysis, code generation, building, and verification. Each phase is a distinct competency. Should we factor some phases into dedicated agents that the main skill dispatches?
+
+## Current Architecture
+
+```
+skills/printing-press/SKILL.md (435 lines - orchestrator + everything)
+skills/printing-press-score/SKILL.md (already factored out)
+skills/printing-press-catalog/SKILL.md (already factored out)
+No agents/ directory
+```
+
+The skill is the orchestrator AND the worker for every phase. It tells Claude what to research, how to build, what to verify - all in one file.
+
+## The Case FOR Agents
+
+### 1. Fresh context per phase
+
+When the skill is one massive document, the LLM carries all 435 lines plus all prior phase outputs in context. By Phase 3 (Build), the research instructions from Phase 0-1.5 are noise. An agent gets a fresh context window focused on just the build task with the relevant inputs passed in.
+
+### 2. Specialized prompting per competency
+
+Research (Phase 1) requires different prompting than building (Phase 3) than verification (Phase 4). Research needs web search patterns. Building needs code generation patterns and the absorb manifest. Verification needs binary execution and scoring. Each agent can be optimized for its competency.
+
+### 3. Parallelization
+
+Some phases are naturally parallelizable:
+- Phase 1 research + Phase 1.5 ecosystem research could run simultaneously
+- Phase 4 shipcheck tools (dogfood, verify, scorecard) already run in parallel
+- Emboss's re-research + current audit could overlap
+
+With agents, the orchestrator dispatches them in parallel naturally.
+
+### 4. Reusability
+
+A "research-api-landscape" agent could be reused by emboss mode, by the top-50 candidate ranking, and by any future tool that needs to understand an API's ecosystem.
+
+### 5. The precedent works
+
+`printing-press-score` was already factored out as a separate skill. Phase 4.9 uses `compound-engineering:cli-agent-readiness-reviewer` - an EXTERNAL agent. The pattern of the orchestrator calling specialized agents is already in use.
+
+## The Case AGAINST Agents
+
+### 1. SKILL.md is only 435 lines
+
+This is not actually that long. v1 was 1,664 lines. v2 already did the heavy compression. 435 lines is readable in one pass.
+
+### 2. Coordination overhead
+
+Every agent dispatch adds: prompt construction, context passing, result parsing, error handling for agent failures. For a 30-minute process, adding 5 agent dispatches could add 5 minutes of coordination overhead.
+
+### 3. State passing is messy
+
+The skill builds up state across phases: the brief informs the absorb manifest, which informs the build priorities, which inform verification. Passing this between agents means serializing/deserializing state at each boundary. The single-skill approach keeps all state in the conversation context naturally.
+
+### 4. Debugging is harder
+
+When something goes wrong in a single skill, you can trace the conversation. With agents, you're debugging across multiple context windows with only the outputs visible.
+
+### 5. The LLM ignoring instructions is the REAL problem
+
+The reason phases get skipped isn't because the skill is too long - it's because the LLM rationalizes past "mandatory" instructions. Breaking into agents doesn't fix this. The LLM can skip dispatching an agent just as easily as it can skip a phase.
+
+## My Recommendation: Hybrid - Keep the Skill, Add 3 Agents
+
+Don't rewrite the skill. Keep it as the orchestrator. But extract the 3 heaviest phases into agents that the skill dispatches via the Agent tool.
+
+### Agent 1: `printing-press-research` (Phase 1 + 1.5)
+
+**What it does:** Takes an API name, runs ALL the research (brief + ecosystem absorb), returns the brief + absorb manifest as markdown.
+
+**Why agent:** Research is web-search-heavy and benefits from a fresh context window without prior build artifacts. It's the same work whether called from the main skill, from emboss, or from the top-50 ranking.
+
+**Inputs:** API name, spec path (optional), prior research to reuse (optional)
+**Outputs:** Brief markdown + absorb manifest markdown
+**Size:** ~150 lines of agent instructions
+
+### Agent 2: `printing-press-builder` (Phase 3)
+
+**What it does:** Takes a generated CLI directory + absorb manifest + brief, builds all absorbed features and transcendence commands with the 7-principle agent checklist.
+
+**Why agent:** Building is code-generation-heavy. It benefits from a fresh context focused on the codebase, not on research. This is also the natural delegation point for Codex mode.
+
+**Inputs:** CLI directory, spec path, absorb manifest, brief
+**Outputs:** Build log markdown, list of commands built
+**Size:** ~100 lines of agent instructions
+
+### Agent 3: `printing-press-verifier` (Phase 4 + 4.9)
+
+**What it does:** Runs the full shipcheck (dogfood + verify + scorecard) and the agent readiness review, with fix loops.
+
+**Why agent:** Verification is binary-execution-heavy. It runs Go commands, parses output, decides what to fix. Benefits from a fresh context without all the research/build noise.
+
+**Inputs:** CLI directory, spec path
+**Outputs:** Shipcheck report markdown, verify pass rate, scorecard score
+**Size:** ~80 lines of agent instructions
+
+### What stays in the main skill
+
+The orchestrator (~150 lines):
+- Mode detection (default, codex, emboss)
+- Phase 0 (resolve + reuse - lightweight, stays inline)
+- Dispatch Agent 1 (research)
+- Present absorb manifest, wait for approval (Phase Gate 1.5)
+- Phase 2 (generate - one bash command, stays inline)
+- Dispatch Agent 2 (builder)
+- Dispatch Agent 3 (verifier)
+- Phase 5 (live smoke - lightweight, stays inline)
+- Final report
+
+### The math
+
+| Component | Current | Proposed |
+|-----------|---------|----------|
+| Main skill | 435 lines | ~150 lines |
+| Research agent | 0 | ~150 lines |
+| Builder agent | 0 | ~100 lines |
+| Verifier agent | 0 | ~80 lines |
+| **Total** | **435 lines** | **~480 lines** |
+
+Total lines go UP slightly. But each component is focused and has its own context window. The orchestrator is clean and readable.
+
+## When to Do This
+
+**Not now.** The skill works. v2 is only 435 lines. The immediate priority is:
+1. Ship CLIs from the library (Cal.com, Notion, Linear, HubSpot)
+2. Run emboss on the Cal.com CLI that was already generated
+3. Get real feedback from running the press on real APIs
+
+The decomposition makes sense AFTER we've run the press 5-10 times and feel the pain of the monolithic skill. Right now it's theoretical. After 5 runs we'll know which phases actually need isolation.
+
+**Trigger to decompose:** If the skill exceeds 600 lines, or if context window pollution visibly degrades Phase 3 build quality (e.g., the LLM starts confusing research findings with build instructions).
+
+## Acceptance Criteria
+
+- [ ] Decision: decompose now or defer?
+- [ ] If now: create agents/ directory, write 3 agent SKILL.md files, refactor main skill
+- [ ] If defer: save this plan, revisit after 5 CLI runs
+
+## Sources
+
+- Current skill: `skills/printing-press/SKILL.md` (435 lines, 33 sections)
+- Factored example: `skills/printing-press-score/SKILL.md` (separate scoring skill)
+- External agent example: Phase 4.9 uses `compound-engineering:cli-agent-readiness-reviewer`
+- Context window research: compound-engineering's subagent-driven-development skill uses fresh context per task
diff --git a/docs/plans/2026-03-28-research-goat-agent-scoring-alignment-plan.md b/docs/plans/2026-03-28-research-goat-agent-scoring-alignment-plan.md
new file mode 100644
index 00000000..0724e923
--- /dev/null
+++ b/docs/plans/2026-03-28-research-goat-agent-scoring-alignment-plan.md
@@ -0,0 +1,220 @@
+---
+title: "Audit: Does Phase 3 GOAT enforce agent principles? Does scoring need updating?"
+type: research
+status: active
+date: 2026-03-28
+---
+
+# Audit: GOAT Phase + Agent Principles + Scoring Alignment
+
+## Question 1: Does Phase 3 (Build The GOAT) enforce agent design principles?
+
+### What the SKILL.md says
+
+Phase 3 Priority 1 says "matched and beaten with agent-native output." But it doesn't spell out WHAT agent-native means for each absorbed feature. It's an adjective, not a checklist.
+
+### What's missing
+
+The absorb manifest table has columns: Feature | Best Source | Our Implementation | Added Value. But "Added Value" is freeform. There's no enforcement that every absorbed feature gets:
+
+- `--json` output
+- `--dry-run` (for mutation commands)
+- `--stdin` (for batch input)
+- `--select` field filtering
+- Typed exit codes
+- `--compact` token-efficient mode
+- Auto-JSON when piped (no `--json` needed)
+- No interactive prompts (fully scriptable)
+
+**Recommendation:** Add an "Agent Checklist" to Phase 3 that runs AFTER building each absorbed feature:
+
+```
+For each command built, verify:
+[ ] --json works and produces valid JSON
+[ ] --dry-run works for any mutation command (POST/PUT/PATCH/DELETE)
+[ ] --select filters fields correctly
+[ ] Exit code is typed (0/2/3/4/5/7)
+[ ] No interactive prompts (works in CI/agent context without TTY)
+[ ] --compact returns only high-gravity fields
+```
+
+This is basically what `scoreAgentNative` checks, but applied during BUILD, not just during scoring after the fact.
+
+### Verdict: Partial. The intent is there but the enforcement isn't.
+
+---
+
+## Question 2: Does the scoring system need to change?
+
+### Current scorecard dimensions (18 total)
+
+**Tier 1 - Infrastructure (12 dimensions, 0-120 raw -> 50 normalized):**
+1. OutputModes (0-10) - --json, --csv, --select, --quiet, --compact
+2. Auth (0-10)
+3. ErrorHandling (0-10) - typed exits, retry, actionable messages
+4. TerminalUX (0-10)
+5. README (0-10)
+6. Doctor (0-10)
+7. **AgentNative (0-10)** - --json, --select, --dry-run, --stdin, --yes, no prompts
+8. LocalCache (0-10)
+9. Breadth (0-10)
+10. Vision (0-10)
+11. Workflows (0-10)
+12. Insight (0-10)
+
+**Tier 2 - Domain Correctness (6 dimensions, 0-50 raw -> 50 normalized):**
+13. PathValidity (0-10)
+14. AuthProtocol (0-10)
+15. DataPipelineIntegrity (0-10)
+16. SyncCorrectness (0-10)
+17. TypeFidelity (0-5)
+18. DeadCode (0-5)
+
+### What the GOAT changes introduced
+
+| Change | Scoring Impact |
+|--------|---------------|
+| Phase 1.5 Ecosystem Absorb Gate | No scoring impact - this is research, not generated code |
+| Phase 3 "Build ALL absorbed features" | **Breadth score should increase** - more commands = higher breadth. Already handled. |
+| Phase 3 "Build ALL transcendence features" | **Insight and Workflows scores should increase** - more workflow/insight commands. Already handled. |
+| "Agent-native output on every feature" | **AgentNative dimension already checks this.** Scores --json, --select, --dry-run, --stdin, --yes, no-prompts. |
+
+### What's NOT scored that should be
+
+1. **Absorb coverage** - There's no scorecard dimension for "did you match every feature the top competitor has?" The current `Breadth` dimension just counts commands. It doesn't compare against a manifest.
+
+2. **Transcendence depth** - `Insight` checks for file prefixes (health, trends, patterns, etc.) but doesn't verify the insight commands query REAL data from the data layer. A `health.go` that queries an empty table scores the same as one that computes a real composite score.
+
+3. **Compound query verification** - The transcendence features require cross-entity joins (e.g., issues + cycles for velocity). No scorecard dimension checks that compound queries work.
+
+### Recommendation: Scoring is MOSTLY fine. Two small additions.
+
+**Addition 1: Add "Absorb Coverage" check to Tier 2**
+
+If a Phase 1.5 absorb manifest exists (in `docs/plans/*absorb-manifest*`), the scorecard should:
+- Count absorbed features in the manifest
+- Count implemented commands in the CLI
+- Score: implemented / absorbed * 10
+
+This is a Tier 2 (domain correctness) dimension because it checks whether the CLI actually built what the research said to build.
+
+**Addition 2: Verify insight commands query non-empty tables**
+
+Currently `scoreInsight` checks if files like `health.go`, `trends.go` exist. It should ALSO grep those files for actual SQL queries or store method calls, not just file existence.
+
+This is already partially covered by `DataPipelineIntegrity` (checks sync calls domain Upsert). But extending it to insight commands would close the gap.
+
+### What does NOT need to change
+
+- AgentNative (0-10) already covers the agent flags
+- OutputModes (0-10) already covers --json, --csv, --select
+- ErrorHandling (0-10) already covers typed exits
+- The verify command already tests every command at runtime
+- The two-tier weighted system (50% infra + 50% domain) is balanced
+
+## The Safety Blanket: Protect Both Sides
+
+The user's insight: don't just check agent principles AFTER building. Use them DURING building AND have an agent REVIEW the work after.
+
+### What Phase 4.9 Does (the pattern to learn from)
+
+Phase 4.9 (`feat-agent-readiness-review-loop-plan.md`) invokes the `compound-engineering:cli-agent-readiness-reviewer` agent which evaluates **7 deep principles** - not just flag presence:
+
+1. Non-interactive automation (no TTY prompts)
+2. Structured output (JSON, typed fields)
+3. Progressive help (usage examples, not just flag lists)
+4. Actionable errors (specific fix suggestions, not generic messages)
+5. Safe retries (idempotent operations, --dry-run)
+6. Composability (pipe-friendly, exit codes, --select)
+7. Bounded responses (--limit, --compact, token-conscious)
+
+Each finding has a severity: **Blocker** (must fix), **Friction** (should fix), **Optimization** (nice to have).
+
+The fix loop: implement all fixes, `go build && go vet`, re-review. Iterate until 0 Blockers + 0 Frictions, max 2 passes. Gracefully skips if compound-engineering plugin not available.
+
+### The Two-Sided Protection Model
+
+```
+Phase 3 (BUILD)                    Phase 4.9 (REVIEW)
+Agent principles guide what        Agent reviewer checks what
+you build and HOW you build it     was actually built
+
+"Every absorbed feature must       "Does search_issues actually
+have --json, --dry-run, --select,  output valid JSON? Does
+typed exit codes, no prompts"      --dry-run actually skip the
+                                   API call? Is the error message
+INPUT-SIDE PROTECTION              actionable or generic?"
+(checklist during construction)
+                                   OUTPUT-SIDE PROTECTION
+                                   (agent review with fix loop)
+```
+
+### What to Change
+
+**Change 1: Add agent build checklist to Phase 3**
+
+After building each Priority 1 (absorbed) and Priority 2 (transcendence) command, verify:
+
+```markdown
+### Agent Build Checklist (per command)
+
+After building each command, verify these 7 principles are met:
+
+1. [ ] **Non-interactive**: No TTY prompts, no `bufio.Scanner(os.Stdin)`, works in CI
+2. [ ] **Structured output**: `--json` produces valid JSON, `--select` filters fields
+3. [ ] **Progressive help**: `--help` shows realistic examples with domain values
+4. [ ] **Actionable errors**: Error messages include the specific flag/arg and correct usage
+5. [ ] **Safe retries**: Mutation commands support `--dry-run`, idempotent where possible
+6. [ ] **Composability**: Exit codes are typed (0/2/3/4/5/7), output pipes to jq cleanly
+7. [ ] **Bounded responses**: `--compact` mode exists, list commands have `--limit`
+
+This checklist maps 1:1 to the 7 principles that Phase 4.9's agent reviewer will check.
+If you apply them during build, Phase 4.9 becomes a confirmation, not a catch-all.
+```
+
+**Change 2: Phase 3 gets a mini-review gate at Priority boundaries**
+
+After completing Priority 1 (all absorbed features), BEFORE starting Priority 2 (transcendence):
+
+```markdown
+### Priority 1 Review Gate
+
+After building all absorbed features, run a quick self-review:
+- Pick 3 random commands. Run each with `--json`, `--dry-run`, `--help`.
+- Do they all work? If any fail, fix before proceeding.
+- This catches systemic issues (e.g., --dry-run not wired) early.
+```
+
+This is a lighter version of Phase 4.9's fix loop, applied during build.
+
+**Change 3: No scoring changes needed**
+
+Phase 4.9 already handles the deep review with the agent reviewer. The scorecard's `AgentNative` dimension (0-10) handles the string-matching check. The `verify` command handles runtime testing. Adding another scoring dimension would be redundant - the protection is already three layers deep:
+
+1. Phase 3 build checklist (prevention)
+2. Phase 4 shipcheck + verify (runtime testing)
+3. Phase 4.9 agent readiness review (deep 7-principle review with fix loop)
+
+## Summary
+
+| Question | Answer | Action Needed? |
+|----------|--------|---------------|
+| Does Phase 3 enforce agent principles? | Partially - intent is there but no per-command checklist | **Add 7-principle checklist to Phase 3** |
+| Does Phase 4.9 already catch agent issues? | Yes - deep 7-principle review with Blocker/Friction severity and fix loop | **Already working. Phase 3 checklist makes it a confirmation not a catch-all.** |
+| Does scoring need to change? | No - AgentNative (scorecard) + verify (runtime) + Phase 4.9 (deep review) = three layers | **No changes needed** |
+| Is the model right? | Yes - protect BOTH sides. Build with principles (Phase 3), review with agent (Phase 4.9) | **Add the build checklist and mini-review gate** |
+
+## Acceptance Criteria
+
+- [x] Phase 3 in SKILL.md gets the 7-principle agent build checklist (per command)
+- [x] Phase 3 gets a mini-review gate between Priority 1 and Priority 2
+- [x] Checklist maps 1:1 to Phase 4.9's 7 principles (so Phase 4.9 becomes confirmation)
+- [x] No scoring changes (3 layers already sufficient)
+
+## Sources
+
+- `docs/plans/2026-03-27-feat-agent-readiness-review-loop-plan.md` - Phase 4.9 plan (completed)
+- `docs/brainstorms/2026-03-27-agent-readiness-review-loop-requirements.md` - 7 principles definition
+- `internal/pipeline/scorecard.go` - AgentNative dimension (0-10)
+- `skills/printing-press/SKILL.md` - Phase 3 Build The GOAT
+- `internal/pipeline/runtime.go` - verify tests every command at runtime
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index 146669fb..3e4d445b 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -320,7 +320,32 @@ Priority 3 (polish):
 - naming cleanup for ugly operationId-derived commands
 - tests for non-trivial store/workflow logic
 
-Get Priority 0 and 1 working first (the foundation and absorbed features), then build Priority 2 (transcendence), then verify.
+### Agent Build Checklist (per command)
+
+After building each command in Priority 1 and Priority 2, verify these 7 principles are met. These map 1:1 to what Phase 4.9's agent readiness reviewer will check - apply them now so the review becomes a confirmation, not a catch-all.
+
+1. **Non-interactive**: No TTY prompts, no `bufio.Scanner(os.Stdin)`, works in CI without a terminal
+2. **Structured output**: `--json` produces valid JSON, `--select` filters fields correctly
+3. **Progressive help**: `--help` shows realistic examples with domain-specific values (not "abc123")
+4. **Actionable errors**: Error messages name the specific flag/arg that's wrong and the correct usage
+5. **Safe retries**: Mutation commands support `--dry-run`, idempotent where possible
+6. **Composability**: Exit codes are typed (0/2/3/4/5/7), output pipes to `jq` cleanly
+7. **Bounded responses**: `--compact` returns only high-gravity fields, list commands have `--limit`
+
+### Priority 1 Review Gate
+
+After completing ALL Priority 1 (absorbed) features, BEFORE starting Priority 2 (transcendence):
+
+Pick 3 random commands from Priority 1. Run each with:
+```bash
+<cli> <command> --help          # Does it show realistic examples?
+<cli> <command> --dry-run       # Does it show the request without sending?
+<cli> <command> --json          # Does it produce valid JSON?
+```
+
+If any of the 3 fail, there's a systemic issue. Fix it across all commands before proceeding. This catches problems like "--dry-run not wired" or "--json outputs table instead of JSON" early, when they're cheap to fix.
+
+Get Priority 0 and 1 working first (the foundation and absorbed features), pass the review gate, then build Priority 2 (transcendence), then verify.
 
 Write:
 

← 432041e2 docs(readme): agents-first design, Absorb & Transcend, embos  ·  back to Cli Printing Press  ·  fix(scorecard): handle unscored auth semantics (#29) 7a1c1646 →