clikit-plugin 0.3.10 → 0.3.11

package/dist/index.js

@@ -16594,10 +16594,6 @@ var DEFAULT_CONFIG = {
     subagent_question_blocker: {
       enabled: true
     },
-    tilth_first_guard: {
-      enabled: true,
-      log: false
-    },
     truncator: {
       enabled: true,
       max_output_chars: 30000,
@@ -17166,46 +17162,6 @@ function isSubagentTool(toolName) {
 function formatBlockerWarning() {
   return `[CliKit:subagent-blocker] Subagent attempted to ask clarifying questions. Subagents should execute autonomously.`;
 }
-// src/hooks/tilth-first-guard.ts
-var EXPLORE_AGENT = "explore";
-var FALLBACK_TOOLS = new Set(["read", "grep", "glob"]);
-var EXPLICIT_TILTH_COMMAND = /^(?:npx\s+)?tilth(?:\s|$)/i;
-function normalize(value) {
-  return typeof value === "string" ? value.trim().toLowerCase() : "";
-}
-function isExploreAgent(agent) {
-  return normalize(agent) === EXPLORE_AGENT;
-}
-function isFallbackNavigationTool(toolName) {
-  return FALLBACK_TOOLS.has(normalize(toolName));
-}
-function isExplicitTilthCommand(command) {
-  return typeof command === "string" && EXPLICIT_TILTH_COMMAND.test(command.trim());
-}
-function markTilthAttempt(state) {
-  return {
-    ...state || {},
-    sawTilthAttempt: true
-  };
-}
-function shouldBlockTilthFallback(agent, toolName, state) {
-  if (!isExploreAgent(agent)) {
-    return false;
-  }
-  if (!isFallbackNavigationTool(toolName)) {
-    return false;
-  }
-  return state?.sawTilthAttempt !== true;
-}
-function formatTilthFirstGuardWarning(toolName) {
-  return `[CliKit:tilth-first-guard] Blocked @explore from using ${toolName} before an explicit tilth CLI attempt.`;
-}
-function formatTilthFirstGuardReason(toolName) {
-  return `@explore must call 'tilth <path>' before using ${toolName}. read/grep/glob are fallback tools only.`;
-}
-function formatTilthFirstGuardPass(command) {
-  return `[CliKit:tilth-first-guard] Recorded tilth attempt for @explore: ${command}`;
-}
 // src/hooks/truncator.ts
 var DEFAULT_MAX_CHARS = 30000;
 var DEFAULT_MAX_LINES = 500;
@@ -18433,7 +18389,6 @@ function ensureDcpInConfig() {
 var CliKitPlugin = async (ctx) => {
   const todosBySession = new Map;
   const sessionAgents = new Map;
-  const tilthFirstBySession = new Map;
   const defaultMcpEntries = {
     "beads-village": {
       type: "local",
@@ -18953,7 +18908,6 @@ ${(content || "").trim()}`.trim();
         if (sessionID) {
           todosBySession.delete(sessionID);
           sessionAgents.delete(sessionID);
-          tilthFirstBySession.delete(sessionID);
         }
       }
     },
@@ -19058,32 +19012,6 @@ ${(content || "").trim()}`.trim();
           }
         }
       }
-      if (pluginConfig.hooks?.tilth_first_guard?.enabled !== false && isExploreAgent(activeAgent)) {
-        const tilthGuardConfig = pluginConfig.hooks?.tilth_first_guard;
-        const command = toolInput.command ?? toolInput.cmd;
-        try {
-          if (isToolNamed(toolName, "bash") && command && isExplicitTilthCommand(command)) {
-            const nextState = markTilthAttempt(tilthFirstBySession.get(sessionID));
-            tilthFirstBySession.set(sessionID, nextState);
-            if (tilthGuardConfig?.log === true) {
-              await cliLog("info", formatTilthFirstGuardPass(command.trim()));
-            }
-          }
-          if (isFallbackNavigationTool(toolName)) {
-            const state = tilthFirstBySession.get(sessionID);
-            if (shouldBlockTilthFallback(activeAgent, toolName, state)) {
-              await cliLog("warn", formatTilthFirstGuardWarning(toolName));
-              await showToast("@explore must call tilth before fallback tools", "warning", "CliKit Guard");
-              blockToolExecution(formatTilthFirstGuardReason(toolName));
-            }
-          }
-        } catch (error45) {
-          if (isBlockedToolExecutionError(error45)) {
-            throw error45;
-          }
-          await hookErr("tilth-first-guard", error45, { tool: toolName, sessionID, agent: activeAgent, command });
-        }
-      }
     },
     "tool.execute.after": async (input, output) => {
       const toolName = input.tool;

package/memory/_templates/discussion.md

@@ -0,0 +1,91 @@
+# Discussion Template
+
+Use this template when documenting clarified intent before `/create`.
+
+**Output path:** `.opencode/memory/discussions/YYYY-MM-DD-<topic>.md`
+
+This template is optimized for **pre-create discussion**: the report should reduce guessing for `/create`, `/research`, and `/start` by separating locked intent from unresolved technical work.
+
+---
+
+```markdown
+---
+topic: [Topic Name]
+date: YYYY-MM-DD
+status: draft | approved
+mode: interactive | assumptions
+bead_id: [optional]
+---
+
+# Discussion: [Topic]
+
+**Goal:** [What outcome the user wants]
+**Why now:** [Why this needs to be clarified before planning]
+**Assumptions:** [Any assumptions made due to incomplete context, or "None"]
+
+---
+
+## Scope Boundary
+
+- **In scope:** [What this discussion covers]
+- **Out of scope:** [What is explicitly excluded]
+
+---
+
+## Locked Decisions
+
+### Decision 1: [Title]
+- **Decision:** [Confirmed choice]
+- **Why it matters:** [Why `/create` or `/research` must preserve it]
+- **Source:** user-confirmed | prior artifact-confirmed
+
+### Decision 2: [Title]
+- **Decision:** [Confirmed choice]
+- **Why it matters:** [Practical consequence]
+- **Source:** user-confirmed | prior artifact-confirmed
+
+---
+
+## Confirmed Assumptions
+
+- **Assumption:** [What was assumed]
+  - **Confirmed by:** [user / artifact / codebase pattern]
+  - **Notes:** [Any caveat]
+
+---
+
+## Open Questions
+
+- **Question:** [Unresolved item]
+  - **Why unresolved:** [Reason]
+  - **Next owner:** `/create` | `/research` | user
+
+---
+
+## Codebase Context
+
+- **Relevant files/modules:** [Paths or components]
+- **Existing patterns:** [Patterns worth preserving]
+- **Reuse opportunities:** [What downstream work should reuse]
+- **Constraints:** [Technical realities discovered locally]
+
+---
+
+## Canonical References
+
+- [Internal doc, file, or prior artifact]
+- [Another source downstream agents should read]
+
+---
+
+## Deferred / Later
+
+- [Idea intentionally postponed]
+- [Follow-up that should not expand current scope]
+
+---
+
+## Planning Notes
+
+- [Specific instruction `/create` should preserve in the plan]
+```

package/memory/_templates/handoff.md

@@ -9,7 +9,7 @@ Use this template when saving state for session breaks.
 ```markdown
 ---
 date: YYYY-MM-DD
-phase: spec'd | researched | planned | implementing | validating
+phase: discussed | researched | planned | implementing | validating
 branch: [git branch name]
 bead_id: [optional]
 ---
@@ -28,7 +28,7 @@ bead_id: [optional]
 
 | Type | Path | Status |
 |------|------|--------|
-| Spec | `.opencode/memory/specs/YYYY-MM-DD-descriptor.md` | ✅ Complete |
+| Discussion | `.opencode/memory/discussions/YYYY-MM-DD-topic.md` | 🧭 Reference |
 | Plan | `.opencode/memory/plans/YYYY-MM-DD-feature.md` | ✅ Complete |
 | Research | `.opencode/memory/research/YYYY-MM-DD-topic.md` | 📚 Reference |
 | PRD | `.opencode/memory/prds/YYYY-MM-DD-feature.md` | ⏸️ In Review |

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.10",
-  "description": "OpenCode plugin — 7 agents, 15 commands, 25 skills, 12 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",

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