@gr8ful/spf 0.2.1 → 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
@@ -34,10 +34,12 @@ spf init --template ts-cc      # or start from a packaged, ready-to-run template
 spf list                       # every chain this install knows, its phases, what it needs
 ```
 
-On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model, which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
+On a real terminal, `spf init` asks a short interview — which coding agent (`claude_code` or `flue`) and model (optionally customized per agent instead of one model for the whole roster), which quality checks to gate on, whether to turn on `spf watch` and against which tracker/code host, and whether to push notifications to Slack/Teams/a webhook — and writes `.spf/spf.config.yaml` with only what you answered differently from the packaged defaults, plus whatever secrets those answers imply appended to `.env` (already gitignored, and already auto-loaded by every command) and their key names mirrored into a committable `.env.example`. Re-running it later shows any existing `.env` value masked and keeps it on an empty answer, so rotating one secret doesn't mean re-answering everything. Piped input, `--yes`, or `--template <name>` all skip the interview and fall back to the original non-interactive behavior — a scripted `spf init` never blocks on stdin.
 
 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 |
 |---|---|---|
@@ -322,6 +372,56 @@ export BITBUCKET_API_TOKEN=...   # same Atlassian API token mechanism as Jira ab
 
 **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).
 
+## Notifications
+
+Optional, off by default: push a curated set of milestones to Slack,
+Microsoft Teams, or a generic webhook. It's scoped to **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` — never notify; you're already looking at the terminal
+for those.
+
+```yaml
+# .spf/spf.config.yaml
+notifications:
+  events: errors            # off (default) | errors | all
+  channels:
+    - kind: slack            # slack | teams | webhook
+      webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
+```
+
+`events` is the whole filter: `errors` sends only failed runs/phases, blocked
+issues, and watch errors; `all` adds every milestone — run started/finished,
+issue claimed, PR opened, issue done. A channel's own `events` overrides the
+top-level scope for just that channel. `spf doctor` reports whether each
+configured channel's env var is set.
+
+The webhook URL is a secret and lives only in `.env` — `webhook_url_env`
+names the key, never the URL itself, matching `GITHUB_TOKEN`/
+`JIRA_API_TOKEN`. Defaults per kind: `SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`,
+`SPF_WEBHOOK_URL`. `spf init`'s interview asks for this section and collects
+the URL straight into `.env`, same as every other credential.
+
+Getting each channel's URL:
+
+- **Slack** — [Sending messages using Incoming Webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks): create a Slack app, enable Incoming Webhooks, "Add New Webhook to Workspace".
+- **Microsoft Teams** — [Send messages in Teams using incoming webhooks](https://support.microsoft.com/en-us/office/post-a-workflow-when-a-webhook-request-is-received-in-microsoft-teams-8ae491c7-0394-4861-ba59-055e33f75498): in the target channel, add a Workflows webhook template (search for one along the lines of "Post to a channel when a webhook request is received" / "Send webhook alerts to a channel" — Microsoft's own naming here has shifted between revisions) and copy the generated URL. This is the *only* supported path now — the old Office 365 connector webhook has been retired by Microsoft.
+- **webhook** — any endpoint that accepts a JSON POST of the event: Discord,
+  n8n, Zapier, a homegrown receiver.
+
+Delivery never blocks or fails a run: an unconfigured/misconfigured channel
+is skipped with one warning, and a failed POST logs one line and is
+swallowed — never changes a run's exit code. One thing worth knowing under
+`events: all`: `spf watch` runs its per-issue chains in-process, so a failed
+issue produces **two** notifications for the same failure — `run_failed`
+(keyed to the chain's own `adw_id`, e.g. `issue-142`) from the chain-run
+side, and `issue_blocked` (keyed to the issue) from watch itself. Both are
+genuinely informative, just worth expecting.
+
+Full field reference: `spf install-skill`'s installed skill
+(`references/config.md`).
+
 ## What's in this repo
 
 ```
@@ -335,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

@@ -12,9 +12,10 @@ always shows the resolved, merged result for the repo you're in.
 1. The packaged built-in default (`assets/defaults/spf.config.yaml` inside
    the installed CLI).
 2. `.spf/spf.config.yaml` in the target repo, if present — merged on top,
-   field by field (`defaults`/`observability`/`quality` merge key-by-key;
-   `agents` merges by `name`: a matching name patches that entry, a new name
-   appends).
+   field by field (`defaults`/`observability`/`quality`/`watch`/`notifications`
+   merge key-by-key — `notifications.channels` replaces wholesale, same as
+   `quality.checks`; `agents` merges by `name`: a matching name patches that
+   entry, a new name appends).
 3. An explicit `--config <path>` replaces both — standalone, no built-in
    underneath it.
 
@@ -107,6 +108,85 @@ 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.
 
+### `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.
+
+
+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`)
+never notify — you're already looking at the terminal for those. Off by
+default; adding it is entirely additive.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `events` | `"off"` \| `"errors"` \| `"all"` | The whole filter. `off` (default): nothing. `errors`: only failed runs/phases, blocked issues, watch errors. `all`: every curated milestone (run started, issue claimed, PR opened, ...) plus errors. |
+| `timeout_ms` | int | Per-request timeout for a channel's HTTP POST. Default `5000`. |
+| `channels[]` | array | See below. |
+
+`channels[].kind`: `"slack"` \| `"teams"` \| `"webhook"`. `channels[].events`
+overrides `events` for just that channel (unset = inherit). `webhook_url_env`
+names the `.env` key holding the secret URL — never the URL itself, matching
+`GITHUB_TOKEN`/`JIRA_API_TOKEN`. Empty/omitted uses the kind's own default:
+`SLACK_WEBHOOK_URL`, `TEAMS_WEBHOOK_URL`, `SPF_WEBHOOK_URL`. `name` is a
+cosmetic label for warning lines when you have two channels of the same
+kind.
+
+```yaml
+notifications:
+  events: errors
+  channels:
+    - kind: slack
+      webhook_url_env: SLACK_WEBHOOK_URL   # optional; this is the default for slack
+    - kind: teams
+      events: all                           # per-channel override
+    - kind: webhook
+      webhook_url_env: OPS_WEBHOOK_URL
+      name: ops-bus
+```
+
+Delivery never blocks or fails a run: a channel with an unset env var is
+skipped with one warning at startup (`spf doctor` reports the same thing as
+a check); a failed POST logs one line and is swallowed, never changing the
+run's exit code. See the main README's "Notifications" section for how to
+get each channel's webhook URL, and `spf init`'s interview, which asks for
+this section and collects the URL straight into `.env`.
+
 ### `agents[]`
 
 | Field | Required | Meaning |

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,3 +64,23 @@ 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).
+# Interactive commands (doctor, list, sessions, ...) never notify. events:
+# "errors" sends only failures/blocked issues; "all" adds every milestone.
+# The webhook URL is a secret — put it in .env under the key named below,
+# never here. See the main README's "Notifications" section.
+# notifications:
+#   events: errors            # off (default) | errors | all
+#   channels:
+#     - kind: slack            # slack | teams | webhook
+#       webhook_url_env: SLACK_WEBHOOK_URL

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);
     }