opencode-starterkit 1.0.1

package/baseline/skill/development-lifecycle/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: development-lifecycle
+description: Orchestrates the full feature development lifecycle from ideation through verification. Guides through phases (brainstorm → design → specify → plan → implement → verify) and loads appropriate sub-skills at each stage.
+version: 1.0.0
+tags: [workflow, planning]
+dependencies: [brainstorming, prd, writing-plans, executing-plans, verification-before-completion, requesting-code-review, finishing-a-development-branch]
+---
+
+---
+
+# Development Lifecycle Orchestration
+
+## When to Use
+
+- Starting a new feature, migration, or refactor and need the full end-to-end workflow
+- You want phase-by-phase guidance with the correct sub-skill at each stage
+
+## When NOT to Use
+
+- You are already mid-phase and only need a specific sub-skill
+- The change is trivial and can skip the full lifecycle
+
+## Overview
+
+This skill orchestrates the complete feature development workflow, guiding you through each phase and loading the appropriate sub-skills automatically.
+
+**Use when:** Starting any new feature, migration, refactor, or significant change.
+
+**Announce at start:** "I'm using development-lifecycle to guide this work through all phases."
+
+## The Lifecycle
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│  IDEATION   │───▶│   DESIGN    │───▶│ SPECIFICATION│───▶│   PLANNING  │───▶│IMPLEMENTATION│
+│ brainstorming│   │  design.md  │    │   prd.md    │    │  tasks.md   │    │executing-plans│
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+                          │                  │                  │                  │
+                          └──────────────────┴──────────────────┴──────────────────┤
+                                              │                                     ▼
+                                    ┌─────────────────┐                   ┌─────────────┐
+                                    │    RESEARCH     │                   │VERIFICATION │
+                                    │   (optional)    │                   │verification-│
+                                    │ /research cmd   │                   │before-      │
+                                    └─────────────────┘                   │completion   │
+                                                                          └─────────────┘
+```
+
+**Note:** Research (`/research <bead-id>`) can happen at any phase when you need external information or deeper codebase understanding. It's not a sequential step but a parallel activity.
+
+## Phase 1: Ideation (brainstorming)
+
+### Phase 1 Checklist
+
+- [ ] Load `brainstorming`
+- [ ] Validate design with user
+- [ ] Write `.beads/artifacts/<bead-id>/design.md`
+
+**When:** You have a rough idea but need to explore and refine it.
+
+**Load skill:**
+
+```typescript
+skill({ name: "brainstorming" });
+```
+
+**Entry criteria:** User has an idea or problem to solve.
+
+**Process:**
+
+1. Understand current project context
+2. Ask questions one at a time (prefer multiple choice)
+3. Explore 2-3 approaches with trade-offs
+4. Present design in 200-300 word sections
+
+**Exit criteria:**
+
+- Design validated by user
+- Output: `.beads/artifacts/<bead-id>/design.md`
+
+**Template:** `.opencode/memory/_templates/design.md`
+
+---
+
+## Phase 2: Specification (prd)
+
+### Phase 2 Checklist
+
+- [ ] Confirm or create bead id
+- [ ] Ask clarifying questions
+- [ ] Write `.beads/artifacts/<bead-id>/prd.md`
+
+**When:** Design is validated, need formal requirements and task breakdown.
+
+**Load skill:**
+
+```typescript
+skill({ name: "prd" });
+```
+
+**Entry criteria:** Design document exists and is validated.
+
+**Process:**
+
+1. Confirm bead id (create if needed: `br create "Feature Name"`)
+2. Ask clarifying questions (5-7 max)
+3. Explore codebase patterns and constraints
+4. Write PRD with machine-convertible Tasks section
+
+**Exit criteria:**
+
+- PRD with all sections completed
+- Output: `.beads/artifacts/<bead-id>/prd.md`
+
+**Template:** `.opencode/memory/_templates/prd.md`
+
+---
+
+## Phase 3: Task Conversion (prd-task)
+
+### Phase 3 Checklist
+
+- [ ] Read PRD from `.beads/artifacts/<bead-id>/prd.md`
+- [ ] Generate `.beads/artifacts/<bead-id>/prd.json`
+- [ ] Ensure `progress.txt` exists
+
+**When:** PRD is complete, need executable task list.
+
+**Load skill:**
+
+```typescript
+skill({ name: "prd-task" });
+```
+
+**Entry criteria:** PRD exists at `.beads/artifacts/<bead-id>/prd.md`.
+
+**Process:**
+
+1. Read PRD and extract ## Tasks section
+2. Convert to JSON format with dependencies
+3. Create progress.txt for cross-iteration memory
+
+**Exit criteria:**
+
+- JSON task file created
+- Progress file initialized
+- Output: `.beads/artifacts/<bead-id>/prd.json`, `progress.txt`
+
+---
+
+## Phase 4: Planning (writing-plans)
+
+### Phase 4 Checklist
+
+- [ ] Create bite-sized tasks with exact file paths
+- [ ] Include TDD steps and verification commands
+- [ ] Write `.beads/artifacts/<bead-id>/plan.md`
+
+**When:** Tasks defined, need detailed implementation instructions.
+
+**Load skill:**
+
+```typescript
+skill({ name: "writing-plans" });
+```
+
+**Entry criteria:** Task list exists (prd.json or tasks.md).
+
+**Process:**
+
+1. Create bite-sized steps (2-5 min each)
+2. Include exact file paths, complete code
+3. TDD: write failing test → verify fail → implement → verify pass → commit
+4. Add verification commands for each step
+
+**Exit criteria:**
+
+- Detailed plan ready for execution
+- Output: `.beads/artifacts/<bead-id>/plan.md`
+
+**Template:** `.opencode/memory/_templates/tasks.md` (for task structure reference)
+
+---
+
+## Phase 5: Implementation (executing-plans)
+
+### Phase 5 Checklist
+
+- [ ] Load and review plan
+- [ ] Execute in batches with verification
+- [ ] Report for feedback between batches
+
+**When:** Plan is ready, time to build.
+
+**Load skill:**
+
+```typescript
+skill({ name: "executing-plans" });
+```
+
+**Entry criteria:** Plan exists at `.beads/artifacts/<bead-id>/plan.md`.
+
+**Process:**
+
+1. Load and review plan critically
+2. Execute in 3-task batches
+3. Report for feedback between batches
+4. Stop on blockers, don't guess
+
+**Exit criteria:**
+
+- All tasks completed
+- All verifications pass
+- Ready for final verification
+
+---
+
+## Phase 6: Verification (verification-before-completion)
+
+### Phase 6 Checklist
+
+- [ ] Identify verification commands
+- [ ] Run full verification suite
+- [ ] Only then claim completion and close bead
+
+**When:** Implementation complete, before claiming done.
+
+**Load skill:**
+
+```typescript
+skill({ name: "verification-before-completion" });
+```
+
+**Entry criteria:** All implementation tasks marked complete.
+
+**Process:**
+
+1. IDENTIFY: What commands prove completion?
+2. RUN: Execute full verification suite fresh
+3. READ: Check output, count failures
+4. VERIFY: Does output confirm the claim?
+5. ONLY THEN: Claim completion
+
+**Exit criteria:**
+
+- All verification commands pass with evidence
+- Bead can be closed: `br close <bead-id>`
+
+---
+
+## Phase Transitions
+
+### Quick Start (Skip to appropriate phase)
+
+| Starting Point                    | Begin At | Command                                             |
+| --------------------------------- | -------- | --------------------------------------------------- |
+| Rough idea                        | Phase 1  | `skill({ name: "brainstorming" })`                  |
+| Design done, need requirements    | Phase 2  | `skill({ name: "prd" })`                            |
+| PRD done, need task JSON          | Phase 3  | `skill({ name: "prd-task" })`                       |
+| Tasks defined, need detailed plan | Phase 4  | `skill({ name: "writing-plans" })`                  |
+| Plan ready, time to build         | Phase 5  | `skill({ name: "executing-plans" })`                |
+| Done coding, need verification    | Phase 6  | `skill({ name: "verification-before-completion" })` |
+
+### Skipping Phases
+
+For small changes, you can skip early phases:
+
+- **Bug fix:** Skip to Phase 5 (implement directly with verification)
+- **Clear requirements:** Skip Phase 1, start at Phase 2
+- **Simple refactor:** Skip to Phase 4 (plan) or Phase 5 (execute)
+
+---
+
+## Templates Reference
+
+| Phase         | Template                 | Purpose                       |
+| ------------- | ------------------------ | ----------------------------- |
+| Design        | `_templates/design.md`   | Architecture decisions        |
+| Specification | `_templates/prd.md`      | Requirements + task breakdown |
+| Planning      | `_templates/tasks.md`    | Detailed task structure       |
+| Quick Ideas   | `_templates/proposal.md` | Lightweight change proposals  |
+
+---
+
+## Beads Integration
+
+Every phase should operate within a bead context:
+
+```bash
+# Create bead for new feature
+br create "Feature Name"
+
+# Check current bead status
+br show <bead-id>
+
+# Update status as you progress
+br update <bead-id> --status in_progress
+
+# Close when complete
+br close <bead-id> --reason "All verification passed"
+
+# Sync changes
+br sync --flush-only
+```
+
+---
+
+## Example Full Workflow
+
+```
+User: "I want to add a dark mode toggle"
+
+1. IDEATION
+   → skill({ name: "brainstorming" })
+   → Questions about scope, triggers, persistence
+   → Design decisions documented
+   → Output: .beads/artifacts/br-dark-mode/design.md
+
+2. SPECIFICATION
+   → skill({ name: "prd" })
+   → Full PRD with requirements
+   → Tasks section for conversion
+   → Output: .beads/artifacts/br-dark-mode/prd.md
+
+3. TASK CONVERSION
+   → skill({ name: "prd-task" })
+   → JSON task list with dependencies
+   → Output: .beads/artifacts/br-dark-mode/prd.json
+
+4. PLANNING
+   → skill({ name: "writing-plans" })
+   → Bite-sized implementation steps
+   → Output: .beads/artifacts/br-dark-mode/plan.md
+
+5. IMPLEMENTATION
+   → skill({ name: "executing-plans" })
+   → Execute in batches with feedback
+   → All code written and committed
+
+6. VERIFICATION
+   → skill({ name: "verification-before-completion" })
+   → Tests pass: ✓
+   → Lint clean: ✓
+   → Build succeeds: ✓
+   → br close br-dark-mode --reason "Dark mode implemented and verified"
+```
+
+---
+
+## Key Principles
+
+1. **Phase-appropriate skills:** Load the right skill for each phase
+2. **Evidence at every gate:** No phase transition without verification
+3. **Templates guide structure:** Use templates for consistent output
+4. **Beads track progress:** Every feature gets a bead
+5. **Skip only when appropriate:** Small changes can skip early phases

package/baseline/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