software-factory

Files (7)

• .claude-plugin
• .codex-plugin
• plugin.json · .plugin/
• README.md
• SKILL.md
• software-factory.md · commands/
• factory.py · scripts/

SKILL.md (first lines)

# Software Factory

Build a GitHub software factory from the automation plugin specs in
`plugins/<id>/.plugin/plugin.json`, with setup defaults still read from
`automations/catalog/<id>/manifest.json`; a Jira or Linear station is created
by its own skill. This skill adds no automation logic.

Two phases: **Phase 1** gets a working factory after one question. **Phase 2**
extends it in short rounds, only as far as the user wants. After Phase 1 and
after every round, the **Checkpoint** shows what exists and lets the user stop.

Code lives on GitHub. Tickets can come from GitHub issues (default), Jira or
Linear: only the issue to PR station changes (see "Ticket source"). GitLab and
Bitbucket code hosts are not part of this flow.

## Stations

| Station | Catalog id | Phase | Agent profile |
|---|---|---|---|
| Issue to PR | `github-issue-to-pr`, or the Jira or Linear station | 1 | `default` (GitHub issues only) |
| PR reviewer | `github-pr-reviewer` | 1 | `default` |
| Issue triage | `github-issue-triage`, or `linear-triage-assistant` | 1 | `default` (GitHub issues only) |
| AGENTS.md maintainer | `github-agents-md-maintainer` | add-on | `default` |
| Auto-merge watchdog | `github-delivery-watchdog` | add-on | none |
| Stale-CI PR closer | `github-stale-ci-pr-closer` | add-on | none |
| QA changes | `qa-changes` | add-on | none |

## Helper script

`scripts/factory.py` in this skill's directory does every catalog and API step
and prints one JSON document; it exits non-zero with `{"error": ...}` on
failure. Its usage is below: do not read its source, and do not load the
`openhands-automation` skill for Phase 1.

Set `OPENHANDS_HOST` to the **Ingress** URL in `<RUNTIME_SERVICES>` on a local
Agent Canvas (it serves both `/api/automation` and `/api`; the automation
backend URL does not), or to `<HOST>` on OpenHands Cloud. Run every command as:

```bash
GITHUB_PERSONAL_ACCESS_TOKEN="$GITHUB_PERSONAL_ACCESS_TOKEN" \
OPENHANDS_AUTOMATION_API_KEY="$OPENHANDS_AUTOMATION_API_KEY" \
OPENHANDS_API_KEY="$OPENHANDS_API_KEY" \
python3 <this skill's directory>/scripts/factory.py <command> ...
```

`$F` below stands for that whole line. Keep the secret names in it: the agent
server passes a saved secret into a command only when the command names it.
The script reads the token and never prints it.

| Command | Does |
|---|---|
| `$F preflight --repos a/b,c/d` | Which stations this deployment supports, the agent profile, the GitHub login, push access per repository. |
| `$F create --repos a/b --ids ID,ID [--set FIELD=VALUE] [--set ID.FIELD=VALUE]` | Creates disabled plugin-spec stations with the `software-factory` tag where supported. Reports existing stations separately and tags them where possible. |
| `$F tune --repos a/b --ids ID,ID [--set schedule=...|timezone=...] [--set ID.schedule=...]` | Updates schedule or timezone in place; other plugin config requires recreating the station until config patching is supported. |
| `$F tag ID...` | Adds the `software-factory` tag to automations created by other skills, reporting failures under `not_tagged`. |
| `$F verify ID... [--no-wait ID...]` | Dispatches once, enables the ones whose run `COMPLETED` and disables the rest, reporting their `error_detail`. `--no-wait` enables without waiting. |
| `$F status ID...` | The latest run of each. |
| `$F prs --repos a/b [--branch-prefix P]` | Open pull requests whose branch starts with `P` (default `openhands/agents-md`, the AGENTS.md maintainer's). |
| `$F reset-token` | Deletes the saved `GITHUB_PERSONAL_ACCESS_TOKEN` (local Agent Canvas), so `request_secret` opens its form again. |

`create` and `verify` return each automation's `url`, its page in Agent Canvas.
Trust the script's output: do not open pages in the browser to check them, and
do not use the task tracker for this flow.

Plugin-spec stations use the agent profile named `default`. Keep `--profile`
omitted unless you are explicitly checking that same profile name. Remote plugin
sources use the installed `openhands-extensions` version tag when available, or
`main` for unreleased source checkouts. Set `FACTORY_EXTENSIONS_REF` to pin a
specific tag or branch.

## Rules

- **Supported stations**: create only those `preflight` reports `ok`; say why
  the others are skipped.
- **Derived values** (the script fills them; never ask): every
  `githubTokenSecret` is `GITHUB_PERSONAL_ACCESS_TOKEN`. The watchdog's
  `branchPrefix` must equal issue to PR's: when it was changed, pass
  `--set github-delivery-watchdog.branchPrefix=<same value>`.
- **Agent profile**: plugin-spec stations that launch agents use the profile
  named `default`. If `preflight` reports a profile error, skip the stations
  that need one and ask the user to create or fix the `default` profile.
- **Token**: never ask for its value in chat, echo it, or put it in a tool
  argument or file.
- **Failures**: if `create` fails, its output lists the stations it already
  created; report them with the error and ask whether to retry or delete them
  (`DELETE ${OPENHANDS_HOST}/api/automation/v1/{id}`).
- **Existing stations**: a station `create` reports under `existing` was already
  set up by an earlier run. Say so rather than presenting it as new. Use `$F tune`
  only for schedule or timezone changes; delete and recreate for other plugin
  settings until config patching is supported.
- **Factory tag**: every station carries the `software-factory` tag where
  supported. `create` adds it; for stations created by other skills (Jira or
  Linear issue to PR, Linear triage, QA changes), run `$F tag <id>`. If a station
  is `not_tagged`, report its reason: only its creator may change tags, or the
  deployment does not support tags yet.

## Phase 1 - Working factory

1. Ask, in one message: "Which GitHub repositories (`owner/repo`)? Where do
   tickets live: GitHub issues (default), Jira or Linear?" Say that everything
   else uses defaults that can be changed afterwards. If the answer names only
   repositories, use GitHub issues; do not ask again.
2. Run `$F preflight --repos <repos>`. Drop repositories without `push`, and
   say which.
3. If `github_login` is null, act on `token_error`:
   - `not_set`, and the `request_secret` tool is available: call it once with
     `name: "GITHUB_PERSONAL_ACCESS_TOKEN"` and a `reason` asking for Contents,
     Issues, Pull requests and Workflows read and write (classic PAT: `repo`,
     `workflow`), and saying a token can be created at
     https://github.com/settings/personal-access-tokens. End your turn, wait
     for the `[secret-request]` message, then rerun `preflight`.
   - `rejected`: GitHub refuses the saved token (invalid or expired), and
     `request_secret` cannot replace it: it answers `saved` at once for a name
     that exists. Say so in one sentence and ask "Shall I remove it and open
     the form for a new one?" On yes, run `$F reset-token`, then handle it as
     `not_set`. If `reset-token` fails, tell the user to create a token at
     https://github.com/settings/personal-access-tokens, replace it in
     Settings -> Secrets, and say when done.
   - `not_set` without the tool: tell the user to create a token at

From OpenHands/extensions, MIT.

More from OpenHands/extensions