Disinto Factory

Set up and operate a disinto autonomous code factory. Use when bootstrapping a new factory instance, checking on agents and CI, managing the backlog, or trou...

Security Scan

The skill's instructions and shipped script legitimately need sensitive build/CI credentials and access to Docker/host files, but the package does not declare those required environment variables or explain the sensitive operations, creating an incoherent and potentially risky installation.

Purpose & Capability

The described purpose (operating an autonomous code factory) legitimately requires access to the local Docker stack, Forgejo/Woodpecker APIs, and repository mirrors, which the SKILL.md instructs. However, the skill metadata lists no required environment variables or credentials even though the runtime instructions and the included script expect secrets like FORGE_TOKEN, WOODPECKER_TOKEN, FORGE_URL, and a populated .env. That mismatch is a meaningful incoherence.

Instruction Scope

Runtime instructions tell the operator (and the agent, if invoked) to source .env, run docker exec into containers, call internal APIs with tokens, clone remote repos, show SSH public keys, and test SSH access to external forges. Those actions are plausibly within the skill's stated scope, but they involve sensitive tokens and host-level operations and the SKILL.md gives broad interactive discretion (e.g., cloning repos, initializing bots, generating and saving tokens) without enumerating required secrets or explicitly warning the user.

Install Mechanism

This is instruction-only (no install spec) with one small helper script; nothing is downloaded from arbitrary URLs and no archive extraction is used. That reduces install-time risk.

Credentials

The skill uses multiple sensitive environment values (FORGE_TOKEN, WOODPECKER_TOKEN, possibly FORGE_URL, PROJECT_REPO_ROOT, SSH keys, etc.) but requires.env and primary credential fields are empty. Requiring and sourcing an undisclosed .env containing CI and repository tokens is disproportionate to what the package metadata declares and hides the credential surface from reviewers.

Persistence & Privilege

The skill is not always: true and uses normal autonomous-invocation defaults; it does instruct running an init that generates and 'saves' tokens into .env (normal for this class of tool), but it does not request or claim elevated platform privileges or to modify other skills. Still, the combination of host-level Docker access and credential generation/storage raises operational risk and should be confined to isolated hosts/containers.

What to consider before installing

This skill appears to be a legitimate factory operator, but it does not declare the sensitive environment variables and tokens it needs. Before installing or running it: (1) inspect the disinto repo/init scripts (bin/disinto) and any code that writes/reads .env to verify what tokens are created/stored; (2) do not run the init on a host with unrelated secrets — run it in an isolated VM or LXD container as recommended; (3) review the contents of your .env and only provide least-privilege tokens (create tokens scoped to the specific repo and CI actions); (4) avoid uploading or pasting private SSH keys — only add the public key to remotes; (5) if you need a stronger assurance, ask the publisher for an explicit requires.env list and a signed release or review the full upstream repository on Codeberg/GitHub before trusting the scripts. If the maintainer provides an explicit list of required env vars and a clear explanation of what the init writes to .env, my confidence would increase toward benign.

You are helping the user set up and operate a disinto autonomous code factory — a system of bash scripts and Claude CLI that automates the full development lifecycle: picking up issues, implementing via Claude, creating PRs, running CI, reviewing, merging, and mirroring.

First-time setup

Walk the user through these steps interactively. Ask questions where marked with [ASK].

1. Environment

[ASK] Where will the factory run? Options:

• LXD container (recommended for isolation) — need Debian 12, Docker, nesting enabled
• Bare VM or server — need Debian/Ubuntu with Docker
• Existing container — check prerequisites

Verify prerequisites:

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

Any missing tool — help the user install it before continuing.

2. Clone and init

git clone https://codeberg.org/johba/disinto.git && cd disinto

[ASK] What repo should the factory develop? Options:

• Itself (self-development): bin/disinto init https://codeberg.org/johba/disinto --yes --repo-root $(pwd)
• Another project: bin/disinto init <repo-url> --yes

Run the init and watch for:

• All bot users created (dev-bot, review-bot, etc.)
• WOODPECKER_TOKEN generated and saved
• Stack containers all started

3. Post-init verification

Run this checklist — fix any failures before proceeding:

# Stack healthy?
docker ps --format "table {{.Names}}\t{{.Status}}"
# Expected: forgejo, woodpecker (healthy), woodpecker-agent (healthy), agents, edge, staging

# Token generated?
grep WOODPECKER_TOKEN .env | grep -v "^$" && echo "OK" || echo "MISSING — see references/troubleshooting.md"

# Agent cron active?
docker exec -u agent disinto-agents-1 crontab -l -u agent

# Agent can reach Forgejo?
docker exec disinto-agents-1 bash -c "source /home/agent/disinto/.env && curl -sf http://forgejo:3000/api/v1/version | jq .version"

# Agent repo cloned?
docker exec -u agent disinto-agents-1 ls /home/agent/repos/

If the agent repo is missing, clone it:

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

4. Mirrors (optional)

[ASK] Should the factory mirror to external forges? If yes, which?

• GitHub: need repo URL and SSH key added to GitHub account
• Codeberg: need repo URL and SSH key added to Codeberg account

Show the user their public key:

cat ~/.ssh/id_ed25519.pub

Test SSH access:

ssh -T [e-mail] 2>&1; ssh -T [e-mail] 2>&1

If SSH host keys are missing: ssh-keyscan github.com codeberg.org >> ~/.ssh/known_hosts 2>/dev/null

Edit projects/<name>.toml to add mirrors:

[mirrors]
github   = "[e-mail]:Org/repo.git"
codeberg = "[e-mail]:user/repo.git"

Test with a manual push:

source .env && source lib/env.sh && export PROJECT_TOML=projects/<name>.toml && source lib/load-project.sh && source lib/mirrors.sh && mirror_push

5. Seed the backlog

[ASK] What should the factory work on first? Brainstorm with the user.

Help them create issues on the local Forgejo. Each issue needs:

• A clear title prefixed with fix:, feat:, or chore:
• A body describing what to change, which files, and any constraints
• The backlog label (so the dev-agent picks it up)

source .env
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 POST "http://localhost:3000/api/v1/repos/<org>/<repo>/issues" \
  -H "Authorization: token $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"title\": \"<title>\", \"body\": \"<body>\", \"labels\": [$BACKLOG_ID]}"

For issues with dependencies, add Depends-on: #N in the body — the dev-agent checks these before starting.

Use labels:

• backlog — ready for the dev-agent
• blocked — parked, not for the factory
• No label — tracked but not for autonomous work

6. Watch it work

The dev-agent polls every 5 minutes. Trigger manually to see it immediately:

docker exec -u agent disinto-agents-1 bash -c "cd /home/agent/disinto && bash dev/dev-poll.sh projects/<name>.toml"

Then monitor:

# Watch the agent work
docker exec disinto-agents-1 tail -f /home/agent/data/logs/dev/dev-agent.log

# Check for Claude 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 -q 'claude.*-p' && echo 'Claude is running'; done"

Ongoing operations

Check factory status

source .env

# 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)"'

# 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)"'

# Agent logs
docker exec disinto-agents-1 tail -20 /home/agent/data/logs/dev/dev-agent.log

Check CI

source .env
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}'

Unstick a blocked issue

When a dev-agent run fails (CI timeout, implementation error), the issue gets labeled blocked:

1. Close stale PR and delete the branch
2. docker exec disinto-agents-1 rm -f /tmp/dev-agent-*.json /tmp/dev-agent-*.lock
3. Relabel the issue to backlog
4. Update agent repo: docker exec -u agent disinto-agents-1 bash -c "cd /home/agent/repos/<name> && git fetch origin && git reset --hard origin/main"

Access Forgejo UI

If running in an LXD container with reverse tunnel:

# From your machine:
ssh -L 3000:localhost:13000 user@jump-host
# Open http://localhost:3000

Reset admin password if needed:

docker exec disinto-forgejo-1 su -c "forgejo admin user change-password --username disinto-admin --password <new-pw> --must-change-password=false" git

Important context

• Read AGENTS.md for per-agent architecture and file-level docs
• Read VISION.md for project philosophy
• The factory uses a single internal Forgejo as its forge, regardless of where mirrors go
• Dev-agent uses claude -p --resume for session continuity across CI/review cycles
• Mirror pushes happen automatically after every merge (fire-and-forget)
• Cron schedule: dev-poll every 5min, review-poll every 5min, gardener 4x/day