@gr8ful/spf 0.1.5 → 0.1.7

package/README.md

@@ -28,11 +28,12 @@ spf scout "describe this repo"      # a real, read-only run, no setup required
 ### Customizing a repo
 
 ```bash
-spf init          # seed .spf/spf.config.yaml — override only what you want to change
-spf list          # every chain this install knows, its phases, what it needs
+spf init                       # seed .spf/spf.config.yaml — override only what you want to change
+spf init --template ts-cc      # or start from a packaged, ready-to-run template instead
+spf list                       # every chain this install knows, its phases, what it needs
 ```
 
-`spf init` writes a small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field — override one model, one prompt, one quality check, and everything else stays inherited. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
+`spf init` writes a small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field — override one model, one prompt, one quality check, and everything else stays inherited. `--template <name>` writes a real, filled-in config instead of the commented-out starter — every packaged template's name prints after `spf init` runs, and the same files live in [`assets/templates/`](assets/templates/) to browse directly. Nothing here needs to exist for `spf` to run; it's how you make one repo's roster diverge from the defaults.
 
 ### Local development
 
@@ -116,6 +117,24 @@ Config defines who an agent **is**. The chain call site defines how it is **used
 
 Set `coding_agent: claude_code` on any agent (or in `defaults`) to run it on your own installed [Claude Code](https://claude.com/product/claude-code) CLI instead of Flue — `spf doctor` checks it's on `PATH`. Model names follow Claude Code's own vocabulary (a bare alias like `sonnet`, not `provider/model-id`); everything else — `tools`, `writes`, `thinking` — stays the same shape. Pointing a `claude_code` agent at a local or cloud [Ollama](https://ollama.com) server needs no config at all — just `ANTHROPIC_BASE_URL`/`ANTHROPIC_AUTH_TOKEN` set before you run `spf`, since Claude Code's CLI reads those itself.
 
+#### Proxy or wrapper launchers
+
+To route the `claude` command through a wrapper, proxy server, or launcher (e.g., [Ollama](https://ollama.com)), set the `SPF_CLAUDE_CMD` environment variable before running `spf`. Space-separated command chains are supported:
+
+```bash
+# Route through Ollama's launcher
+export SPF_CLAUDE_CMD="ollama launch claude"
+spf build "your prompt"
+```
+
+```bash
+# Or use a custom wrapper script
+export SPF_CLAUDE_CMD=/path/to/my-wrapper
+spf build "your prompt"
+```
+
+The command/launcher must support the full Claude Code CLI interface: `-p` for prompt, `--json-schema`, `--model`, `--session-id`/`--resume`, `--output-format stream-json`, and all other flags `agent_cc` uses. When unset, `SPF_CLAUDE_CMD` defaults to `claude` (resolved from `PATH` normally).
+
 ---
 
 ## Phases: three lanes, one primitive
@@ -219,11 +238,15 @@ spf build-test "implement the plan" --adw-id a1b2c3d4
 
 ## `spf watch`
 
-Polls a GitHub repo for issues labeled `<prefix>:ready`, runs a configured chain against each in its own git worktree, opens a PR, and tracks it through to merged or blocked — driving the same chains above rather than reimplementing an SDLC. Labels are the whole state machine: `ready → working → review → done`/`blocked`.
+Polls an issue tracker for issues labeled `<prefix>:ready`, runs a configured chain against each in its own git worktree, opens a PR against a code host, and tracks it through to merged or blocked — driving the same chains above rather than reimplementing an SDLC. Labels are the whole state machine: `ready → working → review → done`/`blocked`.
+
+The tracker (`issue_provider`) and the code host (`code_host`) are independent config choices, not one bundled "provider" — a tracker and a host are independent choices in practice (Jira issues against a Bitbucket repo is a real setup). Supported today: `issue_provider: github | jira`, `code_host: github | bitbucket` — any combination works, including Jira+GitHub or GitHub-issues+Bitbucket.
 
 ```yaml
-# .spf/spf.config.yaml
+# .spf/spf.config.yaml — GitHub issues + GitHub PRs (the default)
 watch:
+  issue_provider: github     # default
+  code_host: github          # default
   repo: owner/name
   label_prefix: spf          # polls issues labeled spf:ready
   chain: plan-build-test     # any registered chain
@@ -232,31 +255,68 @@ watch:
   concurrency: 2
 ```
 
+```yaml
+# .spf/spf.config.yaml — Jira issues + Bitbucket PRs
+watch:
+  issue_provider: jira
+  code_host: bitbucket
+  repo: workspace/repo_slug  # Bitbucket's own two-part identifier
+  label_prefix: spf          # polls Jira issues labeled spf:ready
+  chain: plan-build-test
+  base_branch: main
+  jira:
+    base_url: https://your-domain.atlassian.net
+    project_key: PROJ
+```
+
 ```bash
-export GITHUB_TOKEN=...     # classic PAT — see "GITHUB_TOKEN scope" below; spf doctor checks it's set
-spf watch init                # idempotently create/update the 5 labels below — run this first
+spf watch init                # idempotently seed tracker state (no-op for Jira — see below); run this first
 spf watch                    # foreground daemon; Ctrl-C drains in-flight claims first
 spf watch --once             # one poll tick, then exit — good for cron
 spf watch --dry-run          # log intended claims/transitions, mutate nothing
 ```
 
-`spf watch init` seeds `<prefix>:ready`/`working`/`review`/`done`/`blocked` with a color and description each — safe to re-run any time (creates what's missing, corrects any that drifted, leaves the rest alone).
+No GitHub App, no webhook, no Jira/Bitbucket app install — it's a plain REST poll against whichever combination is configured, same philosophy as the trace db's own polling contract. See [`assets/templates/`](assets/templates/) for full worked configs (also usable directly via `spf init --template <name>`), and `spf install-skill`'s installed skill (`roster.md`, `references/config.md`) for the field-by-field reference.
 
-No GitHub App, no webhook — it's a plain REST poll, same philosophy as the trace db's own polling contract. See [`docs/examples/`](docs/examples/) for full worked configs, and `spf install-skill`'s installed skill (`roster.md`, `references/config.md`) for the field-by-field reference.
+### GitHub (`issue_provider: github` and/or `code_host: github`)
 
-### `GITHUB_TOKEN` scope
+```bash
+export GITHUB_TOKEN=...   # classic PAT; spf doctor checks it's set
+```
 
-A **classic** PAT (fine-grained tokens use different permission names — not covered here), scoped to the minimum that covers every call `spf watch`/`spf watch init` makes: creating/editing labels, reading and labeling issues, posting comments, opening PRs, and reading PR/check-run status.
+`spf watch init` seeds `<prefix>:ready`/`working`/`review`/`done`/`blocked` labels with a color and description each — safe to re-run any time (creates what's missing, corrects any that drifted, leaves the rest alone).
+
+A **classic** PAT (fine-grained tokens use different permission names — not covered here), scoped to the minimum that covers every call `spf watch`/`spf watch init` makes on GitHub: creating/editing labels, reading and labeling issues, posting comments, opening PRs, and reading PR/check-run status.
 
 | Target repo | Scope | Covers |
 |---|---|---|
 | Private | `repo` | Everything above, full read/write |
 | Public only | `public_repo` | The same, restricted to public repos |
 
-**Do not grant the `project` scope.** It's a separate, unrelated permission for GitHub Projects (classic/org/user boards) — `spf watch` doesn't touch Projects at all (deliberately out of scope for v1; see the label-based state machine above), so granting it would just be more access than this tool ever uses.
+**Do not grant the `project` scope.** It's a separate, unrelated permission for GitHub Projects (classic/org/user boards) — `spf watch` doesn't touch Projects at all, so granting it would just be more access than this tool ever uses.
 
 There's no dedicated "issues" or "pull requests" scope on classic PATs — GitHub bundles both into `repo`/`public_repo`, which is why that's the whole table.
 
+### Jira (`issue_provider: jira`)
+
+```bash
+export JIRA_EMAIL=you@example.com
+export JIRA_API_TOKEN=...   # id.atlassian.com -> Security -> API tokens
+```
+
+State is modeled as Jira **labels** (`<prefix>:ready`, etc.), mirroring GitHub exactly, rather than native workflow status transitions — the latter would need per-project transition-id mapping, since workflows vary by project/scheme; labels work identically everywhere with zero per-project setup. One caveat: colons are a legal Jira label character and JQL matches on them fine, but they won't show up in Jira's own label autocomplete UI — cosmetic only.
+
+`spf watch init` is a no-op here (Jira labels are freeform strings with no color/description registry to seed, unlike GitHub's) — it just reports the labels this run will use.
+
+### Bitbucket (`code_host: bitbucket`)
+
+```bash
+export BITBUCKET_EMAIL=you@example.com
+export BITBUCKET_API_TOKEN=...   # same Atlassian API token mechanism as Jira above
+```
+
+**Bitbucket Cloud app passwords are being fully removed** (brownout window closing July 28, 2026) — this project only supports the replacement, API tokens, which need the account's email alongside the token (username alone no longer works).
+
 ## What's in this repo
 
 ```

package/assets/skill/references/config.md

@@ -100,8 +100,9 @@ quality:
 ```
 
 A full worked example, including the `defaults.coding_agent`/`watch:`
-sections: `docs/examples/node-typescript.spf.config.yaml` in the spf
-repo (or wherever this skill's own package is installed from).
+sections: `assets/templates/ts.spf.config.yaml` in the spf package (or
+`spf init --template ts` to write it straight into `.spf/spf.config.yaml`).
+`spf init` with no `--template` prints every packaged template's name.
 
 ### `agents[]`
 

package/assets/templates/ts-cc.spf.config.yaml

@@ -0,0 +1,59 @@
+# .spf/spf.config.yaml — Claude Code backend, pointed at Ollama (local or
+# cloud) instead of Anthropic's API. `spf init --template ts-cc` writes
+# this file as-is.
+#
+# No spf-side config makes the Ollama redirect happen: `coding_agent:
+# claude_code` shells out to your own installed `claude` CLI, and Claude
+# Code's CLI itself reads ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN to
+# decide where to send requests. agent_cc.ts never special-cases this — it
+# just passes your shell's environment through unmodified to the `claude`
+# subprocess, the same way every other env var reaches an agent.
+#
+# Local Ollama, before running spf:
+#   ollama serve                          # if not already running
+#   ollama pull qwen3-coder:30b           # or whatever model you want
+#   export ANTHROPIC_BASE_URL=http://localhost:11434
+#   export ANTHROPIC_AUTH_TOKEN=ollama    # any non-empty value — local Ollama doesn't check it
+#
+# Ollama Cloud instead of a local server:
+#   export ANTHROPIC_BASE_URL=<your Ollama Cloud endpoint — see docs.ollama.com>
+#   export ANTHROPIC_AUTH_TOKEN=<a real Ollama Cloud API key>
+#
+# `spf doctor` checks that `claude` is on PATH and treats a missing
+# ANTHROPIC_API_KEY as informational (claude login is a valid alternative)
+# — it does NOT know about this redirect, so it won't tell you whether
+# ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN are actually set. Confirm those
+# yourself before a real run.
+#
+# `model:` becomes whatever model name your Ollama server actually serves
+# once redirected — not one of Claude Code's own aliases (sonnet/opus/...)
+# and not provider/model-id.
+quality:
+  checks:
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: lint, operation: lint, argv: ["npm", "run", "lint"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    test: [test]
+    all: [typecheck, lint, build, test]
+
+defaults:
+  coding_agent: claude_code
+  model: qwen3-coder:30b # swap for whatever `ollama list` shows on your machine
+
+# REQUIRED, not just an example: the packaged default roster pins
+# planner/reviewer/documenter to their own explicit Flue-style
+# provider/model-id strings, which an agent's own model always wins over
+# defaults.model above — switching coding_agent globally does NOT reset
+# those three, so they'd run on Claude Code (redirected at Ollama) with a
+# model id Ollama has never heard of, and fail outright. builder/scout
+# have no model of their own in the packaged roster, so they correctly
+# inherit defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: qwen3-coder:30b
+  - name: reviewer
+    model: qwen3-coder:30b
+  - name: documenter
+    model: qwen3-coder:30b

package/assets/templates/ts-flue-openrouter.spf.config.yaml

@@ -0,0 +1,53 @@
+# .spf/spf.config.yaml — Flue backend (the default), routed through
+# OpenRouter to a Kimi model. `spf init --template ts-flue-openrouter`
+# writes this file as-is.
+#
+# model: is ALWAYS provider/model-id for Flue — the string's first segment
+# names the provider, and that segment alone decides which env var gets
+# read for credentials. This resolution belongs to Flue's own underlying
+# `pi-ai` library, not to spf: agents.validate() only checks the STRING
+# SHAPE (does it look like provider/id, via agent_flue.ts's resolveModel())
+# — never that the provider is real or that its key is actually set. A
+# wrong provider name or a missing key only surfaces at the first real
+# dispatch, not at validate() time.
+#
+# `spf doctor` has its own small, hand-maintained table of common
+# providers' env-var conventions (src/cli/commands/doctor.ts) for an
+# informational check — pi-ai's real internal provider table isn't
+# exported for spf to read, so this is best-effort, not authoritative.
+# openrouter's own entry in that table: OPENROUTER_API_KEY.
+#
+# Before running spf:
+#   export OPENROUTER_API_KEY=sk-or-...
+quality:
+  checks:
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: lint, operation: lint, argv: ["npm", "run", "lint"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    test: [test]
+    all: [typecheck, lint, build, test]
+
+defaults:
+  coding_agent: flue
+  # Check openrouter.ai/models for the exact current id — "kimi-k2.7" here
+  # matches this project's existing fictional-model-version convention
+  # (kimi-k3, gemini-3.6, gpt-5.6, claude-sonnet-5, ...), not a live catalog
+  # entry verified against a real API.
+  model: openrouter/moonshotai/kimi-k2.7
+
+# Not required the way the claude_code templates' agents: override is (an
+# agent's own model always wins over defaults.model, but Flue accepts any
+# provider/model-id, so the packaged roster's planner/reviewer/documenter
+# — fireworks/openai models, unrelated to OpenRouter — would still resolve
+# and run fine, just outside OPENROUTER_API_KEY's reach). Overridden here
+# anyway so every agent actually demonstrates the OpenRouter routing this
+# template is about, not just the three without their own packaged model.
+agents:
+  - name: planner
+    model: openrouter/moonshotai/kimi-k2.7
+  - name: reviewer
+    model: openrouter/moonshotai/kimi-k2.7
+  - name: documenter
+    model: openrouter/moonshotai/kimi-k2.7

package/assets/templates/ts.spf.config.yaml

@@ -0,0 +1,66 @@
+# .spf/spf.config.yaml for a Node/TypeScript project — `spf init --template
+# ts` writes this file as-is; `spf init` with no --template seeds a starter
+# with the same shape, commented out. This fills it in with real commands
+# so `plan-build-test`/`plan-build-test-quality`/`quality`/`simple-sdlc` —
+# every chain with a REQUIRED_SUITES entry — actually have something to run
+# instead of failing loudly at validate() time.
+#
+# Adjust the argv to your own project: swap `npm` for `pnpm`/`yarn`, point
+# `build`/`typecheck` at whatever scripts you already have in package.json.
+quality:
+  checks:
+    # `operation` classifies the check for the trace/UI (lint | typecheck |
+    # build) — it doesn't have to literally match the argv. Running a test
+    # suite doesn't have its own operation value, so `build` is the closest
+    # fit; it doesn't change what actually runs.
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: lint, operation: lint, argv: ["npm", "run", "lint"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    # `test:` is what build-test/plan-build-test/simple-sdlc's bounded fix
+    # loop runs after every build. Keep it fast — it runs on every attempt.
+    test: [test]
+    # `all:` is what plan-build-test-quality/quality run — the full bar.
+    all: [typecheck, lint, build, test]
+
+# Optional: run agents on Claude Code instead of the default Flue backend.
+# Needs the `claude` CLI installed and authenticated (`spf doctor` checks) —
+# no separate provider API key required if you're logged in via `claude
+# login`. Remove this whole block (and the agents: override below) to stay
+# on Flue with a `provider/model-id` roster instead.
+defaults:
+  coding_agent: claude_code
+  model: sonnet # claude_code's own alias — NOT provider/model-id
+
+# REQUIRED alongside coding_agent: claude_code above, not just an example:
+# the packaged default roster pins planner/reviewer/documenter to their own
+# explicit Flue-style provider/model-id strings, which an agent's own model
+# always wins over defaults.model — switching coding_agent globally does
+# NOT reset those three, so they'd run on Claude Code with a model id it
+# can't resolve at all ("There's an issue with the selected model...").
+# builder/scout have no model of their own in the packaged roster, so they
+# correctly inherit defaults.model above and need no override here.
+agents:
+  - name: planner
+    model: sonnet
+  - name: reviewer
+    model: sonnet
+  - name: documenter
+    model: sonnet
+
+# Optional: retune one agent further without touching the rest of the roster.
+#   - name: builder
+#     thinking: high
+#     writes: [src/, tests/]   # narrow what this agent may change in the repo
+
+# Optional: poll an issue tracker's `spf:ready`-labeled issues and run a
+# chain against each — see the main README's "spf watch" section for every
+# issue_provider x code_host combination's env vars and required scopes
+# (GitHub, or Jira issues against a Bitbucket repo, or any mix).
+# Needs a GITHUB_TOKEN env var (classic PAT, repo scope) for the defaults below.
+# watch:
+#   repo: owner/name
+#   label_prefix: spf
+#   chain: plan-build-test
+#   base_branch: main

package/dist/cli/commands/doctor.js

@@ -143,10 +143,26 @@ export function doctorCommand(argv) {
         check(report, `${envFile}`, true, existsSync(p) ? `present (${statSync(p).size} bytes)` : "absent — fine if no provider needs a key from it");
     }
     if (cfg.watch.repo.trim()) {
-        check(report, "watch.provider", cfg.watch.provider === "github", cfg.watch.provider);
-        check(report, "GITHUB_TOKEN", Boolean(process.env["GITHUB_TOKEN"]), process.env["GITHUB_TOKEN"]
-            ? "set"
-            : 'not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo); see README.md\'s "GITHUB_TOKEN scope" section');
+        check(report, "watch.issue_provider", true, cfg.watch.issue_provider);
+        check(report, "watch.code_host", true, cfg.watch.code_host);
+        if (cfg.watch.issue_provider === "github" || cfg.watch.code_host === "github") {
+            check(report, "GITHUB_TOKEN", Boolean(process.env["GITHUB_TOKEN"]), process.env["GITHUB_TOKEN"]
+                ? "set"
+                : 'not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo); see README.md\'s "GITHUB_TOKEN scope" section');
+        }
+        if (cfg.watch.issue_provider === "jira") {
+            check(report, "watch.jira", Boolean(cfg.watch.jira.base_url.trim() && cfg.watch.jira.project_key.trim()), cfg.watch.jira.base_url.trim() && cfg.watch.jira.project_key.trim()
+                ? `${cfg.watch.jira.base_url} (${cfg.watch.jira.project_key})`
+                : "watch.jira.base_url and watch.jira.project_key must both be set");
+            check(report, "JIRA_EMAIL / JIRA_API_TOKEN", Boolean(process.env["JIRA_EMAIL"] && process.env["JIRA_API_TOKEN"]), process.env["JIRA_EMAIL"] && process.env["JIRA_API_TOKEN"]
+                ? "set"
+                : 'not set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens); see README.md\'s "spf watch" section');
+        }
+        if (cfg.watch.code_host === "bitbucket") {
+            check(report, "BITBUCKET_EMAIL / BITBUCKET_API_TOKEN", Boolean(process.env["BITBUCKET_EMAIL"] && process.env["BITBUCKET_API_TOKEN"]), process.env["BITBUCKET_EMAIL"] && process.env["BITBUCKET_API_TOKEN"]
+                ? "set"
+                : 'not set — Bitbucket app passwords are being removed; spf watch needs an Atlassian account email plus an API token instead; see README.md\'s "spf watch" section');
+        }
         check(report, "watch.chain", Boolean(findChain(cfg.watch.chain)), findChain(cfg.watch.chain) ? cfg.watch.chain : `"${cfg.watch.chain}" is not a registered chain`);
     }
     return finish(report, flags["json"]);

package/dist/cli/commands/init.js

@@ -1,9 +1,28 @@
 /** `spf init` — seed a `.spf/` override directory. Everything else is inherited from the packaged defaults. */
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import * as paths from "../../core/paths.js";
 import { ensureGitignore } from "../gitignore.js";
 import { parseCli } from "../../core/utils.js";
+import { paint } from "../../core/console.js";
+const TEMPLATE_SUFFIX = ".spf.config.yaml";
+/** Every template's short name (e.g. "ts-cc"), derived from disk rather than hand-maintained — never drifts from what's actually packaged. */
+function listTemplates() {
+    if (!existsSync(paths.TEMPLATES_DIR))
+        return [];
+    return readdirSync(paths.TEMPLATES_DIR)
+        .filter((f) => f.endsWith(TEMPLATE_SUFFIX))
+        .map((f) => f.slice(0, -TEMPLATE_SUFFIX.length))
+        .sort();
+}
+function loadTemplate(name) {
+    const templatePath = path.join(paths.TEMPLATES_DIR, `${name}${TEMPLATE_SUFFIX}`);
+    if (!existsSync(templatePath)) {
+        const available = listTemplates();
+        throw new Error(`unknown template ${JSON.stringify(name)} — available: ${available.length > 0 ? available.join(", ") : "(none packaged)"}`);
+    }
+    return readFileSync(templatePath, "utf-8");
+}
 const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packaged built-in defaults.
 # List only what you want to CHANGE; everything else (the roster, prompts,
 # models) is inherited. Run \`spf doctor\` any time to see what's actually in
@@ -25,15 +44,28 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #     model: anthropic/claude-sonnet-4-6
 #     coding_agent: claude_code   # run this agent on Claude Code instead of Flue
 #     model: sonnet               # claude_code's own alias, NOT provider/model-id
+#
+# Switching coding_agent globally, in defaults: above, instead of per-agent?
+# The packaged default roster pins planner/reviewer/documenter to their own
+# explicit Flue-style provider/model-id strings, and an agent's own model
+# always wins over defaults.model — so those three keep running on whatever
+# backend you just switched to, with a model id it can't resolve, unless
+# you override their model here too (builder/scout have no model of their
+# own in the packaged roster, so they need no override). See
+# assets/templates/ts.spf.config.yaml (or --template ts) for the full
+# working pattern.
 
-# Uncomment to enable \`spf watch\` — polls GitHub issues labeled
+# Uncomment to enable \`spf watch\` — polls an issue tracker labeled
 # <label_prefix>:ready and runs \`chain\` against each in its own worktree.
-# Needs a GITHUB_TOKEN env var: a classic PAT with repo scope (or public_repo
-# for a public-only repo) — never the project scope, which is unrelated and
-# unused here. See README.md's "GITHUB_TOKEN scope" section. \`spf doctor\`
-# checks it's set.
+# issue_provider and code_host default to "github" and are independent —
+# a Jira tracker against a Bitbucket repo is just issue_provider: jira +
+# code_host: bitbucket + a watch.jira: {base_url, project_key} block. See
+# README.md's "spf watch" section for every combination's env vars and
+# required scopes. \`spf doctor\` checks whatever this resolves to.
 # watch:
-#   repo: owner/name
+#   issue_provider: github   # github | jira
+#   code_host: github        # github | bitbucket
+#   repo: owner/name          # "owner/name" (github) or "workspace/repo_slug" (bitbucket)
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
@@ -44,7 +76,7 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 // (engine/, from `spf eject`), and secrets (.env).
 const GITIGNORE_ENTRIES = [".spf/data/", ".spf/engine/", ".env"];
 export function initCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd"], ["force"]);
+    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
     const sfDir = path.join(anchor.repo_root, ".spf");
     mkdirSync(sfDir, { recursive: true });
@@ -53,10 +85,17 @@ export function initCommand(argv) {
         console.log(`${configPath} already exists — leaving it alone (--force to overwrite)`);
     }
     else {
-        writeFileSync(configPath, STARTER_CONFIG);
-        console.log(`wrote ${configPath}`);
+        const templateName = options["template"];
+        const content = templateName ? loadTemplate(templateName) : STARTER_CONFIG;
+        writeFileSync(configPath, content);
+        console.log(`wrote ${configPath}${templateName ? ` (from template "${templateName}")` : ""}`);
     }
     ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
+    const templates = listTemplates();
+    if (templates.length > 0) {
+        console.log(`templates available via --template: ${templates.join(", ")}`);
+    }
     console.log(`\nnext: spf doctor   (confirm everything resolves), then spf scout "describe this repo"`);
+    console.log(paint("yellow", `warning: spf ui reads .spf/data/spf.db, which doesn't exist until a run creates it — run spf scout (or any chain) at least once before spf ui.`));
     return 0;
 }

package/dist/cli/commands/watch.js

@@ -5,40 +5,79 @@
  * actual state machine; this file is just the wiring: config, the GitHub
  * provider, the chain-dispatch callback, the lockfile, and the CLI loop.
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import * as agents from "../../core/agents.js";
 import * as paths from "../../core/paths.js";
 import { isRepoAt, makeGit } from "../../core/git_helper.js";
 import { GitHubProvider } from "../../core/issues/github_provider.js";
+import { JiraProvider } from "../../core/issues/jira_provider.js";
+import { BitbucketProvider } from "../../core/issues/bitbucket_provider.js";
 import { createWatchState, tick } from "../../core/watch.js";
 import { findChain } from "../../chains/index.js";
 import { SfDb } from "../../ui/server/db.js";
 import { parseCli } from "../../core/utils.js";
 /**
- * Shared by `watch` and `watch init`: resolve config and build the
- * provider, checking only what BOTH need — a supported provider, a
- * non-empty `watch.repo`, and `GITHUB_TOKEN`. `watch`'s own extra checks
- * (a real git repo, a registered chain) don't apply to seeding labels.
- * Prints its own error and returns `null` on failure — the caller just
- * needs to `return 1`.
+ * Shared by `watch` and `watch init`: resolve config into an `IssueProvider`
+ * — checking only what BOTH need. `watch`'s own extra checks (a real git
+ * repo, a registered chain) don't apply to seeding labels. Prints its own
+ * error and returns `null` on failure — the caller just needs to `return 1`.
  */
-function resolveWatchProvider(cfg) {
-    if (cfg.watch.provider !== "github") {
-        console.error(`watch.provider ${JSON.stringify(cfg.watch.provider)} is not supported`);
-        return null;
+function resolveIssueProvider(cfg) {
+    if (cfg.watch.issue_provider === "github") {
+        if (!cfg.watch.repo.trim()) {
+            console.error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+            return null;
+        }
+        const token = process.env["GITHUB_TOKEN"];
+        if (!token) {
+            console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
+            return null;
+        }
+        return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
     }
+    if (cfg.watch.issue_provider === "jira") {
+        if (!cfg.watch.jira.base_url.trim() || !cfg.watch.jira.project_key.trim()) {
+            console.error(`watch.jira.base_url and watch.jira.project_key must both be set when watch.issue_provider is "jira"`);
+            return null;
+        }
+        const email = process.env["JIRA_EMAIL"];
+        const token = process.env["JIRA_API_TOKEN"];
+        if (!email || !token) {
+            console.error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — spf watch needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens). See README.md\'s "spf watch" section.');
+            return null;
+        }
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token);
+    }
+    console.error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} is not supported`);
+    return null;
+}
+/** Same shape as `resolveIssueProvider`, for `watch.code_host`. */
+function resolveCodeHostProvider(cfg) {
     if (!cfg.watch.repo.trim()) {
-        console.error(`watch.repo is not configured — add it to spf.config.yaml's watch: section, e.g. "owner/name"`);
+        console.error(`watch.repo is not configured — add it to spf.config.yaml's watch: section`);
         return null;
     }
-    const token = process.env["GITHUB_TOKEN"];
-    if (!token) {
-        console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
-        return null;
+    if (cfg.watch.code_host === "github") {
+        const token = process.env["GITHUB_TOKEN"];
+        if (!token) {
+            console.error('GITHUB_TOKEN is not set — spf watch needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo). See README.md\'s "GITHUB_TOKEN scope" section.');
+            return null;
+        }
+        return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+    }
+    if (cfg.watch.code_host === "bitbucket") {
+        const email = process.env["BITBUCKET_EMAIL"];
+        const token = process.env["BITBUCKET_API_TOKEN"];
+        if (!email || !token) {
+            console.error('BITBUCKET_EMAIL and BITBUCKET_API_TOKEN must both be set — spf watch needs an Atlassian account email plus an API token (Bitbucket app passwords are being removed; API tokens are the replacement). See README.md\'s "spf watch" section.');
+            return null;
+        }
+        return new BitbucketProvider(cfg.watch.repo, email, token);
     }
-    return new GitHubProvider(cfg.watch.repo, cfg.watch.label_prefix, token);
+    console.error(`watch.code_host ${JSON.stringify(cfg.watch.code_host)} is not supported`);
+    return null;
 }
 function isPidAlive(pid) {
     try {
@@ -78,11 +117,11 @@ export async function watchInitCommand(argv) {
     const { options } = parseCli(argv, ["cwd", "config"], []);
     const anchor = paths.resolveAnchor(options["cwd"]);
     const cfg = agents.loadConfig(paths.resolveConfigPaths(anchor, options["config"]).paths);
-    const provider = resolveWatchProvider(cfg);
+    const provider = resolveIssueProvider(cfg);
     if (!provider)
         return 1;
     const result = await provider.ensureLabels();
-    console.log(`spf watch init: ${cfg.watch.repo} (label prefix "${cfg.watch.label_prefix}")`);
+    console.log(`spf watch init: ${cfg.watch.issue_provider} (label prefix "${cfg.watch.label_prefix}")`);
     for (const name of result.created)
         console.log(`  + ${name} (created)`);
     for (const name of result.updated)
@@ -96,9 +135,12 @@ export async function watchCommand(argv) {
     const anchor = paths.resolveAnchor(options["cwd"]);
     const configPaths = paths.resolveConfigPaths(anchor, options["config"]).paths;
     const cfg = agents.loadConfig(configPaths);
-    const provider = resolveWatchProvider(cfg);
+    const provider = resolveIssueProvider(cfg);
     if (!provider)
         return 1;
+    const codeHost = resolveCodeHostProvider(cfg);
+    if (!codeHost)
+        return 1;
     if (!isRepoAt(anchor.repo_root)) {
         console.error(`${anchor.repo_root} is not a git repository`);
         return 1;
@@ -119,6 +161,27 @@ export async function watchCommand(argv) {
     const git = makeGit(anchor.repo_root);
     const worktreesDir = path.join(homedir(), ".spf", "watch", path.basename(anchor.repo_root), "worktrees");
     mkdirSync(worktreesDir, { recursive: true });
+    /**
+     * Without this, a claimed issue's chain resolves its session/trace data
+     * relative to `cwd` (the worktree, not the main repo — see
+     * ChainContext's doc comment), so it lands in a fresh `.spf/data` that
+     * `cleanupWorktree` deletes along with the rest of the worktree once the
+     * issue finishes: invisible in `spf ui` while running, and gone entirely
+     * afterward. Symlinking `.spf/data` in the worktree to the main repo's
+     * own `dataPaths.data_dir` makes every claimed issue show up in the same
+     * `spf ui` you already have open, and survive worktree cleanup. Multiple
+     * concurrent worktrees writing through the same symlink to one sqlite
+     * file is exactly what tracer.ts's WAL + busy_timeout=5000 already exist
+     * for. Idempotent: a no-op if the worktree already has a `.spf/data`
+     * (e.g. resuming an orphaned worktree).
+     */
+    function linkDataDir(worktreePath) {
+        const target = path.join(worktreePath, ".spf", "data");
+        if (existsSync(target))
+            return;
+        mkdirSync(path.dirname(target), { recursive: true });
+        symlinkSync(dataPaths.data_dir, target, "dir");
+    }
     const runChain = async (opts) => {
         const chainDef = findChain(cfg.watch.chain); // checked above
         const ctx = { prompt: opts.prompt, config_paths: configPaths, adw_id: opts.adwId, cwd: opts.cwd };
@@ -141,6 +204,7 @@ export async function watchCommand(argv) {
     };
     const deps = {
         provider,
+        codeHost,
         git,
         worktreeGit: makeGit,
         labelPrefix: cfg.watch.label_prefix,
@@ -148,6 +212,7 @@ export async function watchCommand(argv) {
         baseBranch: cfg.watch.base_branch,
         concurrency: cfg.watch.concurrency,
         worktreesDir,
+        linkDataDir,
         dryRun: Boolean(flags["dry-run"]),
         runChain,
         log: (message) => console.log(message),
@@ -184,7 +249,7 @@ export async function watchCommand(argv) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
-    console.log(`[spf] watch     ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}${flags["dry-run"] ? "  (dry run)" : ""}`);
+    console.log(`[spf] watch     ${cfg.watch.issue_provider}+${cfg.watch.code_host}  ${cfg.watch.repo}  label "${cfg.watch.label_prefix}:*"  chain "${cfg.watch.chain}"  concurrency ${cfg.watch.concurrency}${flags["dry-run"] ? "  (dry run)" : ""}`);
     try {
         for (;;) {
             await tick(deps, state);