disinto/skill/SKILL.md

name	description	license	metadata
disinto	Operate the disinto autonomous code factory. Use when managing factory agents, filing issues on the forge, reading agent journals, querying CI pipelines, checking the dependency graph, or inspecting factory health.	AGPL-3.0	author version johba 0.1.0

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

Variable	Purpose
FORGE_TOKEN	Forgejo/Gitea API token with repo scope
FORGE_API	Base API URL, e.g. https://forge.example/api/v1/repos/owner/repo
PROJECT_REPO_ROOT	Absolute path to the checked-out disinto repository

Optional:

Variable	Purpose
WOODPECKER_SERVER	Woodpecker CI base URL (for pipeline queries)
WOODPECKER_TOKEN	Woodpecker API bearer token
WOODPECKER_REPO_ID	Numeric repo ID in Woodpecker

The nine agents

Agent	Role	Runs via
Dev	Picks backlog issues, implements in worktrees, opens PRs	dev/dev-poll.sh (cron)
Review	Reviews PRs against conventions, approves or requests changes	review/review-poll.sh (cron)
Gardener	Grooms backlog: dedup, quality gates, dust bundling, stale cleanup	gardener/gardener-run.sh (cron 0,6,12,18 UTC)
Planner	Tracks vision progress, maintains prerequisite tree, files constraint issues	planner/planner-run.sh (cron daily 07:00 UTC)
Predictor	Challenges claims, detects structural risks, files predictions	predictor/predictor-run.sh (cron daily 06:00 UTC)
Supervisor	Monitors health (RAM, disk, CI, agents), auto-fixes, escalates	supervisor/supervisor-run.sh (cron */20)
Action	Executes operational tasks dispatched by planner via formulas	action/action-poll.sh (cron)
Vault	Gates dangerous actions, manages resource procurement	vault/vault-poll.sh (cron)
Exec	Interactive executive assistant reachable via Matrix	exec/exec-session.sh

How agents interact

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 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 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 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

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 scripts/factory-status.sh --ci

Or query Woodpecker directly:

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:

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.