Implementation Plan: Agentic Primitives - Repository Command Suite

Version: 1.0 Date: 2026-02-11 Status: Draft - Ready for Review Changelog:

• v1.0: Initial draft - Agentic command workflow for repository plans Related:
• content/metadata/plans/01 Governance Model & Content Structure/
• .opencode/agents/plan.md
• .opencode/agents/review.md
• .opencode/agents/build.md

Executive Summary

This plan establishes a comprehensive agentic command workflow for creating, reviewing, and completing repository-level implementation plans. The initiative introduces four new slash commands (/create-repo-plan, /review-plan, /review-completed-plan, /complete-plan) that work together to provide an end-to-end plan lifecycle management system.

Key Benefits:

• Structured Workflow: Clear progression from plan creation → review → execution → validation
• Agent Specialization: Each command leverages the appropriate agent (Plan, Review, or Build) for optimal results
• Context-Aware: Commands intelligently infer plan context from conversation history and repository structure
• Interactive Validation: Built-in checklist and question mechanisms ensure quality at each stage
• Status Tracking: Automatic frontmatter updates document plan lifecycle progression

Critical Dependencies:

• Updated agent permissions (Review agent bash access, Plan agent write access to content/metadata/plans/**)
• Existing plan structure in content/metadata/plans/ with established frontmatter conventions
• OpenCode.ai command framework supporting agent delegation and $ARGUMENTS variable

This command suite will extend naturally to other plan types (Value Stream, Guild/Practice) in future iterations, establishing a reusable pattern for all metadata/plans/ directories throughout the repository.

Architecture/Context Overview

Current State

• Plan Creation: Manual process or existing /create-plan command (generic, not repository-specific)
• Plan Review: Ad-hoc review by switching to Review agent manually
• Plan Execution: Manual handoff to Build agent with no structured workflow
• Status Tracking: Manual frontmatter updates, inconsistent status values

Proposed Approach

A four-command workflow with clear agent responsibilities:

graph LR
    A[/create-repo-plan] -->|creates| B[Draft Plan]
    B -->|triggers| C[/review-plan]
    C -->|validates| D[Reviewed Plan]
    D -->|triggers| E[/complete-plan]
    E -->|executes| F[In-Progress/Completed]
    F -->|validates| G[/review-completed-plan]

Command-Agent Mapping:

• /create-repo-plan → Plan Agent (write to content/metadata/plans/**)
• /review-plan → Review Agent (read + bash inspection)
• /review-completed-plan → Review Agent (read + bash verification)
• /complete-plan → Build Agent (full execution permissions)

Context Discovery Strategy:

1. Conversation History: Check for recent plan creation/discussion in session
2. Path Inference: Use plan type (repo) + conversation context to infer path
3. Interactive Fallback: If ambiguous, list available plans and prompt user selection

Status Lifecycle:

Draft → Ready for Review → Reviewed → In Progress → Completed → Verified

Tradeoffs & Decisions

Implementation Steps

Phase 1: Command File Creation & Agent Configuration Updates

Human Decision Point: Validate command file structures and agent permission updates before proceeding.

Step 1.1: Rename and Update /create-plan to /create-repo-plan

Tasks:

1. Rename .opencode/commands/create-plan.md to create-repo-plan.md
2. Update command description to specify “repository-level implementation plan”
3. Update output format to enforce content/metadata/plans/[NN-topic-name]/rev1.md naming
4. Add frontmatter template with Status field initialization:

   ---
   Version: 1.0
   Date: YYYY-MM-DD
   Status: Draft - Ready for Review
   Changelog:
     - v1.0: Initial draft
   ---

5. Add instruction to set status to “Draft - Ready for Review” upon creation

Deliverable: .opencode/commands/create-repo-plan.md with repository-specific context

Verification: Run /create-repo-plan test-feature and confirm:

• File created at correct path with rev1.md naming
• Frontmatter includes Status field set to “Draft - Ready for Review”
• Plan agent has write permission to content/metadata/plans/**

Dependencies: Updated Plan agent write permissions (already completed)

Step 1.2: Create /review-plan Command

Tasks:

1. Create .opencode/commands/review-plan.md with following structure:

---
description: Review a plan for quality, feasibility, and alignment with best practices
agent: review
subtask: true
model: anthropic/claude-sonnet-4.5
---

2. Implement context discovery logic:

   • Check conversation history for recent /create-repo-plan invocation
   • If $ARGUMENTS provided, treat as explicit path
   • If no context, search content/metadata/plans/ for recent plans (by date modified)
   • Present interactive selection if multiple candidates found

3. Define review checklist structure using question tool:

   questions:
     - header: "Plan Completeness"
       options:
         - All required sections present
         - Executive summary clear and comprehensive
         - Implementation steps actionable
         - Success criteria measurable
     - header: "Technical Feasibility"
       options:
         - Prerequisites clearly identified
         - Dependencies documented
         - Risk assessment adequate
         - Integration points addressed
     # ... additional checklist items

4. Add instructions to:

   • Use bash commands (grep, cat, ls, git) to inspect repository state
   • Compare plan against existing decisions and related plans
   • Validate plan structure matches template in /create-repo-plan
   • Update Status field to “Reviewed - Ready for Execution” if approved
   • Document review findings in plan directory as REVIEW_FINDINGS.md

Deliverable: .opencode/commands/review-plan.md with context-aware review workflow

Verification:

1. Create test plan with /create-repo-plan
2. Run /review-plan without arguments (should auto-discover)
3. Confirm interactive checklist presented
4. Verify bash inspection commands used (check for git diff, grep, etc. in output)
5. Confirm Status field updated to “Reviewed - Ready for Execution”

Dependencies: Review agent bash permissions (already completed)

Step 1.3: Create /complete-plan Command

Tasks:

1. Create .opencode/commands/complete-plan.md with following structure:

---
description: Execute an implementation plan phase-by-phase with validation gates
agent: build
subtask: true
model: anthropic/claude-sonnet-4.5
---

2. Implement context discovery (same strategy as /review-plan)

3. Add phase execution logic:

   • Parse plan phases (look for ”## Phase N:” headers or ”### Phase N:” markers)
   • Execute tasks within each phase sequentially
   • After completing phase, pause and present validation checklist
   • Update Status field to “In Progress - Phase N of M” during execution
   • Update to “Completed” when all phases done

4. Add fallback logic for issues:

   • If Status ≠ “Reviewed - Ready for Execution”, trigger interactive validation:

     ⚠️ Warning: This plan has not been reviewed or status is unclear.
     
     Current Status: [STATUS]
     
     Questions:
     - Is this plan ready for execution?
     - Should review be performed first?
     - Are there known blockers?
     

   • If descrepancies found (missing files, unclear steps), document and ask clarifying questions

   • Create EXECUTION_LOG.md in plan directory documenting progress and blockers

5. Add phase completion confirmation:

   • After each phase, present checklist via question tool:

     questions:
       - header: "Phase [N] Validation"
         options:
           - All tasks in phase completed
           - Deliverables produced and verified
           - No blockers for next phase
           - Continue to Phase [N+1]

Deliverable: .opencode/commands/complete-plan.md with phase-aware execution

Verification:

1. Create and review test plan with multiple phases
2. Run /complete-plan
3. Confirm execution pauses after Phase 1 with validation checklist
4. Verify Status field updates to “In Progress - Phase 1 of 3”
5. Complete all phases and confirm final Status = “Completed”
6. Check EXECUTION_LOG.md created with progress documentation

Dependencies:

• Build agent permissions (already has full access)
• Reviewed plan with Status = “Reviewed - Ready for Execution”

Step 1.4: Create /review-completed-plan Command

Tasks:

1. Create .opencode/commands/review-completed-plan.md with following structure:

---
description: Validate completed plan execution against original requirements and success criteria
agent: review
subtask: true
model: anthropic/claude-sonnet-4.5
---

2. Implement context discovery (same strategy as previous commands)

3. Define completion validation checklist:

   questions:
     - header: "Deliverable Verification"
       options:
         - All planned deliverables produced
         - Files/directories created as specified
         - Tests passing (if applicable)
         - Documentation updated
     - header: "Success Criteria Met"
       options:
         - Measurable outcomes achieved
         - Acceptance criteria satisfied
         - No regression issues introduced
     - header: "Quality Assessment"
       options:
         - Code follows best practices
         - Integration points working
         - Error handling adequate
         - Performance acceptable

4. Add instructions to:

   • Use bash commands to verify file existence, run tests, check git status
   • Compare actual implementation against plan steps
   • Review EXECUTION_LOG.md for blockers or deviations
   • Document findings in COMPLETION_REVIEW.md
   • Update Status field to “Verified - Complete” if all checks pass
   • If issues found, set Status to “Requires Rework” and document issues

Deliverable: .opencode/commands/review-completed-plan.md with verification workflow

Verification:

1. Complete test plan execution with /complete-plan
2. Run /review-completed-plan
3. Confirm checklist validates actual deliverables against plan
4. Verify bash commands used to inspect filesystem/git state
5. Check COMPLETION_REVIEW.md created with findings
6. Confirm Status updated to “Verified - Complete”

Dependencies:

• Review agent bash permissions (already completed)
• Completed plan with Status = “Completed”

Phase 2: Documentation & Testing

Human Decision Point: Review command implementations, validate full workflow with end-to-end test, approve documentation updates.

Step 2.1: Create Workflow Documentation

Tasks:

1. Create content/metadata/plans/03 Agentic Primitives - Repository/WORKFLOW.md documenting:

   • Command sequence and purpose
   • Agent responsibilities at each stage
   • Status lifecycle diagram
   • Context discovery behavior
   • Interactive checklist examples
   • Troubleshooting common issues

2. Update .opencode/AGENTS.md if needed (document Review agent’s expanded bash permissions)

3. Create example walkthrough in content/metadata/plans/03 Agentic Primitives - Repository/EXAMPLE_WALKTHROUGH.md

Deliverable: Comprehensive workflow documentation

Verification: Documentation includes all commands, clear examples, and troubleshooting guidance

Dependencies: All commands implemented and tested

Step 2.2: End-to-End Workflow Test

Tasks:

1. Test complete workflow with realistic scenario:

   /create-repo-plan example-feature-implementation
   → Verify plan created with correct frontmatter
   
   /review-plan
   → Verify auto-discovery works
   → Complete interactive checklist
   → Confirm status updated to "Reviewed"
   
   /complete-plan
   → Verify phase-by-phase execution
   → Complete phase validations
   → Confirm status updates during execution
   
   /review-completed-plan
   → Verify deliverables checked
   → Confirm final status "Verified - Complete"
   

2. Test edge cases:

   • /review-plan with no recent plan (should trigger interactive selection)
   • /complete-plan on unreviewed plan (should trigger warning and fallback)
   • /review-completed-plan on incomplete plan (should document issues)
   • Multiple plans in progress (context discovery should handle correctly)

3. Document test results in content/metadata/plans/03 Agentic Primitives - Repository/TEST_RESULTS.md

Deliverable: Validated workflow with test results documentation

Verification: All commands work correctly in sequence and handle edge cases gracefully

Dependencies: All commands implemented, documentation complete

Step 2.3: Update Create-Plan Command Documentation

Tasks:

1. Update command help/description in create-repo-plan.md to reference workflow

2. Add “Next Steps” section at end of plan creation:

   ## Next Steps
   
   Your plan has been created at: content/metadata/plans/[NN-topic]/rev1.md
   Status: Draft - Ready for Review
   
   Recommended workflow:
   1. Run `/review-plan` to validate plan quality
   2. Address any review feedback
   3. Run `/complete-plan` to execute implementation
   4. Run `/review-completed-plan` to verify completion
   

Deliverable: Updated command documentation with workflow guidance

Verification: Command output includes next steps and workflow reference

Dependencies: Workflow testing complete

Decision Points & Options

Decision 1: Support File Naming Convention

Options:

1. All caps with underscores (current): REVIEW_FINDINGS.md, EXECUTION_LOG.md
   • Pros: Consistent with existing DECISIONS_SUMMARY.md, CLARIFICATIONS_NEEDED.md
   • Cons: Less aesthetic, may be harder to read
2. Lowercase with hyphens: review-findings.md, execution-log.md
   • Pros: Follows common markdown conventions, easier to type
   • Cons: Breaks consistency with existing pattern

Recommendation: Use all caps with underscores to maintain consistency with established repository conventions.

Decision 2: Revision File Naming When Plan Updated

Options:

1. Increment revision file (current pattern): rev1.md → rev2.md for major changes

   • Pros: Clear version history, supports rollback
   • Cons: More complex command logic, need to determine when to increment

2. In-place updates with changelog: Keep rev1.md, update frontmatter changelog

   • Pros: Simpler command logic, single source of truth
   • Cons: Loses explicit version history, harder to compare versions

Recommendation: Use in-place updates with changelog for review/completion updates, reserve revision file increment for major plan restructuring (manual decision).

Decision 3: Interactive Selection UI Pattern

Options:

1. Question tool with plan list: Use OpenCode’s built-in question tool

   • Pros: Consistent UX, follows OpenCode patterns
   • Cons: May be verbose for long plan lists

2. Simple text prompt with numbered list: Print list, ask for number

   • Pros: More compact, faster for power users
   • Cons: Inconsistent with OpenCode UX patterns

Recommendation: Use question tool with plan list for consistency with OpenCode.ai design patterns.

Risk Assessment

Risk 1: Context Discovery Ambiguity

Description: Multiple plans in progress simultaneously could confuse auto-discovery logic.

Mitigation:

• Prioritize most recent plan by modification date
• Include plan status in selection criteria (prefer “Draft” for review, “Reviewed” for completion)
• Always show plan path in interactive selection for user verification
• Allow explicit path override via $ARGUMENTS

Likelihood: Medium | Impact: Medium

Risk 2: Status Field Consistency

Description: Different agents updating status could lead to inconsistent values or race conditions.

Mitigation:

• Define explicit status vocabulary in command documentation
• Each command only updates to specific status values (create→Draft, review→Reviewed, etc.)
• Use consistent status format: “[State] - [Context]” (e.g., “In Progress - Phase 2 of 4”)
• Document status lifecycle in workflow documentation

Likelihood: Low | Impact: Medium

Risk 3: Phase Detection Reliability

Description: Plan formatting variations could break phase detection in /complete-plan.

Mitigation:

• Define phase marker standards in /create-repo-plan template
• Support multiple phase formats (## Phase N:, Phase N:, Phase N:)
• Fallback to sequential step execution if no phases detected
• Add phase validation to /review-plan checklist

Likelihood: Medium | Impact: High

Risk 4: Permission Boundary Violations

Description: Commands might attempt operations outside agent permission boundaries.

Mitigation:

• Plan agent write permission explicitly scoped to content/metadata/plans/**/*
• Review agent bash permission explicitly allows only read operations
• Build agent already has full permissions (by design)
• Test permission boundaries during Phase 2 testing

Likelihood: Low | Impact: Low (caught by OpenCode permission system)

Success Criteria

Measurable Outcomes

1. ✅ Four command files created and functional:

   • /create-repo-plan creates plan with correct frontmatter
   • /review-plan validates plan and updates status
   • /complete-plan executes phases and tracks progress
   • /review-completed-plan verifies completion against criteria

2. ✅ Context discovery works in 90%+ of typical use cases without explicit path argument

3. ✅ Status field accurately reflects plan lifecycle stage throughout workflow

4. ✅ Interactive checklists provide clear validation at each stage

5. ✅ End-to-end workflow test completes successfully without manual intervention

Acceptance Criteria

• All command files created in .opencode/commands/ directory
• Commands correctly assigned to appropriate agents (plan, review, build)
• Context discovery implemented with conversation history + interactive fallback
• Interactive checklists use OpenCode question tool consistently
• Status field updates automatically at each workflow stage
• Phase-by-phase execution works with human validation gates
• Support files (REVIEW_FINDINGS.md, EXECUTION_LOG.md, COMPLETION_REVIEW.md) created correctly
• Documentation complete (WORKFLOW.md, EXAMPLE_WALKTHROUGH.md, TEST_RESULTS.md)
• Edge cases handled gracefully (no plan found, wrong status, multiple plans)
• Agent permissions validated (no violations during testing)

Appendices

Appendix A: Status Vocabulary Reference

Status Values:
  - "Draft - Ready for Review" # After /create-repo-plan
  - "Reviewed - Ready for Execution" # After /review-plan (passed)
  - "Requires Revision" # After /review-plan (issues found)
  - "In Progress - Phase N of M" # During /complete-plan
  - "In Progress - Awaiting Clarification" # /complete-plan paused for questions
  - "Completed" # After /complete-plan finishes
  - "Verified - Complete" # After /review-completed-plan (passed)
  - "Requires Rework" # After /review-completed-plan (issues found)

Appendix B: Command File Template Structure

---
description: [Brief command description]
agent: [plan|review|build]
subtask: true
model: anthropic/claude-sonnet-4.5
---
 
# [Command Name]: $ARGUMENTS
 
You are the [Agent Name] [creating/reviewing/executing] [description].
 
## Context Discovery
 
[Instructions for finding plan file from conversation history or arguments]
 
## Primary Workflow
 
[Step-by-step instructions for command execution]
 
## Interactive Elements
 
[Question tool usage for checklists/validation]
 
## Status Management
 
[Instructions for updating Status field in frontmatter]
 
## Output/Deliverables
 
[What files/updates this command produces]
 
## Error Handling
 
[Fallback behavior for edge cases]

Appendix C: Example Plan Context Discovery Logic

## Context Discovery Algorithm
 
1. **Check $ARGUMENTS**: If path provided, use directly
2. **Check Conversation History**: Look for recent mentions of:
   - `/create-repo-plan [topic]` invocation
   - Plan file paths (content/metadata/plans/[NN-topic]/\*)
   - Plan topics or titles
3. **Infer from Plan Type**: If command is `/review-plan` (no prefix), default to `content/metadata/plans/`
 
4. **Search Recent Plans**:
   ```bash
   find content/metadata/plans/ -name "rev*.md" -type f -mtime -7 | sort -r
   ```

5. Filter by Status (if applicable):
   • /review-plan: Prefer “Draft” status
   • /complete-plan: Prefer “Reviewed” status
   • /review-completed-plan: Prefer “Completed” status
6. Interactive Selection: If multiple candidates:
   • Use question tool to present list
   • Show: Plan number, title, status, last modified date
   • Include “Type your own path” option

---

### Appendix D: Troubleshooting Guide

**Issue**: Context discovery can't find plan
- **Solution**: Use explicit path: `/review-plan content/metadata/plans/05-my-feature/rev1.md`

**Issue**: Status field not updating
- **Solution**: Check agent write permissions for plan directory, verify frontmatter format

**Issue**: Phase detection not working in `/complete-plan`
- **Solution**: Ensure phases marked with `## Phase N:` or `### Phase N:` headers

**Issue**: `/complete-plan` asks too many clarifying questions
- **Solution**: Improve plan specificity in implementation steps, include code examples

**Issue**: Multiple agents trying to update same plan simultaneously
- **Solution**: Workflow is sequential by design—complete one command before starting next

---

## Summary of Key Decisions

1. **Command Naming**: Explicit type prefix (`/create-repo-plan`) enables future expansion
2. **Status Updates**: Automatic frontmatter updates track lifecycle without manual overhead
3. **Context Discovery**: Auto-discover with interactive fallback balances UX and clarity
4. **Execution Model**: Phase-by-phase with validation gates respects human intervention points
5. **Support Files**: All-caps naming convention maintains consistency with existing patterns
6. **Review Format**: Interactive checklists via question tool follow OpenCode UX standards

---

**End of Plan**