docs(plans): nightnight chaining plan + E2E test plan for pipeline

01f4439662cead67a2967d79bf2c45e983158a28 · 2026-03-24 07:54:25 -0700 · Matt Van Horn
Files touched

A docs/plans/2026-03-24-feat-pipeline-nightnight-chaining-plan.md
A docs/plans/2026-03-24-test-pipeline-e2e-petstore-plan.md
Diff

commit 01f4439662cead67a2967d79bf2c45e983158a28
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date:   Tue Mar 24 07:54:25 2026 -0700

    docs(plans): nightnight chaining plan + E2E test plan for pipeline
---
 ...03-24-feat-pipeline-nightnight-chaining-plan.md | 155 +++++++++++++++++++++
 .../2026-03-24-test-pipeline-e2e-petstore-plan.md  | 155 +++++++++++++++++++++
 2 files changed, 310 insertions(+)

diff --git a/docs/plans/2026-03-24-feat-pipeline-nightnight-chaining-plan.md b/docs/plans/2026-03-24-feat-pipeline-nightnight-chaining-plan.md
new file mode 100644
index 00000000..dd60a47e
--- /dev/null
+++ b/docs/plans/2026-03-24-feat-pipeline-nightnight-chaining-plan.md
@@ -0,0 +1,155 @@
+---
+title: "Pipeline Nightnight-Style Chaining - Autonomous Phase Execution"
+type: feat
+status: active
+date: 2026-03-24
+---
+
+# Pipeline Nightnight-Style Chaining
+
+## Overview
+
+Update the printing-press SKILL.md with Workflow 4 (autonomous pipeline) and Workflow 5 (resume). When the user says `/printing-press print gmail`, the skill initializes the pipeline, then chains through 6 phases - each one running ce:plan to expand the seed into a full plan, then ce:work to execute it, then CronCreate to chain to the next phase with fresh context.
+
+Modeled directly on osc-nightnight's proven patterns: checkpoint-based resumption, heartbeat safety net, mechanical budget gate, JSONL event logging.
+
+## Acceptance Criteria
+
+- [ ] SKILL.md has Workflow 4 (autonomous pipeline) with full phase loop
+- [ ] SKILL.md has Workflow 5 (resume pipeline)
+- [ ] Skill allowed-tools includes Skill, Agent, CronCreate, CronList, CronDelete, Edit
+- [ ] Heartbeat CronCreate scheduled at pipeline start (45 min safety net)
+- [ ] Phase chain CronCreate scheduled after each phase completes (30 sec)
+- [ ] Budget gate checks elapsed time between phases (3h max)
+- [ ] Resume mode loads state.json and runs budget gate FIRST
+- [ ] Morning report written on completion or budget exhaustion
+- [ ] Error handling: retry once per phase, skip after 2 failures, never die silently
+- [ ] Version bumped to 0.4.0
+
+## Implementation Units
+
+### Unit 1: Update SKILL.md Frontmatter
+
+**Files:** `skills/printing-press/SKILL.md`
+
+**Approach:**
+- Bump version from 0.3.0 to 0.4.0
+- Add to allowed-tools: `Skill`, `Agent`, `Edit`, `CronCreate`, `CronList`, `CronDelete`
+- Update description to mention autonomous pipeline
+
+### Unit 2: Write Workflow 4 - Autonomous Pipeline
+
+**Files:** `skills/printing-press/SKILL.md`
+
+**Approach:** Insert after Workflow 3 (Submit to Catalog), before Safety Gates section.
+
+Workflow 4 structure:
+
+```
+When user says "print <api-name>":
+
+Step 1: Initialize
+  - Build press binary: go build -o ./printing-press ./cmd/printing-press
+  - Run: ./printing-press print <api-name> [--output] [--force]
+  - This creates docs/plans/<api-name>-pipeline/ with 6 plan seeds + state.json
+
+Step 2: Heartbeat safety net
+  - CronCreate 45 min from now: "/printing-press print <api-name> --resume"
+  - Uses: date -v+45M '+%M %H %d %m' for cron time
+
+Step 3: Phase execution loop
+  For each phase in state.json where status != "completed":
+    a. Read the plan seed at state.phases[phase].plan_path
+    b. Run Skill("compound-engineering:ce:plan", plan_path)
+       - ce:plan expands the seed with parallel research agents
+    c. Run Skill("compound-engineering:ce:work", plan_path)
+       - ce:work implements, tests, checks off criteria
+    d. Update state.json: mark phase "completed"
+    e. Run budget gate (Step 4)
+    f. If more phases remain:
+       - CronCreate 30 sec from now: "/printing-press print <api-name> --resume"
+       - Print: "[phase] Complete. Chaining to [next] in 30s..."
+       - END SESSION (fresh context for next phase)
+
+Step 4: Budget gate (between every phase)
+  python3 -c "
+  import json, datetime
+  s = json.load(open('docs/plans/<api-name>-pipeline/state.json'))
+  started = datetime.datetime.fromisoformat(s['started_at'])
+  elapsed = (datetime.datetime.now() - started).total_seconds() / 3600
+  if elapsed > 3:
+      print('STOP')
+  else:
+      print('CONTINUE')
+  "
+  If STOP: go to Step 5 (morning report), do NOT chain.
+
+Step 5: Morning report
+  Write docs/plans/<api-name>-pipeline/report.md:
+  - API name, spec source, spec URL
+  - Phases completed vs total
+  - Resources and endpoint count (from scaffold output)
+  - Enrichments applied (from overlay.yaml if exists)
+  - Quality score (from review phase if reached)
+  - Total elapsed time
+  - Next steps for the human
+```
+
+**Patterns to follow:** osc-nightnight SKILL.md - CronCreate syntax, budget gate python3 command, heartbeat scheduling, resume logic
+
+### Unit 3: Write Workflow 5 - Resume Pipeline
+
+**Files:** `skills/printing-press/SKILL.md`
+
+**Approach:**
+
+```
+When user says "resume <api-name>" or "--resume" flag:
+
+1. Load docs/plans/<api-name>-pipeline/state.json
+2. MANDATORY: Run budget gate FIRST (before any work)
+3. If STOP: write morning report if not already written, exit
+4. If CONTINUE:
+   - Show status: which phases done, which is next
+   - Delete heartbeat cron if stale
+   - Schedule new heartbeat (45 min)
+   - Go to Workflow 4 Step 3 (phase loop)
+```
+
+### Unit 4: Error Handling Section
+
+**Files:** `skills/printing-press/SKILL.md`
+
+**Approach:** Add error handling rules to Workflow 4:
+
+- If ce:plan fails on a phase: log error to state.json errors array, retry once. If still fails, mark phase "failed", skip to next phase.
+- If ce:work fails: retry once with same plan. If still fails, mark "failed", skip to next.
+- If 2+ consecutive phases fail: write morning report and STOP. Do not chain.
+- NEVER die silently. Always update state.json before ending a session.
+- If CronCreate fails: print manual resume command as fallback.
+
+### Unit 5: Update Limitations Section
+
+**Files:** `skills/printing-press/SKILL.md`
+
+**Approach:** Update limitations to reflect current capabilities:
+- Remove "OAuth2 flows are simplified to bearer_token" (now fully supported)
+- Remove "Generated CLIs do not include retry/rate-limiting" (now included)
+- Update endpoint cap from 20 to 50
+- Add: "Pipeline mode requires Compound Engineering plugin"
+- Add: "Pipeline budget gate is 3 hours max"
+
+**Verification:** Read the final SKILL.md, verify all 5 workflows are present, frontmatter is correct, and the phase loop matches nightnight's pattern.
+
+## Scope Boundaries
+
+- Don't modify Go code - this plan is SKILL.md only
+- Don't implement the actual phase logic in Go - the skill orchestrates via Bash/Skill calls
+- Don't add new plan seed templates - those already exist in seeds.go
+
+## Sources
+
+- osc-nightnight: `~/.claude/skills/osc-nightnight/SKILL.md` - CronCreate syntax, budget gate, heartbeat, resume logic
+- Current skill: `skills/printing-press/SKILL.md` - existing 4 workflows to extend
+- Pipeline state: `internal/pipeline/state.go` - PipelineState, PhaseOrder, status constants
+- Pipeline init: `internal/pipeline/pipeline.go` - Init() creates dir + seeds
diff --git a/docs/plans/2026-03-24-test-pipeline-e2e-petstore-plan.md b/docs/plans/2026-03-24-test-pipeline-e2e-petstore-plan.md
new file mode 100644
index 00000000..98c38ae6
--- /dev/null
+++ b/docs/plans/2026-03-24-test-pipeline-e2e-petstore-plan.md
@@ -0,0 +1,155 @@
+---
+title: "E2E Test - Run Pipeline on Petstore"
+type: test
+status: active
+date: 2026-03-24
+---
+
+# E2E Test - Run Pipeline on Petstore
+
+## Overview
+
+Run `printing-press print petstore` end-to-end. Verify the pipeline directory is created with plan seeds, state.json tracks all phases, and then manually execute each phase's plan to verify the full pipeline produces a working CLI.
+
+Petstore is the simplest spec (3 resources, 13 endpoints, no OAuth2) - ideal for validating the pipeline machinery without complexity from the API itself.
+
+## Acceptance Criteria
+
+- [ ] `printing-press print petstore` creates `docs/plans/petstore-pipeline/` with 6 plan seeds
+- [ ] `state.json` has all 6 phases with status "planned" and correct plan paths
+- [ ] Each plan seed has proper frontmatter (title, type, status, date)
+- [ ] Each plan seed has acceptance criteria and implementation units
+- [ ] Plan seeds reference correct spec URL (petstore3.swagger.io)
+- [ ] Preflight plan can be executed: Go check passes, spec downloads, conventions cached
+- [ ] Scaffold plan can be executed: CLI generates, 7 quality gates pass
+- [ ] Generated petstore-cli compiles and `--help` works
+- [ ] Generated petstore-cli `doctor` runs
+- [ ] Pipeline cleanup: remove test artifacts after verification
+
+## Implementation Units
+
+### Unit 1: Build and Run Print Command
+
+**Approach:**
+```bash
+cd ~/cli-printing-press
+go build -o ./printing-press ./cmd/printing-press
+./printing-press print petstore --output /tmp/petstore-e2e-test
+```
+
+**Verify:**
+- Directory `docs/plans/petstore-pipeline/` exists
+- Contains: `00-preflight-plan.md` through `05-ship-plan.md` (6 files)
+- Contains: `state.json`
+- No errors in output
+
+### Unit 2: Validate State File
+
+**Approach:**
+```bash
+cat docs/plans/petstore-pipeline/state.json | python3 -m json.tool
+```
+
+**Verify:**
+- `api_name` is "petstore"
+- `spec_url` is the Petstore swagger URL
+- All 6 phases present with status "planned"
+- Each phase has a `plan_path` pointing to the correct file
+
+### Unit 3: Validate Plan Seed Quality
+
+**Approach:**
+Read each plan seed and verify:
+
+```bash
+for f in docs/plans/petstore-pipeline/*.md; do
+  echo "=== $(basename $f) ==="
+  head -10 "$f"
+  grep -c "Acceptance Criteria\|Implementation Units" "$f"
+  echo ""
+done
+```
+
+**Verify:**
+- Each plan has YAML frontmatter with title, type: feat, status: active, date
+- Each plan has `## Acceptance Criteria` section with checkboxes
+- Each plan has `## Implementation Units` section
+- Preflight plan references the Petstore spec URL
+- Scaffold plan references the output directory
+
+### Unit 4: Execute Preflight Phase Manually
+
+**Approach:**
+Execute the preflight plan's acceptance criteria by hand:
+
+```bash
+# Check Go
+go version
+
+# Check press compiles
+go build -o /tmp/pp-check ./cmd/printing-press
+
+# Download and verify spec
+curl -sL "https://petstore3.swagger.io/api/v3/openapi.json" -o /tmp/petstore-spec.json
+head -5 /tmp/petstore-spec.json  # Should show openapi: 3.x
+```
+
+**Verify:**
+- Go 1.23+ installed
+- Press binary compiles
+- Spec downloads and starts with `openapi` or `"openapi"`
+
+### Unit 5: Execute Scaffold Phase Manually
+
+**Approach:**
+```bash
+./printing-press generate --spec "https://petstore3.swagger.io/api/v3/openapi.json" --output /tmp/petstore-e2e-test
+```
+
+**Verify:**
+- All 7 quality gates pass (PASS in output)
+- CLI generated at /tmp/petstore-e2e-test
+
+### Unit 6: Dogfood the Generated CLI
+
+**Approach:**
+```bash
+cd /tmp/petstore-e2e-test
+go build -o petstore-cli ./cmd/petstore-cli
+./petstore-cli --help
+./petstore-cli pet --help
+./petstore-cli store --help
+./petstore-cli user --help
+./petstore-cli doctor
+./petstore-cli version
+```
+
+**Verify:**
+- Binary compiles
+- `--help` shows pet, store, user resources
+- `--no-color` flag present (from GOAT color work)
+- `doctor` runs without crash
+- `version` prints version
+
+### Unit 7: Cleanup
+
+**Approach:**
+```bash
+rm -rf docs/plans/petstore-pipeline/
+rm -rf /tmp/petstore-e2e-test
+rm -f /tmp/petstore-spec.json
+```
+
+## Scope Boundaries
+
+- Don't run ce:plan or ce:work on the plan seeds (that tests the full pipeline, not the infrastructure)
+- Don't test the nightnight chaining (that's a separate manual test after the skill is updated)
+- Don't test with Gmail or other complex specs (Petstore is sufficient for infrastructure validation)
+- Don't modify any code - this is pure verification
+
+## Sources
+
+- Pipeline init: `internal/pipeline/pipeline.go:Init()` - creates the pipeline directory
+- Plan seeds: `internal/pipeline/seeds.go` - seed templates per phase
+- State types: `internal/pipeline/state.go` - PipelineState, PhaseOrder
+- Discovery: `internal/pipeline/discover.go` - KnownSpecs registry with Petstore URL
← 6be0e67f Revert "feat(skill): add autonomous pipeline workflow with n · back to Cli Printing Press · feat(skill): add autonomous pipeline workflows with nightnig 9734d0c1 →