@matt82198/aesop 0.1.0 → 0.2.0

package/docs/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Aesop
+
+Aesop is **source-available** under the [PolyForm Strict License 1.0.0](../LICENSE). You may read, run, and use the software for any permitted purpose (noncommercial, personal, or organizational research), but **modification and redistribution are not permitted**.
+
+## Contribution Policy
+
+**Outside code patches cannot be merged as contributions** due to license terms. However, feedback and collaboration are genuinely welcome:
+
+- **Issues and bug reports** — describe what's broken or confusing.
+- **Discussion and ideas** — feature requests, design critiques, use-case questions.
+- **Code snapshots for discussion** — propose changes in issues or discussions without expecting merge.
+
+Code changes are made by the maintainer at their discretion. If you'd like to propose a change, open an issue first — describe the problem, your approach, and why it matters.
+
+## Running the Test Suites
+
+Aesop has three test suites:
+
+```bash
+# Node.js tests (orchestration skills, monitor, UI API)
+npm run test:node
+
+# Python tests (state_store, log rotation, secret-scan)
+npm run test:py
+
+# Bash tests (daemons, watchdog, hook policy)
+npm run test:sh
+
+# All suites
+npm run test:all
+```
+
+Each suite is self-contained and idempotent. Run them before proposing any changes.
+
+## Workflow (for Maintainers)
+
+Aesop develops itself via its own `/buildsystem` wave cycle. The process:
+
+1. **One issue per branch** — `feature/issue-name` branches only (never main).
+2. **Commit and push** — each commit triggers the pre-push hook.
+3. **Secret-scan gate** — `hooks/pre-push-policy.sh` blocks any credentials before they leave your machine.
+4. **Pull request** — PR runs CI and waits for merge-train coordination.
+5. **Checkpoint** — STATE.md and BUILDLOG.md capture wave state; both are git-committed and survive wipes.
+
+See [docs/ARCHITECTURE.md](./ARCHITECTURE.md) for the wave cycle diagram and [docs/HOW-THE-LOOP-WORKS.md](./HOW-THE-LOOP-WORKS.md) for a concrete walkthrough.
+
+## Code Style
+
+**Python**: Stdlib-first (no external deps except asyncio). Docstrings required; snake_case for functions and variables. See `tools/secret_scan.py` and `state_store/` for examples.
+
+**Node.js/JavaScript**: Node stdlib for tooling only (no external packages). Use async/await. See `daemons/`, `monitor/`, and `bin/` for patterns.
+
+**Bash**: POSIX-safe (no Bashisms; works in Git Bash on Windows). Sourceable scripts must guard with `[[ "${BASH_SOURCE[0]}" == "${0}" ]]`. See `hooks/pre-push-policy.sh` for structure.
+
+## Attribution
+
+Commits are authored with your git user.name. The repo signs all commits and uses co-author trailers for multi-person changes:
+
+```
+git commit -m "message
+
+Co-Authored-By: Alice <alice@example.com>
+Co-Authored-By: Bob <bob@example.com>"
+```
+
+## License & DCO
+
+By proposing changes, you affirm that you own or have the right to contribute your work and agree to license it under PolyForm Strict 1.0.0. See [LICENSE](../LICENSE) for the full terms.
+
+## Questions?
+
+Open an issue or discussion on GitHub. Read [docs/GOVERNANCE.md](./GOVERNANCE.md) for details on the decision-making process and [docs/RELIABILITY.md](./RELIABILITY.md) for the engineering principles behind Aesop.

package/docs/DEMO.md

@@ -0,0 +1,334 @@
+# Init-Prime-Demo: Your First Complete Aesop Flow
+
+**TL;DR**: This 10-minute walkthrough takes you from nothing to a working orchestration harness, primed and ready for your first wave.
+
+Covered in this demo:
+1. Create a toy project (just a git repo)
+2. Scaffold Aesop into a fleet harness
+3. Run `/power` to prime the orchestrator
+4. Understand what happens next
+
+---
+
+## What You'll Need
+
+Before starting, ensure you have:
+
+- **Node.js** v18+ (for scaffolder and CLI)
+- **Git** v2.40+ (for repo setup)
+- **Bash** v4+ (for daemons; Windows: Git Bash)
+- **Claude Code CLI** v0.1+ (for `/power` and `/buildsystem` skills)
+
+Check versions:
+```bash
+node --version
+git --version
+bash --version
+claude --version
+```
+
+---
+
+## Step 1: Create a Toy Project (2 min)
+
+This simulates a real project that Aesop will manage.
+
+```bash
+# Create a new directory and initialize git
+mkdir ~/my-demo-project
+cd ~/my-demo-project
+git init
+
+# Configure git (required for commits)
+git config user.email "demo@aesop.test"
+git config user.name "Demo User"
+
+# Create a sample file and make an initial commit
+echo "# My Demo Project" > README.md
+git add README.md
+git commit -m "Initial commit"
+```
+
+Your toy project is now ready. It's a clean git repo with one commit.
+
+---
+
+## Step 2: Scaffold Aesop (2 min)
+
+Create a fleet harness in a separate directory. The harness orchestrates your project(s).
+
+```bash
+# Go to a working directory (e.g., your home or ~/projects)
+cd ~
+
+# Scaffold Aesop (creates ~/demo-fleet/)
+npx @matt82198/aesop demo-fleet \
+  --name "demo-fleet" \
+  --repos "~/my-demo-project" \
+  --yes
+
+# Move into the harness
+cd ~/demo-fleet
+```
+
+What this does:
+- Creates `daemons/`, `skills/`, `monitor/`, `tools/`, `ui/`, `docs/` subdirectories
+- Generates `aesop.config.json` with your project path
+- Creates `CLAUDE.md` (orchestrator brain template)
+- Installs a git pre-push hook for secret scanning
+- Initializes a git repo in the harness
+
+Expected output:
+```
+✓ Creating ~/demo-fleet...
+✓ Copying scaffold files...
+✓ Generating CLAUDE.md...
+✓ Generating aesop.config.json...
+✓ Installing pre-push hook...
+✓ Initializing git repo...
+
+Next steps:
+  1. cd ~/demo-fleet
+  2. npx @matt82198/aesop doctor  # Verify preflight checks
+  3. /power                        # Prime orchestrator brain
+  4. /buildsystem                  # Run your first wave
+```
+
+---
+
+## Step 3: Verify Installation (1 min)
+
+Run preflight checks to ensure everything is ready.
+
+```bash
+npx @matt82198/aesop doctor
+```
+
+Expected output:
+```
+[doctor] Checking prerequisites...
+  ✓ Node.js v18.14.0 found
+  ✓ Git v2.42.0 found
+  ✓ Bash v5.1.16 found
+  ✓ Python v3.11.0 found (optional)
+  ✓ aesop.config.json is readable
+  ✓ Pre-push hook is installed and executable
+  ✓ Port 8770 is available (for dashboard)
+
+All checks passed. Ready to start.
+```
+
+If you see warnings about missing optional tools (Python, jq), that's OK for this demo. You can install them later.
+
+---
+
+## Step 4: Prime the Orchestrator (/power) (3 min)
+
+Now open Claude Code and invoke the `/power` skill. This reads your configuration and verifies the orchestrator is healthy.
+
+```
+/power
+```
+
+What `/power` does:
+1. Reads `~/.claude/CLAUDE.md` (your global orchestrator rules)
+2. Reads `aesop.config.json` (your fleet configuration)
+3. Checks `state/STATE.md` (current phase and next steps)
+4. Validates that daemons are healthy (checks heartbeat files)
+5. Reports a health brief
+
+Expected output:
+```
+Orchestrator Brain Loaded
+
+✓ Global rules (CLAUDE.md) loaded
+✓ Fleet config (aesop.config.json) loaded
+  - 1 repo configured: my-demo-project
+  - Brain root: ~/.claude
+  - State root: ~/demo-fleet/state
+✓ Fleet daemons: healthy (watchdog heartbeat ~30s old)
+✓ STATE.md initialized: Phase 1, ready for backlog
+
+NEXT STEPS:
+(1) Create a backlog (P1/P2 tasks)
+(2) Run /buildsystem to execute a complete wave cycle
+```
+
+If you see errors about missing CLAUDE.md or heartbeat files, don't worry—they'll be created on first startup. Re-run `/power` after a few seconds.
+
+---
+
+## Step 5: Understand the Backlog (Optional, 2 min)
+
+Before running your first wave, you need a backlog of work. The orchestrator dispatches agents to complete these tasks.
+
+Example backlog:
+```markdown
+## Wave 1 Backlog
+
+- **P1: Add setup documentation** (backend-dev) — Document the initial setup process
+- **P2: Fix README formatting** (docs-agent) — Improve readability of README.md
+- **P3: Add a test scaffold** (test-bot) — Create tests/ directory with example test
+```
+
+Each task should:
+- Fit in 5–15 minutes for a Haiku agent
+- Be scoped (not "refactor everything")
+- Have a priority (P1=blocker, P2=quality, P3=tech debt)
+- Be assigned to an agent type
+
+For this demo, you can skip this step and just observe what `/buildsystem` would do. Or create 2–3 simple tasks.
+
+---
+
+## Step 6: Run Your First Wave (Optional, 10+ min)
+
+Once you have a backlog, invoke `/buildsystem` in Claude Code:
+
+```
+/buildsystem
+```
+
+What `/buildsystem` does:
+1. **Rank & Assign** — Reads your backlog, assigns agents to tasks
+2. **Dispatch Fleet** — Spawns 3–8 Haiku agents in parallel worktrees
+3. **Execute** — Each agent works on its task independently
+4. **Verify** — Runs tests, checks compilation, validates changes
+5. **Merge Train** — Commits and pushes completed tasks
+6. **Checkpoint** — Saves state (STATE.md, BUILDLOG.md)
+
+You'll see live updates as agents work. Each task runs in isolation (no conflicts).
+
+Expected output:
+```
+Wave 1 / Rank & Assign
+  ✓ Task 1: Add setup documentation (backend-dev)
+  ✓ Task 2: Fix README formatting (docs-agent)
+  ✓ Task 3: Add test scaffold (test-bot)
+→ Dispatching 3 Haiku agents (est. 45–60 min)...
+
+[Agent 1: backend-dev] Working on Task 1...
+[Agent 2: docs-agent] Working on Task 2...
+[Agent 3: test-bot] Working on Task 3...
+
+Wave 1 / Merge Train
+  ✓ All agents completed
+  ✓ 3 PRs created
+  ✓ All tests passed
+  ✓ Merging to main...
+
+Wave 1 Complete
+  Duration: 47 minutes
+  Cost: 3,200 tokens
+  Files changed: 12
+  NEXT STEPS: Review BUILDLOG.md, run Wave 2 if needed
+```
+
+---
+
+## What Happened?
+
+You just ran a complete Aesop wave cycle:
+
+1. **Orchestrator** (you) → defined the backlog
+2. **Dispatch** (Aesop) → analyzed tasks, assigned agents
+3. **Execution** → 3+ Haiku agents worked in parallel (each in their own worktree)
+4. **Verification** → tests passed, code reviewed, merged
+5. **Checkpoint** → progress saved to `state/STATE.md` and `state/BUILDLOG.md`
+
+Each wave is independent. You can run wave 2 with a new backlog, or pause and review results.
+
+---
+
+## Exploring the Harness
+
+Now that you've seen it work, explore:
+
+### 1. Check the state files
+```bash
+cat state/STATE.md          # Current phase and next steps
+cat state/BUILDLOG.md       # Append-only progress log
+```
+
+### 2. View the dashboard (optional)
+```bash
+npx @matt82198/aesop dash  # Launches http://localhost:8770
+```
+
+Monitor waves in real-time: see active agents, heartbeats, logs, and costs.
+
+### 3. Check the daemons
+```bash
+ls -la daemons/
+bash daemons/run-watchdog.sh --once  # Run watchdog once (no daemon)
+```
+
+The watchdog handles backup, secret scanning, and fleet health checks.
+
+### 4. Review the configuration
+```bash
+cat aesop.config.json       # Your fleet configuration
+cat CLAUDE.md               # Orchestrator brain (domain map, rules)
+```
+
+---
+
+## Scaling to Real Projects
+
+Once you're comfortable with the demo flow, you can:
+
+1. **Add more repos** — Edit `aesop.config.json` and list your real projects
+2. **Customize domains** — Edit `CLAUDE.md` to define your team structure
+3. **Tune the backlog** — Work with your team to prioritize tasks
+4. **Run continuous waves** — Schedule `/buildsystem` to run on a cadence
+5. **Set cost ceilings** — Add spending limits to prevent runaway bills
+
+See [CONFIGURE.md](CONFIGURE.md) and [INSTALL.md](INSTALL.md) for full details.
+
+---
+
+## Troubleshooting
+
+**Q: `/power` says "CLAUDE.md not found"**
+- A: Copy the skills to your Claude Code home:
+  ```bash
+  cp -r skills/power ~/.claude/skills/
+  cp -r skills/buildsystem ~/.claude/skills/
+  ```
+
+**Q: `aesop doctor` reports missing Python**
+- A: Python is optional for the demo. If you want secret scanning or log rotation, install it:
+  ```bash
+  python3 --version  # Check if installed
+  pip install pyyaml  # If needed
+  ```
+
+**Q: Watchdog fails with "not inside a git repository"**
+- A: Make sure you've run the scaffold from a location with git installed and initialized. Re-run scaffold:
+  ```bash
+  npx @matt82198/aesop demo-fleet --yes
+  ```
+
+**Q: Dashboard won't open (port 8770 in use)**
+- A: The scaffold will use the next available port (8771, 8772, etc). Check `aesop.config.json` for the actual port.
+
+See [INSTALL.md](INSTALL.md) for more troubleshooting and [CONCEPTS.md](CONCEPTS.md) for deeper understanding.
+
+---
+
+## Next Steps
+
+1. **Run the full test suite** — Verify everything works:
+   ```bash
+   npm run test:all
+   ```
+
+2. **Read [FIRST-WAVE.md](FIRST-WAVE.md)** — Deep dive into the wave cycle
+
+3. **Explore [CONCEPTS.md](CONCEPTS.md)** — Understand the dispatch model and state architecture
+
+4. **Add your real repos** — Scale from demo to production
+
+5. **Set up continuous integration** — Schedule waves to run automatically
+
+Enjoy! 🚀

package/docs/INSTALL.md

@@ -33,7 +33,7 @@ The fastest way to get started is to use the Aesop template scaffolder. It creat
 ### Step 1: Scaffold the harness
 
 ```bash
-npx @matt82198/aesop@beta my-fleet \
+npx @matt82198/aesop my-fleet \
   --name "my-api" \
   --repos "/path/to/repo1,/path/to/repo2"
 ```
@@ -196,6 +196,75 @@ export DEBUG=1
 
 ---
 
+## Using Non-Claude Backends
+
+By default, Aesop uses Claude Code (the orchestration harness) as its backend. You can configure it to use other models via the **AgentDriver abstraction**—enabling Ollama, OpenAI-compatible endpoints, OpenRouter, and more.
+
+### Configure a backend in aesop.config.json
+
+Add or modify the `backend` section:
+
+```json
+{
+  "backend": "openai-compatible",
+  "model": "ollama-mistral",
+  "base_url": "http://localhost:11434/v1",
+  "api_key_env": "OLLAMA_API_KEY"
+}
+```
+
+Supported backends:
+- `"claude"` (default) — Claude Code CLI harness
+- `"openai-compatible"` — OpenAI Chat Completions API (Ollama, OpenRouter, etc.)
+- `"codex"` — CodeX OpenAI backend (legacy)
+
+### Example: Local Ollama
+
+To run Aesop against Mistral locally via Ollama:
+
+```bash
+# 1. Install Ollama (https://ollama.ai) and start the daemon
+ollama serve
+
+# 2. In another terminal, pull a model
+ollama pull mistral
+
+# 3. Configure Aesop to use it
+cat > aesop.config.json <<EOF
+{
+  "backend": "openai-compatible",
+  "model": "mistral",
+  "base_url": "http://localhost:11434/v1",
+  "api_key_env": "OLLAMA_API_KEY"
+}
+EOF
+
+# 4. Start Aesop (it will use Mistral for subagent dispatch)
+npx @matt82198/aesop my-fleet --name "my-api"
+```
+
+### Verification tiers: weaker backends get more checking
+
+The AgentDriver framework applies **honest verification tiers** — weaker backends (lower accuracy, no structured output) trigger stronger verification in the orchestrator:
+
+| Backend | Accuracy | Verification Tier | What it means |
+|---------|----------|-------------------|---------------|
+| Claude Code | ~0.99 | 1 (minimal) | Orchestrator trusts output; spot-check tests |
+| OpenAI (GPT-4) | ~0.95 | 2 | Validate all JSON, run full test suite |
+| Ollama (Mistral) | ~0.70 | 4 (maximum) | Validate all JSON, adversarial review, expensive repair cap |
+
+Lower tiers cost less but require more orchestrator work. See [driver/README.md](../driver/README.md) for full verification-policy details.
+
+### Troubleshooting
+
+**Backend won't connect**: Check `OLLAMA_API_KEY` (or your backend's API key env var) is set and the `base_url` is reachable.
+
+**Verification tier too strict**: If your backend is over-verified (tier 4 when it should be tier 2), update `probe_capabilities()` in the driver to report higher accuracy scores honestly.
+
+For more details, see [driver/README.md](../driver/README.md).
+
+---
+
 ## Pre-push Hook Installation
 
 The `npx` scaffold installs the pre-push hook automatically. If you cloned the repo manually, install it:

package/docs/QUICKSTART.md

@@ -0,0 +1,80 @@
+# Quickstart: 5 Minutes to Your First Wave
+
+Get from `npx @matt82198/aesop` to a working wave cycle: scaffold, verify, run the orchestrator skills, and watch it work.
+
+---
+
+## Step 1: Scaffold
+
+```bash
+cd ~/my-repo
+npx @matt82198/aesop .
+```
+
+Or if your repo is new:
+```bash
+npx @matt82198/aesop my-fleet && cd my-fleet
+```
+
+This installs daemons, skills, config, and a pre-push hook. Edit `aesop.config.json` to add repos.
+
+---
+
+## Step 2: Verify & Test
+
+```bash
+npx @matt82198/aesop doctor          # Preflight: Git, Node, Python, CLI, skills
+bash daemons/run-watchdog.sh --once  # Test the watchdog daemon
+```
+
+Expected: all green. See [INSTALL.md](INSTALL.md) if not.
+
+---
+
+## Step 3: Launch Dashboard (Optional)
+
+```bash
+npx @matt82198/aesop dash  # Opens http://localhost:8770
+```
+
+Monitor waves in real-time. View logs, agents, heartbeats, backlog.
+
+---
+
+## Step 4: Run Your First Wave (in Claude Code)
+
+### Priming
+```
+/power
+```
+Loads orchestrator brain, verifies system health, outputs next steps.
+
+### Orchestrating
+```
+/buildsystem
+```
+Runs one complete iteration: ranks backlog → dispatches Haiku agents → verifies merges → checkpoints state → audits fleet. Typically 30 min–2 hours.
+
+---
+
+## Key Concepts
+
+**Local + Claude Code**: Orchestrator runs in Claude Code; subagents are Haiku dispatched via `/buildsystem`. Daemons run locally (watchdog, dashboard).
+
+**State survives wipes**: `STATE.md` and `BUILDLOG.md` are committed to git. Resume anytime.
+
+**Cost**: ~$0.03–$0.05 per wave (1 Opus + 5–8 Haikus).
+
+**No modification of your repos**: Each agent works in a sibling worktree. Primary tree stays clean.
+
+---
+
+## Next Steps
+
+- [CONFIGURE.md](CONFIGURE.md) — Customize repos and ports
+- [CONCEPTS.md](CONCEPTS.md) — Dispatch model and architecture
+- [FIRST-WAVE.md](FIRST-WAVE.md) — Detailed expectations and monitoring
+- [ANY-REPO.md](ANY-REPO.md) — Adapt to any codebase (no stack lock-in)
+- [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — Concrete walkthrough
+
+**Troubleshooting**: [INSTALL.md#troubleshooting](INSTALL.md)

package/docs/README.md

@@ -1,6 +1,6 @@
 # Aesop Documentation
 
-Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, durable state, observable machinery, security gates.
+Aesop is an autonomous developer system that crawls into any repository and orchestrates intelligent work. It ranks tasks, dispatches parallel Haiku agents, verifies merges, audits the work, and feeds the next iteration. **State persists across multiple instances via a durable SQLite event log**, so your whole team uses one coordinated system.
 
 ---
 
@@ -12,7 +12,7 @@ If you're new to Aesop, follow this 4-stage path:
 **[INSTALL.md](INSTALL.md)** — Prerequisites, `npx` scaffold, what gets created
 
 - System requirements (Claude Code CLI, Git, Bash, Node.js, Python)
-- Quick-start: `npx @matt82198/aesop@beta my-fleet`
+- Quick-start: `npx @matt82198/aesop my-fleet`
 - Manual setup for development (git clone)
 - Pre-push hook installation
 
@@ -56,6 +56,33 @@ If you're new to Aesop, follow this 4-stage path:
 
 ---
 
+## Core Concepts: /power and /buildsystem
+
+### /power — System Initialization
+The `/power` skill initializes Aesop into your repository. It:
+- Loads your orchestrator brain (cardinal rules, domain map, team memory, system state)
+- Verifies the system is healthy (filesystem, git, API keys, watchdog)
+- Outputs a health brief and next-step recommendations
+
+Run `/power` at the start of each Claude Code session. It's idempotent—safe to run multiple times. See [skills/power/SKILL.md](../skills/power/SKILL.md) for details.
+
+### /buildsystem — One Complete Wave Cycle
+The `/buildsystem` skill runs **one complete iteration of the autonomous delivery loop**. It:
+1. **Ranks** the backlog (priority, dependencies, team affinity)
+2. **Dispatches** parallel Haiku agents on file-disjoint domains (tests, build, docs, UI, review, etc.)
+3. **Verifies** each merge (CI, security scans, audit spot-checks)
+4. **Checkpoints** (STATE.md + BUILDLOG.md committed to git, survive wipes)
+5. **Audits** fleet health and feeds next backlog (monitor signals, signal collectors, findings)
+
+This is the repeatable loop that runs your delivery cycle indefinitely, with each wave learning from the prior audit. You can run `/buildsystem` once per wave (typically 30 min–2 hours depending on backlog size). See [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) for a concrete walkthrough.
+
+### Team State & Multi-Instance Design
+**Current Status (0.1.0)**: Single-instance proven. A team uses Aesop by designating one operator who runs the wave loop. State is durably checkpointed in git (STATE.md, BUILDLOG.md, tracker.json exports).
+
+**In Design**: Multi-instance coordination via the state_store substrate. The event-sourced SQLite layer is production-ready but currently opt-in. A future release will enable multiple Aesop instances (e.g., per-team subgroups or geographic regions) to coordinate around a single source of truth—a Postgres-backed event log, with git as a diffable export. See [TEAM-STATE.md](TEAM-STATE.md) (design in progress) for the vision and current architecture decisions.
+
+---
+
 ## Deep-Dive Reference Docs
 
 Once you've completed the adopter journey, use these for operational reference:
@@ -108,12 +135,15 @@ Once you've completed the adopter journey, use these for operational reference:
 **I want to understand the cost model**
 → [DISPATCH-MODEL.md](DISPATCH-MODEL.md) or [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md#why-its-fast--cheap)
 
-**I want to know what's actually proven vs. claimed (the rc.1 milestone)**
+**I want to know what's actually proven vs. claimed (the 0.1.0 milestone)**
 → [autonomous-swe.md](autonomous-swe.md)
 
 **I need to understand how state survives a crash**
 → [CHECKPOINTING.md](CHECKPOINTING.md)
 
+**I want to understand multi-instance coordination**
+→ [TEAM-STATE.md](TEAM-STATE.md)
+
 **I'm reviewing a PR that changes orchestration behavior**
 → [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)