disinto/skill/SKILL.md

---
name: disinto
description: >-
  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.
license: AGPL-3.0
metadata:
  author: johba
  version: "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
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.