meta: insights-driven improvements — friction fixes, new features, and horizon agents

[Data-Wise]

Source: /insights session analysis (122 hours · 160 commits · 43 sessions)

Triage

Priority	Item	Effort	Section
P0	Squash-merge branch cleanup	Low	Friction
P0	mkdocs --strict PostToolUse hook template	Low	New Ways
P1	/release Skill	Medium	New Ways
P1	Headless mode docs + recipes	Low	New Ways
P2	Autonomous release pipeline agent	High	On the Horizon
P2	Docs-drift reconciliation agent	High	On the Horizon
P3	TDD swarm pattern	High	On the Horizon

---

Friction Fixes

Fix: squash-merge-aware branch cleanup

Branch cleanup deadlocks: squash-merged branches refuse git branch -d (not in ancestry) while branch-guard blocks force delete.

Solution: use git cherry <base> <branch> — if all commits are prefixed -, content is in base regardless of ancestry. Safe to force-delete.

# Confirm squash-merge before force-delete
git cherry dev <branch> | grep -v '^-' | grep -q '.' && echo "NOT merged" || echo "SAFE to delete"

• Add helper to lib/git-utils.sh
• Update branch-cleanup commands to use content comparison
• Branch-guard allows force-delete when squash-merge confirmed

---

New Ways to Use Claude Code

1. Custom Skills — codify /release as a Skill

The release workflow is the #1 repeated pipeline (14 sessions). Recurring friction: version/count/schema drift across files, Homebrew auto-bump firing with wrong version.

Proposed skills/release/SKILL.md:

1. Verify clean working tree
2. Reconcile versions across ALL surfaces: README badge · CHANGELOG · plugin.json · hub.md counts · mkdocs.yml extra.version · lockfiles · footers
3. Open release PR (multi-branch: dev → main; single-integration: feature → main)
4. Merge after CI green
5. Tag + publish
6. Patch Homebrew formula if auto-bump fires wrong version
7. Update .STATUS, push

• Create skills/release/SKILL.md
• Reconcile step explicitly audits all known stale locations
• Homebrew patch is idempotent
• Works for both branch patterns

2. Hooks — mkdocs --strict PostToolUse hook template

CI has no mkdocs build --strict gate — macros/Jinja errors and dead links stay invisible until a manual build. A PostToolUse hook surfaces failures immediately.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "command": "[ -f mkdocs.yml ] && mkdocs build --strict 2>&1 | tail -8 || true"
    }]
  }
}

• Add template to craft's hook library with documentation
• [ -f mkdocs.yml ] guard makes it a no-op in non-MkDocs repos
• Documented in hook reference with enable instructions

3. Headless Mode — batch docs audits and release tasks from scripts/CI

Many release/doc tasks (version reconcile, count audit, doc sweep) don't need interactive sessions.

Example recipes:

# Reconcile version references after a bump
claude -p "grep for old version X.Y.Z across all docs and config files, update to A.B.C" \
  --allowedTools "Edit,Read,Bash"

# Audit docs for count/schema drift
claude -p "audit docs/ for skill count drift vs tests/fixtures/expected-counts.js" \
  --allowedTools "Read,Bash"

# Post-release doc sweep
claude -p "verify all doc version references match package.json version" \
  --allowedTools "Read,Edit,Bash"

• Add headless mode section to craft docs with working examples
• At least 3 recipes: version reconcile · count audit · doc sweep
• CI usage example (GitHub Actions)

---

On the Horizon

Autonomous release pipeline agent

Sessions repeatedly cut off mid-pipeline (Homebrew check, CI polling, pak conflicts). A background agent that owns the full lifecycle without babysitting:

Phase 1 — Pre-release: version bump + full surface reconcile + open PR
Phase 2 — CI watch (background agent): poll CI every ~60s · on green: merge + tag + publish · self-correct known failures: Homebrew wrong-version → patch formula; pak/Remotes conflict → suggest pin; stale pathspec → re-stage
Phase 3 — Cleanup: update .STATUS · verify squash-merged branches via git cherry before delete

• /release --autonomous flag triggers background mode
• Self-corrects Homebrew wrong-version and pak dependency conflict
• Reports final state (live/blocked), no babysitting required
• Works for both branch patterns
• Depends on: /release Skill above

Docs-drift reconciliation agent

Docs reconciliation (count drift, phantom refs, broken examples) recurs every release. A standing agent that diffs shipped features against docs and files targeted PRs:

Audit pass: crawl docs/** · compare against exported functions + expected-counts · detect phantom refs · spot-check code examples · flag jargon forward-refs · check hub.md Gate 2/3
PR generation: one focused PR per confirmed gap · group related fixes · dedup against open PRs by file+line

• Invokable as /craft:docs:reconcile
• Produces structured gap report (file · line · gap type · fix)
• Opens targeted PRs, not one giant catch-all
• Dedup logic prevents reopening already-tracked gaps

TDD swarm — parallel per-layer agents with coordinator

Multi-layer features (data/core/CLI/MCP/zsh) run sequentially today. Fan-out pattern: one agent per layer, TDD until green, coordinator reconciles interfaces and catches schema drift.

Coordinator: define interface contract → write cross-layer e2e tests → fan out per-layer agents
Per-layer agents (parallel): red → green → report test count + coverage to coordinator
Reconcile: run e2e suite · flag count/schema drift (e.g. plugin.json vs expected-counts) · merge only when all layers + e2e pass

• /craft:tdd:swarm command or workflow template
• Interface contract step is explicit + user-confirmed before fan-out
• Per-layer agents run with isolation: "worktree"
• Works for any N-layer feature

---

Closes #221 #222 #223 #224 #225 #226 #227

[Data-Wise]

Audit breakdown: release skill item is DONE (skills/release/SKILL.md exists and matches spec). Still open, no code found: mkdocs build --strict PostToolUse hook, squash-merge-aware git-cherry-based branch-cleanup command, docs:reconcile/TDD-swarm commands, dedicated headless-mode guide. Recommend splitting each remaining item into its own small issue rather than tracking as one umbrella — happy to do that split on request.

[Data-Wise]

Audit finding (2026-07-26): re-scope, don't close outright.

Full re-check against current dev state, all 7 items:

Item	Verdict	Evidence
Squash-merge branch cleanup (P0)	MOOT	lib/git-utils.sh:5-29 is_squash_merged() (cherry fast-path + tree-diff fallback), wired into scripts/branch-guard.sh:676-684. Commit a6e08a01a.
mkdocs --strict PostToolUse hook (P0)	MOOT	skills/hooks/SKILL.md:24-27 ships this exact template. Same commit.
/release Skill (P1)	MOOT	skills/release/SKILL.md exists, matches spec.
Headless mode docs + recipes (P1)	MOOT	docs/guide/headless-recipes.md — 3 recipes + GitHub Actions example, matches acceptance criteria verbatim.
Autonomous release pipeline agent (P2)	Mostly shipped, different shape	skills/release/references/autonomous-mode.md covers safety checks, version auto-detection, CI monitoring, Homebrew update, CI-on-main verify under --autonomous. Not found by name: explicit self-correct for "Homebrew wrong-version" / "pak conflict."
/craft:docs:reconcile (P2)	VALID	No docs:reconcile command or reconcile/dedup-PR logic exists anywhere in the repo.
/craft:tdd:swarm (P3)	VALID (design only)	SPEC-orchestrate-swarm-2level-2026-06-18.md is a different feature (--swarm=2 nesting depth), not this. No commands/tdd/.

Recommendation: strike the 4 shipped items from this umbrella, spin docs:reconcile and tdd:swarm into their own small issues (both genuinely need a fresh design pass, not a quick fix), and close this one once that split happens. Not closing this comment alone — leaving that action to whoever picks up the split.