From 3f76b3495a77e99c596402e81263b525501f84f3 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 10 Apr 2026 08:26:24 +0000 Subject: [PATCH] =?UTF-8?q?fix:=20docs:=20architecture=20docs=20still=20de?= =?UTF-8?q?scribe=20cron=20scheduling=20=E2=80=94=20factory=20runs=20from?= =?UTF-8?q?=20while-true=20polling=20loop=20(#546)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 12 +++---- README.md | 69 ++++++++++++++++++++-------------------- disinto-factory/SKILL.md | 2 +- disinto-factory/setup.md | 6 ++-- 4 files changed, 45 insertions(+), 44 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7d028ea..816cdda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Disinto is an autonomous code factory. It manages ten agents (dev, review, gardener, supervisor, planner, predictor, architect, reproduce, triage, edge dispatcher) that pick up issues from forge, implement them, review PRs, plan -from the vision, and keep the system healthy — all via cron (bare-metal) or a polling loop (Docker) and `claude -p`. +from the vision, and keep the system healthy — all via a polling loop (`docker/agents/entrypoint.sh`) and `claude -p`. The dispatcher executes formula-based operational tasks. Each agent has a `.profile` repository on Forgejo that stores lessons learned @@ -23,12 +23,12 @@ See `README.md` for the full architecture and `disinto-factory/SKILL.md` for set disinto/ (code repo) ├── dev/ dev-poll.sh, dev-agent.sh, phase-test.sh — issue implementation ├── review/ review-poll.sh, review-pr.sh — PR review -├── gardener/ gardener-run.sh — direct cron executor for run-gardener formula +├── gardener/ gardener-run.sh — polling-loop executor for run-gardener formula │ best-practices.md — gardener best-practice reference │ pending-actions.json — queued gardener actions -├── predictor/ predictor-run.sh — daily cron executor for run-predictor formula -├── planner/ planner-run.sh — direct cron executor for run-planner formula -├── supervisor/ supervisor-run.sh — formula-driven health monitoring (cron wrapper) +├── predictor/ predictor-run.sh — polling-loop executor for run-predictor formula +├── planner/ planner-run.sh — polling-loop executor for run-planner formula +├── supervisor/ supervisor-run.sh — formula-driven health monitoring (polling-loop executor) │ preflight.sh — pre-flight data collection for supervisor formula ├── architect/ architect-run.sh — strategic decomposition of vision into sprints ├── vault/ vault-env.sh — shared env setup (vault redesign in progress, see #73-#77) @@ -173,7 +173,7 @@ Humans write these. Agents read and enforce them. | ID | Decision | Rationale | |---|---|---| -| AD-001 | Nervous system runs from cron (bare-metal) or a polling loop (Docker), not PR-based actions. | Planner, predictor, gardener, supervisor run directly via `*-run.sh`. They create work, they don't become work. (See PR #474 revert.) | +| AD-001 | Nervous system runs from a polling loop (`docker/agents/entrypoint.sh`), not PR-based actions. | Planner, predictor, gardener, supervisor run directly via `*-run.sh`. They create work, they don't become work. (See PR #474 revert.) | | AD-002 | Single-threaded pipeline per project. | One dev issue at a time. No new work while a PR awaits CI or review. Prevents merge conflicts and keeps context clear. | | AD-003 | The runtime creates and destroys, the formula preserves. | Runtime manages worktrees/sessions/temp. Formulas commit knowledge to git before signaling done. | | AD-004 | Event-driven > polling > fixed delays. | Never `waitForTimeout` or hardcoded sleep. Use phase files, webhooks, or poll loops with backoff. | diff --git a/README.md b/README.md index 40c9889..836d74c 100644 --- a/README.md +++ b/README.md @@ -21,22 +21,29 @@ Point it at a git repo with a Woodpecker CI pipeline and it will pick up issues, ## Architecture ``` -cron (*/10) ──→ supervisor-poll.sh ← supervisor (bash checks, zero tokens) - ├── all clear? → exit 0 - └── problem? → claude -p (diagnose, fix, or escalate) - -cron (*/10) ──→ dev-poll.sh ← pulls ready issues, spawns dev-agent - └── dev-agent.sh ← claude -p: implement → PR → CI → review → merge - -cron (*/10) ──→ review-poll.sh ← finds unreviewed PRs, spawns review - └── review-pr.sh ← claude -p: review → approve/request changes - -cron (daily) ──→ gardener-poll.sh ← backlog grooming (duplicates, stale, tech-debt) - └── claude -p: triage → promote/close/escalate - -cron (weekly) ──→ planner-poll.sh ← gap-analyse VISION.md, create backlog issues - └── claude -p: update AGENTS.md → create issues +entrypoint.sh (while-true polling loop, 5 min base interval) + │ + ├── every 5 min ──→ review-poll.sh ← finds unreviewed PRs, spawns review + │ └── review-pr.sh ← claude -p: review → approve/request changes + │ + ├── every 5 min ──→ dev-poll.sh ← pulls ready issues, spawns dev-agent + │ └── dev-agent.sh ← claude -p: implement → PR → CI → review → merge + │ + ├── every 6h ────→ gardener-run.sh ← backlog grooming (duplicates, stale, tech-debt) + │ └── claude -p: triage → promote/close/escalate + │ + ├── every 6h ────→ architect-run.sh ← strategic decomposition of vision into sprints + │ + ├── every 12h ───→ planner-run.sh ← gap-analyse VISION.md, create backlog issues + │ └── claude -p: update AGENTS.md → create issues + │ + └── every 24h ───→ predictor-run.sh ← infrastructure pattern detection +entrypoint-edge.sh (edge container) + ├── dispatcher.sh ← polls ops repo for vault actions + └── every 20 min → supervisor-run.sh ← health checks (bash checks, zero tokens) + ├── all clear? → exit 0 + └── problem? → claude -p (diagnose, fix, or escalate) ``` ## Prerequisites @@ -86,17 +93,11 @@ CLAUDE_TIMEOUT=7200 # max seconds per Claude invocation (default: 2h) ``` ```bash -# 3. Install cron (staggered to avoid overlap) -crontab -e -# Add: -# 0,10,20,30,40,50 * * * * /path/to/disinto/supervisor/supervisor-poll.sh -# 3,13,23,33,43,53 * * * * /path/to/disinto/review/review-poll.sh -# 6,16,26,36,46,56 * * * * /path/to/disinto/dev/dev-poll.sh -# 15 8 * * * /path/to/disinto/gardener/gardener-poll.sh -# 0 9 * * 1 /path/to/disinto/planner/planner-poll.sh +# 3. Start the agent and edge containers +docker compose up -d -# 4. Verify -bash supervisor/supervisor-poll.sh # should log "all clear" +# 4. Verify the entrypoint loop is running +docker exec disinto-agents-1 tail -f /home/agent/data/agent-entrypoint.log ``` ## Directory Structure @@ -109,16 +110,16 @@ disinto/ │ ├── env.sh # Shared: load .env, PATH, API helpers │ └── ci-debug.sh # Woodpecker CI log/failure helper ├── dev/ -│ ├── dev-poll.sh # Cron entry: find ready issues +│ ├── dev-poll.sh # Poll: find ready issues │ └── dev-agent.sh # Implementation agent (claude -p) ├── review/ -│ ├── review-poll.sh # Cron entry: find unreviewed PRs +│ ├── review-poll.sh # Poll: find unreviewed PRs │ └── review-pr.sh # Review agent (claude -p) ├── gardener/ -│ ├── gardener-poll.sh # Cron entry: backlog grooming +│ ├── gardener-run.sh # Executor: backlog grooming │ └── best-practices.md # Gardener knowledge base ├── planner/ -│ ├── planner-poll.sh # Cron entry: weekly vision gap analysis +│ ├── planner-run.sh # Executor: vision gap analysis │ └── (formula-driven) # run-planner.toml executed by dispatcher ├── vault/ │ └── vault-env.sh # Shared env setup (vault redesign in progress, see #73-#77) @@ -141,11 +142,11 @@ disinto/ | Agent | Trigger | Job | |-------|---------|-----| -| **Supervisor** | Every 10 min | Health checks (RAM, disk, CI, git). Calls Claude only when something is broken. Self-improving via `best-practices/`. | -| **Dev** | Every 10 min | Picks up `backlog`-labeled issues, creates a branch, implements, opens a PR, monitors CI, responds to review, merges. | -| **Review** | Every 10 min | Finds PRs without review, runs Claude-powered code review, approves or requests changes. | -| **Gardener** | Daily | Grooms the issue backlog: detects duplicates, promotes `tech-debt` to `backlog`, closes stale issues, escalates ambiguous items. | -| **Planner** | Weekly | Updates AGENTS.md documentation to reflect recent code changes, then gap-analyses VISION.md vs current state and creates up to 5 backlog issues for the highest-leverage gaps. | +| **Supervisor** | Every 20 min | Health checks (RAM, disk, CI, git). Calls Claude only when something is broken. Self-improving via `best-practices/`. | +| **Dev** | Every 5 min | Picks up `backlog`-labeled issues, creates a branch, implements, opens a PR, monitors CI, responds to review, merges. | +| **Review** | Every 5 min | Finds PRs without review, runs Claude-powered code review, approves or requests changes. | +| **Gardener** | Every 6h | Grooms the issue backlog: detects duplicates, promotes `tech-debt` to `backlog`, closes stale issues, escalates ambiguous items. | +| **Planner** | Every 12h | Updates AGENTS.md documentation to reflect recent code changes, then gap-analyses VISION.md vs current state and creates up to 5 backlog issues for the highest-leverage gaps. | > **Vault:** Being redesigned as a PR-based approval workflow (issues #73-#77). > See [docs/VAULT.md](docs/VAULT.md) for the vault PR workflow and branch protection details. diff --git a/disinto-factory/SKILL.md b/disinto-factory/SKILL.md index 6a74a18..5892fe3 100644 --- a/disinto-factory/SKILL.md +++ b/disinto-factory/SKILL.md @@ -20,7 +20,7 @@ You are helping the user set up and operate a **disinto autonomous code factory* - The factory uses a single internal Forgejo as its forge, regardless of where mirrors go - Dev-agent uses `claude -p` for one-shot implementation sessions - Mirror pushes happen automatically after every merge -- Cron schedule: dev-poll every 5min, review-poll every 5min, gardener 4x/day +- Polling loop in `docker/agents/entrypoint.sh`: dev-poll/review-poll every 5m, gardener/architect every 6h, planner every 12h, predictor every 24h ## References diff --git a/disinto-factory/setup.md b/disinto-factory/setup.md index dc8ad02..8e6e628 100644 --- a/disinto-factory/setup.md +++ b/disinto-factory/setup.md @@ -57,8 +57,8 @@ docker ps --format "table {{.Names}}\t{{.Status}}" # Token generated? grep WOODPECKER_TOKEN .env | grep -v "^$" && echo "OK" || echo "MISSING — see references/troubleshooting.md" -# Agent cron active? -docker exec -u agent disinto-agents-1 crontab -l -u agent +# Agent entrypoint loop running? +docker exec disinto-agents-1 tail -5 /home/agent/data/agent-entrypoint.log # Agent can reach Forgejo? docker exec disinto-agents-1 bash -c "source /home/agent/disinto/.env && curl -sf http://forgejo:3000/api/v1/version | jq .version" @@ -174,7 +174,7 @@ Use labels: ### 7. Watch it work -The dev-agent polls every 5 minutes. Trigger manually to see it immediately: +The dev-agent runs every 5 minutes via the entrypoint polling loop. Trigger manually to see it immediately: ```bash source .env export PROJECT_TOML=projects/.toml