Release v2.1.0: Wizard Redesign

.claude/commands/plan:phase.md

@@ -6,176 +6,134 @@ args:
     required: true
 ---
 
-You are tasked with creating a comprehensive, step-by-step implementation plan for **Phase {{P}}** of **Milestone {{M}}** (the xvn → anvs rename).
+Create a comprehensive, actionable implementation plan for **Phase {{P}}** of **Milestone {{M}}**.
 
-## Instructions
+## Process
 
-1. **Parse the milestone and phase:**
-   - Extract milestone number (M) and phase number (P) from "{{M:P}}"
-   - For milestone 12, the milestone directory is `spec/milestone-12-renaming-to-anvs/`
+1. **Find milestone**: `ls -d spec/milestone-{{M}}*/` to locate directory
+2. **Read context**: Main plan file, task checklist, existing phase files for formatting consistency
+3. **Extract scope**: Identify all tasks belonging to Phase {{P}}
+4. **Create plan**: `spec/milestone-{{M}}*/phase-{{P}}.md` with complete implementation details
 
-2. **Read the context:**
-   - Read `spec/milestone-12-renaming-to-anvs/RENAME_PLAN.md` to understand the overall rename plan
-   - Read `spec/milestone-12-renaming-to-anvs/RENAME_PLAN_TASKS.md` to see the task checklist
-   - Look at `spec/milestone-12-renaming-to-anvs/phase-0.md` as a reference for the format and level of detail
-   - Identify which section of RENAME_PLAN.md corresponds to Phase {{P}}
+## Document Structure
 
-3. **Create the phase implementation plan:**
-   - Create a new file: `spec/milestone-12-renaming-to-anvs/phase-{{P}}.md`
-   - Structure the plan following the phase-0.md format
-   - Include:
-     - Phase status and metadata (version, duration estimate)
-     - Overview explaining the phase goals
-     - Detailed implementation tasks with specific file changes
-     - Exact commands to run
-     - Action checklists for each task
-     - Verification checklist
-     - Success criteria
-     - Next steps
+```markdown
+# Phase {{P}}: [Descriptive Title]
 
-4. **Plan structure:**
-   ```markdown
-   # Phase {{P}}: [Phase Title from RENAME_PLAN.md]
+**Status**: Not Started | **Version**: vX.Y.Z | **Duration**: 30-45 min + CI time
 
-   **Status**: Not Started
-   **Version**: [Target version, e.g., v2.0.0]
-   **Duration Estimate**: [Time estimate]
+## Overview
+[2-3 sentences: what this phase accomplishes and its role in the milestone]
 
-   ## Overview
+**Why Phase {{P}} is Critical:**
+- [Impact/dependency reason]
+- [Technical/user-facing reason]
+- [Risk mitigation reason]
 
-   [Detailed explanation of what this phase accomplishes and why it's important]
+**⚠️ CHECKPOINT**: [Pre-requisites or blocking warnings]
 
-   **Why Phase {{P}} is [Important/Essential/Critical]:**
-   - [Reason 1]
-   - [Reason 2]
-   - [Reason 3]
-
-   **⚠️ CHECKPOINT** (if applicable): [Any important notes before starting]
-
-   ---
-
-   ## Implementation Tasks
-
-   ### Task {{P}}.1: [Task Title]
-
-   **File**: `path/to/file` (new/existing file)
-
-   **Content Requirements** (for new files):
-   ```markdown
-   [Example content or structure]
-   ```
-
-   **Changes Required** (for existing files):
-   - Line X: Change `old value` to `new value`
-   - Section Y: Update Z
-
-   **Commands** (if applicable):
-   ```bash
-   # Command 1
-   command to run
-
-   # Command 2
-   another command
-   ```
-
-   **Expected Output** (if applicable):
-   ```
-   Expected command output
-   ```
-
-   **Actions**:
-   - [ ] Specific action 1
-   - [ ] Specific action 2
-   - [ ] Specific action 3
-
-   ---
-
-   ### Task {{P}}.2: [Next Task Title]
-
-   [Repeat structure for each task in this phase]
+---
 
-   ---
+## Implementation Tasks
 
-   ## Verification Checklist
+### Task {{P}}.1: [Action-Oriented Title]
 
-   Before proceeding to Phase {{P+1}}, verify ALL of the following:
+**File**: `exact/path/to/file.ext` (new file | existing file)
 
-   - [ ] Verification item 1
-   - [ ] Verification item 2
-   - [ ] Verification item 3
-   - [ ] No breaking changes introduced (or documented if intentional)
+**Content Requirements** (for NEW files only):
+```lang
+[Complete, copy-pasteable file content with actual values]
+```
 
-   ---
+**Changes Required** (for EXISTING files only):
+- Line/Section X: Change `old_value` to `new_value`
+- [Specific before/after examples]
 
-   ## Success Criteria
+**Commands**:
+```bash
+# Descriptive comment explaining purpose
+exact-command --with-real-flags value
 
-   Phase {{P}} is complete when:
+# Expected output:
+[Actual expected output, not placeholder]
+```
 
-   1. ✅ Criterion 1
-   2. ✅ Criterion 2
-   3. ✅ Criterion 3
+**Actions**:
+- [ ] Granular, testable step
+- [ ] Verification step with command
+- [ ] Commit with message: `type: description`
 
-   ---
+---
 
-   ## Next Steps
+[Repeat Task {{P}}.N for each task in phase]
 
-   After completing Phase {{P}}:
+---
 
-   1. [Next action]
-   2. [Next action]
-   3. **Proceed to Phase {{P+1}}**: [Brief description of next phase]
+## Verification Checklist
 
-   ---
+Before Phase {{P+1}}, verify:
+- [ ] Specific check with command: `verification-cmd`
+- [ ] Expected result: [concrete outcome]
+- [ ] All builds/tests pass
+- [ ] No breaking changes (or documented)
 
-   ## Rollback Plan
+---
 
-   If issues are discovered:
+## Success Criteria
 
-   1. [Rollback step 1]
-   2. [Rollback step 2]
+1. ✅ Measurable deliverable 1
+2. ✅ Testable outcome 2
+3. ✅ State change verified
 
-   ---
+---
 
-   ## Notes
+## Next Steps
 
-   - [Important note 1]
-   - [Important note 2]
-   ```
+1. Update milestone tracker
+2. [Any cleanup or documentation]
+3. **Proceed to Phase {{P+1}}**: [One-line preview]
 
-5. **Be extremely detailed:**
-   - For each file that needs to be modified, specify:
-     - The exact file path
-     - What needs to change (with before/after examples)
-     - Line numbers or sections to modify
-   - For each command to run:
-     - Provide the exact command
-     - Explain what it does
-     - Show expected output
-   - For verification:
-     - Provide specific commands to verify changes
-     - Include expected results
+---
 
-6. **Follow the phase-0.md style:**
-   - Use the same level of detail and structure
-   - Include action checklists with `[ ]` checkboxes
-   - Provide context and explanations
-   - Add warnings and important notes
-   - Include time estimates
+## Rollback Plan
 
-7. **Quality assurance:**
-   - After creating the phase plan, review it to ensure:
-     - All tasks from RENAME_PLAN.md for this phase are covered
-     - Task numbers match the phase (e.g., Phase 2 tasks are 2.1, 2.2, etc.)
-     - Commands are accurate and tested
-     - File paths are correct
-     - The plan is actionable and complete
+1. Specific rollback command/steps
+2. Verification of rollback success
 
-## Important Notes
+---
 
-- Phase plans should be as detailed as phase-0.md - developers should be able to execute the phase using ONLY this document
-- Include actual commands, file paths, and code examples
-- Make checklists granular enough to track progress
-- Consider edge cases and potential issues
-- Provide clear success criteria so developers know when they're done
-- Link to related documentation where helpful
-- For milestone 12 specifically, focus on the xvn → anvs rename changes
+## Notes
+
+- Edge cases and gotchas
+- Platform-specific considerations
+```
+
+## Quality Requirements
+
+**CRITICAL - Each task must include:**
+- Real file paths (never use `path/to/file` placeholders)
+- Complete code examples (fully functional, not snippets)
+- Runnable commands with actual flags and values
+- Expected output examples (not just "output will show...")
+- Granular action checkboxes (aim for 3-7 per task)
+- Conventional commit message templates
+
+**For file modifications:**
+- Show before/after examples with context
+- Reference specific line numbers or section headers
+- Include full code blocks, not partial snippets
+
+**For commands:**
+- Always include explanatory comment above command
+- Show complete expected output
+- Include failure modes if relevant
+
+**Duration estimates:**
+- Per-task time estimates for complex tasks
+- Include CI/build wait times separately
+- Be realistic based on similar past work
+
+**Self-contained execution:**
+- Developer should execute phase using ONLY this document
+- No external references required during execution
+- All context and rationale included inline

.opencode/command/README.md

@@ -0,0 +1,80 @@
+# Opencode Command Templates
+
+This directory contains command templates specifically adapted for use with opencode. These templates provide structured workflows for implementing milestones and phases in the ANVS project.
+
+## Available Commands
+
+### Milestone Commands
+
+- **`do:milestone.md`** - Execute a complete milestone implementation
+  - Follows PLAN.md specifications strictly
+  - Includes test-driven development workflow
+  - Handles version bumping and git tagging
+
+- **`plan:milestone.md`** - Generate detailed milestone implementation plans
+  - Creates comprehensive PLAN.md from SPEC.md and TASKS.md
+  - Includes code examples and testing strategies
+
+### Phase Commands
+
+- **`do:phase.md`** - Execute a specific phase within a milestone
+  - Granular task execution with verification
+  - Supports rollback procedures
+  - Includes action checklists and success criteria
+
+- **`plan:phase.md`** - Generate detailed phase implementation plans
+  - Creates actionable phase documents
+  - Includes exact commands and expected outputs
+  - Self-contained execution guides
+
+- **`plan:phase-12.md`** - Milestone 12 specific phase planning
+  - Specialized for the xvn → anvs rename project
+  - Includes rename-specific workflows
+
+## Opencode Integration
+
+These commands are specifically adapted for opencode's tool ecosystem:
+
+- **todowrite** - Task list management and progress tracking
+- **task** - Complex multi-step operations with subagents
+- **read/edit/write** - File manipulation with proper context handling
+- **grep/glob** - Code search and exploration
+- **bash** - Command execution with timeout and security measures
+
+## Usage with Opencode
+
+1. **Invoke commands** using opencode's slash command system
+2. **Pass arguments** as specified in each command's `args` section
+3. **Follow workflows** exactly as documented - these are strict implementation guides
+4. **Use tools appropriately** - leverage opencode's full capability set
+
+## Project-Specific Conventions
+
+- **Testing**: Use `cargo test` and `make check` for validation
+- **Linting**: Run `make check` before commits
+- **Commits**: Follow conventional commit format from CLAUDE.md
+- **Versioning**: Use `./scripts/version.sh` for version bumps
+- **Documentation**: Update PROGRESS.md and task checklists
+
+## Error Handling
+
+All commands include error handling procedures:
+
+- Stop on failures and seek guidance
+- Document issues clearly
+- Use rollback procedures when available
+- Maintain system stability during failures
+
+## Quality Assurance
+
+- Commands include review agent integration
+- All changes require testing validation
+- Code quality checks are mandatory
+- Documentation updates are required
+
+## Related Documentation
+
+- `CLAUDE.md` - Commit conventions and development guidelines
+- `spec/` - Milestone specifications and plans
+- `Makefile` - Available build and test commands
+- `AGENTS.md` - Opencode agent capabilities

.opencode/command/do:milestone.md

@@ -78,6 +78,8 @@ You are tasked with implementing Milestone {{N}} by strictly following the imple
 - **Ask when uncertain** - Don't guess or deviate from the plan
 - **All tests must pass** - This is the definition of "done"
 - **Exception for early milestones** - Skip test-first approach if testing framework doesn't exist yet
+- **Run linting before commits** - Always run `make check` before committing changes
+- **Handle errors gracefully** - If a task fails, document the issue and seek guidance before proceeding
 
 ## Success Criteria
 
@@ -90,4 +92,24 @@ You are tasked with implementing Milestone {{N}} by strictly following the imple
 - Version bumped appropriately with git tag created
   - Milestone completion: minor version bump (e.g., 0.6.0 -> 0.7.0)
   - Bug fixes: patch version bump (e.g., 0.6.0 -> 0.6.1)
-  - Major release: major version bump (e.g., 0.9.0 -> 1.0.0)
+  - Major release: major version bump (e.g., 0.9.0 -> 1.0.0)
+
+## Error Handling and Rollback
+
+If a task fails or unexpected issues arise:
+
+1. **Stop immediately** - Do not continue with other tasks
+2. **Document the issue** - Note what went wrong and why
+3. **Seek guidance** - Ask the user for direction on how to proceed
+4. **Consider rollback options**:
+   - If code changes caused the failure, revert the changes
+   - If tests are failing, investigate the root cause
+   - If the plan itself is flawed, request clarification
+5. **Resume only after resolution** - Do not proceed until the issue is resolved
+
+## Opencode Integration
+
+- Use `make check` before any commits to ensure code quality
+- Leverage opencode's search tools (grep, glob) for code exploration
+- Use the task tool for complex multi-step operations
+- Follow conventional commits as specified in CLAUDE.md