ghostrail 0.0.0 → 0.2.0

package/skill/ghostrail/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: ghostrail
+description: Drive ghostrail (the software factory) from inside this repo. Use when the user types /ghostrail, or asks to set up, customize, check, or run a ghostrail factory — scaffolding ghostrail.toml and prompts, tailoring the scaffolded prompts and gate commands to this codebase, diagnosing a broken setup, or kicking off a run/respond/triage tick.
+user-invocable: true
+argument-hint: "[customize | init | doctor | status | run | respond | triage]"
+license: Apache-2.0
+metadata:
+  version: 0.1.0
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash(npx ghostrail *)
+  - Bash(ghostrail *)
+  - Bash(git *)
+  - Bash(ls *)
+  - Bash(cat *)
+  - Bash(docker images *)
+  - Bash(gh auth status *)
+---
+
+# /ghostrail — drive the factory from the repo
+
+Ghostrail turns this repo into a software factory: it finds eligible tracker
+work, isolates it, runs a sandboxed coding agent that only writes files, gates
+the result against a mirror of CI, and opens a pull request. It never merges.
+
+Dispatch on the argument. With no argument, run **doctor** and then say what the
+useful next step is.
+
+## Resolving the CLI (do this first, every time)
+
+Pick the first that works and reuse it for the whole session:
+
+1. `ghostrail --help` (a global install)
+2. `npx ghostrail --help` (published package)
+3. A local dev checkout, if this *is* the ghostrail repo: `node dist/bin.js --help`
+
+Refer to the chosen form as `<GR>` below. If none work, say so and stop; do not
+hand-roll the factory's behavior.
+
+---
+
+## customize
+
+The headline command. `ghostrail init` scaffolds deliberately generic prompts;
+this tailors them to *this* repo. Never guess: read before proposing.
+
+1. **Confirm the setup exists.** If there is no `ghostrail.toml`, say so and
+   offer to run **init** first.
+2. **Survey the repo.** Gather evidence, don't assume:
+   - Language and layout: manifest files, workspace/monorepo config, `src/` shape.
+   - **Real CI commands** — read the CI workflow (e.g. `.github/workflows/*.yml`)
+     and the package scripts. The gate must mirror CI, in CI's order, including
+     any env vars a build step needs.
+   - Test conventions: framework, where tests live, naming.
+   - House style: a `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`, or lint config.
+3. **Propose edits, then apply on approval.** Show a concrete diff for:
+   - `prompts/resolve-issue.md` — the stack, the layout, where code and tests
+     live, the project's conventions, and the exact lint/typecheck/test commands
+     the agent should run. Keep the `.ghostrail/result.json` contract intact.
+   - `prompts/respond.md` — same context; keep it reading `.ghostrail/feedback.md`.
+   - `prompts/triage.md` — what a right-sized issue looks like in this codebase.
+   - `[gate].commands` — mirroring CI exactly.
+   - `[source]` — the team/project/label/assignee filters, if you can tell what
+     they should be. Ask rather than invent tracker identifiers.
+4. **Do not touch** `[output].auto_merge` (it must stay `false`) or invent
+   credentials.
+
+State plainly what you changed and what still needs a human (tracker IDs, tokens).
+
+---
+
+## init
+
+Scaffold the factory into this repo, then hand off to **customize**.
+
+1. Choose the template from the repo's nature, and say why:
+   - `code-local` — a code repo (gated by CI, opens PRs).
+   - `content-loop` — a writing/content repo (no code gate, draft PRs).
+2. Run `<GR> init <template>`. It is non-clobbering: existing files are kept
+   unless `--force`. Report what was written vs kept.
+3. Tell the user the two things the scaffold can't know (repo-specific prompt
+   detail and the tracker filters), and offer to run **customize** now.
+
+---
+
+## doctor
+
+Diagnose a setup without changing anything. Check and report each, with the fix:
+
+- **CLI** — which form resolved, and its `<GR> version`.
+- **Config** — `ghostrail.toml` present, and it parses. Any ghostrail command
+  prints config errors with a dotted path; use that to point at the exact key.
+- **Prompts** — every path referenced by `[agent].prompt`, `[respond].prompt`,
+  and `[triage].prompt` exists.
+- **Gate** — `[gate].commands` is non-empty for a code factory, and the commands
+  actually exist in the project's scripts.
+- **Credentials** — report which of `LINEAR_API_KEY`, `GH_TOKEN`/`GITHUB_TOKEN`,
+  and `ANTHROPIC_API_KEY` **or** `CLAUDE_CODE_OAUTH_TOKEN` are set. Report only
+  set/unset, **never print a value**. Note that `ANTHROPIC_API_KEY` wins over the
+  OAuth token, so it must be unset to bill a Pro/Max subscription.
+- **GitHub** — `gh auth status` succeeds.
+- **Container backend**, if `[backend].kind = "container"` — the configured
+  `image` exists locally (`docker images`). If not, it must be built.
+
+Finish with a short ordered list of what to fix first.
+
+---
+
+## status
+
+Read-only picture of the factory: the configured queues (source/triage
+eligibility filters), and recent runs from the local store under `.factory/`
+(`events.ndjson`). Summarize the last few runs and their outcomes. For a live
+view, suggest `<GR> board`.
+
+---
+
+## run · respond · triage
+
+Passthroughs. Before executing, state what will happen and confirm, because these
+act on real tracker items and can open real pull requests.
+
+- `run` — one tick over the fix queue. **If `[output].open_pr` is true, this opens
+  a real PR.** Suggest a dry run first (`open_pr = false`) for a new setup.
+- `respond` — folds new PR and tracker comments into existing factory branches.
+- `triage` — decomposes large issues into sub-issues (creates real tracker items).
+
+Run `<GR> <command>` and summarize the resulting JSON: per item, the state
+(`done` / `blocked` / `failed` / `noop` / `skipped`), the gate steps if present,
+and any PR URL. On failure, quote the actual error rather than paraphrasing.
+
+---
+
+## Rules
+
+- **Never** set `auto_merge = true` or merge a factory PR. A human owns merges.
+- **Never** print or commit a secret. Report credentials as set/unset only.
+- Prefer editing the scaffolded prompts over rewriting them; they already encode
+  the `.ghostrail/result.json` and `.ghostrail/triage.json` contracts the factory
+  depends on, and breaking those breaks the loop.
+- When you don't know a tracker identifier (team key, project, labels), ask.

package/templates/{fix-bugs-local → code-local}/README.md

@@ -1,12 +1,12 @@
-# fix-bugs-local
+# code-local
 
 A code factory that runs on your own hardware with zero infrastructure. It drains
 eligible tracker issues, fixes each in an isolated git worktree, gates the result
 against your CI, and opens a pull request. It never merges.
 
 ## Setup
-1. `ghostrail init fix-bugs-local` in your repo (or copy this folder in).
-2. Edit `ghostrail.toml`: set `source.project` to your Linear team key and the
+1. `ghostrail init code-local` in your repo (or copy this folder in).
+2. Edit `ghostrail.toml`: set `source.team` to your Linear team key and the
    `eligible` filter, and set `gate.commands` to your CI steps.
 3. Export `LINEAR_API_KEY` (a Linear personal API key) and make sure `gh` is
    authenticated for your repo.

package/templates/code-local/ghostrail.toml

@@ -0,0 +1,44 @@
+# code-local: a code factory on your own hardware, zero infrastructure.
+# Point it at a repo and a tracker queue; it resolves issues and opens PRs you merge.
+
+[factory]
+name = "code-local"
+base_branch = "main"
+
+[source]
+kind = "linear"                # linear | github-issues (Phase 2)
+team = "TJ"                 # your Linear team key
+eligible = { state = "Todo", label = "factory", assignee = "unassigned" }
+
+[agent]
+kind = "claude-code"
+prompt = "prompts/resolve-issue.md"
+# default allowed_tools = ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
+
+[backend]
+kind = "local-worktree"        # zero infrastructure; git worktree in place
+
+[gate]                         # the oracle: mirror your CI
+commands = [
+  "pnpm install --frozen-lockfile",
+  "pnpm lint",
+  "pnpm typecheck",
+  "pnpm test:unit",
+  "pnpm build",
+]
+
+[guardrails]
+max_items_per_run = 3
+budget_usd_per_item = 3
+timeout = "30m"
+
+[output]
+open_pr = true
+auto_merge = false             # a human owns every merge
+
+[respond]                      # `ghostrail respond` folds PR + tracker comments back in
+prompt = "prompts/respond.md"
+
+[triage]                       # `ghostrail triage` splits large issues into sub-issues
+prompt = "prompts/triage.md"
+eligible = { state = "Todo", label = "triage", assignee = "unassigned" }

package/templates/code-local/prompts/resolve-issue.md

@@ -0,0 +1,31 @@
+# Resolve an issue
+
+You are a coding agent working in an isolated checkout of this repository. Resolve
+the issue described below, whatever kind it is: a bug fix, a new feature, a
+refactor, or a docs change. You may only read and write files and run shell
+commands in this workspace. Do not use git: the factory owns commits, branches,
+and PRs.
+
+Match the surrounding code: its style, patterns, and test conventions.
+
+## The issue
+- ID: {{id}}
+- Title: {{title}}
+- Link: {{url}}
+
+## What to do
+1. Locate the relevant code and understand how it is structured.
+2. Make the smallest correct change that resolves the issue.
+3. Add or update tests (author them from the intent, not the implementation).
+4. Run the project's lint, typecheck, and unit-test commands and fix what you touched.
+
+## Reporting your result (required, do this last)
+Write a JSON file at `.ghostrail/result.json` with exactly one of:
+
+- `{"status":"done","summary":"<what you changed>","type":"<feat|fix|docs|refactor|chore|...>"}`
+- `{"status":"blocked","questions":"<a real product/design decision you need>"}`
+- `{"status":"failed","error":"<why>"}`
+- `{"status":"noop"}`
+
+`type` is the conventional-commit type for the change; it sets the commit and PR
+title. If you omit it, the factory's configured default is used.

package/templates/code-local/prompts/respond.md

@@ -0,0 +1,27 @@
+# Respond to review feedback
+
+You are a coding agent in an isolated checkout of this repository, on the branch
+of an open pull request. New human feedback has been left on the PR or its tracker
+issue. Address it. You may only read and write files and run shell commands in
+this workspace. Do not use git: the factory owns commits and pushes.
+
+## The feedback
+Read `.ghostrail/feedback.md`. It contains the new comments (author and time),
+newest work last. Treat it as the review to act on.
+
+## What to do
+1. Read the feedback and the current state of the branch.
+2. Make the changes it asks for, matching the surrounding code and tests.
+3. Run the project's lint, typecheck, and unit-test commands and fix what you touched.
+4. If a comment is a question rather than a change request, answer it in your result
+   (see `blocked`) instead of guessing.
+
+## Reporting your result (required, do this last)
+Write a JSON file at `.ghostrail/result.json` with exactly one of:
+
+- `{"status":"done","summary":"<what you changed in response>"}`
+- `{"status":"blocked","questions":"<what you need answered>"}`
+- `{"status":"failed","error":"<why>"}`
+- `{"status":"noop"}`
+
+On `done` the factory commits and pushes to the PR branch and posts a summary.

package/templates/code-local/prompts/triage.md

@@ -0,0 +1,51 @@
+# Triage an issue
+
+You are triaging an issue in an isolated checkout of this repository. Your job is
+NOT to fix it: it is to decide whether the issue is too large to fix in one pass
+and, if so, propose how to break it into smaller, ordered sub-issues. Do not use
+git and do not change any source files except the two output files below.
+
+## The issue
+- ID: {{id}}
+- Title: {{title}}
+- Link: {{url}}
+
+## What to do
+1. Read the issue and enough of the codebase to judge its scope.
+2. Decide:
+   - **Atomic** — a single, focused change a coding agent can do in one pass.
+   - **Too large** — spans several independent changes, or mixes unrelated
+     concerns. Propose 2 to 6 sub-issues, each independently shippable, ordered so
+     that dependencies come first.
+3. Write the plan to `.ghostrail/triage.json` (schema below).
+4. Write `.ghostrail/result.json` with `{"status":"done","summary":"<one line>"}`
+   when you produced a plan, or `{"status":"blocked","questions":"<what you need>"}`
+   if you genuinely cannot decide without a human.
+
+## `.ghostrail/triage.json` schema
+
+Atomic (no split):
+
+```json
+{ "status": "noop", "reason": "<why it is already the right size>" }
+```
+
+Split into sub-issues:
+
+```json
+{
+  "status": "split",
+  "reason": "<why it needs splitting>",
+  "subIssues": [
+    { "title": "First, self-contained step", "description": "<what and why>" },
+    { "title": "Second step", "description": "<...>", "dependsOn": [0] }
+  ]
+}
+```
+
+- `dependsOn` lists the indices of earlier sub-issues (0-based, all strictly
+  less than the current one) that must be done first.
+- Keep titles imperative and specific. Each sub-issue should stand on its own.
+
+The factory creates the sub-issues (unassigned) and a human assigns each to the
+bot to start work; the parent leaves the triage queue.

package/templates/content-loop/ghostrail.toml

@@ -13,8 +13,8 @@ base_branch = "main"
 
 [source]
 kind = "linear"
-project = "TJ"                 # your Linear team key
-eligible = { state = "Todo", label = "draft", unassigned = true }
+team = "TJ"                 # your Linear team key
+eligible = { state = "Todo", label = "draft", assignee = "unassigned" }
 
 [agent]
 kind = "claude-code"
@@ -34,3 +34,6 @@ timeout = "30m"
 open_pr = true
 draft = true                   # content PRs open as drafts
 auto_merge = false
+
+[respond]                      # fold PR + tracker feedback back into the draft
+prompt = "prompts/respond.md"

package/templates/content-loop/prompts/respond.md

@@ -0,0 +1,25 @@
+# Respond to feedback on a draft
+
+You are a writing agent in an isolated checkout of this repository, on the branch
+of an open draft pull request. New human feedback has been left on the PR or its
+tracker issue. Revise the draft to address it. You may only read and write files
+and run shell commands in this workspace. Do not use git: the factory owns commits
+and pushes.
+
+## The feedback
+Read `.ghostrail/feedback.md`. It contains the new comments (author and time),
+newest work last. Treat it as the editorial review to act on.
+
+## What to do
+1. Read the feedback and the current draft on this branch.
+2. Revise the draft accordingly, keeping the established voice and format.
+3. If a comment is a question rather than a change, answer it in your result
+   (`blocked`) instead of guessing.
+
+## Reporting your result (required, do this last)
+Write a JSON file at `.ghostrail/result.json` with exactly one of:
+
+- `{"status":"done","summary":"<what you revised>"}`
+- `{"status":"blocked","questions":"<what you need answered>"}`
+- `{"status":"failed","error":"<why>"}`
+- `{"status":"noop"}`

package/templates/fix-bugs-local/ghostrail.toml

@@ -1,37 +0,0 @@
-# fix-bugs-local: a code factory on your own hardware, zero infrastructure.
-# Point it at a repo and a tracker label; it fixes bugs and opens PRs you merge.
-
-[factory]
-name = "fix-bugs"
-base_branch = "main"
-
-[source]
-kind = "linear"                # linear | github-issues (Phase 2)
-project = "TJ"                 # your Linear team key
-eligible = { state = "Todo", label = "factory", unassigned = true }
-
-[agent]
-kind = "claude-code"
-prompt = "prompts/fix-bug.md"
-# default allowed_tools = ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
-
-[backend]
-kind = "local-worktree"        # zero infrastructure; git worktree in place
-
-[gate]                         # the oracle: mirror your CI
-commands = [
-  "pnpm install --frozen-lockfile",
-  "pnpm lint",
-  "pnpm typecheck",
-  "pnpm test:unit",
-  "pnpm build",
-]
-
-[guardrails]
-max_items_per_run = 3
-budget_usd_per_item = 3
-timeout = "30m"
-
-[output]
-open_pr = true
-auto_merge = false             # a human owns every merge

package/templates/fix-bugs-local/prompts/fix-bug.md

@@ -1,27 +0,0 @@
-# Fix a bug
-
-You are a coding agent working in an isolated checkout of a repository. Fix the
-issue described below. You may only read and write files and run shell commands
-in this workspace. Do not use git: the factory owns commits, branches, and PRs.
-
-## The issue
-- ID: {{id}}
-- Title: {{title}}
-- Link: {{url}}
-
-## What to do
-1. Reproduce and locate the bug.
-2. Make the smallest correct fix.
-3. Add or update unit tests that cover it.
-4. Keep the change focused; do not refactor unrelated code.
-
-## Reporting your result (required, do this last)
-Write a JSON file at `.ghostrail/result.json` with exactly one of these shapes:
-
-- Success: `{"status":"done","summary":"<what you changed, one paragraph>"}`
-- Needs a human decision: `{"status":"blocked","questions":"<the decision you need>"}`
-- Could not fix it: `{"status":"failed","error":"<why>"}`
-- No change needed: `{"status":"noop"}`
-
-The factory reads this file to decide what to do, then runs your CI gate and, if
-it passes, opens a pull request for a human to review and merge.