← back to Cli Printing Press
docs(readme): agents-first design, Absorb & Transcend, emboss, verify
432041e23beeabcc1401cb31ead0d7a834edccd9 · 2026-03-28 07:37:23 -0700 · Matt Van Horn
- Opening pitch: agents are the primary power user in 2026
- New "Absorb & Transcend" section: steal every feature, compound on top
- Phase diagram: add Phase 1.5 Ecosystem Absorb Gate
- Emboss mode documented
- Verify command added to verification tools
- "What Gets Generated" leads with agent design rationale
- GitHub About updated with absorb + agents-first framing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Files touched
M README.mdA docs/plans/2026-03-28-docs-readme-agents-absorb-update-plan.md
Diff
commit 432041e23beeabcc1401cb31ead0d7a834edccd9
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Sat Mar 28 07:37:23 2026 -0700
docs(readme): agents-first design, Absorb & Transcend, emboss, verify
- Opening pitch: agents are the primary power user in 2026
- New "Absorb & Transcend" section: steal every feature, compound on top
- Phase diagram: add Phase 1.5 Ecosystem Absorb Gate
- Emboss mode documented
- Verify command added to verification tools
- "What Gets Generated" leads with agent design rationale
- GitHub About updated with absorb + agents-first framing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
README.md | 44 +++++++++--
...-03-28-docs-readme-agents-absorb-update-plan.md | 87 ++++++++++++++++++++++
2 files changed, 124 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index 58b613cf..63a2996e 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,17 @@
# CLI Printing Press
-Just making a CLI is not hard. Making a CLI that understands the power user is extremely hard.
+Just making a CLI is not hard. Making a CLI that understands the power user is extremely hard. And the power user in 2026 is an AI agent.
+
+Claude Code, Codex, Gemini CLI, Cursor - they call CLIs thousands of times a day. Every printing press CLI is designed for agents first: `--json` by default when piped, typed exit codes for self-correction, `--compact` for token efficiency, `--dry-run` for safe exploration. Humans get the same great experience, but agents are the primary design target.
```bash
/printing-press Discord
/printing-press Stripe
/printing-press Linear
+/printing-press emboss ./library/notion-cli # Second pass: improve an existing CLI
```
-One command. Lean 5-phase loop. Usually 15-35 minutes to first shipcheck instead of an hour of mandatory phase churn. Produces a Go CLI + MCP server plus the few artifacts that actually help the next step. REST or GraphQL. Matches core competitor features, then adds the data layer they don't have.
+One command. Lean loop. Produces a Go CLI + MCP server that absorbs every feature from every competing tool, then transcends with compound use cases only possible with local data. REST or GraphQL.
### Get it
@@ -24,6 +27,16 @@ Why does the 11-command tool win? Because Steinberger saw something Discord's ow
Until now, you had to choose: breadth (wrap every endpoint) or depth (understand the user). The printing press eliminates that choice. It generates the full API surface AND matches every feature the top competitor has AND adds the discrawl-style intelligence layer AND an MCP server. One spec in. Everything out.
+## Absorb & Transcend
+
+The GOAT CLI isn't built by finding gaps. It's built by stealing every good idea and compounding on top.
+
+**Layer 1 - Absorb:** Before generating, Phase 1.5 catalogs every feature from every Claude Code plugin, MCP server, community skill, competing CLI, and automation script. Every feature becomes a row in the absorb manifest - something our CLI must match AND beat with offline support, agent-native output, and SQLite persistence.
+
+**Layer 2 - Transcend:** Once you have everything in SQLite, compound use cases emerge that no stateless tool can do. Velocity tracking requires historical cycle data. Churn risk requires joining charges + subscriptions. Bottleneck detection requires the full issue relationship graph. These are the Non-Obvious Insight commands - and they only work because Layer 1 put everything in a local database.
+
+The GOAT = everything everyone else does + everything nobody else thought of.
+
## The Non-Obvious Insight
Every API has a secret identity. The data it exposes is useful for something its creators never designed for. The printing press finds that secret and builds a CLI around it.
@@ -117,9 +130,10 @@ The fast path is a lean loop. Artifacts still matter, but only when they directl
```
Phase 0 Resolve + Reuse (1-3 min) Reuse prior research, detect tokens, lock the spec source
-Phase 1 Research Brief (5-10 min) API identity, top workflows, table stakes, data layer, thesis
+Phase 1 Research Brief (5-10 min) API identity, competitors, data layer, product thesis
+Phase 1.5 Ecosystem Absorb Gate (5-10 min) Catalog every MCP/skill/CLI feature -> absorb manifest
Phase 2 Generate (1-2 min) Go CLI + MCP server from spec with validation
-Phase 3 Build (10-20 min) Data layer + top workflows + highest-value gaps
+Phase 3 Build The GOAT (10-20 min) ALL absorbed features + transcendence commands
Phase 4 Shipcheck (3-8 min) dogfood + verify --fix + scorecard as one verification block
Phase 5 Live Smoke (optional) (2-5 min) Read-only API smoke + data-flow check
```
@@ -131,10 +145,20 @@ Phase 5 Live Smoke (optional) (2-5 min) Read-only API smoke + data-fl
/printing-press Discord # Standard Opus mode (default)
```
-When you add `codex`, Phase 4's code generation tasks are delegated to Codex CLI. Claude stays the brain (research, planning, scoring, review). Codex does the hands (writing Go code from scoped prompts). Same quality, 60% fewer Opus tokens.
+When you add `codex`, Phase 3's code generation tasks are delegated to Codex CLI. Claude stays the brain (research, planning, scoring, review). Codex does the hands (writing Go code from scoped prompts). Same quality, 60% fewer Opus tokens.
+
+### Emboss Mode (second pass)
+
+```bash
+/printing-press emboss ./library/notion-cli # Improve an existing CLI
+```
+
+Already generated a CLI? Emboss runs a 30-minute improvement cycle: audit baseline (verify + scorecard), re-research what's changed, identify top 5 improvements, build them, re-verify, report the delta. The binary handles the bookkeeping (`printing-press emboss --audit-only`), the skill handles the creative work.
## What Gets Generated
+**Designed for AI agents.** Every flag, every output format, every exit code is chosen because an agent will consume it. `--json` is automatic when piped. `--compact` drops to high-gravity fields only (id, name, status, timestamps) - 60-80% fewer tokens. Typed exit codes (`0`=success, `2`=usage, `3`=not found, `4`=auth, `5`=API, `7`=rate limited) let agents self-correct in one retry without parsing error text. `--dry-run` lets agents explore safely. `--stdin` enables batch operations. Humans benefit from all of this too - agent-native design is just good CLI design taken seriously.
+
**Agent-first flags** (every command): `--json`, `--select`, `--dry-run`, `--stdin`, `--csv`, `--compact`, `--quiet`, `--yes`, `--no-input`, `--no-cache`, `--no-color`. Auto-JSON when piped (no `--json` needed). Typed exit codes (`0`=success, `2`=usage, `3`=not found, `4`=auth, `5`=API, `7`=rate limited).
**Actionable errors**: errors include the specific flag/arg that's wrong, the correct usage pattern, and the command path. Agents self-correct in one retry.
@@ -197,10 +221,16 @@ Inspired by Peter Steinberger's [gogcli](https://github.com/steipete/gogcli). Tw
**Why two tiers?** The original scorecard tested syntax (does this string exist in the file?) not semantics (does this code actually work?). Generated CLIs scored Grade A and failed on the first real API call. The v2 scorecard catches that.
```bash
-# Run the honest scorecard
+# Runtime verification: tests every command against real API or mock server
+printing-press verify --dir ./discord-cli --spec /tmp/discord-spec.json --api-key $TOKEN
+
+# Emboss audit: baseline snapshot for improvement cycle
+printing-press emboss --dir ./discord-cli --spec /tmp/discord-spec.json --audit-only
+
+# Quality scorecard: two-tier structural scoring
printing-press scorecard --dir ./discord-cli --spec /tmp/discord-spec.json
-# Run the mechanical dogfood validator
+# Mechanical dogfood: catches dead flags, invalid paths, auth mismatches
printing-press dogfood --dir ./discord-cli --spec /tmp/discord-spec.json
```
diff --git a/docs/plans/2026-03-28-docs-readme-agents-absorb-update-plan.md b/docs/plans/2026-03-28-docs-readme-agents-absorb-update-plan.md
new file mode 100644
index 00000000..79ab1a08
--- /dev/null
+++ b/docs/plans/2026-03-28-docs-readme-agents-absorb-update-plan.md
@@ -0,0 +1,87 @@
+---
+title: "Update README + GitHub About with Agents-First and Absorb & Transcend"
+type: docs
+status: active
+date: 2026-03-28
+---
+
+# Update README + GitHub About
+
+## What's Changed Since the README Was Last Updated
+
+1. **Phase 1.5: Ecosystem Absorb Gate** - The press now catalogs every feature from every MCP, skill, and competing CLI, then builds ALL of them into the generated CLI before transcending with NOI commands. The README still says "top 3-5 workflows" in places.
+
+2. **Agents are the primary power user** - The README mentions "agent-first flags" but doesn't lead with the thesis that AI agents (Claude Code, Codex, Gemini CLI, Cursor) are now the primary consumers of CLIs. Humans use CLIs; agents LIVE in them. Every design decision flows from this.
+
+3. **Absorb & Transcend philosophy** - The README talks about "depth beats breadth" and the NOI, but doesn't explain the two-layer model: absorb everything competitors have, then transcend with compound use cases only possible with local data.
+
+4. **Phase diagram is outdated** - Missing Phase 1.5 (Ecosystem Absorb Gate).
+
+5. **Emboss mode** - Built but not in README.
+
+6. **Verify command** - Built but not in README verification tools section.
+
+7. **GitHub About description** - Currently: "Every API has a secret identity..." Good but doesn't mention agents or the absorb model.
+
+## Changes to Make
+
+### C1: Update the opening pitch (lines 1-11)
+
+Current: "Just making a CLI is not hard. Making a CLI that understands the power user is extremely hard."
+
+Add after: The power user in 2026 is an AI agent. Claude Code, Codex, Gemini CLI, Cursor - they call CLIs thousands of times a day. Every printing press CLI is designed for agents first: --json by default when piped, typed exit codes for self-correction, --compact for token efficiency, --dry-run for safe exploration. Humans get the same great experience, but agents are the primary design target.
+
+### C2: Add "Absorb & Transcend" section (after NOI section)
+
+New section explaining the two-layer model:
+- Layer 1: Absorb every feature from every MCP, skill, competing CLI. Match and beat them all.
+- Layer 2: Transcend with compound use cases that only work with local SQLite data.
+- The GOAT CLI = everything everyone else does + everything nobody else thought of.
+
+### C3: Update Phase diagram (line 119-125)
+
+Add Phase 1.5 between Phase 1 and Phase 2:
+```
+Phase 1.5 Ecosystem Absorb Gate (5-10 min) Catalog every tool, build absorb manifest, get approval
+```
+
+### C4: Add Emboss mode to README
+
+After the Codex Mode section, add Emboss:
+```bash
+/printing-press emboss ./library/notion-cli # Second pass: improve an existing CLI
+```
+Brief explanation of the 6-step cycle and delta reporting.
+
+### C5: Add Verify command to Verification Tools
+
+```bash
+# Runtime verification: tests every command against real API or mock server
+printing-press verify --dir ./my-cli --spec ./openapi.json --api-key $TOKEN
+```
+
+### C6: Update GitHub About description
+
+Current: "Every API has a secret identity - Stripe isn't payments, it's a business health monitor. This finds the Non-Obvious Insight and generates a Go CLI with SQLite sync, offline search, and the 12 commands that matter."
+
+New: "Every API has a secret identity. This finds it, absorbs every feature from every competing tool, then builds the GOAT CLI on top - Go binary + MCP server, designed for AI agents first, with SQLite sync and offline search."
+
+### C7: Fix "What Gets Generated" agent framing
+
+The "Agent-first flags" bullet exists but is buried. Move it up and expand: explain WHY agents need these specific features (typed exit codes for self-correction, --compact for token budget, auto-JSON for pipe chains, --dry-run for safe exploration).
+
+## Acceptance Criteria
+
+- [ ] Opening pitch mentions agents as primary power user
+- [ ] "Absorb & Transcend" section explains two-layer model
+- [ ] Phase diagram includes Phase 1.5 Ecosystem Absorb Gate
+- [ ] Emboss mode documented
+- [ ] Verify command documented in verification tools
+- [ ] GitHub About description updated
+- [ ] "What Gets Generated" leads with agent design rationale
+- [ ] No stale references to "top 3-5 workflows" (should be "full absorb manifest")
+
+## Files
+
+- `README.md`
+- GitHub repo description (via `gh api`)
← 49b98a3b feat(skill): add Phase 1.5 Ecosystem Absorb Gate - build the
·
back to Cli Printing Press
·
feat(skill): add 7-principle agent build checklist and Prior 6727b860 →