From 92812ccc34193d316113bfa80a147f4499efcca2 Mon Sep 17 00:00:00 2001 From: dev-bot Date: Tue, 31 Mar 2026 18:17:38 +0000 Subject: [PATCH] docs: rewrite SKILL.md to focus on external project setup (#64) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructures SKILL.md to: - Remove self-development guidance — focus on external project setup - Clarify that `disinto init` accepts remote URLs or owner/name slugs - Add project configuration TOML format documentation with field descriptions - Revise mirror setup section to reference project TOML Closes #822 and #823 on Codeberg. --- _Upstream: codeberg johba/disinto PR #824_ Co-authored-by: johba Reviewed-on: http://forgejo:3000/johba/disinto/pulls/64 Reviewed-by: review-bot Co-authored-by: dev-bot Co-committed-by: dev-bot --- disinto-factory/SKILL.md | 83 ++++++++++++++++++++++++++++++++++------ 1 file changed, 71 insertions(+), 12 deletions(-) diff --git a/disinto-factory/SKILL.md b/disinto-factory/SKILL.md index 8e17508..8c6a672 100644 --- a/disinto-factory/SKILL.md +++ b/disinto-factory/SKILL.md @@ -9,6 +9,8 @@ You are helping the user set up and operate a **disinto autonomous code factory* 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. +This guide shows how to set up the factory to develop an **external project** (e.g., `johba/harb`). + ## First-time setup Walk the user through these steps interactively. Ask questions where marked with [ASK]. @@ -27,20 +29,34 @@ docker --version && git --version && jq --version && curl --version && tmux -V & Any missing tool — help the user install it before continuing. -### 2. Clone and init +### 2. Clone disinto and choose a target project +Clone the disinto factory itself: ```bash 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 --yes` +[ASK] What repository should the factory develop? Provide the **remote repository URL** in one of these formats: +- Full URL: `https://github.com/johba/harb.git` or `https://codeberg.org/johba/harb.git` +- Short slug: `johba/harb` (uses local Forgejo as the primary remote) -Run the init and watch for: -- All bot users created (dev-bot, review-bot, etc.) -- `WOODPECKER_TOKEN` generated and saved -- Stack containers all started +The factory will clone from the remote URL (if provided) or from your local Forgejo, then mirror to the remote. + +Then initialize the factory for that project: +```bash +bin/disinto init johba/harb --yes +# or with full URL: +bin/disinto init https://github.com/johba/harb.git --yes +``` + +The `init` command will: +- Create all bot users (dev-bot, review-bot, etc.) on the local Forgejo +- Generate and save `WOODPECKER_TOKEN` +- Start the stack containers +- Clone the target repo into the agent workspace + +> **Note:** The `--repo-root` flag is optional and only needed if you want to customize +> where the cloned repo lives. By default, it goes under `/home/agent/repos/`. ### 3. Post-init verification @@ -70,7 +86,48 @@ 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//.git /home/agent/repos/" ``` -### 4. Mirrors (optional) +### 4. Create the project configuration file + +The factory uses a TOML file to configure how it manages your project. Create +`projects/.toml` based on the template format: + +```toml +# projects/harb.toml + +name = "harb" +repo = "johba/harb" +forge_url = "http://localhost:3000" +repo_root = "/home/agent/repos/harb" +primary_branch = "master" + +[ci] +woodpecker_repo_id = 0 +stale_minutes = 60 + +[services] +containers = ["ponder"] + +[monitoring] +check_prs = true +check_dev_agent = true +check_pipeline_stall = true + +# [mirrors] +# github = "git@github.com:johba/harb.git" +# codeberg = "git@codeberg.org:johba/harb.git" +``` + +**Key fields:** +- `name`: Project identifier (used for file names, logs, etc.) +- `repo`: The source repo in `owner/name` format +- `forge_url`: URL of your local Forgejo instance +- `repo_root`: Where the agent clones the repo +- `primary_branch`: Default branch name (e.g., `main` or `master`) +- `woodpecker_repo_id`: Set to `0` initially; auto-populated on first CI run +- `containers`: List of Docker containers the factory should manage +- `mirrors`: Optional external forge URLs for backup/sync + +### 5. Mirrors (optional) [ASK] Should the factory mirror to external forges? If yes, which? - GitHub: need repo URL and SSH key added to GitHub account @@ -88,7 +145,7 @@ ssh -T git@github.com 2>&1; ssh -T git@codeberg.org 2>&1 If SSH host keys are missing: `ssh-keyscan github.com codeberg.org >> ~/.ssh/known_hosts 2>/dev/null` -Edit `projects/.toml` to add mirrors: +Edit `projects/.toml` to uncomment and configure mirrors: ```toml [mirrors] github = "git@github.com:Org/repo.git" @@ -100,7 +157,7 @@ Test with a manual push: source .env && source lib/env.sh && export PROJECT_TOML=projects/.toml && source lib/load-project.sh && source lib/mirrors.sh && mirror_push ``` -### 5. Seed the backlog +### 6. Seed the backlog [ASK] What should the factory work on first? Brainstorm with the user. @@ -128,10 +185,12 @@ Use labels: - `blocked` — parked, not for the factory - No label — tracked but not for autonomous work -### 6. Watch it work +### 7. Watch it work The dev-agent polls every 5 minutes. Trigger manually to see it immediately: ```bash +source .env +export PROJECT_TOML=projects/.toml docker exec -u agent disinto-agents-1 bash -c "cd /home/agent/disinto && bash dev/dev-poll.sh projects/.toml" ```