clikit-plugin 0.2.28 → 0.2.30

package/command/init.md

@@ -1,5 +1,5 @@
 ---
-description: Initialize CliKit plugin in the current project.
+description: Initialize CliKit plugin and generate a well-crafted AGENTS.md for the project.
 agent: build
 ---
 
@@ -7,20 +7,15 @@ You are the **Build Agent**. Execute the `/init` command.
 
 ## Your Task
 
-Set up the CliKit plugin in the current project.
+Set up CliKit AND generate a high-quality `AGENTS.md` file. The AGENTS.md is the highest-leverage file in the project — it goes into every single session. Craft it carefully.
 
 ## Process
 
 ### 1. Check Prerequisites
 
 ```bash
-# Check if .opencode/ already exists
 ls -la .opencode/ 2>/dev/null
-
-# Check if package.json exists
 ls package.json 2>/dev/null
-
-# Check package manager
 ls bun.lockb pnpm-lock.yaml yarn.lock 2>/dev/null
 ```
 
@@ -29,7 +24,6 @@ If `.opencode/` already exists with CliKit files, warn user and ask before overw
 ### 2. Install Plugin
 
 ```bash
-# Detect package manager and install
 bun add -d clikit-plugin 2>/dev/null || \
 pnpm add -D clikit-plugin 2>/dev/null || \
 npm install -D clikit-plugin 2>/dev/null
@@ -46,67 +40,150 @@ export default CliKitPlugin;
 
 ### 4. Create Default Configuration
 
-Create `.opencode/clikit.config.json`:
-
-```json
-{
-  "$schema": "https://unpkg.com/clikit-plugin/schema.json",
-  "disabled_agents": [],
-  "disabled_commands": [],
-  "hooks": {
-    "session_logging": true,
-    "todo_enforcer": {
-      "enabled": true,
-      "warn_on_incomplete": true
-    },
-    "empty_message_sanitizer": {
-      "enabled": true
-    }
-  }
-}
-```
+Create `.opencode/clikit.config.json` with sensible defaults (see existing template).
 
 ### 5. Create Memory Directory Structure
 
 ```bash
-mkdir -p .opencode/memory/{specs,plans,research,reviews,handoffs,prds,beads}
+mkdir -p .opencode/memory/{specs,plans,research,reviews,handoffs,prds,beads,_templates}
 ```
 
-### 6. Verify Setup
+### 6. Generate AGENTS.md
+
+**This is the most important step.** The AGENTS.md file goes into EVERY session. Follow these principles:
+
+#### 6a. Explore the Project First (parallel)
+
+Fire these immediately to understand the project:
+
+```
+Explore: "Identify: 1) Language/runtime (check package.json, Cargo.toml, go.mod, pyproject.toml, etc.) 2) Framework (Next.js, Express, FastAPI, etc.) 3) Package manager (bun, pnpm, npm, yarn, cargo, pip) 4) Build command 5) Test command 6) Lint command"
+Explore: "Map top-level structure. What are the main directories? Is this a monorepo? What are the apps vs packages vs shared code?"
+Explore: "Find entry points, main config files, and any existing AGENTS.md/CLAUDE.md/CONTRIBUTING.md/README.md with project conventions."
+```
+
+#### 6b. Write AGENTS.md Following Best Practices
+
+Write to `AGENTS.md` in the project root. Follow these rules strictly:
+
+**TARGET: Under 60 lines. Every line must be universally applicable to every session.**
+
+**Structure — WHAT / WHY / HOW:**
+
+```markdown
+# [Project Name]
+
+[1-2 sentences: WHAT this project is and WHY it exists. Be specific — not "a web app" but "a real-time collaboration platform for design teams using WebSocket sync".]
+
+## Stack
+
+[Language, runtime, framework, key libraries. One line each, no fluff.]
+
+## Project Structure
+
+[Map the top-level directories. For monorepos, explain what each app/package does. Use a compact tree — max 10-15 lines. Focus on WHERE things are, not what every file does.]
+
+## Development
+
+[Only the commands an agent needs for ANY task. Build, test, typecheck, lint, dev server. Nothing task-specific.]
+
+```bash
+[package-manager] install
+[package-manager] run build
+[package-manager] run test
+[package-manager] run lint
+```
+
+## Where to Find More
+
+[Progressive disclosure — point to files, don't inline their contents. Only include files that actually exist in the project.]
+
+- Architecture decisions: [path or "ask the team"]
+- API patterns: [path]
+- Testing conventions: [path]
+- Contributing guide: [path]
+```
+
+#### 6c. What NOT to Include
+
+Applying the blog's principles strictly:
+
+- ❌ **No code style rules** — that's what linters and formatters do. Hooks handle auto-format and typecheck.
+- ❌ **No task-specific instructions** — "how to create a database migration" doesn't belong. Put that in a separate doc and point to it.
+- ❌ **No model/agent details** — agents know their own config. Don't list all 10 agents and their models.
+- ❌ **No inline code snippets** — they go stale. Use `file:line` pointers instead.
+- ❌ **No exhaustive command lists** — agent can discover commands. Only include the core workflow.
+- ❌ **No "rules" that are just good engineering** — "write clean code" wastes instruction budget. The agent already knows.
+- ❌ **No skill recommendations** — that's task-specific. Skills are discovered at task time.
+
+#### 6d. What TO Include (universally applicable)
+
+- ✅ **What the project IS** — 1-2 sentences, specific.
+- ✅ **Tech stack** — language, runtime, framework, key deps.
+- ✅ **Project map** — where things live (especially monorepos).
+- ✅ **Essential commands** — build, test, lint, dev server.
+- ✅ **Progressive disclosure pointers** — "Read X for Y" references to existing docs.
+- ✅ **Non-obvious conventions** — only things the agent would get WRONG without being told (e.g., "We use Bun, not Node" or "Database migrations use Drizzle push, not migrate").
+- ✅ **Verification commands** — how to confirm changes work.
+
+### 7. If AGENTS.md Already Exists
+
+If the project already has an `AGENTS.md` or `CLAUDE.md`:
+
+1. Read it first
+2. Audit it against the blog principles (concise? universally applicable? progressive disclosure?)
+3. Propose improvements to the user — don't overwrite without asking
+4. If user approves, rewrite following the principles above
+
+### 8. Verify Setup
 
 - Check that plugin loads correctly
 - Verify agents are available
-- Verify commands are registered
+- Verify AGENTS.md exists and is under 60 lines
+- Count instructions in AGENTS.md — warn if over 30 (LLMs reliably follow ~150 instructions, Claude Code's system prompt already uses ~50)
 
-### 7. Report
+### 9. Report
 
 ```
 ## CliKit Initialized
 
-✅ Plugin installed: clikit-plugin
+✅ Plugin installed
 ✅ Entry point: .opencode/index.ts
 ✅ Config: .opencode/clikit.config.json
 ✅ Memory directories created
+✅ AGENTS.md generated ([N] lines, [M] instructions)
 
-### Available Agents
-[list agents]
-
-### Available Commands
-[list commands]
+### AGENTS.md Quality
+- Lines: [N] (target: <60)
+- Instructions: [M] (target: <30, budget shared with system prompt)
+- Progressive disclosure: [Y/N]
+- Task-specific content: [none found / WARNING: found N task-specific items]
 
 ### Next Steps
-1. Run `/create` to start a new feature
-2. Customize `.opencode/clikit.config.json` as needed
-3. See README for full configuration options
+1. Review AGENTS.md — every line matters, it affects every session
+2. Run `/create` to start a new feature
+3. Customize `.opencode/clikit.config.json` as needed
 ```
 
-## Rules
+## AGENTS.md Quality Principles (from humanlayer.dev)
 
-- ✅ ALWAYS check for existing setup before overwriting
-- ✅ ALWAYS detect the correct package manager
-- ✅ ALWAYS create memory directory structure
-- ✅ ALWAYS verify the setup works
-- ❌ NEVER overwrite existing config without asking
-- ❌ NEVER skip verification step
+1. **Less is more** — frontier models follow ~150 instructions reliably. System prompt uses ~50. Your AGENTS.md gets ~100 max. Each unnecessary instruction degrades ALL instructions uniformly.
+2. **Universally applicable only** — if it doesn't matter for EVERY session, it doesn't belong here.
+3. **Progressive disclosure** — point to detailed docs, don't inline them. The agent reads them only when relevant.
+4. **Not a linter** — never put code style in AGENTS.md. Use formatters, hooks, and tooling.
+5. **Pointers over copies** — reference `file:line`, not code snippets. Snippets go stale.
+6. **Carefully crafted** — this is the highest leverage point. Every line either helps or hurts.
+
+## Rules
 
-Now, initializing CliKit...
+- ✅ ALWAYS explore the project before generating AGENTS.md
+- ✅ ALWAYS keep AGENTS.md under 60 lines
+- ✅ ALWAYS use WHAT/WHY/HOW structure
+- ✅ ALWAYS use progressive disclosure (pointers, not copies)
+- ✅ ALWAYS verify the final instruction count
+- ✅ ALWAYS check for existing AGENTS.md before overwriting
+- ❌ NEVER put code style rules in AGENTS.md
+- ❌ NEVER put task-specific instructions in AGENTS.md
+- ❌ NEVER inline code snippets (they go stale)
+- ❌ NEVER generate more than 30 instructions
+- ❌ NEVER overwrite existing AGENTS.md without asking

package/command/plan.md

@@ -1,5 +1,5 @@
 ---
-description: Convert specs and research into execution plan.
+description: Convert spec into execution plan with parallel waves, file impact, and executable acceptance criteria.
 agent: plan
 ---
 
@@ -10,196 +10,138 @@ You are the **Plan Agent**. Execute the `/plan` command.
 Use template at: `@.opencode/memory/_templates/plan.md`
 
 ## Prerequisites
-- `spec.md` MUST exist
+
+- `spec.md` MUST exist in `.opencode/memory/specs/`
 - `research.md` recommended if external knowledge needed
 
-## Your Task
+## Execution Rules
 
-Create a detailed implementation plan from the specification.
+- **DO NOT** generate a plan without exploring the codebase first
+- **DO NOT** write acceptance criteria that require human manual testing
+- Auto-generate the plan after gap analysis — don't ask "should I create the plan now?"
 
 ## Process
 
-1. **Load artifacts**: spec.md, research.md (if exists)
-
-2. **Understand codebase** using:
-   - `finder` for semantic search
-   - Delegate to Explore Agent for file discovery
-
-3. **Consult Oracle** for non-trivial architecture decisions
-
-4. **Decompose into tasks** following Task Schema (see `.opencode/schemas.md` §1)
-
-5. **Generate File Impact section** (REQUIRED)
-
-6. **Create `plan.md`** at `.opencode/memory/plans/YYYY-MM-DD-<feature>.md`
-
-7. **Update bead** with plan reference
-
-8. **Get user approval**
-
-## Plan Structure (follows `_templates/plan.md`)
-
-The plan MUST include:
-
-```markdown
-# Implementation Plan: [Feature]
-
-**Date:** YYYY-MM-DD
-**Author:** [Name]
-**Status:** Draft | Approved
-**bead_id:** [ID]
-
----
+### 1. Load Artifacts
 
-## Overview
+Load spec.md and research.md (if exists) from `.opencode/memory/`.
 
-[Brief description of what will be built]
+### 2. Memory & History Mining (parallel with step 3)
 
-## 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)
-
----
-
-## 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]
-
----
+Fire these immediately alongside codebase exploration:
 
-### 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)
+**Memory mining** (Plan reads directly — has file read access):
+```
+Read: ".opencode/memory/_digest.md" — Auto-generated from SQLite (decisions, learnings, blockers, handoffs)
+Read: ".opencode/memory/research/" — List files, read any related to the feature
+Read: ".opencode/memory/handoffs/" — Read recent handoffs for prior session context
+Read: ".opencode/memory/reviews/" — Check past review findings on related code
+Read: ".opencode/memory/specs/" — Check for prior/related specs
+```
 
----
+> `_digest.md` is generated by the Memory Digest hook on session start. Contains past decisions, learnings, blockers, and handoffs from the SQLite observations DB.
 
-## Dependencies
+Surface from memory files:
+- Past decisions that constrain this plan
+- Learnings and gotchas from related work
+- Blockers encountered on similar features
+- Patterns that worked or failed
 
-```mermaid
-graph TD
-    T001[T-001: Title] --> T002[T-002: Title]
-    T002 --> T003[T-003: Title]
-    T001 --> T003
+**Git history mining** (delegate to Explore — Plan has bash: false):
+```
+Explore: "Mine git log for conventions. Return:
+  1. Commit message format (git log --oneline -n 20)
+  2. Branch naming (git branch -a | head -20)
+  3. Recent commits on related files (git log --oneline -n 20 -- [paths from spec])
+  4. Gotcha markers (git log --grep='HACK\|TODO\|FIXME\|workaround' --oneline -n 10)"
 ```
 
----
-
-## Effort Summary
-
-| Task | Effort | Priority |
-|------|--------|----------|
-| T-001 | S | P0 |
-| T-002 | M | P0 |
-| T-003 | S | P1 |
+### 3. Deep Codebase Exploration (parallel with step 2)
 
-**Total Estimated Effort:** [X days/weeks]
+Fire Explore agents immediately:
+```
+Explore: "Find all files that will be affected by this feature. Map integration points."
+Explore: "Find existing patterns for similar features — structure, naming, testing."
+Explore: "Find test infrastructure and conventions — framework, helpers, fixtures."
+```
 
----
+For complex features, also fire:
+```
+Scout: "Find docs and production patterns for [relevant libraries/APIs]."
+Oracle: "Analyze architecture trade-offs for [key decisions]."
+```
 
-## Risk Assessment
+### 4. Gap Analysis (before writing anything)
 
-| Risk | Probability | Impact | Mitigation |
-|------|-------------|--------|------------|
-| [Risk 1] | L/M/H | L/M/H | [Mitigation] |
+Review spec + exploration results + memory findings + git conventions. Classify gaps:
+- **CRITICAL**: Needs user decision → ask immediately
+- **MINOR**: Self-resolvable → fix and note as "Auto-Resolved"
+- **AMBIGUOUS**: Has reasonable default → apply and disclose
 
----
+Cross-reference memory findings against the plan:
+- Past decisions that conflict → flag as risk
+- Past learnings that suggest an approach → incorporate into tasks
+- Past blockers → add preventive acceptance criteria
+- Git conventions → document in Conventions section
 
-## Quick Mode Eligibility
+### 5. Generate Plan
 
-Tasks eligible for Quick Mode (no full plan needed):
-- [ ] T-001 (S, ≤3 files, no security/db/api)
+Write to `.opencode/memory/plans/YYYY-MM-DD-<feature>.md`.
 
----
+**Task decomposition rules:**
+- Each task = 1 module/concern = 1-3 files max
+- Group into parallel waves (3-5 tasks per wave)
+- Every acceptance criterion = executable command + expected output
 
-## Rollout Plan
+**File Impact = BUILD BOUNDARY:**
+Build Agent may ONLY touch files listed here. Missing a file = Build can't modify it.
 
-| Phase | Tasks | Milestone |
-|-------|-------|-----------|
-| Phase 1 | T-001, T-002 | [Milestone] |
-| Phase 2 | T-003 | [Milestone] |
+**Parallel wave structure:**
+```
+Wave 1 (parallel): Foundation tasks with no dependencies
+Wave 2 (parallel): Tasks depending on Wave 1
+Wave 3 (sequential): Integration and verification
+```
 
----
+### 6. Quality Self-Review
 
-## Approval
+Before presenting, verify:
+- [ ] Every task has task_id, acceptance criteria, effort, priority
+- [ ] File Impact covers ALL files across ALL tasks
+- [ ] No dependency cycles
+- [ ] Parallel waves maximized
+- [ ] No task touches > 3 files
+- [ ] All acceptance criteria are agent-executable
+- [ ] Top 2+ risks assessed
+- [ ] Conventions & Past Decisions section is populated (even if "none found")
+- [ ] Memory/git findings are cross-referenced against plan
 
-- [ ] Plan reviewed
-- [ ] User approved
-- [ ] Ready for implementation
-```
+Fix any failures before presenting.
 
-## Task Schema Requirements
+### 7. Present and Guide
 
-Every task MUST include these fields (per `.opencode/schemas.md` §1):
-- `task_id` (T-XXX format)
-- `title`
-- `type` (task | bug | feature | chore)
-- `status` (not_started | in_progress | blocked | done)
-- `assignee` (build | fe | be | mobile | devops)
-- `priority` (P0 | P1 | P2)
-- `effort` (S | M | L | XL)
-- `dependencies` (list or none)
-- `description`, `input`, `output`, `boundaries`
-- `acceptance_criteria` (list)
+Present the plan. After user approval:
+1. Delete draft file if exists
+2. Update bead with plan reference
+3. Guide: "Plan approved. Use `/start` to begin implementation."
 
-## Quick Mode Eligibility
+## Task Schema
 
-Task qualifies for Quick Mode (Build Agent) if:
-- `effort: "S"`
-- 3 files or fewer affected
-- No security/auth/db in boundaries
-- No new API endpoints
+Every task MUST follow Task Schema in `.opencode/schemas.md` §1.
 
 ## Rules
 
-- ✅ ALWAYS use the full template structure from `_templates/plan.md`
-- ✅ ALWAYS include frontmatter (Date, Author, Status, bead_id)
-- ✅ ALWAYS use `task_id` field (not `ID`)
-- ✅ ALWAYS include all Task Schema fields
-- ✅ File Impact is the BUILD BOUNDARY — only listed files allowed
-- ✅ Stable IDs: Deprecate tasks, don't delete
-- ✅ Confirm with user before proceeding to build
-- ❌ NEVER omit required Task Schema fields
-
-Now, load the spec and create the implementation plan.
+- ✅ Explore codebase deeply before planning
+- ✅ Mine memory for past decisions, learnings, blockers
+- ✅ Delegate git history mining to Explore (Plan has bash: false)
+- ✅ Include Conventions & Past Decisions section
+- ✅ Agent-executable acceptance criteria ONLY
+- ✅ File Impact is the build contract
+- ✅ Maximize parallel waves
+- ✅ Self-review quality before presenting
+- ❌ NEVER create tasks touching > 3 files
+- ❌ NEVER write "user manually tests..." criteria
+- ❌ NEVER omit File Impact section
+- ❌ NEVER skip gap analysis
+- ❌ NEVER skip memory/git mining phase
+- ❌ NEVER ignore past decisions that conflict with current plan

package/command/research.md

@@ -100,4 +100,4 @@ bead_id: [optional]
 - `mcp__gh_grep__searchGitHub` — Real-world code patterns
 - `librarian` — Deep repository analysis
 
-Now, what topic do you need to research?
+Identify the research questions from the user's request or the active spec, then begin research immediately.

package/command/resume.md

@@ -1,80 +1,59 @@
 ---
-description: Continue from handoff. Restore state and resume work.
-agent: plan
+description: Resume from handoff. Auto-loads state and starts working immediately.
+agent: build
 ---
 
-You are the **Plan Agent** (or **Build Agent**). Execute the `/resume` command.
+You are the **Build Agent**. Execute the `/resume` command **immediately without asking for confirmation**.
 
-## Your Task
+## Execution Rules
 
-Resume work from a previous session using the handoff document.
+- **DO NOT** ask "Ready to continue?" or any confirmation
+- **DO NOT** present a summary and wait — load state and propose the next action in one shot
+- If drift is detected, note it briefly and continue — don't block on it
 
-## Process
+## Process (execute all steps, then present result)
 
-1. **Load latest handoff** from `.opencode/memory/handoffs/`
+### 1. Load Latest Handoff
 
-2. **Load related artifacts**:
-   - spec.md
-   - plan.md
-   - research.md (if exists)
+- Find the most recent `.md` file in `.opencode/memory/handoffs/`
+- Parse its frontmatter and content
+- If no handoff found, say so and suggest `/create` or `/start`
 
-3. **Detect drift** — Check if code changed outside the session:
-   - Run `git status` and `git diff`
-   - Compare with handoff's file list
+### 2. Load Related Artifacts
 
-4. **Summarize current state**: "We are here; these are next steps"
+In parallel:
+- Load spec from `.opencode/memory/specs/` (if referenced or latest)
+- Load plan from `.opencode/memory/plans/` (if referenced or latest)
+- Run `git status --short` and `git log --oneline -3`
 
-5. **Propose next action**
+### 3. Detect Drift
 
-## Resume Workflow
+Compare current git state with handoff's recorded state:
+- New commits since handoff? Note them briefly.
+- File conflicts? Flag which tasks may be affected.
+- No drift? Skip this section entirely.
 
-```
-1. Find latest handoff.md
-2. Load spec.md, plan.md
-3. Check git status for drift
-4. If drift detected:
-   - Summarize changes
-   - Mark affected tasks for re-evaluation
-   - Ask user to reconcile
-5. If no drift:
-   - Present status summary
-   - Propose next task
-```
+### 4. Present and Act
 
-## Output Format
+Output this format, then **immediately begin the first next step**:
 
-```markdown
-## Session Resumed
-
-**Previous Session:** YYYY-MM-DD
-**Phase:** [current phase]
-**Branch:** [branch name]
+```
+## Resumed from <handoff date>
 
-### Where We Left Off
-[Summary from handoff]
+**Branch:** `<branch>` | **Phase:** <phase>
 
-### Drift Detection
-- [ ] No changes detected outside session
-- [ ] Changes detected: [list files]
+**Where we left off:** <1-2 sentences from handoff>
 
-### Current Status
-- **Completed:** X tasks
-- **In Progress:** Y tasks
-- **Remaining:** Z tasks
+**Drift:** <none | brief note of changes>
 
-### Proposed Next Action
-[Specific next step to take]
+**Next:** <first action from handoff's "What To Do Next">
 
 ---
-Ready to continue? [Y/n]
+Starting now.
 ```
 
-## Drift Handling
+Then begin executing the first next step from the handoff.
 
-If drift is detected:
-1. List changed files
-2. Identify which tasks are affected
-3. Mark those tasks for re-evaluation
-4. Ask user: "Code changed outside session. Should I re-evaluate affected tasks?"
+## Philosophy
 
-Now, let me find and load the latest handoff to resume your work.
+Resume is not a status report — it's a running start. Load context, orient briefly, then **get to work**.