@lovehlmmm/primekit 1.0.0

package/skills/cook/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: pk:cook
+description: "Implement features, plans, and fixes with structured workflow. Use for feature development, plan execution, code implementation pipelines."
+user-invocable: true
+when_to_use: "Invoke to implement known scope after requirements are clear."
+category: utilities
+keywords: [implementation, workflow, feature, pipeline]
+argument-hint: "[task|plan-path] [--interactive|--fast|--parallel|--auto|--no-test] [--tdd] [--advice] [--yagni] [--skip-journal]"
+metadata:
+  author: primekit
+  version: "2.3.0"
+  workflow:
+    follows: [primekit-plan]
+    precedes: [primekit-test]
+---
+
+# Cook - Smart Feature Implementation
+
+End-to-end implementation with automatic workflow detection.
+
+**Principles:** KISS, DRY | Full requested scope, nothing extra (`--yagni` to opt into scope-cutting) | Token efficiency | Concise reports
+
+## Usage
+
+```
+/pk:cook <natural language task OR plan path>
+```
+
+**IMPORTANT:** If no flag is provided, the skill will use the `interactive` mode by default for the workflow.
+
+**Optional flags to select the workflow mode:** 
+- `--interactive`: Full workflow with user input (**default**)
+- `--fast`: Skip research, scout→plan→code
+- `--parallel`: Multi-agent execution
+- `--no-test`: Skip testing step
+- `--auto`: Auto-approve all steps
+
+**Composable flags** (combine with any mode):
+- `--tdd`: Tests-first per phase — write tests for current behavior before
+  refactoring, then verify they still pass after the implementation step
+- `--advice`: Run under `kongming` advisory supervision (see Advisory
+  supervision)
+- `--yagni`: Opt into YAGNI — challenge and cut scope not needed for the stated
+  outcome. Default is to implement the full requested scope
+
+**Example:**
+```
+/pk:cook "Add user authentication to the app" --fast
+/pk:cook path/to/plan.md --auto
+/pk:cook "Refactor auth middleware" --tdd
+```
+
+## Advisory supervision (`--advice`)
+
+When `--advice` is present, run this skill under `kongming` supervision.
+Load `../primekit-brainstorm/references/advisory-supervision.md` for supervisor
+identity, host detection, and model routing (Claude subscription → Fable 5;
+Codex → `gpt-5.6-sol` + high effort; Cursor → `claude-fable-5-high`).
+
+Spawn `kongming` at these checkpoints:
+
+- **After each phase completes** — pass the phase goal, what changed, and the
+  evidence; ask for a go/no-go and the next risk to watch before the next phase.
+- **When stuck** — repeated failures, a blocked step, or contradictory evidence;
+  pass everything already tried and the exact obstacle.
+- **Before a high-stakes decision** — a design fork, a public-contract or
+  security-sensitive change, or an irreversible action; get counsel first.
+
+**When the workflow reaches a PR** (e.g. handed off to the installed ship
+skill): pass `--advice` to the downstream skill so supervision persists across
+the handoff. Watch and fix CI until every required check is green, then spawn
+`kongming` to review the whole implementation and post its assessment plus
+concrete next steps as a comment directly on the PR and the source issue (when
+one exists).
+
+<HARD-GATE-BRAINSTORM-FIRST>
+Before planning or implementation, capture the opening brainstorm contract:
+outcome, constraints, non-goals, and observable acceptance criteria.
+
+- If the input is an accepted plan or design, reuse those fields and identify
+  only material gaps.
+- If the input is a natural-language task, state the fields from the request and
+  ask only about a missing decision that would change the result or safety.
+- `--fast`, `--parallel`, and `--auto` change execution shape, not this gate.
+- Route concrete bugs to `/pk:fix`; it frames intent first, then proves the root
+  cause before selecting a solution.
+</HARD-GATE-BRAINSTORM-FIRST>
+
+<HARD-GATE>
+Do NOT write implementation code until a plan exists and has been reviewed.
+This applies regardless of task simplicity. "Simple" tasks are where unexamined assumptions waste the most time.
+Exception: `--fast` mode skips research but still requires a plan step.
+User override: If user explicitly says "just code it" or "skip planning", respect their instruction.
+</HARD-GATE>
+
+<HARD-GATE-SCOUT-FIRST>
+After the opening brainstorm gate and before planning, scan the codebase.
+Mandatory scout outputs:
+1. Project type, language(s), framework(s)
+2. Existing modules/files relevant to the task
+3. Current patterns/conventions for similar features (so the implementation matches them)
+4. Existing docs in `./docs/` and any in-flight plans in your configured plans dir (`plans/` by default) covering this area
+5. Public APIs, schemas, contracts that the task could affect
+
+State a concise codebase-context summary before asking any further questions.
+Skip only when an accepted plan already contains current scout evidence.
+</HARD-GATE-SCOUT-FIRST>
+
+<HARD-GATE-EXACT-REQUIREMENTS>
+Before producing a plan, the brainstorm contract must be concrete and scout
+evidence must identify likely touchpoints and stable public contracts. Ask only
+for a material requirement that neither the request, accepted plan, nor current
+evidence resolves. Ground questions in discovered paths and behavior.
+</HARD-GATE-EXACT-REQUIREMENTS>
+
+<HARD-GATE-NO-SIDE-EFFECTS>
+Implementation is NOT done until verified to be side-effect-free. Code-review and test gates MUST prove:
+
+1. New behavior matches every acceptance criterion above.
+2. All tests pass — including tests in modules that share files/contracts with the change.
+3. No existing business logic / workflow regression: explicitly walk each touchpoint and any caller of changed functions.
+4. No new lint/type/build errors anywhere in the repo.
+5. Public contracts unchanged unless intentional and called out (function signatures, exported types, API responses, DB schemas, env vars, config keys).
+
+User override: If user invoked `--no-test`, item 2 is downgraded to a warning. Surface the unverified-tests risk in the finalize `ask_user capability` so the user accepts the trade-off rather than having it silently chosen. Items 1, 3, 4, 5 remain enforceable via the mandatory `code-reviewer` subagent.
+
+If review/testing reveals a side effect, regression, or broken workflow, STOP. Use `ask_user capability` to present:
+- What broke (file, test, workflow, user-facing behavior)
+- Why this implementation caused it (1-line cause)
+- 2-4 concrete options for the user to choose, e.g.:
+  - "Revert this slice and re-plan with stricter scope"
+  - "Keep the implementation and update <dependents> to match the new contract"
+  - "Add a compatibility shim at <boundary> so old callers keep working"
+  - "Accept the regression — old behavior was unintended/buggy"
+
+Let the user decide. Do not silently patch around regressions.
+</HARD-GATE-NO-SIDE-EFFECTS>
+
+## Anti-Rationalization
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to plan" | Simple tasks have hidden complexity. Plan takes 30 seconds. |
+| "I already know how to do this" | Knowing ≠ planning. Write it down. |
+| "Let me just start coding" | Undisciplined action wastes tokens. Plan first. |
+| "The user wants speed" | Fastest path = plan → implement → done. Not: implement → debug → rewrite. |
+| "I'll plan as I go" | That's not planning, that's hoping. |
+| "Just this once" | Every skip is "just this once." No exceptions. |
+
+## Smart Intent Detection
+
+| Input Pattern | Detected Mode | Behavior |
+|---------------|---------------|----------|
+| Path to `plan.md` or `phase-*.md` | code | Execute existing plan |
+| Contains "fast", "quick" | fast | Skip research, scout→plan→code |
+| Contains "trust me", "auto" | auto | Auto-approve all steps |
+| Lists 3+ features OR "parallel" | parallel | Multi-agent execution |
+| Contains "no test", "skip test" | no-test | Skip testing step |
+| Default | interactive | Full workflow with user input |
+
+See `references/intent-detection.md` for detection logic.
+
+If the task needs a cross-skill workflow sequence decision after intent
+detection, load `references/workflow-routing.md`.
+
+## Process Flow (Authoritative)
+
+```mermaid
+flowchart TD
+    A[Capture or reuse brainstorm contract] --> A2[Intent Detection]
+    A2 --> B{Has accepted plan path?}
+    B -->|Yes| F[Load Plan and current evidence]
+    B -->|No| C{Mode?}
+    C -->|fast| D[Scout → Plan → Code]
+    C -->|interactive/auto/parallel/no-test| SC[Scout Codebase MANDATORY]
+    SC --> SR[Summarize Findings to User]
+    SR --> RQ{Brainstorm contract concrete?<br/>outcome, constraints, non-goals, acceptance}
+    RQ -->|No| SR
+    RQ -->|Yes| E[Research → Review → Plan]
+    E --> F
+    D --> F
+    F --> G[Review Gate]
+    G -->|approved| H[Implement]
+    G -->|rejected| E
+    H --> H1{Simplify signal?}
+    H1 -->|Yes| H2[Conditional Simplify]
+    H1 -->|No| I[Review Gate]
+    H2 --> I
+    I -->|approved| J{--no-test?}
+    J -->|No| K[Test]
+    J -->|Yes| L[Finalize]
+    K --> L
+    L --> M[Report + Journal]
+```
+
+**This diagram is the authoritative workflow.** Prose sections below provide detail for each node. If prose conflicts with this flow, follow the diagram.
+
+## Workflow Overview
+
+```
+[Brainstorm Contract] → [Intent Detection] → [Inspect/Research?] → [Review] → [Plan] → [Review] → [Implement] → [Conditional Simplify?] → [Review] → [Test?] → [Review] → [Finalize]
+```
+
+**Default (non-auto):** Stops at `[Review]` gates for human approval before each major step.
+**Auto mode (`--auto`):** Skips human review gates, implements all phases continuously.
+**Progress tracking:** Discover the live task-management surface at runtime and
+use it when available. Otherwise, update the active plan directly. Plan files
+are the durable source of truth; do not infer support from cached tool lists.
+
+**Plan resolution (files-first):** when the input is a plan path or an
+existing plan is in scope, resolve it via the CLI current-plan pointer
+(`primekit plan use`) first, falling back to `primekit plan resolve` for the current
+repo/branch/worktree. Read phase content with `primekit plan show` (or the files
+directly) and mutate status only through `primekit plan` file-mutating commands
+(`check`/`uncheck`/`update`/`status`) — never from GitHub issue comments, and
+never require a linked issue to resolve or progress a plan. See
+`references/plan-state-files-first.md` for the full model.
+
+| Mode | Research | Testing | Review Gates | Phase Progression |
+|------|----------|---------|--------------|-------------------|
+| interactive | ✓ | ✓ | **User approval at each step** | One at a time |
+| auto | ✓ | ✓ | Per `references/review-cycle.md` | All at once (no stops) |
+| fast | ✗ | ✓ | **User approval at each step** | One at a time |
+| parallel | Optional | ✓ | **User approval at each step** | Parallel groups |
+| no-test | ✓ | ✗ | **User approval at each step** | One at a time |
+| code | ✗ | ✓ | **User approval at each step** | Per plan |
+
+## Step Output Format
+
+```
+✓ Step [N]: [Brief status] - [Key metrics]
+```
+
+## Blocking Gates (Non-Auto Mode)
+
+Human review required at these checkpoints (skipped with `--auto`):
+- **Post-Research:** Review findings before planning
+- **Post-Plan:** Approve plan before implementation
+- **Post-Implementation:** Approve code before testing
+- **Post-Testing:** 100% pass + approve before finalize
+
+**Always enforced (all modes):**
+- **Testing:** 100% pass required (unless no-test mode)
+- **Code Review (MANDATORY):** Spawn `code-reviewer` subagent with explicit checks:
+  (a) every acceptance criterion met,
+  (b) no regression to business logic in touchpoints/blast-radius,
+  (c) no breaking changes to public contracts (signatures, schemas, APIs, env vars) unless called out,
+  (d) follows existing patterns from scout,
+  (e) no new lint/type/build errors anywhere.
+  Pass scout summary + acceptance criteria as context. If reviewer flags side effects → trigger HARD-GATE-NO-SIDE-EFFECTS (`ask_user capability` with 2-4 options).
+  Then: user approval or the auto-mode decision in `references/review-cycle.md`.
+- **Finalize (MANDATORY - never skip):**
+  1. **Activate `the engineer project-management skill` skill (MANDATORY)** → run full plan sync-back across ALL `phase-XX-*.md` (not only current phase), update `plan.md` status/progress, refresh runtime tracking when available, generate progress report
+  2. Evaluate docs impact; use `docs-manager` only for affected routed authority surfaces
+  3. After sync-back verification, reflect completion in the live task-management surface when available
+  4. Ask user if they want to commit via `git-manager` subagent
+  5. Run `/pk:journal` to write a concise technical journal entry upon completion — unless the shared "Journal step — opt-out" below applies.
+
+### Journal step — opt-out
+
+Skip the automatic `/pk:journal` step when either applies:
+- The invocation includes the `--skip-journal` flag, OR
+- `primekit config prefs resolve --json | jq -r 'if .prefs.journal.auto == false then "false" else "true" end'` returns `false`. If the command errors or prints anything other than the exact string `false`, treat as `true` (default) — corrupt or missing config never suppresses the automatic journal.
+
+Precedence: flag > project config > user config > default (`true`).
+When skipped, print one line:
+- `journal skipped by --skip-journal` (flag), or
+- `journal skipped by preference` (config).
+
+Explicit `/pk:journal` and `primekit journal create` are unaffected. The rest of the Finalize block above stays MANDATORY.
+
+## Required Subagents (MANDATORY)
+
+| Phase | Subagent | Requirement |
+|-------|----------|-------------|
+| Research | `researcher` | Optional in fast/code |
+| Scout | `pk:scout` | Optional in code |
+| Plan | `planner` | Optional in code |
+| UI Work | `ui-ux-designer` | If frontend work |
+| Testing | `tester`, `debugger` | **MUST** spawn |
+| Review | `code-reviewer` | **MUST** spawn |
+| Finalize | `the engineer project-management skill`; conditional `docs-manager`; configured git workflow | Project sync and docs-impact decision are mandatory |
+
+**CRITICAL ENFORCEMENT:**
+- Steps 4, 5, 6 **MUST** use the live delegation capability to spawn subagents
+- DO NOT implement testing, review, or finalization yourself - DELEGATE
+- If workflow ends without the required delegations, it is INCOMPLETE
+- Pattern: `delegate_agent capability(subagent_type="[type]", prompt="[task]", description="[brief]")`
+- If the user passed `--yagni`, include it in every subagent prompt and pass it
+  to downstream skills, so the opt-in survives the handoff. Without it the
+  delegate defaults to delivering the full requested scope.
+
+## References
+
+- `references/intent-detection.md` - Detection rules and routing logic
+- `references/workflow-routing.md` - Cross-skill sequence routing for ambiguous workflows
+- `references/workflow-steps.md` - Detailed step definitions for all modes
+- `references/review-cycle.md` - Interactive and auto review processes
+- `references/subagent-patterns.md` - Subagent invocation patterns
+- `references/plan-state-files-first.md` - Canonical plan-file model, `primekit plan` index, and optional GitHub projection
+
+## Workflow Position
+
+**Typically follows:** `primekit-plan` (execute a plan), `/pk:brainstorm` (implement agreed solution)
+**Typically precedes:** `primekit-test` (validate changes)
+**Related:** `/pk:fix` (alternative for bug fixes), `primekit-plan` (create plan before cooking), `the installed code-review skill` (review after implementation, engineer tier)

package/skills/cook/references/intent-detection.md

@@ -0,0 +1,109 @@
+# Intent Detection Logic
+
+Detect user intent from natural language and route to appropriate workflow.
+
+## Detection Algorithm
+
+```
+FUNCTION detectMode(input):
+  # Priority 1: Explicit flags (override all)
+  IF input contains "--interactive": RETURN "interactive"
+  IF input contains "--fast": RETURN "fast"
+  IF input contains "--parallel": RETURN "parallel"
+  IF input contains "--auto": RETURN "auto"
+  IF input contains "--no-test": RETURN "no-test"
+  # "--tdd" is composable and does not change mode selection
+
+  # Priority 2: Plan path detection
+  IF input matches path pattern (./plans/*, plan.md, phase-*.md):
+    RETURN "code"
+
+  # Priority 3: Keyword detection (case-insensitive)
+  keywords = lowercase(input)
+
+  IF keywords contains ["fast", "quick", "rapidly", "asap"]:
+    RETURN "fast"
+
+  IF keywords contains ["trust me", "auto", "yolo", "just do it"]:
+    RETURN "auto"
+
+  IF keywords contains ["no test", "skip test", "without test"]:
+    RETURN "no-test"
+
+  # Priority 4: Complexity detection
+  features = extractFeatures(input)  # comma-separated or "and"-joined items
+  IF count(features) >= 3 OR keywords contains "parallel":
+    RETURN "parallel"
+
+  # Default: interactive workflow
+  RETURN "interactive"
+```
+
+## Feature Extraction
+
+Detect multiple features from natural language:
+
+```
+"implement auth, payments, and notifications" → ["auth", "payments", "notifications"]
+"add login + signup + password reset"        → ["login", "signup", "password reset"]
+"create dashboard with charts and tables"    → single feature (dashboard)
+```
+
+**Parallel trigger:** 3+ distinct features = parallel mode
+
+## Mode Behaviors
+
+| Mode | Skip Research | Skip Test | Review Gates | Auto-Approve | Parallel Exec |
+|------|---------------|-----------|--------------|--------------|---------------|
+| interactive | ✗ | ✗ | **Yes (stops)** | ✗ | ✗ |
+| auto | ✗ | ✗ | **No (skips)** | Per `review-cycle.md` | ✓ (all phases) |
+| fast | ✓ | ✗ | Yes (stops) | ✗ | ✗ |
+| parallel | Optional | ✗ | Yes (stops) | ✗ | ✓ |
+| no-test | ✗ | ✓ | Yes (stops) | ✗ | ✗ |
+| code | ✓ | ✗ | Yes (stops) | Per plan | Per plan |
+
+**Review Gates:** Human approval checkpoints between major steps (see `workflow-steps.md`).
+- All modes EXCEPT `auto` stop at review gates for human approval.
+- `auto` mode is the only mode that runs continuously without stopping.
+
+## Examples
+
+```
+"/pk:cook implement user auth --interactive"
+→ Mode: interactive (explicit flag, stops at review gates)
+
+"/pk:cook implement user auth"
+→ Mode: interactive (default, stops at review gates)
+
+"/pk:cook <plan-dir>/phase-02-api.md"
+→ Mode: code (path detected, stops at review gates)
+
+"/pk:cook quick fix for the login bug"
+→ Mode: fast ("quick" keyword, stops at review gates)
+
+"/pk:cook implement auth, payments, notifications, shipping"
+→ Mode: parallel (4 features, stops at review gates)
+
+"/pk:cook implement dashboard --fast"
+→ Mode: fast (explicit flag, stops at review gates)
+
+"/pk:cook refactor auth middleware --tdd"
+→ Mode: interactive (default mode, with tests-first implementation behavior)
+
+"/pk:cook implement everything --auto"
+→ Mode: auto (NO STOPS, implements all phases continuously)
+
+"/pk:cook implement dashboard trust me"
+→ Mode: auto ("trust me" keyword, NO STOPS)
+```
+
+**Note:** Only `--auto` flag or "trust me"/"auto"/"yolo" keywords enable continuous execution.
+
+## Conflict Resolution
+
+When multiple signals detected, priority order:
+1. Explicit flags (`--fast`, `--auto`, etc.)
+2. Path detection (plan files)
+3. Keywords in text
+4. Feature count analysis
+5. Default (interactive)

package/skills/cook/references/plan-state-files-first.md

@@ -0,0 +1,182 @@
+# Plan State: Files-First Model
+
+Shared by every skill that creates, resolves, or mutates a plan (`pk:plan`,
+`pk:issue-to-plan`, `pk:cook`, and any other skill referencing this file).
+This is the single description of where plan state lives — do not restate a
+divergent copy in another skill; link here instead.
+
+## Canonical state = repo files
+
+- `plans/<timestamp>-<slug>/plan.md` plus `phase-NN-*.md` in the repo ARE the
+  plan. Hand-editable Markdown, legacy-claudekit style. They are the
+  deliverable of planning skills and the only thing implementation skills read
+  to know what to build.
+- A project with no GitHub remote, no `gh` auth, and no network still has a
+  fully working plan — because the files are the plan.
+
+## `primekit plan` / `plans.db` = a rebuildable index, not canonical
+
+- The `primekit plan` CLI (backed by a local SQLite `plans.db`) is a cache/index
+  built FROM the files: fast lookup, search, kanban, cross-repo listing,
+  current-plan resolution.
+- If the index and the files ever disagree, the files win. `primekit plan reindex`
+  rebuilds the index from disk when they drift (e.g. after a hand-edit or a
+  pull that changed plan files without going through the CLI).
+- File-writing commands (`create`, `add-phase`, `check`, `uncheck`, and
+  `update --status`) write the Markdown files and re-sync the index in the same
+  operation — use them for status changes instead of hand-editing a phases
+  table, and the write target is always the files. `status` is read-only;
+  `close` and `archive` are index-only lifecycle transitions that never touch
+  the files (the files already carry their terminal `status:` from the ship
+  commit). Because `close` is index-only, closing an unmerged or abandoned plan
+  whose file still reads `in-progress` will reindex as active on another machine
+  or after a rebuild — pair such a close with `primekit plan update <id> --status
+  cancelled` so the terminal state lives in the files.
+
+## Current-plan resolution
+
+- `primekit plan use <plan-dir>` sets the current-plan pointer for this worktree so
+  downstream tooling (`pk:cook`, dashboards, other agents) can resolve the
+  active plan without re-scanning or requiring a GitHub link.
+- `primekit plan resolve` finds the plan matching the current repo remote + branch
+  (worktree path as tiebreaker) when no explicit pointer is set.
+- `primekit plan show <plan-dir>` reads plan/phase content (frontmatter, checklists,
+  body) for a skill to consume — read plan state this way, not from GitHub
+  issue comments.
+
+## GitHub issue = optional visibility projection, never canonical
+
+- Publishing is the agent's job, not the CLI's: the agent projects a validated
+  plan onto a GitHub issue (create or update) with `gh` / the GitHub API. There
+  is no `primekit plan publish` command.
+- Publishing is never required and never the source of truth. Skip it entirely
+  in a repo with no GitHub remote, no `gh` auth, or when the user does not ask
+  for it — the plan is still fully usable as files. When the user asks to publish
+  but `gh`/GitHub auth is unavailable, skip without failing and report one line
+  suggesting how to enable it (e.g. `gh auth login`).
+- Publishing never overwrites the body of a pre-existing issue a plan was
+  created from (e.g. via `pk:issue-to-plan`); it only adds links, comments, or
+  labels.
+- If the index and a linked issue ever disagree on status, the local files
+  (and the index rebuilt from them) win. The issue is a mirror, not a lock.
+
+### Publish-safety protocol
+
+When an agent does project a plan onto an issue, follow this so the projection is
+safe, idempotent, and recoverable. Run `primekit plan --help` and each subcommand's
+`--help` for exact flags.
+
+1. **Gate every publish, not just the first.** Visibility can flip and new phase
+   evidence appears, so on each write confirm the target repo/issue visibility is
+   acceptable for the content, then run a secret scan over the *rendered*
+   projection text after composing it. Never project raw logs, env values,
+   tokens, credentials, or local absolute paths. If the rendered body would
+   exceed GitHub's comment limit (65,536 chars), truncate to a repo-relative
+   plan-path link — do not split across comments.
+2. **Provenance lives in the index, not the files.** Persist the linkage with the
+   shipped commands (a hand-written `issue:` front-matter key is inert — the
+   parser ignores unknown front matter):
+   - `primekit plan update --issue <n> --root-comment-id <id>` for the plan's issue and
+     root tracking comment;
+   - `primekit plan phase update --comment-id <id>` for a per-phase tracking comment.
+   Persist the ids **immediately** after creating the comment, before any further
+   writes; if the persist fails, print the ids in the report for manual recovery.
+   A human-readable `Tracking: #<n>` line in the plan *body* is a fine
+   non-authoritative breadcrumb.
+3. **Adopt before you create (bootstrap).** The index is per-machine and
+   rebuildable, so a fresh clone, a teammate's machine, or a lost `plans.db` has
+   no recorded ids even when the issue already carries the projection. Embed a
+   stable marker in every bot-authored projected comment:
+   `<!-- primekit-plan <plan-dir-basename> hash=<12-hex> branch=<branch> -->`.
+   Before creating a new root comment, scan the issue's existing comments for that
+   marker; on a unique authored-by-self match, **adopt** it (persist its id via
+   step 2) instead of posting a duplicate.
+4. **Author-verify before editing.** Only edit a comment the current `gh`
+   identity authored (`gh api .../comments/<id> -q .user.login` equals the
+   authenticated login). Identities differ across machines and CI (a
+   `GITHUB_TOKEN` acts as `github-actions[bot]`), so on a mismatch — or a missing
+   or edited marker — **append a new marked comment**; never edit another author's
+   comment and never abort the delivery over it.
+5. **Rev-echo for idempotency and tamper detection.** The marker carries a short
+   content hash of the rendered body. Before rewriting, re-read the comment: if
+   the hash matches what you last wrote, skip the write; if the marker or hash is
+   missing or altered, a human or another bot touched it — append rather than
+   overwrite. Do not build compare-and-swap or "the on-issue revision is newer,
+   stop and reconcile" logic: the projection is derived and regenerable, the files
+   always win, and GitHub's comment API has no atomic swap. Last-writer-wins among
+   your own verified projections is acceptable.
+6. **Fail safe on missing or rate-limited issues.** A 404/410 (issue transferred,
+   deleted, or locked) → report and stop; never auto-create a replacement issue,
+   and never clear recorded ids without user confirmation (a transfer only
+   changes the repo-scoped API path, so 404 ≠ deleted). On rate limits or a
+   partial write, back off, skip, and report — never retry-loop; create-then-
+   record ordering plus the adoption marker keeps a lost write self-healing.
+
+## Delivery finalization (close on ship)
+
+When a plan-backed change ships, finalize the plan so its files stop reading as
+active work — the core "stale plan read as false context" mitigation. The file
+write and the index close are **two different commands at two different moments**,
+because the CLI splits them:
+
+**On ship success, before the ship commit — finalize the FILES:**
+
+1. Resolve the active plan (`primekit plan resolve`). A resolve-miss means no active
+   plan for this repo + branch — **skip finalization silently**; most ships carry
+   no plan. Only an ambiguity error, or a failure partway through the steps
+   below, warrants a warning plus the exact plan-dir path.
+2. Verify the phase checkboxes reflect reality (`primekit plan status` prints the
+   progress summary). If the diff proves a phase's boxes done, `primekit plan check
+   <phase-file>` them. If the work is genuinely partial, `primekit plan update <id>
+   --status in-progress` and stop — never blind-complete a half-done plan.
+3. When the plan is actually complete, `primekit plan update <id> --status completed`.
+   `--status` is file-owned: it rewrites the `plan.md` front-matter `status:`
+   (the canonical state) and updates the index in one operation. The ship's own
+   `git add -A` + commit then carries the finalized plan files onto the branch,
+   so `status: completed` reaches the target branch in the **same merge** as the
+   code it describes — the files can never claim completion for code that did not
+   land. Make this a synchronous/foreground step; do not fold it into a
+   background writer.
+
+Do **not** run `primekit plan close` here. During the review window the correct
+intermediate state is `status: completed` (file) + `state: active` (index):
+`primekit plan resolve` only returns `state='active'` plans, so an early close would
+blind cook/vibe during review-fix cycles, and the index close is a one-way
+transition with no CLI reopen — a rejected PR must not leave a stuck-closed plan.
+`primekit plan reindex` preserves `state`.
+
+**After PR creation — record the linkage:** `primekit plan update <id> --linked-pr <n>`
+(index-only) so the merge flow can match this plan to its PR unambiguously.
+
+**On merge success — close the INDEX and optionally project:**
+
+1. Match the merged PR to its plan via the recorded `--linked-pr` (or plan branch
+   == PR head branch). A match-miss means already closed or unrelated — skip
+   silently; on ambiguity, skip and report rather than guessing.
+2. `primekit plan close <id>` — an index-only transition to `state=closed`. The files
+   already carry `status: completed` from the ship commit, so this changes index
+   visibility only.
+3. Optional projection: if the plan records an issue / root-comment id, **append**
+   a new marked comment (e.g. "plan completed, PR #N merged" with the
+   `<!-- primekit-plan … -->` marker) — never edit the root comment, so a
+   close-time projection cannot clobber anyone. Still apply the publish gates from
+   the publish-safety protocol above (visibility check, secret scan of the
+   rendered text, 65,536-char truncation).
+
+Degrade honestly: if `primekit` is unavailable or any step fails, report the exact
+plan-dir path and reason and complete the delivery with a warning — never
+hand-edit a status line and never delete plan files.
+
+## Rules for skills consuming this model
+
+1. Resolve the current plan via the current-plan pointer (`primekit plan use`) first,
+   falling back to `primekit plan resolve` — never assume a GitHub issue must exist.
+2. Read phase content via `primekit plan show` (or the files directly), not via
+   issue comments.
+3. Mutate status via `primekit plan` file-mutating commands so the files and index
+   stay in sync; do not hand-edit a phases table or a status cell.
+4. Treat `--github` (the agent publishing via `gh` / the GitHub API) as an
+   additive, opt-in visibility step that runs after the plan is already valid as
+   files — never as a prerequisite for planning or implementation to proceed.
+5. Before invoking any subcommand, run `primekit plan --help` and the subcommand's
+   own `--help`; those live surfaces own exact flags, not this file.

package/skills/cook/references/review-cycle.md

@@ -0,0 +1,75 @@
+# Code Review Cycle
+
+Interactive review-fix cycle used in code workflows.
+
+## Interactive Cycle (max 3 cycles)
+
+```
+cycle = 0
+LOOP:
+  1. Run code-reviewer → score, critical_count, warnings, suggestions
+
+  2. DISPLAY FINDINGS:
+     ┌─────────────────────────────────────────┐
+     │ Code Review Results: [score]/10         │
+     ├─────────────────────────────────────────┤
+     │ Summary: [what implemented], tests      │
+     │ [X/X passed]                            │
+     ├─────────────────────────────────────────┤
+     │ Critical Issues ([N]): MUST FIX         │
+     │  - [issue] at [file:line]               │
+     │ Warnings ([N]): SHOULD FIX              │
+     │  - [issue] at [file:line]               │
+     │ Suggestions ([N]): NICE TO HAVE         │
+     │  - [suggestion]                         │
+     └─────────────────────────────────────────┘
+
+  3. ask_user capability (header: "Review & Approve"):
+     IF critical_count > 0:
+       - "Fix critical issues" → fix, re-run tester, cycle++, LOOP
+       - "Fix all issues" → fix all, re-run tester, cycle++, LOOP
+       - "Approve anyway" → PROCEED
+       - "Abort" → stop
+     ELSE:
+       - "Approve" → PROCEED
+       - "Fix warnings/suggestions" → fix, cycle++, LOOP
+       - "Abort" → stop
+
+  4. IF cycle >= 3 AND user selects fix:
+     → "⚠ 3 review cycles completed. Final decision required."
+     → ask_user capability: "Approve with noted issues" / "Abort workflow"
+```
+
+## Auto-Handling Cycle (for auto modes)
+
+```
+cycle = 0
+LOOP:
+  1. Run code-reviewer → score, critical_count, warnings
+
+  2. IF score >= 9.5 AND critical_count == 0:
+     → Auto-approve, PROCEED
+
+  3. ELSE IF critical_count > 0 AND cycle < 3:
+     → Auto-fix critical issues
+     → Re-run tester
+     → cycle++, LOOP
+
+  4. ELSE IF critical_count > 0 AND cycle >= 3:
+     → ESCALATE TO USER
+
+  5. ELSE (no critical, score < 9.5):
+     → Approve with warnings logged, PROCEED
+```
+
+## Critical Issues Definition
+- Security: XSS, SQL injection, OWASP vulnerabilities
+- Performance: bottlenecks, inefficient algorithms
+- Architecture: violations of patterns, coupling
+- Principles: KISS, DRY violations; unrequested scope added beyond the task
+
+## Output Formats
+- Waiting: `⏸ Step 4: Code reviewed - [score]/10 - WAITING for approval`
+- After fix: `✓ Step 4: [old]/10 → Fixed [N] issues → [new]/10 - Approved`
+- Auto-approved: `✓ Step 4: Code reviewed - 9.8/10 - Auto-approved`
+- Approved: `✓ Step 4: Code reviewed - [score]/10 - User approved`