opencode-starterkit 1.0.1

package/baseline/skill/requesting-code-review/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: requesting-code-review
+description: Use when completing meaningful implementation work and needing a high-signal review pass before merge or release - dispatches scoped review agents, synthesizes findings, and routes follow-up actions by severity.
+version: 1.1.0
+tags: [workflow, code-quality, research]
+dependencies: []
+---
+
+# Requesting Code Review
+
+## Overview
+
+Request review when work is **potentially shippable** and you need fresh scrutiny before moving on.
+
+This skill is for **asking for review**, not blindly obeying reviewers. The review output is advisory until verified against the codebase.
+
+**Core principle:** tighter review packet → better findings. Fewer files + clearer requirements beats dumping a vague diff at five agents.
+
+## When to Use
+
+- After completing a feature, bugfix, or meaningful task batch
+- Before merging to main or creating a PR
+- Before release or after a risky refactor
+- When you need multiple review angles on the same implementation
+
+## When NOT to Use
+
+- During TDD RED phase or any intentionally failing state
+- When you only need a single targeted technical answer
+- When implementation is still obviously incomplete and review would be premature
+
+## Golden Path
+
+1. **Stabilize the work** — run the relevant verification first
+2. **Build a tight review packet** — what changed, requirements, diff range, notable risks
+3. **Choose review depth** — targeted, standard, or full multi-angle review
+4. **Dispatch review agents in parallel**
+5. **Deduplicate + synthesize findings**
+6. **Fix or push back with evidence**
+7. **Re-verify after changes**
+
+## Review Packet
+
+Before dispatching any reviewer, assemble a packet with:
+
+- **What changed** — 2-6 bullet summary
+- **Requirements / plan** — acceptance criteria or plan excerpt
+- **Diff range** — `BASE_SHA..HEAD_SHA`
+- **Risk hints** — auth, migrations, concurrency, data deletion, perf-sensitive path, etc.
+- **Verification already run** — typecheck/lint/test/build status
+
+Minimal packet template:
+
+```markdown
+What was implemented:
+
+- [change 1]
+- [change 2]
+
+Requirements:
+
+- [acceptance criterion 1]
+- [acceptance criterion 2]
+
+Diff:
+
+- BASE_SHA: {BASE_SHA}
+- HEAD_SHA: {HEAD_SHA}
+
+Already verified:
+
+- [command] — [result]
+
+Risk areas:
+
+- [auth | migrations | concurrency | performance | none]
+```
+
+## Review Depth Selection
+
+Choose the smallest review depth that still covers the risk.
+
+| Depth        | Use When                                    | Agents |
+| ------------ | ------------------------------------------- | ------ |
+| **targeted** | Small fix, one main risk, one area changed  | 1-2    |
+| **standard** | Typical feature/fix ready for merge         | 3      |
+| **full**     | Risky, cross-cutting, release-critical work | 5      |
+
+### Routing Rules
+
+- **targeted**: use 1-2 specific review prompts
+- **standard**: use security/correctness, tests/types, and completeness
+- **full**: use all 5 specialized review prompts
+
+Do **not** dispatch 5 reviewers by reflex for every tiny change. That produces noise, not rigor.
+
+## Review Scope Self-Check
+
+Before writing ANY review finding, the reviewer MUST ask:
+
+> **"Am I questioning APPROACH or DOCUMENTATION/CORRECTNESS?"**
+
+| Answer | Action |
+| --- | --- |
+| **APPROACH** — "I would have done it differently" | **Stay silent.** The approach was decided during planning. Review doesn't re-litigate design. |
+| **DOCUMENTATION** — "A new developer couldn't execute this" | **Raise it.** Missing file paths, vague acceptance criteria, assumed context. |
+| **CORRECTNESS** — "This will break at runtime" | **Raise it.** Bugs, security holes, type errors, logic flaws. |
+
+### Red Flags for Scope Creep
+
+- Suggesting alternative libraries or frameworks → **out of scope** (approach)
+- "I would rename this to..." without a concrete bug → **out of scope** (style preference)
+- "Consider adding feature X" that wasn't in requirements → **out of scope** (scope inflation)
+- "This could be more performant" without evidence of a real problem → **out of scope** (premature optimization)
+
+### What Reviewers SHOULD Flag
+
+- Missing error handling that will crash in production → **correctness**
+- Vague acceptance criteria that workers can't verify → **documentation**
+- Hardcoded values with no explanation → **documentation**
+- Missing file paths for tasks that require edits → **documentation**
+- "Use the existing pattern" without specifying which pattern → **documentation**
+- Security vulnerabilities (injection, auth bypass, secrets) → **correctness**
+
+Include this self-check instruction in EVERY review dispatch prompt to prevent bikeshedding.
+
+## Step 1: Get Git Context
+
+### Setup Checklist
+
+- [ ] Determine `BASE_SHA` and `HEAD_SHA`
+- [ ] Summarize requirements or link plan
+- [ ] Decide review depth
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+If work is still uncommitted, use the working tree review path and clearly say so in the review packet.
+
+## Step 2: Dispatch Reviewers in Parallel
+
+### A. Security + Correctness
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Security + correctness review",
+  prompt: `Review this implementation for real bugs in changed code only.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Security vulnerabilities (injection, auth bypass, secrets exposure, missing validation)
+- Logic errors, null/undefined access, incorrect guards
+- Broken async/error handling
+- Data integrity issues
+
+Rules:
+- Review only changed code
+- Read full changed files for context before flagging issues
+- Do not speculate; explain the concrete failure scenario
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references
+- brief reasoning for each finding`,
+});
+```
+
+### B. Performance + Architecture
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Performance + architecture review",
+  prompt: `Review this implementation for performance and architecture issues.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Obviously expensive loops / N+1 / repeated work
+- Over-engineering or abstraction without clear value
+- Coupling that will make maintenance painful
+- Missing use of existing abstractions/utilities
+
+Rules:
+- Flag only meaningful issues
+- Skip style-only comments unless they cause structural problems
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+### C. Type Safety + Test Quality
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Type safety + test review",
+  prompt: `Review this implementation for type safety and test quality.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Unsafe assertions, type holes, lossy casts
+- Missing coverage on important branches or edge cases
+- Tests that only prove mocks, not behavior
+- Tests that would still pass if implementation were wrong
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+### D. Conventions + Existing Patterns
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Conventions + patterns review",
+  prompt: `Review this implementation against existing codebase patterns.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+  git log --oneline -10
+
+Check for:
+- Divergence from existing code organization or naming
+- Reimplementation of existing utilities/helpers
+- Documentation drift where changed code no longer matches docs
+- New patterns that conflict with established ones
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+### E. Simplicity + Completeness
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Simplicity + completeness review",
+  prompt: `Review this implementation for completeness and unnecessary complexity.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Missing requirements or acceptance criteria
+- Dead code, TODOs, unreachable branches
+- Complexity that can be deleted without losing behavior
+- Behavior changes that appear unintentional
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+## Dispatch Matrix
+
+| Depth        | Reviewers to Run             |
+| ------------ | ---------------------------- |
+| **targeted** | Choose the 1-2 most relevant |
+| **standard** | A + C + E                    |
+| **full**     | A + B + C + D + E            |
+
+## Step 3: Synthesize Findings
+
+### Synthesis Checklist
+
+- [ ] Merge duplicate findings across reviewers
+- [ ] Keep the strongest explanation when multiple reviewers report same issue
+- [ ] Separate real blockers from optional improvements
+- [ ] Mark disputed / uncertain findings explicitly
+
+Output format:
+
+```markdown
+## Review Summary
+
+**Review depth:** [targeted | standard | full]
+**Agents run:** [N]
+**Critical:** [N]
+**Important:** [N]
+**Minor:** [N]
+
+### Critical Issues
+
+- `path/to/file.ts:123` — [issue + why it breaks]
+
+### Important Issues
+
+- `path/to/file.ts:123` — [issue]
+
+### Minor Issues
+
+- `path/to/file.ts:123` — [optional improvement]
+
+### Disputed / Needs Verification
+
+- [finding that may be wrong, plus what evidence would confirm it]
+
+### Assessment
+
+- [ ] Ready to proceed
+- [ ] Fix required first
+```
+
+## Step 4: Act on Findings
+
+### Remediation Checklist
+
+- [ ] Fix all Critical findings before proceeding
+- [ ] Fix Important findings in the current branch unless consciously deferred
+- [ ] Record deferred Minor findings somewhere durable
+- [ ] Push back on wrong findings with code/tests, not opinion
+
+| Severity      | Action                                        |
+| ------------- | --------------------------------------------- |
+| **Critical**  | Fix immediately before any further work       |
+| **Important** | Fix now or explicitly defer with reason       |
+| **Minor**     | Track for later if not worth immediate change |
+
+If a finding looks wrong, verify it against the codebase before changing anything.
+
+## Step 5: Re-verify
+
+After fixing review findings, re-run the relevant verification commands.
+
+At minimum, use the commands appropriate for the project toolchain:
+
+- `npm run typecheck`
+- `npm run lint`
+- `npm test`
+- `npm run build` (if release/build-sensitive)
+
+Do not claim review is resolved until fresh verification passes.
+
+## Placeholders Reference
+
+| Placeholder       | What to fill                     |
+| ----------------- | -------------------------------- |
+| `{REVIEW_PACKET}` | Tight review packet with context |
+| `{BASE_SHA}`      | Starting commit SHA              |
+| `{HEAD_SHA}`      | Ending commit SHA                |
+
+## Integration with Workflows
+
+| Command | When review runs                     |
+| ------- | ------------------------------------ |
+| `/ship` | After work is complete and verified  |
+| `/pr`   | Before pushing or opening PR         |
+| `/lfg`  | Between execution and compound steps |
+
+## Common Mistakes
+
+- Running 5 reviewers on a tiny one-file fix with no real risk
+- Sending vague prompts with no requirements or verification status
+- Treating reviewer output as automatically correct
+- Failing to deduplicate repeated findings
+- Skipping re-verification after review fixes
+
+## After Review: Compound
+
+Run `/compound` after resolving review findings to capture:
+
+- Patterns review caught that should be prevented earlier
+- False positives that should not be repeated
+- Newly discovered codebase conventions
+
+That turns review from a gate into a feedback loop.

package/baseline/skill/requesting-code-review/review.md

@@ -0,0 +1,160 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness.
+
+**Your task:**
+
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Assess production readiness
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_REFERENCE}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+
+[What's well done? Be specific.]
+
+### Issues
+
+#### Critical (Must Fix)
+
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Recommendations
+
+[Improvements for code quality, architecture, or process]
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+
+- Categorize by actual severity (not everything is Critical)
+- Be specific (file:line, not vague)
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+
+**DON'T:**
+
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```