clikit-plugin 0.3.9 → 0.3.11

package/memory/_templates/plan.md

@@ -7,183 +7,90 @@ Use this template when creating implementation plans.
 ---
 
 ```markdown
-# Implementation Plan: [Feature]
-
-**Date:** YYYY-MM-DD
-**Author:** [Name]
-**Status:** Draft | Approved
-**bead_id:** [ID]
-
----
-
-## Overview
-
-[Brief description of what will be built]
-
-## References
-
-- **Spec:** `.opencode/memory/specs/YYYY-MM-DD-descriptor.md`
-- **PRD:** `.opencode/memory/prds/YYYY-MM-DD-feature.md` (if applicable)
-- **Research:** `.opencode/memory/research/YYYY-MM-DD-topic.md` (if applicable)
-
----
-
-## Conventions & Past Decisions
-
-### Git Conventions
-- **Commit format:** [e.g., conventional commits, prefix patterns]
-- **Branch naming:** [e.g., feature/xxx, bead/B-xxx]
-- **File organization:** [patterns observed from recent commits]
-
-### Relevant Past Decisions
-- [Decision from memory/handoffs that affects this plan, or "None found"]
-
-### Learnings & Gotchas
-- [Past learnings, blockers, workarounds from memory that apply, or "None found"]
-
-### Prior Research
-- [Relevant findings from .opencode/memory/research/*.md, or "None found"]
-
----
-
-## Tasks
-
-### Task 1: [Title]
-
-| Field | Value |
-|-------|-------|
-| **task_id** | T-001 |
-| **type** | task \| bug \| feature \| chore |
-| **assignee** | build \| fe \| be \| mobile \| devops |
-| **effort** | S \| M \| L \| XL |
-| **priority** | P0 \| P1 \| P2 |
-| **status** | not_started \| in_progress \| blocked \| done |
-| **dependencies** | [T-xxx] or none |
-
-**Description:**
-[What needs to be done]
-
-**Input:**
-- [Required artifacts/context]
-
-**Output:**
-- [Expected deliverables]
-- [Files to create/modify]
-
-**Acceptance Criteria:**
-- [ ] AC-01: [Criteria]
-- [ ] AC-02: [Criteria]
-
-**Boundaries:**
-- [What NOT to do]
-
-**Task Packet:**
-- **packet_id:** P-T-001
-- **goal:** [Single executable concern]
-- **files_in_scope:**
-  - create: [`path/to/new-file.ts`]
-  - modify: [`path/to/existing.ts`]
-  - delete: []
-- **verification_commands:**
-  - `bun run typecheck`
-  - `bun test path/to/test.ts`
-- **risks:**
-  - [Top risk for this packet]
-- **escalate_if:**
-  - [Verification fails twice]
-  - [A file outside scope must be edited]
-
----
-
-### Task 2: [Title]
-
-[Repeat structure]
-
----
-
-## File Impact
-
-**Files to CREATE:**
-- `path/to/new-file.ts` — [Purpose]
-
-**Files to MODIFY:**
-- `path/to/existing.ts` — [Reason]
-
-**Files to DELETE:**
-- (none)
-
----
-
-## Execution Model
-
-- Workflow quick mode: `/create → /start → /verify → /ship`
-- Workflow deep mode: `/create → /research → /design → /start → /verify → /ship`
-- Execution unit: **Task Packet**
-- Source of truth: **Beads**
-- `/start`: execute + per-packet verify loop
-- `/verify`: pre-ship gate (all 4 checks, SHIP_READY verdict required before `/ship`)
-- `/ship`: commit + sync/push landed changes in the shared checkout; `/pr` is an explicit exception path
-
----
-
-## Dependencies
-
-```mermaid
-graph TD
-    T001[T-001: Title] --> T002[T-002: Title]
-    T002 --> T003[T-003: Title]
-    T001 --> T003
-```
-
----
-
-## Effort Summary
-
-| Task | Effort | Priority |
-|------|--------|----------|
-| T-001 | S | P0 |
-| T-002 | M | P0 |
-| T-003 | S | P1 |
-
-**Total Estimated Effort:** [X days/weeks]
-
----
-
-## Risk Assessment
-
-| Risk | Probability | Impact | Mitigation |
-|------|-------------|--------|------------|
-| [Risk 1] | L/M/H | L/M/H | [Mitigation] |
-
----
-
-## Quick Mode Eligibility
-
-Tasks eligible for Quick Mode (no full plan needed):
-- [ ] T-001 (S, ≤3 files, no security/db/api)
-
-## Packet Checklist
-
-- [ ] Every task has a packet_id
-- [ ] Every packet stays within 1–3 files
-- [ ] Every packet has executable verification commands
-- [ ] Every packet has an escalate_if clause
-- [ ] File Impact matches all packet scopes
-
 ---
-
-## Rollout Plan
-
-| Phase | Tasks | Milestone |
-|-------|-------|-----------|
-| Phase 1 | T-001, T-002 | [Milestone] |
-| Phase 2 | T-003 | [Milestone] |
-
+phase: XX-name
+plan: NN
+type: execute
+wave: N
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: []
+must_haves:
+  truths: []
+  artifacts: []
+  key_links: []
 ---
 
-## Approval
-
-- [ ] Plan reviewed
-- [ ] User approved
-- [ ] Ready for implementation
+<objective>
+[What this plan accomplishes]
+</objective>
+
+<context>
+[Relevant context files and source references]
+</context>
+
+<tasks>
+<task type="auto">
+  <packet_id>P-T001</packet_id>
+  <task_id>T-001</task_id>
+  <name>Task 1: [Action-oriented name]</name>
+  <goal>[One executable concern]</goal>
+  <files_in_scope>
+    <create>[]</create>
+    <modify>["path/to/file.ext"]</modify>
+    <delete>[]</delete>
+  </files_in_scope>
+  <dependencies>[]</dependencies>
+  <action>[Specific implementation]</action>
+  <acceptance_criteria>
+    <criterion cmd="bun test path/to/test.ts">exits 0</criterion>
+    <criterion cmd="lsp_diagnostics path/to/file.ext">zero errors</criterion>
+  </acceptance_criteria>
+  <verification_commands>
+    <command>bun run typecheck</command>
+    <command>bun test path/to/test.ts</command>
+  </verification_commands>
+  <risks>
+    <risk>[Top risk for this packet]</risk>
+  </risks>
+  <escalate_if>
+    <condition>Verification fails after 2 attempts</condition>
+    <condition>Implementation requires file outside files_in_scope</condition>
+  </escalate_if>
+  <context_refs>
+    <discussion_paths>[]</discussion_paths>
+    <plan_path>.opencode/memory/plans/YYYY-MM-DD-<feature>.md</plan_path>
+    <research_paths>[]</research_paths>
+  </context_refs>
+</task>
+</tasks>
+
+<file_impact>
+  <create>[]</create>
+  <modify>["path/to/file.ext"]</modify>
+  <delete>[]</delete>
+</file_impact>
+
+<dag>
+  <wave number="1">P-T001</wave>
+</dag>
+
+<boundaries>
+  <always>[Required invariants and constraints]</always>
+  <ask_first>[Changes that require explicit approval]</ask_first>
+  <never>[Out-of-scope or forbidden changes]</never>
+</boundaries>
+
+<out_of_scope>
+[Explicitly excluded work]
+</out_of_scope>
+
+<verification>
+[Overall phase checks]
+</verification>
+
+<success_criteria>
+[Measurable completion]
+</success_criteria>
 ```

package/memory/_templates/research.md

@@ -4,6 +4,8 @@ Use this template when documenting research findings.
 
 **Output path:** `.opencode/memory/research/YYYY-MM-DD-<topic>.md`
 
+This template is optimized for **pre-plan research**: the report should reduce guessing for Plan and Build, not just summarize information.
+
 ---
 
 ```markdown
@@ -21,25 +23,35 @@ bead_id: [optional]
 # Research: [Topic]
 
 **Question:** [Original research question]
+**Planning Goal:** [What planning or implementation decision this report should unblock]
+**Assumptions:** [Any assumption made because context was incomplete, or "None"]
 
 ---
 
 ## Summary
 
-[2-3 sentence answer to the research question]
+[2-4 sentence answer that directly helps planning or execution]
+
+---
+
+## Research Brief
+
+- **Decision gaps:** [Which unknowns this research was meant to resolve]
+- **Constraints:** [Language, framework, platform, architecture, version limits]
+- **Research scope:** [What was investigated and what was intentionally excluded]
 
 ---
 
 ## Key Findings
 
 ### Finding 1: [Title]
-[Details]
+[VERIFIED]/[CITED]/[ASSUMED] [Details and why this matters]
 
 ### Finding 2: [Title]
-[Details]
+[VERIFIED]/[CITED]/[ASSUMED] [Details and why this matters]
 
 ### Finding 3: [Title]
-[Details]
+[VERIFIED]/[CITED]/[ASSUMED] [Details and why this matters]
 
 ---
 
@@ -76,10 +88,24 @@ bead_id: [optional]
 
 ---
 
-## Verification Steps
+## Planning Impact
+
+- [How this research should influence the plan or packet boundaries]
+- [What Build should avoid or sequence carefully]
+- [Any dependency, migration, or scope implications]
+
+---
+
+## Verification Hooks
+
+- [ ] [Targeted test, command, or assertion to run during implementation]
+- [ ] [Another implementation-time check]
+
+---
+
+## Conflicting Evidence (if any)
 
-- [ ] [Item to verify in implementation]
-- [ ] [Test with specific scenario]
+- [Source A says X, source B says Y, and the practical implication]
 
 ---
 

package/memory/_templates/review.md

@@ -1,6 +1,6 @@
 # Review Template
 
-Use this template when reviewing code, PRDs, specs, or plans.
+Use this template when reviewing code, PRDs, or plans.
 
 **Output path:** `.opencode/memory/reviews/YYYY-MM-DD-<subject>-review.md`
 
@@ -8,7 +8,7 @@ Use this template when reviewing code, PRDs, specs, or plans.
 
 ```markdown
 ---
-type: Code | PRD | Spec | Plan | Security
+type: Code | PRD | Plan | Security
 date: YYYY-MM-DD
 reviewer: [Name/Agent]
 artifact: [Path to reviewed artifact]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clikit-plugin",
-  "version": "0.3.9",
-  "description": "OpenCode plugin — 7 agents, 15 commands, 25 skills, 10 hooks",
+  "version": "0.3.11",
+  "description": "OpenCode plugin — 7 agents, 14 commands, 26 skills, 11 hooks",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -55,7 +55,7 @@
   },
   "homepage": "https://github.com/KiraKas-Tr/CliKit#readme",
   "dependencies": {
-    "@opencode-ai/plugin": "1.2.25",
+    "@opencode-ai/plugin": "1.3.13",
     "gray-matter": "^4.0.3"
   },
   "devDependencies": {

package/skill/requesting-code-review/SKILL.md

@@ -15,7 +15,7 @@ Request review after: major features, significant refactors, before merge, when
 |------|---------|
 | Diff range | `a1b2c3d..e4f5g6h` |
 | What changed | "Added JWT auth with refresh tokens" |
-| Spec/plan ref | `.opencode/memory/specs/auth.md` |
+| Plan ref | `.opencode/memory/plans/auth.md` |
 | Known gaps | "Edge case X not handled yet" |
 
 ## Dispatch
@@ -23,7 +23,7 @@ Request review after: major features, significant refactors, before merge, when
 ```
 @review: review changes from <sha>..<sha>
 Context: <what was built>
-Spec: <path>
+Plan: <path>
 Known issues: <list or none>
 ```
 

package/skill/ritual-workflow/SKILL.md

@@ -14,7 +14,7 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 | Phase | Gate (must pass before advancing) |
 |-------|-----------------------------------|
 | DISCOVER | Problem statement written, success criteria defined |
-| PLAN | User approves spec + plan |
+| PLAN | User approves plan |
 | IMPLEMENT | All planned tasks checked off |
 | VERIFY | typecheck + tests + lint + build all pass |
 | COMPLETE | Changes landed on default branch / deployed |
@@ -23,8 +23,10 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 
 | Mode | Commands |
 |------|----------|
-| Quick | `/create` → `/start` → `/verify` → `/ship` |
-| Deep (research/UI) | `/create` → `/research` → `/design` → `/start` → `/verify` → `/ship` |
+| Quick | `/discuss` → `/create` → `/start` → `/verify` → `/ship` |
+| Deep (UI) | `/discuss` → `/create` → `/design` → `/start` → `/verify` → `/ship` |
+
+`/create` includes a mandatory pre-plan research pass via `@research` before it finalizes the plan. `/research` remains available as an optional standalone command when the user wants a dedicated evidence pass.
 
 ## Enforcement
 
@@ -37,5 +39,5 @@ DISCOVER → PLAN → IMPLEMENT → VERIFY → COMPLETE
 
 - Implementing without a plan
 - Marking COMPLETE with failing `/verify` gates
-- Moving forward without user approval on spec/plan
+- Moving forward without user approval on the plan
 - Running `/ship` before SHIP_READY

package/src/agents/AGENTS.md

@@ -7,16 +7,16 @@ Each `.md` file in this directory defines an agent. The frontmatter sets model,
 | Agent | Role | Mode | Modifies Code? |
 |---|---|---|---|
 | **@build** | Primary orchestrator and code executor. Delegates, implements, verifies. | primary | ✅ Yes |
-| **@plan** | Primary strategic planner. Produces specs and plans. Architecture-aware. | primary | ❌ Plans only |
+| **@plan** | Primary strategic planner. Handles `/discuss` intent locking and `/create` plan generation. Produces discussion artifacts and XML-structured plans. | primary | ❌ Code / ✅ planning artifacts |
 | **@oracle** | High-depth read-only advisor for hard architecture trade-offs, complex debugging, and second-opinion analysis. Expensive specialist — invoke only when `@explore` or `@research` cannot resolve the question. | subagent | ❌ Read-only |
 | **@explore** | Fast local codebase navigator. Symbol definitions, usages, file structure, git history. Read-only. | subagent | ❌ Read-only |
-| **@research** | External evidence specialist. Docs, APIs, GitHub patterns, web sources. Read-only. | subagent | ❌ Read-only |
+| **@research** | External evidence specialist. Docs, APIs, GitHub patterns, web sources. May write research artifacts when invoked by `/research` or Plan's pre-plan pass. | subagent | ❌ Code / ✅ research artifacts |
 | **@review** | Code reviewer and security auditor. Quality gate before merge. | subagent | ❌ Read-only |
 | **@vision** | Design architect and visual implementer. Frontend UI only. | subagent | ✅ Frontend only |
 
 ## Specialist Boundaries
 
-The three read-only specialists have distinct scopes — choose the right one:
+The specialist subagents have distinct scopes — choose the right one:
 
 | Need | Use | Why |
 |------|-----|-----|
@@ -28,17 +28,19 @@ The three read-only specialists have distinct scopes — choose the right one:
 
 ## File Reading Strategy
 
-All agents that read files must follow the **tilth-first chain** (see `skill/tilth-reading/SKILL.md`):
+All agents that read files must follow the **tilth-first policy** (see `skill/tilth-reading/SKILL.md`):
 
 ```
 1. tilth <path> / tilth <symbol> --scope <dir>   — direct CLI first for read/search/navigation
-2. grep <pattern>                                  — fallback: text pattern search when tilth did not answer
-3. read <path>                                     — fallback: raw full file content
+2. read <path>                                     — fallback: narrowed raw content
+3. grep <pattern>                                  — fallback: text pattern search
 4. glob <pattern>                                  — fallback: explicit path discovery only
 ```
 
 > Prefer direct `tilth` CLI first. Use `npx tilth` only when the CLI is not installed globally.
-> The runtime hook (`tilth_reading`) automatically enhances `read` tool output via tilth, but it does **not** replace `grep`/`glob`, so agents must call `tilth` explicitly for search and navigation.
+> The runtime hook (`tilth_reading`) automatically enhances `read` tool output via tilth when available, so `read` remains the primary raw-content fallback.
+> This is a documented operating rule, not a hard runtime guard.
+> `@explore` should follow the same practical order: `tilth CLI` first, then `read` / `grep` / `glob` depending on the exact fallback need; use LSP after navigation when semantic confirmation is required.
 
 ## Active Roles in Compressed Workflow
 
@@ -62,12 +64,13 @@ Agents use **Beads** (`beads-village_*` MCP tools) for persistent task tracking.
 
 **Core cycle:**
 ```
-beads-village_init → beads-village_add → beads-village_claim → work → beads-village_done
+beads-village_init → beads-village_status/include_agents → beads-village_inbox → beads-village_ls(status="ready") → beads-village_show(id) → beads-village_add (if needed) → beads-village_claim → beads-village_reservations → beads-village_reserve → work → verify → beads-village_done → beads-village_sync
 ```
 
 Execution happens one **Task Packet** at a time.
 
 - **@build**: Creates issues for non-trivial tasks, claims and closes on completion
+- **@build**: Reads issue context before claiming, reserves packet files, verifies evidence, and syncs on completion
 - **@plan**: Creates issues for every plan task after plan approval
 - **Subagents**: Read-only — do not create/modify Beads issues
 
@@ -93,7 +96,7 @@ User → @build (orchestrator)
          └── @review    (quality gate before merge)
 
 User → @plan (planning)
-         ├── @explore   (codebase context, integration points)
-         ├── @research  (external info, version compatibility)
+         ├── @explore   (local context, relevant files, existing patterns)
+         ├── @research  (external info, version compatibility, pre-plan evidence)
          └── @oracle    (architecture trade-offs, risky design decisions)
 ```

package/src/agents/build.md

@@ -50,12 +50,12 @@ You are the Build Agent — the primary executor and orchestrator. You own the f
 
 ### 0.1 Where Build fits in the workflow
 
-When Build is invoked, `@plan` has already produced artifacts on disk:
+When Build is invoked, `@plan` has already produced artifacts on disk, and `/discuss` or `/research` may already have written supporting context:
 
 | Artifact | Path | What it contains |
 |----------|------|-----------------|
+| **Discussion** | `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md` | Locked intent, confirmed assumptions, deferred items |
 | **Plan** | `.opencode/memory/plans/YYYY-MM-DD-<feature>.md` | DAG, File Impact, Boundaries, all Task Packets |
-| **Spec** | `.opencode/memory/specs/YYYY-MM-DD-<feature>.md` | Requirements, user stories, acceptance criteria |
 | **Research** | `.opencode/memory/research/YYYY-MM-DD-<topic>.md` | External evidence, library findings |
 | **Digest** | `.opencode/memory/_digest.md` | Auto-generated summary of all prior session observations |
 
@@ -210,12 +210,12 @@ tilth <path> --section 45-89          # section by line range
 
 ```
 # Fallback order
+read <path>                           # raw content once narrowed
 grep <pattern>                        # text pattern fallback across files
-read <path>                           # full raw content once narrowed
 glob <pattern>                        # path enumeration only when required
 ```
 
-> Follow this order by default: `tilth` → `grep` → `LSP` → `read`.
+> Follow this order by default: `tilth CLI` → `read` → `grep` → `glob`, then use LSP when semantic confirmation is required.
 > Use `glob` only when you need explicit path discovery.
 > `read` tool output is still enhanced by the tilth runtime hook when tilth is available.
 

package/src/agents/explore.md

@@ -67,14 +67,15 @@ Bash access is enabled for **read-only navigation only** and is restricted by fr
 Never use mutating shell commands. In particular: `rm`, `git push`, `git commit`, `git reset`, and `sudo` are forbidden.
 
 Use **tilth CLI as the default navigation/search tool**.
-You must make a relevant tilth attempt before using `read`, `grep`, or `glob` unless bash tilth execution is unavailable.
+You should make a relevant tilth attempt before using `read`, `grep`, or `glob` unless bash tilth execution is unavailable.
+This is a documented operating rule, not a hard runtime block.
 For codebase exploration, follow this fallback order exactly:
 
 ```text
-tilth → grep → LSP → read
+tilth CLI → read → grep → glob
 ```
 
-Use `glob` only when you specifically need raw path enumeration and the main navigation chain is not enough.
+Use `read` for narrowed raw content, `grep` for text-pattern fallback, and `glob` only when you specifically need raw path enumeration.
 
 Start with explicit `bash: tilth` CLI whenever you are locating symbols, sections, files, callers, or likely integration points:
 
@@ -89,21 +90,21 @@ bash: tilth "<text-or-regex>" --scope <dir>
 bash: tilth <symbol> --kind callers --scope <dir>
 ```
 
-If `tilth` does not answer the question or is unavailable, fall back to `grep`, then LSP tools, then `read`.
-Only use `glob` after a tilth attempt when you explicitly need raw path enumeration.
+If `tilth` does not answer the question or is unavailable, fall back to `read`, `grep`, or `glob` based on what kind of answer you need.
+Use LSP tools when semantic confirmation is required after navigation narrows the target.
 
 ### Search priority table
 
 | Priority | What to find | Tools |
 |----------|-------------|-------|
 | 1 | Symbol navigation, sections, likely integration points, callers, file discovery, content search | `bash: tilth <path>` / `bash: tilth --section ...` / `bash: tilth <symbol> --scope ...` |
-| 2 | Text pattern fallback across files | `grep` |
-| 3 | Semantic confirmation: definitions, refs, types | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_find_references`, `lsp_hover` |
-| 4 | Raw file content once narrowed | `read <path>` |
-| 5 | File discovery when path enumeration is required | `glob` |
+| 2 | Raw file content once narrowed | `read <path>` |
+| 3 | Text pattern fallback across files | `grep` |
+| 4 | File discovery when path enumeration is required | `glob` |
+| 5 | Semantic confirmation: definitions, refs, types | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_find_references`, `lsp_hover` |
 | 6 | Recent changes, authorship | `bash: git log`, `git blame`, `git show`, `git diff` |
 
-Use LSP after tilth/grep when you need semantic confirmation or full reference accuracy.
+Use LSP after tilth/read/grep/glob when you need semantic confirmation or full reference accuracy.
 
 ---
 
@@ -146,8 +147,8 @@ Omit empty sections. Keep each entry to one line. If more than 20 locations are
 
 **Always:**
 - Use bash only within the read-only restrictions defined in frontmatter
-- Start navigation with `tilth` CLI; use `grep` second, LSP third, and `read` last
-- Use direct `tilth` CLI patterns for symbol lookup, content search, callers, and path discovery before reaching for `grep` or `glob`
+- Start navigation with `tilth` CLI; then choose `read`, `grep`, or `glob` based on the exact fallback need
+- Use direct `tilth` CLI patterns for symbol lookup, content search, callers, and path discovery before reaching for fallback tools
 - Use `glob` only for explicit path enumeration, not as the default navigator
 - Search broad first to find the right file, then narrow to exact lines
 - Return file paths relative to repo root with line numbers
@@ -157,6 +158,6 @@ Omit empty sections. Keep each entry to one line. If more than 20 locations are
 - Write or edit any file
 - Run commands that mutate state (build, install, test, push)
 - Run `rm`, `git push`, `git commit`, `git reset`, or `sudo`
-- Skip the tilth-first fallback order unless bash tilth execution is unavailable or a later tool is clearly required by the task
+- Skip the documented tilth-first fallback order unless bash tilth execution is unavailable or a later tool is clearly required by the task
 - Start with `read`, `grep`, or `glob` when a relevant `tilth` query can answer the request
 - Explore beyond the stated scope without explicit reason