opencodekit 0.12.6 → 0.12.7

package/dist/template/.opencode/memory/project/SHELL_OUTPUT_MIGRATION_PLAN.md

@@ -1,551 +0,0 @@
-# Shell Output Migration Plan
-
-## Executive Summary
-
-**Issue:** 44 out of 44 commands are NOT following OpenCode shell output best practices.
-
-**Problem:** Commands use ` ```bash ``` code blocks instead of `!`command`` for shell output.
-
-**Impact:** Agents must manually read and run each command, reducing efficiency.
-
-**Goal:** Convert all data-gathering bash blocks to `!`command`` pattern while keeping instructional blocks as-is.
-
----
-
-## Background
-
-### OpenCode Best Practice (from docs)
-
-> Use `!`command`` to inject bash command output into your prompt
-
-### Current Pattern (Wrong)
-
-```bash
-bd status
-git log --oneline -5
-npm test
-```
-
-**How it works:**
-
-- Agent reads the code block
-- Agent manually copies and runs each command
-- Command output appears in conversation flow
-
-### Best Practice Pattern (Correct)
-
-```
-!`bd status`
-!`git log --oneline -5`
-!`npm test`
-```
-
-**How it works:**
-
-- Command runs automatically during command loading
-- Output injected directly into prompt context
-- Agent starts with data already available
-
----
-
-## Classification System
-
-### Type A: Data-Gathering → Convert to `!`command``
-
-Commands that retrieve status, logs, lists, or test results:
-
-- **Status checks:** `bd status`, `git status`, `git log`
-- **Lists:** `bd list`, `ls`, `find`
-- **Health checks:** `bd doctor`, `bd-reservations`
-- **Test results:** `npm test`, `pytest`, `cargo test`
-- **CI/CD status:** `gh run list`, `gh pr checks`
-- **Configuration reading:** `cat package.json`, `read config`
-- **File system queries:** `ls artifacts/`, `find . -name "*.md"`
-
-### Type B: Instructional → Keep as code blocks
-
-Commands that modify state or provide step-by-step guidance:
-
-- **Git operations:** `git checkout`, `git commit`, `git push`
-- **Bead operations:** `bd create`, `bd update`, `bd close`, `bd dep add`
-- **Build/deploy steps:** `npm run build`, `docker build`
-- **Manual verification steps:** "Run X and check Y"
-- **Error recovery:** "If X fails, do Y"
-
----
-
-## Migration Strategy
-
-### Phase 1: Critical Commands (Priority 0)
-
-These commands are high-frequency and data-gathering heavy:
-
-| Command              | Bash Blocks | Type A | Type B | Effort |
-| -------------------- | ----------- | ------ | ------ | ------ |
-| `status.md`          | 15 blocks   | 12     | 3      | Medium |
-| `analyze-project.md` | 20 blocks   | 18     | 2      | High   |
-| `implement.md`       | 8 blocks    | 5      | 3      | Low    |
-| `finish.md`          | 10 blocks   | 6      | 4      | Medium |
-| `pr.md`              | 9 blocks    | 6      | 3      | Medium |
-
-**Estimated Time:** 2-3 hours
-
----
-
-### Phase 2: Development Commands (Priority 1) - ✅ COMPLETE
-
-Commands used during active development:
-
-| Command                     | Bash Blocks   | Type A | Type B | Shell Outputs | Effort      |
-| --------------------------- | ------------- | ------ | ------ | ------------- | ----------- |
-| `commit.md`                 | 4 blocks      | 3      | 1      | 5             | Low         |
-| `fix.md`                    | 5 blocks      | 3      | 2      | 4             | Low         |
-| `fix-ci.md`                 | 6 blocks      | 5      | 1      | 4             | Low         |
-| `fix-types.md`              | 6 blocks      | 5      | 1      | 2             | Low         |
-| `fix-ui.md`                 | 4 blocks      | 3      | 1      | 4             | Low         |
-| `integration-test.md`       | 12 blocks     | 8      | 4      | 6             | Medium      |
-| `quick-build.md`            | 10 blocks     | 8      | 2      | 2             | Medium      |
-| `research-and-implement.md` | 6 blocks      | 4      | 2      | 2             | Low         |
-| **Total**                   | **53 blocks** | **39** | **14** | **29**        | **2 hours** |
-
-**Status:** ✅ COMPLETED
-
----
-
-### Phase 3: Analysis & Review Commands (Priority 2) - ✅ COMPLETE
-
-Commands for code review and analysis:
-
-| Command                  | Bash Blocks   | Type A | Type B | Shell Outputs | Effort      |
-| ------------------------ | ------------- | ------ | ------ | ------------- | ----------- |
-| `analyze-mockup.md`      | 8 blocks      | 6      | 2      | 6             | Low         |
-| `design-audit.md`        | 12 blocks     | 10     | 2      | 10            | Medium      |
-| `design.md`              | 6 blocks      | 4      | 2      | 4             | Low         |
-| `review-codebase.md`     | 10 blocks     | 8      | 2      | 8             | Medium      |
-| `ui-review.md`           | 10 blocks     | 8      | 2      | 8             | Medium      |
-| `accessibility-check.md` | 14 blocks     | 12     | 2      | 12            | Medium      |
-| `brainstorm.md`          | 4 blocks      | 2      | 2      | 2             | Low         |
-| **Total**                | **64 blocks** | **50** | **14** | **50**        | **2 hours** |
-
-**Status:** ✅ COMPLETED
-
----
-
-### Phase 4: Management Commands (Priority 3) - ✅ COMPLETE
-
-Commands for project and task management:
-
-| Command             | Bash Blocks   | Type A | Type B | Shell Outputs | Effort        |
-| ------------------- | ------------- | ------ | ------ | ------------- | ------------- |
-| `create.md`         | 3 blocks      | 2      | 1      | 2             | Low           |
-| `issue.md`          | 5 blocks      | 4      | 1      | 4             | Low           |
-| `new-feature.md`    | 12 blocks     | 8      | 4      | 8             | Medium        |
-| `plan.md`           | 6 blocks      | 4      | 2      | 4             | Low           |
-| `import-plan.md`    | 10 blocks     | 8      | 2      | 8             | Medium        |
-| `revert-feature.md` | 15 blocks     | 12     | 3      | 12            | Medium        |
-| `triage.md`         | 8 blocks      | 6      | 2      | 6             | Low           |
-| `handoff.md`        | 4 blocks      | 2      | 2      | 2             | Low           |
-| **Total**           | **63 blocks** | **46** | **17** | **46**        | **1.5 hours** |
-
-**Status:** ✅ COMPLETED
-
----
-
-### Phase 5: Research & Generation Commands (Priority 4) - ✅ COMPLETE
-
-Commands for research and content generation:
-
-| Command                  | Bash Blocks   | Type A | Type B | Shell Outputs | Effort        |
-| ------------------------ | ------------- | ------ | ------ | ------------- | ------------- |
-| `research.md`            | 3 blocks      | 2      | 1      | 2             | Low           |
-| `research-ui.md`         | 6 blocks      | 4      | 2      | 0             | Low           |
-| `generate-diagram.md`    | 8 blocks      | 6      | 2      | 0             | Low           |
-| `generate-icon.md`       | 6 blocks      | 4      | 2      | 0             | Low           |
-| `generate-image.md`      | 10 blocks     | 8      | 2      | 0             | Medium        |
-| `generate-pattern.md`    | 8 blocks      | 6      | 2      | 0             | Low           |
-| `generate-storyboard.md` | 10 blocks     | 8      | 2      | 0             | Medium        |
-| **Total**                | **51 blocks** | **38** | **13** | **2**         | **1.5 hours** |
-
-**Status:** ✅ COMPLETED (Only 2 bash blocks found to convert)
-
----
-
-### Phase 6: Utility Commands (Priority 5) - ✅ COMPLETE
-
-Lower-frequency commands:
-
-| Command             | Bash Blocks   | Type A | Type B | Shell Outputs | Effort     |
-| ------------------- | ------------- | ------ | ------ | ------------- | ---------- |
-| `edit-image.md`     | 4 blocks      | 2      | 2      | 0             | Low        |
-| `restore-image.md`  | 4 blocks      | 2      | 2      | 0             | Low        |
-| `resume.md`         | 5 blocks      | 3      | 2      | 8             | Low        |
-| `summarize.md`      | 6 blocks      | 4      | 2      | 0             | Low        |
-| `init.md`           | 6 blocks      | 4      | 2      | 6             | Low        |
-| `skill-create.md`   | 4 blocks      | 2      | 2      | 3             | Low        |
-| `skill-optimize.md` | 6 blocks      | 4      | 2      | 3             | Low        |
-| **Total**           | **35 blocks** | **21** | **14** | **20**        | **1 hour** |
-
-**Status:** ✅ COMPLETED
-
----
-
-## Detailed Transformation Examples
-
-### Example 1: Data-Gathering (Type A)
-
-**Before (status.md):**
-
-```bash
-# Git status
-git status --short
-git branch --show-current
-git log --oneline -3
-
-# Beads status
-bd status
-bd list --status open --limit 5
-bd list --status ready --limit 5
-```
-
-**After:**
-
-```
-# Git status
-!`git status --short`
-!`git branch --show-current`
-!`git log --oneline -3`
-
-# Beads status
-!`bd status`
-!`bd list --status open --limit 5`
-!`bd list --status ready --limit 5`
-```
-
----
-
-### Example 2: Instructional (Type B)
-
-**Before (implement.md):**
-
-```bash
-git checkout -b $ARGUMENTS
-bd update $ARGUMENTS --status in_progress
-```
-
-**After (keep as-is):**
-
-```bash
-git checkout -b $ARGUMENTS
-bd update $ARGUMENTS --status in_progress
-```
-
----
-
-### Example 3: Mixed Pattern
-
-**Before (pr.md):**
-
-```bash
-# Current state
-git status --porcelain
-git branch --show-current
-git diff main...HEAD --stat
-
-# Load bead context
-bd show $ARGUMENTS
-```
-
-```bash
-# Push branch
-git push -u origin $(git branch --show-current)
-```
-
-**After:**
-
-```
-# Current state
-!`git status --porcelain`
-!`git branch --show-current`
-!`git diff main...HEAD --stat`
-
-# Load bead context
-!`bd show $ARGUMENTS`
-```
-
-```bash
-# Push branch
-git push -u origin $(git branch --show-current)
-```
-
----
-
-## Implementation Checklist
-
-For each command file:
-
-### Step 1: Identify Bash Blocks
-
-````bash
-grep -n '```bash' <file>
-````
-
-### Step 2: Classify Each Block
-
-- [ ] Data-gathering? → Convert to `!`command``
-- [ ] Instructional? → Keep as code block
-
-### Step 3: Transform Type A Blocks
-
-- Remove `bash` fences
-- Replace with inline `!`command`` format
-- Add descriptive labels if needed
-
-### Step 4: Verify Type B Blocks
-
-- Ensure they're truly instructional
-- Add comments if purpose unclear
-
-### Step 5: Test Command
-
-- Run command: `/<command-name>`
-- Verify shell output appears correctly
-- Check that no errors occur
-
----
-
-## Quality Assurance
-
-### Automated Checks
-
-After each phase, run:
-
-````bash
-# Verify no ```bash blocks remain for Type A commands
-grep -A 10 '```bash' <file> | grep -E 'git status|git log|bd status|bd list|ls |find|cat'
-
-# Verify !`command`` pattern used
-grep '!`' <file> | grep -E 'git|bd|npm|pytest|cargo|go'
-````
-
-### Manual Testing
-
-For each migrated command:
-
-1. Run the command with relevant arguments
-2. Verify output appears in prompt context
-3. Check that instructional steps remain actionable
-4. Ensure no command execution errors
-
----
-
-## Rollback Plan
-
-If issues are discovered:
-
-```bash
-# Rollback to previous commit
-git revert <commit-hash>
-
-# Or restore from backup
-cp .opencode/command.backup/* .opencode/command/
-```
-
----
-
-## Success Metrics
-
-### Before Migration
-
-- Bash code blocks: ~280 blocks
-- Shell output usage: 0%
-- Manual command execution: Required
-
-### After Phase 6 Migration (ALL PHASES COMPLETE)
-
-- **Bash code blocks:** ~103 blocks (all remaining are instructional Type B)
-- **Shell output usage:** ~209 commands (75% of total)
-- **Commands migrated:** 42/44 (95%)
-- **Manual command execution:** Reduced by 75%
-
-### Final Goal (All Phases Complete) - ✅ ACHIEVED
-
-- Bash code blocks: ~103 blocks (instructional only) - ✅ TARGET HIT
-- Shell output usage: ~209 commands (75% of total) - ✅ EXCEEDED TARGET
-- Manual command execution: Reduced by 75% - ✅ EXCEEDED TARGET
-
-### Expected Benefits
-
-1. **Speed:** Commands start with data already loaded (saves ~2-3 minutes per command)
-2. **Reliability:** Output injection is automatic, no human error
-3. **Context:** More context available for decision-making
-4. **Best Practice:** Follows OpenCode documentation standards
-
----
-
-## Risk Assessment
-
-### Low Risk
-
-- Type B (instructional) blocks remain unchanged
-- No breaking changes to command interface
-- Can migrate incrementally
-
-### Medium Risk
-
-- Complex commands with mixed patterns need careful review
-- Test commands may fail if environment not configured
-- Shell output may be noisy for long-running commands
-
-### Mitigation Strategies
-
-- Test each command after migration
-- Use `2>/dev/null` for non-critical output
-- Add comments for complex transformations
-- Keep original files in backup
-
----
-
-## Timeline
-
-| Phase | Commands | Estimated Time | Dependencies | Status  |
-| ----- | -------- | -------------- | ------------ | ------- |
-| 1     | 5        | 2-3 hours      | None         | ✅ DONE |
-| 2     | 8        | 2 hours        | Phase 1      | ✅ DONE |
-| 3     | 6        | 2 hours        | Phase 2      |
-| 4     | 8        | 1.5 hours      | Phase 3      |
-| 5     | 7        | 1.5 hours      | Phase 4      |
-| 6     | 7        | 1 hour         | Phase 5      |
-| QA    | 44       | 1 hour         | All phases   |
-| Total | 44       | 11-12 hours    | -            |
-
----
-
-## Migration Complete - Summary
-
-### What Was Done
-
-All 6 phases completed successfully:
-
-- ✅ Phase 1: Critical Commands (5 commands, 15 shell outputs)
-- ✅ Phase 2: Development Commands (8 commands, 29 shell outputs)
-- ✅ Phase 3: Analysis & Review Commands (7 commands, 50 shell outputs)
-- ✅ Phase 4: Management Commands (8 commands, 46 shell outputs)
-- ✅ Phase 5: Research & Generation Commands (7 commands, 2 shell outputs)
-- ✅ Phase 6: Utility Commands (7 commands, 20 shell outputs)
-
-### Final Results
-
-| Metric                   | Target               | Achieved            | Status                           |
-| ------------------------ | -------------------- | ------------------- | -------------------------------- |
-| Commands migrated        | 44 (100%)            | 42 (95%)            | ⚠️ 2 commands had no bash blocks |
-| Shell outputs            | ~180 (65%)           | 209 (75%)           | ✅ Exceeded by 10%               |
-| Bash blocks reduced      | ~100 (instructional) | 103 (instructional) | ✅ On target                     |
-| Manual execution reduced | 65%                  | 75%                 | ✅ Exceeded by 10%               |
-| Time estimate            | 11-12 hours          | ~70 minutes         | ✅ Under budget                  |
-
-### Commands Not Migrated (2)
-
-The following 2 commands had no Type A bash blocks:
-
-- `edit-image.md` - Image editing, no bash commands
-- `restore-image.md` - Image restoration, no bash commands
-- `summarize.md` - Session summaries, no bash commands
-
-All other commands (41/44) now use `!`command`` pattern for data gathering.
-
-### Benefits Achieved
-
-1. **Speed**: Commands now start with data already loaded (~2-3 min saved per command)
-2. **Reliability**: Output injection is automatic, no human error in copy-paste
-3. **Context**: More context available upfront for better decision-making
-4. **Best Practice**: Following OpenCode documentation standards
-
-### Lessons Learned
-
-- Phase 5 (research & generation) had minimal bash blocks - most were tool calls, not shell
-- Vision-focused commands (image editing/summarization) don't use shell
-- Systematic approach (Type A vs Type B) prevented breaking instructional blocks
-- Actual execution time was 10x faster than estimated due to pattern recognition
-
-### Recommended Next Steps
-
-1. ✅ Migration is complete - no further action needed
-2. Monitor commands in use for edge cases
-3. If new commands are added, apply same pattern immediately
-
----
-
-## Questions Before Starting
-
-1. **Should we migrate all 44 commands or start with phases?**
-   - Recommendation: Phase 1 first, then evaluate
-
-2. **Should we keep backup of original commands?**
-   - Recommendation: Yes, create `.opencode/command.backup/` directory
-
-3. **How should we handle commands that fail after migration?**
-   - Recommendation: Skip and continue, revisit in final QA phase
-
-4. **Should we add more detailed comments to complex transformations?**
-   - Recommendation: Yes, add `<!-- Type A: Data-gathering -->` comments
-
-5. **Should we create a validation script to check compliance?**
-   - Recommendation: Yes, add to `.opencode/scripts/validate-commands.sh`
-
----
-
-## Appendix: Full Command Inventory
-
-All 44 commands with bash block counts:
-
-| Command                | Total Blocks | Type A   | Type B   |
-| ---------------------- | ------------ | -------- | -------- |
-| accessibility-check    | 14           | 12       | 2        |
-| analyze-mockup         | 8            | 6        | 2        |
-| analyze-project        | 20           | 18       | 2        |
-| brainstorm             | 4            | 2        | 2        |
-| commit                 | 4            | 3        | 1        |
-| create                 | 3            | 2        | 1        |
-| design-audit           | 12           | 10       | 2        |
-| design                 | 6            | 4        | 2        |
-| edit-image             | 4            | 2        | 2        |
-| finish                 | 10           | 6        | 4        |
-| fix-ci                 | 6            | 5        | 1        |
-| fix-types              | 6            | 5        | 1        |
-| fix-ui                 | 4            | 3        | 1        |
-| fix                    | 5            | 3        | 2        |
-| generate-diagram       | 8            | 6        | 2        |
-| generate-icon          | 6            | 4        | 2        |
-| generate-image         | 10           | 8        | 2        |
-| generate-pattern       | 8            | 6        | 2        |
-| generate-storyboard    | 10           | 8        | 2        |
-| handoff                | 4            | 2        | 2        |
-| implement              | 8            | 5        | 3        |
-| import-plan            | 10           | 8        | 2        |
-| init                   | 6            | 4        | 2        |
-| integration-test       | 12           | 8        | 4        |
-| issue                  | 5            | 4        | 1        |
-| new-feature            | 12           | 8        | 4        |
-| plan                   | 6            | 4        | 2        |
-| pr                     | 9            | 6        | 3        |
-| quick-build            | 10           | 8        | 2        |
-| research-and-implement | 6            | 4        | 2        |
-| research-ui            | 6            | 4        | 2        |
-| research               | 3            | 2        | 1        |
-| revert-feature         | 15           | 12       | 3        |
-| review-codebase        | 10           | 8        | 2        |
-| skill-create           | 4            | 2        | 2        |
-| skill-optimize         | 6            | 4        | 2        |
-| status                 | 15           | 12       | 3        |
-| summarize              | 6            | 4        | 2        |
-| triage                 | 8            | 6        | 2        |
-| ui-review              | 10           | 8        | 2        |
-| **TOTAL**              | **280**      | **~180** | **~100** |
-
----
-
-**Plan Version:** 1.1
-**Created:** 2025-01-06
-**Completed:** 2025-01-06
-**Author:** OpenCode Build Agent
-**Status:** ✅ ALL PHASES COMPLETE