opencodekit 0.20.5 → 0.20.7

package/dist/template/.opencode/skill/reflection-checkpoints/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: reflection-checkpoints
+description: >
+  Use when executing long-running commands (/ship, /lfg) to add self-assessment
+  checkpoints that detect scope drift, stalled progress, and premature completion claims.
+  Inspired by ByteRover's reflection prompt architecture.
+version: 1.0.0
+tags: [workflow, quality, autonomous]
+dependencies: [verification-before-completion]
+---
+
+# Reflection Checkpoints
+
+## When to Use
+
+- During `/ship` execution after completing 50%+ of tasks
+- During `/lfg` at each phase transition (Plan→Work→Review→Compound)
+- When a task takes significantly longer than estimated
+- When context usage exceeds 60% of budget
+
+## When NOT to Use
+
+- Simple, single-task work (< 3 tasks)
+- Pure research or exploration commands
+- When user explicitly requests fast execution without checkpoints
+
+## Overview
+
+Long-running autonomous execution drifts silently. By the time you notice, you've burned context on the wrong thing. Reflection checkpoints force self-assessment at critical moments — catching drift before it compounds.
+
+**Core principle:** Pause to assess, don't just assess to pause.
+
+## The Four Reflection Types
+
+### 1. Mid-Point Check
+
+**Trigger:** After completing ~50% of planned tasks (e.g., 3 of 6 tasks done)
+
+```
+## 🔍 Mid-Point Reflection
+
+**Progress:** [N/M] tasks complete
+**Context used:** ~[X]% estimated
+
+### Scope Check
+- [ ] Am I still solving the original problem?
+- [ ] Have I introduced any unplanned work?
+- [ ] Are remaining tasks still correctly scoped?
+
+### Quality Check
+- [ ] Do completed tasks actually work (not just "done")?
+- [ ] Any verification steps I deferred?
+- [ ] Any TODO/FIXME I left that needs addressing?
+
+### Efficiency Check
+- [ ] Am I spending context on the right things?
+- [ ] Should remaining tasks be parallelized?
+- [ ] Any tasks that should be deferred to a follow-up bead?
+
+**Assessment:** [On track / Drifting / Blocked]
+**Adjustment:** [None needed / Describe change]
+```
+
+### 2. Completion Check
+
+**Trigger:** Before claiming any task or phase is complete
+
+```
+## ✅ Completion Check
+
+**Claiming complete:** [task/phase name]
+
+### Evidence Audit
+- [ ] Verification command was run (not assumed)
+- [ ] Output confirms the claim (not inferred)
+- [ ] No stub patterns in modified files
+- [ ] Imports/exports are wired (not just declared)
+
+### Goal-Backward Check
+- [ ] Does this task achieve its stated end-state?
+- [ ] Would a user see the expected behavior?
+- [ ] If tested manually, would it work?
+
+**Verdict:** [Complete / Needs work: describe what]
+```
+
+### 3. Near-Limit Warning
+
+**Trigger:** When context usage exceeds ~70% or step count approaches limit
+
+```
+## ⚠️ Near-Limit Warning
+
+**Context pressure:** [High / Critical]
+**Remaining tasks:** [N]
+
+### Triage
+1. What MUST be done before stopping? [list critical tasks]
+2. What CAN be deferred? [list deferrable tasks]
+3. What should be handed off? [list with context needed]
+
+### Action
+- [ ] Compress completed work
+- [ ] Prioritize remaining tasks ruthlessly
+- [ ] Prepare handoff if needed
+
+**Decision:** [Continue (enough budget) / Compress and continue / Handoff now]
+```
+
+### 4. Phase Transition Check
+
+**Trigger:** At `/lfg` phase boundaries (Plan→Work, Work→Review, Review→Compound)
+
+```
+## 🔄 Phase Transition: [Previous] → [Next]
+
+### Previous Phase Assessment
+- **Objective met?** [Yes / Partially / No]
+- **Artifacts produced:** [list]
+- **Open issues carried forward:** [list or "none"]
+
+### Next Phase Readiness
+- [ ] Prerequisites satisfied
+- [ ] Context is clean (no stale noise)
+- [ ] Correct skills loaded for next phase
+
+**Proceed:** [Yes / Need to resolve: describe]
+```
+
+## Integration Points
+
+### In `/ship` (Phase 3 task loop)
+
+After every ceil(totalTasks / 2) tasks, run **Mid-Point Check**:
+
+```typescript
+const midpoint = Math.ceil(totalTasks / 2);
+if (completedTasks === midpoint) {
+  // Run mid-point reflection
+  // Log assessment to .beads/artifacts/$BEAD_ID/reflections.md
+}
+```
+
+Before each task completion claim, run **Completion Check** (lightweight — just the evidence audit).
+
+### In `/lfg` (phase transitions)
+
+At each step boundary (Plan→Work, Work→Review, Review→Compound), run **Phase Transition Check**.
+
+### Context pressure monitoring
+
+When context usage estimate exceeds 70%, run **Near-Limit Warning** regardless of task position.
+
+## Reflection Log
+
+Append all reflections to `.beads/artifacts/$BEAD_ID/reflections.md` (or session-level if no bead):
+
+```markdown
+## Reflection Log
+
+### [timestamp] Mid-Point Check
+
+Assessment: On track
+Context: ~45% used
+Adjustment: None
+
+### [timestamp] Completion Check — Task 3
+
+Verdict: Complete
+Evidence: typecheck pass, test pass (12/12)
+
+### [timestamp] Near-Limit Warning
+
+Decision: Compress and continue
+Deferred: Task 6 (cosmetic cleanup) → follow-up bead
+```
+
+## Gotchas
+
+- **Don't over-reflect** — these are quick self-checks, not long analyses. Each should take < 30 seconds of reasoning.
+- **Don't block on minor drift** — if drift is cosmetic (variable naming, style), note it and continue. Only pause for scope drift.
+- **Context cost** — each reflection adds ~200-400 tokens. Budget accordingly. Skip mid-point check for < 4 tasks.
+- **Not a replacement for verification** — reflections assess trajectory, not correctness. Always run actual verification commands.

package/dist/template/.opencode/skill/verification-before-completion/SKILL.md

@@ -245,6 +245,81 @@ After ANY `task()` subagent returns with "success", follow the **Worker Distrust
 > check a file, verify a condition, reject if unmet. Don't rely on the agent
 > "remembering" to follow the rule.
 
+## Phantom Completion Detection
+
+Tasks can "pass" verification while containing stub implementations. This gate catches completions that are technically correct but substantively empty.
+
+### When to Run
+
+- After all PRD tasks are marked complete (during `/ship` Phase 4-5)
+- Before closing any bead
+- When `--full` verification is requested
+
+### Stub Patterns to Detect
+
+Scan all files modified in the current task/bead for these phantom indicators:
+
+```bash
+# Run against modified code files only (exclude .md, .json, .yml to avoid false positives)
+git diff --name-only origin/main | grep -E '\.(ts|tsx|js|jsx|py|rs|go|swift|kt|java)$' | xargs grep -nE \
+  'return null|return undefined|return \{\}|return \[\]|onClick=\{?\(\) => \{\}\}?|TODO|FIXME|placeholder|stub|not.?implemented|throw new Error\(.Not implemented' \
+  2>/dev/null
+```
+
+| Pattern                                                  | What It Indicates         | Severity |
+| -------------------------------------------------------- | ------------------------- | -------- |
+| `return null` / `return undefined`                       | Empty implementation      | HIGH     |
+| `return {}` / `return []`                                | Hollow data               | HIGH     |
+| `onClick={() => {}}`                                     | No-op handler             | HIGH     |
+| `<div>Component</div>` / `<div>{/* TODO */}</div>`       | Placeholder UI            | HIGH     |
+| `TODO` / `FIXME` / `HACK`                                | Acknowledged incomplete   | MEDIUM   |
+| `placeholder` / `stub` / `not implemented`               | Self-documenting stubs    | HIGH     |
+| `throw new Error("Not implemented")`                     | Explicit stub             | HIGH     |
+| `fetch('/api/...')` without `await` or error handling    | Disconnected call         | MEDIUM   |
+| `Response.json({ok: true})` or static hardcoded response | Fake API response         | HIGH     |
+| `console.log` as only function body                      | Debug-only implementation | MEDIUM   |
+
+### Three-Level Artifact Verification
+
+For each file listed in PRD `Affected Files`:
+
+| Level              | Check                  | How                                                                                          |
+| ------------------ | ---------------------- | -------------------------------------------------------------------------------------------- |
+| **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` — verify real logic exists |
+| **3: Wired**       | Connected and used     | `grep -r "import.*ExportName" src/` — verify other files import/use it                       |
+
+### Key Link Verification
+
+Check that components are actually connected (not just existing side-by-side):
+
+| Connection Type | Check Command                                                  |
+| --------------- | -------------------------------------------------------------- |
+| Component → API | `grep -E "fetch.*api/\|axios\|useSWR\|useQuery" Component.tsx` |
+| API → Database  | `grep -E "prisma\.\|db\.\|sql\|query" route.ts`                |
+| Form → Handler  | `grep "onSubmit\|handleSubmit" Component.tsx`                  |
+| State → Render  | `grep "{stateVar}" Component.tsx`                              |
+| Route → Page    | Check router config references the page component              |
+
+### Phantom Score
+
+After running all checks, report a phantom score:
+
+```
+Phantom Completion Check:
+- Files scanned: [N]
+- Stubs found: [N] (HIGH: [n], MEDIUM: [n])
+- Artifact levels: [N] exist, [M] substantive, [K] wired
+- Key links verified: [N]/[M]
+- Score: [CLEAN | SUSPECT | PHANTOM]
+```
+
+| Score       | Criteria                                       | Action                            |
+| ----------- | ---------------------------------------------- | --------------------------------- |
+| **CLEAN**   | 0 HIGH stubs, all artifacts Level 3            | Proceed                           |
+| **SUSPECT** | 1-2 MEDIUM stubs OR 1 artifact not Level 3     | Report, ask user                  |
+| **PHANTOM** | Any HIGH stubs OR >2 artifacts not substantive | **BLOCK** — fix before completion |
+
 ## Why This Matters
 
 From 24 failure memories:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.20.5",
+	"version": "0.20.7",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": [
 		"agents",