clikit-plugin 0.3.10 → 0.3.11

package/command/research.md

@@ -1,5 +1,5 @@
 ---
-description: Deep-dive any library, API, or pattern — web search, official docs, and real GitHub examples synthesized into a saved research report.
+description: Optional standalone research pass — read discussion context, identify decision gaps, gather evidence, and write a planning-ready research report.
 agent: research
 subtask: true
 ---
@@ -10,35 +10,103 @@ You are the **Research Agent**. Execute the `/research` command.
 
 Use template at: `@.opencode/memory/_templates/research.md`
 
-## Your Task
+## Purpose
 
-Conduct deep research on a topic before planning implementation.
+Run a **GSD-inspired research pass adapted for CliKit**.
 
-## Process
+This command is not a generic fact-finding exercise. Its purpose is to close the **decision gaps that would otherwise force Plan or Build to guess**.
+
+Keep the workflow compatible with the current kit:
+- Save artifacts to `.opencode/memory/research/YYYY-MM-DD-<topic>.md`
+- Do **not** create `.planning/*` artifacts
+- Do **not** modify plans or source code
+- Use your own research tools to gather external evidence
+- Produce an output that is directly useful to `/create`, `/start`, or manual planning
+- Always read discussion context first when a discussion artifact exists
+
+## Inputs
 
-1. **Identify research questions** from spec or user request
+Use whichever context is available:
+- The explicit user request
+- Active discussion artifact
+- Active PRD / plan / handoff / prior research artifacts
+- Known constraints: language, framework, runtime, platform, versions
 
-2. **Run focused external research** with:
-   - Question to research
-   - Constraints (language, framework, versions)
-   - Format: summary | comparison | deep-dive
-   - Depth: quick | standard | deep
+If context is incomplete, state your assumption at the top of the report instead of stalling.
 
-3. **Document findings** at `.opencode/memory/research/YYYY-MM-DD-<topic>.md`
+## Process
+
+1. **Read available planning context first**
+   - Check the user request
+   - Read any relevant discussion, PRD, plan, handoff, or prior research artifacts
+   - Treat the discussion artifact as the first planning constraint input when it exists
+   - Identify what is already known so you do not repeat solved work
+
+2. **Create a Research Brief**
+   - What exact question or decision needs evidence?
+   - Why does it matter for planning or implementation?
+   - What constraints apply?
+   - What is still unknown?
+
+3. **Identify decision gaps**
+   Focus only on gaps that materially affect one of these:
+   - architecture or approach selection
+   - API / library choice
+   - version compatibility
+   - implementation boundaries
+   - test / verification strategy
+   - known risks, edge cases, or migration constraints
+
+4. **Decide whether external research is actually needed**
+   - If the available context already answers the question well enough, say so explicitly
+   - In that case, produce a short report recommending that planning proceed without more external research
+   - Otherwise, research only the high-impact gaps
+
+5. **Gather external evidence**
+   Use your tools with this priority:
+   - authoritative sources first
+   - version-pinned findings when possible
+   - real-world patterns only when they affect implementation decisions
+   - explicit conflict reporting when sources disagree
+
+6. **Synthesize for planning use**
+   - Tag claims inline as `[VERIFIED]`, `[CITED]`, or `[ASSUMED]`
+   - Assign overall confidence: `high | medium | low`
+   - Convert findings into planning guidance, not just a summary
+   - End with recommended approach, planning impact, and verification hooks
+
+7. **Write the research artifact yourself**
+   - Create or update `.opencode/memory/research/YYYY-MM-DD-<topic>.md`
+   - You may write only inside `.opencode/memory/research/`
+   - Do not write anywhere else in the repository
 
-4. **Summarize key insights** for planning
+## Tools to Use
+
+- `webfetch` — fetch known docs, changelogs, specs
+- `context7_resolve-library-id` + `context7_query-docs` — official library docs
+- `grep_searchGitHub` — real-world usage patterns
+- `websearch` — recent findings when direct docs are insufficient
+- `write` / `edit` — save the final research report to `.opencode/memory/research/`
 
 ## Research Request Format
 
 Use this request schema:
+
 ```yaml
 type: "research"
-question: "[Research question]"
+mode: "pre-plan-phase"
+question: "[Exact question or decision to research]"
+planning_goal: "[What planning decision this research should unblock]"
+decision_gaps:
+  - "[Gap 1]"
+  - "[Gap 2]"
 constraints:
   language: "[Language]"
   framework: "[Framework]"
-format: "comparison"  # summary | comparison | deep-dive
-depth: "standard"     # quick | standard | deep
+  platform: "[Platform]"
+  versions: "[Known version range]"
+format: "planning-brief"  # planning-brief | comparison | deep-dive
+depth: "standard"         # quick | standard | deep
 ```
 
 ## Research Report Template
@@ -58,13 +126,25 @@ bead_id: [optional]
 # Research: [Topic]
 
 **Question:** [Original research question]
+**Planning Goal:** [What decision this report should unblock]
+**Assumptions:** [Any assumption made due to incomplete context, or "None"]
 
 ## Summary
-[2-3 sentence answer]
+[2-4 sentence direct answer focused on planning usefulness]
+
+## Research Brief
+
+- **Decision gaps:** [What was unknown before research]
+- **Constraints:** [Language, framework, platform, versions, architecture constraints]
+- **Research scope:** [What was investigated and what was intentionally skipped]
 
 ## Key Findings
-1. [Finding 1]
-2. [Finding 2]
+
+### Finding 1: [Title]
+[VERIFIED]/[CITED]/[ASSUMED] [Finding details and why it matters]
+
+### Finding 2: [Title]
+[VERIFIED]/[CITED]/[ASSUMED] [Finding details and why it matters]
 
 ## Comparison (if applicable)
 | Option | Pros | Cons | Best For |
@@ -78,13 +158,31 @@ bead_id: [optional]
 ```
 
 ## Recommendation
-[Recommended approach]
 
-## Verification Steps
-- [ ] [Item to verify in implementation]
+**Recommended approach:** [Recommended approach]
+
+**Why:**
+1. [Reason 1]
+2. [Reason 2]
+
+## Planning Impact
+
+- [How this changes the implementation approach]
+- [What Plan or Build should do differently because of this research]
+- [Any packet, scope, dependency, or sequencing implications]
+
+## Verification Hooks
+
+- [ ] [Executable check, targeted test, or implementation-time assertion]
+- [ ] [Another verification hook]
+
+## Conflicting Evidence (if any)
+
+- [Source A says X, source B says Y, and why that matters]
 
 ## Open Questions
-- [Question needing verification]
+
+- [Question needing implementation-time confirmation]
 
 ## Sources
 | Source | Type | Reliability |
@@ -92,10 +190,14 @@ bead_id: [optional]
 | [URL/Title] | Official Docs | High |
 ```
 
-## Tools to Use
-- `websearch` — general web search
-- `webfetch` — fetch and read specific URLs
-- `context7_resolve-library-id` + `context7_query-docs` — official library documentation
-- `grep_searchGitHub` — real-world code patterns from public repos
+## Rules
+
+- Start from planning needs, not from tool-first exploration
+- Avoid redundant research when existing artifacts already answer the question
+- Research only what changes planning, sequencing, scope, or verification
+- Prefer official docs over community summaries
+- Preserve conflicting evidence instead of flattening it
+- Write only the final research artifact under `.opencode/memory/research/`
+- Save a report that another agent can use without re-reading the web
 
-Identify the research questions from the user's request or the active spec, then begin research immediately.
+Begin by deriving the research brief from the user's request and available planning context, then proceed immediately.

package/command/resume.md

@@ -22,7 +22,7 @@ You are the **Build Agent**. Execute the `/resume` command **immediately without
 ### 2. Load Related Artifacts
 
 In parallel:
-- Load spec from `.opencode/memory/specs/` (if referenced or latest)
+- Load discussion from `.opencode/memory/discussions/` (if referenced or latest)
 - Load plan from `.opencode/memory/plans/` (if referenced or latest)
 - Run `git status --short` and `git log --oneline -3`
 
@@ -46,7 +46,7 @@ Output this format, then **immediately begin the first next step**:
 
 **Drift:** <none | brief note of changes>
 
-**Next:** <first action from handoff's "What To Do Next">
+**Next:** <first action from handoff's "Next Steps">
 
 ---
 Starting now.

package/command/ship.md

@@ -32,7 +32,7 @@ Run `/verify` for full quality assurance before shipping.
 
 Before landing changes:
 - Review changed files (`git diff --name-only` and `git diff`)
-- Confirm acceptance criteria from spec/plan are satisfied
+- Confirm acceptance criteria from the plan are satisfied
 - Confirm no debug artifacts (`console.log`, `TODO`, temporary hacks)
 - Confirm changes stay within planned file impact
 

package/command/start.md

@@ -11,7 +11,7 @@ Execute the plan: claim the next packet, implement it, verify it, and close it.
 
 **Standalone use:** You can run `/start` directly if you already have a plan in `.opencode/memory/plans/` or describe what to implement and the agent will create a minimal plan inline.
 
-**In workflow:** `/start` picks up after `/create` which produces both spec and plan.
+**In workflow:** `/start` usually picks up after `/discuss → /create`, where `/create` reads the discussion artifact, runs a mandatory research pass, and then produces the plan.
 
 ## Process
 
@@ -21,15 +21,14 @@ Look for plans in `.opencode/memory/plans/`. If multiple exist, ask the user whi
 
 If no plan exists:
 - **If user described a task inline**: create a minimal single-packet plan on the fly and proceed
-- **Otherwise**: suggest running `/create` first to produce a full spec + plan
-- Check for specs in `.opencode/memory/specs/`
+- **Otherwise**: suggest running `/create` first to produce a full plan
 
 ### 2. Load Context
 
-- Read `plan.md` — get task list, file impact, dependencies
-- Read `spec.md` — understand requirements and acceptance criteria
+- Read `plan.md` — get objectives, context, task list, file impact, dependencies, and acceptance criteria
+- Read `discussion.md` (if referenced or latest relevant) — preserve locked intent and constraints
 - Read latest handoff in `.opencode/memory/handoffs/` (if exists) — resume from previous session
-- Check bead status via `mcp__beads_village__ls()`
+- Check bead status via `beads-village_ls()`
 
 ### 3. Determine Next Packet
 
@@ -42,7 +41,7 @@ If resuming from handoff, pick up `in_progress` tasks first.
 
 ### 4. Execute Packet
 
-- Reserve packet files via `mcp__beads_village__reserve()`
+- Reserve packet files via `beads-village_reserve()`
 - Follow `files_in_scope` strictly
 - Implement only the active packet
 
@@ -67,7 +66,7 @@ If verification fails twice, stop and escalate.
 
 ```
 1. ✅ Plan exists and is approved (created by /create)
-2. ✅ Context loaded (spec, plan, handoff)
+2. ✅ Context loaded (plan, discussion, handoff)
 3. ✅ Next task identified
 4. ✅ Packet selected
 5. ✅ Files reserved
@@ -76,7 +75,7 @@ If verification fails twice, stop and escalate.
 
 ## Rules
 
-- ✅ ALWAYS load plan and spec before starting
+- ✅ ALWAYS load the plan before starting
 - ✅ ALWAYS check for existing handoff to resume
 - ✅ ALWAYS execute one packet at a time
 - ✅ ALWAYS verify before marking packet done

package/command/status.md

@@ -14,9 +14,11 @@ Show the current state of work: beads, tasks, files, and git status.
 ### 1. Check Beads Village
 
 ```
-mcp__beads_village__status()
+beads-village_status()
 ```
 
+Also inspect ready work, reservations, and inbox state using the matching `beads-village_*` tools.
+
 ### 2. Check Git State
 
 ```bash
@@ -28,7 +30,7 @@ git log --oneline -5
 ### 3. Check Artifacts
 
 Look for:
-- `.opencode/memory/specs/` — Active specifications
+- `.opencode/memory/discussions/` — Discussion artifacts
 - `.opencode/memory/plans/` — Implementation plans
 - `.opencode/memory/handoffs/` — Pending handoffs
 - `.opencode/memory/research/` — Research docs
@@ -66,7 +68,7 @@ Look for:
 
 | Type | File | Status |
 |------|------|--------|
-| Spec | YYYY-MM-DD-feature.md | ✅ Active |
+| Discussion | YYYY-MM-DD-topic.md | 🧭 Intent Locked |
 | Plan | YYYY-MM-DD-feature.md | ✅ Active |
 | Research | YYYY-MM-DD-topic.md | 📚 Reference |
 | Handoff | YYYY-MM-DD-phase.md | ⏸️ Paused |
@@ -92,7 +94,7 @@ Look for:
 
 | Need | Command |
 |------|---------|
-| Start new feature | `/create` |
+| Start new feature | `/discuss` |
 | Begin implementing | `/start` |
 | Resume paused work | `/resume` |
 | Ship & land | `/ship` |
@@ -111,11 +113,11 @@ Look for:
 
 | Area | Tool |
 |------|------|
-| Beads | `mcp__beads_village__status()` |
-| Tasks | `mcp__beads_village__ls()` |
-| Ready tasks | `mcp__beads_village__ls(status="ready")` |
-| Reservations | `mcp__beads_village__reservations()` |
-| Messages | `mcp__beads_village__inbox()` |
+| Beads | `beads-village_status()` |
+| Tasks | `beads-village_ls()` |
+| Ready tasks | `beads-village_ls(status="ready")` |
+| Reservations | `beads-village_reservations()` |
+| Messages | `beads-village_inbox()` |
 | Git | `git status`, `git log` |
 | Artifacts | `glob`, `Read` |