diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md new file mode 100644 index 0000000..4277812 --- /dev/null +++ b/BOOTSTRAP.md @@ -0,0 +1,212 @@ +# Bootstrapping a New Project + +How to point dark-factory at a new target project and get all four agents running. + +## Prerequisites + +Before starting, ensure you have: + +- [ ] A **Codeberg repo** with at least one issue labeled `backlog` +- [ ] A **Woodpecker CI** pipeline (`.woodpecker/` dir with at least one `.yml`) +- [ ] A **second Codeberg account** for the review bot (branch protection requires reviews from a different user) +- [ ] A **local clone** of the target repo on the same machine as dark-factory +- [ ] `claude` CLI installed and authenticated (`claude --version`) + +## 1. Configure `.env` + +```bash +cp .env.example .env +``` + +Fill in: + +```bash +# ── Target project ────────────────────────────────────────── +CODEBERG_REPO=org/project # Codeberg slug +PROJECT_REPO_ROOT=/home/you/project # absolute path to local clone +PRIMARY_BRANCH=main # main or master + +# ── Auth ──────────────────────────────────────────────────── +# CODEBERG_TOKEN= # or use ~/.netrc (machine codeberg.org) +REVIEW_BOT_TOKEN=tok_xxxxxxxx # the second account's API token + +# ── Woodpecker CI ─────────────────────────────────────────── +WOODPECKER_TOKEN=tok_xxxxxxxx +WOODPECKER_SERVER=http://localhost:8000 +WOODPECKER_REPO_ID=2 # numeric — find via Woodpecker UI or API + +# Woodpecker Postgres (for direct pipeline queries) +WOODPECKER_DB_PASSWORD=secret +WOODPECKER_DB_USER=woodpecker +WOODPECKER_DB_HOST=127.0.0.1 +WOODPECKER_DB_NAME=woodpecker + +# ── Optional: Matrix notifications ────────────────────────── +# MATRIX_HOMESERVER=http://localhost:8008 +# MATRIX_BOT_USER=@factory:your.server +# MATRIX_TOKEN= +# MATRIX_ROOM_ID= + +# ── Tuning ────────────────────────────────────────────────── +CLAUDE_TIMEOUT=7200 # seconds per Claude invocation +``` + +## 2. Prepare the Target Repo + +### Required: CI pipeline + +The repo needs at least one Woodpecker pipeline. Dark-factory monitors CI status to decide when a PR is ready for review and when it can merge. + +### Required: `CLAUDE.md` + +Create a `CLAUDE.md` in the repo root. This is the context document that dev-agent and review-agent read before working. It should cover: + +- **What the project is** (one paragraph) +- **Tech stack** (languages, frameworks, DB) +- **How to build/run/test** (`npm install`, `npm test`, etc.) +- **Coding conventions** (import style, naming, linting rules) +- **Project structure** (key directories and what lives where) + +The dev-agent reads this file via `claude -p` before implementing any issue. The better this file, the better the output. + +### Required: Issue labels + +Create two labels on the Codeberg repo: + +| Label | Purpose | +|-------|---------| +| `backlog` | Issues ready to be picked up by dev-agent | +| `in-progress` | Managed by dev-agent (auto-applied, auto-removed) | + +Optional but recommended: + +| Label | Purpose | +|-------|---------| +| `tech-debt` | Gardener can promote these to `backlog` | +| `blocked` | Dev-agent marks issues with unmet dependencies | + +### Required: Branch protection + +On Codeberg, set up branch protection for your primary branch: + +- **Require pull request reviews**: enabled +- **Required approvals**: 1 (from the review bot account) +- **Restrict push**: only allow merges via PR + +This ensures dev-agent can't merge its own PRs — it must wait for review-agent (running as the bot account) to approve. + +### Optional: `STATE.md` + +Dev-agent creates this file automatically on first merge. It tracks what was delivered and when: + +```markdown +# STATE.md — What currently is and does + +- [2026-03-14] lint: upgrade frontend ESLint (#4) +- [2026-03-15] fix: form validation on submit (#7) +``` + +No action needed — just don't be surprised when it appears. + +## 3. Write Good Issues + +Dev-agent works best with issues that have: + +- **Clear title** describing the change (e.g., "Add email validation to customer form") +- **Acceptance criteria** — what "done" looks like +- **Dependencies** — reference blocking issues with `#NNN` in the body or a `## Dependencies` section: + ``` + ## Dependencies + - #4 + - #7 + ``` + +Dev-agent checks that all referenced issues are closed (= merged) before starting work. If any are open, the issue is skipped and checked again next cycle. + +## 4. Install Cron + +```bash +crontab -e +``` + +Add (adjust paths): + +```cron +FACTORY_ROOT=/home/you/dark-factory + +# Supervisor — health checks, auto-healing (every 10 min) +0,10,20,30,40,50 * * * * $FACTORY_ROOT/factory/factory-poll.sh + +# Review agent — find unreviewed PRs (every 10 min, offset +3) +3,13,23,33,43,53 * * * * $FACTORY_ROOT/review/review-poll.sh + +# Dev agent — find ready issues, implement (every 10 min, offset +6) +6,16,26,36,46,56 * * * * $FACTORY_ROOT/dev/dev-poll.sh + +# Gardener — backlog grooming (daily) +15 8 * * * $FACTORY_ROOT/gardener/gardener-poll.sh +``` + +The 3-minute offsets prevent agents from competing for resources. + +## 5. Verify + +```bash +# Should complete with "all clear" (no problems to fix) +bash factory/factory-poll.sh + +# Should list backlog issues (or "no backlog issues") +bash dev/dev-poll.sh + +# Should find no unreviewed PRs (or review one if exists) +bash review/review-poll.sh +``` + +Check logs after a few cycles: + +```bash +tail -30 factory/factory.log +tail -30 dev/dev-agent.log +tail -30 review/review.log +``` + +## 6. Optional: Matrix Notifications + +If you want real-time notifications and human-in-the-loop escalation: + +1. Set `MATRIX_*` vars in `.env` +2. Install the listener as a systemd service: + ```bash + sudo cp lib/matrix_listener.service /etc/systemd/system/ + sudo systemctl enable --now matrix_listener + ``` +3. The factory and gardener will post status updates and escalation threads to the configured room. Reply in-thread to answer escalations. + +## Lifecycle + +Once running, the system operates autonomously: + +``` +You write issues (with backlog label) + → dev-poll finds ready issues + → dev-agent implements in a worktree, opens PR + → CI runs (Woodpecker) + → review-agent reviews, approves or requests changes + → dev-agent addresses feedback (if any) + → merge, close issue, clean up + +Meanwhile: + factory-poll monitors health, kills stale processes, manages resources + gardener grooms backlog: closes duplicates, promotes tech-debt, escalates ambiguity +``` + +## Troubleshooting + +| Symptom | Check | +|---------|-------| +| Dev-agent not picking up issues | `cat /tmp/dev-agent.lock` — is another instance running? Issues labeled `backlog`? Dependencies met? | +| PR not getting reviewed | `tail review/review.log` — CI must pass first. Review bot token valid? | +| CI stuck | `bash lib/ci-debug.sh` — check Woodpecker. Rate-limited? (exit 128 = wait 15 min) | +| Claude not found | `which claude` — must be in PATH. Check `lib/env.sh` adds `~/.local/bin`. | +| Merge fails | Branch protection misconfigured? Review bot needs write access to the repo. | +| Memory issues | Factory auto-heals at <500 MB free. Check `factory/factory.log` for P0 alerts. |