opencode-skills-collection 4.0.53 → 4.0.55

package/bundled-skills/build/references/detailed-guide.md

@@ -0,0 +1,637 @@
+# build - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Instructions
+
+This command manages a 4-phase feature development workflow for building major features. Parse `$ARGUMENTS` to determine which subcommand to run.
+
+**Arguments provided:** $ARGUMENTS
+
+### Argument Parsing
+
+Parse the first word of $ARGUMENTS to determine the subcommand:
+
+- `research [name]` → Run the Research phase
+- `implementation [name]` → Run the Implementation phase
+- `progress [name]` → Run the Progress phase
+- `phase [n] [name]` → Run Phase n of the implementation
+- `status [name]` → Show current status and suggest next step
+- (empty or unrecognized) → Show usage help
+
+If the feature name is not provided in arguments, you MUST use AskUserQuestion to prompt for it.
+
+---
+
+
+## Subcommand: Help (empty args)
+
+If no arguments provided, display this help:
+
+```
+/build - Feature Development Pipeline
+
+Subcommands:
+  /build research [name]        Deep research on a feature idea
+  /build implementation [name]  Create phased implementation plan
+  /build progress [name]        Set up progress tracking
+  /build phase [n] [name]       Execute implementation phase n
+  /build status [name]          Show status and next steps
+
+Example workflow:
+  /build research chat-interface
+  /build implementation chat-interface
+  /build progress chat-interface
+  /build phase 1 chat-interface
+```
+
+Then use AskUserQuestion to ask what they'd like to do:
+
+- question: "What would you like to do?"
+- header: "Action"
+- multiSelect: false
+- options:
+  - label: "Start new feature research"
+    description: "Begin deep research on a new feature idea"
+  - label: "Continue existing feature"
+    description: "Work on a feature already in progress"
+  - label: "Check status"
+    description: "See what step to do next for a feature"
+
+---
+
+
+## Subcommand: research
+
+### Step 1: Get Feature Name
+
+If feature name not in arguments, use AskUserQuestion:
+
+- question: "What's a short identifier for this feature? (lowercase, hyphens ok - e.g., 'chat-interface', 'user-auth', 'data-export'). Use 'Other' to type it."
+- header: "Feature name"
+- multiSelect: false
+- options:
+  - label: "I'll type the name"
+    description: "Enter a short, kebab-case identifier for the feature"
+
+### Step 2: Check for Existing Research
+
+Check if `docs/{name}/RESEARCH.md` already exists.
+
+If it exists, use AskUserQuestion:
+
+- question: "A RESEARCH.md already exists for this feature. What would you like to do?"
+- header: "Existing doc"
+- multiSelect: false
+- options:
+  - label: "Overwrite"
+    description: "Replace existing research with fresh exploration"
+  - label: "Append"
+    description: "Add new research below existing content"
+  - label: "Skip"
+    description: "Keep existing research, suggest next step"
+
+If "Skip" selected, suggest running `/build implementation {name}` and exit.
+
+### Step 3: Gather Feature Context
+
+Use AskUserQuestion to understand the feature:
+
+- question: "Describe the feature you want to build. What problem does it solve? What should it do? (Use 'Other' to describe)"
+- header: "Description"
+- multiSelect: false
+- options:
+  - label: "I'll describe it"
+    description: "Provide a detailed description of the feature"
+
+### Step 4: Research Scope
+
+Use AskUserQuestion:
+
+- question: "What aspects should the research focus on?"
+- header: "Focus areas"
+- multiSelect: true
+- options:
+  - label: "Technical implementation"
+    description: "APIs, libraries, architecture patterns"
+  - label: "UI/UX design"
+    description: "Interface design, user flows, interactions"
+  - label: "Data requirements"
+    description: "What data to store, schemas, privacy"
+  - label: "Platform capabilities"
+    description: "OS APIs, system integrations, permissions"
+
+### Step 5: Conduct Deep Research
+
+Now conduct DEEP research on the feature:
+
+1. **Codebase exploration**: Understand existing patterns, similar features, relevant code
+2. **Web search**: Research best practices, similar implementations, relevant APIs
+3. **Technical deep-dive**: Explore specific technologies, libraries, frameworks
+4. **Use AskUserQuestion FREQUENTLY**: Validate assumptions, clarify requirements, get input on decisions
+
+Research should cover:
+- Problem definition and user needs
+- Technical approaches and trade-offs
+- Required data models and storage
+- UI/UX considerations
+- Integration points with existing code
+- Potential challenges and risks
+- Recommended approach with rationale
+
+### Step 6: Write Research Document
+
+Create the directory if needed: `docs/{name}/`
+
+Write findings to `docs/{name}/RESEARCH.md` with this structure:
+
+```markdown
+# {Feature Name} Research
+
+## Overview
+[Brief description of the feature and its purpose]
+
+## Problem Statement
+[What problem this solves, why it matters]
+
+## User Stories / Use Cases
+[Concrete examples of how users will use this]
+
+## Technical Research
+
+### Approach Options
+[Different ways to implement this, with pros/cons]
+
+### Recommended Approach
+[The approach you recommend and why]
+
+### Required Technologies
+[APIs, libraries, frameworks needed]
+
+### Data Requirements
+[What data needs to be stored/tracked]
+
+## UI/UX Considerations
+[Interface design thoughts, user flows]
+
+## Integration Points
+[How this connects to existing code/features]
+
+## Risks and Challenges
+[Potential issues and mitigation strategies]
+
+## Open Questions
+[Things that still need to be decided]
+
+## References
+[Links to relevant documentation, examples, articles]
+```
+
+### Step 7: Next Step
+
+After writing the research doc, inform the user:
+
+"Research complete! Document saved to `docs/{name}/RESEARCH.md`
+
+**Next step:** Run `/build implementation {name}` to create a phased implementation plan."
+
+---
+
+
+## Subcommand: implementation
+
+### Step 1: Get Feature Name
+
+If feature name not in arguments, use AskUserQuestion to prompt for it (same as research phase).
+
+### Step 2: Verify Research Exists
+
+Check if `docs/{name}/RESEARCH.md` exists.
+
+If it does NOT exist:
+- Inform user: "No research document found at `docs/{name}/RESEARCH.md`"
+- Suggest: "Run `/build research {name}` first to create the research document."
+- Exit
+
+### Step 3: Check for Existing Implementation Doc
+
+Check if `docs/{name}/IMPLEMENTATION.md` already exists.
+
+If it exists, use AskUserQuestion:
+
+- question: "An IMPLEMENTATION.md already exists. What would you like to do?"
+- header: "Existing doc"
+- multiSelect: false
+- options:
+  - label: "Overwrite"
+    description: "Create a fresh implementation plan"
+  - label: "Append"
+    description: "Add new phases below existing content"
+  - label: "Skip"
+    description: "Keep existing plan, suggest next step"
+
+If "Skip" selected, suggest running `/build progress {name}` and exit.
+
+### Step 4: Read Research Document
+
+Read `docs/{name}/RESEARCH.md` to understand:
+- The recommended approach
+- Technical requirements
+- Data models needed
+- UI/UX design
+- Integration points
+
+### Step 5: Design Implementation Phases
+
+Break the research into practical implementation phases. Each phase should:
+- Be independently valuable (deliver something usable)
+- Be small enough to complete in a focused session
+- Build on previous phases
+- Have clear success criteria
+
+Use AskUserQuestion to validate phase breakdown:
+
+- question: "How granular should the implementation phases be?"
+- header: "Phase size"
+- multiSelect: false
+- options:
+  - label: "Small phases (1-2 hours)"
+    description: "Many focused phases, easier to track progress"
+  - label: "Medium phases (half day)"
+    description: "Balanced approach, moderate number of phases"
+  - label: "Large phases (full day)"
+    description: "Fewer phases, each delivering significant functionality"
+
+### Step 6: Conduct Phase Research
+
+For each phase you're planning, do targeted research:
+- Web search for implementation specifics
+- Review relevant code in the codebase
+- Identify dependencies between phases
+
+Use AskUserQuestion for any uncertainties about phase ordering or scope.
+
+### Step 7: Write Implementation Document
+
+Write to `docs/{name}/IMPLEMENTATION.md` with this structure:
+
+```markdown
+# {Feature Name} Implementation Plan
+
+## Overview
+[Brief recap of what we're building and the approach from research]
+
+## Prerequisites
+[What needs to be in place before starting]
+
+## Phase Summary
+[Quick overview of all phases]
+
+---
+
+## Phase 1: [Phase Title]
+
+### Objective
+[What this phase accomplishes]
+
+### Rationale
+[Why this phase comes first, what it enables]
+
+### Tasks
+- [ ] Task 1
+- [ ] Task 2
+- [ ] Task 3
+
+### Success Criteria
+[How to verify this phase is complete]
+
+### Files Likely Affected
+[List of files that will probably need changes]
+
+---
+
+## Phase 2: [Phase Title]
+
+[Same structure as Phase 1]
+
+---
+
+[Continue for all phases]
+
+---
+
+## Post-Implementation
+- [ ] Documentation updates
+- [ ] Testing strategy
+- [ ] Performance validation
+
+## Notes
+[Any additional context or decisions made during planning]
+```
+
+### Step 8: Next Step
+
+After writing the implementation doc, inform the user:
+
+"Implementation plan complete! Document saved to `docs/{name}/IMPLEMENTATION.md`
+
+**Next step:** Run `/build progress {name}` to set up progress tracking."
+
+---
+
+
+## Subcommand: progress
+
+### Step 1: Get Feature Name
+
+If feature name not in arguments, use AskUserQuestion to prompt for it.
+
+### Step 2: Verify Implementation Doc Exists
+
+Check if `docs/{name}/IMPLEMENTATION.md` exists.
+
+If it does NOT exist:
+- Inform user: "No implementation document found at `docs/{name}/IMPLEMENTATION.md`"
+- Suggest: "Run `/build implementation {name}` first."
+- Exit
+
+### Step 3: Check for Existing Progress Doc
+
+Check if `docs/{name}/PROGRESS.md` already exists.
+
+If it exists, use AskUserQuestion:
+
+- question: "A PROGRESS.md already exists. What would you like to do?"
+- header: "Existing doc"
+- multiSelect: false
+- options:
+  - label: "Overwrite"
+    description: "Start fresh progress tracking"
+  - label: "Keep existing"
+    description: "Keep current progress, suggest next step"
+
+If "Keep existing" selected, read the progress doc and suggest the next incomplete phase.
+
+### Step 4: Read Implementation Document
+
+Read `docs/{name}/IMPLEMENTATION.md` to extract:
+- All phase titles
+- Tasks within each phase
+- Success criteria
+
+### Step 5: Create Progress Document
+
+Write to `docs/{name}/PROGRESS.md` with this structure:
+
+```markdown
+# {Feature Name} Progress
+
+## Status: Phase 1 - Not Started
+
+## Quick Reference
+- Research: `docs/{name}/RESEARCH.md`
+- Implementation: `docs/{name}/IMPLEMENTATION.md`
+
+---
+
+## Phase Progress
+
+### Phase 1: [Title from Implementation]
+**Status:** Not Started
+
+#### Tasks Completed
+- (none yet)
+
+#### Decisions Made
+- (none yet)
+
+#### Blockers
+- (none)
+
+---
+
+### Phase 2: [Title]
+**Status:** Not Started
+
+[Same structure]
+
+---
+
+[Continue for all phases]
+
+---
+
+## Session Log
+
+### [Date will be added as work happens]
+- Work completed
+- Decisions made
+- Notes for next session
+
+---
+
+## Files Changed
+(Will be updated as implementation progresses)
+
+## Architectural Decisions
+(Major technical decisions and rationale)
+
+## Lessons Learned
+(What worked, what didn't, what to do differently)
+```
+
+### Step 6: Next Step
+
+After creating progress doc:
+
+"Progress tracking set up! Document saved to `docs/{name}/PROGRESS.md`
+
+**Next step:** Run `/build phase 1 {name}` to begin implementation."
+
+---
+
+
+## Subcommand: phase
+
+### Step 1: Parse Arguments
+
+Parse arguments to extract:
+- Phase number (if provided)
+- Feature name (if provided)
+
+If neither provided, prompt for both using AskUserQuestion.
+
+### Step 2: Get Feature Name
+
+If feature name not determined, use AskUserQuestion to prompt for it.
+
+### Step 3: Verify All Docs Exist
+
+Check that all three docs exist:
+- `docs/{name}/RESEARCH.md`
+- `docs/{name}/IMPLEMENTATION.md`
+- `docs/{name}/PROGRESS.md`
+
+If any missing, inform user which doc is missing and suggest the appropriate `/build` command to create it.
+
+### Step 4: Get Phase Number
+
+If phase number not in arguments:
+
+Read `docs/{name}/IMPLEMENTATION.md` to extract available phases.
+
+Use AskUserQuestion to let user select:
+
+- question: "Which phase would you like to work on?"
+- header: "Phase"
+- multiSelect: false
+- options: [dynamically generated from phases found in IMPLEMENTATION.md, marking completed ones]
+
+### Step 5: Read All Context
+
+Read all three documents to fully understand:
+- The research and rationale (RESEARCH.md)
+- The specific phase tasks and success criteria (IMPLEMENTATION.md)
+- Current progress and decisions made (PROGRESS.md)
+
+### Step 6: Deep Research on Phase
+
+Before starting implementation:
+
+1. **Web search** for specific implementation details relevant to this phase
+2. **Codebase exploration** for relevant existing code
+3. **Use AskUserQuestion** to clarify any ambiguities about the phase requirements
+
+### Step 7: Execute Phase Work
+
+Begin implementing the phase:
+
+1. Work through each task in the phase
+2. Use AskUserQuestion frequently for implementation decisions
+3. Follow the "Always Works" philosophy - test as you go
+4. Document decisions in PROGRESS.md as you make them
+
+### Step 8: Update Progress Document
+
+As you work, update `docs/{name}/PROGRESS.md`:
+
+- Mark tasks as completed
+- Record decisions made and why
+- Note any blockers encountered
+- List files changed
+- Add architectural decisions
+- Update the session log with today's work
+
+Update the phase status:
+- "In Progress" when starting
+- "Completed" when all tasks done and success criteria met
+
+### Step 9: Next Step
+
+After completing the phase:
+
+1. Read PROGRESS.md to determine next incomplete phase
+2. Inform user of completion and suggest next action:
+
+"Phase {n} complete! Progress updated in `docs/{name}/PROGRESS.md`
+
+**Next step:** Run `/build phase {n+1} {name}` to continue with [next phase title]."
+
+Or if all phases complete:
+
+"All phases complete! The {feature name} feature implementation is done.
+
+Consider:
+- Running tests to verify everything works
+- Updating documentation
+- Creating a PR for review"
+
+---
+
+
+## Subcommand: status
+
+### Step 1: Get Feature Name
+
+If feature name not in arguments, use AskUserQuestion to prompt for it.
+
+### Step 2: Check Which Docs Exist
+
+Check for existence of:
+- `docs/{name}/RESEARCH.md`
+- `docs/{name}/IMPLEMENTATION.md`
+- `docs/{name}/PROGRESS.md`
+
+### Step 3: Determine Status and Next Step
+
+Based on which docs exist:
+
+**No docs exist:**
+"No documents found for feature '{name}'.
+**Next step:** Run `/build research {name}` to start."
+
+**Only RESEARCH.md exists:**
+"Research complete for '{name}'.
+**Next step:** Run `/build implementation {name}` to create implementation plan."
+
+**RESEARCH.md and IMPLEMENTATION.md exist:**
+"Research and implementation plan complete for '{name}'.
+**Next step:** Run `/build progress {name}` to set up progress tracking."
+
+**All three exist:**
+Read PROGRESS.md to find current phase status.
+"Feature '{name}' is in progress.
+**Current status:** [Phase X - status]
+**Next step:** Run `/build phase {next incomplete phase} {name}` to continue."
+
+If all phases complete:
+"Feature '{name}' implementation is complete!"
+
+---
+
+
+## Important Guidelines
+
+### Use AskUserQuestion Liberally
+
+Throughout all phases, use AskUserQuestion whenever:
+- There's ambiguity in requirements
+- Multiple approaches are possible
+- You need to validate an assumption
+- A decision will significantly impact the implementation
+- You're unsure about scope or priority
+
+### Deep Research Expectations
+
+"Deep research" means:
+- Multiple web searches on different aspects
+- Thorough codebase exploration
+- Reading relevant documentation
+- Considering multiple approaches
+- Understanding trade-offs
+
+Don't rush through research - it's the foundation for good implementation.
+
+### Progress Tracking
+
+Keep PROGRESS.md updated in real-time during phase work:
+- Don't wait until the end to update
+- Record decisions as they're made
+- Note blockers immediately
+- This creates valuable context for future sessions
+
+### Scope Management
+
+A key purpose of this workflow is preventing scope creep:
+- Each phase should have clear boundaries
+- If new requirements emerge, note them for future phases
+- Don't expand the current phase's scope mid-implementation
+- Use AskUserQuestion to validate if something is in/out of scope
+
+### Always Works Philosophy
+
+When implementing phases:
+- Test changes as you make them
+- Don't assume code works - verify it
+- If something doesn't work, fix it before moving on
+- The goal is working software, not just written code