omakaseagent 0.1.0

package/dist/agents/.agents/skills/omakase/reference/execution-plan.md

@@ -0,0 +1,159 @@
+# Execution plan — tactical spec for factory handoff
+
+Use when **@omakase-engineer** (or router `plan` with implementation intent) writes a backlog item after audit — or when scoping a single well-known fix without a full audit.
+
+**Not** the same as `reference/plan.md` (strategic: why, options, trade-offs). Execution plans are **how**: self-contained specs for `omakase-implementation-lead` or a follow-up Engineer session with zero audit context.
+
+**Storage:** `.omakaseagent/backlog/NNN-<slug>.md`  
+**Index:** `.omakaseagent/backlog/README.md`
+
+Patterns adapted from senior advisor / executor-spec practice (self-contained context, verification gates, STOP conditions).
+
+---
+
+## Three properties (non-negotiable)
+
+1. **Self-contained context** — paths, excerpts, conventions, commands inlined; no "as discussed in audit."
+2. **Verification gates** — every step ends with a command and expected result from `factory.md` or recon.
+3. **Hard boundaries** — in-scope / out-of-scope lists; STOP conditions instead of improvisation when reality diverges.
+
+---
+
+## Template
+
+```markdown
+# Plan NNN: <Imperative title — what will be true after this>
+
+> **Executor instructions**: Follow step by step. Run every verification command
+> and confirm the expected result before the next step. On any STOP condition,
+> stop and report — do not improvise. When done, update this plan's status row
+> in `.omakaseagent/backlog/README.md`.
+>
+> **Drift check (run first)**: `git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>`
+> If in-scope files changed, compare "Current state" excerpts to live code; mismatch
+> → STOP.
+
+## Status
+
+- **Priority**: P1 | P2 | P3
+- **Effort**: S | M | L
+- **Risk class**: 0–3+ (per `.omakaseagent/factory.md`)
+- **Depends on**: `backlog/NNN-*.md` or none
+- **Category**: bug | security | perf | tests | tech-debt | migration | dx | docs | direction
+- **Planned at**: commit `<short SHA>`, <YYYY-MM-DD>
+- **Gate**: (filled after factory close — path to `.omakaseagent/gates/...` or "n/a Class 0–1")
+
+## Why this matters
+
+2–5 sentences: problem, cost, what improves. Cite `taste.md` / `decisions.md` when they constrain the shape.
+
+## Current state
+
+- Files and roles (`path` — one line each)
+- Short excerpts with `file:line` markers
+- Convention exemplar: "Match error handling in `src/foo.ts`"
+
+## Commands you will need
+
+| Purpose | Command | Expected on success |
+|---------|---------|---------------------|
+| ... | from `factory.md` mechanical list | exit 0 / all pass |
+
+## Scope
+
+**In scope** (only files you may modify):
+- ...
+
+**Out of scope** (do NOT touch):
+- ...
+
+## Steps
+
+### Step 1: <imperative title>
+
+Precise instructions. Target shape when load-bearing.
+
+**Verify**: `<command>` → <expected output>
+
+### Step 2: ...
+
+## Test plan
+
+- New tests: file, cases, pattern file to copy
+- **Verify**: `<test command>` → all pass including N new tests
+
+## Done criteria
+
+Machine-checkable. ALL must hold:
+
+- [ ] ...
+- [ ] No files outside in-scope modified (`git status`)
+- [ ] `backlog/README.md` status updated
+- [ ] (Class 2+) Gate file written and plan path linked
+
+## STOP conditions
+
+Stop and report (do not improvise) if:
+
+- Current state excerpts do not match live code (drift)
+- Verification fails twice after reasonable fix attempt
+- Fix requires an out-of-scope file
+- Key assumption "<...>" is false
+- Risk class escalates (e.g. touches auth) — escalate to Engineer before continuing
+
+## Maintenance notes
+
+What future changes interact with this; what reviewers should scrutinize; explicit deferrals.
+```
+
+---
+
+## Index: `.omakaseagent/backlog/README.md`
+
+```markdown
+# Backlog — execution plans
+
+Omakase backlog. Execute in order unless dependencies say otherwise.
+Factory loop (critic + gate) applies per `reference/factory-orchestration.md`.
+
+## Execution order & status
+
+| Plan | Title | Priority | Effort | Risk | Depends on | Status |
+|------|-------|----------|--------|------|------------|--------|
+| 001 | ... | P1 | S | 1 | — | TODO |
+
+Status: TODO | IN PROGRESS | DONE | BLOCKED (reason) | STALE (drift) | REJECTED (reason)
+
+## Dependency notes
+
+- 002 requires 001 because ...
+
+## Findings considered and rejected
+
+- <finding>: <one line why> (optional: see `decisions.md` <date>)
+```
+
+---
+
+## Quality bar (check before shipping each plan)
+
+- Could a model that has never seen this repo execute with only this file?
+- Is every verification a command + expected result, not judgment?
+- Does every step name exact files and symbols?
+- Are STOP conditions specific to this plan's risks?
+- Would critic + human reading "Why" + "Done criteria" know what they're approving?
+- No secret values — locations and types only.
+- Planned-at SHA filled; drift check paths match Scope.
+- Plan passes taste bar — no over-engineering spec'd into steps.
+
+---
+
+## After execution (factory close)
+
+Engineer updates:
+
+1. Plan **Gate** field → path to gate report
+2. `backlog/README.md` status → DONE (only after critic + gate on Class 2+)
+3. `decisions.md` when the work establishes durable policy (via archivist when appropriate)
+
+Critic checks **both** Omakase rubric and plan done criteria.

package/dist/agents/.agents/skills/omakase/reference/factory-orchestration.md

@@ -0,0 +1,123 @@
+# Factory orchestration — one goal, multiple agents
+
+Use when a user gives a **goal** (single or multi-step) and expects the **Omakase team** to run Level 4 — not a single chat reply.
+
+**User says:** “Add gate report CI and make sure our factory checkpoints are real.”  
+**User does not:** name leads, seeds, scenarios, or handoffs.
+
+---
+
+## Who owns what
+
+| Role | Lead | Responsibility |
+|------|------|----------------|
+| Orchestrator | **@omakase-engineer** | Task brief, scenarios, delegation, mechanical checks, **final gate file**, human checkpoint |
+| Build | `omakase-implementation-lead` (delegated) | Focused implementation charter |
+| Review | **@omakase-critic** | Evidence + rubric on Class 2+ before human checkpoint |
+| Memory | **@omakase-archivist** | Durable decisions / taste when factory policy changes |
+| Specialists | senior-reviewer, verify path via critic | As Engineer routes |
+
+**Engineer is the factory floor manager.** Other leads are invoked at defined points — not optional on Class 2+ factory work.
+
+---
+
+## Phases (one goal)
+
+```mermaid
+flowchart LR
+  U[User goal] --> E[Engineer: brief + scenarios]
+  E --> W[Work: impl lead / engineer]
+  W --> M[Mechanical checks]
+  M --> C[Critic: evidence review]
+  C --> G[Gate report file]
+  G --> A[Archivist: memory if durable]
+  G --> H[Human checkpoint]
+```
+
+### Phase 1 — Intake (Engineer)
+
+1. Read `factory.md`, `taste.md`, `decisions.md`, `reference/task-intake.md`.  
+2. Publish **Task brief** (plain language).  
+3. Class **2+:** draft scenarios → one user confirm.  
+4. Save brief to `.omakaseagent/handoffs/<date>-<slug>-brief.md` on multi-step or Class 2+ work.
+
+### Phase 2 — Work (Engineer + specialists)
+
+- Delegate implementation when isolated context helps (`omakase-implementation-lead`).  
+- Handoff charter: brief excerpt + files in scope + mechanical commands to run.  
+- **Backlog item:** charter = full `.omakaseagent/backlog/NNN-*.md`; executor runs drift check and STOP rules from the plan (`reference/execution-plan.md`).  
+- Save handoff: `.omakaseagent/handoffs/<date>-<slug>-to-implementation.md` (optional when backlog plan is the charter).
+
+### Phase 3 — Mechanical evidence (Engineer)
+
+Run every command in `factory.md` mechanical list relevant to the change. Capture exit codes in gate draft.
+
+### Phase 4 — Critic gate (mandatory Class 2+)
+
+Invoke **@omakase-critic** with:
+
+- Task brief  
+- Diff summary or paths  
+- Mechanical output  
+- Ask: rubric pass? P0/P1 issues?
+
+Save critic summary into gate `## Critic` section. Handoff file optional: `handoffs/<date>-<slug>-to-critic.md`.
+
+**Do not** tell the user “done” before critic pass on Class 2+.
+
+### Phase 5 — Gate artifact (Engineer)
+
+Write `.omakaseagent/gates/<date>-<slug>-gate.md` — all headings in `reference/learn.md`.  
+If repo has `npm run verify:gate-reports`, run it.
+
+### Phase 6 — Memory (Archivist, when warranted)
+
+If the task changes factory policy (new CI rule, new required heading, new risk class):
+
+- **@omakase-archivist** proposes `decisions.md` diff — user confirms.  
+- Skip for one-off features with no durable policy.
+
+### Phase 7 — Human checkpoint
+
+Tell the user: gate path, what was proven, what decision remains. Not a full diff walkthrough unless they ask.
+
+---
+
+## Multi-step goals
+
+User: “Fix CI, then add gate verifier, then document the factory run.”
+
+Engineer:
+
+1. One **program brief** with ordered steps.  
+2. **Per step:** mini brief → work → mechanical → critic (if Class 2+) → sub-gate or section in one gate.  
+3. **One final gate** references all steps — preferred for related work.
+
+Do not spawn separate user threads per step unless harness requires it.
+
+---
+
+## Routing failures to avoid
+
+| Failure | Fix |
+|---------|-----|
+| Engineer implements + says “done” with no critic | Phase 4 mandatory on Class 2+ |
+| User told to “create a seed” | `task-intake.md` — Engineer co-writes brief |
+| No `factory.md` | Offer `omakase learn` once; continue Class 0–1 |
+| Router/chef mode on engineering goal | Redirect to `@omakase-engineer` |
+| Chat-only evidence | Gate file + mechanical output |
+
+---
+
+## Backlog-driven work
+
+User: "Implement backlog/002" or Engineer proposes next item after audit.
+
+1. Read execution plan; drift check first.  
+2. Phases 1–7 unchanged — plan does not waive critic or gate.  
+3. Gate `## Seed` links backlog path; `## Mechanical evidence` includes plan done-criteria commands.  
+4. Update `backlog/README.md` status on close; reconcile on next audit (`reference/backlog-audit.md`).
+
+## Reference E2E
+
+Full worked example with handoffs: `examples/factory-e2e/` in the omakaseagent repo.

package/dist/agents/.agents/skills/omakase/reference/handoff.md

@@ -0,0 +1,43 @@
+# Handoff — Clean Protocol
+
+When work moves from one agent (or person) to another, a high-quality handoff is mandatory (Rule 6).
+
+## Required Elements
+
+Every handoff must include:
+
+1. **Goal restatement** (in the recipient's terms)
+2. **Context that matters** (only what the next party needs — no dump)
+3. **Decisions made + Why** (link to or excerpt from `decisions.md` when relevant)
+4. **Current state** (what exists, what works, what is known to be broken or incomplete)
+5. **Open questions / risks / assumptions**
+6. **Recommended next actions** (prioritized, with rationale)
+7. **How to verify success** (observable criteria)
+
+## Tone & Density
+
+- Direct. No motivational language.
+- High signal-to-noise. If a sentence does not change what the recipient should do or know, delete it.
+- Use the same "Why this approach" standard as engineering work.
+
+## When to Produce a Handoff
+
+- Explicit `/omakase handoff`
+- Before switching to a different persona or sub-agent
+- At natural phase boundaries (plan → implement, research → build, etc.)
+- When the current agent is stopping and expects another to continue
+
+## Storage
+
+Save substantial handoffs to `.omakaseagent/handoffs/` with a clear slug (date + topic). This builds institutional memory over time.
+
+The recipient should be able to pick up the work with minimal back-and-forth.
+
+## Execution plans vs handoffs
+
+| Artifact | When |
+|----------|------|
+| **Handoff** (`handoffs/`) | Session continuity, context between agents mid-task |
+| **Execution plan** (`backlog/`) | Scoped implementation spec — steps, STOP, verify gates (`reference/execution-plan.md`) |
+
+After a backlog audit, a short findings summary may live in `handoffs/`; durable work specs go to `backlog/`. Implementation always follows factory orchestration — an execution plan is not a substitute for critic + gate on Class 2+.

package/dist/agents/.agents/skills/omakase/reference/init.md

@@ -0,0 +1,146 @@
+# Init — Bootstrap the Omakase Standard in a Project
+
+**Preferred (deterministic):** run the CLI from the project root:
+
+```bash
+npx omakase init
+# or, in the omakase repo: node bin/omakase.js init
+```
+
+This creates `.omakaseagent/`, updates `AGENTS.md`, installs the skill bundle, and registers **native agents** (`omakase-engineer`, `omakase-critic`, `omakase-archivist`, plus hidden/internal specialists) for OpenCode, Cursor, Claude Code, and Codex.
+
+**Next:** `npx omakase learn` — bootstrap Level 4 factory for this repo (`factory.md`, scenarios, gates). See `reference/learn.md`.
+
+**Skill fallback:** `/omakase init` in a harness chat follows the steps below when the CLI cannot be run — but the CLI path is strongly preferred so native agents are actually on disk.
+
+`omakase init` creates the persistent memory layer and sets the project up to use the standard.
+
+## What It Creates
+
+At minimum:
+- `.omakaseagent/` directory at project root
+- `.omakaseagent/taste.md` — running record of what good looks like for this project/team and what patterns are rejected
+- `.omakaseagent/decisions.md` — key architectural and product decisions with date + "Why"
+- `AGENTS.md` (created or enhanced) — lightweight project-level guidance including Omakase team model reference
+
+Optionally (when the project justifies it):
+- `.omakaseagent/context/` for additional high-signal reference material
+- `.omakaseagent/handoffs/` for saved handoff documents
+
+## Behavior
+
+1. **Detect existing state.**
+   - If `.omakaseagent/` already exists, read the current taste and decisions.
+   - Ask the user whether they want to refresh / expand the existing memory or leave it alone.
+   - Never silently overwrite.
+
+2. **Explore the project (light but real).**
+   - Read README, AGENTS.md / CLAUDE.md / any existing standards docs, package.json or equivalent.
+   - Note the primary language/stack and any obvious architectural patterns.
+   - Form a hypothesis about what "senior work" looks like in this codebase.
+
+3. **Create the .omakaseagent/ directory and files (exact steps).**
+   - `mkdir -p .omakaseagent`
+   - Write `.omakaseagent/taste.md` using the high-signal starter below (customize the "What Good Looks Like Here" section based on your project exploration in step 2).
+   - Write `.omakaseagent/decisions.md` with at least one initial entry capturing the current context + the decision to adopt Omakase.
+   - If this repo already has excellent examples (see the ones in this project's own `.omakaseagent/`), use those as the gold standard for tone and density rather than the generic templates.
+
+4. **Explain what was created and why it matters.**
+   - Tell the user the exact paths.
+   - Show the first few lines of taste.md and decisions.md.
+   - Explain that per SKILL.md Setup, these files are now mandatory context for every significant task (with required "Memory consulted" citation).
+
+5. **Generate or enhance AGENTS.md**
+   - Create `AGENTS.md` in the project root (or enhance it if it already exists).
+   - Add a clear Omakase section that references the core principles and the team model (Engineering, Archives, Critics).
+   - Keep the addition lightweight — link to the installed Omakase skill for the full rules and rubric.
+   - Example section to add:
+     ```markdown
+     ## Omakase Standards
+     This project follows the Omakase standard (senior craftsmanship, zero AI slop, mandatory critique gate, ruthless simplicity).
+
+     Teams:
+     - Engineering (lead: The Engineer) — primary implementation and technical work
+     - Archives (lead: The Archivist) — memory, decisions, and knowledge management
+     - Critics (lead: The Critic) — cross-cutting quality enforcement
+
+     Use `/omakase engineer`, `/omakase critique`, etc. once the skill is installed.
+     See the installed Omakase skill for the full 12 Rules and Critique Rubric.
+     ```
+
+6. **Offer the obvious next step.**
+   - Usually: "Now you can say `/omakase engineer <task>` or just describe what you want built/reviewed/planned."
+   - If the project has no prior standards, this is often the moment to do a light first critique or shape a small piece of work so the taste memory gets its first real data point.
+
+**Minimal Seed for First Task (used by SKILL.md when no .omakaseagent/ exists on first significant engineering work, and user elects to proceed without full /omakase init):**
+Create only:
+- `.omakaseagent/decisions.md` with exactly this starter (customize date/project name):
+  ```markdown
+  # Key Decisions
+
+  ## YYYY-MM-DD — Core Omakase Standards Adopted
+  **Context**: First significant engineering task on a project with no prior .omakaseagent/ memory.
+  **Decision**: Adopt core Omakase Rules + Critique Rubric immediately. Full taste.md and richer decisions will be captured on first real body of work or via explicit `/omakase init`.
+  **Why**: Prevents total context loss and generic output from the very first deliverable. Matches Rule 5 (Persistent Taste Memory) and the Setup requirement in SKILL.md. A minimal seed is better than none for Context Fidelity.
+  **Revisit if**: User runs full init or provides project-specific taste.
+  ```
+- No taste.md yet (or a 1-line placeholder directing to run init for real preferences).
+After creating, tell the user the exact path created and that the next significant output will cite this seed entry. Then proceed with the task under core + engineering (if signals) standards. This is the *only* allowed path for "proceed without init" on first heavy task.
+
+**Gold standard reference:** The `.omakaseagent/taste.md` and `decisions.md` in this very repository (the Omakase source) are the current best examples of the expected density, directness, and "Why" quality. When in doubt during init, bias toward matching that tone rather than the generic templates below.
+
+## Starter taste.md (high-signal template)
+
+```markdown
+# Omakase Taste Memory
+
+## What Good Looks Like Here
+- [Project-specific observation 1]
+- [Project-specific observation 2]
+- Ruthless simplicity is valued more than clever abstractions
+- Code that a strong mid-level engineer can understand and modify six months later
+
+## What We Reject
+- Unnecessary comments that restate the obvious
+- Defensive code around trusted paths
+- `any` casts used as escape hatches
+- Files that grow past ~1000 lines without clear justification
+- "For future flexibility" abstractions that add cost today
+
+## Current Standards
+- Every non-trivial engineering change includes a short "Why this approach" section
+- Critique gate is mandatory before significant work is considered done
+- Persistent decisions are recorded in decisions.md
+```
+
+## Starter decisions.md (high-signal template)
+
+```markdown
+# Key Decisions
+
+## YYYY-MM-DD — Decision Title
+**Context**: One sentence on the situation.
+**Decision**: What we chose.
+**Why**: The senior reasoning (trade-offs, constraints, taste).
+**Revisit if**: Conditions under which we would reconsider.
+
+---
+
+(Older decisions go below. Keep the most recent ones near the top.)
+```
+
+## Success Criteria for This Command
+
+After running `omakase init`, a new or existing project should have a clean, useful `.omakaseagent/` that the skill will actually consult on future work. The files should feel like they were written by someone with taste, not by a generic template engine.
+
+If the project already has strong standards elsewhere, `init` should acknowledge them and focus on creating the minimal bridge into the Omakase memory layer rather than fighting existing conventions.
+
+## Minimum Seed Content for First-Task / Proactive Seeding (when init is not explicit)
+
+When the router creates a seed on the first significant task (see SKILL.md Routing Logic):
+- taste.md must contain **at least three concrete, observable, task-derived entries** (not generic aspirations) in "What Good Looks Like Here" and "What We Reject", pulled directly from the files, request, or smells under discussion in the current turn.
+- decisions.md must contain the adoption entry plus the context of the triggering task.
+- After writing, the persona must re-read the created files and perform a quick internal rubric pass, recording the result in the output or decisions.md.
+- The seed must be high-signal enough that a future agent loading it 10 minutes later can make a better decision on the *same* task than it could with no memory.
+
+Generic one-line placeholders ("Core standards adopted") are a failure of Context Fidelity.

package/dist/agents/.agents/skills/omakase/reference/learn.md

@@ -0,0 +1,66 @@
+# omakase learn — repo factory bootstrap
+
+**Owner:** The Archivist (method). **CLI:** `bin/omakase.js learn` (deterministic discover + write).
+
+## Purpose
+
+Install a **Level 4 dark factory** for *this* repo — not generic templates. `learn` discovers stack and scripts, then writes:
+
+- `.omakaseagent/factory.md` — repo playbook (checks, risk classes, workflow)
+- `.omakaseagent/scenarios/` — up to 5 starter scenarios (approve before Class 2+ work)
+- `.omakaseagent/gates/` + `handoffs/` + `backlog/` — empty with README
+- Taste/decisions/AGENTS.md updates when missing factory markers
+
+Global bar: `reference/dark-factory.md`. This command installs **instrumentation**.
+
+## CLI
+
+```bash
+omakase learn              # factory + memory markers
+omakase learn --dry-run    # list paths only
+omakase learn --memory-only   # taste/decisions only, no scenarios
+omakase learn --factory-only  # factory.md + scenarios, skip taste merge
+omakase learn --project-agents-only  # project-agents/ + native emit only
+```
+
+**Precondition:** `.omakaseagent/` exists (`omakase init` first).
+
+## Agent fallback (no CLI)
+
+1. Confirm `.omakaseagent/` exists; else tell user to run `omakase init`.  
+2. Read README, `package.json`, CI workflows, main source dirs.  
+3. Propose same artifacts as CLI would write; show diffs.  
+4. **Wait for confirm** before writing.  
+5. Log decision in `decisions.md`.
+
+## After learn
+
+Agents follow **`reference/task-intake.md`** (single tasks) and **`reference/factory-orchestration.md`** (Class 2+ team loop: Engineer → critic → gate → archivist when needed). Backlog audit and execution plans: **`reference/backlog-audit.md`**, **`reference/execution-plan.md`**.
+
+- Class **0–1:** brief inline; mechanical checks; light checkpoint OK.  
+- Class **2+:** brief + scenarios (agent drafts); one confirm; gate file at end.  
+- Re-run `learn` when stack or CI changes (`--dry-run` first).
+
+## Gate report shape (minimum headings)
+
+```markdown
+# Gate: <task>
+
+## Seed
+## Scenarios
+## Mechanical evidence
+## Critic
+## Memory consulted
+## Risks / human decision
+```
+
+## Project agents (Phase G)
+
+`learn` proposes up to **3** namespaced agents under `.omakaseagent/project-agents/` from repo signals (`skill/`, `bin/`, domain dirs). On learn, stubs emit to installed harness `agents/` dirs (e.g. `.cursor/agents/omakase-<pkg>-skill.md`).
+
+- **Canonical source:** `.omakaseagent/project-agents/*.md` — edit here, re-run learn
+- **Does not replace** core leads (`@omakase-engineer`, etc.)
+- **Gate:** skill-judge report on new/changed bodies (report-only; human decides)
+- **Refresh:** `omakase learn --project-agents-only` after editing project agent files
+
+See `reference/team-architecture.md` for delegation patterns.

package/dist/agents/.agents/skills/omakase/reference/native-agents.md

@@ -0,0 +1,45 @@
+# Native Omakase Agents
+
+Portable reference (shipped with the skill). Full doc: `docs/NATIVE-SUBAGENTS.md` in the repo.
+
+## Install
+
+```bash
+npx omakase init
+```
+
+## User-facing leads
+
+| Agent id | Use for |
+|----------|---------|
+| `omakase-engineer` | Implementation, architecture, refactoring |
+| `omakase-critic` | Quality enforcement, critique |
+| `omakase-archivist` | Memory, decisions, synthesis; git recap & chat preferences (`reference/archivist-workflows.md`) |
+
+## Invoke
+
+| Harness | Command |
+|---------|---------|
+| OpenCode | `opencode run --agent omakase-engineer "…"` |
+| Grok Build | `grok --agent omakase-engineer "…"` |
+| Claude | `claude -p --agent omakase-engineer "…"` |
+| Cursor | `@omakase-engineer` |
+| Codex | `codex exec -c 'agent="omakase_engineer"' "…"` |
+
+## Delegation (leads only)
+
+Task → `subagent_type` from the lead’s delegation list (e.g. `omakase-senior-reviewer`, `omakase-skill-judge`). See each lead agent file.
+
+Specialists are **INTERNAL ONLY** — not user-facing.
+
+## Skill router (fallback)
+
+This install includes skill **`omakase-router`** at `.agents/skills/omakase/SKILL.md` (folder name `omakase`).
+
+Use for: `/omakase-router plan`, taste, handoff — **not** for `@omakase-engineer`.
+
+## Verify
+
+```bash
+npm run verify:native-agents
+```

package/dist/agents/.agents/skills/omakase/reference/plan.md

@@ -0,0 +1,79 @@
+# Plan — Senior Planning with Domain Awareness
+
+`plan` is a core command. It produces plans that a strong senior engineer or team would actually want to follow.
+
+Like `critique`, it is a smart traffic-cop: it detects the nature of the request, merges the appropriate standards, and then delivers a high-signal plan with explicit reasoning.
+
+## Core Principle
+
+A mediocre plan is worse than no plan. Every Omakase plan must itself pass the Critique Rubric (core + relevant merged extensions) before being delivered.
+
+## Detection & Merge Logic
+
+**Strong signals to merge Engineering extensions** (from `reference/engineering.md`):
+- Implementation, architecture, refactoring, performance, system design, "how should we build X"
+- Code, modules, boundaries, tech choices, team process around code
+- Any request that will result in significant code or technical decisions
+- "Sketch the core data model", "API surface", "backend service" or similar technical depth
+
+**Non-Engineering Signals (core standards only — do not merge engineering extensions)**:
+- Pure product strategy, GTM, org design, high-level roadmap, ICP/positioning/pricing work with explicit or implied "high-level" or "no implementation details" framing.
+- Writing, narrative, or process-focused requests: "develop the messaging", "write the strategy brief for execs", "design a better operating rhythm for feature requests", "critique this customer email sequence for voice".
+- Requests that actively disclaim technical depth.
+
+**Mixed / Ambiguous (common)**:
+- When the request combines product/strategy with any meaningful technical architecture, data model, or implementation implications → merge engineering extensions for the relevant portions only.
+- When in doubt (e.g., "plan improvements to the developer platform" or "add X feature" without clear qualifiers), **ask once** rather than guessing: "This plan request blends product strategy with potential technical elements. Should I produce a plan under core Omakase standards only, or merge in engineering standards (ruthless simplicity for architecture, boundary hygiene, etc.) for the technical sections?"
+
+When in doubt, ask once rather than guessing the register. The plan output must always include an explicit Domain Detection & Merge note near the top (see required elements below).
+
+## What a Senior Omakase Plan Must Contain
+
+A good plan is not a list of tasks. It is a clear, reasoned artifact that reduces ambiguity and surfaces the important thinking.
+
+Required elements:
+
+1. **Domain Detection & Merge Declaration** (mandatory, placed early — right after Goal Restatement or as a top callout box): Explicitly state the detected domain and merge decision with reasoning. Examples:
+   - "Domain: Pure product strategy / GTM. Standards: Core Omakase only (no engineering extensions merged). Reason: Request was high-level positioning and launch phases with no technical architecture or implementation content."
+   - "Domain: Mixed (product positioning + technical implementation sketch). Standards: Core + Engineering extensions (applied to data model and API sections for code judo and contract clarity). Reason: Explicit request for both strategy and core data model/API surface."
+   This fulfills the requirement that every plan (and its subsequent critique) transparently documents whether engineering standards were correctly avoided or applied.
+2. **Problem / Goal Restatement** (sharper and more precise than the original request)
+3. **Key Constraints & Non-Goals** (what we are deliberately *not* doing and why)
+4. **Recommended Approach** with explicit "Why this approach" section (trade-offs, why this shape over obvious alternatives)
+5. **Options Considered** (at least the main 2-3 alternatives and why they were rejected or deferred)
+6. **Risks, Assumptions & Open Questions**
+7. **Proposed Phasing / Order of Work** (with justification — not just a flat list)
+8. **Success Criteria** (observable, testable outcomes)
+9. **Handoff Notes** (what the implementer needs to know that isn't in the plan itself)
+
+## Quality Bar
+
+- Ruthless simplicity in the *plan itself*. Bloated plans are a smell.
+- The plan must pass the Critique Rubric (core only for pure product/strategy/writing work; core + engineering extensions when the plan contains meaningful technical decisions or architecture).
+- Every non-obvious recommendation must have "Why this approach" reasoning.
+- The Domain Detection & Merge Declaration must itself be accurate and defensible (this is part of the self-critique gate).
+- The plan should feel like it was written by someone who has actually shipped similar work and knows where things usually go wrong.
+
+## Tone
+
+Calm, senior, decisive but not arrogant. You are comfortable saying "this is the right shape" while still showing the thinking that led there. You surface uncomfortable trade-offs early.
+
+## Self-Application
+
+The output of `plan` is frequently handed to `engineer` or other agents. Poor plans create expensive downstream problems. Hold the plan to the same standard you would hold the final implementation.
+
+## Relationship to Handoff
+
+When the plan is substantial, consider also producing a crisp handoff document (see `reference/handoff.md`) for the transition from planning to execution.
+
+## Strategic plan vs execution plan
+
+| | Strategic (`reference/plan.md`) | Execution (`.omakaseagent/backlog/`) |
+|---|--------------------------------|--------------------------------------|
+| **Purpose** | Why, options, trade-offs, phasing | How — steps, excerpts, verify gates |
+| **Trigger** | `/omakase plan`, shaping direction | Backlog audit selection, "fix X" spec |
+| **Audience** | Human + Engineer deciding shape | `omakase-implementation-lead` with zero session context |
+| **Template** | Required elements in this file | `reference/execution-plan.md` |
+| **Close** | Handoff to Engineer | Factory loop: critic + gate |
+
+A strategic plan may recommend backlog items; Engineer writes execution plans when it's time to spec concrete file-level work (`reference/backlog-audit.md`).