@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 3+ independent failures that can be investigated without shared state or dependencies - dispatches multiple Claude agents to investigate and fix independent problems concurrently
+version: 1.0.0
+tags: [agent-coordination, workflow]
+dependencies: []
+---
+
+# Dispatching Parallel Agents
+
+> **Replaces** sequential investigation of independent failures — one-by-one debugging when problems don't share state
+
+## When to Use
+
+- 3+ independent failures across different subsystems or test files
+- Each investigation can proceed without shared state or coordination
+
+## When NOT to Use
+
+- Failures are related or likely share a root cause
+- Work requires sequential understanding of the same code paths
+
+## Parallel Dispatch Checklist
+
+- [ ] Confirm 3+ independent failures or domains
+- [ ] Group failures by domain and define clear ownership
+- [ ] Write focused prompts with scope, constraints, and expected output
+- [ ] Dispatch one agent per domain in parallel
+- [ ] Review each agent’s summary and check for conflicts
+- [ ] Run full verification after integrating changes
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures");
+Task("Fix batch-completion-behavior.test.ts failures");
+Task("Fix tool-approval-race-conditions.test.ts failures");
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+4. **Structured termination** - Include the Structured Termination Contract from AGENTS.md (Result/Verification/Summary/Blockers format)
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+[Include Structured Termination Contract here]
+```
+
+For large investigations (context >500 tokens), use the **Context File Pattern** from AGENTS.md — write context to `.beads/artifacts/<id>/investigation-context.md` and reference by path in the dispatch prompt.
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes
+
+## See Also
+
+- `agent-teams` — for coordinated parallel work (not just debugging)
+- `swarm-coordination` — for large-scale task decomposition
+- `executing-plans` — for plan-driven parallel execution

package/dist/template/.opencode/skill/documentation-and-adrs/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: documentation-and-adrs
+description: Use when writing technical documentation, Architecture Decision Records (ADRs), API docs, or project READMEs — covers documentation structure, ADR format, and keeping docs in sync with code
+version: 1.0.0
+tags: [workflow, code-quality]
+dependencies: []
+---
+
+# Documentation & ADRs
+
+> **Replaces** undocumented architectural decisions and stale wiki pages with living documentation that stays close to code
+
+## When to Use
+
+- Making a significant architectural decision that should be recorded
+- Writing or updating project documentation (README, guides, API docs)
+- Onboarding documentation needs updating
+- Code has complex behavior that isn't obvious from reading it
+
+## When NOT to Use
+
+- Code is self-documenting (clear naming, simple logic, typed interfaces)
+- Writing comments that restate what the code does (comment the why, not the what)
+- Documentation for throwaway prototypes
+
+## Overview
+
+Documentation has two purposes: **decisions** (why things are the way they are) and **usage** (how to use them). ADRs handle the first. Guides, READMEs, and API docs handle the second.
+
+**Core principle:** Document decisions when they're made, not months later when context is lost. Keep docs next to the code they describe.
+
+## Architecture Decision Records (ADRs)
+
+### When to Write an ADR
+
+- Choosing between technologies, frameworks, or approaches
+- Establishing a pattern that the team should follow
+- Deviating from an existing convention (and why)
+- Any decision you'd want to explain to a new team member in 6 months
+
+### ADR Template
+
+```markdown
+# ADR-NNN: [Decision Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+
+What is the issue we're facing? What constraints exist?
+[2-5 sentences describing the problem and constraints]
+
+## Decision
+
+What did we decide to do?
+[1-3 sentences stating the decision clearly]
+
+## Alternatives Considered
+
+| Option   | Pros | Cons | Verdict            |
+| -------- | ---- | ---- | ------------------ |
+| Option A | ...  | ...  | Chosen             |
+| Option B | ...  | ...  | Rejected: [reason] |
+| Option C | ...  | ...  | Rejected: [reason] |
+
+## Consequences
+
+### Positive
+
+- [Good outcomes]
+
+### Negative
+
+- [Trade-offs accepted]
+
+### Risks
+
+- [Things that could go wrong]
+```
+
+### ADR File Location
+
+```
+docs/adr/
+├── 001-use-typescript.md
+├── 002-choose-react-over-vue.md
+├── 003-api-versioning-strategy.md
+└── template.md
+```
+
+**Naming:** `NNN-kebab-case-title.md` — numbered for ordering, kebab-case for readability.
+
+## README Structure
+
+### Minimum Viable README
+
+```markdown
+# Project Name
+
+One-line description of what this does.
+
+## Quick Start
+
+[3-5 commands to get running]
+
+## Development
+
+[How to build, test, lint]
+
+## Architecture
+
+[Brief overview or link to docs/]
+
+## Contributing
+
+[Link to CONTRIBUTING.md or inline guide]
+```
+
+### README Anti-Patterns
+
+| Anti-Pattern                        | Fix                             |
+| ----------------------------------- | ------------------------------- |
+| "See wiki for docs" (wiki is stale) | Keep docs in repo, next to code |
+| Huge README (>500 lines)            | Split into docs/ directory      |
+| No Quick Start section              | First thing a new dev needs     |
+| Setup instructions that don't work  | CI should verify setup steps    |
+
+## API Documentation
+
+### In-Code Documentation
+
+````typescript
+/**
+ * Create a new project workspace.
+ *
+ * @param name - Project name (1-100 chars, alphanumeric + hyphens)
+ * @param options - Configuration options
+ * @returns The created project with generated ID
+ * @throws {ValidationError} If name is invalid
+ * @throws {ConflictError} If project name already exists
+ *
+ * @example
+ * ```typescript
+ * const project = await createProject('my-app', { template: 'react' });
+ * console.log(project.id); // "proj_abc123"
+ * ```
+ */
+export async function createProject(
+  name: string,
+  options?: CreateProjectOptions,
+): Promise<Project> {
+````
+
+### Documentation Comments Rules
+
+| Do                                               | Don't                                |
+| ------------------------------------------------ | ------------------------------------ |
+| Document the **why**                             | Restate the code as prose            |
+| Document **contracts** (inputs, outputs, errors) | Document obvious getters/setters     |
+| Document **non-obvious behavior**                | Document every function              |
+| Include **examples** for complex APIs            | Write examples for self-evident APIs |
+
+## Keeping Docs in Sync
+
+### Documentation Debt Signals
+
+- README references files that don't exist
+- Setup instructions fail on clean checkout
+- API docs describe removed/renamed endpoints
+- ADRs reference superseded decisions without linking forward
+
+### Automation
+
+```yaml
+# CI check: verify docs are not stale
+- name: Check links
+  run: npx markdown-link-check README.md docs/**/*.md
+
+- name: Verify setup instructions
+  run: |
+    # Run the Quick Start commands from README
+    npm install
+    npm run build
+    npm test
+```
+
+## Common Rationalizations
+
+| Excuse                         | Rebuttal                                                                |
+| ------------------------------ | ----------------------------------------------------------------------- |
+| "The code is self-documenting" | Code shows what, not why. Decisions need context.                       |
+| "Nobody reads the docs"        | Because the docs are stale. Fresh docs get read.                        |
+| "I'll document it later"       | You won't. Context decays faster than you think.                        |
+| "ADRs are overhead"            | An ADR takes 10 minutes. Re-debating the decision takes hours.          |
+| "We use Notion/Confluence"     | Docs in external tools drift from code. Keep docs in repo.              |
+| "Comments get stale"           | So delete stale comments. But contracts and decisions need documenting. |
+
+## Red Flags — STOP
+
+- Architecture changed but no ADR recorded
+- README setup instructions haven't been tested in >30 days
+- API docs describe behavior that doesn't match implementation
+- Decision was made in Slack/meeting with no written record
+- New team member can't set up the project from docs alone
+
+## Verification
+
+- [ ] Significant decisions have ADRs with status, context, and alternatives
+- [ ] README Quick Start works on a clean checkout
+- [ ] API functions with complex behavior have JSDoc with examples
+- [ ] No dead links in documentation
+- [ ] Docs live in the repo (not external wiki only)
+
+## See Also
+
+- **api-and-interface-design** — API docs are part of the interface contract
+- **deprecation-and-migration** — Deprecation decisions warrant ADRs
+- **prd** — Product requirements docs (higher-level than ADRs)

package/dist/template/.opencode/skill/executing-plans/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: executing-plans
+description: Use when a complete implementation plan exists — parses dependency waves, executes independent tasks in parallel via subagents, runs review checkpoints between waves
+version: 2.0.0
+tags: [workflow, planning, parallel]
+dependencies: [writing-plans]
+---
+
+# Executing Plans
+
+> **Replaces** sequential task-by-task implementation — detects parallelizable waves and dispatches subagents concurrently within each wave
+
+## When to Use
+
+- A complete implementation plan exists (`.beads/artifacts/<id>/plan.md` or provided directly)
+- The plan has a dependency graph with wave assignments from `/plan`
+
+## When NOT to Use
+
+- No plan yet (use `writing-plans` or `prd` first)
+- All tasks are tightly sequential with no parallelism opportunity
+- Fewer than 3 tasks (just execute directly, overhead not worth it)
+
+## Overview
+
+Load plan → parse dependency waves → execute each wave (parallel within, sequential between) → review after each wave → next wave.
+
+**Core principle:** Parallel within waves, sequential between waves, review at wave boundaries.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+#### Plan Review Checklist
+
+- [ ] Read the plan file end-to-end
+- [ ] Identify goal, deliverables, risks, and missing pieces
+- [ ] If concerns, ask via `question()` and wait for decision
+- [ ] If no concerns, proceed to wave parsing
+
+1. Read plan file
+2. Review critically — identify any questions or concerns
+3. If concerns: raise them with `question()` tool
+4. If no concerns: proceed
+
+### Step 2: Parse Dependency Graph
+
+Look for the dependency graph section in the plan. The `/plan` command generates this format:
+
+```
+## Dependency Graph
+
+Task A: needs nothing, creates src/models/X.ts
+Task B: needs Task A, creates src/api/X.ts
+Task C: needs nothing, creates src/utils/Y.ts
+Task D: needs Task B + Task C, creates src/routes/Z.ts
+
+Wave 1: A, C  (independent)
+Wave 2: B     (depends on A)
+Wave 3: D     (depends on B, C)
+```
+
+**Extract:**
+- Which tasks belong to each wave
+- Which files each task modifies (for conflict detection)
+- Dependencies between tasks
+
+**If no dependency graph found:** Fall back to sequential execution (batch of 3 tasks).
+
+**File conflict check:** Tasks in the same wave MUST NOT modify the same files. If they do, move one to the next wave.
+
+### Step 3: Create TodoWrite
+
+Create todos for all tasks, grouped by wave:
+
+```typescript
+todowrite({
+  todos: [
+    { content: "Wave 1: Task A — [description]", status: "pending", priority: "high" },
+    { content: "Wave 1: Task C — [description]", status: "pending", priority: "high" },
+    { content: "Wave 1 review checkpoint", status: "pending", priority: "high" },
+    { content: "Wave 2: Task B — [description]", status: "pending", priority: "high" },
+    { content: "Wave 2 review checkpoint", status: "pending", priority: "high" },
+    // ...
+  ]
+});
+```
+
+### Step 4: Execute Wave
+
+**Before starting a wave:** create a git tag for safe rollback:
+
+```bash
+git tag wave-${WAVE_NUMBER}-start
+```
+
+#### Single-task wave (no parallelism needed)
+
+Execute directly in the current agent context. No subagent overhead.
+
+#### Multi-task wave (2+ independent tasks)
+
+Dispatch parallel subagents — one per task:
+
+```typescript
+// Dispatch all tasks in this wave simultaneously
+task({
+  subagent_type: "general",
+  description: `Wave ${N}: Task A — ${taskTitle}`,
+  prompt: `You are implementing Task A from the plan.
+
+## Task
+${taskDescription}
+
+## Files to modify
+${taskFiles.join('\n')}
+
+## Constraints
+- ONLY modify files listed above
+- Follow each step exactly as written in the task
+- Run verification commands specified in the task
+- Commit your changes: git add <specific-files> && git commit -m "feat: ${taskTitle}"
+
+## Report back
+- What you implemented
+- Files changed
+- Verification results (pass/fail)
+- Commit hash
+- Any issues or blockers`
+});
+// ...dispatch other tasks in this wave simultaneously
+```
+
+**Critical rules for parallel dispatch:**
+
+| Rule | Why |
+| --- | --- |
+| Non-overlapping files | Subagents editing same file = merge conflicts |
+| Exact file list per subagent | Prevents scope creep into other tasks |
+| Each subagent commits independently | Clean git history per task |
+| Never `git add .` | Only stage files from this task |
+
+#### Wave Execution Checklist
+
+- [ ] Create wave start tag: `git tag wave-${WAVE_NUMBER}-start`
+- [ ] Dispatch subagents for all tasks in this wave (parallel)
+- [ ] Collect results from all subagents
+- [ ] Check for failures — if any task failed, stop and report
+- [ ] Run verification gates (typecheck + lint in parallel, then tests)
+- [ ] Create wave complete tag: `git tag wave-${WAVE_NUMBER}-complete`
+- [ ] Mark wave tasks as completed in TodoWrite
+
+### Step 5: Review Wave
+
+After each wave completes:
+
+1. **Synthesize results** from all subagents
+2. **Run verification gates** on the combined changes:
+   ```bash
+   # Parallel: typecheck + lint
+   npm run typecheck & npm run lint & wait
+   # Sequential: tests
+   npm test
+   ```
+3. **Report to user:**
+   - Tasks completed in this wave
+   - Verification results
+   - Wave tag created
+   - Any issues found
+4. **Wait for feedback** before proceeding to next wave
+
+### Step 6: Next Wave
+
+Based on feedback:
+- Apply corrections if needed
+- Execute next wave (repeat Steps 4-5)
+- Continue until all waves complete
+
+### Step 7: Complete Development
+
+After all waves complete and verified:
+
+- Announce: "I'm using finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use skill({ name: "finishing-a-development-branch" })
+- Follow that skill to verify tests, present options, execute choice
+
+## Wave-Level Rollback with Git Tags
+
+Git tags act as checkpoints between waves. If a wave fails irrecoverably, roll back to the last known-good state.
+
+### Tag Protocol
+
+| When                         | Command                         | Purpose                   |
+| ---------------------------- | ------------------------------- | ------------------------- |
+| Before starting any wave     | `git tag wave-N-start`          | Mark rollback point       |
+| After wave passes all gates  | `git tag wave-N-complete`       | Seal confirmed-good state |
+| On irrecoverable failure     | `git reset --hard wave-N-start` | Restore to pre-wave state |
+| Listing all wave checkpoints | `git tag --list "wave-*"`       | Audit trail of execution  |
+
+### When to Rollback
+
+Roll back (with user confirmation) when:
+- Verification gates fail twice consecutively in the same wave
+- Subagent made destructive changes outside its file scope
+- Tests were broken and the cause is unclear
+
+**Always ask the user before running `git reset --hard`** — it discards uncommitted changes irreversibly.
+
+## Sequential Fallback
+
+If the plan has no dependency graph or waves:
+
+1. Group tasks into batches of 3
+2. Execute each batch sequentially (no parallel subagents)
+3. Review between batches
+4. Same wave-tag protocol applies
+
+This preserves backward compatibility with plans that don't have wave assignments.
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Subagent reports a blocker or failure
+- File conflict detected between parallel tasks
+- Verification fails twice in the same wave
+- Plan has critical gaps preventing starting
+
+**Ask for clarification rather than guessing.**
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Dispatching parallel subagents for tasks that share files | Edit conflicts, lost changes, merge chaos | Move conflicting tasks to separate waves |
+| Skipping verification between waves | Broken code compounds across waves | Run all gates after each wave before proceeding |
+| Giving subagents the full plan instead of their task | Context pollution, scope creep | Extract only the specific task + file list |
+| Running all tasks in one wave regardless of dependencies | Later tasks fail because prerequisites aren't ready | Respect the dependency graph strictly |
+| Not committing per-task | Can't rollback individual tasks, messy git history | Each subagent commits its own changes |
+
+## See Also
+
+- `writing-plans` — Create detailed, zero-ambiguity implementation plans before execution
+- `swarm-coordination` — For 10+ task scenarios with full PARL orchestration
+- `subagent-driven-development` — For sequential per-task execution with review between each
+- `verification-before-completion` — Run final verification gates before claiming completion