From cade6ce2f7f28023ec0669217934666772743568 Mon Sep 17 00:00:00 2001 From: oxedom Date: Sun, 25 Jan 2026 19:57:06 +0200 Subject: [PATCH] workflow --- .../user-guide/raw-plan-implement-workflow.md | 374 ++++++++++++++++++ docs/workflows/raw-plan-implement.md | 291 ++++++++++++++ packages/backend/src/services/workflow.ts | 64 +++ .../tests/unit/services/workflow.test.ts | 116 ++++++ 4 files changed, 845 insertions(+) create mode 100644 docs/user-guide/raw-plan-implement-workflow.md create mode 100644 docs/workflows/raw-plan-implement.md diff --git a/docs/user-guide/raw-plan-implement-workflow.md b/docs/user-guide/raw-plan-implement-workflow.md new file mode 100644 index 0000000..b4cfe3c --- /dev/null +++ b/docs/user-guide/raw-plan-implement-workflow.md @@ -0,0 +1,374 @@ +# User Guide: Raw - Plan β†’ Implement Workflow + +## What is the Raw - Plan β†’ Implement Workflow? + +The **Raw - Plan β†’ Implement** workflow is a two-phase process designed for complex tasks where you want an AI to first plan a solution carefully, then implement it based on that plan. This workflow is particularly useful when: + +- You're working on a significant architectural change +- The task requires careful upfront design +- You want to review the approach before implementation begins +- You need clear documentation of the implementation strategy + +## How It Works + +### Phase 1: Planning & Design + +In the first phase, the AI will: + +1. **Understand Your Request**: Read and comprehend what you want to build or change +2. **Explore the Codebase**: Analyze existing code patterns, architecture, and conventions +3. **Identify Challenges**: Understand what might be difficult or complex +4. **Design the Solution**: Create a detailed plan for how to approach the problem +5. **Document Everything**: Produce a comprehensive planning document + +**Output**: A planning document that includes: +- What the task is asking for +- How the existing codebase is structured +- What patterns and approaches work in this codebase +- Specific files that need to be created or modified +- Dependencies and integration points +- Known risks and how to avoid them +- Testing strategy + +**Duration**: Phase 1 typically takes several minutes for the AI to thoroughly explore your codebase and create a detailed plan. + +### Phase Transition: Review Planning + +After Phase 1 completes, you'll see: + +1. **Planning Summary**: A brief summary of the approach +2. **Full Planning Document**: The complete analysis and design +3. **Review Opportunity**: Chance to read the plan before proceeding +4. **Confirmation Prompt**: Option to proceed to implementation + +You can: +- βœ… Proceed to implementation if the plan looks good +- πŸ“– Read the full planning document if you want more details +- πŸ›‘ Stop and adjust if something doesn't look right + +### Phase 2: Implementation + +In the second phase, the AI will: + +1. **Review the Plan**: Read and understand the planning document +2. **Implement According to Plan**: Write code exactly as designed +3. **Write Tests**: Create tests as specified in the plan +4. **Document Results**: Record what was implemented + +**Output**: Your code is now implemented according to the carefully designed plan from Phase 1. + +**Duration**: Phase 2 typically takes several minutes to implement and test the changes. + +## Getting Started + +### Step 1: Create a New Mission + +1. Open Haflow and click "New Mission" +2. Give your task a title (e.g., "Add user authentication to the app") +3. Select the workflow type (feature, fix, enhance, etc.) +4. Describe what you want to do in "Raw Input" + +### Step 2: Select the Workflow + +Look for the workflow selection dropdown: + +``` +[Raw Research Plan] | [Oneshot] | [Raw - Plan β†’ Implement] +``` + +Select **"Raw - Plan β†’ Implement"** for your complex task. + +### Step 3: Provide Clear Input + +Write a clear description of what you want: + +❌ **Too vague:** +``` +Add login functionality +``` + +βœ… **Better:** +``` +Add user authentication to the web app using JWT tokens. +Requirements: +- User login with email and password +- JWT token issued on login +- Token stored in secure cookies +- Logout functionality +- Protected routes only accessible when logged in +``` + +### Step 4: Wait for Phase 1 + +The AI will: +- Explore your codebase (several minutes) +- Analyze the architecture +- Design an implementation approach +- Create a detailed planning document + +You'll see progress as the AI works. + +### Step 5: Review the Plan + +When Phase 1 completes: + +1. **Read the Summary**: Quick overview of the approach +2. **Review the Full Document**: Detailed analysis and design +3. **Check for Issues**: Does the plan make sense? + +### Step 6: Proceed to Phase 2 + +Once you're satisfied with the plan, click "Continue to Implementation" + +The AI will: +- Read the planning document +- Implement the changes +- Write tests +- Validate the implementation + +### Step 7: Review the Implementation + +When Phase 2 completes: + +1. **View the Results**: Summary of what was implemented +2. **Review the Code**: See the changes made +3. **Run Tests**: Use quick commands to verify +4. **Approve or Adjust**: Complete or request changes + +## Example: Adding a Feature + +### Scenario: Add an Admin Dashboard + +**Input:** +``` +Add an admin dashboard to the application that allows admin users to: +- View statistics about the system +- Manage user accounts +- View system logs +- Configure application settings + +Admins should be identified by a role in the database. +The dashboard should only be accessible to admin users. +``` + +**Phase 1 Planning Output:** +``` +## Planning Document: Admin Dashboard Implementation + +### Problem Summary +Create a web-based admin dashboard with restricted access, +statistics display, user management, and configuration features. + +### Current Architecture +- Frontend: React with TailwindCSS +- Backend: Express.js with PostgreSQL +- Authentication: JWT-based +- Users table has a 'role' column + +### Implementation Approach +1. Create AdminDashboard.tsx React component +2. Add admin role check to protected routes +3. Create API endpoints for: + - GET /api/admin/stats + - GET /api/admin/users + - PUT /api/admin/users/:id + - GET /api/admin/logs + - POST /api/admin/settings +4. Create database queries for statistics +5. Add role-based access control middleware + +### Files to Create/Modify +- New: src/components/AdminDashboard.tsx +- New: src/api/admin.ts +- Modify: src/routes.ts (add admin routes) +- Modify: src/middleware/auth.ts (add adminOnly check) +- New: db/admin-queries.sql + +### Risks +- Users could access admin endpoints without role check +Mitigation: Always verify role in middleware + +### Testing Strategy +- Unit tests for role verification +- Integration tests for each admin endpoint +- E2E test for full dashboard flow +``` + +**Phase 2 Implementation:** +- Creates AdminDashboard component +- Adds API endpoints +- Implements role verification +- Writes tests +- All changes follow the plan + +**Result:** +- Admin dashboard is implemented and tested +- All changes follow the planned approach +- Code quality is maintained +- Tests pass + +## Tips & Best Practices + +### 1. Be Clear in Your Input + +The better you describe the task, the better the plan: + +- βœ… Explain what you want to build +- βœ… List specific requirements +- βœ… Mention constraints or preferences +- βœ… Reference existing code patterns you like + +### 2. Review the Planning Document Carefully + +The planning document is your guide: + +- πŸ“– Read the "Implementation Approach" section carefully +- ❓ Ask yourself: "Does this make sense?" +- ⚠️ If something seems wrong, you can pause before Phase 2 +- πŸ’‘ Use the planning document to understand what will happen + +### 3. Understand the Scope + +Phase 1 helps you understand if the task is: + +- 🟒 Simple and straightforward +- 🟑 Moderate complexity +- πŸ”΄ Very complex and risky + +If the plan seems too complex, you might want to break it into smaller tasks. + +### 4. Use Phase Transition Wisely + +At the transition between phases: + +- βœ… Proceed if the plan looks good +- πŸ›‘ Stop and refine if something seems off +- πŸ“ The planning document can guide manual work if needed + +### 5. Choose the Right Workflow + +When to use "Raw - Plan β†’ Implement": + +- βœ… Complex architectural changes +- βœ… When you want to review the approach first +- βœ… When careful design is important +- βœ… Major refactoring efforts + +**When to use other workflows:** + +- Use "Oneshot" for simple changes that don't need planning +- Use "Raw Research Plan" for understanding requirements without implementation + +## Understanding the Planning Document + +### What's in the Planning Document? + +1. **Problem Statement**: Clear understanding of what to build +2. **Architecture Overview**: How the existing system works +3. **Implementation Approach**: Step-by-step how to build it +4. **File Changes**: Exactly which files to create/modify +5. **Dependencies**: What else needs to be in place +6. **Risks**: What could go wrong and how to prevent it +7. **Testing Strategy**: How to verify it works + +### How to Read It + +```markdown +# Planning Document: My Feature + +## Problem Summary +[Quick overview of what we're building] + +## Current Architecture +[How the system currently works] + +## Implementation Approach +[Step-by-step plan] + +## Files to Create/Modify +[Specific list with what changes in each file] + +## Dependencies +[What needs to be true for this to work] + +## Risks +[What could go wrong] + +## Testing Strategy +[How to test it] +``` + +## Troubleshooting + +### Phase 1 is Taking a Long Time + +**What's happening?** The AI is exploring your codebase thoroughly to understand it. + +**What to do:** Wait. This is normal for complex codebases. Typically takes 2-5 minutes. + +### The Planning Document Seems Incomplete + +**What to do:** +1. Review the document carefully +2. If critical information is missing, you can: + - Pause and provide more input + - Move forward if you're confident in the approach + +### I Don't Like the Planned Approach + +**What to do:** +1. Note what concerns you +2. You can: + - Proceed anyway if it's acceptable + - Stop and start a new mission with adjusted input + - Provide specific feedback for the approach + +### Phase 2 Implementation Doesn't Match the Plan + +**What to do:** +1. Review the implementation against the planning document +2. If there are discrepancies: + - Note them in your review + - The implementation phase emphasizes plan adherence + - You can request corrections + +## Comparing Workflows + +| Aspect | Raw - Plan β†’ Implement | Oneshot | Raw Research Plan | +|--------|----------------------|---------|-------------------| +| **Phases** | 2 (Plan + Implement) | 1 (Direct Coding) | Full 8-step pipeline | +| **Best For** | Complex tasks needing design | Quick changes | Comprehensive analysis | +| **Planning** | Explicit phase 1 | None | Integrated in pipeline | +| **Review Point** | Between phases | After completion | Multiple gates | +| **Time** | Moderate | Fast | Slower | +| **When to Use** | Architectural changes | Simple fixes | Big features | + +## Common Questions + +**Q: What if I don't like the plan?** +A: You can stop before Phase 2 and try again with different input, or proceed anyway. + +**Q: Can I modify the plan before Phase 2?** +A: Currently, the workflow is fixed. You can stop, adjust your request, and start over. + +**Q: How long does each phase take?** +A: Planning typically takes 2-5 minutes. Implementation varies based on complexity (2-10 minutes). + +**Q: Can I use this workflow for documentation?** +A: Yes! You can ask it to plan and implement documentation improvements. + +**Q: Is the planning output saved?** +A: Yes! The planning document is saved as an artifact in your mission history. + +**Q: Can I share the planning document?** +A: Yes! The planning document is part of your mission and can be reviewed at any time. + +## Next Steps + +1. Create your first mission with this workflow +2. Observe the planning phase in action +3. Review the planning document carefully +4. Proceed to implementation +5. Validate the results + +The "Raw - Plan β†’ Implement" workflow is powerful for complex tasks. Start with clear input, review the plan carefully, and you'll get great results! diff --git a/docs/workflows/raw-plan-implement.md b/docs/workflows/raw-plan-implement.md new file mode 100644 index 0000000..ea37f00 --- /dev/null +++ b/docs/workflows/raw-plan-implement.md @@ -0,0 +1,291 @@ +# Raw - Plan β†’ Implement Workflow + +## Overview + +The **Raw - Plan β†’ Implement** workflow is a two-phase workflow designed for complex tasks that benefit from explicit separation between planning and implementation. This workflow enables users to: + +1. **Phase 1 (Planning & Design)**: Thoroughly explore the problem space, analyze the codebase, and design a comprehensive implementation approach +2. **Phase 2 (Implementation)**: Execute the plan with full context from Phase 1, ensuring implementation fidelity to the designed approach + +This workflow is ideal for: +- Complex feature implementations +- Major refactoring efforts +- Architectural changes +- Tasks requiring significant upfront design +- Situations where planning and implementation benefits from explicit separation + +## Workflow Architecture + +``` +Raw - Plan β†’ Implement +β”‚ +β”œβ”€ Phase 1: Planning & Design (Agent Step) +β”‚ β”œβ”€ Input: raw-input.md (user request) +β”‚ β”œβ”€ Output: planning-output.md (planning document) +β”‚ └─ Mode: Document (analysis and planning) +β”‚ +β”œβ”€ Human Review: Review Planning (Human Gate) +β”‚ β”œβ”€ Reviews: planning-output.md +β”‚ └─ User Confirms: Ready to proceed to implementation +β”‚ +β”œβ”€ Phase 2: Implementation (Agent Step) +β”‚ β”œβ”€ Input: planning-output.md (Phase 1 output) +β”‚ β”œβ”€ Output: implementation-result.json (implementation summary) +β”‚ └─ Mode: Codegen (code changes and testing) +β”‚ +└─ Final Review: Review Implementation (Code Review Gate) + β”œβ”€ Quick Commands: npm test, npm lint, npm run build + └─ User Approves: Implementation complete +``` + +## Workflow Definition + +The workflow is defined in `/workspace/packages/backend/src/services/workflow.ts`: + +```typescript +'raw-plan-implement': { + workflow_id: 'raw-plan-implement', + name: 'Raw - Plan β†’ Implement', + steps: [ + { + step_id: 'plan', + name: 'Phase 1: Planning & Design', + type: 'agent', + agent: 'planning-agent', + inputArtifact: 'raw-input.md', + outputArtifact: 'planning-output.md', + workspaceMode: 'document' + }, + { + step_id: 'review-plan', + name: 'Review Planning', + type: 'human-gate', + reviewArtifact: 'planning-output.md', + workspaceMode: 'document' + }, + { + step_id: 'implement', + name: 'Phase 2: Implementation', + type: 'agent', + agent: 'impl-agent', + inputArtifact: 'planning-output.md', + outputArtifact: 'implementation-result.json', + workspaceMode: 'codegen' + }, + { + step_id: 'review-impl', + name: 'Review Implementation', + type: 'code-review', + workspaceMode: 'codegen', + quickCommands: ['npm test', 'npm run lint', 'npm run build'] + } + ] +} +``` + +## Context Passing Mechanism + +The workflow implements context passing between phases: + +- **Phase 1 Output**: The `plan` step writes its analysis and design to `planning-output.md` +- **Phase 2 Input**: The `implement` step reads `planning-output.md` as its input artifact +- **System Instructions**: The implementation phase prompt explicitly references and instructs the agent to follow the planning document +- **Full Context**: The planning document provides complete context about the problem, approach, and design decisions + +This ensures Phase 2 always has access to the design decisions and analysis from Phase 1. + +## System Instructions + +### Phase 1: Planning & Design + +The planning phase prompt instructs the agent to: + +1. Understand the user's request from `raw-input.md` +2. Explore the codebase to understand architecture, patterns, and conventions +3. Analyze requirements and identify key challenges +4. Design a comprehensive implementation approach with clear architecture +5. Document findings in a structured planning document + +The planning document should include: +- Problem statement and requirements summary +- Codebase architecture overview and relevant patterns +- Proposed implementation approach with architecture decisions +- List of files to create/modify with specific changes +- Dependencies and integration points +- Known risks and mitigation strategies +- Testing strategy and success criteria + +**Key Characteristic**: Phase 1 focuses on analysis, exploration, and planningβ€”NOT implementation or code changes. + +### Phase 2: Implementation + +The implementation phase prompt instructs the agent to: + +1. Read and understand the planning document from Phase 1 +2. Explore the codebase to confirm patterns referenced in the plan +3. Implement changes exactly according to the plan +4. Write tests as specified in the planning document +5. Document what was done in `implementation-result.json` + +**Key Characteristic**: Phase 2 focuses on executing the plan with fidelity, using the planning document as the source of truth. + +## Integration with Haflow System + +### Workflow Discovery + +The workflow is automatically discovered through the standard Haflow discovery mechanism: + +1. Backend `getWorkflows()` function returns all workflows from the WORKFLOWS object +2. API endpoint `/api/workflows` exposes all workflows +3. Frontend automatically fetches and displays all available workflows +4. Users can select the workflow from the UI + +### Execution Flow + +1. User creates a mission with the `raw-plan-implement` workflow +2. First step (`plan`) is automatically executed +3. After Phase 1 completes, mission transitions to human gate +4. User reviews the planning document and confirms to proceed +5. Phase 2 implementation step starts with Phase 1 planning as input +6. After Phase 2 completes, mission transitions to code review gate +7. User reviews the implementation and approves completion + +### Storage and Persistence + +- Planning output is stored as artifact: `~/.haflow/missions/m-/artifacts/planning-output.md` +- Implementation output is stored as artifact: `~/.haflow/missions/m-/artifacts/implementation-result.json` +- Step executions are tracked in `~/.haflow/missions/m-/runs/r-.json` +- Logs for each step are stored in `~/.haflow/missions/m-/logs/` + +## Extending the Workflow + +### Modifying Phase Instructions + +To adjust the planning or implementation phase behavior: + +1. Edit the relevant prompt in `STEP_PROMPTS` in `/workspace/packages/backend/src/services/workflow.ts` +2. Update the `plan` or `implement` prompt as needed +3. Ensure the prompt still references the correct input/output artifacts +4. Add `COMPLETE` marker at the end + +### Adding Custom Agents + +To use different agents for the phases: + +1. Modify the `agent` property in the step definition (currently `planning-agent` and `impl-agent`) +2. Ensure the agent is registered in the Haflow agent system +3. The agent will be used for execution when the step is reached + +### Adding Tools per Phase + +To add phase-specific tools: + +1. Extend the system instructions to reference available tools +2. Tools are inherited from the base agent configuration +3. Phase-specific tool selection is handled through system instructions + +## Testing the Workflow + +### Unit Tests + +Unit tests for the workflow are located in `/workspace/packages/backend/tests/unit/services/workflow.test.ts`: + +- Workflow is registered and discoverable +- Workflow can be retrieved by ID +- Workflow has correct structure (4 steps) +- Steps are in correct order +- Step types are correct +- Phase sequencing is correct +- Context passing is properly configured +- Prompts contain required elements + +Run tests: +```bash +pnpm --filter @haflow/backend test -- workflow.test.ts +``` + +### Integration Tests + +Integration tests verify the workflow integrates correctly with: +- Workflow registry and discovery +- Mission creation and execution +- Frontend UI +- Artifact storage and retrieval +- Step sequencing and transitions + +### Manual Testing + +To manually test the workflow: + +1. Start the backend: `pnpm --filter @haflow/backend dev` +2. Start the frontend: `pnpm --filter frontend dev` +3. Open the UI and create a new mission +4. Select "Raw - Plan β†’ Implement" workflow +5. Provide a task description +6. Observe Phase 1 execution (planning) +7. Review the planning document +8. Confirm to proceed to Phase 2 +9. Observe Phase 2 execution (implementation) +10. Review the implementation results + +## Architecture Decisions + +### Why Two Distinct Phases? + +The workflow separates planning and implementation to provide: + +1. **Explicit Design Review**: Users can review the approach before implementation +2. **Clear Separation of Concerns**: Planning focuses on understanding; implementation focuses on execution +3. **Flexibility**: Users can request plan adjustments before implementation begins +4. **Better Context**: Phase 2 has full context of design decisions from Phase 1 + +### Why Use Document Mode for Phase 1? + +Phase 1 uses document mode because: +- Focus is on analysis and documentation, not code changes +- No need for full codebase access or test execution +- Cleaner separation between planning and implementation workspaces + +### Why Use Codegen Mode for Phase 2? + +Phase 2 uses codegen mode because: +- Full codebase access needed to implement changes +- Tests must be run to validate implementation +- Code must be written and tested + +## Troubleshooting + +### Planning Phase Takes Too Long + +If Phase 1 planning takes excessive time: +- Consider if the task might be better suited for the full 8-step workflow +- Ensure the user request is clear and well-structured +- The planning agent may be exploring too thoroughlyβ€”this is expected behavior + +### Implementation Doesn't Follow Plan + +If Phase 2 implementation diverges from the plan: +- Ensure the planning document was clear and specific +- The implementation prompt emphasizes plan adherence +- User can review and ask for corrections + +### Phase 2 Can't Read Planning Output + +This should not happen in normal operation, but if it does: +- Verify the planning output artifact was created correctly +- Check that the step's inputArtifact points to `planning-output.md` +- Check mission logs for errors during Phase 1 + +## Files Involved + +| File | Purpose | +|------|---------| +| `/packages/backend/src/services/workflow.ts` | Workflow definition and prompts | +| `/packages/backend/tests/unit/services/workflow.test.ts` | Unit tests | +| `/docs/workflows/raw-plan-implement.md` | This documentation | + +## Related Documentation + +- [Workflow System Overview](./README.md) +- [Haflow Architecture](../architecture.md) +- [User Guide: Raw - Plan β†’ Implement Workflow](../user-guide/raw-plan-implement-workflow.md) diff --git a/packages/backend/src/services/workflow.ts b/packages/backend/src/services/workflow.ts index 518c25f..9c7979a 100644 --- a/packages/backend/src/services/workflow.ts +++ b/packages/backend/src/services/workflow.ts @@ -24,6 +24,16 @@ const WORKFLOWS: Record = { { step_id: 'review', name: 'Review', type: 'code-review', workspaceMode: 'codegen', quickCommands: ['git status'] }, ], }, + 'raw-plan-implement': { + workflow_id: 'raw-plan-implement', + name: 'Raw - Plan β†’ Implement', + steps: [ + { step_id: 'plan', name: 'Phase 1: Planning & Design', type: 'agent', agent: 'planning-agent', inputArtifact: 'raw-input.md', outputArtifact: 'planning-output.md', workspaceMode: 'document' }, + { step_id: 'review-plan', name: 'Review Planning', type: 'human-gate', reviewArtifact: 'planning-output.md', workspaceMode: 'document' }, + { step_id: 'implement', name: 'Phase 2: Implementation', type: 'agent', agent: 'impl-agent', inputArtifact: 'planning-output.md', outputArtifact: 'implementation-result.json', workspaceMode: 'codegen' }, + { step_id: 'review-impl', name: 'Review Implementation', type: 'code-review', workspaceMode: 'codegen', quickCommands: ['npm test', 'npm run lint', 'npm run build'] }, + ], + }, }; // Step-specific prompts for Claude agents @@ -119,6 +129,60 @@ Your task: Focus on: correctness, code quality, following project patterns. When you are satisfied with the implementation, include COMPLETE at the end of your response.`, + + 'plan': `You are in the PLANNING & DESIGN phase of a two-phase workflow. Your role is to thoroughly understand the requirements, explore the codebase, and design a comprehensive implementation approach. + +Read the file "raw-input.md" and create a detailed planning document. + +Your task: +1. Read raw-input.md to understand the user's request +2. Explore the codebase to understand existing architecture, patterns, and conventions +3. Analyze the requirements and identify key challenges +4. Design a comprehensive implementation approach with clear architecture +5. Document all findings and create a detailed planning document +6. Write the planning document to "planning-output.md" + +The planning document should include: +- Problem statement and requirements summary +- Codebase architecture overview and relevant patterns +- Proposed implementation approach with architecture decisions +- List of files to create/modify with specific changes +- Dependencies and integration points +- Known risks and mitigation strategies +- Testing strategy and success criteria + +DO NOT implement or write code during this phase. Focus on thorough exploration and clear documentation. + +When you have completed the planning document, include COMPLETE at the end of your response.`, + + 'implement': `You are in the IMPLEMENTATION phase of a two-phase workflow. You have completed planning in Phase 1. + +You have the following planning document from Phase 1: "planning-output.md" + +Your task: +1. Read the planning document (planning-output.md) to understand the design and approach +2. Explore the codebase to understand existing patterns (referenced in the planning document) +3. Implement the planned changes by modifying files in the project according to the plan +4. Write tests as specified in the planning document +5. Ensure code quality and follows existing project conventions +6. Document what was done in "artifacts/implementation-result.json" with format: + { + "status": "completed" | "partial" | "blocked", + "filesCreated": ["path/to/file1", ...], + "filesModified": ["path/to/file2", ...], + "testsAdded": ["test descriptions..."], + "notes": "any important notes about the implementation" + } + +Implementation guidelines: +- Reference the planning document for architecture and approach +- Implement changes exactly according to the plan +- Follow existing code patterns and conventions documented in the plan +- Create tests as specified +- If you encounter issues requiring plan adjustment, explicitly note and propose solutions aligned with the original intent +- Focus on correctness, code quality, and plan adherence + +When you are satisfied with the implementation and all success criteria from the plan are met, include COMPLETE at the end of your response.`, }; // Get the prompt for a specific step diff --git a/packages/backend/tests/unit/services/workflow.test.ts b/packages/backend/tests/unit/services/workflow.test.ts index 03de4f7..d39e56c 100644 --- a/packages/backend/tests/unit/services/workflow.test.ts +++ b/packages/backend/tests/unit/services/workflow.test.ts @@ -4,6 +4,8 @@ import { getDefaultWorkflow, getWorkflowStepName, getStepPrompt, + getWorkflows, + getWorkflowById, } from '../../../src/services/workflow.js'; describe('workflow service', () => { @@ -148,4 +150,118 @@ describe('workflow service', () => { } }); }); + + describe('raw-plan-implement workflow', () => { + it('workflow is registered and discoverable', () => { + const workflows = getWorkflows(); + const rawPlanImpl = workflows.find(w => w.workflow_id === 'raw-plan-implement'); + expect(rawPlanImpl).toBeDefined(); + }); + + it('can be retrieved by ID', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow).toBeDefined(); + expect(workflow?.workflow_id).toBe('raw-plan-implement'); + }); + + it('has correct name', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow?.name).toBe('Raw - Plan β†’ Implement'); + }); + + it('has 4 steps', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow?.steps).toHaveLength(4); + }); + + it('steps are in correct order: plan β†’ review-plan β†’ implement β†’ review-impl', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow?.steps[0].step_id).toBe('plan'); + expect(workflow?.steps[1].step_id).toBe('review-plan'); + expect(workflow?.steps[2].step_id).toBe('implement'); + expect(workflow?.steps[3].step_id).toBe('review-impl'); + }); + + it('step types are correct: agent β†’ human-gate β†’ agent β†’ code-review', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow?.steps[0].type).toBe('agent'); + expect(workflow?.steps[1].type).toBe('human-gate'); + expect(workflow?.steps[2].type).toBe('agent'); + expect(workflow?.steps[3].type).toBe('code-review'); + }); + + it('planning phase uses document mode', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow?.steps[0].workspaceMode).toBe('document'); + expect(workflow?.steps[1].workspaceMode).toBe('document'); + }); + + it('implementation phase uses codegen mode', () => { + const workflow = getWorkflowById('raw-plan-implement'); + expect(workflow?.steps[2].workspaceMode).toBe('codegen'); + expect(workflow?.steps[3].workspaceMode).toBe('codegen'); + }); + + it('agent steps have inputArtifact and outputArtifact', () => { + const workflow = getWorkflowById('raw-plan-implement'); + const agentSteps = workflow?.steps.filter(s => s.type === 'agent'); + + for (const step of agentSteps || []) { + expect(step.inputArtifact).toBeDefined(); + expect(step.outputArtifact).toBeDefined(); + } + }); + + it('human-gate steps have reviewArtifact', () => { + const workflow = getWorkflowById('raw-plan-implement'); + const humanGateSteps = workflow?.steps.filter(s => s.type === 'human-gate'); + + for (const step of humanGateSteps || []) { + expect(step.reviewArtifact).toBeDefined(); + } + }); + + it('planning output is input to implementation phase (context passing)', () => { + const workflow = getWorkflowById('raw-plan-implement'); + const planningStep = workflow?.steps[0]; + const implementationStep = workflow?.steps[2]; + + expect(planningStep?.outputArtifact).toBe('planning-output.md'); + expect(implementationStep?.inputArtifact).toBe('planning-output.md'); + }); + + it('planning step has planning-focused prompt', () => { + const workflow = getWorkflowById('raw-plan-implement'); + const planStep = workflow?.steps[0]; + const prompt = getStepPrompt(planStep!); + + expect(prompt).toContain('PLANNING & DESIGN phase'); + expect(prompt).toContain('raw-input.md'); + expect(prompt).toContain('planning-output.md'); + expect(prompt).toContain('plan'); + expect(prompt).toContain('COMPLETE'); + }); + + it('implementation step has implementation-focused prompt with plan reference', () => { + const workflow = getWorkflowById('raw-plan-implement'); + const implStep = workflow?.steps[2]; + const prompt = getStepPrompt(implStep!); + + expect(prompt).toContain('IMPLEMENTATION phase'); + expect(prompt).toContain('planning-output.md'); + expect(prompt).toContain('planning document'); + expect(prompt).toContain('implementation-result.json'); + expect(prompt).toContain('COMPLETE'); + }); + + it('code-review step has appropriate quick commands', () => { + const workflow = getWorkflowById('raw-plan-implement'); + const reviewStep = workflow?.steps[3]; + + expect(reviewStep?.quickCommands).toBeDefined(); + expect(reviewStep?.quickCommands).toContain('npm test'); + expect(reviewStep?.quickCommands).toContain('npm run lint'); + expect(reviewStep?.quickCommands).toContain('npm run build'); + }); + }); });