opencode-starterkit 1.0.1

package/baseline/command/plan.md

@@ -0,0 +1,355 @@
+---
+description: Create detailed implementation plan with TDD steps for a bead
+argument-hint: "<bead-id> [--create-beads]"
+agent: plan
+---
+
+# Plan: $ARGUMENTS
+
+Create a detailed implementation plan with TDD steps. Optional deep-planning between `/start` and `/ship`.
+
+> **Workflow:** `/create` → `/start <id>` → **`/plan <id>`** (optional) → `/ship <id>`
+>
+> ⛔ Bead MUST be `in_progress` with `prd.md`. Use `/start` first.
+>
+> **When to use:** Complex tasks where PRD verification steps aren't enough guidance. Skip for simple tasks.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "writing-plans" }); // TDD plan format
+```
+
+## Parse Arguments
+
+| Argument         | Default  | Description                       |
+| ---------------- | -------- | --------------------------------- |
+| `<bead-id>`      | required | The bead to plan                  |
+| `--create-beads` | false    | Create child beads for each phase |
+
+## Before You Plan
+
+- **Be certain**: Only create tasks you're confident about
+- **Don't over-plan**: If the PRD is clear, trust it
+- **Budget context**: Target ~50% context per execution
+- **Split signals**: Create child beads for complex work
+- **Vertical slices**: Each task should cover one feature end-to-end
+
+## Phase 0: Institutional Research (Mandatory)
+
+Before touching the PRD or planning anything, load what the codebase already knows.
+
+**This step is not optional.** Skipping it means planning in the dark.
+
+### Step 1: Search institutional memory
+
+```typescript
+// Search for past decisions, patterns, gotchas related to this work
+memory_search({ query: "<bead-title or feature keywords>", limit: 5 });
+memory_search({ query: "<key technical concept from bead>", type: "bugfix", limit: 3 });
+memory_read({ file: "handoffs/last" }); // Check last session context
+```
+
+If relevant observations found: incorporate them directly into the plan. Don't re-solve solved problems.
+
+### Step 2: Mine git history
+
+```bash
+# What has changed recently in affected areas?
+git log --oneline -20
+
+# Who wrote the relevant code and when?
+git log --oneline --follow -- <relevant-file-path>
+
+# What patterns appear in recent commits?
+git log --oneline --all | head -30
+```
+
+Look for:
+
+- Commit conventions (how this team names things)
+- Recent changes to files you'll touch (merge conflict risk)
+- How similar features were implemented before
+- Any "fix:", "revert:", "hotfix:" commits near your scope (footgun zones)
+
+### Step 3: Spawn learnings-researcher (if Level 2-3 work)
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "Search codebase for patterns related to this work",
+  prompt: `Search the codebase for patterns, conventions, and existing implementations related to: [FEATURE].
+
+  Run these searches:
+  - grep for relevant function names and patterns
+  - Find similar existing features
+  - Check test patterns for this domain
+  - Look for any TODO/FIXME comments in relevant files
+
+  Return: existing patterns to follow, files to be aware of, and any gotchas.`,
+});
+```
+
+**Only after completing Phase 0** do you proceed to planning. The research phases must use this context.
+
+## Phase 1: Guards
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Verify:
+
+- Bead is `in_progress`
+- `prd.md` exists
+- If `plan.md` already exists, ask user: overwrite or skip?
+
+## Phase 2: Discovery Assessment
+
+Before research, determine discovery level based on PRD:
+
+| Level | Scope                | When to Use                                                       | Action                                      |
+| ----- | -------------------- | ----------------------------------------------------------------- | ------------------------------------------- |
+| **0** | Skip                 | Pure internal work, existing patterns only (grep confirms)        | Skip research, proceed to decomposition     |
+| **1** | Quick (2-5 min)      | Single known library, confirming syntax/version                   | `context7 resolve-library-id + query-docs`  |
+| **2** | Standard (15-30 min) | Choosing between 2-3 options, new external integration            | Spawn `@scout` for research                 |
+| **3** | Deep (1+ hour)       | Architectural decision, novel problem, multiple external services | Full research with parallel `@scout` agents |
+
+**Depth indicators:**
+
+- Level 2+: New library not in package.json, external API, "choose/select/evaluate"
+- Level 3: "architecture/design/system", data modeling, auth design
+
+**Decision:** Ask user to confirm or adjust:
+
+```typescript
+const suggestedLevel = assessDiscoveryLevel(prdContent);
+
+question({
+  questions: [
+    {
+      header: "Discovery Level",
+      question: `Suggested: Level ${suggestedLevel} (${getLevelDescription(suggestedLevel)}). Proceed?`,
+      options: [
+        { label: `Yes, Level ${suggestedLevel} (Recommended)` },
+        { label: "Lower (less research)", description: "If you know the patterns" },
+        { label: "Higher (more research)", description: "If uncertain about approach" },
+        { label: "Skip research", description: "I know the codebase" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 3: Research (if Level 1-3)
+
+Read the PRD and extract tasks, success criteria, affected files, scope.
+
+Spawn parallel agents to gather implementation context:
+
+| Agent     | Purpose                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `explore` | Codebase patterns, affected file structure, test patterns, conflicts |
+| `scout`   | Best practices, common patterns, pitfalls                            |
+
+## Phase 4: Goal-Backward Analysis
+
+**Forward planning:** "What should we build?" → produces tasks
+**Goal-backward:** "What must be TRUE for the goal to be achieved?" → produces requirements
+
+### Step 1: Extract Goal from PRD
+
+Take success criteria from PRD. Must be outcome-shaped, not task-shaped.
+
+- Good: "Working chat interface" (outcome)
+- Bad: "Build chat components" (task)
+
+### Step 2: Derive Observable Truths
+
+"What must be TRUE for this goal to be achieved?" List 3-7 truths from USER's perspective.
+
+Example for "working chat interface":
+
+- User can see existing messages
+- User can type a new message
+- User can send the message
+- Sent message appears in the list
+- Messages persist across page refresh
+
+**Test:** Each truth verifiable by a human using the application.
+
+### Step 3: Derive Required Artifacts
+
+For each truth: "What must EXIST for this to be true?"
+
+| Truth                          | Required Artifacts                                              |
+| ------------------------------ | --------------------------------------------------------------- |
+| User can see existing messages | Message list component, Messages state, API route, Message type |
+| User can send a message        | Input component, Send handler, POST API                         |
+
+**Test:** Each artifact = a specific file or database object.
+
+### Step 4: Identify Key Links
+
+"Where is this most likely to break?" Critical connections where breakage causes cascading failures.
+
+| From      | To        | Via                 | Risk                                |
+| --------- | --------- | ------------------- | ----------------------------------- |
+| Input     | API       | `fetch` in onSubmit | Handler not wired                   |
+| API       | Database  | `prisma.query`      | Query returns static, not DB result |
+| Component | Real data | `useEffect` fetch   | Shows placeholder, not messages     |
+
+## Phase 5: Decompose with Context Budget
+
+**Quality Degradation Rule:** Target ~50% context per execution. More plans, smaller scope = consistent quality.
+
+| Task Complexity | Max Tasks | Context/Task | Total   |
+| --------------- | --------- | ------------ | ------- |
+| Simple (CRUD)   | 3         | ~10-15%      | ~30-45% |
+| Complex (auth)  | 2         | ~20-30%      | ~40-50% |
+| Very complex    | 1-2       | ~30-40%      | ~30-50% |
+
+**Split signals (create child plans):**
+
+- More than 3 tasks
+- Multiple subsystems (DB + API + UI)
+- Any task with >5 file modifications
+- Checkpoint + implementation in same plan
+- Discovery + implementation in same plan
+
+Assess size to determine plan structure:
+
+| Size          | Files     | Approach                                 |
+| ------------- | --------- | ---------------------------------------- |
+| S (1-3 files) | 2-4 tasks | Single plan, no phases                   |
+| M (3-8 files) | 5-8 tasks | 2-3 phases                               |
+| L (8+ files)  | 9+ tasks  | Create child beads with `--create-beads` |
+
+## Phase 6: Dependency Graph & Wave Assignment
+
+**For each task, record:**
+
+- `needs`: What must exist before this runs
+- `creates`: What this produces
+- `has_checkpoint`: Requires user interaction?
+
+**Example:**
+
+```
+Task A (User model): needs nothing, creates src/models/user.ts
+Task B (User API): needs Task A, creates src/api/users.ts
+Task C (User UI): needs Task B, creates src/components/UserList.tsx
+
+Wave 1: A (independent)
+Wave 2: B (depends on A)
+Wave 3: C (depends on B)
+```
+
+**Wave assignment enables parallel execution in `/ship`.**
+
+**Vertical slices preferred:** Each plan covers one feature end-to-end (model + API + UI)
+**Avoid horizontal layers:** Don't create "all models" then "all APIs" then "all UI"
+
+## Phase 7: Write Plan
+
+Write `.beads/artifacts/$ARGUMENTS/plan.md` following the `writing-plans` skill format:
+
+### Required Plan Header
+
+```markdown
+# [Feature] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use skill({ name: "executing-plans" }) to implement this plan task-by-task.
+
+**Goal:** [Outcome-shaped goal from PRD]
+
+**Discovery Level:** [0-3] - [Rationale]
+
+**Context Budget:** [Estimated context usage, target ~50%]
+
+---
+
+## Must-Haves
+
+### Observable Truths
+
+(What must be TRUE for the goal to be achieved?)
+
+1. [Truth 1]
+2. [Truth 2]
+3. [Truth 3]
+
+### Required Artifacts
+
+| Artifact         | Provides       | Path                  |
+| ---------------- | -------------- | --------------------- |
+| [File/component] | [What it does] | `src/path/to/file.ts` |
+
+### Key Links
+
+| From        | To    | Via     | Risk           |
+| ----------- | ----- | ------- | -------------- |
+| [Component] | [API] | `fetch` | [Failure mode] |
+
+## Dependency Graph
+```
+
+Task A: needs nothing, creates src/models/X.ts
+Task B: needs Task A, creates src/api/X.ts
+Task C: needs Task B, has_checkpoint, creates src/components/X.tsx
+
+Wave 1: A
+Wave 2: B
+Wave 3: C
+
+```
+
+## Tasks
+```
+
+### Task Standards:
+
+- **Exact file paths** — never "add to the relevant file"
+- **Complete code** — never "add validation logic here"
+- **Exact commands with expected output**
+- **TDD order** — test first, then implementation
+- **Each step is 2-5 minutes** — one action per step
+- **Tasks map to PRD tasks**
+
+## Phase 8: Create Child Beads (if --create-beads or L size)
+
+For large work, create child beads for each plan phase:
+
+```bash
+CHILD=$(br create "[Phase title]" --type task --json | jq -r '.id')
+br dep add $CHILD $ARGUMENTS
+```
+
+## Phase 9: Report
+
+Output:
+
+1. **Discovery Level:** [0-3] with rationale
+2. **Must-Haves:** [N] observable truths, [M] required artifacts, [K] key links
+3. **Context Budget:** [Estimated usage]
+4. **Dependency Waves:** [N] waves for parallel execution
+5. **Task count:** [N] tasks, [M] TDD steps
+6. **Files affected:** [List]
+7. **Plan location:** `.beads/artifacts/$ARGUMENTS/plan.md`
+8. **Child bead hierarchy:** (if created)
+9. **Next step:** `/ship $ARGUMENTS`
+
+```bash
+br comments add $ARGUMENTS "Created plan.md: Level [N] discovery, [X] waves, [Y] tasks, [Z] TDD steps"
+```
+
+## Related Commands
+
+| Need           | Command       |
+| -------------- | ------------- |
+| Create spec    | `/create`     |
+| Start working  | `/start <id>` |
+| Execute plan   | `/ship <id>`  |
+| Research first | `/research`   |

package/baseline/command/pr.md

@@ -0,0 +1,161 @@
+---
+description: Create and submit pull request with bead traceability
+argument-hint: "[bead-id] [--draft]"
+agent: build
+---
+
+# Pull Request
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument    | Default  | Description        |
+| ----------- | -------- | ------------------ |
+| `<bead-id>` | optional | Link PR to bead    |
+| `--draft`   | false    | Create as draft PR |
+
+## Phase 1: Pre-PR Verification
+
+```bash
+git status --porcelain
+```
+
+If uncommitted changes exist, ask whether to commit first.
+
+Run verification gates. Detect project type and use the appropriate commands:
+
+| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
+| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
+| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
+| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
+| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
+| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
+
+Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
+
+If any gate fails, stop. Fix errors first, then run `/pr` again.
+
+## Phase 2: Gather Context
+
+```bash
+git branch --show-current
+git log main...HEAD --oneline
+git diff main...HEAD --stat
+```
+
+If bead ID provided:
+
+```bash
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+Read the PRD to extract goal and success criteria for the PR description.
+
+## Phase 2B: Pre-PR Review
+
+This is the last gate before code hits GitHub. Run it every time.
+
+Load the review skill:
+
+```typescript
+skill({ name: "requesting-code-review" });
+```
+
+Run **5 parallel agents**: security/correctness, performance/architecture, type-safety/tests, conventions/patterns, simplicity/completeness.
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git merge-base HEAD origin/main)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+Fill placeholders:
+
+- `{WHAT_WAS_IMPLEMENTED}`: what this PR delivers (from git log summary)
+- `{PLAN_OR_REQUIREMENTS}`: PRD path or brief requirements
+- `{BASE_SHA}` / `{HEAD_SHA}`: from above
+
+**Gate rule:** All Critical issues must be resolved before pushing. No exceptions.
+Important issues: fix or document as known limitation in PR body.
+
+After fixing issues, re-run verification gates from Phase 1 if code was changed.
+
+## Phase 3: Push and Confirm
+
+Show what will be pushed and ask the user:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Push",
+      question: "Ready to push and create PR. Proceed?",
+      options: [
+        { label: "Push & create PR (Recommended)", description: "Push branch and create PR" },
+        { label: "Push & draft PR", description: "Create as draft for review" },
+        { label: "Show diff first", description: "Review changes before pushing" },
+      ],
+    },
+  ],
+});
+```
+
+If confirmed:
+
+```bash
+git push -u origin $(git branch --show-current)
+```
+
+## Phase 4: Create PR
+
+```bash
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+
+[1-2 sentences: what this PR does and why]
+
+## Changes
+
+- `file.ts`: [what changed]
+- `other.ts`: [what changed]
+
+## Testing
+
+- All tests pass
+- Lint and typecheck pass
+- Manual verification: [how to test]
+
+## Checklist
+
+- [x] Tests added/updated
+- [x] All gates pass
+- [ ] Docs updated (if applicable)
+EOF
+)"
+```
+
+If `--draft`, add `--draft` flag.
+
+If bead ID provided, add artifacts section linking to `.beads/artifacts/$ARGUMENTS/prd.md`.
+
+## Output
+
+Report:
+
+1. PR URL
+2. Status (Ready for Review / Draft)
+3. Branch → main
+4. Gate results
+
+## Related Commands
+
+| Need         | Command        |
+| ------------ | -------------- |
+| Ship first   | `/ship <id>`   |
+| Verify first | `/verify <id>` |

package/baseline/command/research.md

@@ -0,0 +1,125 @@
+---
+description: Research a topic or bead before implementation
+argument-hint: "<topic-or-bead-id> [--quick|--thorough]"
+agent: scout
+---
+
+# Research: $ARGUMENTS
+
+Gather information before implementation. Find answers, document findings, stop when done.
+
+> Research can happen at any phase when you need external information or codebase understanding.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+// For --thorough mode:
+skill({ name: "deep-research" });
+```
+
+## Parse Arguments
+
+| Argument         | Default  | Description                         |
+| ---------------- | -------- | ----------------------------------- |
+| Topic or bead ID | required | What to research                    |
+| `--quick`        | false    | ~10 tool calls, single question     |
+| `--thorough`     | false    | ~100+ calls, comprehensive analysis |
+
+Default depth: ~30 tool calls for moderate exploration.
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                            |
+| ---------- | --------------------------- | --------------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Research within that bead context |
+| Topic      | String                      | Standalone research               |
+
+## Before You Research
+
+- **Be certain**: Only research what you need for implementation
+- **Don't over-research**: Stop when you have enough to proceed
+- **Use source priority**: Codebase → Docs → Source → GitHub → Web
+- **Verify confidence**: Medium+ confidence required before stopping
+- **Document findings**: Write to research.md for beads, report for topics
+
+## Available Tools
+
+| Tool         | Use When                        |
+| ------------ | ------------------------------- |
+| `explore`    | Codebase patterns, LSP analysis |
+| `scout`      | External docs, best practices   |
+| `context7`   | Official API references         |
+| `opensrc`    | Package source code inspection  |
+| `codesearch` | Real-world usage examples       |
+| `grepsearch` | GitHub code search              |
+
+## Phase 1: Load Context
+
+If argument is a bead ID:
+
+```bash
+br show $ARGUMENTS
+```
+
+Read PRD if it exists and extract questions that need answering.
+
+Check memory for previous research on this topic.
+
+## Phase 2: Research
+
+### Source Priority
+
+1. **Codebase patterns** — delegate to `explore` agent for LSP analysis
+2. **Official docs** — `context7` for API references
+3. **Source code** — `npx opensrc <package>` when docs are insufficient
+4. **GitHub examples** — `codesearch` / `grepsearch` for real-world patterns
+5. **Web search** — only if tiers 1-4 don't answer
+
+### Delegation
+
+| What              | Agent                        | When                                   |
+| ----------------- | ---------------------------- | -------------------------------------- |
+| Codebase analysis | `explore`                    | Internal patterns, file structure, LSP |
+| External docs     | `scout` (this agent)         | Library APIs, best practices           |
+| Multiple domains  | Parallel `explore` + `scout` | 3+ independent questions               |
+
+### Confidence Levels
+
+- **High**: Multiple authoritative sources agree, verified in codebase
+- **Medium**: Single good source, plausible but unverified
+- **Low**: Conflicting info, speculation — discard without corroboration
+
+## Phase 3: Stop When
+
+- All questions answered with medium+ confidence
+- Tool budget exhausted for depth level
+- Last 5 tool calls yielded no new insights
+- Blocked and need human input
+
+## Phase 4: Document
+
+Write findings to `.beads/artifacts/$ARGUMENTS/research.md` (if bead) or report directly (if topic):
+
+- Questions asked → answered/partial/unanswered with confidence
+- Key findings with sources (file paths, docs)
+- Recommendation based on findings
+- Open items needing resolution
+
+## Output
+
+Report:
+
+1. Depth level and tool call count
+2. Questions with answer status and confidence
+3. Key insights (bullet points)
+4. Open items remaining
+5. Next step suggestion
+
+## Related Commands
+
+| Need          | Command       |
+| ------------- | ------------- |
+| Create spec   | `/create`     |
+| Plan details  | `/plan <id>`  |
+| Start working | `/start <id>` |