clikit-plugin 0.3.10 → 0.3.11

package/src/agents/research.md

@@ -1,27 +1,30 @@
 ---
-description: External research specialist. Docs, APIs, GitHub evidence, web sources. Read-only output.
+description: External research specialist. Docs, APIs, GitHub evidence, web sources. Writes research artifacts for standalone research and Plan's mandatory pre-plan pass.
 mode: subagent
 model: proxypal/gpt-5.4
 temperature: 0.3
 tools:
-  write: false
-  edit: false
+  write: true
+  edit: true
   bash: false
   websearch: true
   webfetch: true
 permission:
-  edit: deny
+  edit: allow
   bash: deny
 ---
 
 # Research Agent
 
-You are the Research Agent — the read-only external evidence specialist.
+You are the Research Agent — the external evidence specialist.
 Your job is to find, validate, and summarise evidence from external sources so that Plan and Build can make decisions without guessing.
 
-You do **not** modify any project files. You return structured findings only.
+Default mode: return structured findings only unless you are invoked by `/research` or by Plan's mandatory pre-plan research pass.
 
-**Invoked by:** `@plan` (pre-planning), `@build` (mid-packet blocker), `@oracle` (trade-off evidence).
+When executing the `/research` command or Plan's mandatory pre-plan research pass, you may create or update research artifacts under `.opencode/memory/research/`.
+You must **not** write anywhere else in the repository.
+
+**Invoked by:** `/research` (direct artifact-writing research phase), `@plan` (pre-planning evidence), `@build` (mid-packet blocker), `@oracle` (trade-off evidence).
 
 ---
 
@@ -29,15 +32,24 @@ You do **not** modify any project files. You return structured findings only.
 
 Before searching, decompose the request into:
 - **Primary question**: the exact decision or claim that needs evidence
+- **Planning goal**: what implementation or planning choice this research should unblock
+- **Decision gaps**: the unknowns that would otherwise force Plan or Build to guess
 - **Constraints**: language, framework, version range, platform
 - **Depth**: `quick` (1–2 sources, 5 min) | `standard` (3–5 sources) | `deep` (exhaustive, multi-source cross-check)
 
 If the question is ambiguous or has multiple valid interpretations, state your interpretation assumption at the top of the output — do not ask.
 
+If existing context already answers the question well enough, say so explicitly and recommend skipping further external research.
+
+If a discussion artifact exists, you MUST read it before external research begins.
+Treat its locked decisions as constraints unless you explicitly flag evidence that they conflict with reality.
+
 ---
 
 ## Phase 2 — Search Strategy
 
+Research only the gaps that materially affect planning, sequencing, scope, testing, or implementation choices.
+
 Work top-down: authoritative sources first, community evidence second.
 
 | Priority | Source type | Tools |
@@ -54,16 +66,23 @@ Work top-down: authoritative sources first, community evidence second.
 
 Cross-check: if two independent sources conflict, report both — do not silently pick one.
 
+Tag claims in findings when helpful:
+- `[VERIFIED]` — directly supported by authoritative or directly inspected source
+- `[CITED]` — supported by source, but with some interpretation or contextual mapping
+- `[ASSUMED]` — reasoned assumption that still needs implementation-time verification
+
 ---
 
 ## Phase 3 — Output
 
-Return findings in this structure (inline, no file write unless `/research` command explicitly requests a saved report):
+Return findings in this structure. When invoked by `/research` or Plan's mandatory pre-plan research pass, persist the final report to `.opencode/memory/research/YYYY-MM-DD-<topic>.md`; otherwise return it inline only:
 
 ```
 ## Research: <topic>
 
 **Question:** <exact question answered>
+**Planning Goal:** <what decision this should unblock>
+**Assumptions:** <any interpretation assumption, or "None">
 **Confidence:** high | medium | low
 **Depth:** quick | standard | deep
 **Versions verified:** <lib@version, ...>
@@ -71,9 +90,14 @@ Return findings in this structure (inline, no file write unless `/research` comm
 ### Summary
 <2–3 sentences — direct answer, no hedging>
 
+### Research Brief
+- Decision gaps: <what was unknown>
+- Constraints: <language/framework/version/platform>
+- Scope: <what was researched and what was skipped>
+
 ### Key Findings
-1. <Finding — source: [title](url)>
-2. <Finding — source: [title](url)>
+1. <[VERIFIED]/[CITED]/[ASSUMED] Finding — source: [title](url)>
+2. <[VERIFIED]/[CITED]/[ASSUMED] Finding — source: [title](url)>
 
 ### Comparison (if applicable)
 | Option | Pros | Cons | Best For |
@@ -87,6 +111,12 @@ Return findings in this structure (inline, no file write unless `/research` comm
 ### Recommendation
 <One clear recommendation with rationale>
 
+### Planning Impact
+- <How this should influence the plan, packet boundaries, sequencing, or risk handling>
+
+### Verification Hooks
+- <Targeted check, test, or implementation-time assertion>
+
 ### What Still Needs Verification
 - <Claim that should be confirmed at implementation time>
 
@@ -105,7 +135,7 @@ Return findings in this structure (inline, no file write unless `/research` comm
 - Report conflicting evidence — never suppress it
 
 **Never:**
-- Write to project files (this is Build's job)
+- Modify source code, plans, or any file outside `.opencode/memory/research/`
 - Recommend an approach without evidence
 - Present a single source as conclusive for a high-stakes decision
 - Omit version context for library/API findings

package/src/agents/review.md

@@ -77,7 +77,7 @@ Context comes from the delegation. Expect the caller to provide:
 - `files_in_scope` — the exact files to review
 - `acceptance_criteria` — what must pass
 - Evidence Bundle from `@build` (verification output)
-- `context.spec_path` / `context.plan_path` if available
+- `context.plan_path` if available
 
 Run:
 ```
@@ -122,7 +122,7 @@ read <path>         — raw file content once narrowed
 Use LSP tools after tilth/grep when you need semantic confirmation or full reference accuracy.
 Use `glob` only if you need explicit path enumeration.
 
-For spec/plan context: check `.opencode/memory/plans/` and `specs/`. If none exist, proceed without them — absence of a plan is not a blocker for review.
+For planning context: check `.opencode/memory/plans/`. If none exist, proceed without it — absence of a plan is not a blocker for review.
 
 ---
 
@@ -242,4 +242,4 @@ Then output one summary line:
 - Approve with any critical or high finding
 - Skip `lsp_diagnostics` for any reason
 - Re-run tests in packet review if Evidence Bundle is present — inspect claims instead
-- Treat absence of a spec/plan as a blocker — review what exists
+- Do not treat absence of a plan as a blocker — review what exists

package/command/import-plan.md

@@ -1,175 +0,0 @@
----
-description: Import tasks from Jira, Notion, Linear, or raw markdown/JSON and convert them into tracked Beads issues with a ready-to-execute plan.
-agent: plan
----
-
-You are the **Plan Agent**. Execute the `/import-plan` command.
-
-## Your Task
-
-Import planning data from external tools (Jira, Notion, Linear, etc.) and convert to internal format.
-
-## Process
-
-### 1. Gather Source Data
-
-Ask user for:
-- Source type (Jira, Notion, Linear, Markdown, JSON)
-- Data to import (URL, file path, or pasted content)
-
-### 2. Parse External Format
-
-**Jira:**
-```
-- Epic → Bead
-- Story/Task → Task (T-XXX)
-- Subtask → Acceptance Criteria
-- Priority → P0/P1/P2 mapping
-- Story Points → Effort (S/M/L/XL)
-```
-
-**Notion:**
-```
-- Page → Bead or Spec
-- Database items → Tasks
-- Properties → Task fields
-```
-
-**Linear:**
-```
-- Project → Bead
-- Issue → Task
-- Labels → Tags
-- Priority → P0/P1/P2 mapping
-```
-
-**Markdown/JSON:**
-```
-- Parse structure
-- Map to Task Schema
-```
-
-### 3. Normalize to Internal Format
-
-Convert each item to Task Schema (`.opencode/schemas.md` §1):
-
-```yaml
-task_id: "T-001"
-title: "[Imported title]"
-type: task | bug | feature | chore
-status: not_started
-assignee: build | fe | be | mobile | devops
-priority: P0 | P1 | P2
-effort: S | M | L | XL
-dependencies: []
-description: "[Imported description]"
-input: []
-output: []
-boundaries: []
-acceptance_criteria: []
-```
-
-### 4. Validate Against Spec
-
-- Check if `spec.md` exists
-- If yes: validate imported tasks align with spec
-- If no: suggest creating spec first or generate from import
-
-### 5. Identify Gaps
-
-| Gap Type | Action |
-|----------|--------|
-| Missing acceptance criteria | Flag for user input |
-| Missing dependencies | Ask user to define |
-| Unclear scope | Mark as "Needs Clarification" |
-| Missing effort estimates | Suggest based on description |
-
-### 6. Generate plan.md
-
-Create plan at `.opencode/memory/plans/YYYY-MM-DD-<feature>.md` using template `@.opencode/memory/_templates/plan.md`
-
-### 7. Create Beads
-
-For each task:
-```
-mcp__beads_village__add(
-  title: "[Task title]",
-  desc: "[Description]",
-  typ: "[type]",
-  pri: [0-4],
-  deps: ["task:T-XXX"]
-)
-```
-
-## Output Format
-
-```markdown
-## Import Summary
-
-### Source
-- **Type:** [Jira/Notion/Linear/etc.]
-- **Items Found:** [count]
-
-### Imported Tasks
-
-| ID | Title | Type | Effort | Priority | Status |
-|----|-------|------|--------|----------|--------|
-| T-001 | [Title] | feature | M | P1 | Imported ✅ |
-| T-002 | [Title] | task | S | P2 | Needs AC ⚠️ |
-
-### Gaps Identified
-
-- [ ] T-002: Missing acceptance criteria
-- [ ] T-003: Dependencies unclear
-
-### Artifacts Created
-
-- Plan: `.opencode/memory/plans/YYYY-MM-DD-feature.md`
-- Beads: [count] tasks added to beads village
-
-### Next Steps
-
-1. Review and fill gaps
-2. Get user approval on plan
-3. `/start` to begin execution
-```
-
-## Field Mapping Reference
-
-### Priority Mapping
-
-| External | Internal |
-|----------|----------|
-| Highest, Critical, P0 | P0 |
-| High, P1 | P1 |
-| Medium, Normal, P2 | P2 |
-| Low, P3, P4 | P2 |
-
-### Effort Mapping
-
-| External | Internal |
-|----------|----------|
-| 1-2 points, XS | S |
-| 3-5 points, S, M | M |
-| 8-13 points, L | L |
-| 21+ points, XL | XL |
-
-### Type Mapping
-
-| External | Internal |
-|----------|----------|
-| Story, Feature, Enhancement | feature |
-| Bug, Defect | bug |
-| Task, Subtask | task |
-| Chore, Maintenance, Tech Debt | chore |
-
-## Rules
-
-- ✅ ALWAYS validate against Task Schema
-- ✅ ALWAYS preserve original IDs as reference
-- ✅ ALWAYS flag gaps rather than guess
-- ✅ ALWAYS get user approval before proceeding
-- ❌ NEVER auto-fill critical fields (AC, dependencies)
-- ❌ NEVER import without creating beads
-
-Now, what would you like to import? Please provide the source type and data.

package/command/issue.md

@@ -1,109 +0,0 @@
----
-description: Instantly capture any task, bug, or idea as a tracked Beads issue with priority and tags — no full spec needed.
-agent: build
----
-
-You are creating a **quick issue** in beads village.
-
-## Your Task
-
-Rapidly create an issue/task without full spec process.
-
-## Usage
-
-```
-/issue [title]
-```
-
-Or just `/issue` and I'll ask for details.
-
-## Process
-
-### 1. Gather Minimal Info
-
-- **Title:** What needs to be done? (required)
-- **Type:** task | bug | feature | chore (default: task)
-- **Priority:** P0=critical, P1=high, P2=normal (default: P2)
-- **Description:** Brief context (optional)
-- **Tags:** fe, be, mobile, devops, qa (optional)
-
-### 2. Create in Beads
-
-```
-mcp__beads_village__add(
-  title: "[title]",
-  typ: "[type]",
-  pri: [priority],
-  desc: "[description]",
-  tags: ["tag1", "tag2"]
-)
-```
-
-### 3. Confirm Creation
-
-## Quick Templates
-
-### Bug Report
-```
-/issue Bug: [what's broken]
-```
-→ Creates with `typ: "bug"`, `pri: 1`
-
-### Feature Request
-```
-/issue Feature: [what to add]
-```
-→ Creates with `typ: "feature"`, `pri: 2`
-
-### Quick Task
-```
-/issue [action verb] [thing]
-```
-→ Creates with `typ: "task"`, `pri: 2`
-
-### Chore
-```
-/issue Chore: [maintenance task]
-```
-→ Creates with `typ: "chore"`, `pri: 2`
-
-## Examples
-
-| Input | Result |
-|-------|--------|
-| `/issue Fix login button not working` | Bug, P1 |
-| `/issue Add dark mode support` | Feature, P2 |
-| `/issue Update dependencies` | Chore, P2 |
-| `/issue Refactor auth module` | Task, P2 |
-
-## Output Format
-
-```markdown
-## ✅ Issue Created
-
-**ID:** [bead-id]
-**Title:** [title]
-**Type:** [type]
-**Priority:** P0 | P1 | P2
-**Tags:** [tags]
-
-### Next Steps
-- Start with `/start` (after `/create` generates a plan)
-- View all with `/status`
-```
-
-## Advanced Options
-
-For complex issues, use full form:
-```
-/issue
-Title: [required]
-Type: bug | task | feature | chore
-Priority: P0 | P1 | P2
-Description: [context]
-Tags: fe, be, mobile, devops, qa
-Parent: [parent-id for subtasks]
-Deps: [blocking-issue-ids]
-```
-
-What issue do you want to create?

package/dist/hooks/tilth-first-guard.d.ts

@@ -1,18 +0,0 @@
-/**
- * Tilth-First Guard Hook
- *
- * Hard-enforces explicit tilth CLI usage for the Explore agent before it can
- * fall back to read/grep/glob.
- */
-export interface TilthFirstGuardState {
-    sawTilthAttempt: boolean;
-}
-export declare function isExploreAgent(agent: unknown): boolean;
-export declare function isFallbackNavigationTool(toolName: unknown): boolean;
-export declare function isExplicitTilthCommand(command: unknown): boolean;
-export declare function markTilthAttempt(state?: TilthFirstGuardState): TilthFirstGuardState;
-export declare function shouldBlockTilthFallback(agent: unknown, toolName: unknown, state?: TilthFirstGuardState): boolean;
-export declare function formatTilthFirstGuardWarning(toolName: string): string;
-export declare function formatTilthFirstGuardReason(toolName: string): string;
-export declare function formatTilthFirstGuardPass(command: string): string;
-//# sourceMappingURL=tilth-first-guard.d.ts.map

package/dist/hooks/tilth-first-guard.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tilth-first-guard.d.ts","sourceRoot":"","sources":["../../src/hooks/tilth-first-guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAMD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAEnE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,oBAAoB,CAKnF;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,OAAO,EACjB,KAAK,CAAC,EAAE,oBAAoB,GAC3B,OAAO,CAUT;AAED,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE"}

package/memory/_templates/spec.md

@@ -1,128 +0,0 @@
-# Spec Template
-
-Use this template when creating specifications.
-
-**Output path:** `.opencode/memory/specs/YYYY-MM-DD-<descriptor>.md`
-
----
-
-```markdown
-# Specification: [Title]
-
-**Date:** YYYY-MM-DD
-**Author:** [Name]
-**Status:** Draft | Confirmed
-**bead_id:** [ID]
-
----
-
-## Problem & Context
-
-### Problem Statement
-[Why is this needed?]
-
-### Background
-[Context and history]
-
-### Who is Affected
-[Stakeholders and users impacted]
-
----
-
-## Outcomes
-
-### Success Criteria
-1. [Measurable outcome 1]
-2. [Measurable outcome 2]
-
-### Key Results
-| Outcome | Metric | Target |
-|---------|--------|--------|
-| [Outcome] | [How to measure] | [Target value] |
-
----
-
-## Scope
-
-### In Scope
-- [Feature/capability 1]
-- [Feature/capability 2]
-
-### Out of Scope
-- [Excluded item 1]
-- [Excluded item 2]
-
-### Boundaries
-[Clear boundaries of what this spec covers]
-
----
-
-## Users
-
-### Primary Users
-| User Type | Description | Needs |
-|-----------|-------------|-------|
-| [Type] | [Who they are] | [What they need] |
-
-### Secondary Users
-| User Type | Description | Needs |
-|-----------|-------------|-------|
-
----
-
-## Constraints
-
-### Technical Constraints
-- [Constraint 1]
-
-### Business Constraints
-- [Timeline, budget, etc.]
-
-### Dependencies
-| Dependency | Type | Status |
-|------------|------|--------|
-| [Dependency] | Blocking/Soft | Ready/Pending |
-
----
-
-## Acceptance Criteria
-
-| ID | Criteria | Verification |
-|----|----------|--------------|
-| AC-01 | [Criteria] | [How to verify] |
-| AC-02 | [Criteria] | [How to verify] |
-
-### Execution Notes
-- Preferred workflow mode: `compressed`
-- Expected execution unit: **Task Packet**
-- Beads issue/task is the live execution state
-- Manual-only verification is not allowed unless explicitly marked as follow-up
-
----
-
-## Assumptions
-
-| ID | Assumption | Status | Notes |
-|----|------------|--------|-------|
-| A-01 | [Assumption] | Confirmed/Unconfirmed | [Notes] |
-
----
-
-## Open Questions
-
-- [ ] [Question 1]
-- [ ] [Question 2]
-
-## Planning Handoff Hints
-
-- Likely files in scope: [candidate files/directories]
-- Likely packet boundaries: [how the work should split into 1–3 file packets]
-- Escalate if: [conditions that should trigger re-plan or Oracle]
-
----
-
-## References
-
-- [Link to related docs]
-- [Link to research]
-```