@lemoncode/lemony 0.1.0

package/catalog/skills/review-pr/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: review-pr
+description: Interactive PR review with a dry-run approval flow — fetch the diff, analyze it through the review lenses, present a numbered findings table, and post only the human-selected ones as GitHub inline review comments. Use at the merge gate (or whenever a curated inline pass is wanted) — a lightweight assist, not the heavy multi-agent fan-out.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [orchestrator]
+---
+
+# Review PR
+
+## Core principle
+
+**Show before you post.** Analyze → dry-run → human picks → post. Never submit GitHub
+review comments without explicit human approval. This is a single-pass, curated assist
+layered on the merge gate — for an exhaustive multi-agent audit, that's a different,
+heavier tool, deliberately not this one.
+
+## Workflow
+
+### 0. Resolve the PR
+
+- **URL** (`https://github.com/<org>/<repo>/pull/123`): extract `<org>/<repo>` + number.
+- **Number** (`#834`, `834`): resolve the repo with `gh repo view --json nameWithOwner`.
+- **No argument**: detect the open PR on the current branch with `gh pr view`.
+
+Run in parallel:
+
+- `gh pr diff <number> --repo <org>/<repo>`
+- `gh pr view <number> --repo <org>/<repo> --json title,headRefName,baseRefName,files,headRefOid`
+
+If the diff is empty, stop and tell the human.
+
+### 1. Read project context
+
+Read the repo's `CLAUDE.md` (and `CONTEXT.md` if present). Summarize in ≤ 50 lines:
+code-style rules, comment conventions, naming, architecture constraints. This is what
+the analysis judges "against project convention" by.
+
+### 2. Analyze (single sub-agent, the #43 lenses as a checklist)
+
+Spawn **one** `Explore` sub-agent with the full diff, the changed-files list, and the
+project context. Its prompt walks the five review lenses as a checklist — **not** five
+separate agents (that's the heavy fan-out this skill deliberately avoids):
+
+1. **Security** — injection, auth/authz gaps, secret exposure, unsafe input reaching a
+   sink, OWASP-class issues.
+2. **Silent failures** — swallowed errors, empty `catch`, a fallback that hides a bug,
+   a `return` where it should `throw`.
+3. **Spec compliance** — does the diff do what the issue/spec/PR says, no more and no
+   less? Scope drift, missing acceptance criteria.
+4. **Test gaps** — logic-bearing code with no test; a bug fix with no regression test;
+   assertions that don't actually pin the behavior.
+5. **Senior quality** — correctness, edge cases, naming that encodes intent, N+1s,
+   convention violations from step 1's summary.
+
+The agent returns a strict JSON array of findings (see [reference.md](reference.md) for
+the exact prompt and schema). It returns `[]` when the diff is clean — it must **not**
+manufacture findings to seem thorough.
+
+### 3. Dry-run
+
+Print the findings as a numbered table (don't post anything yet):
+
+```
+## Dry-run — <PR_TITLE> (#<NUMBER>)
+
+| # | Sev | File | Line | Problem | Suggestion |
+|---|-----|------|------|---------|------------|
+| 1 | 🟠  | src/foo.ts | 42 | Swallowed error in the catch | Re-throw or log + surface |
+...
+
+Total: N findings. Which do I post? ("all", "1,3,5", or "none")
+```
+
+### 4. Human selection
+
+Wait for the reply. Parse:
+
+- `all` → every finding.
+- `none` → stop; post nothing.
+- `1,3,5` or `1 3 5` → the selected indices.
+
+Confirm the list before posting.
+
+### 5. Post the review comments
+
+Use `headRefOid` from step 0 as `commit_id`. Post all selected comments in **one**
+`gh api` call (one review thread, not N). See [reference.md](reference.md) for the
+exact `gh api` invocation and the comment-body format.
+
+### 6. Confirm
+
+Report the count of posted comments and the PR URL.
+
+## Error handling
+
+- `gh` not available → stop, tell the human.
+- A finding's line isn't in the diff (position mismatch) → skip that comment and warn.
+- A post fails → show the error, offer a retry.
+
+## Uncontemplated scenarios
+
+1. Apply the closest matching rule, with reasoning.
+2. Flag it: "This case isn't covered by `review-pr`; I applied [rule] because [reason].
+   Want to refine the skill?"

package/catalog/skills/review-pr/reference.md

@@ -0,0 +1,105 @@
+# Review PR — reference
+
+## Analysis agent prompt
+
+Pass this to the single `Explore` sub-agent. The five lenses are a **checklist one
+agent walks**, not a fan-out.
+
+```
+You are reviewing a GitHub PR diff. Find real issues worth posting as inline review
+comments. Walk these five lenses in order; a finding can come from any of them:
+
+1. Security — injection, auth/authz gaps, secret exposure, unsafe input reaching a
+   sink, OWASP-class issues.
+2. Silent failures — swallowed errors, empty catch, a fallback that hides a bug, a
+   return where it should throw.
+3. Spec compliance — does the diff match the stated intent (issue/spec/PR)? Scope
+   drift, missing acceptance criteria.
+4. Test gaps — logic-bearing code with no test; a bug fix with no regression test;
+   assertions that don't pin the behavior.
+5. Senior quality — correctness, edge cases, naming, N+1s, convention violations.
+
+Judge "against convention" using the project context below.
+
+Do NOT flag:
+- Style preferences not in the project context.
+- TODOs explicitly marked as such.
+- Changes that are clearly intentional from the diff context.
+
+Return ONLY a JSON array (no markdown, no preamble). Return [] if the diff is clean —
+do not manufacture findings.
+
+## Project context
+<PROJECT_CONTEXT>
+
+## Changed files
+<FILES>
+
+## Diff
+<DIFF>
+```
+
+## Output schema
+
+```json
+[
+  {
+    "file": "src/foo.ts",
+    "line": 42,
+    "side": "RIGHT",
+    "lens": "security|silent-failure|spec-compliance|test-gap|senior-quality",
+    "severity": "critical|important|suggestion",
+    "title": "Short title (max 60 chars)",
+    "issue": "What is wrong and why it matters",
+    "suggestion": "How to fix it (specific, not generic)"
+  }
+]
+```
+
+Empty result: `[]`.
+
+`line` must exist on the right side of the diff for that file. `side` is `"RIGHT"` for
+added or modified lines.
+
+## Comment body format
+
+Each GitHub review comment body:
+
+````markdown
+**<title>** _(<lens>)_
+
+<issue>
+
+```suggestion
+<new line content>   ← optional, only for a single-line replacement
+```
+````
+
+## Dry-run table
+
+| #   | Sev | File | Line | Problem | Suggestion |
+| --- | --- | ---- | ---- | ------- | ---------- |
+
+Severity emoji: 🔴 `critical` · 🟠 `important` · 🟡 `suggestion`.
+
+## GitHub API — batch review
+
+All selected comments go in a **single** API call (one review thread, not N):
+
+```bash
+gh api repos/<org>/<repo>/pulls/<number>/reviews \
+  --method POST \
+  --field commit_id=<headRefOid> \
+  --field body='' \
+  --field event=COMMENT \
+  --field 'comments[][path]=src/foo.ts' \
+  --field 'comments[][line]=42' \
+  --field 'comments[][side]=RIGHT' \
+  --field 'comments[][body]=**Title** _(silent-failure)_ …' \
+  --field 'comments[][path]=src/bar.ts' \
+  --field 'comments[][line]=23' \
+  --field 'comments[][side]=RIGHT' \
+  --field 'comments[][body]=**Title** _(security)_ …'
+```
+
+Repeat the four `comments[]...` fields per selected finding.

package/catalog/skills/security-review/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: security-review
+description: Security review of a change — OWASP-style vectors plus AI/LLM-specific risks. Checks input validation, authorization/IDOR, injection, secrets & logging, transport/headers, dependencies, and prompt-injection where an LLM is in the loop. Use after `senior-review` on any change touching user input, auth, data access, or an LLM.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [reviewer]
+---
+
+# Security Review
+
+Review the change for security risk with **fresh context**. Scope the depth to what
+the change touches — a pure refactor of internal logic needs a lighter pass than a new
+endpoint or an LLM call. Consult the project's **security playbook** for project-
+specific rules (deployment model, auth scheme, secret tooling); the checklist below is
+the generic floor. Flag only findings you're confident are real, ranked by severity.
+
+## 1. Input validation at boundaries
+
+- Every entry point (request body, query/path params, headers, file, env, third-party
+  response) validates **shape, type, required-ness, and max length** before use.
+- External strings are validated/converted at the boundary, not asserted into the
+  internal type.
+- No mass-assignment: unexpected fields are rejected, not spread into a model.
+
+## 2. Authorization (not just authentication)
+
+- **Authentication** (who are you?) and **authorization** (are you allowed?) are
+  distinct checks — a valid session is not permission.
+- **Ownership / IDOR**: a resource fetched by id verifies it belongs to the caller. An
+  auth guard never substitutes for the ownership check.
+- Privileged actions check role/scope server-side, never trusting a client claim.
+
+## 3. Injection
+
+- **SQL/NoSQL**: parameterized queries / validated ids; never interpolate user input
+  into a query, never pass a raw request object to a query (object-injection).
+- **Command/path**: no user input concatenated into a shell command or file path
+  (path traversal).
+- **Output/XSS**: rendered user content is escaped by default; raw-HTML sinks
+  (`dangerouslySetInnerHTML`, server-generated HTML/PDF) sanitize at render time.
+
+## 4. Secrets & logging
+
+- No secret, token, password, key, or PII in code, logs, or error messages (a
+  never-log redaction list is configured; emails in failure logs are hashed).
+- No secret committed (`.env` gitignored; `.env.example` carries placeholders only).
+- Constant-time comparison for secrets/tokens (no `===` on a hash); strong randomness
+  for generated keys.
+
+## 5. Transport, headers & CSRF
+
+- Security headers present (nosniff, frame-options/ deny, HSTS in prod).
+- CORS is closed by default; opened only deliberately for known origins.
+- Cookie-based sessions set `httpOnly`, `secure` (prod), and `SameSite` (CSRF
+  defense); token/header auth flows are not CSRF-susceptible.
+
+## 6. Dependencies & exposure
+
+- `npm audit` (or the ecosystem equivalent) clean at moderate+; the change adds no
+  vulnerable dependency.
+- No source maps served publicly in production; no debug/verbose error bodies leaking
+  internals to clients.
+
+## 7. AI / LLM-specific (when an LLM is in the loop)
+
+- **Prompt injection**: untrusted content (user text, fetched pages, tool output) is
+  treated as data, not instructions; system prompts are not overridable by user input.
+- **Output handling**: LLM output is validated/escaped before it drives an action
+  (code execution, a query, a shell command, a network call) — never `eval`'d or run
+  unchecked.
+- **Secret/PII exposure**: no secret or excessive PII placed in a prompt sent to a
+  third-party model; tool/function access from the model is least-privilege.
+- **Resource limits**: token/cost/loop bounds on agentic calls to prevent runaway use.
+
+## Report
+
+```
+## Security Review — <task name>
+
+**Critical**: <vector — file:line — fix> | none
+**High**: <…> | none
+**Medium**: <…> | none
+**Low / hardening**: <…> | none
+
+**Verdict**: no blocking issues / <N> issues to fix before merge
+```
+
+A finding that the **spec** mandated an insecure approach is a **discovery** (the spec
+needs a human decision) — run `raise-discovery` rather than silently complying.

package/catalog/skills/senior-review/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: senior-review
+description: Post-implementation code & test quality review — the "is it good?" half (mechanical gates + execution belong to `verify`). Checks test meaningfulness, integration seams, TypeScript async/type pitfalls, and a self-review checklist, gated by confidence. Use after `verify`, with fresh context, to judge the quality of just-implemented code.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [reviewer]
+---
+
+# Senior Review
+
+Judge the **quality** of the code just implemented, with **fresh context** — review
+it as if it were someone else's work. This is the "**is it good?**" half of review;
+the "**does it work?**" half (build, type-check, lint, tests, coverage, audit, and a
+real run) is the `verify` skill, which the Reviewer runs **first**. Do not re-run the
+gates here — assume `verify` passed and focus on judgment. Work each phase in order.
+
+## Confidence gating
+
+Only raise a finding you are **>80% confident** is a real problem. State your
+confidence when it's borderline. A review that flags everything trains the reader to
+ignore it; a review that flags only what matters gets acted on. Style nitpicks the
+formatter/linter already owns are not findings.
+
+## Phase 1 — Test quality
+
+`verify` confirmed the suite passes; here you judge whether the tests are _meaningful_.
+
+1. Identify the logic-bearing files in the change (services, mappers, hooks,
+   processors, helpers, components).
+2. For each, open its `*.spec.ts(x)` and verify:
+   - Happy path covered.
+   - At least one **error** case covered.
+   - At least one **edge** case (empty input, null, boundary value).
+   - **Arrange / Act / Assert** structure present.
+   - `toStrictEqual` used (not `toEqual` / `toBe`) — `toStrictEqual` catches
+     `undefined` properties the others miss.
+   - Assertions test **behavior**, not the mock (no mock-and-assert, no over-mocking
+     of internal modules).
+3. **User-visible flow**: if the change adds/modifies a navigation / form / list /
+   auth flow, is there an end-to-end test (or was one updated)? See the project's
+   testing playbook (`docs/playbooks/testing.md`, then the global layer) for when E2E
+   is warranted.
+4. If a spec is missing or shallow, that is a finding — name the file and the gap.
+
+## Phase 2 — Integration seams
+
+Most bugs live at module boundaries, not inside modules. Identify the seams this
+change touches — event pipelines, cross-module boundaries, API↔UI contracts,
+producer→consumer handoffs. For each seam touched, confirm there is at least one test
+that **crosses the boundary**, not just a unit test inside one module.
+
+## Phase 3 — TypeScript async & type pitfalls
+
+Read the diff for the failure modes the compiler does not catch on its own:
+
+- [ ] **Floating promises** — every async call is `await`ed or deliberately handled;
+      no fire-and-forget that should have been awaited.
+- [ ] **Missing `await` in `try`** — an un-awaited promise inside `try/catch` escapes
+      the catch.
+- [ ] **`any` / unsafe casts** — no `as any`, no `as unknown as T` smuggling past the
+      type system; assertions are justified.
+- [ ] **Non-null assertions (`!`)** that hide a genuinely possible null.
+- [ ] **Unhandled rejection paths** — `Promise.all` vs `allSettled` chosen
+      deliberately; one rejection doesn't silently drop the rest.
+- [ ] **Boundary types** — external/untrusted input is validated and narrowed at the
+      boundary, not asserted into the internal type.
+
+## Phase 4 — Self-review checklist
+
+Read the diff fresh, as if it were someone else's:
+
+- [ ] No N+1 calls or unnecessary work in loops.
+- [ ] Subscriptions, intervals, and event listeners cleaned up on teardown.
+- [ ] No silent error swallowing (a `catch` that does nothing, optional chaining that
+      hides a bug) — for a deeper pass, the `silent-failure-hunter` skill.
+- [ ] External/user input validated at system boundaries.
+- [ ] Errors fail **explicitly** with a message that identifies the problem.
+- [ ] No dead code or unused variables.
+- [ ] Comments only where logic is non-obvious (not narrating every line).
+
+## Phase 5 — Report
+
+Output a concise verdict the Orchestrator can act on:
+
+```
+## Senior Review — <task name>
+
+**Test quality**: ✅ / ⚠️ <missing/shallow specs>
+**User-visible flow**: ✅ tested / N/A / ⚠️ <gap>
+**Integration seams**: ✅ covered / ⚠️ <uncrossed boundary>
+**TS async/types**: ✅ / ⚠️ <finding>
+**Self-review**: <findings, or "none">
+
+**Verdict**: approve / changes requested — <one-line reason>
+```
+
+If a finding is about the spec itself (the spec is wrong or silent on a case), that is
+a **discovery**, not a rejection: run `raise-discovery` instead of failing the change.

package/catalog/skills/silent-failure-hunter/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: silent-failure-hunter
+description: Hunt for silently swallowed errors and dangerous fallbacks in a change — the failures that hide bugs instead of surfacing them. Five focused passes over the diff. Use during review when a change touches error handling, async flows, or boundary parsing, before `security-review`.
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [reviewer]
+---
+
+# Silent Failure Hunter
+
+The most expensive bugs are the ones that never raise their hand. This skill is a
+focused pass for **silent failures** — code that hides a problem instead of surfacing
+it. The rule it enforces (from the engineering playbook): **errors should fail loudly,
+at the point of the problem, with a message that names it.** Make five passes over the
+diff; for each finding, state the failure mode and the loud alternative.
+
+## Pass 1 — Empty / swallowing catches
+
+- `catch` blocks that do nothing, only `console.log`, or `return null/undefined/[]`
+  without rethrowing or handling.
+- `.catch(() => {})` on a promise.
+- `try` wrapping logic where the `catch` masks the real failure.
+
+> A `catch` is for _handling_ an error (recover, translate, add context, rethrow) —
+> not for making it disappear. An expected no-op (idempotent retry) is fine **only**
+> with a comment stating the intent.
+
+## Pass 2 — Dangerous fallbacks
+
+- `value ?? defaultThatHidesAbsence` / `value || fallback` where the fallback masks a
+  missing-data bug instead of failing.
+- Optional chaining (`a?.b?.c`) that silently yields `undefined` where the value was
+  required — the bug surfaces three layers later, detached from its cause.
+- `try { JSON.parse(x) } catch { return {} }` — a parse failure becomes empty data.
+
+## Pass 3 — Inadequate logging / observability
+
+- An error is caught and handled but **never logged**, so it's invisible in
+  production.
+- Logged at the wrong level (`debug`/`info` for a real error) so it's filtered out.
+- The log message lacks the context to act on it (no id, no operation, no cause).
+
+## Pass 4 — Propagation issues
+
+- A floating promise (no `await`, no `.catch`) whose rejection is lost.
+- `Promise.all` where one rejection silently aborts siblings (vs `allSettled` when
+  partial success matters) — or the reverse, swallowing a failure that should abort.
+- An async function whose error path returns a _success-shaped_ value.
+- An error translated to a generic message that erases the original cause (no `cause`
+  chain).
+
+## Pass 5 — Missing handling at boundaries
+
+- External/untrusted input (API response, file, env var, user input) used without
+  validation, so a malformed value flows in as a silent bad state rather than a loud
+  rejection.
+- A `switch`/branch with no `default` for an unexpected value.
+- A required env var read with a silent fallback instead of failing fast at startup.
+
+## Report
+
+```
+## Silent Failure Hunt — <task name>
+
+**Empty/swallowing catches**: <file:line — failure → loud fix> | none
+**Dangerous fallbacks**: <…> | none
+**Inadequate logging**: <…> | none
+**Propagation**: <…> | none
+**Missing boundary handling**: <…> | none
+
+**Verdict**: clean / <N> silent failures to fix
+```
+
+For each finding, give the loud alternative concretely (`throw new Error(\`… ${id}\`)`instead of`return null`). If the "silent" path is intentional, it must carry a comment
+saying so — absent that comment, treat it as a finding.

package/catalog/skills/spec-compliance-check/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: spec-compliance-check
+description: Walk an L1 spec point by point against the implementation and emit a per-requirement pass/fail verdict. Use during review of an SDD task to prove every EARS requirement (including unwanted-behavior paths) is satisfied and tested — a committable audit trail. Complements `senior-review` (quality) with traceability (coverage of intent).
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: post-implementation
+invoked-by: [reviewer]
+---
+
+# Spec Compliance Check
+
+`senior-review` judges whether the code is _good_; this skill proves it does what the
+**spec said** — every requirement, point by point. It produces a traceability matrix:
+a committable audit trail mapping each requirement to its implementation and its test.
+Only meaningful for **L1 (SDD) tasks** that have a spec under
+`.claude/state/tasks/<id>/spec/`; skip it for L2.
+
+## Process
+
+### 1. Load the spec
+
+Read all three spec artifacts for the task:
+
+- `requirements.md` — the **EARS** requirements (ubiquitous / event-driven /
+  state-driven / optional-feature / **unwanted-behavior**), each numbered with
+  acceptance criteria.
+- `design.md` — the intended files, interfaces, approach, edge cases.
+- `tasks.md` — the atomic checklist, each item referencing the requirements it
+  satisfies.
+
+### 2. Trace each requirement to the implementation
+
+For **every** numbered requirement (do not sample — enterprise audit trails are
+exhaustive):
+
+1. Locate where the change implements it (file + symbol).
+2. Locate the test that proves it (the test whose assertion maps to the acceptance
+   criteria).
+3. Decide the verdict:
+   - **PASS** — implemented **and** covered by a test that asserts the acceptance
+     criteria.
+   - **PARTIAL** — implemented but the test is missing or doesn't assert the criteria.
+   - **FAIL** — not implemented, or the behavior contradicts the requirement.
+
+Pay special attention to **unwanted-behavior** requirements (`If … then …`) — these
+are the ones implementations quietly skip. Each needs a test that drives the bad input
+and asserts the rejection/guard.
+
+### 3. Check for drift
+
+- **Unspecified additions**: implementation behavior with no backing requirement →
+  either scope drift (a `T3` discovery) or a missing requirement.
+- **Design divergence**: the change took an approach `design.md` didn't describe —
+  note it; if it invalidates a design decision, that's a discovery.
+
+### 4. Emit the matrix
+
+```
+## Spec Compliance — task #<id>
+
+| Req | Summary | Status | Implementation | Test |
+| --- | --- | --- | --- | --- |
+| R1 | <ubiquitous …> | ✅ PASS | `x.service.ts:42` | `x.service.spec.ts` |
+| R7 | <If invalid → reject> | ⚠️ PARTIAL | `x.service.ts:80` | — (no test) |
+| R9 | <state-driven …> | ❌ FAIL | — | — |
+
+**Covered**: <n>/<total>  ·  **Partial**: <n>  ·  **Failing**: <n>
+**Verdict**: compliant / non-compliant — <one-line reason>
+```
+
+A `FAIL` or `PARTIAL` is a review finding routed back to the Implementer. If a
+requirement is itself wrong, ambiguous, or contradicted by reality, that's a
+**discovery** — run `raise-discovery`, don't quietly mark it PASS or rewrite the spec
+yourself.

package/catalog/skills/spec-to-issue/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: spec-to-issue
+description: Fill a managed issue's body with the externalized spec. Use when the Spec Author publishes the completed spec into the GitHub issue the Orchestrator already created, mentions "fill the issue", "spec-to-issue", or "externalize the spec into the issue".
+origin: vendor
+vendor_version: '{{vendor_version}}'
+phase: pre-implementation
+invoked-by: [spec-author]
+---
+
+# Spec to Issue
+
+## Core Principle
+
+The GitHub issue **is** the spec, externalized. The Orchestrator already created it (a
+skeleton with the harness labels) at the start of `spec-in-progress` and gave the task
+its permanent `<id>`. This skill does one thing: replace that skeleton body with the
+real spec, so the issue reads as a self-contained spec on GitHub.
+
+Run this **after** `prd-to-spec` has produced `requirements.md` + `design.md` +
+`tasks.md` under `.claude/state/tasks/<id>/spec/`.
+
+## Preconditions
+
+- The issue already exists (the Orchestrator created it) and `<id>` is known.
+- A spec exists at `.claude/state/tasks/<id>/spec/{requirements,design,tasks}.md`.
+- `gh` is authenticated and `task_storage.type` is `github` (see `harness.config.yml`).
+
+You do **not** create the issue, rename any folder (the id is real from the start —
+there is no `draft-<slug>`), or touch labels. Issue creation and the entire label
+lifecycle belong to the Orchestrator.
+
+## Process
+
+### 1. Build the issue body from the spec
+
+The body is the externalized spec — self-contained enough to read on GitHub, with
+links back to the committed files for the full detail:
+
+```markdown
+## Summary
+
+<one paragraph: the capability and why, from the PRD>
+
+## Requirements (EARS)
+
+<paste requirements.md, or its numbered list>
+
+## Design
+
+See `.claude/state/tasks/<id>/spec/design.md`.
+
+## Tasks
+
+See `.claude/state/tasks/<id>/spec/tasks.md`.
+```
+
+### 2. Replace the skeleton body
+
+```bash
+gh issue edit <id> --body-file <body>
+```
+
+This overwrites the `🚧 Spec in progress …` skeleton the Orchestrator wrote at issue
+creation. Labels are untouched — the issue still carries `harness:managed` +
+`harness:sdd` + `harness:status:spec-in-progress`; the Orchestrator flips it to
+`spec-ready` after you hand back.
+
+### 3. Hand back to the Orchestrator
+
+Return a short confirmation. From here the **Orchestrator** flips the status label to
+`harness:status:spec-ready`, commits and pushes the task state to the branch, and runs
+the human approval gate. This skill transitions no labels.
+
+## Ownership boundary
+
+- **Spec Author** (this skill): fills the issue **body** from the committed spec.
+- **Orchestrator**: created the issue, owns every label transition
+  (`spec-in-progress → spec-ready → in-progress → in-review → done`), and closes it at
+  closeout.
+
+## Uncontemplated Scenarios
+
+When a scenario doesn't clearly fit these rules:
+
+1. Apply the closest matching approach with reasoning.
+2. **Flag it**: "This scenario isn't covered by the spec-to-issue skill. I applied
+   [approach] because [reason]. Want to update the skill?"
+3. Offer to add a new rule for the case.