specdo 1.0.2

package/dist/core/skill-content/workflow-content.js

@@ -0,0 +1,1572 @@
+/**
+ * Workflow Skill Content
+ *
+ * 5 个工作流 skill 的完整 progressive-disclosure 内容：
+ *   每个 skill 由 1 个精炼 SKILL.md（≤ 50 行）+ 1-2 个 references/*.md 组成。
+ *
+ *   - SKILL.md: When to use / Quick command / 链接 references / Next step
+ *   - references/REFERENCE.md: 完整命令矩阵、所有标志、exit code、错误恢复
+ *   - references/EXAMPLES.md: 1-2 段真实对话样本
+ *
+ * 当前内容约束：
+ *   - 不导出 `specdo-init` skill（input 由 agent 直接引导）
+ *   - exit code 列表对齐当前 CLI 行为
+ *   - description 包含真实 trigger 短语（"let's plan", "scaffold the change" 等）
+ *
+ * Source of truth 为代码本身（运行时渲染，无模板文件）。
+ */
+// ─── specdo-explore ────────────────────────────────────────────
+const EXPLORE_BODY = `# specdo explore
+
+## How to use this skill (do exactly this)
+
+**CRITICAL: Do NOT run \`specdo explore\` immediately.**
+
+When this skill loads, your first instinct may be to run \`specdo explore '<idea>'\`.
+**Resist this.** Running explore without preparation produces a zero-domain,
+shallow-context change with a random slug that will fail downstream.
+
+You MUST first complete the Grill-Me interview below — ask at least 8
+domain questions (typically 10-30), one at a time, in \`[domain:index]\`
+format. Only run
+\`specdo explore\` **after** the user has answered enough questions and you
+can summarize all decisions into a \`--context\` string.
+
+## Overview
+
+Seed a new change directory with domain-scored context. The explore stage
+captures the user's intent, selects relevant domains (1-4 of 6), runs the
+Grill-Me interview methodology, and records discovery context before any
+artifacts are generated. Output: \`specdo/changes/<name>/context.json\`.
+
+## The correct flow (follow this exactly)
+
+### Phase 1 — DISCOVERY (do this FIRST)
+
+1. Read \`references/DOMAIN_DISCOVERY.md\` — review all 6 domains'
+   signals and questions.
+2. **Select 1-4 domains** that match the user's intent. Do NOT rely on
+   \`scoreDomains()\` — non-English input (pure Chinese, Japanese, etc.)
+   may produce zero matches; prefer explicit \`--domains\` selection.
+3. **Grill the user** using the Grill-Me Methodology below — ask at least 8
+   domain questions (typically 10-30), one at a time, with \`[domain:index]\`
+   format. Continue until the decision tree is exhausted. Do NOT offer to
+   proceed to propose after only 3-5 questions **unless every branch of
+   the decision tree has been genuinely resolved in fewer** (see stop
+   conditions below).
+4. **Summarize** all collected decisions into a \`--context\` string
+   (comma-separated key decisions, e.g. "Next.js + Tailwind, Markdown in
+   repo, no DB").
+
+### Phase 2 — RECORD (only after Phase 1 is complete)
+
+\`\`\`bash
+specdo explore '<idea>' \\
+  --change <your-english-slug> \\
+  --domains <list> \\
+  --context '<summary>' \\
+  --depth standard
+\`\`\`
+
+\`--change\` must be lowercase ASCII letters, digits, and hyphens only, max 50 chars.
+
+**For non-English ideas (Chinese, Japanese, etc.):** always pass
+\`--change <your-english-slug>\`. The auto-generated slug from non-ASCII
+input will be a random string like \`change-mq1r8sxt-l6be\`.
+
+That's it. The CLI creates the directory, writes context.json with correct
+schema, enforces atomic writes, and stamps \`completedAt\`.
+
+## What happens if you skip Phase 1 (anti-pattern)
+
+\`\`\`bash
+# WRONG — bare explore, no --change, no --domains, no --context
+$ specdo explore '我要开发一个博客系统'
+# → Change captured: change-mq1r8sxt-l6be  (random slug!)
+# → No domains matched (Chinese input, auto-score returned zero)
+# → depth: shallow (no --context provided)
+# → propose will warn: "Explore depth is shallow"
+# → Result: garbage change that must be deleted and restarted
+\`\`\`
+
+If you already ran bare explore, fix it:
+\`\`\`bash
+rm -rf specdo/changes/<bad-slug>
+# Then start over: grill first, then run with --change, --domains, --context
+\`\`\`
+
+## CRITICAL: Only the CLI creates valid context.json
+
+Do **not** use \`Write\`, \`mkdir\`, or \`Update\` to create or modify
+\`specdo/changes/*/context.json\`. Hand-written files break schema validation
+and will fail at \`propose\`, \`apply\`, \`sync\`, and \`archive\`.
+
+## The "Grill-Me" Methodology
+
+Interview the user relentlessly about every aspect of the plan before running
+\`specdo explore\`. Walk down each branch of the decision tree, resolving
+dependencies between decisions one-by-one. **For each question, provide your
+recommended answer** based on best practices.
+
+### How to grill
+
+1. **ONE question at a time — this is the most important rule**: Never put
+   two \`[domain:index]\` questions in one message. After asking, STOP and
+   WAIT for the user's response. If you batch questions and the user replies
+   "B", you won't know which question they answered — the answer is lost.
+
+2. **Start with domain questions**: From \`references/DOMAIN_DISCOVERY.md\`,
+   ask questions from each selected domain. You decide how many — **minimum
+   1 per domain**, **total ≥8 across all domains**, **maximum 10 per domain**. Go deeper (6-10 questions) on
+   domains central to the user's intent; ask only the 1-2 most critical
+   questions for peripheral domains.
+
+3. **Go deeper within each domain**: Don't jump to another domain after one
+   question. Follow the decision tree — pick the NEXT indexed question from
+   \`DOMAIN_DISCOVERY.md\` within the same domain that becomes relevant based
+   on the user's last answer. Example: choosing Next.js opens questions about
+   deployment strategy (Vercel vs Docker), styling approach (Tailwind vs CSS
+   Modules), and data fetching (Server Components vs SWR). Chase each branch
+   until resolved before moving to the next domain. For peripheral domains,
+   the 1-2 critical questions from rule 2 are sufficient — move on when
+   those are answered.
+
+4. **Walk the decision tree**: Identify dependencies between decisions and
+   resolve them in order. E.g., choosing Next.js affects deployment (Vercel
+   vs Docker), styling (Tailwind vs CSS Modules), data fetching (Server
+   Components vs client SWR). Chase each branch until it's resolved.
+
+5. **Explore the codebase when relevant**: If a question can be answered by
+   reading existing code, config, or specs, explore the codebase instead of
+   asking the user.
+
+6. **Address concerns NOW, don't defer**: Do NOT create a "flagged concerns"
+   list and push items to later stages. If you identify a gap (payment model,
+   auth strategy, scalability plan), address it immediately with the user.
+
+### Question format protocol
+
+Every question MUST use this format — one \`[domain:index]\` per message:
+
+\`\`\`
+[domain:index] Single clear question? Options if applicable.
+
+Recommended: <your recommendation with brief reason>
+\`\`\`
+
+Rules:
+- \`domain\` = the domain name (frontend, backend, security, etc.)
+- \`index\` = the question index from DOMAIN_DISCOVERY.md
+- Always provide your recommended answer with a brief reason
+- After asking, STOP. Do not ask another question until the user responds.
+
+CORRECT — one question:
+\`\`\`
+[frontend:0] Which framework? I recommend Next.js App Router — it gives you
+SSG for blog posts, API routes, and excellent SEO out of the box.
+\`\`\`
+
+WRONG — two questions batched (causes unrecoverable ambiguity):
+\`\`\`
+[backend:1] User system? A/B/C
+[backend:2] Database? A/B/C/D
+\`\`\`
+If the user replies "B", you CANNOT know which question they answered. The
+answer is lost and you must re-ask both questions — wasting a full round-trip.
+
+### When to stop grilling
+
+You are done exploring when:
+- Each selected domain has at least 1 question answered, **AND the total
+  across all domains reaches at least 8 questions (never stop at 3-5) —
+  unless every branch of the decision tree has been genuinely resolved
+  in fewer, in which case document the resolved decisions and proceed
+- Every branch of the decision tree has been resolved (no open dependencies)
+- You can describe the solution to a colleague and they'd know exactly what
+  to build without asking more questions
+- There are zero unaddressed concerns left for later stages
+
+A healthy explore phase typically covers **10-30 questions** across all
+selected domains, with deeper coverage on the core 1-2 domains.
+
+### When the user refuses grilling
+
+If the user explicitly declines ("just do it", "don't ask, just build"),
+acknowledge the risk and fall back to a minimal capture:
+
+1. **Explain the trade-off**: "Without context, the proposal will be generic.
+   OK for sketching ideas, but production features need exploration."
+2. **Run explore with what you have**:
+   \`\`\`bash
+   specdo explore '<idea>' \\
+     --change <your-english-slug> \\
+     --domains <agent-inferred-list> \\
+     --depth shallow
+   \`\`\`
+   \`--change\` must be lowercase ASCII letters, digits, and hyphens only, max 50 chars.
+   Even in degraded mode, infer at least 1-2 domains from the idea and
+   pass them via \`--domains\` — this prevents zero-domain changes when
+   auto-scoring fails on non-English input.
+   ⚠️  Do **not** add \`--context\` in degraded mode — even a minimal
+   \`--context\` without explicit \`--depth shallow\` causes the CLI to
+   auto-derive \`--depth standard\`, suppressing the shallow warning at
+   propose time.
+3. **Accept the degraded result** — \`propose\` will warn that depth is shallow.
+
+This is a degraded path — prefer grilling whenever the user is willing.
+
+**Note:** \`context.json\` does not record whether the user declined
+grilling. If resuming a conversation where explore was completed in a
+previous session, check \`explore.depth\` — a \`shallow\` depth with
+empty \`collectedContext\` may indicate a degraded path that should be
+accepted without re-asking.
+
+### Anti-patterns
+
+- **Premature propose**: Do NOT ask "Want me to proceed to propose?" after
+  only 3-5 questions. If you catch yourself about to offer propose, ask:
+  "Have I exhausted the decision tree?" If no, keep grilling.
+- **Deferred concerns**: Do NOT create a "⚠️ Flagged concerns" list and push
+  items to propose/apply. Resolve them now.
+- **Batched questions**: Do NOT put multiple \`[domain:index]\` questions in
+  one message. If the user replies "B", which question did they answer —
+  backend:1 or backend:2? This creates unrecoverable ambiguity and forces
+  you to re-ask, wasting a full round-trip.
+- **Hand-writing context.json**: Do NOT use \`Write\`/\`mkdir\` to create
+  context.json manually. Only \`specdo explore\` writes a valid, atomic
+  context.json with correct schema. Hand-written files will fail downstream
+  validation and propose.
+
+### Why focus questions but inject all domains?
+
+During explore, you ask questions only about selected domains — this keeps
+the user focused and avoids overwhelming them with 48 questions across all
+6 domains. But when artifacts are generated downstream, **ALL 6 domains'
+checklists are injected** — into design.md and tasks.md at propose time.
+At apply time, domains are matched dynamically per task via signal scoring
+against the current task title, falling back to the domains used during
+propose. (See \`specdo-apply\` for the full \`implement\` clause injection logic.)
+
+This ensures every production-grade concern (security, architecture,
+operations, backend, quality, frontend) gets reviewed in the generated
+artifacts — even domains the user didn't discuss explicitly during explore.
+The \`--domains\` flag controls only **which domains to ask questions about**,
+not which domain checklists are injected at propose/apply time.
+
+## When to use
+
+- The user describes a new feature, refactor, bug fix, or migration and has
+  described a concrete change — at least 2 proactive-detection signals or
+  ≥10 words describing the target behaviour/outcome. (See Proactive
+  Detection below for the full signal table.)
+- Before any \`specdo propose\` or \`specdo apply\` invocation.
+- Trigger phrases: "let's plan X", "new feature Y", "capture this idea",
+  "set up a change", "scaffold a proposal".
+
+## When NOT to use
+
+- Do NOT run explore with just a one-line vague idea and immediately
+  proceed to propose. This produces low-quality generic templates.
+- If the user's input is too short or vague (< 2 proactive detection
+  signals AND < 10 words describing target outcome) — ask one clarifying
+  question to understand what they want to build, then proceed to Grill-Me
+  when the intent is concrete enough for domain selection.
+
+## Proactive explore detection
+
+**Even without an explicit trigger phrase, recognize when the user is
+describing a new requirement and light-weight suggest explore.**
+
+### Signals to watch for
+
+Watch for these natural-language patterns during any conversation:
+
+| Pattern | Example |
+|---------|---------|
+| Feature wish | "I wish it could...", "It should be able to...", "Can we add..." |
+| Pain point | "Every time I have to manually...", "This is broken when..." |
+| Gap description | "We're missing...", "There's no way to...", "We don't handle..." |
+| Future intent | "Eventually we'll need...", "Down the road...", "Phase 2 should..." |
+| Edge case concern | "What happens if the user...", "What about when..." |
+
+### Decision flow
+
+When you detect ≥2 signals in a single exchange (the user's most recent
+message, or up to 3 consecutive messages without agent interruption)
+AND the idea is concrete
+(≥10 words describing a behaviour or outcome):
+
+1. **Acknowledge the idea** — "That sounds like a meaningful change."
+2. **Offer, don't force** — "Want me to capture this with \`specdo explore\`
+   so we don't lose track of it?"
+3. **If yes** — switch into the full Grill-Me workflow.
+4. **If no** — continue the current task without interruption.
+
+### When NOT to suggest
+
+- The user is asking a question, not describing a requirement
+- It's a trivial one-line fix (typo, rename, config tweak)
+- You're mid-debugging and the user hasn't finished diagnosing
+- The user is clearly brainstorming without intent to act
+
+### Example
+
+> User: "Hmm, every time I add a new API route I forget to wire up the
+> rate limiter. It would be nice if the scaffold did that automatically."
+>
+> Agent: "That sounds like a worthwhile improvement. Want me to capture
+> this as a change with \`specdo explore\` so we can spec out the scaffold
+> enhancement properly?"
+>
+> User: "Sure, let's do that."
+>
+> Agent: [enters Grill-Me workflow...]
+
+## What it produces
+
+- A new \`specdo/changes/<name>/\` directory
+- \`context.json\` (schema v2) with \`explore.matchedDomains\`, \`answers\`,
+  \`collectedContext\`, \`depth\`, \`flaggedConcerns\`, and \`completedAt\`
+
+## Depth levels
+
+| Level | Meaning |
+|-------|---------|
+| \`shallow\` | Idea captured but minimal domain context. \`propose\` will warn. |
+| \`standard\` | Domains selected, clarifying questions answered, reasonable context. |
+| \`deep\` | All domain questions answered, thorough context, code/spec reviewed. |
+
+Self-assess honestly. If you only have a one-line idea and no domain answers,
+your depth is \`shallow\`. Set \`--depth standard\` only when you have done
+real discovery work.
+
+If you omit \`--depth\`, the CLI auto-derives it: \`standard\` when both
+\`--domains\` and \`--context\` are provided, otherwise \`shallow\`.
+
+## LLM mode (dynamic question generation)
+
+For complex or deeply customized changes, use \`--llm\` to generate tailored
+questions instead of the offline pool ranking:
+
+\`\`\`bash
+# Step 1: emit LLM prompt
+specdo explore '<idea>' --domains backend,security --llm
+
+# Step 2: feed the ---SPECDO_LLM_PROMPT--- JSON to an LLM.
+# The payload includes domain signals, descriptions, and the user's idea.
+# Instruct the LLM: "Generate 5-10 clarifying questions per domain,
+# specific to this idea and the domain signal taxonomy."
+
+# Step 3: inject LLM-generated questions
+specdo explore '<idea>' \\
+  --domains backend,security \\
+  --llm-questions '{"security":["Q1?","Q2?"],"backend":["Q3?","Q4?"]}'
+\`\`\`
+
+Full protocol in \`references/REFERENCE.md\`.
+
+## See also
+
+- [\`references/REFERENCE.md\`](references/REFERENCE.md) — full flag matrix,
+  exit codes, recovery, LLM mode protocol
+- [\`references/EXAMPLES.md\`](references/EXAMPLES.md) — annotated sample
+  sessions
+- [\`references/DOMAIN_DISCOVERY.md\`](references/DOMAIN_DISCOVERY.md) —
+  all 6 domains with signals, pool metadata, and clarifying questions
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Bare explore produced garbage change | \`rm -rf specdo/changes/<bad-slug>\` and restart with proper grilling |
+| Wrong slug / wrong domains | Re-run \`specdo explore '<idea>' --change <correct-slug> --domains <list>\` |
+| Explore depth stuck at shallow | Re-run with \`--context '<richer-summary>' --depth standard\` |
+| User refused grilling, proposal is generic | Accept degraded result; proceed to propose with shallow depth accepted |
+
+## Next step
+
+Once \`explore.completedAt\` is set and \`depth\` is at least \`standard\`,
+run \`specdo propose --change <name>\`. If \`depth\` is \`shallow\`, collect
+more context and re-run explore before proposing — unless the user
+explicitly declined grilling, in which case the degraded shallow path
+is accepted and you may proceed to propose.
+`;
+const EXPLORE_REFERENCE = `# specdo explore — Reference
+
+## Full command matrix
+
+| Form | Use case |
+|------|----------|
+| \`specdo explore '<idea>'\` | Auto-scored domains via signal matching (may be inaccurate for non-English) |
+| \`specdo explore '<idea>' --domains <list>\` | **Recommended**: agent selects domains, bypasses auto-scoring |
+| \`specdo explore '<idea>' --change <slug> --domains <list> --context '<text>'\` | Full agent-driven discovery with collected context |
+| \`specdo explore '<idea>' --domains <list> --depth standard\` | Explicitly mark explore as well-prepared |
+| \`specdo explore '<idea>' --domains <list> --depth deep\` | Mark the change as thoroughly explored — all questions answered, highest confidence |
+| \`specdo explore '<idea>' --domains <list> --llm\` | Emit LLM prompt for tailored question generation |
+| \`specdo explore '<idea>' --domains <list> --llm-questions '<json>'\` | Inject LLM-generated questions, bypassing pool ranking |
+| \`specdo explore '<idea>' --non-interactive --answers '{...}'\` | CI mode: preset answers as JSON \`{"<domain>:<index>":"<text>"}\` |
+
+## New flags (agent-driven explore)
+
+- \`--domains <list>\` — Comma-separated domain names to **focus questions on**
+  during explore (e.g. \`frontend,backend\`). When provided, \`scoreDomains()\`
+  is bypassed. Each named domain gets score 1.0 and reason "Agent-selected
+  via --domains". Unknown domain names cause exit code 2.
+  **Note**: \`--domains\` controls only which domains you ask questions about.
+  All 6 domains' checklists are still injected at propose/apply time for
+  production-grade completeness.
+- \`--context <text>\` — Free-text summary of discovery context collected
+  by the agent. Written to \`explore.collectedContext\`.
+- \`--depth <level>\` — Self-assessed depth: \`shallow\`, \`standard\`,
+  or \`deep\`. Default is auto-derived: \`standard\` when both \`--domains\`
+  and \`--context\` are provided, otherwise \`shallow\`.
+- \`--llm\` — Enable LLM-driven question generation. Emits a structured
+  JSON prompt to stdout that you feed to an LLM to generate context-specific
+  questions. The LLM response is ingested via \`--llm-questions\`.
+- \`--llm-questions <json>\` — Inject LLM-generated questions as a JSON
+  object \`{"<domain>":["Q1","Q2"]}\`. These questions replace the default
+  pool ranking for the named domains. Cached in \`context.json\` under
+  \`explore.llmQuestions\` to avoid regeneration on re-explore.
+
+## LLM mode workflow
+
+When the user's idea is complex or domain coverage needs deep customization,
+use the LLM mode to generate tailored questions instead of the default offline
+pool ranking:
+
+1. Run \`specdo explore '<idea>' --domains <list> --llm\`
+2. Parse the \`---SPECDO_LLM_PROMPT---\` block from stdout. It contains:
+   - \`idea\` — the user's original input
+   - \`domains\` — selected domains with full signal taxonomies and descriptions
+   - \`existingAnswers\` — empty (first call) or pre-collected answers
+3. Call an LLM with this payload. The system prompt should instruct the LLM to
+   generate 5-10 clarifying questions per domain, tailored to the user's idea
+   and the domain's signal taxonomy. Questions should be specific, not generic.
+4. Re-run: \`specdo explore '<idea>' --domains <list> --llm-questions '<json>'\`
+   with the LLM's response. The CLI stores the questions in \`context.json\` and
+   uses them in the interactive loop instead of pool ranking.
+5. If \`--llm\` is used without \`--llm-questions\`, the CLI falls back to the
+   offline question pool for all domains and logs a warning.
+
+## Slug rules
+
+- Derived from idea text: lowercase, alphanumerics + hyphens, max 50 chars
+- Non-ASCII input (Chinese, Japanese, etc.) produces a random fallback slug
+  (e.g. \`change-<timestamp>-<random>\`). Always pass \`--change <slug>\`
+  for non-English ideas to get a meaningful name.
+- Collisions resolved by appending \`-2\`, \`-3\`, ... (never overwrite)
+- Pass \`--change <slug>\` to force a specific name
+
+## Exit codes
+
+- \`0\` — explore stage stored; \`completedAt\` set (also emitted for \`--llm\` prompt mode)
+- \`1\` — workspace not initialized (\`specdo/config.yaml\` missing), idea string empty, invalid --change name, invalid \`--answers\` JSON, or change directory already exists without explicit \`--change\`
+- \`2\` — unknown domain name in \`--domains\`, invalid \`--llm-questions\` JSON, or payload exceeds size limit
+- \`3\` — filesystem write failure (e.g. \`specdo/changes/\` not writable)
+
+## Domain injection modes
+
+\`--domains\` controls which domains to **ask questions about** during
+explore. At propose time, **all 6 domains' checklists are always
+injected** into design.md and tasks.md for production-grade completeness.
+At apply time, domain focus is selected dynamically per task via signal
+matching against the task title.
+
+1. **Agent-driven** (\`--domains <list>\`): You select which domains to focus
+   questions on. The explore phase is shorter and more focused.
+2. **Auto-scored** (no \`--domains\`): \`scoreDomains()\` runs signal matching
+   to suggest focus domains. May produce zero matches for non-English input.
+   When zero matches occur, the CLI suggests using \`--domains\`.
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Wrong slug | \`rm -rf specdo/changes/<wrong>\` and re-run with \`--change <right>\` |
+| Wrong domains | Re-run \`specdo explore '<idea>' --change <name> --domains <correct-list>\` |
+| Shallow explore | Re-run with \`--context '<richer-summary>' --depth standard\` |
+| Stuck mid-prompt | Ctrl-C; \`context.json\` will not exist; re-run from scratch |
+
+## Schema reference
+
+See [\`src/core/json-schemas.ts\`](../../../../src/core/json-schemas.ts) for
+the Zod schema validating \`context.json\` at every stage.
+`;
+const EXPLORE_EXAMPLES = `# specdo explore — Examples
+
+## Session 1: the "Grill-Me" workflow (recommended)
+
+> User: "I want to build a blog website."
+
+The agent reads \`references/DOMAIN_DISCOVERY.md\`, selects domains, then
+grills the user relentlessly — **one question at a time** — before calling
+explore:
+
+\`\`\`
+Agent: I've read the domain catalogue. Based on "blog website", I recommend
+       selecting frontend (UI, rendering, styling) and architecture (system
+       design, data flow). Does that cover your scope, or should I add
+       backend (CMS/API) or operations (deployment)?
+
+User:  Add backend too — I want a custom API.
+
+Agent: Got it: frontend, architecture, backend.
+       [frontend:0] Which framework do you prefer? I recommend Next.js App
+       Router — it gives you SSG for blog posts and easy API routes.
+
+User:  Next.js is fine.
+
+Agent: [frontend:1] What styling approach? Tailwind CSS is the default for
+       rapid UI with design tokens. Or do you have a design system in mind?
+
+User:  Tailwind.
+
+Agent: [architecture:0] Where will blog content live? I recommend Markdown
+       files in the repo (no CMS needed for a personal blog). This keeps
+       everything version-controlled and deployable as static pages.
+
+User:  Yes, Markdown files.
+
+Agent: [architecture:1] How will you handle images in posts? Options:
+       (a) same repo under public/, (b) external CDN, (c) Vercel Blob.
+       I recommend (a) for simplicity.
+
+User:  Option a.
+
+Agent: [backend:0] Do you need a database, or is filesystem + Markdown
+       enough? For a personal blog, no DB is simpler and faster.
+
+User:  No database needed.
+
+Agent: [backend:1] Comments system? None (static), third-party (Giscus/Disqus),
+       or custom? I recommend Giscus — free, GitHub-backed, no DB.
+
+User:  Giscus sounds good.
+
+// ... continues for ~20 more questions across all domains ...
+
+Agent: I've exhausted the decision tree. Summary:
+       - Next.js App Router + Tailwind, Markdown in repo, Giscus comments
+       - No DB, no CMS, images in public/, Vercel deployment
+       - RSS feed, code highlighting, tag-based navigation
+       - No auth needed (static site), no real-time features
+       Ready to record. Running specdo explore...
+\`\`\`
+
+\`\`\`bash
+$ specdo explore 'Build a Markdown-driven blog website' \\
+    --change build-blog-website \\
+    --domains frontend,architecture,backend \\
+    --context 'Next.js App Router + Tailwind, Markdown in repo, Giscus comments, no DB/CMS, Vercel deploy, RSS + code highlighting + tag nav, no auth, no real-time' \\
+    --depth deep
+
+✓ Change captured: build-blog-website
+
+Matched domains (agent-selected):
+  - frontend      score=1.000  Agent-selected via --domains
+  - architecture  score=1.000  Agent-selected via --domains
+  - backend       score=1.000  Agent-selected via --domains
+
+Answers: skipped (non-interactive mode without --answers) (0 entries).
+
+Next: specdo propose --change build-blog-website
+\`\`\`
+
+Notice: the agent grilled the user for ~20 questions BEFORE running explore.
+The \`--context\` flag captures the complete decision tree summary.
+
+## Session 2: CI / non-interactive with structured answers
+
+> Test pipeline pre-fills answers; no human typing.
+
+\`\`\`bash
+$ specdo explore 'Migrate session store from memory to Redis' \\
+    --change session-redis-migration \\
+    --domains backend,operations \\
+    --non-interactive \\
+    --answers '{"backend:0":"Redis 7 with persistence","operations:0":"blue/green"}' \\
+    --depth standard
+
+✓ Change captured: session-redis-migration
+
+Matched domains (agent-selected):
+  - backend        score=1.000  Agent-selected via --domains
+  - operations     score=1.000  Agent-selected via --domains
+
+Answers: preset (from --answers JSON) (2 entries).
+
+Next: specdo propose --change session-redis-migration
+\`\`\`
+
+## Session 3: auto-scored fallback (not recommended for non-English)
+
+\`\`\`bash
+$ specdo explore 'Add rate limiting to the public API'
+✓ Change captured: add-rate-limiting-to-the-public-api
+
+Matched domains (by score):
+  - backend       score=0.235  Matched 3 signals: api, rate limiting, ...
+
+[backend] What data store backs the change?
+> Redis for counters
+
+Answers: collected interactively (pool ranked) (1 entries).
+
+Next: specdo propose --change add-rate-limiting-to-the-public-api
+\`\`\`
+
+Notice: auto-scored mode works for English input but may miss domains or
+return zero matches for non-English. Prefer \`--domains\` for reliability.
+
+## Anti-pattern: one-line idea directly to propose
+
+\`\`\`bash
+$ # WRONG — too shallow, no domain context
+$ specdo explore 'build a blog'
+$ specdo propose --change build-a-blog
+# → Warning: Explore depth is "shallow" — context may be insufficient.
+\`\`\`
+
+The fix: re-run explore with \`--domains\`, \`--context\`, and \`--depth standard\`.
+
+## Anti-pattern: hand-writing context.json breaks the pipeline
+
+\`\`\`bash
+# WRONG — agent bypasses CLI, hand-writes everything
+$ mkdir -p specdo/changes/my-change
+$ Write context.json with hand-crafted matchedDomains as object {frontend: 9}
+$ Write proposal.md, design.md, tasks.md, specs/*.md by hand
+$ specdo validate --change my-change
+# → Error: schema validation failed. matchedDomains must be array, not object.
+# → Missing required fields: domainsUsed, capabilities, collectedContext, depth.
+# → context.json is irrecoverable. Must rm -rf the change directory and restart.
+
+# CORRECT — always run the CLI
+$ specdo explore 'my idea' --change my-change --domains backend --depth standard
+$ specdo propose --change my-change
+\`\`\`
+`;
+// ─── specdo-propose ────────────────────────────────────────────
+const PROPOSE_BODY = `# specdo propose
+
+## How to use this skill (do exactly this)
+
+\`\`\`bash
+specdo propose --change <name>            # safe; skips existing handwritten artifacts
+specdo propose --change <name> --force    # overwrite user-modified artifacts
+\`\`\`
+
+The CLI reads context.json, renders all 4 artifacts with domain checklists
+injected, and validates the schema automatically. Do **not** hand-write
+\`proposal.md\`, \`design.md\`, \`tasks.md\`, or \`specs/*.md\` — the
+renderer injects domain knowledge you cannot replicate manually.
+
+**Note:** \`propose\` does **not** accept \`--domains\`. The \`--domains\`
+flag is only for \`specdo explore\`. \`propose\` always injects all 6
+domains' checklists regardless of which domains were explored.
+
+**CRITICAL: Never silently use \`--force\`.** Always ask the user whether
+to keep their edits or overwrite with generated artifacts. Only add
+\`--force\` when the user explicitly requests overwrite.
+
+## Overview
+
+Render OpenSpec-aligned artifacts from the explore context: proposal.md,
+design.md, tasks.md, and specs/<capability>/spec.md. All 6 domain checklists
+are injected regardless of which domains were explored. Existing handwritten
+artifacts are preserved unless \`--force\` is explicitly requested.
+
+### Before you run — verify explore depth
+
+Read \`specdo/changes/<name>/context.json\` and check \`explore.depth\`:
+- \`standard\` or \`deep\` → proceed.
+- \`shallow\` → if the user already explicitly declined grilling during
+  explore (the degraded shallow path was accepted), proceed without re-asking.
+  Otherwise, warn the user that the proposal will be generic, then
+  ask whether to (a) re-run explore with richer context or (b) accept
+  the degraded shallow path.
+
+## When to use
+
+- \`specdo explore --change <name>\` has set \`explore.completedAt\` and
+  \`explore.depth\` is at least \`standard\` (not \`shallow\`), unless
+  the user explicitly accepted the degraded shallow path.
+- You have collected sufficient context during explore — at minimum, you
+  have selected domains and answered clarifying questions.
+- Before any implementation work or \`specdo apply\` invocation.
+- Trigger phrases: "generate the proposal", "scaffold tasks", "draft the
+  design doc", "kick off the change", "what's next for <change>".
+
+## When NOT to use
+
+- Do NOT run propose immediately after a shallow explore (\`depth: shallow\`),
+  *unless* the user explicitly accepted the degraded shallow path during
+  explore. The resulting templates will be generic and low-quality. Instead,
+  re-run explore with richer \`--context\` and proper \`--domains\`.
+
+## After propose runs
+
+Read each generated artifact and supplement with the context you
+collected during discovery:
+- \`proposal.md\`: add specific details to scope and risks sections.
+- \`design.md\`: inject architecture decisions discussed in explore.
+- \`tasks.md\`: refine task descriptions based on domain choices.
+Use the file editing tool to insert content inline — never regenerate
+artifacts manually. Do **not** skip directly to apply without
+reviewing \`proposal.md\`, \`design.md\`, and \`tasks.md\`.
+
+## What it produces
+
+\`\`\`
+specdo/changes/<name>/
+├── proposal.md              # why + scope + risks
+├── specs/
+│   └── <capability>/spec.md # behaviour contracts (the source of truth post-sync)
+├── design.md                # how (domain design.checklist injected)
+└── tasks.md                 # ordered, numbered task list (drives apply)
+\`\`\`
+
+## Quality warning
+
+If propose outputs "Explore depth is shallow", the generated artifacts
+will be generic templates with minimal domain-specific guidance. Return
+to explore and collect more context before proceeding — unless the user
+explicitly declined grilling during explore (degraded shallow path
+accepted), in which case you may proceed with the caveat that artifacts
+will be generic.
+
+## See also
+
+- [\`references/REFERENCE.md\`](references/REFERENCE.md) — flag matrix, exit
+  codes, conflict handling
+- [\`references/EXAMPLES.md\`](references/EXAMPLES.md) — sample artifact
+  layout and the \`--force\` recovery dance
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Explore depth is shallow | Warn user; either re-run explore with richer context or accept degraded path |
+| Hand-edited artifact was skipped | Review stderr warnings; keep file as source of truth or re-run with \`--force\` |
+| Wrong domain matches in generated artifacts | Re-run \`specdo explore '<idea>' --change <name>\` to re-score, then \`propose --change <name> --force\` |
+| Mixed spec layout detected | Resolve by normalizing to capability folders, then re-run with \`--force\` |
+
+## Next step
+
+Run \`specdo apply --change <name>\` to render the execution brief and start
+TDD-disciplined task work.
+`;
+const PROPOSE_REFERENCE = `# specdo propose — Reference
+
+## Full command matrix
+
+| Form | Use case |
+|------|----------|
+| \`specdo propose --change <name>\` | Safe default; writes missing/generated artifacts and skips existing handwritten ones with stderr warnings |
+| \`specdo propose --change <name> --force\` | Overwrite user-modified artifacts and normalize legacy / mixed spec layouts before task progress exists |
+
+## Required preconditions
+
+- \`specdo/changes/<name>/context.json\` exists with \`explore.completedAt\` non-null
+- Workspace passes \`specdo validate\` (config.yaml parses, no schema drift)
+
+## Exit codes
+
+- \`0\` — all artifacts rendered; \`propose.completedAt\` set
+- \`1\` — change not found, workspace invalid, no explore stage, explore
+  in-progress (\`--llm\` mode), mixed spec layout detected, or legacy-layout
+  upgrade blocked by existing execution progress
+- \`3\` — filesystem write failure
+
+## What gets injected per domain
+
+| Artifact | Injected content |
+|----------|------------------|
+| \`design.md\` | \`domain.design.checklist\` + \`patterns\` + \`antiPatterns\` for every domain (all 6 are always injected) |
+| \`specs/<capability>/spec.md\` | OpenSpec-style requirement/scenario scaffold; behaviour to be authored by user |
+| \`tasks.md\` | numbered list with empty evidence slots, ordered for TDD |
+| \`proposal.md\` | summary + risks + matched-domain rationale |
+
+## Conflict semantics
+
+When the user has already edited a file:
+
+- Without \`--force\`: each existing non-empty handwritten artifact is skipped
+  individually with a warning on stderr; generated-looking placeholders can
+  still be refreshed in the same run.
+- With \`--force\`: rendered artifacts are overwritten in place.
+- Legacy flat specs (\`specs/foo.md\`) are preserved as-is on a normal re-run
+  to avoid creating a mixed layout. Upgrading them to
+  \`specs/<capability>/spec.md\` requires \`--force\`, and is rejected once
+  any task progress or evidence exists.
+- If the change already contains both legacy flat specs and capability folders,
+  \`propose\` stops with "mixed spec layout detected" until the user resolves
+  it or explicitly normalizes with \`--force\`.
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Existing handwritten artifact was skipped | Review the stderr warnings, keep the file as source of truth, or re-run with \`--force\` if you want the renderer to replace it |
+| Legacy change needs OpenSpec capability layout | Re-run \`specdo propose --change <name> --force\` before any task is completed or evidence is recorded. Once execution progress exists, the command fails with \`Cannot upgrade legacy artifacts with existing task progress\`. |
+| Wrong domain matches | Re-run \`specdo explore '<idea>' --change <name>\` to re-score, then \`propose --change <name> --force\` |
+`;
+const PROPOSE_EXAMPLES = `# specdo propose — Examples
+
+## Session 1: clean propose after explore
+
+\`\`\`bash
+$ specdo propose --change rate-limiting-public-api
+# specdo propose --change rate-limiting-public-api
+
+Domain selection: all 6 domains (full coverage, overrides applied)
+✓ wrote proposal.md
+✓ wrote specs/rate-limiting-public-api/spec.md
+✓ wrote design.md
+✓ wrote tasks.md
+
+Next: specdo apply --change rate-limiting-public-api
+\`\`\`
+
+The 6 tasks in tasks.md will look roughly like:
+
+\`\`\`markdown
+## 1. Spec Updates
+
+- [ ] 1.1 Finalize 429 requirement scenarios
+
+## 2. Backend Implementation
+
+- [ ] 2.1 Add Redis-backed token bucket middleware
+- [ ] 2.2 Wire middleware into the public router
+
+## 3. Verification
+
+- [ ] 3.1 Add metrics and rollback coverage
+\`\`\`
+
+## Session 2: user edited design.md, propose rejects without --force
+
+\`\`\`bash
+$ specdo propose --change rate-limiting-public-api
+# (stderr) ! design.md already exists and has content. Skipping. Use --force to overwrite.
+\`\`\`
+
+Recommended dialog:
+
+> Agent should ask: "design.md was edited. Should I keep that file as the
+> source of truth, or re-generate it with \`--force\`?" — do NOT silently
+> force an overwrite.
+
+This run still exits \`0\`; the warning is advisory and the untouched file
+remains the source of truth.
+
+## Session 3: after propose, review and supplement artifacts
+
+After \`specdo propose\` completes, read each generated artifact and
+supplement with your discovery context before moving to apply:
+
+\`\`\`
+Agent: Propose complete. Let me review the generated artifacts and
+       cross-check with the context we collected during explore.
+
+       Reading proposal.md — the scope and risks look right.
+       I'll add a note about the rate-limit threshold we discussed
+       (100 req/min per IP).
+
+       Reading design.md — the middleware pattern is solid.
+       I'll note that we chose token bucket over sliding window
+       for memory efficiency.
+
+       Reading tasks.md — 6 tasks, ordered for TDD.
+       I confirm task 1.1 (spec updates) should come first since
+       we need the spec to drive the red-green cycle.
+
+       Ready for apply. Running specdo apply --change rate-limiting-public-api...
+\`\`\`
+
+## Anti-pattern: don't hand-edit context.json to skip propose
+
+If \`propose.completedAt\` is missing from \`context.json\`, the right
+recovery is to run \`specdo propose --change <name>\`, not to write
+\`completedAt\` by hand. The renderer is the only thing that knows which
+domains are actually injected.
+`;
+// ─── specdo-apply ──────────────────────────────────────────────
+const APPLY_BODY = `# specdo apply
+
+## How to use this skill (do exactly this)
+
+Run the CLI for ALL task state changes:
+
+\`\`\`bash
+specdo apply --change <name>                                    # (re)render brief
+specdo apply --change <name> --done <ref> --evidence "..."      # mark task ref done
+specdo apply --change <name> --undo <ref>                       # revert task ref
+\`\`\`
+
+Do **not** hand-edit \`tasks.md\` checkboxes or \`context.json\` →
+\`apply.tasksEvidence\`. The CLI's evidence ledger lives in \`context.json\`,
+not \`tasks.md\`. Hand-flipping \`- [ ]\` to \`- [x]\` will be **overwritten**
+the next time \`apply\` regenerates the brief. Always go through \`--done\` /
+\`--undo\`.
+
+### Typical apply loop
+
+1. \`specdo apply --change <name>\` — render the brief, note the task refs
+   (e.g. \`1.1\`, \`2.1\`, \`3.1\`) from the generated \`apply-brief.md\`
+2. Read \`apply-brief.md\` to find the current task ref
+3. Implement the task, write tests, verify
+4. \`specdo apply --change <name> --done <ref> --evidence "..."\` — mark done
+5. Repeat steps 2-4 until all tasks complete
+6. \`specdo sync --change <name>\` — promote specs
+
+When all tasks are marked done, the CLI automatically sets
+\`apply.completedAt\` in \`context.json\`. This is the gate that
+\`specdo sync\` checks before allowing spec promotion.
+
+## Overview
+
+Render the execution brief for a change (with each matched domain's
+\`implement\` clauses injected) and record per-task evidence as the user
+completes them. This is the main loop during implementation.
+
+## When to use
+
+- \`specdo propose --change <name>\` has produced \`tasks.md\`.
+- During iterative TDD work — each completed task is recorded with
+  one-line evidence.
+- Trigger phrases: "start implementing", "I'm done with task 3", "mark
+  task 2 complete", "show me the brief", "what's next on <change>".
+
+## When NOT to use
+
+- Do NOT run apply when \`propose.completedAt\` is null — proposal artifacts
+  (especially \`tasks.md\`) must exist first.
+- Do NOT hand-edit \`tasks.md\` checkboxes to simulate progress; always use
+  \`--done\` / \`--undo\` to keep the evidence ledger in \`context.json\` in sync.
+
+## What it produces
+
+- Goal + change metadata
+- For each matched domain: \`implement.focusAreas\`, \`patterns\`, \`antiPatterns\`
+- Optional protocol injection when the resolved domains plus the current task
+  activate it (for example \`review-to-solid\` on quality-heavy work) — see
+  the \`references/PROTOCOL_REVIEW_TO_SOLID.md\` guidance
+- Task list with current completion state, hierarchical task refs (such as
+  \`1.1\` / \`2.1\`), and evidence summaries
+
+## See also
+
+- [\`references/REFERENCE.md\`](references/REFERENCE.md) — flag matrix, exit
+  codes, evidence formatting rules, undo semantics
+- [\`references/EXAMPLES.md\`](references/EXAMPLES.md) — full apply loop from
+  task 1 to task N, plus the \`--undo\` correction pattern
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Task marked done with wrong evidence | \`specdo apply --change <name> --undo <ref>\`, then re-mark with correct \`--evidence\` |
+| Hand-edited tasks.md checkbox overwritten | Always go through \`--done\` / \`--undo\`; the CLI regenerates \`apply-brief.md\` from \`context.json\` |
+| Propose not complete (\`tasks.md\` missing) | Run \`specdo propose --change <name>\` first |
+| Attempted undo on incomplete task | Verify the task ref; the task may already be unchecked or the wrong ref was used |
+| Evidence too vague ("done", "ok") | Push back: "What test / commit / file demonstrates this task is complete?" |
+
+## Next step
+
+After every task in \`tasks.md\` is marked done, run \`specdo sync --change <name>\` to promote the per-change specs into \`specdo/specs/\`.
+`;
+const APPLY_REFERENCE = `# specdo apply — Reference
+
+## Full command matrix
+
+| Form | Use case |
+|------|----------|
+| \`specdo apply --change <name>\` | Render / re-render \`apply-brief.md\`; safe to run any time |
+| \`specdo apply --change <name> --done <ref> --evidence "<text>"\` | Mark task ref (for example \`1\` or \`1.1\`) complete with a one-line evidence note |
+| \`specdo apply --change <name> --undo <ref>\` | Revert that task ref to unchecked; deletes its evidence entry |
+
+## Evidence formatting rules
+
+- One line, ≤ 200 chars after trim
+- Should name the artifact proving the task is done (test name, commit SHA,
+  file path, log excerpt). Examples:
+  - \`"middleware added in src/api/rate-limit.ts; test rate-limit.test.ts:42 passes"\`
+  - \`"docs/runbook.md §rollback updated; reviewed in PR #482"\`
+- Avoid filler ("done", "ok", "✓") — these add no audit value
+
+## Required preconditions
+
+- \`propose.completedAt\` non-null (i.e. \`tasks.md\` exists)
+- Task ref in \`--done\` / \`--undo\` must match an existing task entry such
+  as \`1\`, \`1.1\`, or \`2.3\`
+
+## Exit codes
+
+- \`0\` — brief rendered, or task state updated
+- \`1\` — change not found, propose not complete, task ref not found in
+  tasks.md, missing / empty evidence, \`--done\`/\`--undo\` mutually exclusive,
+  \`--evidence\` cannot be used with \`--undo\`, task already completed (use
+  \`--undo\` first), task not completed (nothing to undo), or workspace invalid
+- \`2\` — invalid task ref format (non-canonical like \"01\" or \"abc\";
+  rejected at CLI parse before \`handleApply\`)
+- \`3\` — filesystem write failure
+
+## Protocol activation semantics
+
+- Explicitly mentioning a protocol name does **not** inject it by itself
+- \`apply\` decides protocol injection from the resolved domain set plus the
+  current task wording
+- When the quality domain is disabled from explore, quality-driven protocol
+  injection is disabled too
+
+## Brief regeneration
+
+\`apply-brief.md\` is **always overwritten** on \`specdo apply --change <name>\`
+(no \`--force\` needed). It is a derived artifact — user edits should go into
+\`tasks.md\` / \`design.md\` instead.
+
+## Undo semantics
+
+\`--undo\` cannot be used with \`--evidence\`. To change evidence, run
+\`--undo <ref>\` first, then re-mark with \`--done <ref> --evidence "..."\`.
+
+\`--undo <ref>\`:
+- Unchecks that task ref in \`tasks.md\`
+- Deletes \`context.json\` → \`apply.tasksEvidence["<ref>"]\` (the key is *removed*,
+  not set to empty string — JSON shape stability matters for replay)
+- Does NOT touch source code (the user is responsible for reverting the work)
+`;
+const APPLY_EXAMPLES = `# specdo apply — Examples
+
+## Session 1: complete loop from task 1.1 to task 3.1
+
+\`\`\`bash
+# Render the brief once, read it, then start coding
+$ specdo apply --change rate-limiting-public-api
+# specdo apply --change rate-limiting-public-api
+
+Tasks: 0/6 complete
+
+Current focus: task 1.1. Finalize 429 requirement scenarios
+Brief written to specdo/changes/rate-limiting-public-api/apply-brief.md.
+
+Mark complete with: specdo apply --change rate-limiting-public-api --done 1.1 --evidence "<...>"
+
+# After writing & passing the red-then-green test for task 1
+$ specdo apply --change rate-limiting-public-api \\
+    --done 1.1 \\
+    --evidence "test rate-limit.test.ts:18 covers 429 path; passes locally"
+✓ Marked task 1.1 done.
+
+# ...iterate for tasks 1.2 through 3.1...
+
+$ specdo apply --change rate-limiting-public-api \\
+    --done 3.1 \\
+    --evidence "docs/runbook.md §rollback updated; reviewed in PR #482"
+✓ Marked task 3.1 done.
+
+All tasks complete (6/6).
+Run 'specdo sync --change rate-limiting-public-api' then 'specdo archive --change rate-limiting-public-api' to finalize.
+\`\`\`
+
+## Session 2: realized task 2.1 was wrong, undo + redo
+
+\`\`\`bash
+$ specdo apply --change rate-limiting-public-api --undo 2.1
+✓ Reverted task 2.1 to incomplete (evidence cleared).
+
+# Fix the work, then re-mark
+$ specdo apply --change rate-limiting-public-api \\
+    --done 2.1 \\
+    --evidence "router wiring fixed in src/api/router.ts; integration test:55 passes"
+✓ Marked task 2.1 done.
+\`\`\`
+
+## Anti-pattern: marking done without evidence
+
+\`\`\`bash
+$ specdo apply --change rate-limiting-public-api --done 2.1
+# (stderr) --evidence is required when marking done. Provide a non-empty string.
+\`\`\`
+
+Filler evidence ("done", "ok") is allowed by the CLI but defeats the audit
+trail. Agent should push back: "What test / commit / file demonstrates this
+task is complete?"
+
+## Anti-pattern: hand-editing tasks.md to flip the checkbox
+
+The CLI's evidence ledger lives in \`context.json\`, not \`tasks.md\`. Hand
+flipping \`- [ ]\` to \`- [x]\` will be **overwritten** the next time
+\`apply\` regenerates the brief. Always go through \`--done\` / \`--undo\`.
+`;
+// ─── specdo-sync ───────────────────────────────────────────────
+const SYNC_BODY = `# specdo sync
+
+## How to use this skill (do exactly this)
+
+Run the CLI — never hand-copy spec files into \`specdo/specs/\`:
+
+\`\`\`bash
+specdo sync --change <name>            # safe; aborts on any conflict
+specdo sync --change <name> --force    # clobber conflicts (stages backups in specdo/.sync-backup/)
+\`\`\`
+
+Do **not** manually \`cp\` or \`mv\` per-change spec files into
+\`specdo/specs/\`. Only the CLI knows the conflict detection rules,
+backup staging semantics (\`specdo/.sync-backup/\`), forced-conflict
+hash audit, and \`sync.completedAt\` timestamping. Hand-copied files
+will look like "synced" but lack audit metadata, breaking archive.
+
+## Overview
+
+Promote a change's per-change specs (\`specdo/changes/<name>/specs/<capability>/spec.md\`) to
+the canonical \`specdo/specs/\` directory, detecting and reporting conflicts
+against any existing same-name spec.
+
+## What it produces
+
+- Updates \`specdo/specs/<capability>/spec.md\` for each per-change spec
+- Writes \`context.json\` → \`sync.completedAt\` and \`sync.syncedSpecs\`
+- On conflict without \`--force\`: writes \`sync.conflicts\` (array of paths)
+- On \`--force\`: writes \`sync.forcedConflicts\` + SHA256 hashes for audit
+
+## When to use
+
+- Every task in \`tasks.md\` is marked done via \`specdo apply --done\`.
+- Before \`specdo archive\`.
+- Trigger phrases: "sync specs", "promote the specs", "merge change specs",
+  "publish the spec", "spec is ready to be canonical".
+
+## When NOT to use
+
+- Do NOT run sync before every task in \`tasks.md\` is marked done —
+  \`apply.completedAt\` must be non-null.
+- Do NOT manually \`cp\` per-change specs into \`specdo/specs/\` — only the CLI
+  writes \`sync.completedAt\` and the audit metadata required by archive.
+
+## Conflict policy
+
+- Unresolved conflicts → \`sync\` exits 1 and \`archive\` will refuse to proceed.
+- \`--force\` records the path list as \`forcedConflicts\` plus before/after
+  hashes. Existing canonical specs are copied into \`specdo/.sync-backup/\`
+  before overwrite; that staging area is removed on success and preserved on
+  partial failure for manual recovery.
+- **Never silently re-run with \`--force\`.** Always ask the user first:
+  show which specs conflict, offer to diff, and let the user choose between
+  hand-merge and deliberate overwrite. The \`--force\` audit trail is permanent
+  and visible in \`archive-summary.md\`.
+
+## Skipping sync
+
+If the user needs to bypass sync (e.g. template migration, specs already
+promoted by hand), use \`specdo archive --change <name> --skip-sync-check\`.
+This records a mandatory risk note in \`archive-summary.md\`. Do NOT use
+\`--skip-sync-check\` silently — confirm with the user and note the reason
+in conversation. The CLI auto-generates the risk note; you do not need to
+write it yourself.
+
+## See also
+
+- [\`references/REFERENCE.md\`](references/REFERENCE.md) — exit codes, conflict
+  detection internals, hash audit format
+- [\`references/EXAMPLES.md\`](references/EXAMPLES.md) — clean sync, dirty
+  sync with conflicts, and the recommended \`--force\` review dialog
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Sync rejected (unresolved conflicts) | Show user the diff; let them choose hand-merge or \`--force\` |
+| Stale \`specdo/.sync-backup/\` from previous failed run | Inspect staged files, complete manual recovery, then remove the directory |
+| Accidental \`--force\` completed successfully | Recover prior contents from VCS or archive history; the before/after hashes are in \`archive-summary.md\` |
+| Apply not complete (\`completedAt\` null) | Run \`specdo apply --change <name>\` and complete all tasks first |
+
+## Next step
+
+When \`sync\` completes (no unresolved conflicts), run \`specdo archive
+--change <name>\` to finalize.
+`;
+const SYNC_REFERENCE = `# specdo sync — Reference
+
+## Full command matrix
+
+| Form | Use case |
+|------|----------|
+| \`specdo sync --change <name>\` | Detect conflicts; promote only when conflict-free |
+| \`specdo sync --change <name> --force\` | Overwrite same-name specs in \`specdo/specs/\`; existing targets are staged under \`specdo/.sync-backup/\` first |
+
+## Conflict detection
+
+A conflict exists when:
+1. \`specdo/changes/<name>/specs/<capability>/spec.md\` exists AND
+2. \`specdo/specs/<capability>/spec.md\` exists AND
+3. The two files differ (byte-equal short-circuits as "no conflict; skipped")
+
+Unresolved conflicts are stored in \`context.json\` → \`sync.conflicts\`
+as an array of relative spec paths. \`archive\` reads this field to
+enforce the sync gate. When \`--force\` is used, conflicts are moved to
+\`sync.forcedConflicts\` and \`sync.conflicts\` is cleared.
+
+## Exit codes
+
+- \`0\` — all per-change specs promoted; \`sync.completedAt\` set
+- \`1\` — change not found, apply not complete, or unresolved conflicts present
+- \`3\` — filesystem write failure, write+restore failure, or a leftover
+  \`specdo/.sync-backup/\` directory from a previous failed run
+
+## \`--force\` audit fields
+
+When \`--force\` is used, \`context.json\` → \`sync\` is augmented with:
+
+\`\`\`json
+{
+  "forced": true,
+  "forcedConflicts": ["rate-limiting-public-api/spec.md"],
+  "forcedConflictHashes": {
+    "rate-limiting-public-api/spec.md": {
+      "before": "sha256:...",
+      "after": "sha256:..."
+    }
+  }
+}
+\`\`\`
+
+These hashes are echoed in \`archive-summary.md\` for downstream review.
+
+## Backup staging semantics
+
+- Forced overwrites copy the current canonical file to
+  \`specdo/.sync-backup/<relative-path>\`
+- The staging directory is removed after a successful sync
+- If overwrite succeeds but later writes fail, restore is attempted from
+  \`specdo/.sync-backup/\`
+- If restore also fails, the backup directory is intentionally left behind and
+  the command exits \`3\`
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Conflict on a file you don't want to overwrite | Hand-merge \`specdo/specs/<file>\` to incorporate both, then re-run \`sync\` (it will see the files are equal and skip) |
+| Previous run left \`specdo/.sync-backup/\` behind | Inspect the staged files, complete manual recovery if needed, then remove the directory before retrying |
+| Accidental \`--force\` that still completed successfully | Recover the prior contents from the staged copy you preserved before removing \`specdo/.sync-backup/\`, or from VCS / archive history |
+`;
+const SYNC_EXAMPLES = `# specdo sync — Examples
+
+## Session 1: clean first-time sync
+
+\`\`\`bash
+$ specdo sync --change rate-limiting-public-api
+# specdo sync --change rate-limiting-public-api
+
+Synced 1 spec file(s) into specdo/specs/.
+  ✓ rate-limiting-public-api/spec.md
+
+Next: specdo archive --change rate-limiting-public-api
+\`\`\`
+
+## Session 2: conflict against an existing spec
+
+\`\`\`bash
+$ specdo sync --change auth-flow-revamp
+# (stderr) Sync blocked: 2 conflict(s) detected.
+# (stderr)   ✗ auth-flow/spec.md
+# (stderr)   ✗ session-policy/spec.md
+# (stderr) Run with --force to overwrite (a backup will be written to specdo/.sync-backup/).
+\`\`\`
+
+Agent should *never* silently re-run with \`--force\`. The correct dialog:
+
+> "Two specs in specdo/specs/ already exist and differ from your change's
+> versions. Should I (a) show you a diff so you can merge by hand, or (b)
+> overwrite both with your change's versions? — option (b) stages the current
+> canonical copies under specdo/.sync-backup/ before overwrite."
+
+## Session 3: deliberate --force with audit trail
+
+\`\`\`bash
+$ specdo sync --change auth-flow-revamp --force
+# specdo sync --change auth-flow-revamp
+
+Synced 2 spec file(s) into specdo/specs/.
+  ✓ auth-flow/spec.md  [forced]
+  ✓ session-policy/spec.md  [forced]
+
+Forced overwrites recorded in context.json.sync.forcedConflictHashes (2 entries).
+
+Next: specdo archive --change auth-flow-revamp
+\`\`\`
+
+The before/after hashes flow into \`archive-summary.md\` so any reviewer can
+spot a forced spec rewrite later.
+
+## Anti-pattern: archive before sync
+
+\`\`\`bash
+$ specdo archive --change auth-flow-revamp
+# (stderr) Cannot archive: sync has not been executed. Run 'specdo sync --change auth-flow-revamp' first, or pass --skip-sync-check (record-only).
+\`\`\`
+
+Always run \`sync\` (or explicitly skip with \`archive --skip-sync-check\` plus
+a written risk note) before archiving.
+`;
+// ─── specdo-archive ────────────────────────────────────────────
+const ARCHIVE_BODY = `# specdo archive
+
+## How to use this skill (do exactly this)
+
+Run the CLI — never hand-move the change directory:
+
+\`\`\`bash
+specdo archive --change <name>
+\`\`\`
+
+Do **not** manually \`mv specdo/changes/<name> specdo/archive/<name>\`.
+Hand-moving skips \`archive-summary.md\` generation and \`archivedAt\`
+stamping, leaving the change in a broken state ("in flight" to \`list active\`
+AND "archived" to \`list archived\`). Always go through \`specdo archive\`.
+
+Use \`--skip-sync-check\` ONLY when the user explicitly accepts that sync was
+incomplete or skipped; a risk note will be automatically recorded in
+\`archive-summary.md\`.
+
+### Before you run — verify completion and sync status
+
+Read \`specdo/changes/<name>/context.json\` and \`tasks.md\`:
+
+**Task completion:**
+- Every task in \`tasks.md\` must be \`[x]\` with non-empty \`Evidence:\` line
+- \`context.apply\` must exist and \`tasksCompleted === tasksTotal\`
+- If tasks are incomplete, run \`specdo apply --change <name>\` first
+
+**Sync status:**
+- \`sync.completedAt\` must be non-null. If null, confirm with the user
+  before using \`--skip-sync-check\` — note the reason in conversation.
+- \`sync.conflicts\` must be empty or resolved (\`forcedConflicts\` is OK)
+- The CLI also performs a live filesystem comparison between
+  \`changes/<name>/specs/\` and \`specdo/specs/\` — any unsynced files
+  will cause archive to exit 1
+- If sync conditions are not met, run \`specdo sync --change <name>\` first
+
+## Overview
+
+Finalize a change: move \`specdo/changes/<name>/\` into \`specdo/archive/\`
+with a generated \`archive-summary.md\` snapshotting evidence, sync state,
+and any forced conflicts.
+
+## When to use
+
+- \`specdo sync --change <name>\` succeeded with no unresolved conflicts.
+- The change is done and should leave the active set.
+- Trigger phrases: "archive the change", "finalize <change>", "close out
+  this change", "we're done with X".
+
+## When NOT to use
+
+- Do NOT archive a change with unresolved sync conflicts — \`sync.conflicts\`
+  must be empty.
+- Do NOT manually \`mv\` the change directory to \`specdo/archive/\` — this
+  skips \`archive-summary.md\` generation and \`archivedAt\` stamping, breaking
+  both \`list active\` and \`list archived\` views.
+
+## What it produces
+
+- Moves \`specdo/changes/<name>/\` → \`specdo/archive/<name>/\`
+- Writes \`archive-summary.md\` with:
+  - explore matched domains + final answers
+  - apply tasks total / completed + per-task evidence
+  - sync state snapshot (forced conflicts + hashes, if any)
+  - risk notes (mandatory when \`--skip-sync-check\` is used)
+- Sets \`context.json\` → \`archive.archivedAt\` (ISO timestamp)
+
+## See also
+
+- [\`references/REFERENCE.md\`](references/REFERENCE.md) — flag matrix, exit
+  codes, archive directory layout, audit fields
+- [\`references/EXAMPLES.md\`](references/EXAMPLES.md) — clean archive, the
+  \`--skip-sync-check\` risk-note dialog, and post-archive lookups
+
+## Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Sync incomplete (\`completedAt\` null) | Run \`specdo sync --change <name>\` first, or use \`--skip-sync-check\` with documented reason |
+| Unresolved sync conflicts | Run \`specdo sync --change <name>\` to resolve; \`archive\` refuses with conflicts present |
+| Archive path collision | Confirm with user whether the existing archive is stale. If confirmed, \`rm -rf specdo/archive/<name>\` and retry |
+| Hand-moved directory (broken state) | Move it back: \`mv specdo/archive/<name> specdo/changes/<name>\`, then run \`specdo archive --change <name>\` |
+
+## Next step
+
+This change is now archived. Use \`specdo list --archived\` or
+\`specdo show <name>\` to review the finalized record.
+`;
+const ARCHIVE_REFERENCE = `# specdo archive — Reference
+
+## Full command matrix
+
+| Form | Use case |
+|------|----------|
+| \`specdo archive --change <name>\` | Standard; requires sync-complete + no unresolved conflicts |
+| \`specdo archive --change <name> --skip-sync-check\` | Bypass sync gate; risk note automatically recorded |
+
+## Required preconditions (without \`--skip-sync-check\`)
+
+- \`tasks.md\` exists, parses, and every task is \`[x]\` with non-empty evidence
+- \`context.apply\` exists with \`tasksCompleted === tasksTotal\`
+- \`sync.completedAt\` non-null
+- \`sync.conflicts\` empty (forcedConflicts is OK; they were a deliberate choice)
+- Change directory still exists at \`specdo/changes/<name>/\`
+
+## Exit codes
+
+- \`0\` — archive succeeded; \`context.json\` → \`archive.archivedAt\` set
+- \`1\` — change not found / sync incomplete / unresolved conflicts present / invalid \`--change\`
+- \`3\` — filesystem move failure (target archive path collision, permission)
+
+## Archive directory layout
+
+\`\`\`
+specdo/archive/<name>/
+├── context.json             # final, with archive stage stamped
+├── proposal.md
+├── specs/                   # copy of the per-change specs at archive time
+├── design.md
+├── tasks.md
+├── apply-brief.md           # last-rendered brief
+└── archive-summary.md       # generated by archive command
+\`\`\`
+
+## archive-summary.md sections
+
+1. **Header**: change name, archivedAt, schema version
+2. **Domains**: matched + scores + clarifying answers
+3. **Tasks**: total / completed / evidence (one per task)
+4. **Sync snapshot**: completedAt, forcedConflicts, hashes
+5. **Risk notes**: only present when \`--skip-sync-check\` was used
+
+## Why move (not copy)?
+
+The directory move ensures a single source of truth — no risk of two
+diverging copies of the same change. To recover a change from archive,
+\`mv specdo/archive/<name> specdo/changes/<name>\` (then re-run \`sync\` if
+specs changed in the meantime).
+`;
+const ARCHIVE_EXAMPLES = `# specdo archive — Examples
+
+## Session 1: clean finalization
+
+\`\`\`bash
+$ specdo archive --change rate-limiting-public-api
+✓ Archived 'rate-limiting-public-api' → specdo/archive/rate-limiting-public-api/.
+Summary: specdo/archive/rate-limiting-public-api/archive-summary.md
+
+Pre-archive verify checklist (cross-check before announcing the change):
+  - [ ] (backend) Contract test passes for every endpoint
+  - [ ] (security) All auth endpoints have rate limiting
+  - [ ] (operations) Release notes include headline changes and migration actions
+\`\`\`
+
+## Session 2: trying to archive with unresolved conflicts
+
+\`\`\`bash
+$ specdo archive --change auth-flow-revamp
+# (stderr) Cannot archive: change specs are not fully synced into specdo/specs.
+# (stderr)   ! pending conflict: auth-flow/spec.md
+# (stderr)   ! pending conflict: session-policy/spec.md
+# (stderr) Re-run 'specdo sync --change auth-flow-revamp' before archiving.
+\`\`\`
+
+## Session 3: deliberate skip-sync with risk note
+
+This path is rare. Agent should confirm with the user *why* sync is being
+skipped before invoking it.
+
+> User: "Sync is broken because the spec template changed; just archive it,
+> we'll re-sync later."
+
+\`\`\`bash
+$ specdo archive --change auth-flow-revamp --skip-sync-check
+✓ Archived 'auth-flow-revamp' → specdo/archive/auth-flow-revamp/.
+Summary: specdo/archive/auth-flow-revamp/archive-summary.md
+
+Risk notes:
+  ! Sync started but never completed
+
+Pre-archive verify checklist (cross-check before announcing the change):
+  - [ ] (backend) Contract test passes for every endpoint
+  - [ ] (security) All auth endpoints have rate limiting
+  - [ ] (operations) Release notes include headline changes and migration actions
+\`\`\`
+
+## After archive: read-only lookups still work
+
+\`\`\`bash
+$ specdo list --archived
+Archived changes (2):
+
+  NAME                         STAGE      TASKS    UPDATED
+  rate-limiting-public-api     archive    6/6      ...
+  auth-flow-revamp             archive    ...      ...
+
+$ specdo show rate-limiting-public-api --type spec
+# (renders the archived spec)
+\`\`\`
+
+## Anti-pattern: hand-moving the directory
+
+\`mv specdo/changes/<name> specdo/archive/<name>\` will succeed but skip the
+summary generation and the \`archivedAt\` stamping. The change will then look
+"in flight" to \`list active\` *and* "archived" to \`list archived\` — break-
+ing both views. Always go through \`specdo archive --change <name>\`.
+`;
+// ─── Exported aggregate ────────────────────────────────────────
+export const WORKFLOW_SKILLS = [
+    {
+        name: 'specdo-explore',
+        description: "Use when the user is starting a new feature, refactor, bug fix, or any spec-driven change. Runs `specdo explore '<idea>'` to seed context.json, score domains, and create `specdo/changes/<name>/`. Trigger phrases: 'let's plan X', 'new feature', 'capture this idea', 'scaffold a proposal', 'set up a change'.",
+        body: EXPLORE_BODY,
+        references: {
+            'REFERENCE.md': EXPLORE_REFERENCE,
+            'EXAMPLES.md': EXPLORE_EXAMPLES,
+        },
+    },
+    {
+        name: 'specdo-propose',
+        description: 'Use after specdo explore completes. Runs `specdo propose --change <name>` to render OpenSpec-aligned proposal.md / specs/<capability>/spec.md / design.md / tasks.md, with SpecDo domain guidance injected into the standard skeleton. Existing handwritten artifacts are skipped unless `--force` is explicitly chosen. Trigger phrases: "generate the proposal", "scaffold tasks", "draft design doc", "kick off the change", "what is next for <change>".',
+        body: PROPOSE_BODY,
+        references: {
+            'REFERENCE.md': PROPOSE_REFERENCE,
+            'EXAMPLES.md': PROPOSE_EXAMPLES,
+        },
+    },
+    {
+        name: 'specdo-apply',
+        description: 'Use during change implementation. Runs `specdo apply --change <name>` to render apply-brief.md (with domain implement clauses) and `--done <ref> --evidence "..."` to record per-task evidence under TDD discipline. Trigger phrases: "start implementing", "I\'m done with task 1.1", "mark task 2.1", "show me the brief", "what\'s next on <change>".',
+        body: APPLY_BODY,
+        references: {
+            'REFERENCE.md': APPLY_REFERENCE,
+            'EXAMPLES.md': APPLY_EXAMPLES,
+        },
+    },
+    {
+        name: 'specdo-sync',
+        description: 'Use when every task in tasks.md is complete. Runs `specdo sync --change <name>` to promote per-change specs into `specdo/specs/`, detecting and reporting conflicts. Trigger phrases: "sync specs", "promote the spec", "merge change specs", "publish the spec", "spec is ready to be canonical".',
+        body: SYNC_BODY,
+        references: {
+            'REFERENCE.md': SYNC_REFERENCE,
+            'EXAMPLES.md': SYNC_EXAMPLES,
+        },
+    },
+    {
+        name: 'specdo-archive',
+        description: 'Use after specdo sync succeeds with no unresolved conflicts. Runs `specdo archive --change <name>` to move changes/<name>/ → archive/<name>/ with archive-summary.md. Trigger phrases: "archive the change", "finalize <change>", "close out", "we\'re done with <change>".',
+        body: ARCHIVE_BODY,
+        references: {
+            'REFERENCE.md': ARCHIVE_REFERENCE,
+            'EXAMPLES.md': ARCHIVE_EXAMPLES,
+        },
+    },
+];
+//# sourceMappingURL=workflow-content.js.map