@matt82198/aesop 0.1.0-rc.1 → 0.2.0

package/skills/CLAUDE.md

@@ -1,4 +1,134 @@
 # skills/ — Orchestration and priming skills
 
-- **power/** — /power skill: prime the filesystem brain (load rules, dispatch model, memory, state) and report system health — see power/SKILL.md
-- **healthcheck/** — /healthcheck skill: check fleet health — one colored ball (heartbeats, alerts, orchestrator, tracker items) — see healthcheck/SKILL.md
+## Universal rules (every domain)
+- Feature branch only, never main; every push gated by `python tools/secret_scan.py --staged` exit 0.
+- Tests never pollute cwd or global git config; temp dirs only; dummy secrets are runtime-concatenated, never literal.
+- In worktrees use ABSOLUTE paths under the worktree for every write.
+- Domain docs stay minimal-but-complete; update this file in the same PR as code it describes.
+
+## Module layout
+
+Four orchestration skills, each invoked via CLI (e.g., `/buildsystem`, `/power`):
+
+- **power/** — prime the filesystem brain (load CLAUDE.md rules, dispatch model, memory, state); init-prime or fast-path for already-primed repos
+- **buildsystem/** — execute one complete orchestrated development wave (backlog rank → parallel Haiku fleet → merge train → checkpoint → audit)
+- **healthcheck/** — check fleet health (one colored ball: green/yellow/red based on heartbeats, alerts, orchestrator status)
+- **fleet/** — snapshot fleet state as JSON (agents, heartbeats, tracker lanes, orchestrator status) — never mutates
+
+## Buildsystem manifest & work-order contract
+
+**Backlog format** (`state/BACKLOG.md`):
+```markdown
+## P1: Critical
+- [ ] Task title — agent-type — time-estimate
+  Example: Fix secret-scan hang — backend-dev — 5min
+## P2: Features
+- [ ] Add feature X — frontend-dev — 8min
+## P3: Tech Debt
+- [ ] Refactor module Y — backend-dev — 15min
+```
+
+Time estimates: 3–5 min (typo/config), 5–10 min (function/test), 10–15 min (module refactor), 15+ min (split smaller).
+
+**Work-order contract** (each agent receives):
+- Task: one backlog item (feature/fix/tech debt)
+- Agent type: backend-dev, frontend-dev, test-bot, docs-agent, etc.
+- Time budget: 3–10 min (Haiku best-effort scope)
+- Scope: reproduce, change location, test command, commit message template
+- Constraints: never modify CLAUDE.md/STATE.md, must pass pre-commit hook, no external calls
+
+**Preflight guard invariant** (wave-flat-dispatch.template.mjs):
+- No two backlog items may own the same file or directory
+- Each item assigned to exactly one agent
+- Preflight detects overlap and aborts with remediation plan before dispatch
+
+**Phases**:
+1. Preflight (1–2 min) — validate setup, check heartbeat, parse backlog, detect file overlap
+2. Backlog & Dispatch (5–10 min) — rank items, assign agents, create work orders
+3. Fleet Execution (30–90 min) — Haiku agents work in parallel, in isolated worktrees
+4. Code Review & Integration (10–30 min) — run CI, merge train (serial), flag failures
+5. Checkpoint & Audit (2–5 min) — update STATE.md, append BUILDLOG.md, commit + push
+
+**Worktree isolation** (critical):
+- Each agent runs in `aesop-wt-<wave>-<agent-id>/` (independent branch, HEAD, working dir)
+- Zero cross-agent interference
+- Automatic cleanup after wave closes
+
+**Merge serialization** (critical):
+- All PRs from a wave merge through serial merge train
+- First agent to green CI merges, next waits for main to stabilize, re-tests, then merges
+
+## Power skill
+
+Two entry paths:
+
+1. **Init-prime** (unprimed repo, no CLAUDE.md): fan-out Haiku explorers → synthesize project CLAUDE.md + domain units + STATE.md seed → commit + push
+2. **Already-primed** (fast path): load global rules (`~/.claude/CLAUDE.md`), load memory (MEMORY.md), load active project STATE.md, report compact brief, optionally spin up app and monitor background loops
+
+Prerequisites: Aesop scaffolded into repo via CLI (`npx @matt82198/aesop . --name "my-project"`).
+
+## Healthcheck skill
+
+One-line status command: `python tools/healthcheck.py` (or `--json` for machine-readable).
+
+Output ball:
+- **🟢 Green** — watchdog <300s, monitor <3600s, no HIGH alerts
+- **🟡 Yellow** — stale heartbeat OR unreviewed MED alert
+- **🔴 Red** — HIGH alert OR watchdog dead (>600s) during active dispatch
+
+## Fleet skill
+
+One-shot snapshot: `aesop fleet` (JSON output, read-only, never mutates state).
+
+Returns:
+- heartbeats (watchdog, monitor: age, status, thresholds)
+- agents (active: id, project, status, age, tokens, task label)
+- tracker (backlog counts by lane)
+- orchestrator (activity, phase, timestamp)
+
+Graceful degradation: missing files produce `unavailable: "<reason>"` entries.
+
+## Test commands
+
+- **buildsystem**: Run a full wave (in a test repo with mock backlog)
+  ```bash
+  cd <test-repo>
+  /buildsystem
+  # Verify: STATE.md updated, BUILDLOG.md appended, PRs merged
+  ```
+- **power**: Prime a new repo or already-primed repo
+  ```bash
+  /power
+  # Verify: compact brief output, CLAUDE.md files readable, STATE.md NEXT STEPS clear
+  ```
+- **healthcheck**: Check fleet health
+  ```bash
+  python tools/healthcheck.py
+  python tools/healthcheck.py --json
+  ```
+- **fleet**: Snapshot fleet state
+  ```bash
+  aesop fleet
+  # Verify: JSON valid, heartbeats present, agents or "unavailable" message
+  ```
+
+## Key invariants & gotchas
+
+1. **Buildsystem is stateless across phases** — each phase stands alone (safe to restart mid-wave)
+2. **Backlog must be parseable** (YAML or markdown, consistent format) — preflight will abort on parse errors
+3. **File ownership overlap is fatal** — preflight guard prevents two agents from touching same file
+4. **Worktrees auto-cleanup** — don't manually delete `aesop-wt-*` dirs; buildsystem handles it
+5. **Power init-prime writes repo files** — controlled commit + push via secret-scan gate
+6. **Healthcheck is read-only** — diagnostics only, never repairs
+7. **Fleet snapshot is JSON canonical** — orchestrators use this, not ad-hoc state reads
+
+## Domain-specific details
+
+Each skill has its own **SKILL.md** file in its directory with complete implementation details, manifests, and troubleshooting:
+
+- `skills/buildsystem/SKILL.md` — phases, manifest, work-order contract, troubleshooting
+- `skills/power/SKILL.md` — init-prime and fast-path workflows
+- `skills/healthcheck/SKILL.md` — diagnostics and repair procedures
+- `skills/fleet/SKILL.md` — snapshot structure and queries
+
+Map of all domains: /CLAUDE.md

package/skills/buildsystem/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: buildsystem
+description: Execute one orchestrated development wave — rank backlog, dispatch Haiku fleet in parallel, merge train, checkpoint, closing audit.
+version: 1.0.0
+---
+
+# Buildsystem — Orchestrated Development Wave
+
+This skill automates one complete development wave: backlog prioritization, parallel Haiku agent dispatch, code review, merge train, and state checkpoint. It reads your `CLAUDE.md` rules and project backlog, then orchestrates a fleet of small, focused agents to deliver working features or fixes.
+
+**Core principle**: A wave is a bounded unit of work (2–4 hours) that delivers measurable progress. The orchestrator dispatches independent Haiku agents to parallel worktrees, each agent works in isolation, all agents converge on a merge train, and the wave closes with a checkpoint and audit.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+Before running `/buildsystem`, ensure:
+
+1. **Repository is primed** — Run `/power` first to load your CLAUDE.md layer and confirm orchestrator brain health
+2. **Backlog exists** — Create a ranked backlog in `state/BACKLOG.md` or document your work items in the active `STATE.md`
+3. **Aesop is initialized** — Config file (`aesop.config.json`), watchdog running, state directory populated
+
+### One Command
+
+```bash
+/buildsystem
+```
+
+The orchestrator reads your backlog, dispatches agents, monitors progress, and delivers a closed wave with merged PRs.
+
+---
+
+## Wave Phases
+
+### Phase 0: Preflight (1–2 min)
+
+The orchestrator validates setup:
+- Confirms CLAUDE.md is loaded and rules are understood
+- Checks watchdog heartbeat (healthy daemon)
+- Validates backlog format and work-item sizing
+- Confirms all repos in config are cloned and clean
+- Detects any active uncommitted work or stale agent directories
+
+**Output**: Preflight report (green/red status, any blockers)
+
+If blockers exist, the wave aborts with remediation steps.
+
+### Phase 1: Backlog Rank & Dispatch (5–10 min)
+
+The orchestrator reads the backlog and assigns agents:
+- Rank work by priority (P1/P2/P3) and dependencies
+- Assign each item to an agent type (backend-dev, frontend-dev, test-bot, docs-agent, etc.)
+- Estimate size (Haiku time, ~3–10 min per item)
+- Create work orders for each agent
+
+**Output**: Dispatch summary showing which agent works on which item
+
+The orchestrator then spawns 3–8 Haiku agents in parallel, each with its own worktree and task brief.
+
+### Phase 2: Fleet Execution (30–90 min)
+
+Haiku agents work independently in parallel:
+- Each agent runs in its own worktree (no conflicts)
+- Implements the feature/fix
+- Writes tests and runs local verification
+- Commits to its feature branch (not main)
+- Pushes to origin
+
+The orchestrator monitors:
+- Agent heartbeats (alive/stalled detection)
+- Build/test results (compile, unit tests)
+- Token usage and cost
+- Agent runtime (total time, cost per agent)
+
+**Output**: Real-time agent status, progress updates
+
+### Phase 3: Code Review & Integration (10–30 min)
+
+Pull requests are created automatically as agents push. The orchestrator:
+- Collects all PRs from this wave
+- Routes them through review (linters, unit tests, integration tests)
+- Approves and merges PRs that pass (green CI)
+- Flags PRs with failures for manual triage
+
+**Output**: Merge train progress, any PRs awaiting triage
+
+### Phase 4: Checkpoint & Audit (2–5 min)
+
+The wave closes:
+- Confirms all work is merged to main
+- Updates `STATE.md` with phase completion, NEXT STEPS
+- Appends summary line to `BUILDLOG.md`
+- Runs closing audit (security scan, coverage, test count, code quality metrics)
+- Commits and pushes checkpoint files
+
+**Output**: Wave closed, audit report, ready for next wave
+
+---
+
+## Backlog Format
+
+Create a `state/BACKLOG.md` file or update `STATE.md` with your ranked work:
+
+```markdown
+# Wave 15 Backlog
+
+## P1: Critical
+
+- [ ] Fix secret-scan gate hang (blocking CI) — backend-dev — 5min
+- [ ] Update MEMORY.md with wave-15 learnings — docs-agent — 3min
+
+## P2: Features
+
+- [ ] Add cost-ceiling dashboard widget — frontend-dev — 8min
+- [ ] Implement fleet-ops monitoring — backend-dev — 10min
+
+## P3: Tech Debt
+
+- [ ] Refactor monitor/collect-signals.mjs (duplicate checks) — backend-dev — 15min
+- [ ] Add type hints to Python tools — test-bot — 10min
+```
+
+**Sizing guide**:
+- **3–5 min**: Typo fix, simple config change, one-line refactor
+- **5–10 min**: New function, small feature, unit test
+- **10–15 min**: Module refactor, feature with 2–3 functions
+- **15+ min**: Split into smaller items (waves work best in 30–90 min total)
+
+**Priorities**:
+- **P1**: Blockers, security fixes, showstoppers
+- **P2**: Features, quality, important bug fixes
+- **P3**: Tech debt, docs, refactoring, minor improvements
+
+---
+
+## Work-Order Contract
+
+Each agent receives a work order (brief) describing:
+
+```
+Agent: haiku-backend-dev-5
+Task: Fix secret-scan gate hang (blocking CI)
+Backlog Item: Wave 15 / P1
+Time Budget: 5 min (0 buffer)
+Scope: Identify why secret_scan.py times out on large staged files; implement fast path or raise limit.
+  - Reproduce: git add large-file && git push (hangs at secret-scan gate)
+  - Change: Modify tools/secret_scan.py line 42 OR config file
+  - Test: Verify gate completes within 10s for fixture data
+  - Commit message: fix(security): secret-scan gate timeout on large files
+Constraints:
+  - Never modify CLAUDE.md or STATE.md
+  - Must pass pre-commit hook
+  - Use Haiku best-effort only (no external calls, no model training)
+```
+
+The agent reads the work order, implements the change, commits, and pushes the feature branch. The orchestrator then integrates the work.
+
+---
+
+## Orchestrator Isolation & Safety
+
+### Disjoint File Ownership (Preflight Guard)
+
+The orchestrator enforces a critical safety invariant: **no two agents should modify the same file in a single wave**.
+
+Before dispatch, the preflight verifies:
+- Each backlog item is assigned to exactly one agent
+- No two items touch the same file or directory (checked via domain map)
+- If overlap is detected, the wave aborts with a remediation plan (reorder/resplit items)
+
+This guard is the Preflight phase of `skills/buildsystem/wave-flat-dispatch.template.mjs` (ships with aesop): it refuses to dispatch when two manifest items own the same file, returning `{aborted: true, reason: 'ownership_overlap'}` before any worker spawns.
+
+### Worktree Isolation
+
+Each agent runs in its own git worktree (`aesop-wt-<wave>-<agent-id>/`):
+- Independent branch, independent HEAD, independent working directory
+- No git conflicts (git worktree is designed for this)
+- Automatic cleanup after wave closes
+- Zero cross-agent interference
+
+### Single-Merge Serialization
+
+All PRs from a wave merge through a serial merge train:
+- First agent to reach green CI merges
+- Next agent waits for main to stabilize, re-tests, then merges
+- Prevents race conditions (all PRs are based on stable main at merge time)
+
+---
+
+## Monitoring & Cost
+
+The dashboard (`aesop dashboard`) shows real-time wave progress:
+- **Phase**: Current phase (dispatch, execution, review, checkpoint)
+- **Agents**: Running agents, age, tokens used, task
+- **PRs**: Open PRs this wave, pass/fail status, review progress
+- **Cost**: Total tokens, per-agent cost, cost vs budget
+- **ETA**: Estimated wave completion time
+
+The orchestrator emits heartbeats every 10s so you can monitor progress without polling.
+
+---
+
+## Failure & Remediation
+
+### Agent Stalls
+
+If an agent hasn't updated its heartbeat for 5 min, the orchestrator:
+1. Checks the agent's transcript (last 50 lines of .claude/transcript.jsonl)
+2. Determines if the agent is:
+   - **Stuck in a loop** (repeating the same error)
+   - **Waiting for input** (blocked on a prompt, should never happen)
+   - **Genuinely stalled** (no heartbeat for 10+ min)
+3. Terminates the stalled agent and reports the failure
+4. Optionally retries the work item (if within retry budget: 2 retries max)
+
+### PR Failures
+
+If a PR doesn't pass CI (linter, test failures):
+1. The orchestrator collects the failure reason from CI logs
+2. Routes the PR to a human reviewer or re-dispatch a fix agent
+3. Documents the failure in BUILDLOG.md for the wave audit
+4. Tracks retries to avoid infinite loops
+
+### Preflight Blockers
+
+If preflight detects blockers:
+- Reports the blocker with remediation steps
+- Aborts the wave (safe-fail)
+- Suggests fixes (e.g., "split item X into X.1 and X.2" or "commit pending work first")
+
+---
+
+## Closing Audit
+
+At wave end, the orchestrator runs a closing audit:
+
+**Security**: Runs secret-scan on all merged code (no secrets shipped)
+
+**Coverage**: Compares test coverage before/after wave (target: no decrease)
+
+**Quality**: Counts:
+- Total files changed
+- Total LOC changed
+- Total commits
+- Total agent time (sum of all agent runtimes)
+- PR review cycle time (avg time from push to merge)
+
+**Output**: Audit report in `state/BUILDLOG.md`, sample:
+
+```
+Wave 15 closed (phase 4/4)
+  Agents: 5 (haiku-backend-dev-1, haiku-frontend-dev-1, haiku-test-bot-1, haiku-docs-agent-1, haiku-backend-dev-2)
+  Time: 87 min (dispatch 6m, exec 65m, review 12m, checkpoint 4m)
+  Backlog: 7 items, 1 skipped (P1: 2/2, P2: 4/4, P3: 1/1)
+  PRs: 6 merged, 0 failed, 1 retry
+  Coverage: 82% → 84% (+2%)
+  Security: clean
+  NEXT STEPS: (1) review MEMORY.md updates, (2) stage wave-16 backlog
+```
+
+---
+
+## Best Practices
+
+1. **Size work for Haiku** — Each item should take 1–2 Haiku tokens (3–10 min). Too large and agents will fail mid-task.
+
+2. **Use domain map** — Ensure your `CLAUDE.md` layer has a clear domain map so the preflight guard can validate assignments.
+
+3. **One wave per session** — Run `/buildsystem` once per session (not repeatedly). Use the closing audit to inform the next wave.
+
+4. **Monitor in real-time** — Open the dashboard (`aesop dashboard`) to watch agents work. This builds confidence and catches stalls early.
+
+5. **Commit backlog to git** — Keep your backlog (`state/BACKLOG.md`) in git so wave history is durable and reviewable.
+
+6. **Review NEXT STEPS** — After wave closes, read `STATE.md` NEXT STEPS and `BUILDLOG.md` audit report to plan the next wave.
+
+---
+
+## Troubleshooting
+
+### Wave hangs on Phase 1 (dispatch)
+
+**Cause**: Backlog parsing error or domain-map conflict detected.
+
+**Fix**:
+1. Check `state/BACKLOG.md` format (YAML or markdown, consistent)
+2. Verify each item has: `- [ ] Title — agent-type — time-estimate`
+3. Run `aesop doctor` to verify domain map
+4. Retry: `/buildsystem`
+
+### Wave reports "Preflight blockers"
+
+**Cause**: Uncommitted work, repo not clean, or agent directory conflict.
+
+**Fix**:
+1. Commit all pending work: `git add -A && git commit -m "checkpoint: pending work"` (in each repo)
+2. Confirm watchdog is running: `bash daemons/run-watchdog.sh --once`
+3. Clean up stale worktrees: `git worktree prune`
+4. Retry: `/buildsystem`
+
+### Agent stalls mid-task
+
+**Cause**: Infinite loop, network issue, or model rate-limit.
+
+**Fix**:
+1. Check agent transcript: `tail -50 <wave-workdir>/transcript.jsonl`
+2. Understand the loop (repeating error?) and file an issue
+3. Manually fix the work item or retry in next wave
+4. Document the failure in BUILDLOG.md
+
+### PR fails CI (linter/test)
+
+**Cause**: Agent didn't run tests locally or introduced a bug.
+
+**Fix**:
+1. Review the PR diff and CI logs
+2. Comment on the PR with remediation
+3. Assign a fix agent or manually fix
+4. Retry: `/buildsystem wave-<N>-retry` to re-merge just this PR
+
+---
+
+## See Also
+
+- **[/power skill](../power/SKILL.md)** — Prime your orchestrator brain before running a wave
+- **[FIRST-WAVE.md](../docs/FIRST-WAVE.md)** — Tutorial on running your first wave
+- **[CLAUDE.md format](../docs/CONFIGURE.md#claudemd-layer)** — Document your codebase for agents
+- **[Wave architecture](../docs/ARCHITECTURE.md#wave-cycle)** — Deep dive on the orchestration model