@sassywares/skills 0.7.5 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CONCEPTS.md CHANGED
@@ -14,7 +14,7 @@ A specialized subagent from [sassy-agents](https://github.com/sassywares/sassy-a
14
14
 
15
15
  ## Orchestrator
16
16
 
17
- A skill that mostly coordinates. It reads compact results, writes briefs, and avoids reading source or diffs in the main context. `sassy-work`, `sassy-lfg`, `sassy-ship`, and `sassy-debug` are orchestrators.
17
+ A skill that mostly coordinates. It reads compact results, writes briefs, and avoids reading source or diffs in the main context. `sassy-work`, `sassy-lfg`, `sassy-ship`, `sassy-debug`, and `sassy-goal` are orchestrators.
18
18
 
19
19
  ## Cycle
20
20
 
@@ -37,12 +37,13 @@ A gate is a deliberate stop or pass/fail condition.
37
37
 
38
38
  ## Modes
39
39
 
40
- Three mode tokens: `mode:manual` (default) asks at the skill's gate; `mode:auto` means pre-authorized, no review; `mode:return` reports and changes nothing.
40
+ Three shared mode tokens: `mode:manual` (default) asks at the skill's gate; `mode:auto` means pre-authorized, no review; `mode:return` reports and changes nothing. Some skills take their own modes instead: `sassy-goal`, `sassy-handoff` (`write`, `read`), `sassy-setup` (`init`, `check`), and `sassy-skill` (`create`, `retune`, `verify`).
41
41
 
42
42
  - `sassy-ship` and `sassy-compound` accept `manual` and `auto`. Ship reviews the whole close-out in `mode:manual` and forwards `mode:auto` to compound once its own gate is answered.
43
43
  - `sassy-review`, `sassy-simplify`, and `sassy-validate` accept all three: `manual` asks which findings to fix, `auto` fixes them without asking, `return` hands the findings back to the caller.
44
44
  - `sassy-debug` accepts no mode. It always leaves ship's review gate in place.
45
45
  - `sassy-work` and `sassy-lfg` accept no mode.
46
+ - `sassy-goal` takes its own modes, one per step of a goal: `mode:write` (default), `mode:next`, `mode:check`, and `mode:close`.
46
47
 
47
48
  Everything else is decided by the artifact, not a mode:
48
49
 
@@ -53,6 +54,18 @@ Everything else is decided by the artifact, not a mode:
53
54
 
54
55
  A durable document under `docs/plans/` with intent, decisions, constraints, phase tracking, and per-phase manual QA tables.
55
56
 
57
+ ## Goal
58
+
59
+ Work too big for one plan — a migration, an epic — run by `sassy-goal` as a folder under `artifacts.plans`: `goal.md` (intent, cross-slice decisions, landscape, coexistence, a slice table, carry-forward) plus one plan per started slice. It turns `Done` when `mode:close` verifies its done-when against the whole tree.
60
+
61
+ ## Slice
62
+
63
+ One step of a goal: its own plan (`NN-<slug>.md`, written only when `mode:next` starts it), branch, and PR, and it must ship something complete on its own — never a half-built layer. One slice is in flight at a time: `Pending` > `Planned` > `Shipped` > `Done`.
64
+
65
+ ## Carry-forward
66
+
67
+ The append-only section of `goal.md` that `mode:check` adds to once per slice: what changed versus the plan, new decisions, impact on later slices, and gaps deferred or accepted. Every later slice's grill reads it as settled.
68
+
56
69
  ## Brief
57
70
 
58
71
  A settled in-context brief produced by `sassy-plan` when the user picks "start working" (`sassy-work`) or "implement and ship" (`sassy-lfg`). It carries the goal, decisions, constraints, work, and done-when, but no plan file and no QA tables.
package/README.md CHANGED
@@ -14,6 +14,7 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
14
14
  - [Project config](#project-config)
15
15
  - [Workflows](#workflows)
16
16
  - [From idea to ship](#from-idea-to-ship)
17
+ - [From goal to done](#from-goal-to-done)
17
18
  - [From bug to ship](#from-bug-to-ship)
18
19
  - [Gates and controls](#gates-and-controls)
19
20
  - [Branching](#branching)
@@ -27,7 +28,7 @@ It covers the whole path from a rough idea to a shipped PR, and from a bug repor
27
28
 
28
29
  - **Lean.** Skills are indexes and workflows, not documentation dumps. Detail moves into `references/` only when it is conditionally needed.
29
30
  - **Explicit.** Every skill but `sassy-ship` runs only when you invoke it; ship may be started by the agent once you approve the work, and its review gate still waits. No silent background behavior.
30
- - **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence. Mode tokens are opt-in per skill: `mode:manual` (default) and `mode:auto` on `sassy-ship` and `sassy-compound`, plus `mode:return` on `sassy-review`, `sassy-simplify`, and `sassy-validate`; work, lfg, and debug take no mode.
31
+ - **Controlled.** Code approval, manual QA, and ship review are visible gates that all run in sequence. Mode tokens are opt-in per skill: `mode:manual` (default) and `mode:auto` on `sassy-ship` and `sassy-compound`, plus `mode:return` on `sassy-review`, `sassy-simplify`, and `sassy-validate`; work, lfg, and debug take no mode; `sassy-goal` takes one mode per step of a goal (`write`, `next`, `check`, `close`).
31
32
  - **Reliable.** Work runs through `sassy-cycle` with isolated subagents for implementation, review, simplification, validation, and verified fixes.
32
33
  - **Context-efficient.** Orchestrators coordinate; subagents do the heavy reading and return compact results.
33
34
  - **Never surprising.** Nothing is committed just because a step finished. Shipping is its own phase.
@@ -83,6 +84,7 @@ Debugging:
83
84
  | Skill | What it does |
84
85
  |---|---|
85
86
  | **`sassy-plan`** | Grills you one question at a time through every branch of the work — pushing back, assuming nothing, sketching UI on request — until nothing is open, then offers three choices: write the plan, start working via `sassy-work`, or implement and ship via `sassy-lfg`. |
87
+ | **`sassy-goal`** | Runs a project too big for one plan — a migration, an epic — as a goal split into slices that each ship something complete. `mode:write` (default) grills and writes the goal, `mode:next` plans the next slice via `sassy-plan`, `mode:check` validates a shipped slice and carries its lessons forward, `mode:close` verifies the whole goal. You run every step. |
86
88
  | **`sassy-scout`** | Grounds an area on demand and writes the shared grounding brief other agents read instead of re-exploring. |
87
89
  | **`sassy-work`** | Executes exactly one plan phase, or one in-context brief, commits after code approval, then hands off the next phase — a brief stops before ship. |
88
90
  | **`sassy-lfg`** | Executes every phase of a plan, or one in-context brief, then closes out via `sassy-ship` after code approval. |
@@ -226,6 +228,26 @@ The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg`
226
228
 
227
229
  `sassy-ship` is the close-out. It summarizes what is about to ship and waits, unless the caller passed `mode:auto`.
228
230
 
231
+ ### From goal to done
232
+
233
+ ```mermaid
234
+ flowchart LR
235
+ A[Big idea] --> B[sassy-goal write]
236
+ B --> C[goal.md + slice table]
237
+ C --> D[sassy-goal next]
238
+ D --> E[sassy-plan: slice plan]
239
+ E --> F[sassy-work / sassy-lfg]
240
+ F --> G[sassy-ship]
241
+ G --> H[sassy-goal check]
242
+ H -->|more slices, after merge| D
243
+ H -->|last slice| I[sassy-goal close]
244
+ I --> J[Goal Done, rides the last PR]
245
+ ```
246
+
247
+ A goal is a folder under `artifacts.plans` holding `goal.md` and one plan per started slice (`01-<slice>.md`, `02-…`). `mode:write` grounds every affected domain once, grills only goal-level branches — slice boundaries and order, coexistence, the goal's done-when, non-goals — and pushes back on any slice that would leave a half-built layer. Each slice's plan is grilled only when `mode:next` starts it, with the goal's decisions and every carry-forward entry already settled. The slice then runs the usual work or lfg → ship path on its own branch (`feat/<goal>/<NN-slice>`); ship marks it `Shipped` and babysits the PR without merging, so the check can still land in it.
248
+
249
+ `mode:check` runs on the slice branch before the PR merges: it validates the whole slice plan against the branch's commits, and every gap is fixed now, deferred to a named later slice, or accepted with a reason. It appends the slice's carry-forward entry, marks it `Done` with its PR link, and pushes `goal.md` into the same PR. After the last slice, `mode:close` checks the goal's done-when against the whole tree and marks the goal `Done` in the last PR. One slice is in flight at a time, and nothing chains on its own.
250
+
229
251
  ### From bug to ship
230
252
 
231
253
  ```mermaid
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.7.5",
3
+ "version": "0.8.0",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: sassy-goal
3
+ description: >-
4
+ Run a large project or major feature that one plan cannot hold — a migration,
5
+ an epic, a milestone, a whole-app rewrite — as a goal split into slices, each
6
+ of which plans, ships, and is checked on its own. mode:write (default)
7
+ grills and writes or revises the goal; mode:next plans the next slice via
8
+ sassy-plan; mode:check validates a shipped slice and records carry-forward;
9
+ mode:close verifies the whole goal before the last PR merges. Use when work
10
+ is too big for one plan, spans several PRs, or the user says goal, epic,
11
+ milestone, or migration.
12
+ argument-hint: "<idea | goal path> [mode:write|next|check|close] [slice:<ID>]"
13
+ ---
14
+
15
+ # Sassy Goal
16
+
17
+ **Outcome:** a goal folder whose `goal.md` holds the intent, the cross-slice decisions, and a slice table — then, one slice at a time, a slice plan written when that slice starts, shipped through the usual `sassy-work` / `sassy-lfg` → `sassy-ship` path, checked against its plan, and carried forward; finally the whole goal verified and marked `Done`.
18
+
19
+ **One slice ships at a time, and every slice ships something complete.** A slice is its own plan → work or lfg → ship. It never leaves a half-built layer behind for a later slice to finish.
20
+
21
+ **The user drives every step.** Each mode ends by printing the next command; nothing chains on its own. This skill never implements: code changes belong to `sassy-work`, `sassy-lfg`, and `sassy-cycle`.
22
+
23
+ **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. Goals live under `artifacts.plans`; `git.repo` and `commit.branch` decide how check and close persist.
24
+
25
+ **Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
26
+
27
+ ## The goal
28
+
29
+ A goal is the folder `<artifacts.plans>/<goal-slug>/`: `goal.md` plus one plan per started slice, named `NN-<slice-slug>.md` where `NN` matches the slice ID (`S1` → `01-`). Slice plans are ordinary sassy plans. `references/goal-format.md` owns the `goal.md` format, the slice statuses, and the template — read it before writing or revising `goal.md`.
30
+
31
+ Slice statuses run `Pending` > `Planned` > `Shipped` > `Done`, plus `Blocked`. `mode:next` sets `Planned`, `sassy-ship` sets `Shipped` (and babysits the slice PR without merging), `mode:check` sets `Done` and records the PR link.
32
+
33
+ ## Modes
34
+
35
+ | Mode | Load | Runs | It ends with |
36
+ |---|---|---|---|
37
+ | `write` (default) | `references/write.md` | anytime | a new or revised `goal.md`, and the `mode:next` command |
38
+ | `next` | `references/next.md` | on the base, previous slice merged | the slice's plan written, the slice `Planned`, and the work / lfg commands |
39
+ | `check` | `references/check.md` | on the slice branch after ship, before merge | the slice `Done`, carry-forward appended, pushed with the slice |
40
+ | `close` | `references/close.md` | on the last slice's branch after its check, before merge | `**Status:** Done` (or `Active` with a slice to add), pushed with the last slice |
41
+
42
+ Resolve the mode: an explicit `mode:` token wins. With none, it is `write` — an idea creates a goal, a path to an existing goal folder or `goal.md` revises it. Read the one reference for that mode **and only that one**.
43
+
44
+ ```text
45
+ write → next → work/lfg → ship → check → next → … → ship → check → close
46
+ ```
47
+
48
+ ## Persisting
49
+
50
+ `check` and `close` commit on the slice branch so `goal.md` merges with the slice. Persist exactly like `sassy-ship` steps 4–5, per `git.repo`:
51
+
52
+ - **A remote** — dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`*, which commits, pushes, and updates the slice's open PR. Under `commit.branch: current` there is no PR: the worker loads `sassy-commit` with `branch:current`, then pushes the head to its upstream — never forced; a non-fast-forward rejection is a stop-and-report.
53
+ - **`workspace`** — commit each affected repo on the run's shared branch, run `.sassywares/workspace/snapshot` for `goal.md` and the docs at the root, then push each repo. A missing or outdated snapshot script is a blocker: say to run `sassy-setup`.
54
+ - **`none`** — nothing persists. Report that `goal.md` and any fixes are uncommitted, and stop.
55
+
56
+ ## Hard rules
57
+
58
+ | Rule | Requirement |
59
+ |------|-------------|
60
+ | Writing never implements | `mode:write` and `mode:next` produce documents only. Fixes in check and close go through `sassy-cycle`. |
61
+ | Complete slices | Push back on any slice that does not ship a working outcome on its own; re-cut it before the goal is written. |
62
+ | One slice in flight | Never plan a slice while another is `Planned` or `Shipped`. No parallel slices. |
63
+ | Plan at slice start | A slice's plan is grilled and written only when `mode:next` starts it — never upfront. |
64
+ | Settled stays settled | The goal's decisions and every carry-forward entry reach each slice grill as settled; they are never re-asked. |
65
+ | Carry-forward is append-only | One entry per checked slice; never edit or remove an earlier one. |
66
+ | Done is history | A revision never re-cuts, renumbers, or rewrites a `Done` slice or its plan. |
67
+ | No unchosen gaps | A slice or the goal turns `Done` only when every gap is fixed, deferred to a named slice, or accepted with a recorded reason. |
68
+ | Never default | Never push to a base branch outside `commit.branch: current`; never force-push. |
69
+
70
+ ## Non-goals
71
+
72
+ No auto-chaining between slices or modes, no parallel slices, no auto mode (a future follow-up), and no dependency on any framework outside this suite.
@@ -0,0 +1,25 @@
1
+ # Mode: check — validate a shipped slice and carry it forward
2
+
3
+ Runs on the slice branch after `sassy-ship`, before the PR merges, so whatever it changes rides in the same PR.
4
+
5
+ 1. **Precondition.** Read `goal.md` and find the slice (`slice:<ID>`, else the one `Shipped`). It must be `Shipped`, and every phase in its plan's Phase tracking table must be `Done`. Otherwise stop and say what is due — unfinished phases need `sassy-work` or `sassy-lfg`, an unshipped slice needs `sassy-ship`.
6
+
7
+ Then dispatch a probe `worker` to run the `sassy-setup` skill's `scripts/detect.sh --branch` (no `--policy`), returning `state` and `head`, and `gh pr view <head> --json state,url,baseRefName`. Outside `commit.branch: current`:
8
+ - `state` must be `on-branch` — the slice branch. Anything else → stop and tell the user to check out the slice branch.
9
+ - The PR must be `OPEN`. Already merged → stop: the check can no longer ride in the slice's PR. Recovery: cut a branch from the base, run `mode:check` there, and open a PR for the `goal.md` update and any fixes. Closed unmerged → stop and ask what happened.
10
+ 2. **Find the range.** The probe worker also returns `git merge-base <remote>/<baseRefName> HEAD`. Under `commit.branch: current` there is no PR: ask the user for the commit the slice started from. Under `git.repo: workspace`, get one PR, base, and merge-base per affected repo.
11
+ 3. **Validate.** Load the `sassy-validate` skill with `mode:return`, the slice plan path with no phase (the whole plan), and `range:<merge-base>..HEAD`. In a workspace, make one call per affected repo, each with its own range. A `Blocked — insufficient grounding` grade stops the check: report what it needs.
12
+ 4. **Resolve every gap.** On `Conforms`, there are none. Otherwise present each gap with its evidence, and for each the user picks one:
13
+ - **Fix now** — collected and closed together: load the `sassy-cycle` skill on rework with the chosen gaps as findings and the slice plan as the intent reference. A gap still open after its two fix passes goes back to the user to defer or accept.
14
+ - **Defer to a later slice** — the user names one that is still `Pending`. Add the gap to that slice's Scope or Done when in `goal.md`; it also goes in this slice's carry-forward entry. On the last slice there is nothing to defer to: only fix or accept.
15
+ - **Accept** — with the user's reason, recorded in the carry-forward entry.
16
+
17
+ The slice cannot turn `Done` while any gap is unchosen. Never pick for the user.
18
+ 5. **Carry forward.** Append one entry for this slice to Carry-forward per `references/goal-format.md`: what changed versus the plan, new decisions or constraints (they bind later slices), impact on later slices, and each gap deferred (with its slice) or accepted (with its reason). Never edit an earlier entry.
19
+ 6. **Mark it `Done`** in the slice table, and add the PR link from step 1's `url` to its Plan cell.
20
+ 7. **Persist** per the SKILL.md Persisting section — `goal.md` and any fixes, committed on the slice branch and pushed so they merge with the slice.
21
+ 8. **Next commands**, in the harness's syntax:
22
+ - The last slice → `/sassy-goal <goal path> mode:close`, run on this branch before the PR merges.
23
+ - Otherwise → `/sassy-goal <goal path> mode:next`, once this slice's PR has merged.
24
+
25
+ Persisting ran with `babysit:off`, so end with `/sassy-babysit <PR url>` to watch the updated PR.
@@ -0,0 +1,22 @@
1
+ # Mode: close — verify the whole goal
2
+
3
+ Runs on the last slice's branch after its `mode:check`, before its PR merges, so `**Status:** Done` rides in the last PR.
4
+
5
+ 1. **Precondition.** Read `goal.md`. Every slice must be `Done`. Then dispatch a probe `worker` to return:
6
+ - the `sassy-setup` skill's `scripts/detect.sh --branch` (no `--policy`) `state` and `head`;
7
+ - `gh pr view <head> --json state,url` for the last slice's PR;
8
+ - `gh pr view <url> --json state` for every earlier slice's PR link.
9
+
10
+ Outside `commit.branch: current`, `state` must be `on-branch` (the last slice's branch) and its PR `OPEN`; every earlier PR must be `MERGED`. Under `commit.branch: current`, `git.repo: workspace`, or `git.repo: none` — or when a slice has no PR link — ask the user to confirm the merges instead. Anything else → stop and say what is due. If the last PR already merged, the status can no longer ride in it: cut a branch from the base, run `mode:close` there, and open a PR for it.
11
+ 2. **Two read-only checks, in parallel.** Dispatch both in one turn; neither edits anything:
12
+ - **Done when** — a `worker` that checks each goal Done-when item against the whole tree, including repo-wide checks, and returns pass / fail per item with `file:line` evidence.
13
+ - **Roll-up** — a `worker` that reads `goal.md` and its slice plans and returns whether every slice is `Done` and every gap a carry-forward entry deferred landed in a later slice's plan or was explicitly accepted, naming each one that did not.
14
+ 3. **Resolve every gap.** Present each failure with its evidence, and for each the user picks one:
15
+ - **Fix on this branch** — load the `sassy-cycle` skill on rework with the chosen gaps as findings and `goal.md` as the intent reference.
16
+ - **Add a slice** — record the gap under Deferred in `goal.md` as *needs a new slice*. The user adds the slice with `sassy-goal <goal path> mode:write`, which revises the goal.
17
+ - **Accept** — record it as a Decision with provenance: `D<n>: <gap> accepted unmet — <reason> (user-directed, over fixing)`. Never as an Assumption or a Carry-forward entry.
18
+
19
+ Nothing is left unchosen. With mixed choices, run the chosen fixes first.
20
+ 4. **Mark it `Done`** — only when no gap was sent to a new slice: set `**Status:** Done`. If any was, the goal stays `Active`.
21
+ 5. **Persist** per the SKILL.md Persisting section, on this branch, so `goal.md` and any fixes merge with the last slice.
22
+ 6. **Report** the goal path, each Done-when item with its result, and the gaps fixed, accepted, or sent to a new slice. If the goal stayed `Active`, give `/sassy-goal <goal path> mode:write` to add the slice, then `mode:next` once this PR merges. Otherwise the goal is closed when this PR merges. Persisting ran with `babysit:off`, so end with `/sassy-babysit <PR url>` in the harness's syntax.
@@ -0,0 +1,113 @@
1
+ # Goal file format
2
+
3
+ Read this before writing or revising `goal.md`.
4
+
5
+ ## Layout
6
+
7
+ A goal is a folder under `artifacts.plans`:
8
+
9
+ ```text
10
+ <artifacts.plans>/<goal-slug>/
11
+ ├── goal.md # this format
12
+ ├── 01-<slice-slug>.md # S1's plan, written by sassy-plan when S1 starts
13
+ └── 02-<slice-slug>.md # S2's plan, written when S2 starts
14
+ ```
15
+
16
+ The goal slug is made the way `sassy-plan` makes a plan slug. `NN` is the slice's order and matches its ID: `S1` → `01-`, `S2` → `02-`. A slice plan is an ordinary sassy plan, so `sassy-work`, `sassy-lfg`, `sassy-ship`, and `sassy-validate` run on it unchanged.
17
+
18
+ ## Rules
19
+
20
+ - **No open questions.** Like a plan, the goal has no open-questions section. Every goal-level branch is a decision, a constraint, a deferred item, or an assumption.
21
+ - **Goal level only.** Decisions here are the ones that bind more than one slice. Anything one slice can settle alone is deferred to that slice's grill.
22
+ - **Slices stay surface level.** A slice outline says what ships and how you know; its plan says how. Never write phases, QA rows, or file-by-file work into `goal.md`.
23
+ - **Every slice ships something complete.** A slice that leaves a half-built layer — a schema nobody reads, an API nobody calls — is not a slice. Re-cut it until each one ships a working outcome on its own.
24
+ - **Carry-forward is append-only.** One entry per checked slice, added by `mode:check`, never edited afterward. Later slices read it as settled ground; a correction is a new entry.
25
+ - **Done slices are history.** A revision never re-cuts, renumbers, or rewrites a `Done` slice or its plan.
26
+
27
+ ## Slice statuses
28
+
29
+ | Status | Set by | Meaning |
30
+ |---|---|---|
31
+ | `Pending` | `mode:write` | Outlined; no plan yet |
32
+ | `Planned` | `mode:next` | Plan written; work not shipped |
33
+ | `Shipped` | `sassy-ship` | Close-out committed and PR open |
34
+ | `Done` | `mode:check` | Checked against its plan; every gap fixed, deferred, or accepted |
35
+ | `Blocked` | any mode | Cannot proceed; the Plan cell or a note says why |
36
+
37
+ Order: `Pending` > `Planned` > `Shipped` > `Done`. Only one slice is ever `Planned` or `Shipped` at a time.
38
+
39
+ ## Template
40
+
41
+ ```markdown
42
+ # <Goal title>
43
+
44
+ **Status:** Active
45
+
46
+ ## Intent
47
+ One paragraph: the outcome when the whole goal lands, and why it is worth a multi-slice effort.
48
+
49
+ ## Done when
50
+ Goal-level acceptance — what `mode:close` checks against the whole tree.
51
+ - G1: … (e.g. every screen reads from the local database)
52
+ - G2: … (repo-wide checks too, e.g. "no imports of the HTTP client remain")
53
+
54
+ ## Decisions
55
+ Cross-slice decisions only, each with provenance from the interview ledger.
56
+ - D1: … (user-directed, over <alternative>: <reason>)
57
+ - D2: … (from code: `path/to/file.ts:12`)
58
+
59
+ ## Constraints
60
+ Non-goals and anything that must not change.
61
+
62
+ ## Landscape
63
+ Per domain: what changes, where, and the blast radius.
64
+
65
+ | Domain | What changes | Where | Blast radius |
66
+ |---|---|---|---|
67
+ | Sync | … | `src/sync/client.ts:40` | … |
68
+
69
+ ## Risks
70
+ Known issues, unknowns, and spikes, each with the slice that retires it.
71
+
72
+ ## Coexistence
73
+ How the app runs mid-goal: what old and new run side by side, which flags gate what, and when each is removed.
74
+
75
+ ## Slice tracking
76
+
77
+ | ID | Slice | Ships | Depends | Plan | Status |
78
+ |----|-------|-------|---------|------|--------|
79
+ | S1 | … | … | — | — | Pending |
80
+ | S2 | … | … | S1 | — | Pending |
81
+
82
+ The Plan cell holds the plan link once written, and the PR link once `mode:check` records it: `[plan](01-slug.md) · [PR](<url>)`.
83
+
84
+ ## Slices
85
+
86
+ ### S1 — <short name>
87
+
88
+ **Ships:** One sentence: the complete outcome a user or the system has when this merges.
89
+
90
+ **Scope:** The domains and areas it touches, surface level.
91
+
92
+ **Done when:** Plain-language acceptance for this slice only.
93
+
94
+ ### S2 — <short name>
95
+ …
96
+
97
+ ## Carry-forward
98
+ Append-only. One entry per checked slice, added by `mode:check`.
99
+
100
+ ### S1 — <date>
101
+ - **Changed vs plan:** …
102
+ - **New decisions / constraints:** … (they bind later slices)
103
+ - **Impact on later slices:** S3 — …
104
+ - **Gaps:** deferred to S2 — …; accepted — … (reason)
105
+
106
+ ## Deferred
107
+ - F1: … (user-deferred — to S3's grill)
108
+
109
+ ## Assumptions
110
+ - A1: … (user-delegated)
111
+ ```
112
+
113
+ Omit Risks, Deferred, or Assumptions only when empty. Carry-forward starts empty with its one-line note.
@@ -0,0 +1,28 @@
1
+ # Mode: next — plan the next slice
2
+
3
+ **One slice in flight.** This mode starts exactly one slice by planning it. It never implements, never plans a second slice, and never runs work or lfg itself.
4
+
5
+ 1. **Start from a fresh base.** The slice's branch is cut later by `sassy-work` or `sassy-lfg`, and a run standing on a non-base branch would reuse it. Dispatch a probe `worker` to `git fetch` the remote, run the `sassy-setup` skill's `scripts/detect.sh --branch` (no `--policy`), and return `state`, `head`, and whether local `<head>` equals `<remote>/<head>`. `state` must be `on-base` and the two must match. `on-branch` (usually the previous slice's merged branch), `detached`, or a base behind or ahead of its remote → tell the user to switch to the base and pull, then stop. Under `commit.branch: current` this step does not apply.
6
+ 2. **Load the goal.** Only now read `goal.md`. If its status is `Done`, say so and stop.
7
+ 3. **Nothing in flight.** If any slice is `Planned` or `Shipped`, stop and name what is due: a `Planned` slice needs `sassy-work` or `sassy-lfg` on its plan, a `Shipped` slice needs `mode:check`.
8
+ 4. **Earlier slices merged.** Every `Done` slice's PR must be merged before the next slice starts, or the new slice is built on code that may still change. Dispatch a `worker` to check each PR with `gh pr view <url> --json state` and return the states. Under `commit.branch: current`, `git.repo: workspace`, or `git.repo: none` — or when a slice has no PR link — ask the user to confirm instead. Anything unmerged → stop and say which PR must merge first.
9
+ 5. **Pick the slice.** The first `Pending` slice whose Depends are all `Done`. A `slice:<ID>` token overrides the pick, but its Depends must still be `Done`; a slice that is not `Pending` is a stop. No eligible slice → if every slice is `Done`, point at `mode:close`; otherwise report what blocks each `Pending` slice and stop.
10
+ 6. **Plan it.** Load the `sassy-plan` skill and follow it, with:
11
+ - **frame** = the slice's Ships, Scope, and Done when from `goal.md`
12
+ - **settled** = the goal's Decisions and Constraints, and every Carry-forward entry — enter them in the ledger as settled with their provenance; never re-ask them
13
+ - **context** = the goal path, the goal's Landscape and Coexistence rows for this slice's domains, and the Deferred items addressed to this slice
14
+ - **`out:<goal folder>/NN-<slice-slug>.md`**, with `NN` from the slice ID
15
+
16
+ `sassy-plan` grills the slice in full — this is where its detail gets decided — writes the plan to that path, skips its picker, and returns the path.
17
+
18
+ **Interrupted run.** If an `NN-*.md` for this slice already exists while the slice is still `Pending`, an earlier run stopped after writing it. Pass that file to `sassy-plan` as the `out:` path and the existing plan, so it updates it in place per its existing-plan rule instead of re-grilling from scratch.
19
+ 7. **Mark it `Planned`.** In the slice table set the slice `Planned` and the Plan cell to the plan link. Commit nothing. The plan and `goal.md` ride onto the slice's branch when `sassy-work` or `sassy-lfg` cuts it. Their commits name the plan, not `goal.md`, so the `Planned` mark stays uncommitted on the slice branch until `sassy-ship`'s step 4 commit, which sets it `Shipped`.
20
+ 8. **Hand over.** Report the plan path and print both commands in the harness's syntax, then stop:
21
+
22
+ ```text
23
+ S<n> planned at <plan path>. Pick one:
24
+ /sassy-work <plan path> — one phase per session
25
+ /sassy-lfg <plan path> — every phase, then ship
26
+ ```
27
+
28
+ After `sassy-ship` closes the slice it prints the `mode:check` command.
@@ -0,0 +1,37 @@
1
+ # Mode: write — grill and write the goal
2
+
3
+ **Documents only.** This mode writes or revises `goal.md`. It never writes a slice plan, cuts a branch, edits code, or commits.
4
+
5
+ ## New goal (the argument is an idea)
6
+
7
+ 1. **Frame.** Restate the goal in one or two sentences — the outcome and why it needs more than one plan. Ask the user to confirm or correct it, and what they are already thinking.
8
+ 2. **Ground once, broadly.** Use `sassy-scout` on every domain the goal touches, in one run. Its brief feeds Landscape — what changes per domain, where (with `file:line` citations), and the blast radius — and seeds Risks and Coexistence. Do not re-scout per slice here; each slice's grill grounds its own detail.
9
+ 3. **Grill, bounded to the goal.** Read the `sassy-plan` skill's `references/interview.md` and follow it — the ledger, one question per turn with your recommendation, pushback, the read-back — but walk only goal-level branches:
10
+ - the domains in scope, and the non-goals
11
+ - slice boundaries and their order (Depends)
12
+ - coexistence: how the app runs mid-goal, old and new side by side, which flags
13
+ - the goal's Done when, including repo-wide checks (e.g. "no HTTP client imports left")
14
+ - decisions that bind more than one slice
15
+
16
+ Anything a single slice can settle alone — UI states, a table's columns, a helper's shape — goes to Deferred as *to S<n>'s grill*, with the user's agreement. Run the coverage sweep only against these goal-level rows; the rest are N/A until their slice starts.
17
+ 4. **Push back on incomplete slices.** Every slice must ship a working outcome on its own. A "schema first, API next, UI last" cut is the half-built layer this skill exists to prevent: challenge it with the evidence and offer a vertical re-cut (e.g. "one screen end to end on the new store"). Concede only to an argument or the user's explicit call, and record that call as `user-directed`.
18
+ 5. **Read back.** The whole ledger — decisions, constraints, the slice list with Ships / Depends, deferred items, assumptions — with an empty Open bucket. A correction reopens that branch.
19
+ 6. **Write.** Read `references/goal-format.md` and write `<artifacts.plans>/<goal-slug>/goal.md` with `**Status:** Active`, every slice `Pending`, and an empty Carry-forward.
20
+
21
+ ## Existing goal (the argument is a goal folder or `goal.md`)
22
+
23
+ 1. Read `goal.md`. If its status is `Done`, say so and stop unless the user asks to reopen it.
24
+ 2. Ask what changed, then grill **only the delta** with the same protocol: re-cut, add, drop, or reorder slices, or change a goal-level decision, Done-when item, or constraint. Everything else already in `goal.md` is settled ground.
25
+ 3. Keep history intact. `Done` slices, their plans, and every Carry-forward entry stay exactly as written. A `Planned` or `Shipped` slice is in flight: changing it is a contradiction to raise with the user, never a silent edit. New slices take the next free ID, so existing plan filenames never move.
26
+ 4. Apply the same pushback on incomplete slices, read back the delta, then update `goal.md` in place.
27
+
28
+ ## End
29
+
30
+ Report the absolute path of `goal.md`, the slice table, and the next command in the harness's syntax:
31
+
32
+ ```text
33
+ Goal written to <absolute path>. Start the first slice:
34
+ /sassy-goal <goal path> mode:next
35
+ ```
36
+
37
+ Stop there. Do not plan the first slice in this run.
@@ -7,7 +7,7 @@ description: >-
7
7
  via sassy-lfg.
8
8
  Sketches UI on request. No modes, no QA flags. Use when asked to brainstorm,
9
9
  scope, plan, or create a phased plan.
10
- argument-hint: "[feature description, requirements, or idea to scope]"
10
+ argument-hint: "[feature description, requirements, or idea to scope] [out:<plan path>]"
11
11
  ---
12
12
 
13
13
  # Sassy Plan
@@ -40,9 +40,13 @@ argument-hint: "[feature description, requirements, or idea to scope]"
40
40
 
41
41
  **UI work.** At the first layout, state, flow, or interaction-shape decision, say once that you can sketch it; when the user asks, read `references/sketches.md`.
42
42
 
43
+ ## Caller-set output
44
+
45
+ A caller that owns where the plan goes — `sassy-goal` planning a slice, for one — passes `out:<path>`. Grill exactly as usual, then read `references/plan-format.md`, write the plan to exactly that path, skip the picker entirely, and return the path to the caller. Do not offer `sassy-work` or `sassy-lfg`; the caller hands those over. Anything the caller passes as settled enters the ledger as settled, with its provenance, and is never re-asked.
46
+
43
47
  ## The picker
44
48
 
45
- Only when the read-back is confirmed with zero open items, present exactly these three options and stop until the user picks. Do not recommend one.
49
+ Only when the read-back is confirmed with zero open items — and no `out:` was given — present exactly these three options and stop until the user picks. Do not recommend one.
46
50
 
47
51
  ```text
48
52
  Settled. Pick one:
@@ -81,4 +85,4 @@ The plan document carries manual QA tables per `references/plan-format.md`. Thos
81
85
 
82
86
  If the user points at an existing sassy plan, update phases and tables in place. If they point at a raw plan from elsewhere, reshape it into this format without discarding its settled decisions — but grill whatever it leaves open or merely asserts. An existing plan is already the document.
83
87
 
84
- Decisions already settled earlier in the conversation carry forward per `references/interview.md`; never re-ask them.
88
+ Decisions already settled earlier in the conversation, or passed in by a caller as settled, carry forward per `references/interview.md`; never re-ask them.
@@ -65,8 +65,12 @@ config. This applies to every token these skills forward, not just `branch`.
65
65
  is a stop: cutting from local HEAD would carry commits stranded on the base
66
66
  into the new branch, and cutting from a missing upstream ref silently does
67
67
  exactly that. Name the count, the branch, and the choice.
68
- 3. Name it `<type>/<slug>` from the plan filename or the topic, deterministically,
69
- so a retried run converges on the same name instead of forking `-2`.
68
+ 3. Name it `<type>/<slug>` from the plan path or the topic, deterministically,
69
+ so a retried run converges on the same name instead of forking `-2`. The slug
70
+ is the plan's path relative to `artifacts.plans`, without `.md`: a standalone
71
+ plan stays `feat/<slug>`, and a goal slice nests as `<type>/<goal>/<NN-slice>`
72
+ (`feat/powersync/02-offline-reads`). A `feat/*`-style `base_map` or
73
+ `hooks.pr` family still matches the nested name by prefix.
70
74
  4. Re-run with `--name <name>` and take `pr-base` from that answer: a name like
71
75
  `release/1.2` or `hotfix/x` matches a `base_map` family and retargets the PR,
72
76
  and it also changes which `hooks.pr` pattern applies — a plan slug containing
@@ -80,7 +80,7 @@ hooks:
80
80
 
81
81
  | Key | Default | Meaning |
82
82
  |-----|---------|---------|
83
- | `artifacts.plans` | `docs/plans` | Where `sassy-plan` writes plans |
83
+ | `artifacts.plans` | `docs/plans` | Where `sassy-plan` writes plans, and where `sassy-goal` keeps goal folders (`<slug>/goal.md` plus slice plans) |
84
84
  | `artifacts.solutions` | `docs/solutions` | Where `sassy-compound` writes learnings |
85
85
  | `artifacts.handbooks` | `docs/handbooks` | Where `sassy-handbook` writes handbooks |
86
86
  | `artifacts.concepts` | `CONCEPTS.md` | The glossary file compound maintains |
@@ -28,7 +28,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
28
28
 
29
29
  ## Steps (in order)
30
30
 
31
- 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR" and that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run. In `mode:auto`, skip this gate.
31
+ 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, for a goal slice the `goal.md` change (slice → `Shipped`) and that babysit will not merge, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR" and that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run. In `mode:auto`, skip this gate.
32
32
  2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *load the `sassy-compound` skill and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
33
33
  3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *load the `sassy-handbook` skill and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
34
34
  4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
@@ -44,6 +44,8 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
44
44
 
45
45
  **One PR per run.** Babysitting a workspace fan-out means one `sassy-babysit` run per PR, and a fan-out is never auto-merged: `pr.merge` and `pr.merge:on` apply to a single-PR run only. A multi-repo merge needs an explicit per-PR say-so.
46
46
 
47
+ **Goal slices.** A plan that sits next to a `goal.md` is a `sassy-goal` slice. The step 4 commit worker sets that slice `Shipped` in `goal.md`'s slice table and names `goal.md` in the commit, since `sassy-commit` stages named files only. Step 6 babysits the PR **without merging** — forward `merge:off` whatever `pr.merge` or the caller says — because `sassy-goal` `mode:check` must run on the open PR first. End the final report with the `sassy-goal <goal path> mode:check` command in the harness's syntax.
48
+
47
49
  ## Rules
48
50
 
49
51
  | Rule | Requirement |
@@ -6,7 +6,7 @@ description: >-
6
6
  sassy-cycle. mode:manual (default) asks which to close, mode:auto closes all,
7
7
  mode:return only reports. Use when asked to verify conformance to a plan or
8
8
  intent. Leaves changes uncommitted.
9
- argument-hint: "[plan path + phase, or the intent to validate against] [mode:manual|auto|return]"
9
+ argument-hint: "[plan path [+ phase], or the intent to validate against] [range:<base>..<head>] [mode:manual|auto|return]"
10
10
  ---
11
11
 
12
12
  # Sassy Validate
@@ -33,8 +33,8 @@ Use the mode the caller passed; never pick one yourself.
33
33
 
34
34
  ## Workflow
35
35
 
36
- 1. **Intent.** Resolve the reference: a plan path plus phase (preferred), or an explicit intent the user states. If neither exists, ask and stop.
37
- 2. **Validate.** Dispatch the `validator` with that intent reference.
36
+ 1. **Intent.** Resolve the reference: a plan path plus phase (preferred), a plan path with no phase — the whole plan — or an explicit intent the user states. If none exists, ask and stop.
37
+ 2. **Validate.** Dispatch the `validator` with that intent reference. When the caller passed `range:<base>..<head>`, hand it to the validator as the commit range to validate; otherwise the validator scopes the work itself.
38
38
  3. **Return.** In `mode:return`, return the validator's grade, evidence, and gaps as-is and stop.
39
39
  4. **Conforms?** If the grade is `Conforms`, report it and stop. If `Blocked — insufficient grounding`, report what it needs and stop — do not guess.
40
40
  5. **Choose.** On `Partial` or `Diverges`, in `mode:manual` present the `Gaps` and ask which to close: all / specific / none. In `mode:auto`, take all.
@@ -45,7 +45,7 @@ Use the mode the caller passed; never pick one yourself.
45
45
 
46
46
  | Rule | Requirement |
47
47
  |------|-------------|
48
- | Intent required | Never validate without a plan phase or explicit intent. |
48
+ | Intent required | Never validate without a plan, a plan phase, or an explicit intent. |
49
49
  | Orchestrator only | Never edit code. The `validator` judges, `sassy-cycle` closes. |
50
50
  | Ask first | In `mode:manual`, never change code before the user picks. |
51
51
  | Gap-bound | Close only the chosen gaps. |