johba/disinto
1
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

feat: add disinto-factory skill for guided setup and operations
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details

Browse source 
Distributable skill file (SKILL.md) that walks an AI agent through:
- First-time factory setup with interactive [ASK] prompts
- Post-init verification checklist
- Mirror configuration to GitHub/Codeberg
- Backlog seeding and issue creation
- Ongoing monitoring: agent status, CI, PRs
- Unsticking blocked issues

Includes:
- scripts/factory-status.sh — one-command factory health check
- references/troubleshooting.md — common issues from real deployments
- Slimmed CLAUDE.md pointing to the skill

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
johba 2026-03-28 11:13:24 +00:00
parent ed43f9db11
commit cbe5df52b2
4 changed files with 318 additions and 237 deletions
Download patch file Download diff file Expand all files Collapse all files

248
CLAUDE.md
View file

@ -1,246 +1,20 @@
# CLAUDE.md — Skill file for disinto
# CLAUDE.md
## What is disinto?
This repo is **disinto** — an autonomous code factory.
Disinto is an autonomous code factory — bash scripts + Claude CLI that automate the full
software development lifecycle: picking up issues, implementing via Claude, creating PRs,
running CI, reviewing, merging, and mirroring to external forges.
For setup and operations, load the `disinto-factory` skill from `disinto-factory/SKILL.md`.
Read `VISION.md` for the project philosophy, `AGENTS.md` for architecture, and
`BOOTSTRAP.md` for setup instructions.
## Setting up a new factory instance
### Prerequisites
- An LXD container (Debian 12) with Docker, git, jq, curl, tmux, python3 (>=3.11)
- `claude` CLI installed and authenticated
- SSH key for mirror pushes (added to GitHub/Codeberg)
### First-time setup
1. **Clone the repo** and cd into it:
```bash
git clone https://codeberg.org/johba/disinto.git && cd disinto
```
2. **Run init** against the repo you want the factory to develop:
```bash
bin/disinto init https://codeberg.org/org/repo --yes
```
For self-development (factory develops itself):
```bash
bin/disinto init https://codeberg.org/johba/disinto --yes --repo-root $(pwd)
```
3. **Verify the stack** came up:
```bash
docker ps --format "table {{.Names}}\t{{.Status}}"
```
Expected: forgejo (Up), woodpecker (healthy), woodpecker-agent (healthy), agents (Up),
edge (Up), staging (Up).
4. **Check WOODPECKER_TOKEN** was generated:
```bash
grep WOODPECKER_TOKEN .env
```
If empty, see "Known issues" below.
5. **Verify agent cron** is running:
```bash
docker exec -u agent disinto-agents-1 crontab -l -u agent
```
6. **Set up mirrors** (optional):
Edit `projects/<name>.toml`:
```toml
[mirrors]
github = "git@github.com:Org/repo.git"
codeberg = "git@codeberg.org:user/repo.git"
```
Ensure `~/.ssh` is mounted into the agents container and SSH keys are added
to the remote forges. The compose template includes the mount; just add your
public key to GitHub/Codeberg.
### Post-init checklist
- [ ] Stack containers all running and healthy
- [ ] `WOODPECKER_TOKEN` in `.env` is non-empty
- [ ] `projects/<name>.toml` exists with correct `repo_root` and `primary_branch`
- [ ] Labels exist on Forgejo repo: backlog, in-progress, blocked, tech-debt, etc.
- [ ] Agent container can reach Forgejo API: `docker exec disinto-agents-1 bash -c "source /home/agent/disinto/.env && curl -sf http://forgejo:3000/api/v1/version"`
- [ ] Agent repo is cloned: `docker exec -u agent disinto-agents-1 ls /home/agent/repos/<name>`
- If not: `docker exec disinto-agents-1 chown -R agent:agent /home/agent/repos && docker exec -u agent disinto-agents-1 bash -c "source /home/agent/disinto/.env && git clone http://dev-bot:\${FORGE_TOKEN}@forgejo:3000/org/repo.git /home/agent/repos/<name>"`
- [ ] Create backlog issues on Forgejo for the factory to work on
## Checking on the factory
### Agent status
```bash
# Are agents running?
docker exec disinto-agents-1 bash -c "
for f in /proc/[0-9]*/cmdline; do
cmd=\$(tr '\0' ' ' < \$f 2>/dev/null)
echo \$cmd | grep -qi claude && echo PID \$(echo \$f | cut -d/ -f3): running
done
"
# Latest dev-agent activity
docker exec disinto-agents-1 tail -20 /home/agent/data/logs/dev/dev-agent.log
# Latest poll activity
docker exec disinto-agents-1 tail -20 /home/agent/data/logs/dev/dev-agent-<project>.log
```
### Issue and PR status
```bash
source .env
# Open issues
curl -sf "http://localhost:3000/api/v1/repos/<org>/<repo>/issues?state=open" \
-H "Authorization: token $FORGE_TOKEN" | jq -r '.[] | "#\(.number) [\(.labels | map(.name) | join(","))] \(.title)"'
# Open PRs
curl -sf "http://localhost:3000/api/v1/repos/<org>/<repo>/pulls?state=open" \
-H "Authorization: token $FORGE_TOKEN" | jq -r '.[] | "PR #\(.number) [\(.head.ref)] \(.title)"'
```
### CI status
```bash
source .env
# Check pipelines (requires session cookie + CSRF for WP v3 API)
WP_CSRF=$(curl -sf -b "user_sess=$WOODPECKER_TOKEN" http://localhost:8000/web-config.js \
| sed -n 's/.*WOODPECKER_CSRF = "\([^"]*\)".*/\1/p')
curl -sf -b "user_sess=$WOODPECKER_TOKEN" -H "X-CSRF-Token: $WP_CSRF" \
"http://localhost:8000/api/repos/1/pipelines?page=1&per_page=5" \
| jq '.[] | {number, status, event}'
```
### Unsticking a blocked issue
When a dev-agent run fails (CI timeout, implementation error), the issue gets labeled
`blocked`. To retry:
```bash
source .env
# 1. Close stale PR if any
curl -sf -X PATCH "http://localhost:3000/api/v1/repos/<org>/<repo>/pulls/<N>" \
-H "Authorization: token $FORGE_TOKEN" -H "Content-Type: application/json" \
-d '{"state":"closed"}'
# 2. Delete stale branch
curl -sf -X DELETE "http://localhost:3000/api/v1/repos/<org>/<repo>/branches/fix/issue-<N>" \
-H "Authorization: token $FORGE_TOKEN"
# 3. Remove locks
docker exec disinto-agents-1 rm -f /tmp/dev-agent-*.json /tmp/dev-agent-*.lock
# 4. Relabel issue to backlog
BACKLOG_ID=$(curl -sf "http://localhost:3000/api/v1/repos/<org>/<repo>/labels" \
-H "Authorization: token $FORGE_TOKEN" | jq -r '.[] | select(.name=="backlog") | .id')
curl -sf -X PUT "http://localhost:3000/api/v1/repos/<org>/<repo>/issues/<N>/labels" \
-H "Authorization: token $FORGE_TOKEN" -H "Content-Type: application/json" \
-d "{\"labels\":[$BACKLOG_ID]}"
# 5. Update agent repo to latest main
docker exec -u agent disinto-agents-1 bash -c \
"cd /home/agent/repos/<name> && git fetch origin && git reset --hard origin/main"
```
The next cron cycle (every 5 minutes) will pick it up.
### Triggering a poll manually
```bash
docker exec -u agent disinto-agents-1 bash -c \
"cd /home/agent/disinto && bash dev/dev-poll.sh projects/<name>.toml"
```
## Filing issues
The factory picks up issues labeled `backlog`. The dev-agent:
1. Claims the issue (labels it `in-progress`)
2. Creates a worktree on branch `fix/issue-<N>`
3. Runs Claude to implement the fix
4. Pushes, creates a PR, waits for CI
5. Requests review from review-bot
6. Merges on approval, pushes to mirrors
Issue body should contain enough context for Claude to implement it. Include:
- What's wrong or what needs to change
- Which files are affected
- Any design constraints
- Dependency references: `Depends-on: #N` (dev-agent checks these before starting)
Use labels:
- `backlog` — ready for the dev-agent to pick up
- `blocked` — not ready (missing dependency, needs investigation)
- `in-progress` — claimed by dev-agent (set automatically)
- No label — parked, not for the factory to touch
## Reverse tunnel access (for browser UI)
If running in an LXD container with a reverse SSH tunnel to a jump host:
```bash
# On the LXD container, add to /etc/systemd/system/reverse-tunnel.service:
# -R 127.0.0.1:13000:localhost:3000 (Forgejo)
# -R 127.0.0.1:18000:localhost:8000 (Woodpecker)
# From your machine:
ssh -L 3000:localhost:13000 user@jump-host
# Then open http://localhost:3000 in your browser
```
Forgejo admin login: `disinto-admin` / set during init (or reset with
`docker exec disinto-forgejo-1 su -c "forgejo admin user change-password --username disinto-admin --password <pw> --must-change-password=false" git`).
## Known issues & workarounds
### WP CI agent needs host networking in LXD
Docker bridge networking inside LXD breaks gRPC/HTTP2. The compose template uses
`network_mode: host` + `privileged: true` for the WP agent, connecting via
`localhost:9000`. This is baked into the template and works on regular VMs too.
### CI step containers need Docker network
The WP agent spawns CI containers that need to reach Forgejo for git clone.
`WOODPECKER_BACKEND_DOCKER_NETWORK: disinto_disinto-net` is set in the compose
template to put CI containers on the compose network.
### Forgejo webhook allowlist
Forgejo blocks outgoing webhooks by default. The compose template sets
`FORGEJO__webhook__ALLOWED_HOST_LIST: "private"` to allow delivery to
Docker-internal hosts.
### OAuth2 token generation during init
The init script drives a Forgejo OAuth2 flow to generate a Woodpecker token.
This requires rewriting URL-encoded Docker-internal hostnames and submitting
all Forgejo grant form fields. If token generation fails, check Forgejo logs
for "Unregistered Redirect URI" errors.
### Woodpecker UI not accessible via tunnel
The WP OAuth login redirects use Docker-internal hostnames that browsers can't
resolve. Use the Forgejo UI instead — CI results appear as commit statuses on PRs.
### PROJECT_REPO_ROOT inside agents container
The agents container needs `PROJECT_REPO_ROOT` set in its environment to
`/home/agent/repos/<name>` (not the host path from the TOML). The compose
template includes this. If the agent fails with "cd: no such file or directory",
check this env var.
Quick references:
- `AGENTS.md` — per-agent architecture and file-level docs
- `VISION.md` — project philosophy
- `BOOTSTRAP.md` — detailed init walkthrough
- `disinto-factory/references/troubleshooting.md` — common issues and fixes
- `disinto-factory/scripts/factory-status.sh` — quick status check
## Code conventions
See `AGENTS.md` for per-file architecture docs and coding conventions.
Key principles:
- Bash for checks, AI for judgment
- Zero LLM tokens when idle (cron checks are pure bash)
- Zero LLM tokens when idle (cron polls are pure bash)
- Fire-and-forget mirror pushes (never block the pipeline)
- Issues are the unit of work; PRs are the delivery mechanism
- See `AGENTS.md` for per-file watermarks and coding conventions