@gr8ful/spf 0.3.0 → 0.4.0

package/README.md

@@ -15,7 +15,7 @@ Everyone can get an agent to write code once. Almost nobody gets the same result
 npm i -g @gr8ful/spf
 ```
 
-No Bun, no separate coding-agent binary to install first, no template stamped into your repo. `spf` ships with a packaged default agent roster and default prompts — it runs against any repo with zero setup, and only writes files into that repo if you explicitly ask it to (`spf init`, `spf install-skill`).
+No Bun, no separate coding-agent binary to install first, no template stamped into your repo. `spf` ships with a packaged default agent roster and default prompts — it runs against any repo with zero setup, and only writes files into that repo if you explicitly ask it to (`spf init`, which also installs the Claude Code skill unless you pass `--no-skills`; `spf install-skill` does just the skill by hand).
 
 ```bash
 cd your-repo
@@ -38,6 +38,8 @@ On a real terminal, `spf init` asks a short interview — which coding agent (`c
 
 Without an interview, `spf init` writes the same small starter `.spf/spf.config.yaml`, commented, that merges on top of the packaged built-ins field by field. `--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.
 
+Every `spf init` run — interview or not — also installs the repo-local Claude Code skill (`.claude/skills/spf`), the same work `spf install-skill` does by hand: pass `--no-skills` to skip it. It's idempotent (a no-op once the skill is already current, and writes a `.new` sibling instead of overwriting a file you've locally edited), so re-running `spf init` never clobbers anything there. `spf install-skill --user` (installing to `~/.claude/skills/spf` instead) is still its own separate invocation.
+
 ### Local development
 
 Working from a clone instead of the published package:
@@ -108,7 +110,7 @@ agents:
     writes: [specs/]                 # the plan is all it may leave in the repo
 ```
 
-Five starter agents ship in the box: `planner`, `builder`, `scout` (read-only recon), `reviewer`, and `documenter`. There is no tester, because running a suite is a known command and therefore code, not an agent's job.
+Six starter agents ship in the box: `planner`, `builder`, `scout` (read-only recon), `refiner` (decomposes a product spec for `spf watch`'s refine lane — see "`spf watch`" below), `reviewer`, and `documenter`. There is no tester, because running a suite is a known command and therefore code, not an agent's job.
 
 Every agent gets its own model, thinking level, prompts, and tools. Give the planner a frontier model and the builder a cheap fast one. Give the reviewer no ability to write code at all.
 
@@ -243,6 +245,8 @@ spf build-test "implement the plan" --adw-id a1b2c3d4
 
 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`.
 
+A second, optional lane (`watch.refine`, off by default) decomposes a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues instead — see "Refining specs" below.
+
 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.
 
 The easiest way into any of this is `spf init`'s interview: it asks whether to enable `spf watch`, which tracker and code host, and collects exactly the env vars that combination needs (below) straight into `.env` — no hand-editing YAML or hunting down which credential pair a given combination wants.
@@ -283,15 +287,61 @@ spf watch --dry-run          # log intended claims/transitions, mutate nothing
 
 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.
 
+### Refining specs (`watch.refine`)
+
+A product spec isn't individually workable — it needs to become a feature,
+broken down into user stories and bugs, before the build lane above has
+anything to claim. `watch.refine` is a second lane over the same poll loop
+that does exactly that: it polls `<prefix>:spec-ready`, runs a decomposition
+chain (`refine` by default) against the spec in its own worktree, and
+publishes what it produces as real tracker issues — a feature/epic container
+plus story/bug/task leaves, linked via GitHub's native sub-issue hierarchy.
+
+```yaml
+watch:
+  issue_provider: github    # required — issue authoring isn't implemented for Jira yet
+  repo: owner/name
+  refine:
+    enabled: true
+    chain: refine           # any chain that ends in steps.publishIssues()
+    concurrency: 1          # this lane's own budget, independent of watch.concurrency
+```
+
+Every generated issue carries a `<prefix>:type:epic|feature|story|bug|task`
+label. A container (a feature/epic — something else names it as `parent`)
+gets only that label; a leaf additionally gets `<prefix>:refined` — **never**
+`<prefix>:ready`. Promoting a leaf to `<prefix>:ready` is a deliberate human
+decision: the refine lane never auto-promotes anything, so a spec fanning out
+into twenty stories doesn't turn into twenty unattended chain runs and twenty
+PRs with nobody having looked at the breakdown first. Once you do promote a
+leaf, the existing build lane picks it up completely unchanged.
+
+The spec issue itself gets a `spec-ready → refining → done`/`blocked`
+lifecycle, same shape as the build lane, and a summary comment listing every
+issue it created. Try it by hand first, against a real spec, before turning
+on the daemon:
+
+```bash
+spf refine "<spec text or path/to/spec.md>" --issue 42   # --issue renders a "## Parent: #42" back-reference
+```
+
+`spf watch init` seeds the type labels alongside the state ones. This lane's
+prompt (`assets/prompts/refiner/`) is adapted from a "tracer-bullet ticket"
+decomposition skill — vertical slices, a `blocked_by` dependency graph, and
+an expand/migrate/contract sequence for wide mechanical refactors — with a
+gate (`gates.refinementWellFormed`) added on top to enforce the
+container/leaf shape that skill left as prose convention rather than a
+checked rule.
+
 ### GitHub (`issue_provider: github` and/or `code_host: github`)
 
 ```bash
 export GITHUB_TOKEN=...   # classic PAT; spf doctor checks it's set
 ```
 
-`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).
+`spf watch init` seeds `<prefix>:ready`/`working`/`review`/`done`/`blocked`/`spec-ready`/`refining`/`refined` labels, plus `<prefix>:type:epic`/`feature`/`story`/`bug`/`task` (used by the refine lane whether or not it's enabled), each with a color and description — 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.
+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, reading PR/check-run status, and — with `watch.refine.enabled` — creating issues and linking them via the sub-issues API. All of it is already covered by `repo`/`public_repo`; refine needs no additional scope.
 
 | Target repo | Scope | Covers |
 |---|---|---|
@@ -385,7 +435,7 @@ super-portable-software-factory/
 └── assets/
     ├── defaults/    # the packaged default roster
     ├── prompts/     # default system.md + user.md per starter agent
-    └── skill/       # an optional Claude Code skill — `spf install-skill` to use it
+    └── skill/       # a Claude Code skill — `spf init` installs it by default (`--no-skills` to opt out), or `spf install-skill` by hand
 ```
 
 There's no template stamped into your repo. Everything above ships inside the installed npm package; a repo you run `spf` against only ever gains a `.spf/` directory, and only if you ask for one.

package/assets/defaults/spf.config.yaml

@@ -101,6 +101,22 @@ agents:
   # No tester agent: running the suite is a known command, so it is a kind="code"
   # phase over core/quality.ts. See SKILL.md hard rule 8.
 
+  - name: refiner
+    thinking: high
+    color: "#34d399"
+    purpose: Decompose a product spec into a feature/story-or-bug tree of vertical slices; change nothing.
+    prompt_engineering:
+      system: refiner/system.md
+      user: refiner/user.md
+    writes: []                     # read-only w.r.t. the repo; refine_plan.md lands in context_handoff_dir, not here
+    tools:                         # full recon; write only for refine_plan.md, no edit
+      - read
+      - grep
+      - find
+      - ls
+      - bash
+      - write
+
   - name: reviewer
     model: openai/gpt-5.6-terra
     thinking: high

package/assets/prompts/refiner/system.md

@@ -0,0 +1,53 @@
+# Refiner Agent
+
+## Purpose
+
+Decompose a product spec into a feature/story-or-bug tree of vertical slices the factory can build one at a time. Change nothing.
+
+## Instructions
+
+- Read-only: explore the codebase to ground the decomposition, never write to it.
+- Use the project's domain glossary vocabulary in every title and description, if the repo has one. Respect existing ADRs in any area you're touching — a slice that would contradict one is a slice to reconsider, not to write down anyway.
+- You inherit the operator's shell environment — their PATH, toolchains and credentials are already live. Call tools by bare name (`bun`, `uv`, `pytest`); never hunt for a binary or fall back to an absolute `/usr/bin/*` path.
+- Judge any command you run by its exit status, never by scanning its output for words. `error` or `not found` inside passing output is text, not a failure.
+- Write your working notes to `<context_handoff_dir>/refine_plan.md` before emitting your Report JSON.
+
+## The tree
+
+Every node you produce is either a **container** (`epic` or `feature` — exists only to group other nodes; never itself a unit of work) or a **leaf** (`story`, `bug`, or `task` — the independently workable unit). A node is a container exactly when some other node names it as `parent`; everything else is a leaf. At least one leaf is required — a decomposition that is all containers has produced nothing to build.
+
+Emit a **flat list**, not nested JSON: each node names its `parent` by another node's `key`, or leaves `parent` empty for a top-level feature/epic. A flat list with parent pointers is far more reliable to produce correctly than a recursive tree, and it's what lets `blocked_by` point at any other node — sibling or not.
+
+## Vertical-slice rules (for every leaf)
+
+- Each slice cuts a narrow but COMPLETE path through every layer it touches (schema, API, UI, tests) — vertical, never a horizontal slice of one layer.
+- A completed slice is demoable or verifiable on its own.
+- Size each slice to fit in a single fresh context window for the builder that will implement it — when in doubt, split.
+- Any prefactoring the spec implies should be its own slice, sequenced first via `blocked_by`, not folded into the first "real" slice.
+
+## Dependencies: a DAG, not a tree
+
+Give every node its `blocked_by`: the other nodes' `key`s that must land first. A node with no blockers can start immediately — leave `blocked_by` empty rather than inventing an order where none is required. The factory works the **frontier**: any leaf whose blockers are all done. For a purely linear chain that means top to bottom; for anything wider, only real dependencies belong in `blocked_by` — an artificial one just stalls the frontier.
+
+## Wide refactors — the one exception to vertical slicing
+
+A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose blast radius fans across the codebase, so a single edit breaks thousands of call sites and no vertical slice can land green on its own. Sequence it as **expand -> migrate -> contract**, each stage its own leaf(s):
+
+- **expand**: add the new form beside the old so nothing breaks yet.
+- **migrate**: batch the call sites by blast radius (per package, per directory) — each batch its own leaf, `blocked_by` the expand leaf. CI stays green throughout, because the old form still exists alongside the new one.
+- **contract**: delete the old form — `blocked_by` every migrate batch.
+
+If even a batch can't stay green alone, keep the same three-stage sequence but let the migrate batches share an integration branch that all block a final integrate-and-verify leaf — green is promised only there, not at every batch.
+
+## Writing titles and bodies
+
+- Title and body describe end-to-end behavior from the user's (or the next engineer's) perspective — not a layer-by-layer implementation list.
+- Avoid specific file paths or code snippets; they go stale fast. Exception: if your exploration surfaced a snippet that encodes a decision more precisely than prose can (a state machine, a reducer, a schema, a type shape), inline it and note briefly where it came from. Trim to the decision-rich part, not a working demo.
+- Do **not** write a "Blocked by" or "Parent" section into `body` yourself — the harness renders both from `blocked_by`/the source issue automatically, with real issue numbers once everything is created. Writing your own would go stale or duplicate the real one.
+- `body` should read as `## What to build` followed by `## Acceptance criteria` (a checklist).
+
+## Subagents
+
+`subagent_create` / `_continue` / `_list` / `_remove` fan out exploration — one per subsystem or open question — when the spec spans more than you can read cheaply. Give each a self-contained task, hold it to read-only work, and omit `model`.
+
+They run in the background. **Wait for every one you spawned to report before writing `refine_plan.md` or your Report JSON.** Skip them when a few reads would do.

package/assets/prompts/refiner/user.md

@@ -0,0 +1,70 @@
+# Refine Task
+
+## Variables
+
+### prompt
+
+{{prompt}}
+
+### previous_envelope
+
+{{previous_envelope}}
+
+### context_handoff_dir
+
+{{context_handoff_dir}}
+
+## Task
+
+Decompose the product spec in `prompt` into a feature/story-or-bug tree, following every rule in your system instructions (vertical slices, the `blocked_by` DAG, expand/migrate/contract for wide refactors, no "Blocked by"/"Parent" text of your own).
+
+1. Explore the codebase only as far as you need to ground the decomposition in what actually exists.
+2. Write your working notes to `<context_handoff_dir>/refine_plan.md`.
+3. Emit your `Report` JSON, declaring that one file in `artifacts`.
+
+## Report
+
+Respond with ONLY valid JSON matching `RefineOutput` — no prose before or after:
+
+```json
+{
+  "status": "success",
+  "summary": "<one sentence: how many features and how many leaves, and the shape of the dependency chain>",
+  "artifacts": ["<context_handoff_dir>/refine_plan.md"],
+  "notes_for_next_agent": "<anything the publish step or a human reviewer should know>",
+  "issues": [
+    {
+      "key": "F1",
+      "kind": "feature",
+      "title": "<feature title>",
+      "body": "## What to build\n\n<end-to-end behavior this feature covers>\n\n## Acceptance criteria\n\n- [ ] <criterion>",
+      "parent": "",
+      "blocked_by": []
+    },
+    {
+      "key": "S1",
+      "kind": "story",
+      "title": "<leaf title>",
+      "body": "## What to build\n\n<end-to-end behavior from the user's perspective>\n\n## Acceptance criteria\n\n- [ ] <criterion>\n- [ ] <criterion>",
+      "parent": "F1",
+      "blocked_by": []
+    },
+    {
+      "key": "S2",
+      "kind": "bug",
+      "title": "<leaf title>",
+      "body": "## What to build\n\n<the fix, described end-to-end>\n\n## Acceptance criteria\n\n- [ ] <criterion>",
+      "parent": "F1",
+      "blocked_by": ["S1"]
+    }
+  ]
+}
+```
+
+Rules on the shape (enforced by a gate — a violation sends this back to you as a correction, not a silent acceptance):
+
+- `key` is your own local id for this run, unique within `issues` — never a real tracker id.
+- A node is a **container** (`kind: "epic"` or `"feature"`) exactly when some other node names it in `parent`; every other node is a **leaf** (`kind: "story"`, `"bug"`, or `"task"`) and must not be a container. At least one leaf is required.
+- `parent` is another node's `key`, or `""` for a top-level feature/epic.
+- `blocked_by` is a list of other nodes' `key`s — real dependencies only, and no cycles (through `parent` or `blocked_by`, or both together).
+- `body` is `## What to build` then `## Acceptance criteria` only — no "Blocked by" or "Parent" section; those are rendered for you once every node has a real issue number.

package/assets/skill/references/config.md

@@ -108,9 +108,45 @@ 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.
 
-### `notifications`
+### `watch`
+
+Full mechanism: the main README's "`spf watch`" section. Field reference:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `issue_provider` | `"github"` \| `"jira"` | The tracker `spf watch` polls. Default `github`. |
+| `code_host` | `"github"` \| `"bitbucket"` | Where PRs open — independent of `issue_provider` (Jira issues against a Bitbucket repo is a real setup). Default `github`. |
+| `repo` | string | Required once watch is actually run (not schema-validated — fails loudly at `spf watch` startup instead). `"owner/name"` for `code_host: github`, `"workspace/repo_slug"` for `code_host: bitbucket`. |
+| `label_prefix` | string | State-machine label prefix — polls/writes `<prefix>:ready`, `<prefix>:working`, etc. Default `spf`. |
+| `chain` | string | Which registered chain runs per claimed `<prefix>:ready` issue. Default `plan-build-test`. |
+| `base_branch` | string | Branch worktrees fork from and PRs target. Default `main`. |
+| `poll_ms` | int | Tick interval. Default `60000`. |
+| `concurrency` | int ≥1 | Max issues claimed and run at once, the build lane's own budget (independent of `refine.concurrency`). Default `2`. |
+| `jira.base_url` / `jira.project_key` | string | Only consulted when `issue_provider: jira`. |
+| `refine.enabled` | bool | Turns on the second lane: decompose a `<prefix>:spec-ready` product spec into a feature/story-or-bug tree of real issues, instead of running `chain` against it directly (a spec isn't individually workable). Default `false` — off by default, so an existing `watch:` config is unaffected by upgrading. Needs `issue_provider: github` — `spf watch` fails loudly at startup otherwise, since issue authoring (create + link a hierarchy) isn't implemented for Jira yet. |
+| `refine.chain` | string | Which registered chain runs per claimed spec. Default `refine`. |
+| `refine.concurrency` | int ≥1 | The refine lane's own budget, separate from `concurrency`. Default `1`. |
+
+```yaml
+watch:
+  repo: owner/name
+  label_prefix: spf
+  chain: plan-build-test
+  refine:
+    enabled: true       # decompose spf:spec-ready specs into a feature/story tree
+    chain: refine
+    concurrency: 1
+```
+
+Generated issues carry a second, independent label vocabulary —
+`<prefix>:type:epic|feature|story|bug|task` — seeded by `spf watch init`
+alongside the state labels. A feature/epic (a container: some other node
+names it as `parent`) gets only its type label; a leaf (story/bug/task)
+additionally gets `<prefix>:refined`, so a human can review and promote it to
+`<prefix>:ready` when it's worth building — the refine lane never
+auto-promotes anything.
+
 
-Optional outbound push for unattended work — `spf watch`'s daemon lifecycle,
 and every chain run (`spf <chain>` / `spf run`, including watch's own
 per-issue runs). Interactive commands (`doctor`, `list`, `sessions`,
 `phases`, `events`, `init`, `ui`, `migrate`, `eject`, `abort`, `version`)

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

@@ -47,9 +47,9 @@ defaults:
 # 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.
+# model id Ollama has never heard of, and fail outright. builder/scout/
+# refiner 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

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

@@ -39,8 +39,8 @@ defaults:
 # 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.
+# builder/scout/refiner 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
@@ -64,6 +64,14 @@ agents:
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+#   # Optional second lane: decompose a spf:spec-ready product spec into a
+#   # feature/story-or-bug tree of real issues instead of building it
+#   # directly. Off by default; needs issue_provider: github (the default
+#   # above) — issue authoring isn't implemented for Jira yet.
+#   refine:
+#     enabled: true
+#     chain: refine
+#     concurrency: 1
 
 # Optional: push notifications for unattended work — spf watch's daemon
 # lifecycle, and every chain run (including watch's own per-issue runs).

package/dist/chains/context.d.ts

@@ -18,4 +18,13 @@ export interface ChainContext {
     cwd: string;
     /** The CLI name (`"plan-build-test"`), for session.ensure()'s trace record — see core/session.ts. */
     chain_name: string;
+    /**
+     * The originating tracker issue's id, only meaningful to the `refine`
+     * chain — `steps.publishIssues()` renders it as a `## Parent: #<id>`
+     * back-reference on every issue it creates (`core/refine.ts`'s
+     * `renderBody`). `null`/omitted for a manual run with no source issue
+     * (a bare `spf refine "<spec text>"`, no `--issue`). Every other chain
+     * ignores this field.
+     */
+    issue_id?: string | null;
 }

package/dist/chains/index.js

@@ -54,6 +54,11 @@ export const CHAINS = [
         steps.qualityCheck({ suite: "all" }),
     ]),
     stepChain("document", "write up the work that was just done, from the diff", [steps.request(), steps.changes(), steps.document()]),
+    stepChain("refine", "decompose a product spec into a feature/story-or-bug tree of tracker issues — spf watch's spec-ready lane", [
+        steps.request(),
+        steps.refine(),
+        steps.publishIssues(),
+    ]),
     {
         name: "simple-sdlc",
         describe: "the work is real and its shape is not obvious — plan, build, test, review, document; 3 commits",

package/dist/chains/steps.d.ts

@@ -35,6 +35,12 @@ export interface ChainState {
     changeset: ChangeSet | null;
     /** HEAD, pinned by request({logBaseline: true}) before the run commits anything. */
     baseline: string;
+    /**
+     * The originating tracker issue, only meaningful to `publishIssues()` —
+     * lifted from `ChainContext.issue_id` (see its doc comment) because a
+     * `Step` only ever sees `(run, state)`, never the `ChainContext` itself.
+     */
+    issue_id: string | null;
     /** The run's own acceptance criterion — distinct from "every phase succeeded"; see Run.finish(). */
     accepted: boolean;
     /** Why not, when accepted is false — passed straight to run.finish(). */
@@ -109,6 +115,24 @@ export declare function changes(opts?: {
 }): Step;
 /** Write up the captured change. Requires a preceding changes() step. */
 export declare function document(): Step;
+/** Decompose the spec in `prompt` into a feature/story tree — see `RefinedIssueSchema`'s doc comment. Gated so a malformed tree (wrong container/leaf kinds, an unresolved reference, a dependency cycle) re-prompts the same session before publishIssues() ever runs. */
+export declare function refine(): Step;
+/**
+ * Create the tree `refine()` produced on the tracker, in dependency order,
+ * and link each node to its parent. A `code` phase, not an agent one — the
+ * decision-making (topological order, label assignment, `## Blocked by`
+ * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
+ * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
+ *
+ * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
+ * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
+ * chain returns, since a chain's own return value is just an exit code.
+ * `spf watch`'s own marker/comment/transition bookkeeping for the spec
+ * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
+ * `spf refine` run (no daemon, no spec issue in play) still needs this step
+ * to work standalone.
+ */
+export declare function publishIssues(): Step;
 export declare function deriveRequiredAgents(steps: Step[]): string[] | ((options: Record<string, string>) => string[]);
 export declare function deriveRequiredSuites(steps: Step[]): string[];
 /** A display string for `spf list` — derived so it can no longer drift from what actually runs. */

package/dist/chains/steps.js

@@ -20,16 +20,19 @@
  * chain tractable: it would only ever need to name steps and pass them
  * tuning params, never express control flow.
  */
+import { writeFileSync } from "node:fs";
+import path from "node:path";
 import * as changesLib from "../core/changes.js";
 import * as gates from "../core/gates.js";
 import * as quality from "../core/quality.js";
 import * as agentsCfg from "../core/agents.js";
 import * as session from "../core/session.js";
+import * as refineLib from "../core/refine.js";
 import { DOCUMENT_NOTES } from "../core/prompts.js";
-import { BuildOutput, DocumentOutput, GenericOutput, PlanOutput, ReviewOutput, ScoutOutput, makeAgentCall, makeChangeCapture, makePhaseParams, } from "../core/data_types.js";
+import { BuildOutput, DocumentOutput, GenericOutput, PlanOutput, RefineOutput, ReviewOutput, ScoutOutput, makeAgentCall, makeChangeCapture, makePhaseParams, } from "../core/data_types.js";
 import { Run } from "../core/runner.js";
-function makeState(prompt, options) {
-    return { prompt, options, previous: null, quality: null, review: null, changeset: null, baseline: "", accepted: true, reason: "" };
+function makeState(prompt, options, issueId) {
+    return { prompt, options, previous: null, quality: null, review: null, changeset: null, baseline: "", issue_id: issueId, accepted: true, reason: "" };
 }
 function makeStep(fn, meta = {}) {
     const step = fn;
@@ -258,6 +261,54 @@ export function document() {
     };
     return makeStep(fn, { requiredAgents: ["documenter"], label: "documenter" });
 }
+/** Decompose the spec in `prompt` into a feature/story tree — see `RefinedIssueSchema`'s doc comment. Gated so a malformed tree (wrong container/leaf kinds, an unresolved reference, a dependency cycle) re-prompts the same session before publishIssues() ever runs. */
+export function refine() {
+    return agentStep({
+        name: "refine",
+        owner: "refiner",
+        output_type: RefineOutput,
+        description: "Decompose the spec into a feature/story tree of vertical slices",
+        gates: [gates.refinementWellFormed],
+    });
+}
+/**
+ * Create the tree `refine()` produced on the tracker, in dependency order,
+ * and link each node to its parent. A `code` phase, not an agent one — the
+ * decision-making (topological order, label assignment, `## Blocked by`
+ * rendering) is `core/refine.ts`'s job; this step is sequencing only, per
+ * SKILL.md's "chains stay thin" rule. Requires a preceding refine() step.
+ *
+ * Writes what it created to `<context_handoff_dir>/refine_publish.json` —
+ * the side channel `cli/commands/watch.ts`'s `runRefine` reads after the
+ * chain returns, since a chain's own return value is just an exit code.
+ * `spf watch`'s own marker/comment/transition bookkeeping for the spec
+ * issue lives entirely in `core/watch.ts`'s `runSpec`, never here — a bare
+ * `spf refine` run (no daemon, no spec issue in play) still needs this step
+ * to work standalone.
+ */
+export function publishIssues() {
+    const fn = async (run, state) => {
+        const envelope = state.previous;
+        if (!envelope || !Array.isArray(envelope.issues)) {
+            throw new Error("publishIssues() requires a preceding refine() step in the chain's step list");
+        }
+        await run.phase(makePhaseParams({
+            name: "publish",
+            kind: "code",
+            owner: "tracker",
+            description: "Create the feature/story tree on the tracker, in dependency order, and link each to its parent",
+        }), async (ph) => {
+            const tracker = refineLib.resolveAuthoringProvider(run.cfg);
+            const created = await refineLib.publish(tracker, envelope.issues, {
+                labelPrefix: run.cfg.watch.label_prefix,
+                specIssueId: state.issue_id,
+            });
+            writeFileSync(path.join(run.context_handoff_dir, "refine_publish.json"), JSON.stringify(created.map((c) => ({ id: c.issue.id, title: c.issue.title, kind: c.kind, isLeaf: c.isLeaf })), null, 2));
+            ph.log({ created: created.length, leaves: created.filter((c) => c.isLeaf).length });
+        });
+    };
+    return makeStep(fn, { label: "code(publish)" });
+}
 // ── layer 3: derive ChainDefinition fields from a step list ─────────────
 export function deriveRequiredAgents(steps) {
     const dynamicSteps = steps.filter((s) => typeof s.requiredAgents === "function");
@@ -291,7 +342,7 @@ export function derivePhases(steps) {
 /** Run a chain's step list start to finish: prologue, every step in order, then run.finish(). */
 export async function runSteps(ctx, requiredAgents, requiredSuites, steps, options = {}) {
     const run = startRun(ctx, requiredAgents, requiredSuites);
-    const state = makeState(ctx.prompt, options);
+    const state = makeState(ctx.prompt, options, ctx.issue_id ?? null);
     for (const step of steps) {
         await step(run, state);
     }

package/dist/cli/commands/doctor.js

@@ -143,6 +143,12 @@ export function doctorCommand(argv) {
                 : '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`);
+        if (cfg.watch.refine.enabled) {
+            check(report, "watch.refine.chain", Boolean(findChain(cfg.watch.refine.chain)), findChain(cfg.watch.refine.chain) ? cfg.watch.refine.chain : `"${cfg.watch.refine.chain}" is not a registered chain`);
+            check(report, "watch.refine issue authoring", cfg.watch.issue_provider === "github", cfg.watch.issue_provider === "github"
+                ? "github supports issue authoring (createIssue/sub-issues)"
+                : `watch.issue_provider is ${JSON.stringify(cfg.watch.issue_provider)} — the refine lane needs "github" (Jira issue authoring isn't implemented yet)`);
+        }
     }
     if (cfg.notifications.events !== "off") {
         check(report, "notifications.events", true, cfg.notifications.events);

package/dist/cli/commands/init.js

@@ -10,6 +10,14 @@
  * `src/cli/index.ts`). Piped input, `--yes`, or `--template <name>` all
  * fall through to the original non-interactive behavior unchanged — a
  * scripted `spf init` must never hang waiting on stdin.
+ *
+ * Every path here also installs the repo-local Claude Code skill (the same
+ * work `spf install-skill` does by hand) unless `--no-skills` is passed —
+ * on every run, not just the first: `install-skill` is idempotent (a no-op
+ * once the skill is already up to date), so this never re-does work or
+ * clobbers a locally-edited skill file. `--user` (installing to
+ * `~/.claude/skills/spf` instead) stays a `spf install-skill` invocation of
+ * its own; `init` only ever writes the repo-local default.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
@@ -22,6 +30,7 @@ import { paint } from "../../core/console.js";
 import { createAsker, isInteractive, InterviewAborted } from "../ask.js";
 import { gatherContext, runInterview } from "../interview.js";
 import { readEnvFile, upsertEnvFile, writeEnvExample } from "../env_file.js";
+import { installSkillCommand } from "./install-skill.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() {
@@ -67,8 +76,8 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 # 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
+# you override their model here too (builder/scout/refiner 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.
 
@@ -86,6 +95,13 @@ const STARTER_CONFIG = `# .spf/spf.config.yaml — merged ON TOP of spf's packag
 #   label_prefix: spf
 #   chain: plan-build-test
 #   base_branch: main
+#   # Optional second lane: decompose a spf:spec-ready product spec into a
+#   # feature/story-or-bug tree of real issues. Off by default; needs
+#   # issue_provider: github — issue authoring isn't implemented for Jira yet.
+#   refine:
+#     enabled: true
+#     chain: refine
+#     concurrency: 1
 
 # Uncomment to push notifications for unattended work — spf watch's daemon
 # lifecycle, and every chain run (spf <chain> / spf run, including watch's
@@ -113,10 +129,18 @@ const GENERATED_HEADER = `# .spf/spf.config.yaml — written by \`spf init\`'s i
 # (gitignored) — .env.example lists the key names only.
 `;
 export async function initCommand(argv) {
-    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes"]);
+    const { options, flags } = parseCli(argv, ["cwd", "template"], ["force", "yes", "no-skills"]);
     const anchor = paths.resolveAnchor(options["cwd"]);
     const sfDir = path.join(anchor.repo_root, ".spf");
     mkdirSync(sfDir, { recursive: true });
+    // Idempotent (a no-op once the skill is already up to date, a `.new`
+    // sibling rather than an overwrite for a locally-edited file) — safe to
+    // call on every `spf init`, not just the first.
+    const installSkill = () => {
+        if (flags["no-skills"])
+            return;
+        installSkillCommand(options["cwd"] ? ["--cwd", options["cwd"]] : []);
+    };
     const configPath = path.join(sfDir, "spf.config.yaml");
     const templateName = options["template"];
     const interactive = !templateName && !flags["yes"] && isInteractive();
@@ -129,6 +153,7 @@ export async function initCommand(argv) {
             writeFileSync(configPath, content);
             console.log(`wrote ${configPath}${templateName ? ` (from template "${templateName}")` : ""}`);
         }
+        installSkill();
     }
     else {
         const asker = createAsker();
@@ -138,6 +163,7 @@ export async function initCommand(argv) {
                 if (!overwrite) {
                     console.log("leaving the existing config alone (--force to skip this prompt)");
                     asker.close();
+                    installSkill();
                     ensureGitignore(anchor.repo_root, GITIGNORE_ENTRIES);
                     return 0;
                 }
@@ -155,6 +181,7 @@ export async function initCommand(argv) {
             if (Object.keys(result.env).length > 0)
                 upsertEnvFile(anchor.repo_root, result.env);
             writeEnvExample(anchor.repo_root, result.envExampleKeys);
+            installSkill();
             // The same merge-then-validate pipeline `spf doctor` runs — catches a
             // bad answer (e.g. a suite naming an unconfigured check) right after
             // writing, not at the user's first real chain run. Non-fatal: the

package/dist/cli/commands/install-skill.js

@@ -1,7 +1,10 @@
 /**
  * `spf install-skill` — copy the packaged Claude Code skill (`assets/skill/`)
- * into a target repo (or `~/.claude/skills/spf` with `--user`), on explicit
- * request only. Nothing here ever runs unless a user asks for it.
+ * into a target repo (or `~/.claude/skills/spf` with `--user`). `spf init`
+ * calls this itself, every run, unless `--no-skills` is passed — it's the
+ * command name a user (or a script) still reaches for by hand: to reinstall
+ * after an edit, to target `--user` instead of repo-local, or on a repo
+ * that never ran `spf init` at all (a pure-built-ins setup).
  *
  * Idempotent via a manifest (`.spf-skill-version`: {package, version,
  * files: {relpath: sha256}}) written at the skill root:

package/dist/cli/commands/list.js

@@ -9,5 +9,6 @@ export function listCommand() {
         console.log();
     }
     console.log(`spf <name> "<prompt>" [--config <path>] [--adw-id <id>] [--cwd <dir>]   (spf run <name> ... works identically)`);
+    console.log(`spf watch polls a tracker and runs one of these chains per issue — spf doctor shows the current config.`);
     return 0;
 }