opencodekit 0.12.7 → 0.13.0

package/dist/template/.opencode/memory/project/beads-workflow.md

@@ -0,0 +1,278 @@
+---
+purpose: Complete beads workflow mapping for OpenCodeKit commands
+updated: 2025-01-07
+---
+
+# Beads Workflow Best Practices
+
+Based on Steve Yegge's best practices and official beads documentation.
+
+## Core Principles
+
+| Principle                | Why                              | How                                  |
+| ------------------------ | -------------------------------- | ------------------------------------ |
+| One task per session     | Fresh context prevents confusion | Restart after `bd close`             |
+| Plan outside beads first | Better planning tools exist      | Use `/brainstorm` → `/plan` → import |
+| File lots of issues      | Track any work >2 minutes        | `bd create` liberally                |
+| "Land the plane" = PUSH  | `bd sync` means git push         | Always verify push succeeded         |
+| Keep DB small            | Performance degrades >500 issues | `bd cleanup --days 7` weekly         |
+
+## Maintenance Schedule
+
+| Task         | Frequency      | Command               | Why                                    |
+| ------------ | -------------- | --------------------- | -------------------------------------- |
+| Health check | Weekly         | `bd doctor --fix`     | Repairs orphaned issues, sync problems |
+| Cleanup      | Every few days | `bd cleanup --days 7` | Keep DB under 200-500 issues           |
+| Upgrade      | Weekly         | `bd upgrade`          | Latest features and fixes              |
+| Git hooks    | Once per repo  | `bd hooks install`    | Auto-sync on commit/merge/checkout     |
+
+## Command Configuration Best Practices
+
+Based on [OpenCode Command Docs](https://opencode.ai/docs/commands/).
+
+### Frontmatter Options
+
+```yaml
+---
+description: Short description shown in TUI command list
+argument-hint: "<required> [optional] [--flag]"
+agent: build | planner | scout | explore | review | vision
+subtask: true # Run as subagent (doesn't pollute primary context)
+model: gemini-2.5-pro # Override default model
+---
+```
+
+### Prompt Syntax
+
+| Syntax       | Purpose                  | Example                       |
+| ------------ | ------------------------ | ----------------------------- |
+| `$ARGUMENTS` | All arguments as string  | `/fix $ARGUMENTS`             |
+| `$1`, `$2`   | Positional arguments     | `/start $1` → `/start bd-abc` |
+| `!`command`` | Inject shell output      | `!`git status``               |
+| `@filepath`  | Include file content     | `@src/config.ts`              |
+| `$SELECTION` | Current editor selection | For IDE integrations          |
+
+### When to Use `subtask: true`
+
+**Use subtask for research/analysis** - prevents context pollution in primary agent:
+
+| Command Type             | `subtask: true`? | Why                                  |
+| ------------------------ | ---------------- | ------------------------------------ |
+| Research/exploration     | ✅ Yes           | Heavy reads, doesn't need to persist |
+| Code review/analysis     | ✅ Yes           | Analysis output, not implementation  |
+| UI/UX analysis           | ✅ Yes           | Design feedback, not code changes    |
+| Status/dashboard         | ✅ Yes           | Read-only information gathering      |
+| Implementation           | ❌ No            | Needs full context for edits         |
+| Lifecycle (start/finish) | ❌ No            | Coordinates state, needs persistence |
+| Generation (artifacts)   | ❌ No            | Creates files that need tracking     |
+
+### Commands by Category
+
+#### Research Commands (`subtask: true`)
+
+```
+/research, /analyze-project, /review-codebase, /brainstorm,
+/status, /summarize, /init, /ui-review, /accessibility-check,
+/analyze-mockup, /design-audit, /research-ui, /design
+```
+
+#### Lifecycle Commands (NO subtask)
+
+```
+/triage, /start, /create, /new-feature, /issue, /plan,
+/implement, /commit, /finish, /handoff, /resume, /pr, /fix
+```
+
+#### Generation Commands (NO subtask)
+
+```
+/generate-image, /generate-icon, /generate-diagram,
+/generate-pattern, /generate-storyboard, /edit-image, /restore-image
+```
+
+#### Utility Commands (NO subtask)
+
+```
+/quick-build, /fix-ci, /fix-types, /fix-ui,
+/revert-feature, /integration-test, /skill-create, /skill-optimize
+```
+
+## Command → Beads Mapping
+
+### Lifecycle Commands (Touch Beads)
+
+| Command           | Agent   | Beads Operations                                       | When to Use                 |
+| ----------------- | ------- | ------------------------------------------------------ | --------------------------- |
+| `/triage`         | build   | `bd doctor`, `bd list`, `bd ready`, `bd cleanup`       | Start of day, find work     |
+| `/triage --quick` | build   | `bd ready`, `bd list --status=in_progress`             | Fast check, what's next     |
+| `/start <id>`     | build   | `bd update --status in_progress`, `bd hooks install`   | Claim a task                |
+| `/create`         | build   | `bd create`, `bd sync`                                 | Create new tracked task     |
+| `/new-feature`    | planner | `bd create` (epic + subtasks), `bd dep add`, `bd sync` | Complex feature with phases |
+| `/issue <num>`    | build   | `bd create`, `bd sync`, `gh issue comment`             | Import GitHub issue         |
+| `/plan <id>`      | planner | `bd create` (subtasks), `bd dep add`, `bd sync`        | Break down task             |
+| `/implement <id>` | build   | `bd update --status in_progress`, `bd sync`            | Do the work                 |
+| `/commit [id]`    | build   | `bd sync` (if bead-id provided)                        | Commit with traceability    |
+| `/finish <id>`    | build   | `bd close`, `bd sync`                                  | Complete task (asks first)  |
+| `/handoff <id>`   | build   | `bd sync`                                              | Pause work, save context    |
+| `/resume <id>`    | build   | `bd update --status in_progress`                       | Continue previous work      |
+| `/pr <id>`        | build   | `bd-msg`, `bd sync`                                    | Create pull request         |
+| `/fix`            | build   | `bd sync` (after user confirms commit)                 | Fix bugs with tracking      |
+| `/status`         | explore | `bd status`, `bd list`, `bd-inbox`, `bd-release`       | Dashboard view              |
+
+### Research Commands (Read-Only Beads)
+
+| Command            | Agent   | Beads Operations      | Notes                      |
+| ------------------ | ------- | --------------------- | -------------------------- |
+| `/research <id>`   | scout   | `bd show` (read-only) | NO `bd sync` - subagent    |
+| `/brainstorm`      | planner | None                  | Pure planning, no tracking |
+| `/analyze-project` | explore | None                  | Codebase exploration       |
+| `/summarize`       | explore | None                  | Session/code summary       |
+| `/review-codebase` | review  | None                  | Code review                |
+
+### Non-Beads Commands
+
+| Command                | Agent   | Purpose                        |
+| ---------------------- | ------- | ------------------------------ |
+| `/quick-build`         | build   | Trivial fixes, no bead created |
+| `/design`              | planner | Architecture design            |
+| `/ui-review`           | vision  | UI/UX analysis                 |
+| `/accessibility-check` | vision  | A11y audit                     |
+| `/fix-ci`              | build   | CI pipeline fixes              |
+| `/fix-types`           | build   | TypeScript errors              |
+
+## Workflow Patterns
+
+### Pattern 1: Standard Task (S/M size)
+
+```
+/triage --quick          # Find ready work
+/start bd-xxx            # Claim task, create branch
+/implement bd-xxx        # Do the work
+/finish bd-xxx           # Verify, commit (asks first), close
+/pr bd-xxx               # Create PR (asks first)
+```
+
+### Pattern 2: Complex Feature (L/XL size)
+
+```
+/triage                  # Full triage with health check
+/new-feature "Feature"   # Creates epic + spec + plan + subtasks
+/start bd-xxx.1          # Start first subtask
+/implement bd-xxx.1      # Implement
+/finish bd-xxx.1         # Complete subtask
+/start bd-xxx.2          # Next subtask (now unblocked)
+...
+/finish bd-xxx           # Close epic when all subtasks done
+```
+
+### Pattern 3: Research-First
+
+```
+/create "Complex task"   # Create bead with spec
+/research bd-xxx         # Gather information (scout agent)
+/plan bd-xxx             # Design approach (planner agent)
+/implement bd-xxx        # Now implement with full context
+/finish bd-xxx           # Complete
+```
+
+### Pattern 4: Bug Fix
+
+```
+/issue 123               # Import GitHub issue as bead
+/start bd-xxx            # Claim
+/fix bd-xxx              # Diagnose + fix (asks before commit)
+/finish bd-xxx           # Verify + close
+/pr bd-xxx               # Create PR
+```
+
+### Pattern 5: Session Handoff
+
+```
+/implement bd-xxx        # Working on task...
+# Context getting large or end of day
+/handoff bd-xxx          # Save progress, creates handoff.md
+# New session
+/resume bd-xxx           # Load context, continue
+```
+
+### Pattern 6: Trivial Fix (No Bead)
+
+```
+/quick-build "fix typo"  # Single file, <30 min, commits directly
+```
+
+## Agent Boundaries
+
+### Leader Agents (Touch Beads)
+
+| Agent   | Can Do                          | Cannot Do |
+| ------- | ------------------------------- | --------- |
+| `build` | All beads operations, `bd sync` | -         |
+| `rush`  | All beads operations, `bd sync` | -         |
+
+### Subagents (Read-Only Beads)
+
+| Agent     | Can Do                                 | Cannot Do             |
+| --------- | -------------------------------------- | --------------------- |
+| `planner` | `bd show`, `bd list`, create artifacts | `bd sync`, `bd close` |
+| `scout`   | `bd show` (read context)               | Any writes            |
+| `explore` | `bd show`, `bd list`                   | Any writes            |
+| `review`  | `bd show`                              | Any writes            |
+| `vision`  | None                                   | All beads operations  |
+
+## File Locking (Multi-Agent)
+
+```typescript
+// Before editing shared files
+bd - reserve({ paths: ["src/auth.ts"], ttl: 600 });
+
+// Do work...
+
+// After completing edits
+bd - release({ paths: ["src/auth.ts"] });
+
+// Check active locks
+bd - release(); // No args = list locks
+```
+
+## Commit Message Format
+
+Always include bead ID for traceability:
+
+```
+feat(auth): add token refresh (bd-a1b2c3)
+
+Implement automatic token refresh when access token expires.
+
+Closes: bd-a1b2c3
+```
+
+## Session End Checklist
+
+1. [ ] All work committed
+2. [ ] `bd sync` run (pushes to git)
+3. [ ] If incomplete: `/handoff <id>` created
+4. [ ] If complete: `/finish <id>` run
+5. [ ] No stale file locks
+
+## Troubleshooting
+
+| Problem                | Solution                                |
+| ---------------------- | --------------------------------------- |
+| "bd command not found" | `npm install -g beads-village`          |
+| Orphaned issues        | `bd doctor --fix`                       |
+| DB too large           | `bd cleanup --days 3`                   |
+| Sync conflicts         | `bd sync --force` (careful!)            |
+| Stale handoff          | Check if rebase needed before `/resume` |
+| Task not in `bd ready` | Check blockers: `bd show <id>`          |
+
+## Anti-Patterns
+
+| Don't                                  | Why                   | Do Instead                       |
+| -------------------------------------- | --------------------- | -------------------------------- |
+| Skip `bd sync` at session end          | Changes won't persist | Always sync before stopping      |
+| Create beads for trivial fixes         | DB bloat              | Use `/quick-build`               |
+| Work on blocked tasks                  | Wastes time           | Use `bd ready` to find unblocked |
+| Subagents running `bd sync`            | Coordination issues   | Only leader agents sync          |
+| Force through complex with quick-build | Technical debt        | Proper `/create` workflow        |
+| Ignore `bd doctor` warnings            | Corruption risk       | Fix issues promptly              |

package/dist/template/.opencode/memory/session-context.md

@@ -0,0 +1,40 @@
+---
+purpose: Session continuity state that survives compaction
+updated: 2025-01-08
+---
+
+# Session Context
+
+<!--
+Agent-maintained via memory-update tool.
+Update when: goal changes, key decision made, state shifts, uncertainty discovered.
+After compaction: read this file, ask 1-3 targeted questions if gaps exist.
+-->
+
+## Goal
+
+<!-- What we're trying to achieve + success criteria -->
+
+## Constraints
+
+<!-- User-specified limits, discovered guardrails. Mark UNCONFIRMED if inferred -->
+
+## Decisions
+
+<!-- Key choices made this session with brief rationale -->
+
+## State
+
+- **Done**:
+- **Now**:
+- **Next**:
+
+## Open Questions
+
+<!-- Uncertainties - mark UNCONFIRMED if not verified -->
+
+## Working Set
+
+- **Files**:
+- **Bead**:
+- **Branch**: