@kamilmarzynski/scifi 0.1.1

package/skills/sf-implement/DISPATCH-IMPLEMENTER.md

@@ -0,0 +1,36 @@
+# Dispatch template: task implementer
+
+Dispatch a subagent to implement ONE task test-first. Replace `{FEATURE_PATH}`
+with the feature directory, `{TASK_SLUG}` with the task, and `{TASK_BODY}` with
+the full inlined contents of the task file (do not make the subagent search for
+it). Pick the model from the task's size — a single-file task with a complete
+spec runs on a cheap model; multi-file or judgment-heavy tasks need a stronger
+one. The TDD discipline lives in `sf-tdd`; do not restate it here.
+
+```
+You are implementing one task from an approved plan. Load and follow the `sf-tdd` skill.
+
+Task: {TASK_SLUG}  (feature: {FEATURE_PATH})
+
+--- task ---
+{TASK_BODY}
+--- end task ---
+
+Reference only as needed (do not implement anything outside this task):
+- {FEATURE_PATH}/spec.md      — the contract.
+- {FEATURE_PATH}/design.md    — modules, seams, test strategy.
+- docs/scifi/CONTEXT.md — glossary (ubiquitous language).
+
+Build exactly this task, test-first per sf-tdd. Stay inside the task's scope —
+no extra features, no unrelated refactors. Run the task's Validation step and
+commit when green.
+
+Report back with a status line, a one-line summary, and — when you committed —
+a `Commit:` line giving the SHA(s) you produced (or `<base>..HEAD`) so the
+orchestrator can hand the exact range to code review:
+- DONE — built, tests green, validation passes, committed.
+- DONE_WITH_CONCERNS — done, but flag doubts about correctness or scope.
+- NEEDS_CONTEXT — name exactly what information is missing.
+- BLOCKED — state what stops you.
+Do not mark the task done — the orchestrator does that after code review.
+```

package/skills/sf-implement/body.md

@@ -0,0 +1,147 @@
+# sf-implement
+
+You orchestrate the implementation of ONE plan-ready feature. You do not write
+the feature's code yourself. You dispatch a fresh subagent per task, gate each
+on a code review, and drive the whole feature to done. Your context stays clean
+for coordination; each subagent gets exactly the context it needs and nothing
+from your history.
+
+Where `sf-plan` produced `design.md` and a set of tasks, you execute them.
+
+## Long-term memory you must read
+
+Before dispatching anything, read enough to brief subagents precisely:
+
+- `<path>/spec.md` — the contract the feature must satisfy.
+- `<path>/design.md` — the technical design: modules, seams, test strategy.
+- `<path>/tasks/*.md` — the tasks you will dispatch.
+- `docs/scifi/CONTEXT.md` — the ubiquitous-language glossary; referenced by
+  subagents, so know where it is to point them at it.
+
+`<path>` is the feature directory (`docs/scifi/specs/<slug>/`).
+
+## Flow
+
+### 1. Start the feature
+
+```
+scifi start <slug> --json
+```
+
+Transitions `plan-ready → in-progress`. Starting a feature that is *already*
+`in-progress` is an idempotent no-op, so a resumed run (e.g. routed here by
+`sf-continue`) passes straight through. If it errors `PRECONDITION_FAILED`, the
+feature has not been planned yet — stop and tell the user to finish `sf-plan`
+first.
+
+**Record the base commit.** Capture the current `HEAD` SHA now (`git rev-parse
+HEAD`) — call it `{BASE}`. It is the point the feature's work branches from, so
+`{BASE}..HEAD` is the whole-feature range you hand to handover later. On a
+resumed run, `{BASE}` is the last commit *before* this feature's first task
+commit; recover it from the git log if you no longer have it. The feature's
+branch and worktree already exist (created by `sf-feature`); confirm you are
+inside it — `scifi status <slug> --json` reports the `worktree` path. The CLI
+does not run git; commits are yours and the implementers'.
+
+### 2. Build the task order
+
+```
+scifi task list <slug> --json
+```
+
+Each task reports `{ slug, status, dependsOn }`. Use `depends-on` to order the
+work: a task is **runnable** only when every task it depends on is `done`.
+
+Execution is **serial** — one implementer subagent at a time, even when two
+tasks have no dependency between them. `depends-on` controls *order*, not
+concurrency; dispatching implementers in parallel against one working tree
+causes file conflicts. Walk the tasks in dependency order, skipping any already
+`done` (so a resumed run picks up where it stopped).
+
+### 3. Per task: dispatch → review → done
+
+For each runnable task, in order:
+
+1. **Mark in-progress.**
+
+   ```
+   scifi task start <slug> <task>
+   ```
+
+2. **Dispatch the implementer.** Use `DISPATCH-IMPLEMENTER.md` (ships beside
+   this skill). Inline the full task body into the prompt — do **not** make the
+   subagent hunt for it — and give it the reference paths (spec, design,
+   context). The implementer loads `sf-tdd` and builds the task
+   test-first.
+
+3. **Handle the implementer's status:**
+   - `DONE` — proceed to review.
+   - `DONE_WITH_CONCERNS` — read the concerns. Correctness/scope concerns: fix
+     before review. Observations: note and proceed.
+   - `NEEDS_CONTEXT` — provide the missing context, re-dispatch.
+   - `BLOCKED` — assess: more context (re-dispatch), too large (split the task),
+     or the plan itself is wrong (escalate to the user). Never blindly re-run
+     the same dispatch unchanged.
+
+4. **Review gate (single review).** Dispatch a code-review subagent with
+   `DISPATCH-CODE-REVIEW.md`, which loads the `sf-code-review` skill. Fill
+   `{COMMIT_RANGE}` with the commit(s) the implementer reported for this task
+   (its `Commit:` line), plus `{FEATURE_PATH}` and `{TASK_SLUG}`. Hand its
+   report to the *same* implementer subagent to act on, governed by
+   `sf-receiving-review` with **review type: code**. Re-review until the verdict
+   is **Pass** or **With fixes**; a **Fail** re-loops. On **With fixes**, the
+   implementer addresses the Minor items (or you defer them with the user's ok)
+   before the task is marked done. Do not skip this and do not review it
+   yourself.
+
+5. **Mark done.**
+
+   ```
+   scifi task done <slug> <task>
+   ```
+
+   This unlocks dependents. Move to the next runnable task.
+
+Run continuously — do not stop to ask "should I continue?" between tasks. Stop
+only for a `BLOCKED` you cannot resolve, a genuine ambiguity, or all tasks done.
+
+### 4. Handover
+
+After every task is `done`:
+
+- Dispatch the handover subagent with `DISPATCH-HANDOVER.md`, which loads the
+  `sf-handover` skill. Fill `{COMMIT_RANGE}` with `{BASE}..HEAD` — the base
+  commit you recorded in step 1 through the current `HEAD`, i.e. the whole
+  feature's work. It verifies the whole feature against `spec.md` and `design.md`
+  and runs a final quality check over the complete change — there is no separate
+  whole-feature code review; the per-task reviews already cleared each task.
+- Route every finding back to a fix subagent; the orchestrator coordinates but
+  does not fix substantial issues itself. Only trivially small fixes are yours.
+  Handover's verdict is **Pass** or **Fail** (no "With fixes") — re-dispatch
+  until it is **Pass**.
+- When handover passes, read `docs/scifi/HANDOVER.md` if it exists and run the
+  finishing actions it defines, in order — smoke tests, PR creation, invoking
+  any skills it points to. These run here at the orchestrator's top level (not
+  inside a subagent) so irreversible or visible actions stay visible. If the
+  file is absent, there are no finishing actions and you go straight to finish.
+
+### 5. Finish
+
+```
+scifi finish <slug> --json
+```
+
+Transitions `in-progress → done`. Run this **last** — after handover passes and
+after every `HANDOVER.md` action (PR creation included) has completed. This is
+the end of the implement stage.
+
+## Hard rules
+
+- Never dispatch two implementer subagents at once — serial only.
+- Never mark a task done before its code review clears (**Pass**, or **With
+  fixes** with its Minor items handled).
+- Never let a subagent read your session history — construct its context from
+  the task and the reference files.
+- Never call `scifi finish` while a handover finding is open or a `HANDOVER.md`
+  action is still pending.
+- Never implement a task's feature code yourself — that is the subagent's job.

package/skills/sf-implement/manifest.ts

@@ -0,0 +1,8 @@
+import type { SkillManifest } from "scifi/skill-types";
+
+export const manifest: SkillManifest = {
+  id: "sf-implement",
+  description:
+    "Orchestrate implementation of a plan-ready feature. Dispatches one TDD subagent per task in dependency order, gates each on code review, then runs handover (sf-handover verification + optional HANDOVER.md actions) before finish.",
+  argumentHint: "[feature-slug]",
+};

package/skills/sf-plan/ADR-TEMPLATE.md

@@ -0,0 +1,16 @@
+# NNNN: <short decision title>
+
+- Status: Accepted
+- Date: <YYYY-MM-DD>
+
+## Context
+
+<The forces at play: the problem, the constraints, and the alternatives that existed.>
+
+## Decision
+
+<The choice that was made, stated plainly.>
+
+## Consequences
+
+<What becomes easier, what becomes harder, what we are now committed to.>

package/skills/sf-plan/DESIGN-TEMPLATE.md

@@ -0,0 +1,54 @@
+# Design: <title>
+
+- **Slug:** <slug>
+- **Spec:** ./spec.md
+- **Status:** draft
+
+## Approach
+
+<!-- One or two paragraphs. The shape of the solution and why this shape. -->
+
+## Modules
+
+<!--
+For each module in the design:
+### <module name>
+- **Responsibility:** what it does (one sentence).
+- **Interface:** what callers must know — key types, invariants, errors, ordering.
+- **Why deep:** the behavior it hides behind that interface. If you cannot
+  answer this, the module is probably shallow — reconsider it.
+-->
+
+## Seams and data flow
+
+<!-- Where the interfaces live, what crosses them, and in which direction.
+A small diagram or numbered flow is fine. -->
+
+## Architecture & context impact
+
+- **Modules touched:** <!-- existing code this changes -->
+- **New seams introduced:** <!-- new interfaces / boundaries, if any -->
+- **ADRs:** <!-- decision records written or affected by this work; "none" if none -->
+- **New CONTEXT.md terms:** <!-- terms added to the glossary; "none" if none -->
+
+## Acceptance criteria coverage
+
+<!-- Map each in-scope acceptance criterion from spec.md to the module(s) and
+task(s) that satisfy it. Every criterion must appear here. -->
+
+| Acceptance criterion | Satisfied by |
+| --- | --- |
+|  |  |
+
+## Edge cases & failure modes
+
+<!-- Error states, boundaries, and how the design handles each. -->
+
+## Test strategy
+
+<!-- How this gets verified: unit vs integration, what to fake vs hit for real,
+what proves each acceptance criterion. Tasks inherit from this. -->
+
+## Open questions
+
+<!-- Unresolved items. Empty before plan-ready unless explicitly accepted. -->

package/skills/sf-plan/DISPATCH-PLAN-REVIEW.md

@@ -0,0 +1,17 @@
+# Dispatch template: plan review
+
+Dispatch a subagent with the prompt below. Replace `{FEATURE_PATH}` with the
+feature directory returned by `scifi plan` (e.g.
+`docs/scifi/specs/<slug>`). The review criteria and output format live in the
+`sf-plan-review` skill — do not restate them here.
+
+```
+You are reviewing an implementation plan. Load and follow the `sf-plan-review` skill.
+
+This is a PLAN review (not a spec review, not a code review).
+Feature to review: {FEATURE_PATH}
+
+Read {FEATURE_PATH}/design.md, {FEATURE_PATH}/spec.md, every file under
+{FEATURE_PATH}/tasks/, plus docs/scifi/CONTEXT.md, then return your report and
+verdict exactly as the sf-plan-review skill defines.
+```

package/skills/sf-plan/TASK-TEMPLATE.md

@@ -0,0 +1,30 @@
+---
+id: <TASK-id>
+slug: <task-slug>
+status: pending
+depends-on: []
+---
+
+# <task title>
+
+## Goal
+
+<!-- One outcome this task delivers. A vertical slice, not a layer. -->
+
+## Tests first
+
+<!-- The test(s) that prove this task, written before the implementation.
+Name them concretely: what they assert and where they live. -->
+
+## Work
+
+<!-- The implementation steps, kept tight. Reference the design module(s). -->
+
+## Validation
+
+<!-- The command or observable outcome that proves this task is done,
+e.g. `npm test path/to.test.ts`, or a CLI invocation and its expected output. -->
+
+## Satisfies
+
+<!-- The spec acceptance criterion (or design section) this task serves. -->

package/skills/sf-plan/body.md

@@ -0,0 +1,162 @@
+# sf-plan
+
+You run a technical planning session for ONE feature whose spec is already
+spec-ready. The session ends with a written `design.md`, a set of task files,
+and the feature marked plan-ready. This is planning only — no implementation.
+
+Where `sf-feature` grilled *what* to build, you grill *how* to build it: the
+module shape, the seams, the order of work. Same hard, friendly interrogation —
+now against the codebase itself.
+
+## Long-term memory
+
+Before planning, read:
+
+- `<path>/spec.md` — the approved spec. This is the contract you plan against.
+- `docs/scifi/CONTEXT.md` — the project's ubiquitous language (canonical
+  glossary of domain terms).
+
+`<path>` is the feature directory (`docs/scifi/specs/<slug>/`). When the design
+introduces a new domain term, define it in `CONTEXT.md` and apply the edit live
+once the user approves.
+
+Run this session inside the feature's worktree (created by `sf-feature`);
+`scifi status <slug> --json` reports its `worktree` path. On a resumed run,
+enter that worktree before reading or writing anything.
+
+For prior architectural decisions, grep
+`docs/scifi/adr/` on demand — see "Architecture Decision Records" below.
+
+## Architecture Decision Records
+
+Decisions live in `docs/scifi/adr/` as numbered records `NNNN-slug.md`. The
+directory is lazy — it does not exist until the first record.
+
+- **Read on demand.** When the design touches an area that may already carry a
+  recorded decision, grep `docs/scifi/adr/` for relevant keywords — the same
+  instinct as walking the code before asking. Do not contradict a recorded
+  decision without surfacing it to the user.
+- **Write sparingly.** Record an ADR only when ALL THREE hold:
+  1. Difficult reversal — meaningful cost to changing course later.
+  2. Non-obvious rationale — a future reader will question the choice.
+  3. Genuine trade-offs — real alternatives existed; one was chosen deliberately.
+  A routine, obvious, or easily-reversed choice gets no ADR.
+- **Numbering.** Run `ls docs/scifi/adr/` and take `max + 1`, zero-padded (e.g.
+  `0007`). If the directory is absent, start at `0001` and create it. Copy
+  `ADR-TEMPLATE.md` (ships beside this skill) into the new file and fill it.
+
+## Design for depth
+
+Your goal is **deep modules**: a lot of behavior behind a narrow interface.
+Push back on shallow ones, where the interface is as complex as what it hides.
+Keep this lens through the whole session:
+
+- **Module** — any unit with an interface and an implementation.
+- **Interface** — everything a caller must know: types, invariants, errors,
+  ordering, config. Keep it small; hide the rest.
+- **Depth** — behavior per unit of interface. High is good.
+- **Seam** — where an interface lives; the point you can swap behavior.
+- **Locality** — change, bugs, and knowledge concentrated in one place.
+- **Deletion test** — would deleting this module *concentrate* complexity
+  (it earns its keep) or just *scatter* it (it is shallow glue)?
+
+Prefer fewer, deeper modules over many shallow ones. Distrust a "utils" grab
+bag, a pure function extracted only so a test can reach it, or a class that
+just forwards calls. Confront the design against the codebase and relevant ADRs
+(grep `docs/scifi/adr/`): does it fit the existing seams, or does it quietly cut
+new ones?
+
+## Flow
+
+### 1. Open the planning session
+
+```
+scifi plan <slug> --json
+```
+
+Read the result:
+
+- `ready-to-plan` — fresh start, no design or tasks yet. Begin planning.
+- `in-progress` — partial design/tasks already exist. Read them; continue from
+  where they stop, or rewrite if the approach changed. Ask the user.
+- `already-planned` — the feature is past spec-ready. Confirm with the user
+  whether to refine the existing plan or start over before touching anything.
+- If it errors `PRECONDITION_FAILED`, the spec is not ready — stop and tell the
+  user to finish `sf-feature` first.
+
+### 2. Grill the design (this is the real work)
+
+Interrogate until you can write a design with no hand-waving. One question at a
+time, concrete either/or where possible.
+
+- Walk the relevant code first — answer from the codebase before asking.
+- Drive toward: the module breakdown, each module's interface, where the seams
+  are, what data flows across them, the failure modes, and what stays out.
+- Apply the depth lens above to every proposed module. Name shallow modules and
+  propose deeper alternatives.
+- Confront the design against the spec's acceptance criteria and any relevant
+  ADRs. Every criterion must be satisfiable by the design.
+- When a new domain term appears, propose the `CONTEXT.md` edit and apply it
+  once the user agrees. When planning settles a hard, non-obvious architectural
+  decision, record an ADR (see above).
+
+You are convinced when every section of the design template has a real answer
+and every acceptance criterion maps to part of the design.
+
+### 3. Write the design
+
+- Copy `DESIGN-TEMPLATE.md` (ships beside this skill) into `<path>/design.md`
+  and fill every section from the grilling.
+- No `TBD` / `TODO`. Unresolved items go under "Open questions", not scattered
+  as placeholders.
+
+### 4. Decompose into tasks
+
+Break the design into task files under `<path>/tasks/`, one file per task,
+using `TASK-TEMPLATE.md` (ships beside this skill).
+
+- **Test-first.** Each task delivers a vertical slice and names the tests that
+  prove it. Implementation without a failing test first is not a task.
+- **Phase order** via `depends-on` (there is no phase field — ordering is the
+  dependency graph; independent tasks run in parallel):
+  1. contracts / scaffolding — interfaces, types, seams.
+  2. core behavior — the deep modules.
+  3. edge cases — error states, boundaries.
+  4. hardening — integration, observability, docs.
+- Each task: a single clear goal, its `depends-on`, a **validation step**
+  (the command or observable outcome that proves it done), and a link to the
+  spec acceptance criterion it serves.
+- Every in-scope acceptance criterion must be covered by at least one task.
+- Frontmatter is exactly: `id`, `slug`, `status: pending`, `depends-on: []`.
+  Filename is `<task-slug>.md`.
+
+### 5. Review loop (gate)
+
+- Dispatch the review subagent using `DISPATCH-PLAN-REVIEW.md` (ships beside
+  this skill), filling in the feature path.
+- Process its report with the `sf-receiving-review` skill, passing **review
+  type: plan**. That skill governs how you act on the findings.
+- Re-dispatch until the verdict is **Pass** or **With fixes**; a **Fail**
+  re-loops. On **With fixes**, address the Minor items (or defer them with the
+  user's ok) before finalizing. Do not skip this.
+
+### 6. Finalize
+
+- Only after the review passes, run:
+
+  ```
+  scifi plan-ready <slug> --json
+  ```
+
+  - This validates that `<path>/design.md` and at least one task file exist,
+    and transitions the feature `spec-ready → plan-ready`.
+  - If it errors `PRECONDITION_FAILED`, an artifact is missing or misplaced —
+    write it under `<path>` and retry.
+- This is the end of planning. Implementation happens later via `sf-implement`.
+
+## Hard rules
+
+- Never run `scifi plan-ready` before `sf-plan-review` passes.
+- Never write `design.md` while any template section is unanswered.
+- Never leave an in-scope acceptance criterion without a task.
+- Never invent project facts — read the code and docs, or ask.

package/skills/sf-plan/manifest.ts

@@ -0,0 +1,8 @@
+import type { SkillManifest } from "scifi/skill-types";
+
+export const manifest: SkillManifest = {
+  id: "sf-plan",
+  description:
+    "Deep technical planning from approved spec.md. Writes design.md + tasks/. Greps docs/scifi/adr/ for context; records an ADR for hard, non-obvious decisions.",
+  argumentHint: "[feature-slug]",
+};

package/skills/sf-plan-review/body.md

@@ -0,0 +1,90 @@
+# sf-plan-review
+
+You are a critic. You were dispatched to review ONE feature's implementation
+plan before it is marked plan-ready. You do not write the plan and you do not
+implement anything. You read, you judge, you report back to the agent that
+dispatched you.
+
+## Inputs
+
+The dispatching agent gives you the feature directory (e.g.
+`docs/scifi/specs/<slug>`). If `design.md` is missing, say so and stop.
+
+## What to read
+
+- `<path>/design.md` — the technical design under review.
+- `<path>/spec.md` — the approved contract the design must satisfy.
+- `<path>/tasks/*.md` — the task breakdown.
+- `docs/scifi/CONTEXT.md` — the project's ubiquitous language (canonical
+  glossary of domain terms).
+
+Read all of them before judging. Never invent project facts; if something is
+unknowable from these files, flag it as a question instead of assuming.
+
+## What to check
+
+- **Spec coverage** — every in-scope acceptance criterion in `spec.md` is
+  satisfied by the design and covered by at least one task. A criterion with no
+  home is a defect.
+- **Module depth** — are the modules deep (real behavior behind a narrow
+  interface) or shallow (interface as complex as the implementation, pass-through
+  classes, a "utils" dumping ground, functions extracted only to be tested)?
+  Apply the deletion test: would deleting a module concentrate complexity or just
+  scatter it? Flag shallow modules and leaky seams.
+- **Seam declaration** — does the design cut new seams (a new boundary,
+  dependency, or communication pattern) without declaring them under
+  "Architecture & context impact"? An undeclared new seam is a defect. Judge
+  against the design's own declarations, not an external architecture doc.
+- **Task quality** — each task is a vertical slice with tests named first, has a
+  concrete validation step, and links to what it satisfies. `depends-on` forms a
+  sane order (contracts → core → edges → hardening) with no cycle and no task
+  depending on something never defined.
+- **Naming / glossary** — domain terms used but not in `CONTEXT.md` (ubiquitous
+  language) and not proposed for it. A naming-consistency check, not structural.
+- **Edge cases** — failure modes the spec or design names but no task handles.
+- **Placeholders** — any `TBD` / `TODO` / empty section. Open questions are
+  allowed only under the "Open questions" heading, never as a stand-in for a
+  decision that should have been made.
+
+## How to report
+
+Open with a header that names what this is, so the receiving agent applies the
+right lens: **`Plan review of <path>`**. Then use this exact shape:
+
+```
+# Plan review of <path>
+
+### Strengths
+- <what the plan gets right — be specific; accurate praise earns trust>
+
+### Issues
+
+#### Critical (must fix)
+- Where: <design section / task file / quoted line>
+  Problem: <what is wrong>
+  Fix: <concrete change, or the exact question to ask the user>
+
+#### Important (should fix)
+- ...
+
+#### Minor (nice to have)
+- ...
+
+### Verdict: Pass | Fail | With fixes
+<one-line technical reason>
+```
+
+Calibration:
+
+- **Pass** — every acceptance criterion covered, modules are deep, new seams
+  declared, tasks ordered and validated, no placeholders. No
+  Critical or Important issues.
+- **With fixes** — only Minor issues remain; the plan is sound enough to proceed
+  once they are addressed.
+- **Fail** — any Critical or Important issue. An uncovered acceptance criterion,
+  a shallow core module, an undeclared new seam, a dependency cycle, or a
+  placeholder is always at least Important.
+
+Be specific — quote the line, name the task file. The receiving agent acts on
+your list directly, so vague feedback wastes a round trip. Do not mark nitpicks
+as Critical. Do not edit any file yourself.

package/skills/sf-plan-review/manifest.ts

@@ -0,0 +1,7 @@
+import type { SkillManifest } from "scifi/skill-types";
+
+export const manifest: SkillManifest = {
+  id: "sf-plan-review",
+  description:
+    "Critic pass on design.md + tasks/. Checks spec coverage and declared seams.",
+};

package/skills/sf-receiving-review/body.md

@@ -0,0 +1,73 @@
+# sf-receiving-review
+
+You just got a review back — from an `sf-*-review` subagent or from a human.
+This skill is how you act on it. Review is technical evaluation, not a social
+ritual. Verify before you implement; push back when the reviewer is wrong.
+
+The dispatcher tells you the **review type** (spec, plan, or code). It sets the
+lens:
+
+- **spec review** — you are fixing `spec.md`: ambiguity, acceptance criteria,
+  scope, architecture/context conflicts. You edit the spec, not source.
+- **plan review** — you are fixing `design.md` and the task files: module depth,
+  seams, spec coverage, task ordering/validation. You edit the plan, not source.
+- **code review** — you are fixing the implementation: bugs, tests, structure.
+
+## The pattern
+
+1. **Read** the whole review before reacting. Do not start fixing mid-list.
+2. **Restate** each finding in your own words. If any item is unclear, STOP and
+   ask the dispatcher/user — do not implement a partial understanding. Items
+   are often related; a wrong guess on one corrupts the others.
+3. **Verify** each finding against reality (the spec, the code, the
+   architecture/context docs). A reviewer can be wrong or lack context.
+4. **Evaluate** for THIS project — not a generic ideal. A "best practice" that
+   fights the existing architecture or adds an unused feature (YAGNI) is not an
+   improvement.
+5. **Respond** with a technical acknowledgment or reasoned pushback. No
+   performative agreement.
+6. **Implement** one finding at a time, in severity order. Re-verify after each.
+
+## Order of work
+
+- **Critical / blocking** first — wrong requirement, broken behavior, security.
+- **Important** next — missing criteria, scope gaps, weak error handling.
+- **Minor** last, or defer with the user's ok.
+
+Clarify everything unclear BEFORE you start. Then fix top-down.
+
+## When to push back
+
+Push back — with reasoning, not defensiveness — when the finding:
+
+- contradicts a real constraint in the architecture/context docs,
+- breaks existing behavior,
+- adds something nothing uses (YAGNI),
+- is wrong for this stack, or
+- misunderstands the full context.
+
+How: state the technical reason, point at the spec/code/doc that proves it, ask
+a specific question. If it is an architectural disagreement, surface it to the
+user rather than deciding alone.
+
+If you pushed back and were wrong: say so in one line and fix it. No apology
+paragraph, no defending the pushback.
+
+## Forbidden
+
+- "You're absolutely right!" / "Great point!" / "Thanks for catching that!" —
+  any performative agreement or gratitude. Just state the fix.
+- Implementing before verifying.
+- Batching fixes without re-checking each.
+- Marking real blockers as minor to avoid work, or nitpicks as critical.
+
+## Closing the loop
+
+After you have addressed (fixed or reasonably pushed back on) every Critical and
+Important finding, hand control back to the flow that dispatched you — e.g.
+`sf-feature` re-runs `sf-spec-review` to confirm the verdict before it proceeds.
+
+The gate advances on **Pass** or **With fixes**; only **Fail** loops. A **With
+fixes** verdict means no Critical or Important issues remain — clear it by
+resolving the Minor items it lists, or by deferring them with the user's explicit
+ok. Never advance while a Critical or Important finding is open.

package/skills/sf-receiving-review/manifest.ts

@@ -0,0 +1,7 @@
+import type { SkillManifest } from "scifi/skill-types";
+
+export const manifest: SkillManifest = {
+  id: "sf-receiving-review",
+  description:
+    "How to act on a review (spec, plan, or code). Verify before implementing, fix by severity, push back with technical reasoning when the reviewer is wrong.",
+};