docs: add factory interaction lessons to SKILL.md #156

New issue

Closed

opened 2026-04-02 20:28:30 +00:00 by dev-bot · 0 comments

dev-bot commented

2026-04-02 20:28:30 +00:00

Collaborator

Problem

SKILL.md is 268 lines and growing. Adding factory lessons would push it past 350+. Claude Code skills support multi-file packages where SKILL.md is a navigation hub referencing supporting files that are loaded lazily.

What to do

1. Split SKILL.md into three files

Extract from the current SKILL.md:

setup.md — "First-time setup" section (steps 1-7: environment, clone, init, verification, TOML config, mirrors, seed backlog, watch it work)
operations.md — "Ongoing operations" section (status checks, CI access, unstick blocked issues, Forgejo UI access)
best-practices.md — NEW section with factory interaction patterns (see content below)

2. Rewrite SKILL.md as a hub

SKILL.md becomes ~50 lines — overview, when to use each guide, and links:

---
name: disinto-factory
description: Set up and operate a disinto autonomous code factory.
---

# Disinto Factory

You are helping the user set up and operate a **disinto autonomous code factory**.

## Guides

- **[Setup guide](setup.md)** — First-time factory setup: environment, init, verification, backlog seeding
- **[Operations guide](operations.md)** — Day-to-day: status checks, CI debugging, unsticking issues, Forgejo access
- **[Best practices](best-practices.md)** — Patterns for writing issues, debugging CI, retrying failures, vault operations, breaking down features

## 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` for one-shot implementation sessions
- Mirror pushes happen automatically after every merge
- Cron schedule: dev-poll every 5min, review-poll every 5min, gardener 4x/day

## References

- [Troubleshooting](references/troubleshooting.md)
- [Factory status script](scripts/factory-status.sh)

3. Content for best-practices.md

# Working with the factory — best practices

## Writing issues for the dev agent

**Put everything in the issue body, not comments.** The dev agent reads the issue body when it starts work. It does not reliably read comments. If an issue fails and you need to add guidance for a retry, update the issue body.

**One approach per issue, no choices.** The dev agent cannot make design decisions. If there are multiple ways to solve a problem, decide before filing. Issues with "Option A or Option B" will confuse the agent.

**Issues must fit the templates.** Every backlog issue needs: affected files (max 3), acceptance criteria (max 5 checkboxes), and a clear proposed solution. If you cannot fill these fields, the issue is too big — label it `vision` and break it down first.

**Explicit dependencies prevent ordering bugs.** Add `Depends-on: #N` in the issue body. dev-poll checks these before pickup. Without explicit deps, the agent may attempt work on a stale codebase.

## Debugging CI failures

**Check CI logs via Woodpecker SQLite when the API fails.** The Woodpecker v3 log API may return HTML instead of JSON. Reliable fallback:
```bash
sqlite3 /var/lib/docker/volumes/disinto_woodpecker-data/_data/woodpecker.sqlite \
  "SELECT le.data FROM log_entries le \
   JOIN steps s ON le.step_id = s.id \
   JOIN workflows w ON s.pipeline_id = w.id \
   JOIN pipelines p ON w.pipeline_id = p.id \
   WHERE p.number = <N> AND s.name = '<step>' ORDER BY le.id"

When the agent fails repeatedly on CI, diagnose externally. The dev agent cannot see CI log output (only pass/fail status). If the same step fails 3+ times, read the logs yourself and put the exact error and fix in the issue body.

Retrying failed issues

Clean up stale branches before retrying. Old branches cause recovery mode which inherits stale code. Close the PR, delete the branch on Forgejo, then relabel to backlog.

After a dependency lands, stale branches miss the fix. If issue B depends on A, and B's PR was created before A merged, B's branch is stale. Close the PR and delete the branch so the agent starts fresh from current main.

Environment gotchas

Alpine/BusyBox differs from Debian. CI and edge containers use Alpine:

grep -P (Perl regex) does not work — use grep -E
USER variable is unset — set it explicitly: USER=$(whoami); export USER
Network calls fail during docker build in LXD — download binaries on the host, COPY into images

The host repo drifts from Forgejo main. If factory code is bind-mounted, the host checkout goes stale. Pull regularly or use versioned releases.

Vault operations

The human merging a vault PR must be a Forgejo site admin. The dispatcher verifies is_admin on the merger. Promote your user via the Forgejo CLI or database if needed.

Result files cache failures. If a vault action fails, the dispatcher writes .result.json and skips it. To retry: delete the result file inside the edge container.

Breaking down large features

Vision issues need structured decomposition. When a feature touches multiple subsystems or has design forks, label it vision. Break it down by identifying what exists, what can be reused, where the design forks are, and resolve them before filing backlog issues.

Prefer gluecode over greenfield. Check if Forgejo API, Woodpecker, Docker, or existing lib/ functions can do the job before building new components.

Max 7 sub-issues per sprint. If a breakdown produces more, split into two sprints.


## Affected files

- `disinto-factory/SKILL.md` (rewrite as hub, ~50 lines)
- `disinto-factory/setup.md` (new — extracted from SKILL.md)
- `disinto-factory/operations.md` (new — extracted from SKILL.md)
- `disinto-factory/best-practices.md` (new — content above)

## Acceptance criteria

- [ ] SKILL.md is under 60 lines, links to three guides
- [ ] setup.md contains the full first-time setup flow
- [ ] operations.md contains status checks, CI, unsticking, Forgejo access
- [ ] best-practices.md contains all six categories of patterns
- [ ] Existing references/ and scripts/ untouched
- [ ] CI green

## Problem SKILL.md is 268 lines and growing. Adding factory lessons would push it past 350+. Claude Code skills support multi-file packages where SKILL.md is a navigation hub referencing supporting files that are loaded lazily. ## What to do ### 1. Split SKILL.md into three files Extract from the current SKILL.md: - **`setup.md`** — "First-time setup" section (steps 1-7: environment, clone, init, verification, TOML config, mirrors, seed backlog, watch it work) - **`operations.md`** — "Ongoing operations" section (status checks, CI access, unstick blocked issues, Forgejo UI access) - **`best-practices.md`** — NEW section with factory interaction patterns (see content below) ### 2. Rewrite SKILL.md as a hub SKILL.md becomes ~50 lines — overview, when to use each guide, and links: ```markdown --- name: disinto-factory description: Set up and operate a disinto autonomous code factory. --- # Disinto Factory You are helping the user set up and operate a **disinto autonomous code factory**. ## Guides - **[Setup guide](setup.md)** — First-time factory setup: environment, init, verification, backlog seeding - **[Operations guide](operations.md)** — Day-to-day: status checks, CI debugging, unsticking issues, Forgejo access - **[Best practices](best-practices.md)** — Patterns for writing issues, debugging CI, retrying failures, vault operations, breaking down features ## 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` for one-shot implementation sessions - Mirror pushes happen automatically after every merge - Cron schedule: dev-poll every 5min, review-poll every 5min, gardener 4x/day ## References - [Troubleshooting](references/troubleshooting.md) - [Factory status script](scripts/factory-status.sh) ``` ### 3. Content for best-practices.md ```markdown # Working with the factory — best practices ## Writing issues for the dev agent **Put everything in the issue body, not comments.** The dev agent reads the issue body when it starts work. It does not reliably read comments. If an issue fails and you need to add guidance for a retry, update the issue body. **One approach per issue, no choices.** The dev agent cannot make design decisions. If there are multiple ways to solve a problem, decide before filing. Issues with "Option A or Option B" will confuse the agent. **Issues must fit the templates.** Every backlog issue needs: affected files (max 3), acceptance criteria (max 5 checkboxes), and a clear proposed solution. If you cannot fill these fields, the issue is too big — label it `vision` and break it down first. **Explicit dependencies prevent ordering bugs.** Add `Depends-on: #N` in the issue body. dev-poll checks these before pickup. Without explicit deps, the agent may attempt work on a stale codebase. ## Debugging CI failures **Check CI logs via Woodpecker SQLite when the API fails.** The Woodpecker v3 log API may return HTML instead of JSON. Reliable fallback: ```bash sqlite3 /var/lib/docker/volumes/disinto_woodpecker-data/_data/woodpecker.sqlite \ "SELECT le.data FROM log_entries le \ JOIN steps s ON le.step_id = s.id \ JOIN workflows w ON s.pipeline_id = w.id \ JOIN pipelines p ON w.pipeline_id = p.id \ WHERE p.number = <N> AND s.name = '<step>' ORDER BY le.id" ``` **When the agent fails repeatedly on CI, diagnose externally.** The dev agent cannot see CI log output (only pass/fail status). If the same step fails 3+ times, read the logs yourself and put the exact error and fix in the issue body. ## Retrying failed issues **Clean up stale branches before retrying.** Old branches cause recovery mode which inherits stale code. Close the PR, delete the branch on Forgejo, then relabel to backlog. **After a dependency lands, stale branches miss the fix.** If issue B depends on A, and B's PR was created before A merged, B's branch is stale. Close the PR and delete the branch so the agent starts fresh from current main. ## Environment gotchas **Alpine/BusyBox differs from Debian.** CI and edge containers use Alpine: - `grep -P` (Perl regex) does not work — use `grep -E` - `USER` variable is unset — set it explicitly: `USER=$(whoami); export USER` - Network calls fail during `docker build` in LXD — download binaries on the host, COPY into images **The host repo drifts from Forgejo main.** If factory code is bind-mounted, the host checkout goes stale. Pull regularly or use versioned releases. ## Vault operations **The human merging a vault PR must be a Forgejo site admin.** The dispatcher verifies `is_admin` on the merger. Promote your user via the Forgejo CLI or database if needed. **Result files cache failures.** If a vault action fails, the dispatcher writes `.result.json` and skips it. To retry: delete the result file inside the edge container. ## Breaking down large features **Vision issues need structured decomposition.** When a feature touches multiple subsystems or has design forks, label it `vision`. Break it down by identifying what exists, what can be reused, where the design forks are, and resolve them before filing backlog issues. **Prefer gluecode over greenfield.** Check if Forgejo API, Woodpecker, Docker, or existing lib/ functions can do the job before building new components. **Max 7 sub-issues per sprint.** If a breakdown produces more, split into two sprints. ``` ## Affected files - `disinto-factory/SKILL.md` (rewrite as hub, ~50 lines) - `disinto-factory/setup.md` (new — extracted from SKILL.md) - `disinto-factory/operations.md` (new — extracted from SKILL.md) - `disinto-factory/best-practices.md` (new — content above) ## Acceptance criteria - [ ] SKILL.md is under 60 lines, links to three guides - [ ] setup.md contains the full first-time setup flow - [ ] operations.md contains status checks, CI, unsticking, Forgejo access - [ ] best-practices.md contains all six categories of patterns - [ ] Existing references/ and scripts/ untouched - [ ] CI green