workflow

# Workflow

You are tasked with orchestrating the complete research->plan->implement workflow for a given task or requirement. This command manages the entire pipeline from initial research through implementation.

## Initial Setup

When this command is invoked, respond with:
```
I'll orchestrate the complete workflow for your task.

This will include:
1. **Research**: Comprehensive investigation of the problem space
2. **Planning**: Creating a detailed implementation plan
3. **Implementation**: Executing the plan with verification

Please provide:
- The task/feature/bug you want to address
- Any specific constraints or requirements
- Whether you want to run the full pipeline or start from a specific phase

You can also say "workflow continue" if you have existing research or plans.
```

Then wait for the user's input.

### Phase 0: Project State Check

Before starting any workflow phase, check for persistent project state:

1. **Check for `.planning/` directory**:
   - If exists: Read `.planning/STATE.md` to understand current position
   - Load `.planning/ROADMAP.md` for phase context
   - Resume from where STATE.md indicates

2. **If `.planning/` does NOT exist**:
   - Ask: "Would you like to set up persistent project state? This tracks requirements, roadmap, and decisions across sessions."
   - If yes: Initialize from templates
     ```bash
     mkdir -p .planning/phases .planning/todos
     ```
   - Copy templates from `{{HOME_TOOL_DIR}}/templates/planning/` to `.planning/`
   - Guide user through filling in PROJECT.md (vision + constraints)
   - If no: Continue with standard workflow (backward compatible)

3. **If `.planning/` exists and has ROADMAP.md**:
   - Identify current phase from STATE.md
   - Check if current phase has CONTEXT.md (decisions captured)
   - If no CONTEXT.md: Suggest running `/discuss` before planning
   - Load phase context for downstream commands

## Workflow Phases

### Phase 1: Research

If no existing research found in `research/` directory:

1. **Invoke research phase**:
   - Call the `/research` command internally
   - Conduct comprehensive multi-modal research
   - Save findings to `research/YYYY-MM-DD_HH-MM-SS_topic.md`

2. **Review research output**:
   - Read the generated research document
   - Identify key findings and constraints
   - Note any open questions that need clarification

3. **Present research summary**:
   ```
   ## Research Complete

   Key findings:
   - [Major discovery 1]
   - [Major discovery 2]
   - [Important constraint]

   The research has been saved to: research/[filename].md

   Shall I proceed to create an implementation plan based on these findings?
   ```

### Phase 2: Planning

After research is complete or if existing research is found:

1. **Invoke planning phase**:
   - Call the `/plan` command with research context
   - Reference the research document findings
   - Create detailed, phased implementation plan

2. **Interactive planning**:
   - Work with user to refine the plan
   - Ensure all phases have clear success criteria
   - Save to `plans/descriptive_name.md`

3. **Present plan summary**:
   ```
   ## Plan Complete

   Implementation will be done in [N] phases:
   1. [Phase 1 name] - [objective]
   2. [Phase 2 name] - [objective]
   ...

   The plan has been saved to: plans/[filename].md

   Ready to begin implementation?
   ```

### Phase 3: Implementation

After plan is approved:

1. **Invoke implementation**:
   - Call the `/implement` command with plan path
   - Execute phase by phase
   - Track progress with TodoWrite

2. **Progress tracking**:
   - Update checkmarks in plan as phases complete
   - Run verification after each phase
   - Handle any issues that arise

3. **Present completion status**:
   ```
   ## Implementation Status

   Phase 1: [Name] - Complete
   Phase 2: [Name] - Complete
   Phase 3: [Name] - Partial (see notes)

   Verification Results:
   - Tests: [status]
   - Linting: [status]
   - Build: [status]

   Would you like me to run validation on the implementation?
   ```

### Phase 4: Validation (Optional)

If requested or if issues found:

1. **Run validation**:
   - Execute all automated checks
   - Verify against plan success criteria
   - Generate validation report

2. **Present validation results**:
   ```
   ## Validation Report

   Automated Checks:
   All tests passing
   Linting clean
   Build successful

   Plan Criteria:
   [Criterion 1] - Verified
   [Criterion 2] - Verified
   [Criterion 3] - Needs manual verification

   The implementation is ready for review.
   ```

### Phase 5: Knowledge Capture (Suggested)

After successful implementation, offer to capture learnings:

```
## Capture Learnings?

This task is complete. If you encountered any problems worth documenting
for future reference, consider running:

   /compound

This will:
- Capture the solution as a searchable learning
- Save it to docs/solutions/ for future sessions
- Make it discoverable via /research

Useful when:
- You debugged a tricky issue
- You found a non-obvious solution
- You want to remember "the fix" for next time

Skip this if the work was straightforward with no notable discoveries.
```

### .planning/ State Updates

After each major phase transition, update `.planning/STATE.md`:
- After Research: Update "Last activity", add key findings to "Recent Decisions"
- After Plan: Update phase status, link to plan file
- After Implement: Update progress, mark completed requirements
- After Validate: Record validation status, update blockers if any

## Workflow Commands

The user can control the workflow with these commands:

- **`workflow start`** - Begin from research phase
- **`workflow continue`** - Resume from existing research/plan
- **`workflow skip-research`** - Start directly with planning
- **`workflow validate`** - Run validation on completed work
- **`workflow status`** - Show current progress

## Progress Tracking

Throughout the workflow, maintain a master todo list:

```
Master Workflow: [Task Name]
[ ] Research Phase
  [ ] Codebase analysis
  [ ] Documentation review
  [ ] External research (if needed)
  [ ] Synthesize findings
[ ] Planning Phase
  [ ] Review research
  [ ] Draft plan structure
  [ ] Detail each phase
  [ ] Define success criteria
[ ] Implementation Phase
  [ ] Phase 1: [Name]
  [ ] Phase 2: [Name]
  [ ] Phase 3: [Name]
[ ] Validation Phase
  [ ] Run automated tests
  [ ] Verify success criteria
  [ ] Generate report
```

Update this list as you progress through each phase.

## Handling Interruptions

If the workflow is interrupted:

1. **Save state**:
   - Document what phase you're in
   - Note what's been completed
   - Save any partial work

2. **On resume**:
   - Check for existing research in `research/`
   - Check for existing plans in `plans/`
   - Look for checkmarks in plans indicating progress
   - Continue from where you left off

## Best Practices

1. **Always start with research** unless explicitly told to skip
2. **Plans must reference research findings** to ensure alignment
3. **Implementation must follow the plan** (adapt if needed, but document deviations)
4. **Validation is not optional** for production-ready code
5. **Keep the user informed** at each phase transition
6. **Use TodoWrite** to track detailed progress

## Example Usage

```
User: /workflow
Assistant: I'll orchestrate the complete workflow for your task...

User: Add OAuth2 authentication to the application
Assistant: I'll start by researching OAuth2 implementations and your current auth setup...
[Runs research phase]
[Creates plan based on research]
[Implements with user approval]
[Validates the implementation]
```

## Integration with Other Commands

This workflow command internally calls:
- `/research` - For investigation phase
- `/plan` - For planning phase
- `/implement` - For execution phase
- `/validate` - For verification phase (if created)

Each command can also be run independently if needed.