@openhands/extensions 0.30.0 → 0.31.0

package/skills/slack-channel-monitor/scripts/main.py

@@ -17,6 +17,10 @@ On subsequent runs:
 Configuration constants are embedded at automation-creation time by the skill.
 See SKILL.md for the full setup workflow.
 
+Runs against a local agent server (AGENT_SERVER_URL is injected) or on OpenHands
+Cloud and Enterprise (OPENHANDS_CLOUD_API_URL / OPENHANDS_API_KEY / SANDBOX_ID are
+injected instead).
+
 Required secrets (set in OpenHands Settings → Secrets):
   SLACK_BOT_TOKEN    -  bot token (xoxb-…)   with scopes:
                         channels:history, channels:read,
@@ -26,7 +30,8 @@ Required secrets (set in OpenHands Settings → Secrets):
                         channels:history, search:read (for multi-channel),
                         reactions:write, chat:write
 
-Optional secret:
+Optional secret (local Agent Canvas only; on OpenHands Cloud and Enterprise the
+links open the deployment's own Canvas):
   OPENHANDS_URL      -  base URL of your OpenHands instance for conversation
                       links (default: http://localhost:8000)
 """
@@ -38,6 +43,7 @@ import sys
 import time
 import urllib.error
 import urllib.request
+import uuid
 from datetime import datetime, timezone
 from urllib.parse import urlencode
 
@@ -101,6 +107,12 @@ MAX_THREAD_REPLY_POLLS_PER_RUN = 1
 
 # ── Stdlib helpers ─────────────────────────────────────────────────────────────
 
+# A local Agent Canvas run is handed the Agent Server URL. A run on OpenHands
+# Cloud or Enterprise is handed the OpenHands API instead.
+_CLOUD_API_URL = os.environ.get("OPENHANDS_CLOUD_API_URL", "").rstrip("/")
+IS_CLOUD = bool(_CLOUD_API_URL) and not os.environ.get("AGENT_SERVER_URL")
+
+
 def _get_env_key() -> str:
     return (
         os.environ.get("SESSION_API_KEY")
@@ -110,13 +122,14 @@ def _get_env_key() -> str:
 
 
 def get_secret(name: str) -> str:
-    """Fetch a named secret from the agent server."""
-    url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
+    """Fetch a named secret from the agent server, or from the OpenHands API on cloud."""
     key = _get_env_key()
-    req = urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}",
-        headers={"X-Session-API-Key": key},
-    )
+    if IS_CLOUD:
+        # The OpenHands API serves the secrets of this run's sandbox.
+        url = f"{_CLOUD_API_URL}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
+    else:
+        url = f"{os.environ.get('AGENT_SERVER_URL', '').rstrip('/')}/api/settings/secrets/{name}"
+    req = urllib.request.Request(url, headers={"X-Session-API-Key": key})
     with urllib.request.urlopen(req) as r:
         return r.read().decode().strip()
 
@@ -158,6 +171,9 @@ def _ngrok_public_openhands_url() -> str | None:
 
 
 def resolve_openhands_url() -> str:
+    if IS_CLOUD:
+        # Conversations are opened in the Canvas of the deployment itself.
+        return f"{_CLOUD_API_URL}/canvas"
     try:
         configured = get_secret("OPENHANDS_URL").rstrip()
     except Exception:
@@ -184,12 +200,14 @@ def fire_callback(
         body["error"] = error
     if conversation_id:
         body["conversation_id"] = conversation_id
+    # A cloud run is not given a callback key; it authenticates with its API key.
+    api_key = os.environ.get("AUTOMATION_CALLBACK_API_KEY") or os.environ.get("OPENHANDS_API_KEY", "")
     req = urllib.request.Request(
         url,
         data=json.dumps(body).encode(),
         headers={
             "Content-Type": "application/json",
-            "Authorization": f"Bearer {os.environ.get('AUTOMATION_CALLBACK_API_KEY', '')}",
+            "Authorization": f"Bearer {api_key}",
         },
     )
     try:
@@ -578,11 +596,100 @@ def _build_secrets_payload(agent_url: str, api_key: str) -> dict:
     return secrets
 
 
+def _cloud_request(method: str, path: str, body: dict | None = None):
+    """Call the OpenHands API with the API key this cloud run was given."""
+    req = urllib.request.Request(
+        f"{_CLOUD_API_URL}{path}",
+        data=json.dumps(body).encode() if body is not None else None,
+        headers={
+            "Authorization": f"Bearer {os.environ.get('OPENHANDS_API_KEY', '')}",
+            "Content-Type": "application/json",
+        },
+        method=method,
+    )
+    try:
+        with urllib.request.urlopen(req) as r:
+            raw = r.read()
+            return json.loads(raw) if raw.strip() else {}
+    except urllib.error.HTTPError as exc:
+        body_text = exc.read().decode()
+        raise RuntimeError(f"OpenHands API {method} {path} → {exc.code}: {body_text}") from exc
+
+
+def _create_cloud_conversation(initial_message: str, title: str) -> str:
+    """Start a conversation through the OpenHands API and return its id.
+
+    OpenHands runs it in a sandbox of its own, which outlives this run's, with
+    the user's own model, MCP servers and secrets, so none of the local
+    forwarding in create_conversation applies. The API answers with the task
+    that starts the conversation, not with a started conversation.
+    """
+    conversation_id = uuid.uuid4().hex
+    task = _cloud_request(
+        "POST",
+        "/api/v1/app-conversations",
+        {
+            "conversation_id": conversation_id,
+            "title": title,
+            "initial_message": {
+                "role": "user",
+                "content": [{"type": "text", "text": initial_message}],
+            },
+        },
+    )
+    if task.get("status") == "ERROR":
+        raise RuntimeError(f"Starting a conversation failed: {task.get('detail') or 'no detail'}")
+    return conversation_id
+
+
+def _cloud_conversation(conv_id: str) -> dict | None:
+    """The conversation's record, or None while OpenHands is still bringing it up."""
+    found = _cloud_request("GET", f"/api/v1/app-conversations?ids={conv_id}")
+    return found[0] if found else None
+
+
+def _cloud_conversation_status(conv_id: str) -> str:
+    conversation = _cloud_conversation(conv_id)
+    if conversation is None:
+        return "starting"
+    if conversation.get("execution_status"):
+        return conversation["execution_status"]
+    # The status is only reported while the conversation's sandbox is running.
+    # Once it is paused, the last status the agent reported is in its events.
+    events = _cloud_request(
+        "GET",
+        f"/api/v1/conversation/{conv_id}/events/search"
+        "?kind__eq=ConversationStateUpdateEvent&sort_order=TIMESTAMP_DESC&limit=100",
+    )
+    for event in events.get("items", []):
+        if event.get("key") == "execution_status":
+            return event.get("value") or "unknown"
+    return "unknown"
+
+
+def _cloud_conversation_final_response(conv_id: str) -> str:
+    """The agent's closing message, read from the conversation's stored events."""
+    events = _cloud_request(
+        "GET",
+        f"/api/v1/conversation/{conv_id}/events/search?sort_order=TIMESTAMP_DESC&limit=100",
+    )
+    for event in events.get("items", []):
+        if event.get("source") != "agent":
+            continue
+        if event.get("kind") == "ActionEvent" and event.get("tool_name") == "finish":
+            return (event.get("action") or {}).get("message") or ""
+        if event.get("kind") == "MessageEvent":
+            content = (event.get("llm_message") or {}).get("content") or []
+            return "".join(part.get("text", "") for part in content)
+    return ""
+
+
 def create_conversation(
     agent_url: str,
     api_key: str,
     initial_message: str,
     agent: dict | None = None,
+    title: str = "",
 ) -> str:
     """Create a conversation and return its ID.
 
@@ -592,7 +699,13 @@ def create_conversation(
 
     Inherits the user's secrets (as LookupSecret references) and MCP
     server configuration so the spawned agent has the same capabilities.
+
+    On OpenHands Cloud and Enterprise the conversation is started through
+    the OpenHands API instead (see _create_cloud_conversation).
     """
+    if IS_CLOUD:
+        return _create_cloud_conversation(initial_message, title)
+
     # Use a dedicated directory for spawned conversations rather than the
     # automation run's WORKSPACE_BASE, which may be cleaned up between runs.
     workspace_base = os.environ.get("WORKSPACE_BASE", "")
@@ -625,6 +738,15 @@ def create_conversation(
 
 def send_to_conversation(agent_url: str, api_key: str, conv_id: str, text: str) -> None:
     """Send a user message to an existing conversation and resume the agent."""
+    if IS_CLOUD:
+        # Answers 409 while the conversation's sandbox is paused and 404 while
+        # OpenHands is still bringing it up; the caller logs either.
+        _cloud_request("POST", f"/api/v1/app-conversations/{conv_id}/send-message", {
+            "role": "user",
+            "content": [{"type": "text", "text": text}],
+            "run": True,
+        })
+        return
     _oh_request(agent_url, api_key, "POST", f"/api/conversations/{conv_id}/events", {
         "role": "user",
         "content": [{"text": text}],
@@ -633,11 +755,15 @@ def send_to_conversation(agent_url: str, api_key: str, conv_id: str, text: str)
 
 
 def conversation_status(agent_url: str, api_key: str, conv_id: str) -> str:
+    if IS_CLOUD:
+        return _cloud_conversation_status(conv_id)
     result = _oh_request(agent_url, api_key, "GET", f"/api/conversations/{conv_id}")
     return result.get("execution_status", "unknown")
 
 
 def conversation_final_response(agent_url: str, api_key: str, conv_id: str) -> str:
+    if IS_CLOUD:
+        return _cloud_conversation_final_response(conv_id)
     result = _oh_request(
         agent_url, api_key, "GET", f"/api/conversations/{conv_id}/agent_final_response"
     )
@@ -956,9 +1082,12 @@ def _process_trigger_message(
     )
 
     try:
-        agent = _get_agent_dict(agent_url, api_key)
+        # A cloud conversation runs with the user's own settings; its model is
+        # read back from the conversation once it is up.
+        agent = None if IS_CLOUD else _get_agent_dict(agent_url, api_key)
         conv_id = create_conversation(
-            agent_url, api_key, initial_prompt, agent=agent
+            agent_url, api_key, initial_prompt, agent=agent,
+            title=f"Slack: {request_part or text}"[:80],
         )
         conv_url = f"{openhands_url}/conversations/{conv_id}"
 
@@ -969,7 +1098,7 @@ def _process_trigger_message(
             "thread_ts": thread_root,
             "status": "active",
             "llm_profile": "default",
-            "llm_model": agent["llm"].get("model") or "unknown",
+            "llm_model": (agent["llm"].get("model") if agent else None) or "unknown",
             "last_activity": now,
             "last_seen_reply_ts": msg_ts,
             "reply_poll_backoff_seconds": THREAD_REPLY_INITIAL_BACKOFF_SECONDS,
@@ -1027,6 +1156,14 @@ def _check_conversation_completion(
             )
         else:
             summary = final if final else "Success (no message available)."
+        if IS_CLOUD:
+            # The model is the conversation's own, known once OpenHands started it.
+            try:
+                rec["llm_model"] = (
+                    (_cloud_conversation(conv_id) or {}).get("llm_model") or rec.get("llm_model")
+                )
+            except Exception as exc:
+                print(f"  Warning: could not read the model for {conv_id}: {exc}")
         # The values recorded when this script started the conversation; a
         # thread follow-up reuses it, so they still describe its LLM. A record
         # written before provenance was tracked cannot name either value.
@@ -1056,6 +1193,14 @@ def _check_conversation_completion(
 
 def main() -> str | None:
     """Run one polling cycle. Returns the last conversation ID created, if any."""
+    if IS_CLOUD and not _kv_available():
+        # A cloud run starts in a fresh sandbox, so a state file would not
+        # survive it and every run would start over.
+        raise RuntimeError(
+            "The automation KV store is required on OpenHands Cloud and Enterprise, "
+            "but AUTOMATION_KV_TOKEN is not set for this run."
+        )
+
     state = load_state()
 
     agent_url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")

package/skills/software-factory/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "software-factory",
+  "version": "1.0.0",
+  "description": "Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from catalog automations with defaults, then let the user stop or extend it step by step.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "onboarding",
+    "software-factory",
+    "github",
+    "automation",
+    "pull-request"
+  ]
+}

package/skills/software-factory/.codex-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "software-factory",
+  "version": "1.0.0",
+  "description": "Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from catalog automations with defaults, then let the user stop or extend it step by step.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "onboarding",
+    "software-factory",
+    "github",
+    "automation",
+    "pull-request"
+  ]
+}

package/skills/software-factory/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "software-factory",
+  "version": "1.0.0",
+  "description": "Set up a GitHub software factory fast: ask only for the repositories and the ticket source (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from catalog automations with defaults, then let the user stop or extend it step by step.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "onboarding",
+    "software-factory",
+    "github",
+    "automation",
+    "pull-request"
+  ]
+}

package/skills/software-factory/README.md

@@ -0,0 +1,64 @@
+# Software Factory
+
+Set up a GitHub "software factory" fast, then grow it step by step. The skill
+asks only for the repositories, creates a working pipeline from catalog
+automations with their defaults, shows what runs, and lets the user stop there
+or extend it.
+
+## Trigger
+
+This skill is activated by:
+
+- `/software-factory`
+- the phrase "software factory" (only when the skill is enabled)
+
+## What it sets up
+
+| Station | Catalog id | Phase |
+|---|---|---|
+| Issue to PR | `github-issue-to-pr`, or the Jira or Linear station | 1 |
+| PR reviewer | `github-pr-reviewer` | 1 |
+| AGENTS.md maintainer | `github-agents-md-maintainer` | 1 |
+| Issue triage | `github-issue-triage` | add-on |
+| Auto-merge watchdog | `github-delivery-watchdog` | add-on |
+| Stale-CI PR closer | `github-stale-ci-pr-closer` | add-on |
+| QA changes | `qa-changes` | add-on (webhooks only) |
+
+`scripts/factory.py` (Python standard library, no LLM) does the catalog and API
+work - preflight checks, bundle upload and create, in-place tune, smoke run and
+enable - so Phase 1 takes four agent steps. The skill adds no automation logic of its own. Each station is the unmodified
+catalog bundle from `automations/catalog/<id>/`, configured from its `setup`
+block, so fixes to a station reach factories created by this skill too. A Jira
+or Linear issue to PR station is created by its own skill instead.
+
+## Flow
+
+1. **Phase 1**: verify `GITHUB_PERSONAL_ACCESS_TOKEN` (asked for with the
+   `request_secret` tool if missing, never in chat), ask for the repositories
+   and the ticket source (GitHub issues, Jira or Linear),
+   create the three Phase 1 stations with defaults, smoke-run issue to PR and
+   the reviewer, and enable those that pass. The AGENTS.md maintainer is
+   enabled at once and opens an `AGENTS.md` pull request per repository.
+2. **Checkpoint**: show the stations, their settings and how to use the
+   factory. The user can stop here or pick a next step: try it with a test
+   issue, tune settings, or add a station.
+3. **Phase 2**: one round per pick, asking only the questions for it, then back
+   to the Checkpoint.
+
+## Requirements
+
+- An automation backend whose `/api/automation/v1/capabilities` reports the
+  features each station's manifest requires (`customTarball`, plus
+  `agentProfiles` for issue to PR, reviewer and triage; QA needs webhook delivery).
+- A GitHub token with Contents, Issues, Pull requests and Workflows read and
+  write on every selected repository.
+- An OpenHands (not ACP) agent profile that may use that token.
+- Jira tickets: a connected Atlassian Rovo server or a Jira API token. Linear
+  tickets: a Linear connection.
+
+## Scope
+
+Code lives on GitHub. Tickets can come from GitHub issues, Jira (through the
+`jira-issue-to-pr` skill) or Linear (through the `ticket-to-code-change`
+skill); only the issue to PR station changes. GitLab and Bitbucket code hosts
+are not part of this flow.

package/skills/software-factory/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: software-factory
+description: >
+  Set up an OpenHands "software factory" on GitHub fast: ask only for the
+  repositories and where tickets live (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from the
+  automation catalog with defaults, show what runs, then let the user stop or
+  extend it one step at a time (tune settings, triage, auto-merge, stale-CI and
+  QA add-ons).
+triggers:
+  - /software-factory
+  - software factory
+---
+
+# Software Factory
+
+Build a GitHub software factory from unmodified automation catalog bundles
+(`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 | Needs agent profile |
+|---|---|---|---|
+| Issue to PR | `github-issue-to-pr`, or the Jira or Linear station | 1 | yes (GitHub issues only) |
+| PR reviewer | `github-pr-reviewer` | 1 | yes |
+| AGENTS.md maintainer | `github-agents-md-maintainer` | 1 | no |
+| Issue triage | `github-issue-triage`, or `linear-triage-assistant` | add-on | yes (GitHub issues only) |
+| Auto-merge watchdog | `github-delivery-watchdog` | add-on | no |
+| Stale-CI PR closer | `github-stale-ci-pr-closer` | add-on | no |
+| QA changes | `qa-changes` | add-on | no |
+
+## 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]` | Fills each station's form (answers, then derived values, then manifest defaults), uploads the bundle and creates it disabled. `FIELD=VALUE` applies to every listed station with that field. Stations that already exist are reported under `existing`, not recreated. |
+| `$F tune --repos a/b --ids ID,ID [--set FIELD=VALUE] [--set ID.FIELD=VALUE]` | Applies new settings to an existing station by updating it in place. Use this to change a value that is fixed at creation. |
+| `$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.
+
+Add `--profile NAME` to `preflight` or `create` to use a profile other than the
+active one.
+
+## 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**: if `preflight` reports a profile error, skip the stations
+  that need one and point the user to the station's catalog card in Agent
+  Canvas (Automations), which has a profile picker.
+- **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 and was left unchanged. Say so rather than presenting
+  it as new, and change it with `$F tune` if the user wants different settings.
+
+## 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`). 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 replace it in
+     Settings -> Secrets and say when done.
+   - `not_set` without the tool: tell the user to add it in Settings ->
+     Secrets and stop.
+4. `$F create --repos <repos> --ids github-pr-reviewer,github-agents-md-maintainer`,
+   adding `github-issue-to-pr` for GitHub issues. For Jira or Linear, also set
+   up the issue to PR station as "Ticket source" describes.
+5. `$F verify <reviewer id> [<issue to PR id>] --no-wait <maintainer id>`. The
+   maintainer's run opens one `AGENTS.md` pull request per repository.
+6. Go to the Checkpoint.
+
+## Checkpoint
+
+Write one short message, in this order:
+
+1. One plain sentence on what runs and how to use it: "Your factory is running
+   on `<repos>`. Add the `<trigger label>` label to a ticket to get a draft pull
+   request; the reviewer reviews it and you merge it." (On Jira, add that the
+   ticket body must name the `owner/repo`.)
+2. The `AGENTS.md` pull requests from `$F prs --repos <repos>`, asking the user
+   to merge them: they give the build agent the repository's build, test and
+   lint commands. One opened before this setup started (`created_at`) is
+   "still open from an earlier run", not new; the maintainer works once a week
+   per repository. If there are none yet, say they are on their way.
+3. A small table of the automations, each linked to its `url`:
+
+   | Automation | Schedule | Status |
+   |---|---|---|
+   | [Issue to PR](<url>) | every 15 minutes | on |
+
+   Status is `on`, or `off` with the reason in a few words. No automation ids.
+4. The settings in effect, as a short list (the Tune table's current values).
+   Mention that the reviewer also reviews any open, non-draft, green pull
+   request with no review yet (at most 2 new per scan).
+5. End with only a list of possible next steps, one line each, and nothing
+   after it. Mark the first one not done yet as recommended:
+   - **Try it**: I open a small test issue with the `<trigger label>` label in
+     `<repo>`, only if you say so, and report the pull request.
+   - **Tune**: change a setting from the list above.
+   - **Add a station**: triage, auto-merge watchdog, stale-CI closer (QA only
+     if `preflight` reports it `ok`).
+   - **Stop here**: the factory keeps running as it is.
+
+## Phase 2 - Extend, one round at a time
+
+Do only what the user picked. Ask only the questions for it, in one message,
+each with its current value. Apply, then return to the Checkpoint.
+
+### Tune
+
+| Setting | Default | `--set` |
+|---|---|---|
+| Issue trigger label (GitHub issues) | `openhands` | `github-issue-to-pr.triggerLabel` |
+| Draft or ready pull requests | `draft` | `pullRequestMode` (issue to PR, AGENTS.md maintainer) |
+| Branch prefix (GitHub issues) | `openhands/issue` | `github-issue-to-pr.branchPrefix` (and the watchdog's, if present) |
+| Which pull requests get reviewed | label `openhands-review`, reviewer `all-hands-bot` | `github-pr-reviewer.triggerLabel`, `triggerReviewer` |
+| Review tone: concise, thorough, friendly | `concise` | `reviewTone` |
+| Human reviewers requested after agent approval (two or more logins) | none | `maintainers` |
+| Schedules and timezone | issue to PR `*/15 * * * *`, reviewer `*/5 * * * *`, AGENTS.md maintainer `0 9 * * 1`, add-ons per manifest; `UTC` | `ID.schedule`, `timezone` |
+| Agent profile | active profile | `--profile NAME` |
+
+Apply:
+
+- Schedule or timezone only:
+  `PATCH ${OPENHANDS_HOST}/api/automation/v1/{id}` with `{"trigger": {...}}`.
+- Jira or Linear station settings: change them as its skill describes.
+- Anything else is fixed at creation: `$F tune --repos <repos> --ids <id>` with
+  the new `--set` values (repeat every earlier non-default value), then
+  `$F verify <id>`. `tune` updates the station in place, so there is no
+  replacement to delete and no template-id collision.
+
+### Add a station
+
+Ask only the question below, then `$F create` it and `$F verify` it.
+
+- **Auto-merge watchdog** (`github-delivery-watchdog`, GitHub issues only,
+  since it merges only branches with the issue to PR prefix): confirm the user
+  wants the agent to merge pull requests itself once review, tests and CI are
+  green.
+- **Stale-CI closer** (`github-stale-ci-pr-closer`): confirm it may warn on,
+  then close, pull requests whose CI keeps failing.
+- **Triage** (`github-issue-triage`): nothing. For Linear, follow the
+  `linear-triage` skill instead; for Jira there is none.
+- **QA changes**: which base branch (default `main`). Offer QA only if
+  `preflight` reports it `ok` and the `openhands-automation` webhook
+  reachability check passes. It has no bundle, so the script cannot create it:
+  create it as the `openhands-automation` skill describes for an
+  event-triggered prompt preset, with its manifest `prompt` and `filter`, one
+  per repository (it takes a single `repository`). It runs only on pull request
+  events, so leave it enabled and skip `verify`.
+
+## Ticket source
+
+- **GitHub issues**: `github-issue-to-pr`, created with the others in Phase 1.
+- **Jira**: follow the `jira-issue-to-pr` skill with `git_provider` `github`
+  and its defaults (label `create-pr`, `*/5 * * * *`). Ask only what it cannot
+  look up (the Jira site if several, or the API-token details when Atlassian
+  Rovo is not connected). Tell the user each ticket body must name its
+  `owner/repo`.
+- **Linear**: follow the `ticket-to-code-change` skill with GitHub as the
+  provider. Ask its questions in one message, proposing the repositories above
+  and `*/15 * * * *` as defaults.
+
+Once its skill has created the station, run `$F verify <id>` on it.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| Create returns 422 | A value does not match the manifest `setup` block; fix the field at the path the error names. |
+| Issue to PR fails at push | The token lacks Contents or Workflows write, or does not cover that repository. |
+| Reviewer never reviews | The pull request has neither the trigger label nor a request for the trigger reviewer, and is not green. |
+| Watchdog never merges | Its branch prefix differs from issue to PR's, or the pull request lacks an independent approval or green CI. |

package/skills/software-factory/commands/software-factory.md

@@ -0,0 +1,8 @@
+---
+# auto-generated by sync_extensions.py
+description: Set up an OpenHands "software factory" on GitHub fast: ask only for the repositories and where tickets live (GitHub issues, Jira or Linear), create a working issue-to-PR and PR-review pipeline from the automation catalog with defaults, show what runs, then let the user stop or extend it one step at a time (tune settings, triage, auto-merge, stale-CI and QA add-ons).
+---
+
+Read and follow the complete instructions in the SKILL.md file located in this skill's directory.
+
+$ARGUMENTS