opencodekit 0.21.9 → 0.22.0

package/dist/template/.opencode/skill/planning-and-task-breakdown/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: planning-and-task-breakdown
+description: Decomposes a spec into small verifiable tasks with dependencies and acceptance checks. Use when a feature/change has a spec or clear goal and needs an executable implementation plan.
+version: 1.0.0
+tags: [workflow, planning, agent-coordination]
+dependencies: [spec-driven-development]
+agent_types: [planner]
+tools: [TaskCreate, TaskUpdate, memory, srcwalk_search]
+---
+
+# Planning & Task Breakdown
+
+## Overview
+
+A good plan creates leverage for builders. It says what must become true, where to work, what not to touch, and how to prove success.
+
+Core principle: plan backward from observable truths into artifacts, wiring, tasks, dependencies, and verification.
+
+## When to Use
+
+- A spec or clear goal exists and implementation is non-trivial.
+- Work spans multiple files, phases, or agents.
+- Tasks need dependency ordering or parallelization decisions.
+- You need a handoff artifact for worker agents.
+
+## When NOT to Use
+
+- Single-file fixes that can be implemented directly.
+- Requirements are still unclear; use `spec-driven-development` first.
+- You are debugging an active failure; use `debugging-and-error-recovery`.
+
+## Workflow
+
+1. Restate the goal and constraints.
+2. Convert observable truths into required artifacts.
+3. Identify required wiring between artifacts.
+4. Mark key links most likely to break.
+5. Decompose into vertical slices, not horizontal layers.
+6. Limit each task to a small scope with exact files when known.
+7. Add acceptance checks and verification commands to every task.
+8. Build a dependency graph and execution order.
+9. Create tracked tasks or write a plan artifact.
+
+## Task Packet Template
+
+```markdown
+## Task N: [Name]
+
+Goal: [one sentence]
+Files in scope:
+- [path]
+Acceptance checks:
+- [behavior] -> verify with [command/check]
+Non-goals:
+- [explicit exclusion]
+Dependencies:
+- [task id/name or none]
+Review depth: targeted|standard|full
+```
+
+## Slicing Rules
+
+- Prefer vertical slices that produce end-to-end behavior.
+- Put risky unknowns first.
+- Do not mix refactors with feature behavior unless the refactor is required.
+- If one task touches more than five files, split it.
+- If a task needs architectural judgment, route to `planner`, not `worker`.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "I'll make tasks as I go" | Hidden dependencies appear too late. Plan the graph first. |
+| "Layer-by-layer is cleaner" | Horizontal layers delay integration and hide broken wiring. |
+| "Acceptance criteria are obvious" | Workers need objective checks, not intent. |
+| "One big task is simpler" | Big tasks are hard to review, rollback, and verify. |
+
+## Red Flags
+
+- Tasks named after vague activities like "update backend".
+- No verification command/check per task.
+- UI, API, and data work split so nothing works until the end.
+- Multiple agents assigned to overlapping files without sequencing.
+- Plan omits non-goals or rollback considerations.
+
+## Verification
+
+- Every task has goal, scope, acceptance checks, non-goals, dependencies.
+- Execution order respects dependencies.
+- Key links are identified for reviewer verification.
+- The first task can be implemented without further planning.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>planning-and-task-breakdown</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Plan/task packets include scope, dependencies, and verification</evidence>
+  <artifacts>Task ids or plan file path</artifacts>
+  <risks>Large tasks, unresolved dependencies, or none</risks>
+</skill_result>
+```
+
+
+## Consolidated Planning Workflow
+
+This is the canonical active planning skill. It absorbs PRD-to-plan and writing-plans responsibilities. Use spec-driven-development first when requirements are still unclear.
+
+Plans should include:
+- scope and non-goals;
+- ordered tasks with dependencies;
+- exact files or search targets when known;
+- acceptance checks per task;
+- review and verification gates;
+- handoff details for subagents with zero assumed context.

package/dist/template/.opencode/skill/shipping-and-launch/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: shipping-and-launch
+description: Guides final readiness checks, rollback planning, documentation, and release handoff. Use when preparing to merge, deploy, release, or declare a development branch complete.
+version: 1.0.0
+tags: [shipping, workflow, release]
+dependencies: [verification-before-completion, documentation-and-adrs]
+agent_types: [planner, reviewer]
+tools: [bash, ask_user_question, memory]
+---
+
+# Shipping & Launch
+
+## Overview
+
+Shipping should be boring because risk was removed earlier. The ship phase verifies readiness, documents what changed, and makes rollback possible.
+
+Core principle: do not ship work that cannot be verified, explained, or rolled back.
+
+## When to Use
+
+- User says ship, merge, deploy, release, or finish.
+- Before closing tracked work as complete.
+- Before creating a PR or release notes.
+- After build/review/QA phases pass.
+
+## When NOT to Use
+
+- Work is still being implemented.
+- Critical review findings are open.
+- Verification cannot run and no user-approved exception exists.
+
+## Workflow
+
+1. Check worktree state and identify intended changes.
+2. Confirm spec/plan acceptance criteria are met.
+3. Run required verification or use a fresh valid verification stamp.
+4. Run phantom completion checks for stubs, placeholders, and disconnected wiring.
+5. Review security/secrets/configuration risk in the diff.
+6. Confirm docs/ADRs/changelog updates are sufficient.
+7. Define rollback path: revert commit, feature flag, migration rollback, or manual procedure.
+8. Present ship options when action is irreversible: PR, merge, deploy, hold.
+9. Record handoff/memory when useful.
+
+## Pre-Ship Checklist
+
+- Tests relevant to changed behavior pass.
+- Build/typecheck/lint pass or exceptions are documented.
+- No high-severity review findings remain.
+- No secrets or local-only paths in diff.
+- User-facing/API behavior is documented.
+- Rollback path is clear.
+- User approval exists for irreversible actions.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "Tests passed earlier" | Fresh changes require fresh evidence or a valid unchanged-state stamp. |
+| "Rollback is just git revert" | Migrations, flags, queues, and external state may need more. |
+| "Docs can wait" | Shipped behavior without docs becomes support debt. |
+| "Small release, no checklist" | Small releases still leak secrets and break config. |
+
+## Red Flags
+
+- Completion claim without verification evidence.
+- Unresolved P0/P1 findings.
+- No rollback plan for data or API changes.
+- Changelog omits user-visible behavior changes.
+- Deployment/merge attempted without explicit user approval.
+- Placeholder/stub patterns remain in modified code.
+
+## Verification
+
+- Verification commands and outputs are recorded.
+- Acceptance criteria are checked line-by-line.
+- Phantom completion scan is clean or exceptions are explained.
+- Rollback plan is documented.
+- Final action is approved when irreversible.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>shipping-and-launch</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Verification commands, acceptance audit, review status, rollback plan</evidence>
+  <artifacts>Changelog, PR, release notes, handoff, or none</artifacts>
+  <risks>Open findings, skipped checks, deployment risk, or none</risks>
+</skill_result>
+```
+
+
+## Consolidated Branch Completion
+
+`finishing-a-development-branch` was removed as a separate optional skill. Keep merge/PR/cleanup choices, release handoff, rollback planning, and completion evidence in this canonical shipping workflow.

package/dist/template/.opencode/skill/source-driven-development/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: source-driven-development
+description: Grounds implementation decisions in official docs, source code, and cited references. Use when using unfamiliar libraries, external APIs, framework behavior, or current ecosystem guidance.
+version: 1.0.0
+tags: [research, implementation, verification]
+dependencies: []
+agent_types: [scout, planner, worker]
+tools: [context7, websearch, web_fetch, webclaw_scrape, grepsearch, codesearch]
+---
+
+# Source-Driven Development
+
+## Overview
+
+Framework guesses become bugs. Source-driven work verifies behavior against authoritative references before implementation.
+
+Core principle: cite the source for non-trivial external API decisions, or mark the decision as unverified.
+
+## When to Use
+
+- New or unfamiliar library/framework/API.
+- Version-specific behavior matters.
+- Choosing between packages or integration patterns.
+- Error suggests external API misuse.
+- User asks to research current best practice.
+
+## When NOT to Use
+
+- Pure local codebase questions; use code search/explore.
+- Stable project conventions already cover the behavior.
+- Trivial syntax you can verify from existing code.
+
+## Source Hierarchy
+
+1. Official docs, specs, release notes.
+2. Maintained source code and examples.
+3. Maintainer-authored articles.
+4. Community posts only when higher sources are absent.
+
+Higher-ranked sources win on conflicts.
+
+## Workflow
+
+1. State the question precisely.
+2. Check memory/local docs for prior decisions.
+3. Retrieve authoritative sources.
+4. Verify version compatibility with the project.
+5. Compare sources if guidance conflicts.
+6. Extract only the implementation-relevant facts.
+7. Cite URLs or source refs in the recommendation.
+8. Mark unresolved uncertainty explicitly.
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "I know this API" | APIs change; verify version-specific behavior. |
+| "A blog said so" | Blogs lose to official docs/source. |
+| "The package name is obvious" | Similar packages differ in security and maintenance. |
+| "Citations slow us down" | A bad integration costs more than a source check. |
+
+## Red Flags
+
+- Unfamiliar API used without citation or local precedent.
+- Community answer conflicts with official docs.
+- Version in docs differs from package version.
+- Agent invents options, flags, or imports.
+- Research dump has no recommendation.
+
+## Verification
+
+- Key claims cite authoritative sources.
+- Project/library versions are considered.
+- Implementation recommendation is specific.
+- Unverified assumptions are labeled.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>source-driven-development</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Sources consulted and version checks</evidence>
+  <artifacts>Research notes, citations, implementation recommendation</artifacts>
+  <risks>Unverified claims, stale docs, conflicting sources, or none</risks>
+</skill_result>
+```
+
+
+## Consolidated Research Workflow
+
+This is the canonical active source-grounding skill. It absorbs deep-research and source-code-research for normal work. Use opensrc, webclaw, context7, grepsearch, or gemini-large-context as tool-specific companions only when the source demands them.
+
+Evidence hierarchy:
+1. local code and tests;
+2. official docs and source;
+3. maintained examples from reputable repos;
+4. blog posts or issues with dates and caveats.
+
+
+## Removed Optional Companion
+
+`v1-run` was removed as an optional package-health skill. Use source-grounded package evaluation, official advisories, lockfile inspection, and package-manager audit commands instead.

package/dist/template/.opencode/skill/spec-driven-development/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: spec-driven-development
+description: Guides agents from vague request to concrete specification before implementation. Use when starting a new feature, significant change, product idea, or when requirements are ambiguous.
+version: 1.0.0
+tags: [workflow, planning, product]
+dependencies: []
+agent_types: [planner, scout]
+tools: [ask_user_question, TaskCreate, memory]
+---
+
+# Spec-Driven Development
+
+## Overview
+
+A spec converts intent into testable truth. Code written before the target is clear becomes rework.
+
+Core principle: define observable outcomes, constraints, non-goals, and verification before planning implementation.
+
+**Define the vocabulary first.** Every concept in the spec should have one name — that name must match what the code will call it. This is Evans' "ubiquitous language": a shared vocabulary between developers, domain experts, code, and AI context files. Ambiguous language in the spec causes the "AI does the wrong thing" failure mode: the LLM implements what the words say, not what you meant.
+
+After writing the spec, extract a glossary of terms. Every capitalized concept in the spec should correspond to exactly one code symbol (type, class, module, function, file). If two terms mean the same thing, pick one. If one term means two things, split it.
+
+## When to Use
+
+- User asks for a new feature or significant behavior change.
+- Requirements are vague, conflicting, or missing edge cases.
+- Multiple files/systems will be affected.
+- The work needs acceptance criteria or user-visible behavior.
+
+## When NOT to Use
+
+- Tiny mechanical edits with obvious expected behavior.
+- Emergency bug fixes where reproduction is already clear; use `debugging-and-error-recovery`.
+- Pure research with no implementation decision; use `source-driven-development`.
+
+## Workflow
+
+1. State the goal as an outcome, not a task.
+2. **Establish vocabulary**: define the key terms and map them to code concepts.
+3. Derive 3-7 observable truths from the user's perspective.
+4. Identify constraints: technical, UX, security, performance, compatibility.
+5. Define non-goals to prevent scope creep.
+6. List affected surfaces: files, APIs, commands, UI screens, data models.
+7. Define acceptance criteria with verification methods.
+8. **Check vocabulary consistency**: does every spec term map to exactly one code symbol? Are any terms overloaded?
+9. Ask at most 1-4 focused questions only if missing information changes the design.
+10. Hand off to `planning-and-task-breakdown` when the spec is stable.
+
+## Spec Template
+
+```markdown
+# Spec: [Name]
+
+## Goal
+[Outcome in one sentence]
+
+## Vocabulary
+| Term | Definition | Code symbol |
+|------|------------|-------------|
+| ...  | ...        | ...         |
+
+Every concept should have one name. If two terms mean the same thing, consolidate. If one term means two things, split it.
+
+## Observable Truths
+- [User/system can observe X]
+
+## Constraints
+- [Hard constraint]
+
+## Non-Goals
+- [Explicitly out of scope]
+
+## Affected Surfaces
+- [File/API/UI/data area]
+
+## Acceptance Criteria
+- [Criterion] -> verify with [command/check/manual observation]
+
+## Open Questions
+- [Question or none]
+```
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "The user already explained it" | Explanation is not acceptance criteria. Write the target down. |
+| "I'll discover requirements while coding" | Discovery during coding causes churn and hidden scope expansion. |
+| "This is obvious" | Obvious to you is not a contract for the next agent or reviewer. |
+| "The AI will figure out what I mean" | The AI will implement exactly what the spec says. Ambiguous language = wrong implementation. |
+| "Questions slow us down" | One precise question is cheaper than implementing the wrong behavior. |
+
+## Red Flags
+
+- No explicit non-goals for a broad feature.
+- Acceptance criteria are phrased as implementation tasks.
+- Edge cases are deferred without user agreement.
+- The plan starts before observable truths are defined.
+- User-visible behavior has no verification method.
+- **No vocabulary section** — missing ubiquitous language means AI will guess term meanings.
+- **Same term used for different concepts** — e.g. "Order" means creation flow in one place and fulfillment in another.
+- **Different terms for the same concept** — e.g. "User" vs "Account" vs "Profile" used interchangeably.
+
+## Verification
+
+- Goal is outcome-shaped.
+- Observable truths are human-verifiable.
+- Acceptance criteria include commands/checks where possible.
+- Ambiguities that affect implementation are resolved or marked as assumptions.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>spec-driven-development</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Spec sections completed and questions/assumptions recorded</evidence>
+  <artifacts>Spec path or inline spec summary</artifacts>
+  <risks>Unresolved assumptions or none</risks>
+</skill_result>
+```

package/dist/template/.opencode/skill/srcwalk/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: srcwalk
+compatible_srcwalk: ">=1.0.0"
+description: Use when navigating code with srcwalk — repo maps, large-file reads, symbol search, callers/callees, flow slices, impact checks, and precise drill-ins.
+version: 2.1.0
+tags: [code-intelligence, search, cli, srcwalk]
+dependencies: []
+agent_types: [planner, worker, reviewer, explorer]
+tools: [bash, srcwalk_search, srcwalk_read, srcwalk_files, srcwalk_deps, srcwalk_map, srcwalk_callers, srcwalk_callees, srcwalk_flow, srcwalk_impact]
+---
+
+# Srcwalk — Code Navigation
+
+Srcwalk is the project's code navigation engine (v1.0.0+). All Pi tools are backed by the installed `srcwalk` binary.
+
+Run the embedded guide before non-trivial use — it is the version-matched source of truth:
+
+```bash
+srcwalk guide
+```
+
+Do not pipe, truncate, or summarize `srcwalk guide`.
+
+## When to Use
+
+- Any code navigation task: symbol search, large-file reading, repo maps
+- Tracing call graphs (callers, callees, transitive chains)
+- Checking blast radius before breaking changes
+- Understanding repo shape and token budgets
+- Quick function orientation (flow slice)
+- Heuristic impact triage
+
+## When NOT to Use
+
+- Non-code files where tree-sitter has no grammar → use `read` directly
+- Simple one-off reads of small known files → use built-in `read`
+
+## Pi Tool Surface
+
+### Core navigation tools
+
+| Tool | Srcwalk command | Purpose |
+|---|---|---|
+| `srcwalk_search` | `srcwalk discover` / `srcwalk trace callers` | AST-aware symbol/content/regex/callers search |
+| `srcwalk_read` | `srcwalk <path>` | Smart file reading: outline or full with sections |
+| `srcwalk_files` | `srcwalk discover --as file` | Glob file finding with token estimates, grouped by dir |
+| `srcwalk_deps` | `srcwalk deps` + exact import scan | Blast-radius: importers + dep-aware dependents (v1.0.0) |
+
+### Extended analysis tools
+
+| Tool | Srcwalk command | Purpose |
+|---|---|---|
+| `srcwalk_map` | `srcwalk overview` | Token-annotated directory skeleton + dep groups (v1.0.0) |
+| `srcwalk_callers` | `srcwalk trace callers` | Reverse call graph with BFS depth + filters |
+| `srcwalk_callees` | `srcwalk trace callees` | Forward call graph with `--detailed` ordered call sites |
+| `srcwalk_flow` | `srcwalk context` | Compact orientation slice |
+| `srcwalk_impact` | `srcwalk assess` | Heuristic blast-radius triage |
+
+## Command Routing
+
+| Intent | Use first |
+|---|---|
+| Understand repo shape | `srcwalk_map` |
+| Read or inspect a large file | `srcwalk_read` |
+| Jump to exact line | `srcwalk_read({ path: "file:42" })` |
+| Read a line range | `srcwalk_read({ path: "file:44-89" })` — v1.0.0 shortcut |
+| Read by symbol name | `srcwalk_read({ section: "symbolName" })` |
+| Find definition/usages/text/glob | `srcwalk_search` |
+| Find files by glob | `srcwalk_files` |
+| Multi-symbol search | `srcwalk_search({ query: "A, B, C" })` |
+| Who directly calls this? | `srcwalk_callers` |
+| Who reaches this transitively? | `srcwalk_callers({ depth: 2 })` |
+| What does this call? | `srcwalk_callees` |
+| Ordered calls + arg slots | `srcwalk_callees({ detailed: true })` |
+| Quick orientation slice | `srcwalk_flow` |
+| File imports and dependents | `srcwalk_deps` |
+| Heuristic blast-radius | `srcwalk_impact` (verify with callers) |
+
+## Default Workflows
+
+### Explore unfamiliar code
+
+```
+srcwalk_map({ scope: "." })
+srcwalk_search({ query: "likely_symbol", scope: "src" })
+srcwalk_read({ path: "src/file.ts:42" })         // jump to line
+srcwalk_read({ path: "src/file.ts:44-89" })      // range shortcut (v1.0.0)
+```
+
+### Read a large file
+
+```
+srcwalk_read({ path: "src/file.ts" })                        // structural outline
+srcwalk_read({ path: "src/file.ts", section: "handleAuth" }) // drill into symbol
+srcwalk_read({ path: "src/file.ts", section: "44-89" })      // exact range
+```
+
+Prefer outline/section reads before `full: true`.
+
+### Find and drill into symbols
+
+```
+srcwalk_search({ query: "handleAuth", scope: "src" })
+srcwalk_search({ query: "A, B, C", scope: "src" })           // multi-symbol
+srcwalk_search({ query: "handleAuth", expand: 2 })            // inline source
+```
+
+### Trace call graph
+
+```
+// upstream
+srcwalk_callers({ symbol: "handleAuth", scope: "src" })
+srcwalk_callers({ symbol: "handleAuth", depth: 2, scope: "src" })      // transitive
+srcwalk_callers({ symbol: "handleAuth", filter: "args:3", scope: "src" })
+srcwalk_callers({ symbol: "handleAuth", countBy: "file", scope: "src" })
+
+// downstream
+srcwalk_callees({ symbol: "handleAuth", scope: "src" })
+srcwalk_callees({ symbol: "handleAuth", detailed: true, scope: "src" }) // ordered sites
+srcwalk_callees({ symbol: "handleAuth", depth: 2, scope: "src" })       // transitive
+
+// quick orientation
+srcwalk_flow({ symbol: "handleAuth", scope: "src" })
+```
+
+Use `srcwalk_search({ kind: "callers" })` for quick single-hop. Use `srcwalk_callers` when you need depth, filters, or aggregation.
+
+> Note: `--count-by` and `--depth` are mutually exclusive in `srcwalk_callers` — use one or the other, not both.
+
+### Check file blast radius
+
+```
+srcwalk_deps({ path: "src/auth.ts" })
+srcwalk_impact({ symbol: "handleAuth", scope: "src" })  // heuristic; follow up with callers
+```
+
+## v1.0.0 Features
+
+- **Path range shortcut**: `srcwalk_read({ path: "file:start-end" })` reads a line range directly — no need to pass `section` separately
+- **Dependency-aware map**: `srcwalk_map` now shows local relation groups and outbound dependency previews for narrowed scopes
+- **JS/TS artifact navigation**: bundle anchors, artifact reads, artifact search snippets, and artifact caller/callee support
+- **Improved UX**: more compact semantic rows, directory grouping, footer tips, and clearer scope/depth wording across all commands
+
+## Critical Rules
+
+- **Do NOT** use built-in `read`/`grep`/`find` when srcwalk_* tools can answer
+- **Do NOT** re-read files already shown in expanded `srcwalk_search` results
+- `srcwalk_impact` is heuristic, not proof — verify with `srcwalk_callers` or exact reads
+- `srcwalk_flow` may collapse nested/fluent chains — drill with `srcwalk_callees({ detailed: true })` when inner calls matter
+- Follow `> Next:` footers in output — they suggest the best next command
+- Scope paths are **relative to Pi's CWD** (`.pi/` in this project). Use `scope: "extensions"` not `scope: ".pi/extensions"`
+
+## Supported Languages
+
+Rust, TypeScript, TSX, JavaScript, Python, Go, Java, Scala, C, C++, Ruby, PHP, C#, Swift, Elixir, Kotlin. Unsupported files still get smart text/outline reads.
+
+## Setup
+
+The srcwalk plugin is auto-discovered from `.opencode/plugin/srcwalk.ts`. No registration needed.
+
+All scope paths are relative to the **project root directory**. The default scope resolves from the project root.