disinto/skill/SKILL.md

name	description	license	metadata	env_vars	tools
disinto	Operate the disinto autonomous code factory. Use when bootstrapping a new project with `disinto init`, 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.2.0	required optional FORGE_TOKEN FORGE_API PROJECT_REPO_ROOT WOODPECKER_SERVER WOODPECKER_TOKEN WOODPECKER_REPO_ID	bash curl jq git

Disinto Factory Skill

You are the human's assistant for operating the disinto autonomous code factory. You ask the questions, explain the choices, and run the commands on the human's behalf. The human makes decisions; you execute.

Disinto manages eight agents that implement issues, review PRs, plan from a vision, predict risks, groom the backlog, gate actions, and keep the system healthy — all driven by cron and Claude.

System requirements

Before bootstrapping, verify the target machine meets these minimums:

Requirement	Detail
VPS	8 GB+ RAM (4 GB swap recommended)
Docker + Docker Compose	Required for the default containerized stack
Claude Code CLI	Authenticated with API access (claude --version)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1	Set in the factory environment — prevents auto-update pings in production
Disk	Sufficient for CI images, git mirrors, and agent worktrees (40 GB+ recommended)
tmux	Required for persistent dev sessions
git, jq, python3, curl	Used by agents and helper scripts

Optional but recommended:

Tool	Purpose
sops + age	Encrypt secrets at rest (.env.enc)

Bootstrapping with disinto init

The primary setup path. Walk the human through each step.

Step 1 — Check prerequisites

Confirm Docker, Claude Code CLI, and required tools are installed:

docker --version && docker compose version
claude --version
tmux -V && git --version && jq --version && python3 --version

Step 2 — Run disinto init

disinto init <repo-url>

Accepts GitHub, Codeberg, or any git URL. Common variations:

disinto init https://github.com/org/repo              # default (docker compose)
disinto init org/repo --forge-url http://forge:3000    # custom forge URL
disinto init org/repo --bare                           # bare-metal, no compose
disinto init org/repo --yes                            # skip confirmation prompts

What disinto init does

1. Generates docker-compose.yml with four services: Forgejo, Woodpecker server, Woodpecker agent, and the agents container.
2. Starts a local Forgejo instance via Docker (at http://localhost:3000).
3. Creates admin + bot users (dev-bot, review-bot) with API tokens.
4. Creates the repo on Forgejo and pushes the code.
5. Sets up Woodpecker CI — OAuth2 app on Forgejo, activates the repo.
6. Generates projects/<name>.toml — per-project config with paths, CI IDs, and forge URL.
7. Creates standard labels (backlog, in-progress, blocked, etc.).
8. Configures git mirror remotes if [mirrors] is set in the TOML.
9. Encrypts secrets to .env.enc if sops + age are available.
10. Brings up the full docker compose stack.

Step 3 — Set environment variable

Ensure CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 is set in the factory environment (.env or the agents container). This prevents Claude Code from making auto-update and telemetry requests in production.

Step 4 — Verify

disinto status

Docker stack architecture

The default deployment is a docker-compose stack with four services:

┌──────────────────────────────────────────────────┐
│                  disinto-net                      │
│                                                  │
│  ┌──────────┐  ┌─────────────┐  ┌────────────┐  │
│  │ Forgejo  │  │ Woodpecker  │  │ Woodpecker │  │
│  │ (forge)  │◀─│  (CI server)│◀─│  (agent)   │  │
│  │ :3000    │  │  :8000      │  │            │  │
│  └──────────┘  └─────────────┘  └────────────┘  │
│        ▲                                         │
│        │                                         │
│  ┌─────┴──────────────────────────────────────┐  │
│  │              agents                        │  │
│  │  (cron → dev, review, gardener, planner,   │  │
│  │   predictor, supervisor, action, vault)    │  │
│  │  Claude CLI mounted from host              │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Service	Image	Purpose
forgejo	codeberg.org/forgejo/forgejo:11.0	Git forge, issue tracker, PR reviews
woodpecker	woodpeckerci/woodpecker-server:v3	CI server, triggers on push
woodpecker-agent	woodpeckerci/woodpecker-agent:v3	Runs CI pipelines in Docker
agents	./docker/agents (custom)	All eight factory agents, driven by cron

The agents container mounts the Claude CLI binary and ~/.claude credentials from the host. Secrets are loaded from .env (or decrypted from .env.enc).

Git mirror

The factory assumes a local git mirror on the Forgejo instance to avoid rate limits from upstream forges (GitHub, Codeberg). When disinto init runs:

1. The repo is cloned from the upstream URL.
2. A forgejo remote is added pointing to the local Forgejo instance.
3. All branches and tags are pushed to Forgejo.
4. If [mirrors] is configured in the project TOML, additional remotes (e.g. GitHub, Codeberg) are set up and synced via lib/mirrors.sh.

All agent work happens against the local Forgejo forge. This means:

• No GitHub/Codeberg API rate limits on polling.
• CI triggers are local (Woodpecker watches Forgejo webhooks).
• Mirror pushes are fire-and-forget background operations after merge.

To configure mirrors in the project TOML:

[mirrors]
github   = "git@github.com:user/repo.git"
codeberg = "git@codeberg.org:user/repo.git"

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

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)

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) and optional --date YYYY-MM-DD.

Common workflows

1. Bootstrap a new project

Walk the human through disinto init:

# 1. Verify prerequisites
docker --version && claude --version

# 2. Bootstrap
disinto init https://github.com/org/repo

# 3. Verify
disinto status

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

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

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

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

6. 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}'

7. Manage the docker stack

disinto up        # start all services
disinto down      # stop all services
disinto logs      # tail all service logs
disinto logs forgejo   # tail specific service
disinto shell     # shell into agents container

8. 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 "${OPS_REPO_ROOT}/prerequisites.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.
• Local forge is the source of truth: all agent work targets the local Forgejo instance. Upstream mirrors are synced after merge.
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1: must be set in production to prevent Claude Code from making auto-update requests.