← back to Cli Printing Press
feat(emboss): add second-pass improvement command for generated CLIs
efbf4b8814a2384dadcde0307ac6ad363f933006 · 2026-03-27 15:02:34 -0700 · Matt Van Horn
- printing-press emboss: audit baseline, re-research, gap analysis, improve, re-verify
- --audit-only flag for just the baseline snapshot (verify + scorecard)
- SKILL.md emboss section with 6-step cycle (~30 min)
- Reports before/after delta: scorecard, verify pass rate, pipeline status
- Supports codex delegation for improvements
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Files touched
A internal/cli/emboss.goM internal/cli/root.goM skills/printing-press/SKILL.md
Diff
commit efbf4b8814a2384dadcde0307ac6ad363f933006
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Fri Mar 27 15:02:34 2026 -0700
feat(emboss): add second-pass improvement command for generated CLIs
- printing-press emboss: audit baseline, re-research, gap analysis, improve, re-verify
- --audit-only flag for just the baseline snapshot (verify + scorecard)
- SKILL.md emboss section with 6-step cycle (~30 min)
- Reports before/after delta: scorecard, verify pass rate, pipeline status
- Supports codex delegation for improvements
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
internal/cli/emboss.go | 210 +++++++++++++++++++++++++++++++++++++++++
internal/cli/root.go | 1 +
skills/printing-press/SKILL.md | 94 ++++++++++++++++++
3 files changed, 305 insertions(+)
diff --git a/internal/cli/emboss.go b/internal/cli/emboss.go
new file mode 100644
index 00000000..48800780
--- /dev/null
+++ b/internal/cli/emboss.go
@@ -0,0 +1,210 @@
+package cli
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "path/filepath"
+ "time"
+
+ "github.com/mvanhorn/cli-printing-press/internal/pipeline"
+ "github.com/spf13/cobra"
+)
+
+// EmbossReport captures the before/after delta from an emboss cycle.
+type EmbossReport struct {
+ Dir string `json:"dir"`
+ Spec string `json:"spec"`
+ Timestamp string `json:"timestamp"`
+ Before EmbossSnapshot `json:"before"`
+ After *EmbossSnapshot `json:"after,omitempty"`
+ Delta *EmbossDelta `json:"delta,omitempty"`
+ Improvements []string `json:"improvements,omitempty"`
+ Mode string `json:"mode"` // "audit-only" or "full"
+}
+
+type EmbossSnapshot struct {
+ ScorecardTotal int `json:"scorecard_total"`
+ ScorecardGrade string `json:"scorecard_grade"`
+ VerifyPassRate float64 `json:"verify_pass_rate"`
+ VerifyPassed int `json:"verify_passed"`
+ VerifyTotal int `json:"verify_total"`
+ DataPipeline bool `json:"data_pipeline"`
+ CommandCount int `json:"command_count"`
+}
+
+type EmbossDelta struct {
+ ScorecardDelta int `json:"scorecard_delta"`
+ VerifyDelta float64 `json:"verify_delta"`
+ CommandDelta int `json:"command_delta"`
+ PipelineFixed bool `json:"pipeline_fixed"`
+}
+
+func newEmbossCmd() *cobra.Command {
+ var dir string
+ var specPath string
+ var apiKey string
+ var envVar string
+ var asJSON bool
+ var auditOnly bool
+
+ cmd := &cobra.Command{
+ Use: "emboss",
+ Short: "Second-pass improvement cycle for an existing generated CLI",
+ Long: `Run the emboss cycle on an already-generated CLI to make it better.
+
+Step 1: AUDIT - Run verify + scorecard to get a baseline
+Step 2: RE-RESEARCH - (skill-driven) Find what's new since v1
+Step 3: GAP ANALYSIS - (skill-driven) Identify top 5 improvements
+Step 4: IMPROVE - (skill-driven) Build improvements, commit atomically
+Step 5: RE-VERIFY - Run verify + scorecard again, compare to baseline
+Step 6: REPORT - Output the delta
+
+Use --audit-only to just get the baseline without making changes.
+The improvement steps (2-4) are driven by the /printing-press emboss skill.`,
+ Example: ` # Full emboss cycle (audit -> improve -> re-verify)
+ # Run the skill: /printing-press emboss ./discord-cli
+ # Or just get the baseline:
+ printing-press emboss --dir ./discord-cli --spec /tmp/spec.json --audit-only
+
+ # Audit with live API testing
+ printing-press emboss --dir ./discord-cli --spec /tmp/spec.json --api-key $TOKEN --audit-only`,
+ RunE: func(cmd *cobra.Command, args []string) error {
+ report := &EmbossReport{
+ Dir: dir,
+ Spec: specPath,
+ Timestamp: time.Now().Format(time.RFC3339),
+ }
+
+ if auditOnly {
+ report.Mode = "audit-only"
+ } else {
+ report.Mode = "full"
+ }
+
+ // Step 1: AUDIT - baseline
+ fmt.Fprintln(os.Stderr, "Step 1: AUDIT - Running verify + scorecard for baseline...")
+
+ // Run verify
+ verifyCfg := pipeline.VerifyConfig{
+ Dir: dir,
+ SpecPath: specPath,
+ APIKey: apiKey,
+ EnvVar: envVar,
+ Threshold: 80,
+ }
+ verifyReport, err := pipeline.RunVerify(verifyCfg)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, " verify error: %v (continuing with partial baseline)\n", err)
+ }
+
+ // Run scorecard
+ scorecardReport, err := pipeline.RunScorecard(dir, "", specPath)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, " scorecard error: %v (continuing with partial baseline)\n", err)
+ }
+
+ // Build baseline snapshot
+ report.Before = EmbossSnapshot{}
+ if verifyReport != nil {
+ report.Before.VerifyPassRate = verifyReport.PassRate
+ report.Before.VerifyPassed = verifyReport.Passed
+ report.Before.VerifyTotal = verifyReport.Total
+ report.Before.DataPipeline = verifyReport.DataPipeline
+ report.Before.CommandCount = verifyReport.Total
+ }
+ if scorecardReport != nil {
+ report.Before.ScorecardTotal = scorecardReport.Steinberger.Total
+ report.Before.ScorecardGrade = scorecardGrade(scorecardReport.Steinberger.Total)
+ }
+
+ if auditOnly {
+ return printEmbossReport(cmd, report, asJSON)
+ }
+
+ // Steps 2-4 are skill-driven (re-research, gap analysis, improve)
+ // The binary just does the mechanical audit + re-verify
+ fmt.Fprintln(os.Stderr, "\nSteps 2-4: Run the skill for improvements:")
+ fmt.Fprintf(os.Stderr, " /printing-press emboss %s\n\n", dir)
+ fmt.Fprintln(os.Stderr, "After improvements, re-run with --audit-only to get the 'after' snapshot.")
+
+ return printEmbossReport(cmd, report, asJSON)
+ },
+ }
+
+ cmd.Flags().StringVar(&dir, "dir", "", "Path to the generated CLI directory (required)")
+ cmd.Flags().StringVar(&specPath, "spec", "", "Path to the OpenAPI spec file")
+ cmd.Flags().StringVar(&apiKey, "api-key", "", "API key for live testing (read-only GETs only)")
+ cmd.Flags().StringVar(&envVar, "env-var", "", "Environment variable name for the API key")
+ cmd.Flags().BoolVar(&asJSON, "json", false, "Output as JSON")
+ cmd.Flags().BoolVar(&auditOnly, "audit-only", false, "Only run the baseline audit, no improvements")
+ _ = cmd.MarkFlagRequired("dir")
+ return cmd
+}
+
+func printEmbossReport(cmd *cobra.Command, report *EmbossReport, asJSON bool) error {
+ if asJSON {
+ enc := json.NewEncoder(os.Stdout)
+ enc.SetIndent("", " ")
+ return enc.Encode(report)
+ }
+
+ name := filepath.Base(report.Dir)
+ fmt.Printf("EMBOSS REPORT: %s\n", name)
+ fmt.Println("==============================")
+ fmt.Printf("Mode: %s\n", report.Mode)
+ fmt.Printf("Timestamp: %s\n\n", report.Timestamp)
+
+ fmt.Println("BASELINE:")
+ fmt.Printf(" Scorecard: %d/100 (Grade %s)\n", report.Before.ScorecardTotal, report.Before.ScorecardGrade)
+ fmt.Printf(" Verify: %.0f%% (%d/%d passed)\n", report.Before.VerifyPassRate, report.Before.VerifyPassed, report.Before.VerifyTotal)
+ fmt.Printf(" Pipeline: %s\n", boolStatus(report.Before.DataPipeline))
+ fmt.Printf(" Commands: %d\n", report.Before.CommandCount)
+
+ if report.After != nil {
+ fmt.Println("\nAFTER:")
+ fmt.Printf(" Scorecard: %d/100 (Grade %s)\n", report.After.ScorecardTotal, report.After.ScorecardGrade)
+ fmt.Printf(" Verify: %.0f%% (%d/%d passed)\n", report.After.VerifyPassRate, report.After.VerifyPassed, report.After.VerifyTotal)
+ fmt.Printf(" Pipeline: %s\n", boolStatus(report.After.DataPipeline))
+ fmt.Printf(" Commands: %d\n", report.After.CommandCount)
+ }
+
+ if report.Delta != nil {
+ fmt.Println("\nDELTA:")
+ fmt.Printf(" Scorecard: %+d\n", report.Delta.ScorecardDelta)
+ fmt.Printf(" Verify: %+.0f%%\n", report.Delta.VerifyDelta)
+ fmt.Printf(" Commands: %+d\n", report.Delta.CommandDelta)
+ if report.Delta.PipelineFixed {
+ fmt.Println(" Pipeline: FIXED")
+ }
+ }
+
+ if len(report.Improvements) > 0 {
+ fmt.Println("\nIMPROVEMENTS:")
+ for i, imp := range report.Improvements {
+ fmt.Printf(" %d. %s\n", i+1, imp)
+ }
+ }
+
+ return nil
+}
+
+func scorecardGrade(total int) string {
+ switch {
+ case total >= 85:
+ return "A"
+ case total >= 65:
+ return "B"
+ case total >= 50:
+ return "C"
+ default:
+ return "D"
+ }
+}
+
+func boolStatus(b bool) string {
+ if b {
+ return "PASS"
+ }
+ return "FAIL"
+}
diff --git a/internal/cli/root.go b/internal/cli/root.go
index 3f12aeb6..c341d6f2 100644
--- a/internal/cli/root.go
+++ b/internal/cli/root.go
@@ -40,6 +40,7 @@ func Execute() error {
rootCmd.AddCommand(newScorecardCmd())
rootCmd.AddCommand(newDogfoodCmd())
rootCmd.AddCommand(newVerifyCmd())
+ rootCmd.AddCommand(newEmbossCmd())
rootCmd.AddCommand(newVisionCmd())
rootCmd.AddCommand(newVersionCmd())
rootCmd.AddCommand(newPrintCmd())
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index 59951276..e757a363 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -24,8 +24,102 @@ Generate the best CLI that has ever existed for any API. Five mandatory phases.
/printing-press Plaid payments API
/printing-press --spec ./openapi.yaml
/printing-press Discord codex # Codex mode: offload code generation to save Opus tokens
+/printing-press emboss ./discord-cli # Second pass: improve an existing CLI
```
+## Emboss Mode (Second Pass)
+
+When the user's arguments start with `emboss`, this is NOT a from-scratch run. The CLI already exists. Run a 30-minute improvement cycle.
+
+```
+if the user's arguments start with "emboss":
+ EMBOSS_MODE = true
+ EMBOSS_DIR = first argument after "emboss"
+ Verify the directory exists and contains a Go CLI (check for cmd/ and internal/cli/)
+else:
+ EMBOSS_MODE = false (default - normal generation)
+```
+
+### The Emboss Cycle (6 steps, ~30 minutes)
+
+**Step 1: AUDIT (5 min)** - Get a baseline without changing anything.
+
+```bash
+cd ~/cli-printing-press && ./printing-press emboss --dir <cli-dir> --spec <spec-path> --audit-only
+```
+
+Read the output. Note the scorecard score, verify pass rate, data pipeline status, and command count. This is the "before" snapshot.
+
+Also read:
+- The CLI's README for what commands exist
+- Any Phase 0-5 artifacts in `docs/plans/` for this API
+- The CLI's `internal/cli/root.go` to catalog registered commands
+
+**Step 2: RE-RESEARCH (10 min)** - What's changed since v1?
+
+This is NOT a full Phase 0 redo. Run targeted searches:
+
+1. **WebSearch**: `"<API name>" CLI tool 2026` (any new competitors since v1?)
+2. **WebSearch**: `"<API name>" "I wish" OR "I built" site:reddit.com OR site:news.ycombinator.com` (new pain points?)
+3. Check npm: has anyone published a new CLI for this API?
+4. Check if the API spec has been updated (new endpoints?)
+
+Output: a "what's new" briefing (5-10 bullet points, not a full research document).
+
+**Step 3: GAP ANALYSIS (5 min)** - What are the top 5 improvements?
+
+Compare the audit baseline + re-research against what's possible. Score each potential improvement:
+
+| Improvement | User Impact (1-5) | Score Impact (1-5) | Effort (1-5, 5=easy) | Total |
+|------------|-------------------|-------------------|---------------------|-------|
+
+Pick the top 5. Present to the user for approval before building.
+
+Common improvement categories:
+- Fix broken commands (from verify failures)
+- Add missing workflow commands (from re-research)
+- Improve data layer (add tables, fix sync, add FTS5)
+- Polish README (add cookbook, fix examples)
+- Add new endpoints (from spec updates)
+
+**Step 4: IMPROVE (15 min)** - Build the top 5.
+
+For each approved improvement:
+1. Implement it (delegate to Codex if codex mode)
+2. Run `go build && go vet` to verify compilation
+3. Commit atomically: `feat(<api>): <improvement description>`
+
+**Step 5: RE-VERIFY (5 min)** - Prove it worked.
+
+```bash
+cd ~/cli-printing-press && ./printing-press emboss --dir <cli-dir> --spec <spec-path> --audit-only
+```
+
+Compare the new numbers to the baseline from Step 1.
+
+**Step 6: REPORT** - Tell the user the delta.
+
+```
+EMBOSS COMPLETE: <api>-cli
+ Scorecard: <before> -> <after> (+<delta>)
+ Verify: <before>% -> <after>% (+<delta>%)
+ Commands: <before> -> <after> (+<delta>)
+ Pipeline: <before> -> <after>
+ Top improvements: <list>
+```
+
+### Emboss Phase Gate
+
+The emboss is successful if:
+- Scorecard improved by at least 3 points
+- Verify pass rate improved or stayed the same
+- No new critical failures introduced
+- All improvements compile and pass `go vet`
+
+If verify pass rate DECREASED, something broke. Revert the last improvement and investigate.
+
+---
+
## Codex Mode (Opt-In)
Add `codex` to the command to offload code generation (Phase 4, 4.5, 5.7) to Codex CLI. Claude stays the brain (research, planning, scoring, review). Codex does the hands (writing Go code). Saves ~60% Opus tokens per run.
← b5e6f02d fix(plugin): remove invalid skills field from plugin.json
·
back to Cli Printing Press
·
feat(emboss): complete baseline persistence, delta computati 75c37eb6 →