Disinto Factory Skill#

Disinto is an autonomous code factory with nine agents that implement issues, review PRs, plan from a vision, predict risks, groom the backlog, gate actions, and assist the founder — all driven by cron and Claude.

Required environment#

VariablePurposeFORGE_TOKENForgejo/Gitea API token with repo scopeFORGE_APIBase API URL, e.g. https://forge.example/api/v1/repos/owner/repo``PROJECT_REPO_ROOTAbsolute path to the checked-out disinto repository

Optional:

VariablePurposeWOODPECKER_SERVERWoodpecker CI base URL (for pipeline queries)WOODPECKER_TOKENWoodpecker API bearer tokenWOODPECKER_REPO_IDNumeric repo ID in Woodpecker

The nine agents#

AgentRoleRuns viaDevPicks backlog issues, implements in worktrees, opens PRsdev/dev-poll.sh (cron)ReviewReviews PRs against conventions, approves or requests changesreview/review-poll.sh (cron)GardenerGrooms backlog: dedup, quality gates, dust bundling, stale cleanupgardener/gardener-run.sh (cron 0,6,12,18 UTC)PlannerTracks vision progress, maintains prerequisite tree, files constraint issuesplanner/planner-run.sh (cron daily 07:00 UTC)PredictorChallenges claims, detects structural risks, files predictionspredictor/predictor-run.sh (cron daily 06:00 UTC)SupervisorMonitors health (RAM, disk, CI, agents), auto-fixes, escalatessupervisor/supervisor-run.sh (cron */20)ActionExecutes operational tasks dispatched by planner via formulasaction/action-poll.sh (cron)VaultGates dangerous actions, manages resource procurementvault/vault-poll.sh (cron)ExecInteractive executive assistant reachable via Matrixexec/exec-session.sh

How agents interact#

text

Planner ──creates-issues──▶ Backlog ◀──grooms── Gardener
   │                           │
   │                           ▼
   │                     Dev (implements)
   │                           │
   │                           ▼
   │                     Review (approves/rejects)
   │                           │
   │                           ▼
   ▼                        Merged
Predictor ──challenges──▶ Planner (triages predictions)
Supervisor ──monitors──▶ All agents (health, escalation)
Vault ──gates──▶ Action, Dev (dangerous operations)
Exec ──delegates──▶ Issues (never writes code directly)

Issue lifecycle#

backlog → in-progress → PR → CI → review → merge → closed.

Key labels: backlog, priority, in-progress, blocked, underspecified, tech-debt, vision, action, prediction/unreviewed.

Issues declare dependencies in a ## Dependencies section listing #N references. Dev-poll only picks issues whose dependencies are all closed.

Available scripts#

• scripts/factory-status.sh — Show agent status, open issues, and CI pipeline state. Pass --agents, --issues, or --ci for specific sections.
• scripts/file-issue.sh — Create an issue on the forge with proper labels and formatting. Pass --title, --body, and optionally --labels.
• scripts/read-journal.sh — Read agent journal entries. Pass agent name ( planner, supervisor, exec) and optional --date YYYY-MM-DD.

Common workflows#

1. Check factory health#

bash

bash scripts/factory-status.sh

This shows: which agents are active, recent open issues, and CI pipeline status. Use --agents for just the agent status section.

2. Read what the planner decided today#

bash

bash scripts/read-journal.sh planner

Returns today's planner journal: predictions triaged, prerequisite tree updates, top constraints, issues created, and observations.

3. File a new issue#

bash

bash scripts/file-issue.sh --title "fix: broken auth flow" \
  --body "$(cat scripts/../templates/issue-template.md)" \
  --labels backlog

Or generate the body inline — the template shows the expected format with acceptance criteria and affected files sections.

4. Check the dependency graph#

bash

python3 "${PROJECT_REPO_ROOT}/lib/build-graph.py" \
  --project-root "${PROJECT_REPO_ROOT}" \
  --output /tmp/graph-report.json
cat /tmp/graph-report.json | jq '.analyses'

The graph builder parses VISION.md, the prerequisite tree, formulas, and open issues. It detects: orphan issues (not referenced), dependency cycles, disconnected clusters, bottleneck nodes, and thin objectives.

5. Query a specific CI pipeline#

bash

bash scripts/factory-status.sh --ci

Or query Woodpecker directly:

bash

curl -s -H "Authorization: Bearer ${WOODPECKER_TOKEN}" \
  "${WOODPECKER_SERVER}/api/repos/${WOODPECKER_REPO_ID}/pipelines?per_page=5" \
  | jq '.[] | {number, status, commit: .commit[:8], branch}'

6. Read and interpret VISION.md progress#

Read VISION.md at the repo root for the full vision. Then cross-reference with the prerequisite tree:

bash

cat "${PROJECT_REPO_ROOT}/planner/prerequisite-tree.md"

The prerequisite tree maps vision objectives to concrete issues. Items marked [x] are complete; items marked [ ] show what blocks progress. The planner updates this daily.

Gotchas#

• Single-threaded pipeline: only one issue is in-progress per project at a time. Don't file issues expecting parallel work.
• Secrets via env vars only: never embed secrets in issue bodies, PR descriptions, or comments. Use $VAR_NAME references.
• Formulas are not skills: formulas in formulas/ are TOML issue templates for multi-step agent tasks. Skills teach assistants; formulas drive agents.
• Predictor journals: the predictor does not write journal files. Its memory lives in prediction/unreviewed and prediction/actioned issues.
• State files: agent activity is tracked via state/.{agent}-active files. These are presence files, not logs.
• ShellCheck required: all .sh files must pass ShellCheck. CI enforces this.