@kodrunhq/opencode-autopilot 1.4.0 → 1.5.0

package/assets/commands/brainstorm.md

@@ -0,0 +1,7 @@
+---
+description: Start a brainstorming session with Socratic design refinement
+---
+
+Use the brainstorming skill to explore the topic through Socratic questioning. Ask clarifying questions, explore alternatives, generate at least 3 distinct approaches, and present a structured design recommendation.
+
+$ARGUMENTS

package/assets/commands/stocktake.md

@@ -0,0 +1,7 @@
+---
+description: Audit all installed skills, commands, and agents with optional lint validation
+---
+
+Invoke the `oc_stocktake` tool to audit all installed assets. Pass any arguments as the lint option.
+
+$ARGUMENTS

package/assets/commands/tdd.md

@@ -0,0 +1,7 @@
+---
+description: Implement a feature using strict RED-GREEN-REFACTOR TDD methodology
+---
+
+Use the tdd-workflow skill to implement the feature following strict RED-GREEN-REFACTOR. Write the failing test first (RED), implement minimally to pass (GREEN), then clean up (REFACTOR).
+
+$ARGUMENTS

package/assets/commands/update-docs.md

@@ -0,0 +1,7 @@
+---
+description: Detect documentation affected by recent code changes and suggest updates
+---
+
+Invoke the `oc_update_docs` tool to analyze recent code changes and identify documentation that may need updating.
+
+$ARGUMENTS

package/assets/commands/write-plan.md

@@ -0,0 +1,7 @@
+---
+description: Decompose a feature into a structured implementation plan with tasks and dependency waves
+---
+
+Use the plan-writing skill to decompose the feature into bite-sized tasks with exact file paths, dependency waves, and verification criteria for each task.
+
+$ARGUMENTS

package/assets/skills/brainstorming/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: brainstorming
+description: Socratic design refinement methodology for exploring ideas through structured divergent and convergent thinking phases
+stacks: []
+requires: []
+---
+
+# Brainstorming
+
+Structured Socratic design refinement for exploring ideas, challenging assumptions, and arriving at well-reasoned implementation plans. This skill guides you through a 5-phase process that moves from problem clarification through divergent exploration to convergent evaluation, synthesis, and actionable output.
+
+Apply this skill whenever you need to explore design space before committing to an approach. The methodology prevents premature convergence (jumping to the first solution) and analysis paralysis (exploring forever without deciding).
+
+## When to Use
+
+**Activate this skill when:**
+
+- Designing a new feature with multiple possible approaches
+- Making architectural decisions with significant trade-offs
+- The user gives vague or open-ended requirements that need refinement
+- Exploring creative solutions to a technical problem
+- Evaluating whether to build, buy, or adapt an existing solution
+- Refactoring a system with multiple viable restructuring strategies
+- The team disagrees on the right approach and needs structured evaluation
+
+**Do NOT use when:**
+
+- The implementation path is obvious and well-defined
+- The task is a straightforward bug fix with a clear root cause
+- Requirements are precise and leave no design decisions
+- Time pressure demands immediate action over exploration
+- The change is trivial (rename, config tweak, dependency bump)
+
+## The Brainstorming Process
+
+The process has five sequential phases. Each phase has a clear purpose and a defined output. Do not skip phases -- the discipline of following all five is what prevents the anti-patterns listed below.
+
+### Phase 1: Clarify the Problem
+
+**Purpose:** Understand the real problem before generating solutions. Most bad designs trace back to solving the wrong problem.
+
+**Process:**
+
+1. Ask 3-5 Socratic questions to challenge assumptions and surface the actual need
+2. Each question should probe a different dimension: user need, constraints, scope, success criteria, risk
+3. Do NOT propose solutions in this phase -- only ask questions
+4. Synthesize answers into a one-paragraph problem statement
+
+**Socratic Questions to Ask:**
+
+- "What problem does this solve for the user?" -- Forces focus on user value, not technical elegance
+- "What happens if we don't build this?" -- Tests whether the problem is real or imagined
+- "What's the simplest version that delivers value?" -- Prevents scope creep from the start
+- "Who else has solved this problem?" -- Avoids reinventing the wheel
+- "What are we assuming that might not be true?" -- Surfaces hidden assumptions
+
+**Output:** A clear problem statement that the user confirms is accurate. If the user cannot confirm, ask more questions.
+
+**Time box:** 5-10 minutes. If you cannot clarify the problem in 10 minutes, the scope is too large -- split it.
+
+### Phase 2: Divergent Exploration
+
+**Purpose:** Generate multiple distinct approaches without evaluating them. Quantity over quality in this phase.
+
+**Process:**
+
+1. Generate 3-5 distinct approaches to the clarified problem
+2. Each approach must be genuinely different -- not variations of the same idea
+3. For each approach, document:
+   - **Name:** A short, memorable label (2-4 words)
+   - **Description:** One sentence explaining the core idea
+   - **Key trade-off:** The main thing you give up with this approach
+   - **Effort estimate:** Small (hours), Medium (days), or Large (weeks)
+4. Include at least one "wild card" approach that challenges a fundamental assumption
+5. Do NOT evaluate or rank approaches in this phase
+
+**Output:** A numbered list of 3-5 approaches with name, description, trade-off, and effort.
+
+**Time box:** 10-15 minutes. If you cannot generate 3 approaches, the problem definition is too narrow -- go back to Phase 1 and broaden it.
+
+**Forcing creativity:** If all approaches look similar, try these prompts:
+- "What if we had unlimited time/budget?"
+- "What if we had to ship in one hour?"
+- "What if we used a completely different technology?"
+- "What would a competitor build?"
+- "What if we solved the opposite problem?"
+
+### Phase 3: Convergent Evaluation
+
+**Purpose:** Systematically assess each approach against consistent criteria.
+
+**Process:**
+
+1. For each approach from Phase 2, evaluate three dimensions:
+   - **Feasibility:** Can we build this with the current stack, team, and timeline? (LOW / MEDIUM / HIGH)
+   - **Alignment:** Does this solve the clarified problem from Phase 1? (LOW / MEDIUM / HIGH)
+   - **Risk:** What could go wrong? How likely is failure? (LOW / MEDIUM / HIGH risk)
+2. For each dimension, write one sentence justifying the rating
+3. Identify any approach that scores LOW on Alignment -- eliminate it immediately
+4. Flag any approach with HIGH Risk for deeper analysis in Phase 4
+
+**Output:** A comparison table with ratings and justifications for each approach.
+
+**Evaluation format:**
+
+```
+| Approach | Feasibility | Alignment | Risk | Notes |
+|----------|-------------|-----------|------|-------|
+| Name 1   | HIGH        | HIGH      | LOW  | ...   |
+| Name 2   | MEDIUM      | HIGH      | MEDIUM | ... |
+| Name 3   | HIGH        | LOW       | LOW  | Eliminated: doesn't solve core problem |
+```
+
+**Time box:** 10-15 minutes. If evaluation takes longer, you have too many approaches -- drop the weakest two.
+
+### Phase 4: Synthesis
+
+**Purpose:** Select the best approach and refine it. Combine strengths from multiple approaches if possible.
+
+**Process:**
+
+1. Recommend the top approach based on Phase 3 evaluation
+2. State the rationale in 2-3 sentences: why this approach, why not the alternatives
+3. If two approaches have complementary strengths, propose a hybrid that combines the best of both
+4. Document rejected approaches and why -- this becomes decision log material
+5. Identify risks from Phase 3 and propose specific mitigations
+
+**Output:**
+
+- Selected approach with rationale
+- Risk mitigations (1-2 sentences each)
+- Decision log entry: what was decided, what was rejected, why
+
+**Decision log format:**
+
+```
+## Decision: [Topic]
+**Date:** [date]
+**Selected:** [approach name]
+**Rationale:** [2-3 sentences]
+**Rejected alternatives:**
+- [Approach 2]: [reason for rejection]
+- [Approach 3]: [reason for rejection]
+**Risks and mitigations:**
+- [Risk 1]: [mitigation]
+```
+
+### Phase 5: Action Items
+
+**Purpose:** Convert the chosen approach into concrete, executable next steps.
+
+**Process:**
+
+1. Break the selected approach into 3-7 discrete tasks
+2. Each task must be independently completable and verifiable
+3. For each task, specify:
+   - **What:** One sentence describing the deliverable
+   - **Files:** Which files to create or modify
+   - **Tests:** What test(s) verify this task is done
+   - **Dependencies:** Which other tasks must complete first
+4. Order tasks by dependency (independent tasks first)
+5. Identify the first task to start with -- it should be the smallest, lowest-risk task that validates the approach
+
+**Output:** An ordered task list ready for execution.
+
+**Task format:**
+
+```
+1. [Task name]
+   - What: [deliverable description]
+   - Files: [file paths]
+   - Tests: [verification approach]
+   - Depends on: [task numbers or "none"]
+```
+
+## Socratic Question Templates
+
+Use these categorized questions when Phase 1 needs more depth.
+
+### Requirements Questions
+
+- "Who is the primary user of this feature?"
+- "What does success look like from the user's perspective?"
+- "What is the user doing today without this feature?"
+- "What is the minimum viable version that delivers value?"
+- "Are there existing patterns in the codebase we should follow?"
+
+### Architecture Questions
+
+- "What are the scaling constraints we need to respect?"
+- "Where are the system boundaries?"
+- "What data flows through this feature?"
+- "Which existing modules does this touch?"
+- "What's the deployment story -- does this need to be backwards compatible?"
+
+### Risk Questions
+
+- "What's the worst failure mode?"
+- "What do we not know yet?"
+- "What assumptions are we making about the user's environment?"
+- "What happens when this feature interacts with [adjacent system]?"
+- "If this fails in production, how do we detect and recover?"
+
+### Scope Questions
+
+- "Is this one feature or multiple features bundled together?"
+- "What's explicitly out of scope?"
+- "Can we ship this incrementally, or is it all-or-nothing?"
+- "What's the maintenance cost after we ship?"
+
+## Anti-Pattern Catalog
+
+### Anti-Pattern: Premature Convergence
+
+**What goes wrong:** Jumping to the first reasonable solution without exploring alternatives. The "obvious" approach often has hidden trade-offs that only surface during implementation.
+
+**Signs:** Phase 2 produces only one approach. The "exploration" is really just elaborating on a pre-decided solution.
+
+**Instead:** Force yourself to generate at least 3 genuinely different approaches before evaluating any of them. Use the creativity prompts from Phase 2 if stuck.
+
+### Anti-Pattern: Analysis Paralysis
+
+**What goes wrong:** Exploring endlessly without converging. Every approach spawns more questions. The brainstorming session becomes a research project.
+
+**Signs:** Phase 2 generates 8+ approaches. Phase 3 evaluation raises more questions than it answers. The session exceeds 45 minutes with no decision.
+
+**Instead:** Time-box each phase strictly. After Phase 3, force a decision -- even if imperfect. A good decision now beats a perfect decision never.
+
+### Anti-Pattern: Group Think
+
+**What goes wrong:** All generated approaches are variations of the same fundamental idea. No real diversity in the solution space.
+
+**Signs:** Every approach uses the same technology, the same architecture, the same data model. The "wild card" approach isn't actually wild.
+
+**Instead:** Deliberately propose at least one approach that breaks a core assumption. Try "What if we used no database?" or "What if the user did this manually?" to force divergent thinking.
+
+### Anti-Pattern: Scope Creep
+
+**What goes wrong:** Brainstorming expands beyond the original problem. New features, edge cases, and "nice to haves" accumulate until the scope is unrecognizable.
+
+**Signs:** Phase 5 produces 15+ tasks. The action items address problems not mentioned in Phase 1. The effort estimate doubled during brainstorming.
+
+**Instead:** Revisit the Phase 1 problem statement after each phase. If a new idea doesn't serve the clarified problem, log it for future consideration but exclude it from the current session.
+
+### Anti-Pattern: Solutioning Before Clarifying
+
+**What goes wrong:** Skipping Phase 1 and jumping straight to generating approaches. Without a clear problem statement, the approaches solve different problems.
+
+**Signs:** Phase 2 approaches are hard to compare because each one addresses a slightly different interpretation of the problem.
+
+**Instead:** Never skip Phase 1. Invest the time to get a confirmed problem statement before generating any solutions.
+
+## Integration with Our Tools
+
+After completing Phase 5 (Action Items), use the following tools to continue:
+
+- **Plan writing skill:** Convert Phase 5 action items into a formal execution plan with file paths, verification steps, and dependency ordering
+- **`oc_orchestrate`:** For autonomous execution of the chosen approach -- pass the Phase 5 task list as the plan input
+- **`oc_review`:** After implementing any Phase 5 task, invoke a review to catch issues early
+- **Decision log:** The Phase 4 synthesis output is a ready-made decision log entry -- save it for future reference
+
+## Failure Modes
+
+### Unclear Problem Definition
+
+**Symptom:** Phase 1 ends but you still cannot explain the problem in one sentence.
+
+**Recovery:** Ask the user directly: "Can you describe the problem without mentioning any solution?" If they cannot, the problem is not well-defined enough for brainstorming. Help them define the problem first.
+
+### All Approaches Are Variations of the Same Idea
+
+**Symptom:** Phase 2 produces approaches that differ only in implementation details, not in fundamental strategy.
+
+**Recovery:** Add artificial constraints to force creativity:
+- "What if we couldn't use [the obvious technology]?"
+- "What if the budget was 10x smaller / larger?"
+- "What would a team with completely different expertise build?"
+
+### No Approach Feels Feasible
+
+**Symptom:** Phase 3 evaluation rates all approaches LOW on Feasibility.
+
+**Recovery:** The problem scope is too large. Go back to Phase 1 and split the problem into smaller sub-problems. Brainstorm each sub-problem independently.
+
+### Brainstorming Produces Consensus But Wrong Direction
+
+**Symptom:** The selected approach from Phase 4 fails during implementation.
+
+**Recovery:** This is expected and normal. Return to Phase 3 with the failure as new information. Re-evaluate the remaining approaches. The rejected alternatives from the decision log become the starting point for the next round.
+
+### User Disengages During the Process
+
+**Symptom:** The user stops responding to Socratic questions or says "just pick one."
+
+**Recovery:** Respect the signal. Compress: state your top recommendation with a one-sentence rationale. Ask for a yes/no confirmation. Skip to Phase 5 with the recommended approach.

package/assets/skills/code-review/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: code-review
+description: Structured methodology for requesting and receiving code reviews -- what to check, how to provide feedback, and how to respond to review comments
+stacks: []
+requires:
+  - coding-standards
+---
+
+# Code Review
+
+A structured methodology for high-quality code reviews. Whether you are requesting a review, performing one, or responding to feedback, follow these guidelines to maximize the value of every review cycle.
+
+## When to Use
+
+- Before merging any pull request
+- After completing a feature or bug fix
+- When reviewing someone else's code
+- When `oc_review` flags issues that need human judgment
+- After refactoring sessions to catch unintended behavior changes
+
+## Requesting a Review
+
+A good review request sets the reviewer up for success. The less guessing a reviewer has to do, the better the feedback you get back.
+
+### Provide Context
+
+Every review request should include:
+
+- **What the change does** -- one sentence summary of the behavior change
+- **Why it is needed** -- link to the issue, user story, or design decision
+- **What alternatives were considered** -- and why this approach was chosen
+- **Testing done** -- what was tested, how, and what edge cases were covered
+
+### Highlight Risky Areas
+
+Call out areas where you are uncertain or where the change is particularly impactful:
+
+- "I am unsure about the error handling in auth.ts lines 40-60"
+- "The migration is irreversible -- please double-check the column drop"
+- "This changes the public API surface -- backward compatibility impact"
+
+### Keep PRs Small
+
+- Target under 300 lines of meaningful diff (exclude generated files, lockfiles, snapshots)
+- If a change is larger, split it into stacked PRs or a feature branch with incremental commits
+- Each PR should be independently reviewable and shippable
+- One concern per PR -- do not mix refactoring with feature work
+
+### Self-Review First
+
+Before requesting a review from others:
+
+1. Read through the entire diff yourself as if you were the reviewer
+2. Run `oc_review` for automated multi-agent analysis
+3. Check that tests pass and coverage is maintained
+4. Verify you have not left any TODO markers, debug logging, or commented-out code
+5. Use the coding-standards skill as a checklist for naming, structure, and error handling
+
+## Performing a Review
+
+Review in this order for maximum value. Architecture issues found early save the most rework.
+
+### 1. Architecture
+
+- Does the overall approach make sense for the problem being solved?
+- Are responsibilities properly separated between modules?
+- Does this introduce new patterns that conflict with existing conventions?
+- Are the right abstractions being used (not too many, not too few)?
+- Will this scale to handle the expected load or data volume?
+
+### 2. Correctness
+
+- Does the code do what it claims to do?
+- Are edge cases handled? (null inputs, empty collections, boundary values)
+- Are error paths covered? (network failures, invalid data, timeouts)
+- Is the logic correct for concurrent or async scenarios?
+- Are state transitions valid and complete?
+
+### 3. Security
+
+- Is all user input validated at the boundary? (Reference the coding-standards skill)
+- Are authentication and authorization checks in place?
+- Are secrets handled properly? (no hardcoding, no logging)
+- Is output properly escaped to prevent XSS?
+- Are SQL queries parameterized?
+- Is CSRF protection enabled for state-changing endpoints?
+
+### 4. Performance
+
+- Any N+1 query patterns? (fetching in a loop instead of batching)
+- Unbounded loops or recursion? (missing limits, no pagination)
+- Missing database indexes for frequent queries?
+- Unnecessary memory allocations? (large objects created in hot paths)
+- Could any expensive operations be cached or deferred?
+
+### 5. Readability
+
+- Are names descriptive and intention-revealing?
+- Are functions small and focused (under 50 lines)?
+- Are files focused on a single concern (under 400 lines)?
+- Is the nesting depth reasonable (4 levels or less)?
+- Would a future developer understand this without asking the author?
+
+### 6. Testing
+
+- Do tests exist for all new behavior?
+- Do existing tests still pass?
+- Are edge cases tested (not just the happy path)?
+- Are tests independent and deterministic (no flaky tests)?
+- Is the test structure clear? (arrange-act-assert)
+
+## Providing Feedback
+
+### Use Severity Levels
+
+Every review comment should be tagged with a severity so the author can prioritize:
+
+- **CRITICAL** -- Must fix before merge. Bugs, security issues, data loss risks.
+- **HIGH** -- Should fix before merge. Missing error handling, performance issues, incorrect behavior in edge cases.
+- **MEDIUM** -- Consider fixing. Code quality improvements, better naming, minor refactoring opportunities.
+- **LOW** -- Nit. Style preferences, optional improvements, suggestions for future work.
+
+### Be Specific
+
+Bad: "This is confusing."
+Good: "The variable `data` on line 42 of user-service.ts does not convey what it holds. Consider renaming to `activeUserRecords` to match the query filter on line 38."
+
+Every comment should include:
+
+- The file and line (or line range)
+- What the issue is
+- A suggested fix or alternative approach
+
+### Be Constructive
+
+- Explain WHY something is a problem, not just WHAT is wrong
+- Offer alternatives when pointing out issues
+- Acknowledge good work -- positive feedback reinforces good patterns
+- Use "we" language -- "We could improve this by..." not "You did this wrong"
+- Ask questions when unsure -- "Is there a reason this is not using the existing helper?"
+
+## Responding to Review Comments
+
+### Address Every Comment
+
+- Fix the issue, or explain why the current approach is intentional
+- Never ignore a review comment without responding
+- If you disagree, explain your reasoning -- the reviewer may have missed context
+- If you agree but want to defer, create a follow-up issue and link it
+
+### Stay Professional
+
+- Do not take feedback personally -- reviews are about code, not about you
+- Ask for clarification if a comment is unclear
+- Thank reviewers for catching issues -- they saved you from a production bug
+- If a discussion gets long, move to a synchronous conversation (call, pair session)
+
+### Mark Resolved Comments
+
+- After addressing a comment, mark it as resolved
+- If the fix is in a follow-up commit, reference the commit hash
+- Do not resolve comments that were not actually addressed
+
+## Integration with Our Tools
+
+### Automated Review with oc_review
+
+Use `oc_review` for automated multi-agent code review. The review engine runs up to 21 specialist agents (universal + stack-gated) covering:
+
+- Logic correctness and edge cases
+- Security vulnerabilities and input validation
+- Code quality and maintainability
+- Testing completeness and test quality
+- Performance and scalability concerns
+- Documentation and naming
+
+Automated review is a complement to human review, not a replacement. Use it for the mechanical checks so human reviewers can focus on architecture and design decisions.
+
+### Coding Standards Baseline
+
+Use the coding-standards skill as the shared baseline for quality checks. This ensures all reviewers apply the same standards for naming, file organization, error handling, immutability, and input validation.
+
+### Review Workflow
+
+The recommended workflow for any change:
+
+1. Self-review the diff
+2. Run `oc_review` for automated analysis
+3. Address any CRITICAL or HIGH findings from automated review
+4. Request human review with the context template above
+5. Address human review feedback
+6. Merge when all CRITICAL and HIGH items are resolved
+
+## Anti-Pattern Catalog
+
+### Anti-Pattern: Rubber-Stamp Reviews
+
+**What it looks like:** Approving a PR after a cursory glance, or approving without reading the diff at all.
+
+**Why it is harmful:** Defeats the entire purpose of code review. Bugs, security issues, and design problems ship to production uncaught.
+
+**Instead:** Spend at least 10 minutes per 100 lines of meaningful diff. If you do not have time for a thorough review, say so and let someone else review.
+
+### Anti-Pattern: Style-Only Reviews
+
+**What it looks like:** Only commenting on formatting, whitespace, and naming conventions while ignoring logic, architecture, and security.
+
+**Why it is harmful:** Misallocates review effort. Style issues are the least impactful category and can often be caught by linters.
+
+**Instead:** Focus on correctness and architecture first (items 1-4 in the review order). Save style comments for LOW severity nits at the end.
+
+### Anti-Pattern: Blocking on Nits
+
+**What it looks like:** Requesting changes or withholding approval for trivial style preferences (single-line formatting, import order, comment wording).
+
+**Why it is harmful:** Slows down delivery, creates frustration, and discourages submitting PRs. The cost of the delay exceeds the value of the nit fix.
+
+**Instead:** Approve the PR with suggestions for LOW items. The author can address them in a follow-up or not -- it is their call.
+
+### Anti-Pattern: Drive-By Reviews
+
+**What it looks like:** Leaving a single comment on a large PR without reviewing the rest, giving the impression the PR was reviewed.
+
+**Why it is harmful:** Creates false confidence that the code was reviewed when it was not.
+
+**Instead:** If you only have time for a partial review, say so explicitly: "I only reviewed the auth changes, not the database migration. Someone else should review that part."
+
+### Anti-Pattern: Review Ping-Pong
+
+**What it looks like:** Reviewer leaves one comment, author fixes it, reviewer finds a new issue, author fixes that, ad infinitum.
+
+**Why it is harmful:** Each round-trip adds latency. A thorough first review is faster than five rounds of incremental feedback.
+
+**Instead:** Review the entire PR in one pass. Leave all comments at once. If you spot a pattern issue, note it once and add "same issue applies to lines X, Y, Z."
+
+## Failure Modes
+
+- **Review takes too long:** The PR is too large. Split it into smaller PRs.
+- **Reviewer and author disagree:** Escalate to a tech lead or use an ADR (Architecture Decision Record) for design disagreements.
+- **Same issues keep appearing:** The team needs better shared standards. Update the coding-standards skill or add linter rules.
+- **Reviews feel adversarial:** Revisit the team's review culture. Reviews should feel collaborative, not combative.