clikit-plugin 0.3.10 → 0.3.11

package/AGENTS.md

@@ -4,24 +4,27 @@ An OpenCode plugin that provides agents, commands, skills, hooks, and a memory s
 
 ## How It Works
 
-The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `command/*.md`, and skills from `skill/*/SKILL.md`. Runtime hooks in `src/hooks/` intercept tool execution for safety (git guard, security scan) and quality (typecheck, formatting). Configuration lives in `clikit.config.json`.
+The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `command/*.md`, and skills from `skill/*/SKILL.md`. Runtime hooks in `src/hooks/` intercept tool execution for safety (git guard, security scan) and quality (typecheck, formatting). Configuration prefers `clikit.jsonc` or `clikit.json`; legacy `clikit.config.json` remains supported for backward compatibility.
 
 ## Workflow
 
 **Quick mode** (simple features):
 ```
-/create → /start → /verify → /ship
+/discuss → /create → /start → /verify → /ship
 ```
 
 **Deep mode** (complex features, research, UI):
 ```
-/create → /research → /design → /start → /verify → /ship
+/discuss → /create → /design → /start → /verify → /ship
 ```
 
-- `/create` produces both spec and plan — `/start` works directly from this output
-- `/verify` is the pre-ship gate — run before `/ship` finalizes and lands shared-checkout changes
-- `/research` = external docs, API comparison, library research
+- `/discuss` captures user intent and writes a planning-ready discussion artifact
+- `/create` reads discussion context, runs a mandatory pre-plan research pass, then produces a single XML-structured plan — `/start` works directly from this output
+- `/start` executes packet-by-packet and embeds the execute + verify loop in compressed mode
+- `/verify` is the deeper optional audit / pre-ship gate — run before `/ship` finalizes and lands shared-checkout changes
+- `/research` = optional standalone research command — read discussion context, close decision gaps with external evidence, and write a planning-ready report
 - `/design` = UI/UX design and implementation (uses Vision agent)
+- Execution happens one **Task Packet** at a time (1 concern, 1–3 files, one verify bundle)
 
 ## Where to Find Things
 
@@ -29,9 +32,9 @@ The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `
 - **Commands**: `command/*.md` — each slash command's template and instructions.
 - **Skills**: `skill/*/SKILL.md` — load relevant skills before tasks. List available skills with `ls skill/`.
 - **Schemas**: `@.opencode/schemas.md` — canonical schemas for tasks, beads, delegation, artifacts, and Task Packets.
-- **Templates**: `memory/_templates/*.md` — templates for specs, plans, research, reviews, handoffs, PRDs.
-- **Memory**: `memory/_digest.md` (auto-generated from SQLite observations on session start), plus `memory/specs/`, `memory/plans/`, `memory/research/`, `memory/handoffs/`.
-- **Config**: `clikit.config.json` — enable/disable agents, hooks, override models.
+- **Templates**: `memory/_templates/*.md` — templates for discussions, plans, research, reviews, handoffs, PRDs.
+- **Memory**: `memory/_digest.md` (auto-generated from SQLite observations on session start), plus `memory/discussions/`, `memory/plans/`, `memory/research/`, `memory/handoffs/`, `memory/reviews/`, `memory/prds/`.
+- **Config**: `.opencode/clikit.jsonc` or `.opencode/clikit.json` (preferred); `clikit.config.json` remains a legacy fallback.
 - **Full docs**: `@.opencode/README.md` — complete reference for all agents, commands, skills, hooks, and config options.
 
 ## Context Management (DCP Beta)
@@ -74,6 +77,8 @@ Load `session-management` skill for full threshold handling (including handoff t
 bun install        # dependencies
 bun run build      # compile plugin
 bun run typecheck  # type check
+bun run test       # unit tests
+bun run verify     # full local verification
 bun run dev        # watch mode
 ```
 
@@ -86,6 +91,23 @@ bun run dev        # watch mode
 - Memory tools in `src/tools/` are library code used by hooks, not registered as agent tools
 - Never force push without `--force-with-lease`
 
+## Tilth Navigation Policy
+
+When agents navigate files or search the codebase, use **tilth CLI first**.
+
+Fallback order:
+
+```text
+tilth CLI → read → grep → glob
+```
+
+- Use `read` once the target file is narrowed and you need raw content
+- Use `grep` for text-pattern fallback when tilth did not answer the question
+- Use `glob` only for explicit path enumeration
+- Use LSP after navigation when semantic confirmation is required
+
+This is a documented agent rule, not a hard runtime block.
+
 ## Issue Tracking with bd (beads)
 
 **IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
@@ -102,7 +124,7 @@ bun run dev        # watch mode
 ### Agent Core Cycle
 
 ```
-beads-village_init → inspect shared git state → beads-village_add → beads-village_claim → reserve → work → done
+beads-village_init → status/inbox → ls(ready) → show → add (if needed) → claim → reservations → reserve → work → verify → done → sync
 ```
 
 In compressed workflow, the execution unit is a **Task Packet**:
@@ -145,3 +167,9 @@ In compressed workflow, the execution unit is a **Task Packet**:
 - Use `beads-village_reserve` to surface conflicts early in the shared workspace
 - Always `reserve` files before editing in multi-agent contexts
 - Call `done` before ending a completed session; for mid-task handoff, leave the issue open and hand off without `done`
+
+### Nested Repository Note
+
+- In this workspace, `.opencode/` is treated as its own nested git repository
+- The outer repo often only shows `.opencode` as modified, while detailed diffs live inside the nested `.opencode` repo
+- It is not currently configured as a normal `.gitmodules` submodule, so inspect both git layers when auditing docs or code changes

package/README.md

@@ -5,11 +5,11 @@ Curated agents, commands, skills, and memory system for OpenCode.
 ## Features
 
 - **7 Specialized Agents**: build, plan, explore, review, vision, oracle, research
-- **15 Slash Commands**: /create, /start, /ship, /verify, /debug, /design, /research, /commit, /pr, and more
-- **22 Workflow Skills**: TDD, debugging, research, integrations, ritual-workflow, and more
+- **14 Slash Commands**: /discuss, /create, /start, /ship, /verify, /debug, /design, /research, /commit, /pr, and more
+- **26 Workflow Skills**: TDD, debugging, research, integrations, ritual-workflow, and more
 - **7 Internal Utilities**: memory (read/search/get/timeline/update/admin), observation, context-summary, cass-memory (used by hooks, not directly registered as agent tools)
-- **12 Runtime Hooks/Modules**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, tilth-first guard, truncator, memory digest, todo→beads sync, beads-context, cass-memory, and tilth-reading
-- **Memory System**: Templates, specs, plans, research artifacts with FTS5 search
+- **11 Runtime Hooks/Modules**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, truncator, memory digest, todo→beads sync, beads-context, cass-memory, and tilth-reading
+- **Memory System**: Templates, discussions, plans, research artifacts with FTS5 search
 - **Extended Permissions**: doom_loop, external_directory controls
 - **Configurable**: Enable/disable agents, override models, customize behavior
 
@@ -84,21 +84,22 @@ After installation, use these commands:
 
 **Quick mode** (simple features):
 ```
-/create → /start → /verify → /ship
+/discuss → /create → /start → /verify → /ship
 ```
 
 **Deep mode** (complex features, research, UI):
 ```
-/create → /research → /design → /start → /verify → /ship
+/discuss → /create → /design → /start → /verify → /ship
 ```
 
 Workflow notes:
-- All 15 commands work **standalone** — the pipeline is recommended, not required
-- `/create` explores codebase first, then produces both spec and plan
+- All 14 commands work **standalone** — the pipeline is recommended, not required
+- `/discuss` runs a pre-create discussion phase — clarify intent, confirm assumptions, and save a planning-ready discussion artifact
+- `/create` explores codebase first, consumes discussion context, runs a mandatory pre-plan research pass, then produces a single XML-structured plan
 - `/start` executes the plan, one Task Packet at a time — creates a minimal inline plan if none exists
 - `/verify` runs all 4 gates (typecheck, tests, lint, build) + deep review — use anytime, not just pre-ship
 - `/ship` finalizes work in the shared checkout — commit, sync, and land on the repo default branch; `/pr` is optional and only for explicit PR-based exceptions
-- `/research` conducts external research — use standalone before any complex implementation
+- `/research` is an optional standalone research command — it reads discussion context first, closes decision gaps with external evidence, and saves a planning-ready report
 - `/design` implements UI/UX with variant exploration and a11y — uses Vision agent
 - Beads is the live execution source of truth
 - Plans decompose work into **Task Packets** (1 concern, 1–3 files, one verify bundle)
@@ -149,7 +150,6 @@ Project config overrides user config.
     "git_guard": { "enabled": true },
     "security_check": { "enabled": true },
     "subagent_question_blocker": { "enabled": true },
-    "tilth_first_guard": { "enabled": true, "log": false },
     "truncator": { "enabled": true, "packet_friendly": true },
     "memory_digest": { "enabled": true, "compact_mode": true },
     "todo_beads_sync": { "enabled": false, "mode": "disabled" },
@@ -190,7 +190,6 @@ Project config overrides user config.
 | `git_guard` | on | Blocks dangerous git commands (force push, hard reset, rm -rf) |
 | `security_check` | on | Scans for secrets/credentials before git commits |
 | `subagent_question_blocker` | on | Prevents subagents from asking clarifying questions |
-| `tilth_first_guard` | on | Requires `@explore` to make an explicit `tilth` CLI attempt before `read` / `grep` / `glob` fallback |
 | `truncator` | on | Truncates large outputs to prevent context overflow |
 | `memory_digest` | on | Generates `memory/_digest.md` index + topic files (`decision.md`, `learning.md`, etc.) from SQLite observations |
 | `todo_beads_sync` | off | Legacy todo→Beads mirror; disabled in compressed workflow |
@@ -203,9 +202,9 @@ Project config overrides user config.
 | Agent | Mode | Description |
 |-------|------|-------------|
 | `build` | primary | Primary code executor, implements plans |
-| `plan` | primary | Creates implementation plans from specs |
+| `plan` | primary | Handles `/discuss` intent locking and `/create` planning, producing discussion artifacts and XML-structured plans |
 | `oracle` | subagent | Deep code inspection + architecture trade-off analysis |
-| `research` | subagent | External docs + GitHub evidence research |
+| `research` | subagent | External evidence specialist; writes research artifacts for `/research` and Plan's pre-plan pass |
 | `explore` | subagent | Fast codebase exploration |
 | `review` | subagent | Code review & quality gate |
 | `vision` | subagent | Design direction + visual implementation |
@@ -214,13 +213,14 @@ Default active roles in compressed workflow: `build`, `plan`, `review`, plus coo
 
 ## Commands
 
-Run with `/command-name` in OpenCode. **All 15 commands work standalone** — the pipeline is a recommended flow, not a requirement.
+Run with `/command-name` in OpenCode. **All 14 commands work standalone** — the pipeline is a recommended flow, not a requirement.
 
 ### Workflow pipeline
 | Command | Standalone? | One-liner |
 |---------|-------------|-----------|
-| `/create` | ✅ | Explore codebase → interview requirements → produce spec + plan |
-| `/research` | ✅ | Deep-dive any library, API, or pattern with saved report |
+| `/discuss` | ✅ | Pre-create discussion phase — lock intent, confirm assumptions, save planning-ready artifact |
+| `/create` | ✅ | Explore codebase → load discussion context → run mandatory pre-plan research → produce a single XML-structured plan |
+| `/research` | ✅ | Optional standalone research pass — read discussion context, gather evidence, save planning-ready report |
 | `/design` | ✅ | UI/UX design + implementation — variant exploration, a11y, responsive (Vision agent) |
 | `/start` | ✅ | Execute plan packets — creates minimal inline plan if none exists |
 | `/ship` | ✅ | Commit + land shared-checkout changes on the default branch — self-review built in, `/verify` recommended |
@@ -230,14 +230,12 @@ Run with `/command-name` in OpenCode. **All 15 commands work standalone** — th
 | Command | One-liner |
 |---------|-----------|
 | `/debug` | Reproduce → 5-Whys root cause → fix → regression test |
-| `/issue` | Instantly capture a task, bug, or idea as a Beads issue |
 | `/status` | Workspace snapshot — Beads tasks, git state, active artifacts |
 | `/init` | Bootstrap CliKit — scaffold dirs + write tailored AGENTS.md |
 | `/handoff` | Auto-capture session state for graceful pause |
 | `/resume` | Pick up cold from latest handoff, no warm-up questions |
 | `/commit` | Auto-detect type/scope → perfect Conventional Commit message |
 | `/pr` | Optional PR flow for explicit branch-based review exceptions |
-| `/import-plan` | Import Jira/Notion/Linear tasks → Beads issues + plan |
 
 ## Skills
 
@@ -318,14 +316,14 @@ bun run dev
 │   ├── config.ts     # Config loader
 │   ├── types.ts      # Type definitions
 │   ├── agents/       # Agent loaders
-│   ├── skills/       # Skill loaders
+│   ├── skill/        # Skill loaders
 │   ├── tools/        # Internal utilities (memory, context-summary, cass-memory)
-│   └── hooks/        # Runtime hooks (10 modules)
+│   └── hooks/        # Runtime hooks (11 modules + index)
 ├── skill/            # Skill definitions (*.md)
 ├── command/          # Command definitions (*.md)
 ├── memory/           # Memory system
-│   ├── _templates/   # Document templates
-│   ├── specs/        # Specifications
+│   ├── _templates/   # Document templates (discussion, plan, research, handoff, review, PRD)
+│   ├── discussions/  # Discussion artifacts
 │   ├── plans/        # Implementation plans
 │   ├── research/     # Research artifacts
 │   ├── reviews/      # Code reviews

package/command/create.md

@@ -1,23 +1,36 @@
 ---
-description: Kick off any feature — explore codebase, interview requirements, produce spec + implementation plan. Use standalone or as the first step of the workflow.
+description: Turn clarified intent into an execution-ready XML-structured plan — explore codebase, synthesize discussion context, fill remaining gaps, and write a single implementation plan.
 agent: plan
 ---
 
 You are the **Plan Agent**. Execute the `/create` command.
 
-## Templates
+## Template
 
-- Spec: `@.opencode/memory/_templates/spec.md`
 - Plan: `@.opencode/memory/_templates/plan.md`
 
+## Inputs
+
+Prefer discussion-first workflow when available:
+- Discussion: `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md`
+- Research: `.opencode/memory/research/YYYY-MM-DD-<topic>.md`
+
 ## Execution Rules
 
 - **DO NOT** start with generic questions — explore the codebase FIRST
+- **DO** read any relevant discussion artifact before re-eliciting requirements or triggering research
 - **DO NOT** end turns passively — always end with a specific question or action
-- Auto-transition to spec + plan generation when self-clearance passes
+- Auto-transition to plan generation when self-clearance passes
 
 ## Process
 
+### 0. Load Discussion Context First
+
+- Read any relevant discussion artifact under `.opencode/memory/discussions/`
+- Treat `Locked Decisions` as planning constraints, not suggestions
+- Treat `Open Questions` as the only discussion leftovers worth re-asking
+- If no discussion artifact exists, continue normally — `/create` must remain standalone-compatible
+
 ### 1. Proactive Exploration (BEFORE asking questions)
 
 Fire Explore agents in parallel immediately:
@@ -25,7 +38,7 @@ Fire Explore agents in parallel immediately:
 - Find test infrastructure (framework, coverage, examples)
 - Find related code that this feature will integrate with
 
-### 2. Informed Interview
+### 2. Focused Follow-Up
 
 Use exploration results to ask SPECIFIC questions across 5 dimensions:
 - **Problem & Context** — Why is this needed? (reference what you found in codebase)
@@ -34,28 +47,45 @@ Use exploration results to ask SPECIFIC questions across 5 dimensions:
 - **Users** — Primary/secondary users?
 - **Constraints** — Technical, business, timeline?
 
-Max 3 questions per turn. Update draft after each exchange.
+Rules:
+- Max 3 questions per turn
+- Do **not** re-ask anything already locked by `/discuss`
+- Prefer resolving only the gaps that still block plan generation
+- If ambiguity remains high and no discussion artifact exists, you may recommend `/discuss` for a cleaner first pass, but `/create` must still work standalone
+
+Update draft after each exchange.
+
+### 3. Mandatory Pre-Plan Research Pass
 
-### 3. Self-Clearance Check
+Before finalizing the plan, you MUST run a research pass via `@research`.
 
-When ALL of these are true, auto-transition to spec + plan generation:
+Treat this as a `/research`-style contract, not an optional side lookup.
+
+Research pass requirements:
+- Provide the active discussion artifact (or note that none exists)
+- Ask `@research` to read discussion context first, then gather only the external evidence that materially affects planning
+- Require `@research` to save or update a research artifact under `.opencode/memory/research/`
+- Treat the resulting research artifact as a planning input, not an optional appendix
+
+If the research pass finds no meaningful external gap, it should still produce a short artifact that records that conclusion so planning remains auditable.
+
+### 4. Self-Clearance Check
+
+When ALL of these are true, auto-transition to plan generation:
 - Core problem understood and confirmed
 - Scope boundaries defined
 - Enough info for acceptance criteria
 - Codebase patterns identified
+- Locked decisions from discussion artifact preserved
+- Research artifact created or updated by the mandatory pre-plan research pass
 - No critical open questions
 
-### 4. Generate Spec
-
-Write to `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md` using the spec template.
-
-**Acceptance criteria MUST be agent-executable** — commands with expected outputs, not "user manually verifies."
-
 ### 5. Memory & History Mining (parallel with plan generation)
 
 **Memory mining** (Plan reads directly — has file read access):
 ```
 Read: ".opencode/memory/_digest.md" — Compact index of memory topics and highlights
+Read: ".opencode/memory/discussions/" — Any related discussion artifacts
 Read: ".opencode/memory/decision.md" — Architectural decisions
 Read: ".opencode/memory/learning.md" — Learnings and gotchas
 Read: ".opencode/memory/blocker.md" — Past blockers and mitigations
@@ -76,18 +106,68 @@ Explore: "Mine git log for conventions. Return:
 
 Write to `.opencode/memory/plans/YYYY-MM-DD-<feature>.md` using the plan template.
 
+The plan file is the single pre-implementation artifact. It must stay in Markdown with YAML frontmatter plus XML-style sections.
+
+The plan must use this structure:
+
+```markdown
+---
+phase: XX-name
+plan: NN
+type: execute
+wave: N
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: []
+must_haves:
+  truths: []
+  artifacts: []
+  key_links: []
+---
+
+<objective>
+[What this plan accomplishes]
+</objective>
+
+<context>
+[Relevant context files and source references]
+</context>
+
+<tasks>
+<task type="auto">
+  <name>Task 1: [Action-oriented name]</name>
+  <files>path/to/file.ext</files>
+  <action>[Specific implementation]</action>
+  <verify>[Command or check]</verify>
+  <done>[Acceptance criteria]</done>
+</task>
+</tasks>
+
+<verification>
+[Overall phase checks]
+</verification>
+
+<success_criteria>
+[Measurable completion]
+</success_criteria>
+```
+
 **Task decomposition rules:**
 - Each task must contain a **Task Packet**
 - 1 packet = 1 concern = 1-3 files
 - Group tasks into parallel waves where possible
 - Every packet must define `files_in_scope`, `verification_commands`, and `escalate_if`
+- Include relevant discussion artifacts in plan references and packet context when they materially constrain execution
 
 **File Impact = BUILD BOUNDARY:**
 Build Agent may ONLY touch files listed here. Missing a file = Build can't modify it.
 
 ### 7. Quality Self-Review
 
-Before presenting spec + plan, verify:
+Before presenting the plan, run a verification loop and only stop when all conditions pass, a blocker requires escalation, or one focused user clarification is required.
+
+Before presenting the plan, verify:
 - [ ] Every task has task_id, acceptance criteria, effort, priority
 - [ ] File Impact covers ALL files across ALL tasks
 - [ ] No dependency cycles
@@ -95,24 +175,27 @@ Before presenting spec + plan, verify:
 - [ ] All acceptance criteria are agent-executable
 - [ ] Top 2+ risks assessed
 
-### 8. Create Bead & Guide
+### 8. Approval, Create Beads, & Guide
 
-1. Call `mcp__beads_village__add()` with title, description, and priority
-2. Present spec + plan to user
-3. After approval: "Spec and plan ready. Use `/start` to begin execution."
+1. Present plan to user
+2. Wait for explicit approval
+3. Only after approval, call `beads-village_add()` with title, description, and priority
+4. Then say: "Plan ready. Use `/start` to begin execution."
 
 ## Rules
 
 - ✅ Explore codebase BEFORE asking user questions
 - ✅ Write agent-executable acceptance criteria
 - ✅ Tag assumptions as Confirmed/Unconfirmed
+- ✅ Run a mandatory pre-plan research pass and persist its artifact before finalizing the plan
 - ✅ Auto-transition when clearance check passes
-- ✅ Always produce BOTH spec and plan before guiding to `/start`
+- ✅ Always produce a single execution-ready plan before guiding to `/start`
 - ✅ Mine memory for past decisions, learnings, blockers
 - ✅ Delegate git history mining to Explore (Plan has bash: false)
 - ✅ Include Conventions & Past Decisions section in plan
 - ✅ Every task must include a Task Packet
 - ✅ File Impact is the build contract
+- ✅ Create Beads issues only after explicit approval
 - ❌ NEVER ask generic questions without codebase context
 - ❌ NEVER skip acceptance criteria
 - ❌ NEVER end passively — always question or action
@@ -120,3 +203,4 @@ Before presenting spec + plan, verify:
 - ❌ NEVER write "user manually tests..." criteria
 - ❌ NEVER omit File Impact section
 - ❌ NEVER skip gap analysis
+- ❌ NEVER skip the mandatory research pass, even when it only confirms that no extra external evidence is needed

package/command/discuss.md

@@ -0,0 +1,111 @@
+---
+description: Pre-create discussion phase — clarify intent, lock preferences, confirm assumptions, and write a planning-ready discussion artifact.
+agent: plan
+---
+
+You are the **Plan Agent** operating in discussion mode. Execute the `/discuss` command and write only the discussion artifact.
+
+## Template
+
+Use template at: `@.opencode/memory/_templates/discussion.md`
+
+## Purpose
+
+Run a **pre-create discussion phase adapted for CliKit**.
+
+This command exists to capture the decisions that `/create`, `/research`, and `/start` should not have to guess.
+
+Use it to:
+- clarify the intended outcome
+- lock user-facing preferences and constraints
+- confirm the highest-impact assumptions
+- defer ideas that are intentionally out of scope
+- produce a planning-ready artifact for `/create`
+
+Keep the workflow compatible with the current kit:
+- Save artifacts to `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md`
+- Do **not** create `.planning/*` artifacts
+- Do **not** write plans, research artifacts, or source code
+- Do **not** create Beads issues
+- Produce an output that `/create` can consume directly
+
+## Inputs
+
+Use whichever context is available:
+- The explicit user request
+- Prior discussion, PRD, plan, handoff, or research artifacts
+- Relevant codebase files or patterns when they help clarify realistic options
+- Known constraints: language, framework, runtime, platform, timeline, policy
+
+If context is incomplete, capture the uncertainty in the artifact instead of blocking.
+
+## Process
+
+1. **Read available context first**
+   - Check the user request and recent conversation
+   - Read any relevant discussion, PRD, plan, handoff, or research artifacts
+   - Inspect the codebase only far enough to ground the conversation in real patterns
+
+2. **Frame the discussion goal**
+   - What outcome is the user trying to achieve?
+   - What part of the request is already clear?
+   - What ambiguity would cause `/create` or `/research` to guess?
+
+3. **Surface gray areas and assumptions**
+   Focus on ambiguity that materially affects:
+   - scope boundaries
+   - workflow or UX expectations
+   - integration direction
+   - constraints or non-goals
+   - sequencing between discuss/create/research/build
+
+4. **Run an adaptive discussion**
+   - Ask focused, high-signal questions
+   - Prefer decisions over open-ended brainstorming once enough context exists
+   - Avoid re-asking anything already confirmed by prior artifacts
+   - If the repository strongly suggests a sensible default, present it as an assumption for confirmation
+
+5. **Lock what is known and defer the rest**
+   - Record confirmed decisions explicitly
+   - Separate confirmed assumptions from unresolved questions
+   - Push non-critical ideas into a deferred section rather than expanding scope
+
+6. **Write the discussion artifact yourself**
+   - Create or update `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md`
+   - You may write only inside `.opencode/memory/discussions/`
+   - Do not write anywhere else in the repository
+
+7. **Hand off to `/create`**
+   - End by telling the user the discussion artifact is ready
+   - Point them to `/create` as the next step for plan generation
+
+## Discussion Request Format
+
+Use this request schema:
+
+```yaml
+type: "discussion"
+mode: "pre-create-phase"
+topic: "[Feature or topic being clarified]"
+goal: "[What outcome the user wants]"
+ambiguities:
+  - "[Ambiguity 1]"
+  - "[Ambiguity 2]"
+constraints:
+  product: "[User or business constraints]"
+  technical: "[Technical context if relevant]"
+  workflow: "[Any sequencing or approval constraints]"
+format: "discussion-brief"
+depth: "standard"         # quick | standard | deep
+```
+
+## Rules
+
+- Start from user intent, not technical implementation detail
+- Clarify only what changes planning, sequencing, or execution direction
+- Prefer concrete decisions over vague summaries
+- Preserve unresolved items instead of guessing them away
+- Write only the final discussion artifact under `.opencode/memory/discussions/`
+- Save a report that `/create` can use without re-running the conversation
+
+Begin by deriving the discussion goal from the user's request and available context, then proceed immediately.

package/command/handoff.md

@@ -21,18 +21,19 @@ Run these in parallel:
 - `git log --oneline -5` — recent commits
 - `git status --short` — uncommitted changes
 - `git diff --stat` — what changed
+- Check `.opencode/memory/discussions/` for active discussion artifact
 - Check `.opencode/memory/plans/` for active plan
-- Check `.opencode/memory/specs/` for active spec
+- Check `.opencode/memory/research/` for active research artifact
 - Check ritual state if exists
 
 ### 2. Write Handoff
 
-Create `.opencode/memory/handoffs/YYYY-MM-DD-handoff.md` with this structure:
+Create `.opencode/memory/handoffs/YYYY-MM-DD-<phase>.md` with this structure:
 
 ```markdown
 ---
 date: YYYY-MM-DD
-phase: discover | plan | implement | verify | complete
+phase: discussed | researched | planned | implementing | validating
 branch: <branch>
 ---
 
@@ -47,10 +48,11 @@ branch: <branch>
 - Uncommitted: <yes/no, list if yes>
 
 ## Active Artifacts
-- Spec: `<path>` (if exists)
+- Discussion: `<path>` (if exists)
 - Plan: `<path>` (if exists)
+- Research: `<path>` (if exists)
 
-## What To Do Next
+## Next Steps
 1. <immediate next action — be specific>
 2. <following action>
 3. <after that>

package/command/init.md

@@ -33,7 +33,7 @@ export default CliKitPlugin;
 ### 3) Create `.opencode` structure
 
 Ensure these exist:
-- `.opencode/memory/specs`
+- `.opencode/memory/discussions`
 - `.opencode/memory/plans`
 - `.opencode/memory/research`
 - `.opencode/memory/reviews`
@@ -97,7 +97,7 @@ Return:
 
 ### Next
 1. Restart OpenCode
-2. Run /create to begin work
+2. Run /discuss to begin work
 ```
 
 ## Important behavior

package/command/pr.md

@@ -1,5 +1,5 @@
 ---
-description: Optional branch-based utility. Generate a complete PR description from git diff — summary, file changes, test evidence, linked spec/plan — then create it via gh when the user or repo policy explicitly requires a PR.
+description: Optional branch-based utility. Generate a complete PR description from git diff — summary, file changes, test evidence, linked plan — then create it via gh when the user or repo policy explicitly requires a PR.
 agent: build
 ---
 
@@ -37,7 +37,6 @@ If you are still on the shared default branch, stop and ask before proceeding
 
 ### 2. Load Artifacts
 
-- `spec.md` — Link requirements
 - `plan.md` — Link implementation plan
 - `review.md` — Link review results (if exists)
 - Bead info — Get from beads village
@@ -67,7 +66,6 @@ gh pr create \
 
 ### Related
 - **Bead:** [ID]
-- **Spec:** `.opencode/memory/specs/YYYY-MM-DD-feature.md`
 - **Plan:** `.opencode/memory/plans/YYYY-MM-DD-feature.md`
 
 ---
@@ -172,7 +170,7 @@ pnpm lint
 
 ## Rules
 
-- ✅ ALWAYS link to spec/plan/bead
+- ✅ ALWAYS link to plan/bead
 - ✅ ALWAYS include testing info
 - ✅ ALWAYS run checks before PR
 - ✅ ALWAYS self-review first