a66bd91721
- Add setup_forge() to bin/disinto: provisions Forgejo via Docker, creates admin + bot users (dev-bot, review-bot), generates API tokens, creates repo, and pushes code — all automated - Rename env vars: CODEBERG_TOKEN→FORGE_TOKEN, REVIEW_BOT_TOKEN→ FORGE_REVIEW_TOKEN, CODEBERG_REPO→FORGE_REPO, CODEBERG_API→ FORGE_API, CODEBERG_WEB→FORGE_WEB, CODEBERG_BOT_USERNAMES→ FORGE_BOT_USERNAMES (with backwards-compat fallbacks) - Rename API helpers: codeberg_api()→forge_api(), codeberg_api_all() →forge_api_all() (with compat aliases) - Add forge_url field to project TOML; load-project.sh derives FORGE_API/FORGE_WEB from forge_url + repo - Update parse_repo_slug() to accept any host URL, not just codeberg - Forgejo data stored under ~/.disinto/forgejo/ (not in factory repo) - Update all 58 files: agent scripts, formulas, docs, site HTML Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
<!-- last-reviewed: eb7e24cb1df028c6061f47ddfdf9b4ebec33e1cf -->
|
|
# Planner Agent
|
|
|
|
**Role**: Strategic planning using a Prerequisite Tree (Theory of Constraints),
|
|
executed directly from cron via tmux + Claude.
|
|
Phase 0 (preflight): pull latest code, load persistent memory and prerequisite
|
|
tree from `planner/MEMORY.md` and `planner/prerequisite-tree.md`. Also reads
|
|
all available formulas: factory formulas (`$FACTORY_ROOT/formulas/*.toml`) and
|
|
project-specific formulas (`$PROJECT_REPO_ROOT/formulas/*.toml`). Phase 1
|
|
(prediction-triage): triage `prediction/unreviewed` issues filed by the
|
|
Predictor — for each prediction: promote to action, promote to backlog, watch
|
|
(relabel to prediction/backlog), or dismiss with reasoning. Phase 2
|
|
(update-prerequisite-tree): scan repo state + open/closed issues, mark resolved
|
|
prerequisites, discover new ones, update the tree. **Also scans comments on
|
|
referenced issues for bounce/stuck signals** (BOUNCED, ESCALATED, LABEL_CHURN)
|
|
to detect issues ping-ponging between backlog and underspecified. Phase 3
|
|
(file-at-constraints): identify the top 3 unresolved prerequisites that block
|
|
the most downstream objectives — file issues as either `backlog` (code changes,
|
|
dev-agent) or `action` (run existing formula, action-agent). **Stuck issues
|
|
(detected BOUNCED/LABEL_CHURN) are dispatched to the `groom-backlog` formula
|
|
in breakdown mode instead of being re-promoted** — this breaks the ping-pong
|
|
loop by splitting them into dev-agent-sized sub-issues.
|
|
Phase 4 (journal-and-memory): write updated prerequisite tree + daily journal
|
|
entry (committed to git) and update `planner/MEMORY.md` (committed to git).
|
|
Phase 5 (commit-and-pr): one commit with all file changes, push, create PR.
|
|
AGENTS.md maintenance is handled by the Gardener.
|
|
|
|
**Artifacts use `$PROJECT_REPO_ROOT`**: All planner artifacts (journal,
|
|
prerequisite tree, memory, vault state) live under `$PROJECT_REPO_ROOT/planner/`
|
|
and `$PROJECT_REPO_ROOT/vault/`, not `$FACTORY_ROOT`. Each project manages its
|
|
own planner state independently.
|
|
|
|
**Trigger**: `planner-run.sh` runs daily via cron (accepts an optional project
|
|
TOML argument, defaults to `projects/disinto.toml`). It creates a tmux session
|
|
with `claude --model opus`, injects `formulas/run-planner.toml` as context,
|
|
monitors the phase file, and cleans up on completion or timeout. No action
|
|
issues — the planner is a nervous system component, not work.
|
|
|
|
**Key files**:
|
|
- `planner/planner-run.sh` — Cron wrapper + orchestrator: lock, memory guard,
|
|
sources disinto project config, creates tmux session, injects formula prompt,
|
|
monitors phase file, handles crash recovery, cleans up
|
|
- `formulas/run-planner.toml` — Execution spec: six steps (preflight,
|
|
prediction-triage, update-prerequisite-tree, file-at-constraints,
|
|
journal-and-memory, commit-and-pr) with `needs` dependencies. Claude
|
|
executes all steps in a single interactive session with tool access
|
|
- `formulas/groom-backlog.toml` — Dual-mode formula: grooming (default) or
|
|
breakdown (dispatched by planner for bounced/stuck issues — splits the issue
|
|
into dev-agent-sized sub-issues, removes `underspecified` label)
|
|
- `planner/prerequisite-tree.md` — Prerequisite tree: versioned constraint
|
|
map linking VISION.md objectives to their prerequisites. Planner owns the
|
|
tree, humans steer by editing VISION.md. Tree grows organically as the
|
|
planner discovers new prerequisites during runs
|
|
- `planner/MEMORY.md` — Persistent memory across runs (committed to git)
|
|
- `planner/journal/*.md` — Daily raw logs from each planner run (committed to git)
|
|
|
|
**Constraint focus**: The planner uses Theory of Constraints to avoid premature
|
|
issue filing. Only the top 3 unresolved prerequisites that block the most
|
|
downstream objectives get filed as issues. Everything else exists in the
|
|
prerequisite tree but NOT as issues. This prevents the "spray issues across
|
|
all milestones" pattern that produced premature work in planner v1/v2.
|
|
|
|
**Environment variables consumed**:
|
|
- `FORGE_TOKEN`, `FORGE_REPO`, `FORGE_API`, `PROJECT_NAME`, `PROJECT_REPO_ROOT`
|
|
- `PRIMARY_BRANCH`, `CLAUDE_MODEL` (set to opus by planner-run.sh)
|
|
- `MATRIX_TOKEN`, `MATRIX_ROOM_ID`, `MATRIX_HOMESERVER`
|