opencode-starterkit 1.0.1

package/baseline/command/resume.md

@@ -0,0 +1,87 @@
+---
+description: Resume work on a bead from previous session
+argument-hint: "<bead-id>"
+agent: build
+---
+
+# Resume: $ARGUMENTS
+
+Pick up where a previous session left off. Recover context, verify state, continue.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+```
+
+## Phase 1: Verify Task
+
+```bash
+br show $ARGUMENTS
+```
+
+If not found, check `br list --status=all` — it may have been closed or the ID is wrong.
+
+## Phase 2: Git State
+
+```bash
+git branch --show-current
+git status --porcelain
+```
+
+If not on the right branch, check out the feature branch. If uncommitted changes exist, ask user what to do.
+
+## Phase 3: Find Handoff
+
+Check for handoff notes:
+
+```bash
+ls .beads/artifacts/$ARGUMENTS/handoffs/ 2>/dev/null
+```
+
+If a handoff exists, read the latest one. It tells you:
+
+- What was completed
+- Where work stopped
+- What to do next
+- Any blockers
+
+Also search previous sessions:
+
+```typescript
+find_sessions({ query: "$ARGUMENTS" });
+```
+
+## Phase 4: Load Artifacts
+
+Read all available context:
+
+- `.beads/artifacts/$ARGUMENTS/prd.md`
+- `.beads/artifacts/$ARGUMENTS/plan.md` (if exists)
+- `.beads/artifacts/$ARGUMENTS/progress.txt` (if exists)
+- `.beads/artifacts/$ARGUMENTS/research.md` (if exists)
+
+## Phase 5: Check Staleness
+
+If handoff is more than 3 days old:
+
+```bash
+git log --oneline -10
+```
+
+Check if significant changes happened on main. If so, consider rebasing. Don't blindly follow an outdated plan — verify it still makes sense.
+
+## Phase 6: Continue
+
+```bash
+br update $ARGUMENTS --status in_progress
+```
+
+Report:
+
+1. Branch and commit
+2. Handoff age
+3. Progress (completed/remaining tasks)
+4. Next action (from handoff or PRD)
+
+Then continue with `/ship $ARGUMENTS` or `/plan $ARGUMENTS` as appropriate.

package/baseline/command/review-codebase.md

@@ -0,0 +1,131 @@
+---
+description: Review code for quality, security, and compliance
+argument-hint: "[path|bead-id|pr-number|'all'] [--quick|--thorough]"
+agent: review
+---
+
+# Review: $ARGUMENTS
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "requesting-code-review" });
+```
+
+## Determine Input Type
+
+| Input Type            | Detection                    | Action                     |
+| --------------------- | ---------------------------- | -------------------------- |
+| No arguments          | Default                      | Review uncommitted changes |
+| Commit hash (40-char) | SHA pattern                  | `git show <hash>`          |
+| Branch name           | String, not matching above   | `git diff main...HEAD`     |
+| PR URL/number         | Contains "github.com" or "#" | `gh pr diff`               |
+
+## Before You Review
+
+- **Be certain**: Only flag issues you can verify with tools
+- **Don't invent problems**: If an edge case isn't specified, don't flag it
+- **Don't be a zealot about style**: Unless it violates project conventions, don't flag
+- **Review the changes**: Don't review pre-existing code that wasn't modified
+- **Investigate first**: If unsure, use explore/scout agents before flagging
+
+## Available Tools
+
+| Tool         | Use When                                |
+| ------------ | --------------------------------------- |
+| `explore`    | Finding patterns in codebase, prior art |
+| `scout`      | External research, best practices       |
+| `lsp`        | Finding symbol definitions, references  |
+| `grep`       | Finding code patterns                   |
+| `codesearch` | Real-world usage examples               |
+
+## Phase 1: Gather Context
+
+```bash
+git status --short
+git diff --cached  # staged
+git diff           # unstaged
+```
+
+For each changed file:
+
+- Read the full file to understand context
+- Don't rely on diff alone — code that looks wrong in isolation may be correct
+
+If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
+
+## Phase 2: Determine Scope
+
+| Input                    | Scope                 | How to Get Code           |
+| ------------------------ | --------------------- | ------------------------- |
+| File/directory path      | That path only        | `read` or `glob` + `read` |
+| Bead ID (e.g., `br-123`) | Implementation vs PRD | `br show` then `git diff` |
+| PR number (e.g., `#45`)  | PR changes            | `gh pr diff 45`           |
+| `all` or empty           | Recent changes        | `git diff main...HEAD`    |
+
+If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
+
+## Phase 2: Automated Checks
+
+Detect project type and run the appropriate checks in parallel:
+
+| 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.
+
+Also scan for common issues appropriate to the detected language:
+
+- Debug statements (`console.log`, `print()`, `println!`, `fmt.Println`)
+- Loose typing (`any` in TypeScript, `type: ignore` in Python)
+- `TODO|FIXME|HACK` markers
+- Hardcoded secrets patterns
+
+## Phase 3: Manual Review
+
+Review each category:
+
+| Category            | Focus                                                                   |
+| ------------------- | ----------------------------------------------------------------------- |
+| **Security**        | Auth checks, input validation, no secrets in code, injection prevention |
+| **Performance**     | N+1 queries, unbounded loops, missing pagination, hot path ops          |
+| **Maintainability** | Complexity, DRY violations, dead code, naming clarity                   |
+| **Error Handling**  | Async error handling, error context, sanitized user errors              |
+| **Testing**         | Coverage on changed code, behavior tests, edge cases                    |
+| **Type Safety**     | No unjustified `any`, null handling, explicit return types              |
+
+**Depth levels:**
+
+- `--quick`: Automated checks + skim, critical issues only
+- Default: Full automated + manual review
+- `--thorough`: Deep analysis of all categories
+
+## Phase 4: Report
+
+Group findings by severity:
+
+- **Critical** (must fix before merge): with file:line, issue, fix
+- **Important** (should fix): with file:line, issue, fix
+- **Minor** (nice to have): with file:line, suggestion
+
+Include:
+
+1. Summary metrics (files reviewed, issues by severity)
+2. Strengths (what's done well, with file:line)
+3. Verdict: Ready to merge / With fixes / No
+4. Reasoning (1-2 sentences)
+
+Record significant findings with `observation()`.
+
+## Related Commands
+
+| Need                | Command        |
+| ------------------- | -------------- |
+| Ship after review   | `/ship <id>`   |
+| Verify completeness | `/verify <id>` |
+| Check status        | `/status`      |

package/baseline/command/ship.md

@@ -0,0 +1,342 @@
+---
+description: Ship a bead - implement PRD tasks, verify, review, close
+argument-hint: "<bead-id>"
+agent: build
+---
+
+# Ship: $ARGUMENTS
+
+Execute PRD tasks, verify each passes, run review, close the bead.
+
+> **Workflow:** `/create` → `/start <id>` → **`/ship <id>`**
+>
+> ⛔ Bead MUST be `in_progress` with `prd.md`. Run `/start` first if not.
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "verification-before-completion" });
+```
+
+## Determine Input Type
+
+| Input Type | Detection                   | Action                     |
+| ---------- | --------------------------- | -------------------------- |
+| Bead ID    | Matches `br-xxx` or numeric | Ship that bead             |
+| Path       | File/directory path         | Not supported for ship     |
+| `all`      | Keyword                     | Ship all in_progress beads |
+
+## Before You Ship
+
+- **Be certain**: Only ship if all tasks pass verification
+- **Don't skip gates**: Build, test, lint, typecheck are non-negotiable
+- **Run the review**: Always spawn review agent before closing
+- **Verify goals**: Tasks completing ≠ goals achieved (use goal-backward verification)
+- **Commit before close**: Per-task commits required, don't ship without git history
+- **Ask before closing**: Never close bead without user confirmation
+
+## Available Tools
+
+| Tool      | Use When                                  |
+| --------- | ----------------------------------------- |
+| `explore` | Finding patterns in codebase, prior art   |
+| `scout`   | External research, best practices         |
+| `lsp`     | Finding symbol definitions, references    |
+| `grep`    | Finding code patterns                     |
+| `task`    | Spawning subagents for parallel execution |
+
+## Phase 1: Guards
+
+```bash
+br show $ARGUMENTS
+```
+
+Verify:
+
+- Bead status is `in_progress` (if not, tell user to run `/start $ARGUMENTS`)
+- `.beads/artifacts/$ARGUMENTS/prd.md` exists (if not, tell user to run `/create` first)
+
+Check what artifacts exist:
+
+```bash
+ls .beads/artifacts/$ARGUMENTS/
+```
+
+## Phase 2: Route to Execution
+
+| Artifact exists | Action                                                   |
+| --------------- | -------------------------------------------------------- |
+| `plan.md`       | Load `executing-plans` skill, follow its batch process   |
+| `prd.json`      | Proceed to PRD task loop below                           |
+| Only `prd.md`   | Load `prd-task` skill to create `prd.json`, then proceed |
+
+## Phase 3: Wave-Based Execution
+
+If `plan.md` exists with dependency graph:
+
+1. **Load skill:** `skill({ name: "executing-plans" })`
+2. **Parse waves** from dependency graph section
+3. **Execute wave-by-wave:**
+   - Single-task wave → execute directly (no subagent overhead)
+   - Multi-task wave → dispatch parallel `task({ subagent_type: "general" })` subagents, one per task
+4. **Review after each wave** — run verification gates, report, wait for feedback
+5. **Continue** until all waves complete
+
+**Parallel safety:** Only tasks within same wave run in parallel. Tasks must NOT share files. Tasks in Wave N+1 wait for Wave N.
+
+### Phase 3A: PRD Task Loop (Sequential Fallback)
+
+For each task (wave-based or sequential fallback):
+
+1. **Read** the task description, verification steps, and affected files
+2. **Read** the affected files before editing
+3. **Implement** the changes — stay within the task's `files` list
+4. **Handle Deviations:** Apply deviation rules 1-4 as discovered
+5. **Checkpoint Protocol:** If task has `checkpoint:*`, stop and request user input
+6. **Verify** — run each verification step from the task
+7. **If verification fails**, fix and retry (max 2 attempts per task)
+8. **Commit** — per-task commit (see below)
+9. **Mark** `passes: true` in `prd.json`
+10. **Append** progress to `.beads/artifacts/$ARGUMENTS/progress.txt`
+
+### Checkpoint Protocol
+
+When task has `checkpoint:*` type:
+
+| Type                      | Action                                                     |
+| ------------------------- | ---------------------------------------------------------- |
+| `checkpoint:human-verify` | Execute automation first, then pause for user verification |
+| `checkpoint:decision`     | Present options, wait for selection                        |
+| `checkpoint:human-action` | Request specific action with verification command          |
+
+**Automation-first:** If verification CAN be automated, MUST automate it before requesting human check.
+
+**Checkpoint return format:**
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [human-verify | decision | human-action]
+**Progress:** X/Y tasks complete
+
+### Completed
+
+| Task | Commit | Status |
+| ---- | ------ | ------ |
+| [N]  | [hash] | [✓/✗]  |
+
+### Current Task
+
+**Task:** [name]
+**Blocked by:** [specific blocker]
+
+### Awaiting
+
+[What user needs to do/provide]
+```
+
+### TDD Execution Flow
+
+When task specifies TDD:
+
+**RED Phase:**
+
+1. Create test file with failing test
+2. Run test → MUST fail
+3. Commit: `test: add failing test for [feature]`
+
+**GREEN Phase:**
+
+1. Write minimal code to make test pass
+2. Run test → MUST pass
+3. Commit: `feat: implement [feature]`
+
+**REFACTOR Phase:** (if needed)
+
+1. Clean up code
+2. Run tests → MUST still pass
+3. Commit if changes: `refactor: clean up [feature]`
+
+### Task Commit Protocol
+
+After each task completes (verification passed):
+
+1. **Check modified files:** `git status --short`
+2. **Stage individually** (NEVER `git add .`):
+   ```bash
+   git add src/specific/file.ts
+   git add tests/file.test.ts
+   ```
+3. **Commit with type prefix:**
+
+   ```bash
+   git commit -m "feat(bead-$ARGUMENTS): [task description]
+
+   - [key change 1]
+   - [key change 2]"
+   ```
+
+4. **Record hash** in progress log
+
+**Commit types:**
+| Type | Use For |
+|------|---------|
+| `feat` | New feature, endpoint, component |
+| `fix` | Bug fix, error correction |
+| `test` | Test-only changes (TDD RED phase) |
+| `refactor` | Code cleanup, no behavior change |
+| `chore` | Config, tooling, dependencies |
+
+### Stop Conditions
+
+- Verification fails 2x on same task → stop, report blocker
+- Blocked by unfinished dependency → stop, report which one
+- Modifying files outside task scope → stop, ask user
+- Rule 4 deviation encountered → stop, present options
+
+## Phase 4: Verification
+
+Follow the [Verification Protocol](../skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md):
+
+- Use **full mode** (shipping requires all gates)
+- All 4 gates must pass before proceeding to commit/push
+- Also run PRD `Verify:` commands
+
+## Phase 6: Review
+
+Load and run 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 rev-parse HEAD~1)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+Fill placeholders:
+
+- `{WHAT_WAS_IMPLEMENTED}`: bead title + brief summary of what changed
+- `{PLAN_OR_REQUIREMENTS}`: `.beads/artifacts/$ARGUMENTS/prd.md`
+- `{BASE_SHA}` / `{HEAD_SHA}`: from above
+
+Wait for all 5 agents to return. Synthesize findings.
+
+**Auto-fix rule:**
+
+- Critical issues → fix inline, re-run Phase 4 verification, continue
+- Important issues → fix inline, continue
+- Minor issues → add to bead comments, note for `/compound` step
+
+If review finds critical issues that require architectural decisions → stop → present options to user.
+
+### Goal-Backward Verification (if plan.md exists)
+
+Verify that tasks completed ≠ goals achieved:
+
+**Three-Level Verification:**
+
+| Level              | Check                  | Command/Action                                                    |
+| ------------------ | ---------------------- | ----------------------------------------------------------------- |
+| **1: Exists**      | File is present        | `ls path/to/file.ts`                                              |
+| **2: Substantive** | Not a stub/placeholder | `grep -v "TODO\|FIXME\|return null\|placeholder" path/to/file.ts` |
+| **3: Wired**       | Connected and used     | `grep -r "import.*ComponentName" src/`                            |
+
+**Key Link Verification:**
+
+- Component → API: `grep -E "fetch.*api/|axios" Component.tsx`
+- API → Database: `grep -E "prisma\.|db\." route.ts`
+- Form → Handler: `grep "onSubmit" Component.tsx`
+- State → Render: `grep "{stateVar}" Component.tsx`
+
+**Stub Detection:**
+Red flags indicating incomplete implementation:
+
+```javascript
+return <div>Component</div>      // Placeholder
+return <div>{/* TODO */}</div>    // Empty
+return null                       // Empty
+onClick={() => {}}                // No-op handler
+fetch('/api/...')                 // No await, ignored
+return Response.json({ok: true})  // Static, not query result
+```
+
+If any artifact fails Level 2 or 3 → fix → re-verify.
+
+## Phase 7: Close
+
+Ask user before closing:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Close",
+      question: "All tasks pass, gates green, review clean. Close bead $ARGUMENTS?",
+      options: [
+        { label: "Yes, close it (Recommended)", description: "All checks passed" },
+        { label: "No, keep open", description: "Need more work" },
+      ],
+    },
+  ],
+});
+```
+
+If confirmed:
+
+```bash
+br close $ARGUMENTS --reason "Shipped: all PRD tasks pass, verification + review passed"
+br sync --flush-only
+```
+
+Record significant learnings with `/compound $ARGUMENTS` after closing.
+
+## Output
+
+Report:
+
+1. **Execution Summary:**
+   - Tasks completed/total
+   - Waves executed (if plan.md with waves)
+   - Deviations applied (Rules 1-3)
+   - Checkpoints encountered (human-verify/decision/human-action)
+   - Commits made
+
+2. **PRD Task Results:**
+   - Each task status (✓ pass, ✗ fail, ⏸ checkpoint)
+   - Files modified per task
+   - Commit hashes
+
+3. **Verification Gate Results:**
+   - Build: [pass/fail]
+   - Test: [pass/fail]
+   - Lint: [pass/fail]
+   - Typecheck: [pass/fail]
+
+4. **Goal-Backward Verification:**
+   - Artifacts verified: [N] exists, [M] substantive, [K] wired
+   - Key links checked: [pass/fail per link]
+   - Stubs detected: [N] (if any)
+
+5. **Review Summary:**
+   - Critical issues: [N]
+   - Important issues: [N]
+   - Minor issues: [N]
+   - Overall assessment: [pass/needs work]
+
+6. **Next Steps:**
+   - `/pr` to create pull request
+   - Manual commits if not already done
+   - Create follow-up beads for deferred work
+
+## Related Commands
+
+| Need        | Command       |
+| ----------- | ------------- |
+| Create spec | `/create`     |
+| Claim task  | `/start <id>` |
+| Create PR   | `/pr`         |