feat: create disinto skill package (SKILL.md + helper scripts) (#710)
Add skill/ directory implementing the Agent Skills open standard (SKILL.md format) for the disinto factory. Includes: - SKILL.md with YAML frontmatter, 9-agent architecture overview, env var documentation, 6 common workflows, and gotchas section (170 lines) - scripts/factory-status.sh — query agent status, open issues, CI pipelines - scripts/file-issue.sh — create forge issues with label resolution and secret scanning - scripts/read-journal.sh — read planner/supervisor/exec journals by date - templates/issue-template.md — standard issue body format Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
openhands
parent
805fa69770
commit
26fcb186a0
5 changed files with 485 additions and 0 deletions
170
skill/SKILL.md
Normal file
170
skill/SKILL.md
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
---
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue