@exaudeus/workrail 0.1.9 → 0.1.10

package/dist/application/decorators/simple-output-decorator.js

@@ -33,7 +33,7 @@ The MCP server is STATELESS. You MUST send required data with each request:
 **EXAMPLE - Loop Context:**
 \`\`\`json
 {
-  "workflowId": "coding-task-workflow",
+  "workflowId": "coding-task-workflow-with-loops",
   "completedSteps": ["phase-1", "phase-2", "loop-step-1"],
   "context": {
     // Required: condition/template variables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "MCP server for structured workflow orchestration and step-by-step task guidance",
   "license": "MIT",
   "bin": {

package/spec/mcp-api-v1.0.md

@@ -175,7 +175,7 @@ Retrieves workflow information with configurable detail level. Supports progress
   "jsonrpc": "2.0",
   "id": 2,
   "result": {
-    "id": "coding-task-workflow",
+    "id": "coding-task-workflow-with-loops",
     "name": "Excellent Adaptive Coding Workflow",
     "description": "A comprehensive workflow for AI-assisted coding",
     "version": "0.1.0",
@@ -201,7 +201,7 @@ Retrieves workflow information with configurable detail level. Supports progress
   "jsonrpc": "2.0",
   "id": 2,
   "result": {
-    "id": "coding-task-workflow",
+    "id": "coding-task-workflow-with-loops",
     "name": "Excellent Adaptive Coding Workflow",
     "description": "A comprehensive workflow for AI-assisted coding",
     "version": "0.1.0",

package/spec/examples/coding-task-workflow.json

@@ -1,160 +0,0 @@
-{
-    "id": "coding-task-workflow",
-    "name": "Excellent Adaptive Coding Workflow with Devil's Advocate Review",
-    "version": "0.0.1",
-    "description": "A comprehensive and resilient workflow for AI-assisted coding. It adaptively sizes tasks, performs a critical self-review of its own plans, provides efficiency options, enforces closed-loop validation, and defines a robust protocol for handling failures.",
-    "preconditions": [
-        "User has a clear task description (e.g., from Jira, a dev doc, or a BRD).",
-        "The agent has access to necessary tools like `grep`, file readers/editors, and a terminal for commands.",
-        "The agent has access to the relevant codebase files."
-    ],
-    "metaGuidance": [
-        "This workflow follows the PREP -> IMPLEMENT -> VERIFY pattern for each step in the plan.",
-        "Human approval is required after the Devil's Advocate review and before final completion.",
-        "Each implementation step should be a small, logical, and committable chunk of work.",
-        "The agent should never guess or assume. Always ask for clarification or use tools to find missing information.",
-        "Maintain existing coding conventions and architectural patterns found in the codebase."
-    ],
-    "steps": [
-        {
-            "id": "phase-0-intelligent-triage",
-            "title": "Phase 0: Intelligent Task Triage & Complexity Analysis",
-            "prompt": "**ANALYZE**: Evaluate the provided task for complexity indicators:\n\n**Small Path Indicators:**\n- Single function changes or minor refactoring\n- Clear bug fixes with obvious solutions\n- Simple configuration changes\n- Low risk of side effects\n- Well-defined, narrow scope\n\n**Medium Path Indicators:**\n- Multi-file changes or moderate features\n- Standard development work\n- Some unknowns but manageable scope\n- Moderate complexity with clear boundaries\n- Requires planning but not architectural analysis\n\n**Large Path Indicators:**\n- Architectural changes or major features\n- Unfamiliar codebase areas\n- High complexity or significant risk\n- Multiple system interactions\n- Requires deep analysis and careful planning\n\n**IMPLEMENT**: \n1. Analyze the task description for the above indicators\n2. Recommend a complexity level (Small/Medium/Large) with detailed reasoning\n3. Set the taskComplexity context variable\n4. Ask user if they agree or want to override your classification\n5. For Medium tasks, ask: \"Would you like optional deep codebase analysis?\" (sets requestDeepAnalysis context variable)\n\n**VERIFY**: Confirm the complexity classification and any optional analysis preferences before proceeding.",
-            "guidance": [
-                "Be thorough in your analysis - this determines the entire workflow path",
-                "Consider both technical complexity and business risk",
-                "When in doubt, err on the side of more thorough analysis (higher complexity)",
-                "Always allow human override of your classification",
-                "Set context variables that will be used for conditional step execution"
-            ],
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-1-scoping",
-            "runCondition": {
-                "var": "taskComplexity",
-                "not_equals": "Small"
-            },
-            "title": "Phase 1: Task Briefing & Scope Definition",
-            "prompt": "Your first goal is to understand the task. Analyze the following request, summarize your understanding, ask clarifying questions, and assess which parts of the codebase are relevant.\n\n**Task Description:**\n[User inserts detailed task description here]\n\n**Key Objectives & Success Criteria:**\n[User lists specific, measurable success criteria here]\n\n**Scope and Constraints:**\n[User defines boundaries or areas to avoid here]\n\nFinally, based on your analysis, perform a sanity check on the initial complexity sizing. If you believe the classification is incorrect, state your reasoning and ask for confirmation before proceeding. For example: 'You classified this as Medium, but my analysis shows it impacts several core architectural components. I recommend we upgrade to the Large path to perform a Deep Analysis. Do you agree?'",
-            "guidance": [
-                "Provide a complete task description. Vague requests will lead to poor plans and wasted effort.",
-                "This step is automatically skipped for Small tasks based on the complexity classification"
-            ]
-        },
-        {
-            "id": "phase-1b-deep-analysis-mandatory",
-            "runCondition": {
-                "var": "taskComplexity",
-                "equals": "Large"
-            },
-            "title": "Phase 1b: Mandatory Deep Codebase Analysis",
-            "prompt": "Your goal is to become an expert on the attached codebase. This deep analysis is mandatory for Large tasks due to their complexity and risk. Your analysis must include:\n1.  **Architecture:** Main modules, layers, and patterns.\n2.  **Key Concepts:** Core models, conventions, and important components.\n3.  **Execution Flow:** Trace major features or entry points.\n4.  **Code Quality Assessment:** Note maintainability, readability, or coupling issues.\n5.  **Testing Strategy:** Describe how the code is tested.\n6.  **Opportunities:** Suggest refactorings or improvements.\n\nProvide summaries and code examples to illustrate your findings. Be exhaustive, as if preparing onboarding documentation for a senior engineer.",
-            "askForFiles": true,
-            "guidance": [
-                "This step is mandatory for Large tasks due to their complexity and risk",
-                "Ensure all relevant source files are attached or accessible to the agent before running this step",
-                "Be thorough - this analysis will inform the entire implementation strategy"
-            ]
-        },
-        {
-            "id": "phase-1b-deep-analysis-optional",
-            "runCondition": {
-                "and": [
-                    {
-                        "var": "taskComplexity",
-                        "equals": "Medium"
-                    },
-                    {
-                        "var": "requestDeepAnalysis",
-                        "equals": true
-                    }
-                ]
-            },
-            "title": "Phase 1b: Optional Deep Codebase Analysis",
-            "prompt": "You requested optional deep analysis for this Medium task. Your goal is to become an expert on the attached codebase. Your analysis must include:\n1.  **Architecture:** Main modules, layers, and patterns.\n2.  **Key Concepts:** Core models, conventions, and important components.\n3.  **Execution Flow:** Trace major features or entry points.\n4.  **Code Quality Assessment:** Note maintainability, readability, or coupling issues.\n5.  **Testing Strategy:** Describe how the code is tested.\n6.  **Opportunities:** Suggest refactorings or improvements.\n\nProvide summaries and code examples to illustrate your findings. Be exhaustive, as if preparing onboarding documentation for a senior engineer.",
-            "askForFiles": true,
-            "guidance": [
-                "This optional analysis was requested for a Medium task",
-                "Ensure all relevant source files are attached or accessible to the agent before running this step",
-                "Focus on areas most relevant to the current task"
-            ]
-        },
-        {
-            "id": "phase-2-planning",
-            "runCondition": {
-                "var": "taskComplexity",
-                "not_equals": "Small"
-            },
-            "title": "Phase 2: Create Detailed Implementation Plan",
-            "prompt": "Your goal is to produce a thorough and actionable plan of attack. Do not write any code. Your plan must be detailed, broken into committable phases, and justified.\n\nYour plan must include these sections:\n1.  **Goal Clarification:** Your understanding of the goal, assumptions, and success criteria.\n2.  **Impact Assessment:** Affected codebase parts, dependencies, and risks.\n3.  **Implementation Strategy:** A list of discrete, actionable steps. Each step must detail the task, its rationale, inputs, and outputs.\n4.  **Final Review Checklist:** A specific checklist of items that must be verified to consider this entire task complete. This will be used in the final review phase.\n\nPresent this as a formal proposal.",
-            "guidance": [
-                "The agent will now proceed to critique its own plan in the next step. Withhold your final approval until after that critique.",
-                "This step is automatically skipped for Small tasks based on the complexity classification"
-            ]
-        },
-        {
-            "id": "phase-2b-devil-advocate-review",
-            "runCondition": {
-                "var": "taskComplexity",
-                "not_equals": "Small"
-            },
-            "title": "Phase 2b: Devil's Advocate Plan Review",
-            "prompt": "Your new goal is to act as a skeptical but fair senior principal engineer. Your task is to perform a 'devil's advocate' review of the implementation plan you just created in Phase 2. The objective is not to discard the plan, but to rigorously stress-test it and make it stronger. Your critique must be balanced and evidence-based.\n\nAnalyze the plan through the following lenses. For every point you make (positive or negative), you must cite specific evidence from the plan, the codebase, or the initial task description.\n\n1.  **Hidden Assumptions:** What assumptions does this plan make about the codebase, user behavior, or existing data that might be incorrect?\n2.  **Potential Risks & Unintended Side Effects:** What is the biggest risk of this plan? Could it impact performance, security, or another feature in a negative way?\n3.  **Overlooked Complexities or Edge Cases:** What specific edge cases (e.g., empty states, invalid inputs, race conditions) does the plan fail to explicitly address?\n4.  **Alternative Approaches:** Briefly propose at least one alternative technical approach. What are the pros and cons of the alternative versus the current plan?\n5.  **Plan Strengths:** To ensure a balanced review, explicitly state the strongest parts of the plan. What aspects are well-thought-out and likely to succeed?\n\nConclude with a balanced summary. If you found issues, provide concrete suggestions for how to amend the plan. Finally, give a confidence score (1-10) for the plan *if* your suggestions are implemented.",
-            "guidance": [
-                "This is a critical thinking step. The agent's goal is to find weaknesses in its *own* prior work to improve it. This is a sign of a high-functioning process.",
-                "Evaluate the agent's points. Not all 'risks' it identifies may be realistic. Use your judgment to decide which suggestions to incorporate into the plan.",
-                "After this review, you can ask the agent to create a final, amended version of the plan before you give your final approval to proceed with implementation.",
-                "This step is automatically skipped for Small tasks based on the complexity classification"
-            ],
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-3-iterative-implementation",
-            "title": "Phase 3: Iterative Implementation (PREP -> IMPLEMENT -> VERIFY)",
-            "prompt": "The implementation phase has now begun. **Please provide me with the next single step from the approved plan.** If we are on the 'Small' path, provide a single, clear implementation instruction.\n\nI will execute *only* that step using the PREP -> IMPLEMENT -> VERIFY cycle defined in the guidance below, and then await your command for the subsequent step. This process will repeat until all steps are complete.",
-            "guidance": [
-                "**Efficiency Tip:** For high-confidence plans, you may provide multiple step instructions at once. I will execute them sequentially, performing the P->I->V cycle for each, and will only pause to ask for input if I encounter a verification failure or ambiguity.",
-                "**PREP:** Before implementing each step, you must first PREPARE. Re-read the step's description, confirm the previous step was completed correctly, verify the plan for this step is still valid in the current codebase, and list all required inputs or files. Do not proceed if anything is unclear.",
-                "**IMPLEMENT:** After preparation is confirmed, you will IMPLEMENT the step. Focus only on this single step. Use your tools to make the necessary code changes, adhering to all quality standards. Provide a commit message upon completion.",
-                "**VERIFY:** Immediately after implementation, you must VERIFY your work. Your verification for this step **is not complete until you have**:\n1.  **Written necessary unit/integration tests** for the new logic.\n2.  **Run the full test suite** to ensure no regressions were introduced.\n3.  **Performed a critical self-review** of the changes against the plan, checking for code quality, side effects, and architectural alignment.\n\n**Failure Protocol:** If a verification failure cannot be resolved after two attempts, you must halt. Do not try a third time. Instead, present a summary of the problem, detail your failed attempts, and recommend a course of action to the user (e.g., 'revert this step and re-plan', 'request more information', 'proceed with a known issue')."
-            ]
-        },
-        {
-            "id": "phase-4-final-review",
-            "title": "Phase 4: Final Review & Completion",
-            "prompt": "All planned steps have been implemented and verified. Your final goal is to perform a holistic review by validating the work against the **'Final Review Checklist'** created and approved during Phase 2.\n\nFor each item on that checklist, provide a confirmation and evidence that it has been met. Conclude with a summary of any potential follow-ups or new dependencies to note.",
-            "guidance": [
-                "This is the final quality check. Ensure the agent's summary and checklist validation align with your understanding of the completed work."
-            ],
-            "requireConfirmation": true,
-            "validationCriteria": [
-                {
-                    "type": "contains",
-                    "value": "checklist",
-                    "message": "Should reference the final review checklist"
-                },
-                {
-                    "type": "contains",
-                    "value": "complete",
-                    "message": "Should confirm completion of all requirements"
-                },
-                {
-                    "type": "length",
-                    "min": 150,
-                    "condition": {
-                        "var": "taskComplexity",
-                        "not_equals": "Small"
-                    },
-                    "message": "Complex tasks require detailed final review"
-                },
-                {
-                    "type": "regex",
-                    "pattern": "(?!.*TODO)",
-                    "message": "Should not contain TODO items"
-                }
-            ],
-            "hasValidation": true
-        }
-    ]
-}

package/workflows/coding-task-workflow.json

@@ -1,352 +0,0 @@
-{
-    "id": "coding-task-workflow",
-    "name": "[DEPRECATED] Excellent Adaptive Coding Workflow with Devil's Advocate Review",
-    "version": "0.8.0",
-    "description": "[DEPRECATED] This workflow has been superseded by 'coding-task-workflow-with-loops' which includes enhanced loop capabilities for better iterative development. Use 'coding-task-workflow-with-loops' for new projects. Comprehensive AI coding workflow with bidirectional re-triage, deep analysis, intelligent clarification, devil's advocate review, automation levels, failure bounds, tool fallbacks, and context documentation for production-ready development.",
-
-    "preconditions": [
-        "User has a clear task description (e.g., from Jira, a dev doc, or a BRD).",
-        "The agent has access to necessary tools like `grep`, file readers/editors, and a terminal for commands.",
-        "The agent has access to the relevant codebase files.",
-        "Git repository is recommended for version control and commits (workflow degrades gracefully if unavailable)."
-    ],
-    "metaGuidance": [
-        "⚠️ DEPRECATION NOTICE: This workflow is deprecated. Use 'coding-task-workflow-with-loops' instead for enhanced iterative development capabilities with loop support.",
-        "This workflow follows the ANALYZE -> CLARIFY -> PREP -> IMPLEMENT -> VERIFY pattern with bidirectional dynamic re-triage capabilities.",
-        "Deep codebase analysis occurs early to inform intelligent requirements clarification and all subsequent planning phases.",
-        "Dynamic re-triage allows complexity upgrades and safe downgrades based on new insights from analysis and clarifications.",
-        "Automation levels (Low/Medium/High) control confirmation requirements to balance autonomy with safety.",
-        "Failure bounds prevent resource waste: word limits (2000), step tracking (>20), and escalation protocols.",
-        "Context documentation is maintained throughout to enable seamless handoffs between chat sessions, with updates triggered by progress milestones, failures, or user interventions.",
-        "For specialized tasks (e.g., debugging), call sub-workflows via workflow_get tool when available.",
-        "Limit all documentation outputs to 2000 words max; use bullet points for scannability.",
-        "Output markdown content in response; use read_file/edit_file tools to create/update actual files if available, else request user upload.",
-        "Align with custom instructions: Use --quiet flags for commands; output to files; prefer workflows for debugging.",
-        "Human approval is required after the Devil's Advocate review and before final completion.",
-        "Each implementation step should be a small, logical, and committable chunk of work.",
-        "The agent should never guess or assume. Always ask for clarification or use tools to find missing information.",
-        "If you fail to get test results or other tool outputs on the first attempt, ask the user to run it manually.",
-        "Document all user interventions, change requests, and feedback immediately in context documentation to ensure continuity.",
-        "**Git Fallback Strategy:** If git not initialized or tools fail, gracefully skip commits/branches, log changes manually in CONTEXT.md with timestamps, and warn user at phase-6 start. Document all file modifications for manual version control.",
-        "**Git Error Handling:** Use run_terminal_cmd for git operations; if fails, output exact command for user manual execution. Never halt workflow due to git unavailability.",
-        "Persist all variables across steps using conversation context, external state, or by including them in every response metadata; reset flags like proposedDowngrade after confirmation.",
-        "Use safe git practices: Create feature branches for isolation, commit on successful verification, generate clear commit messages, revert on failures. Log commit hashes in CONTEXT.md for traceability.",
-        "Maintain existing coding conventions and architectural patterns found in the codebase.",
-        "COMMIT STRATEGY: Auto-commit after successful steps for High automation; suggest for Medium/Low. Use conventional format: type(scope): description. Commit at milestones and after verification passes."
-    ],
-    "steps": [
-        {
-            "id": "phase-0-intelligent-triage",
-            "title": "Phase 0: Intelligent Task Triage & Complexity Analysis",
-            "prompt": "**ANALYZE**: Evaluate the provided task for complexity indicators:\n\n**Small Path Indicators:**\n- Single function changes or minor refactoring\n- Clear bug fixes with obvious solutions\n- Simple configuration changes\n- Low risk of side effects\n- Well-defined, narrow scope\n\n**Medium Path Indicators:**\n- Multi-file changes or moderate features\n- Standard development work\n- Some unknowns but manageable scope\n- Moderate complexity with clear boundaries\n- Requires planning but not architectural analysis\n\n**Large Path Indicators:**\n- Architectural changes or major features\n- Unfamiliar codebase areas\n- High complexity or significant risk\n- Multiple system interactions\n- Requires deep analysis and careful planning\n\n**IMPLEMENT**: \n1. Analyze the task description for the above indicators\n2. Recommend a complexity level (Small/Medium/Large) with detailed reasoning\n3. Set the taskComplexity context variable\n4. Ask user if they agree or want to override your classification\n5. For Medium tasks, ask: \"Would you like optional deep codebase analysis?\" (sets requestDeepAnalysis context variable)\n6. Ask: \"What automation level would you prefer? High (auto-approve low-risk decisions), Medium (standard confirmations), or Low (extra confirmations for safety)?\" (sets automationLevel context variable)\n\n**VERIFY**: Confirm the complexity classification, optional analysis preferences, and automation level before proceeding.",
-            "agentRole": "You are a technical assessment specialist with expertise in evaluating software development complexity. Your role is to accurately classify tasks based on technical risk, scope, and architectural impact. Be thorough in your analysis while remaining decisive and clear in your recommendations.",
-            "guidance": [
-                "Be thorough in your analysis - this determines the entire workflow path",
-                "Consider both technical complexity and business risk",
-                "When in doubt, err on the side of more thorough analysis (higher complexity)",
-                "Always allow human override of your classification",
-                "Set context variables that will be used for conditional step execution and automation",
-                "Automation levels: High=auto-approve confidence >8, Medium=standard, Low=extra confirmations"
-            ],
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-1-deep-analysis-mandatory",
-            "runCondition": {"var": "taskComplexity", "equals": "Large"},
-            "title": "Phase 1: Mandatory Deep Codebase Analysis",
-            "prompt": "Your goal is to become an expert on the attached codebase before any planning begins. This deep analysis is mandatory for Large tasks due to their complexity and risk.\n\n**ANALYSIS BOUNDS: Limit output to 1500 words; prioritize task-relevant sections.**\n\nYour analysis must include:\n1.  **Architecture:** Main modules, layers, and patterns.\n2.  **Key Concepts:** Core models, conventions, and important components.\n3.  **Execution Flow:** Trace major features or entry points.\n4.  **Code Quality Assessment:** Note maintainability, readability, or coupling issues.\n5.  **Testing Strategy:** Describe how the code is tested.\n6.  **Opportunities:** Suggest refactorings or improvements.\n7.  **Task Relevance:** Identify which parts of the codebase are most relevant to the current task.\n8.  **Potential Ambiguities:** Note areas where the initial task description might be unclear given the codebase structure.\n9.  **Complexity Indicators:** Note any discoveries that might affect the initial complexity assessment.\n\nProvide summaries and code examples to illustrate your findings. Be exhaustive within the word limit, as if preparing onboarding documentation for a senior engineer. This analysis will inform all subsequent requirements clarification, specification, and design work.",
-            "agentRole": "You are an expert codebase analyst with 10+ years of experience in software architecture and legacy system analysis. Your specialty is quickly understanding complex codebases and identifying architectural patterns, risks, and opportunities. Approach this with the thoroughness of a senior engineer conducting a technical due diligence review.",
-            "askForFiles": true,
-            "guidance": [
-                "This step is mandatory for Large tasks due to their complexity and risk",
-                "Ensure all relevant source files are attached or accessible to the agent before running this step",
-                "Be thorough but respect the 1500-word limit - focus on task-relevant insights",
-                "This analysis will inform requirements clarification, specification, design, and implementation strategy",
-                "Pay special attention to areas of the codebase relevant to the current task",
-                "Note potential ambiguities in the task description that become apparent after understanding the codebase",
-                "Flag any complexity indicators that might warrant re-triaging the task complexity"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-1-deep-analysis-optional",
-            "runCondition": {
-                "and": [
-                    {"var": "taskComplexity", "equals": "Medium"},
-                    {"var": "requestDeepAnalysis", "equals": true}
-                ]
-            },
-            "title": "Phase 1: Optional Deep Codebase Analysis",
-            "prompt": "You requested optional deep analysis for this Medium task. Your goal is to become an expert on the attached codebase before planning begins.\n\n**ANALYSIS BOUNDS: Limit output to 1500 words; prioritize task-relevant sections.**\n\nYour analysis must include:\n1.  **Architecture:** Main modules, layers, and patterns.\n2.  **Key Concepts:** Core models, conventions, and important components.\n3.  **Execution Flow:** Trace major features or entry points.\n4.  **Code Quality Assessment:** Note maintainability, readability, or coupling issues.\n5.  **Testing Strategy:** Describe how the code is tested.\n6.  **Opportunities:** Suggest refactorings or improvements.\n7.  **Task Relevance:** Identify which parts of the codebase are most relevant to the current task.\n8.  **Potential Ambiguities:** Note areas where the initial task description might be unclear given the codebase structure.\n9.  **Complexity Indicators:** Note any discoveries that might affect the initial complexity assessment.\n\nProvide summaries and code examples to illustrate your findings. Focus on areas most relevant to the current task while maintaining architectural awareness. This analysis will inform all subsequent requirements clarification, specification, and design work.",
-            "agentRole": "You are a focused codebase analyst specializing in targeted technical analysis for medium-complexity projects. Your approach balances thoroughness with efficiency, focusing on areas most relevant to the current task while maintaining architectural awareness.",
-            "askForFiles": true,
-            "guidance": [
-                "This optional analysis was requested for a Medium task",
-                "Ensure all relevant source files are attached or accessible to the agent before running this step",
-                "Focus on areas most relevant to the current task while maintaining broader architectural context",
-                "Respect the 1500-word limit - prioritize task-relevant insights",
-                "This analysis will inform requirements clarification, specification, and design phases",
-                "Note potential ambiguities in the task description that become apparent after understanding the codebase",
-                "Flag any complexity indicators that might warrant re-triaging the task complexity"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-2-informed-clarification",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 2: Informed Requirements Clarification",
-            "prompt": "Based on your deep understanding of the codebase from Phase 1, you are now in a position to ask intelligent, targeted questions to clarify the requirements. Your codebase analysis may have revealed ambiguities, missing details, or potential issues that weren't apparent from the initial task description.\n\n**Your goal is to ask specific, informed questions that will lead to a clear, unambiguous specification. Consider:**\n\n1. **Technical Ambiguities:** Are there aspects of the task that could be implemented in multiple ways given the existing architecture? Which approach is preferred?\n\n2. **Integration Questions:** How should the new functionality integrate with existing systems, APIs, or workflows you discovered?\n\n3. **Scope Boundaries:** Given the existing codebase structure, what should be included/excluded from this task?\n\n4. **Convention Alignment:** Should the implementation follow existing patterns you observed, or is this an opportunity to establish new patterns?\n\n5. **Edge Cases:** What should happen in edge cases that are now apparent given the existing data models and business logic?\n\n6. **Dependencies:** Are there existing components, services, or data that the task should leverage or avoid?\n\n7. **Testing Strategy:** Given the existing test patterns, what level and type of testing is expected?\n\n8. **Complexity Concerns:** Based on your analysis, are there risk factors that might indicate this task is more complex than initially classified?\n\n**Present 3-7 well-formulated questions that will significantly improve the clarity and implementability of the final specification.**",
-            "agentRole": "You are a senior business analyst and technical consultant specializing in requirements elicitation. Your expertise lies in translating deep technical understanding into precise business questions that eliminate ambiguity and prevent costly rework. You excel at identifying the critical gaps between initial requirements and implementation reality.",
-            "guidance": [
-                "This step is automatically skipped for Small tasks based on complexity classification",
-                "Ask questions that could only be formulated after understanding the codebase",
-                "Focus on questions that will significantly impact the specification and implementation approach",
-                "Avoid generic questions - make them specific to the codebase and task at hand",
-                "Present questions in a clear, prioritized manner",
-                "Include questions about potential complexity changes based on your analysis"
-            ],
-            "requireConfirmation": {
-                "or": [
-                    {"var": "automationLevel", "equals": "Low"},
-                    {"var": "automationLevel", "equals": "Medium"}
-                ]
-            }
-        },
-        {
-            "id": "phase-2b-dynamic-retriage",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 2b: Dynamic Complexity Re-Triage",
-            "prompt": "Based on your codebase analysis and requirements clarification, re-evaluate the initial complexity classification. New insights may have revealed:\n\n- Hidden architectural dependencies\n- Unforeseen integration complexities\n- Risk factors not apparent in the initial description\n- Scope expansion based on clarified requirements\n- Technical constraints that increase difficulty\n- **OR existing utilities/patterns that simplify the task**\n\n**EVALUATE:**\n1. Review the original taskComplexity classification\n2. Consider new information from codebase analysis and clarifications\n3. Assess if the complexity should be upgraded (e.g., Medium → Large) OR downgraded (e.g., Large → Medium)\n4. Provide detailed reasoning for any recommended changes\n\n**If you recommend upgrading complexity:**\n- Clearly explain what new insights led to this recommendation\n- Describe the additional risks or complexity discovered\n- Justify why the higher complexity path would be beneficial\n- Ask for user confirmation to change the taskComplexity context variable\n\n**If you recommend downgrading complexity:**\n- Set proposedDowngrade context variable to true\n- Clearly explain what existing utilities, patterns, or simplified scope led to this recommendation\n- Provide evidence of reduced risk and scope\n- Require user confirmation and evidence of reduced risk unless automationLevel=High and confidence >8\n- Justify why the lower complexity path is safe and appropriate\n\n**If current classification remains appropriate:**\n- Briefly confirm the classification is still accurate\n- Proceed without requesting changes\n\n**Note:** Both upgrades and downgrades are allowed with proper justification to ensure optimal workflow efficiency.",
-            "agentRole": "You are a senior technical risk assessor specializing in project complexity evaluation. Your expertise lies in identifying hidden risks and complexity factors that emerge during analysis phases, as well as recognizing when tasks are simpler than initially assessed. You excel at making decisive recommendations to ensure projects follow the appropriate rigor level.",
-            "guidance": [
-                "This step allows both upgrading and downgrading complexity based on new insights",
-                "Only change complexity if there are clear, justifiable reasons",
-                "For downgrades, set proposedDowngrade flag and require explicit user approval unless automationLevel=High and confidence >8",
-                "Be specific about what new information led to the reassessment",
-                "If changing complexity, the workflow will continue with the new complexity path",
-                "Downgrades must be justified with evidence of reduced risk/scope",
-                "Reset proposedDowngrade to false after user confirmation or rejection"
-            ],
-            "requireConfirmation": {
-                "or": [
-                    {"var": "automationLevel", "equals": "Low"},
-                    {"var": "automationLevel", "equals": "Medium"},
-                    {"var": "proposedDowngrade", "equals": true}
-                ]
-            }
-        },
-        {
-            "id": "phase-3-specification",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 3: Create Specification",
-            "prompt": "Using your codebase analysis from Phase 1, the clarified requirements from Phase 2, and any complexity re-assessment from Phase 2b, create a specification document that aligns with the existing system and addresses all identified ambiguities. Your specification should be precise, unambiguous, and fully implementable.\n\n**Task Description:**\n[Updated based on clarifications from Phase 2]\n\n**Key Objectives & Success Criteria:**\n[Refined based on codebase understanding and clarifications]\n\n**Scope and Constraints:**\n[Updated to reflect codebase realities and clarified boundaries]\n\n**IMPORTANT**: Your specification must consider:\n- Existing architectural patterns and conventions identified in your codebase analysis\n- How the proposed changes fit within the current system design\n- Potential impacts on existing components and workflows\n- Alignment with current testing strategies and code quality standards\n- All clarifications and decisions made in Phase 2\n- Any complexity insights from the re-triage assessment\n\nOutput markdown content in response; use edit_file tool to create actual spec.md file if available, else request user upload.\n\nFinally, perform a sanity check on the current complexity classification. If you believe further adjustment is needed given your comprehensive understanding, state your reasoning and ask for confirmation before proceeding.",
-            "agentRole": "You are a senior business analyst and technical lead specializing in requirement gathering and scope definition. Your goal is to produce a clear, comprehensive `spec.md` file that leverages your deep understanding of the existing codebase and incorporates all clarified requirements to serve as an unambiguous foundation for design and implementation.",
-            "guidance": [
-                "Provide a complete task description based on all previous analysis and clarifications",
-                "The output of this step should be the content for `spec.md`",
-                "This step is automatically skipped for Small tasks based on the complexity classification",
-                "Leverage your codebase analysis and clarifications to ensure the specification is precise and implementable",
-                "Reference specific decisions made during the clarification phase",
-                "Consider any complexity changes from the re-triage phase"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-3b-create-context-doc",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 3b: Create Context Documentation",
-            "prompt": "Create a comprehensive context documentation file (`CONTEXT.md`) that captures all critical information from the workflow so far. This document is essential for enabling seamless handoffs between chat sessions when context limits are reached.\n\n**For automationLevel=High, generate a summary-only version (limit 1000 words); otherwise, full update (limit 2000 words).**\n\n**Your `CONTEXT.md` must include:**\n\n## 1. ORIGINAL TASK CONTEXT\n- Original task description and requirements\n- Complexity classification (Small/Medium/Large) and reasoning\n- Any re-triage decisions made and why\n- Automation level selected and its implications\n\n## 2. CODEBASE ANALYSIS SUMMARY\n- Key architectural patterns and conventions found\n- Relevant components, modules, and their locations\n- Testing strategies and patterns in use\n- Critical dependencies and integration points\n- Any complexity indicators discovered\n\n## 3. CLARIFICATIONS AND DECISIONS\n- Questions asked and answers received\n- Ambiguities resolved and how\n- Scope boundaries clearly defined\n- Technical approach decisions made\n\n## 4. SPECIFICATION SUMMARY\n- Core objectives and success criteria\n- Key constraints and requirements\n- Design principles to follow\n- Integration requirements\n\n## 5. WORKFLOW PROGRESS TRACKING\n- ✅ Completed phases (0, 1, 2, 2b, 3, 3b)\n- 🔄 Current phase: Architecture Design (Phase 4)\n- ⏳ Remaining phases: 4, 5, 5b, 5c, 5d, 5e, 6, 7\n- 📋 Context variables set (taskComplexity, automationLevel, etc.)\n\n## 6. HANDOFF INSTRUCTIONS\n- Files to attach when resuming (e.g., spec.md via tool or user upload)\n- Key context to provide to new chat session\n- Critical decisions that must not be forgotten\n\n**Format this as a clear, scannable document using bullet points that a new agent could quickly read to understand the full project context.**",
-            "agentRole": "You are a meticulous technical documentation specialist with expertise in creating comprehensive project handoff documents. Your role is to capture all critical context in a way that enables seamless continuity across different team members or chat sessions. You excel at synthesizing complex technical information into clear, actionable documentation.",
-            "guidance": [
-                "This step is automatically skipped for Small tasks",
-                "Create a document that would allow a completely new agent to pick up the work seamlessly",
-                "Include specific file paths, component names, and technical details discovered",
-                "Reference all key decisions made in previous phases",
-                "Make the progress tracking section very clear for workflow continuation",
-                "Consider this document as critical as the specification itself",
-                "Use bullet points for scannability; limit to word count based on automation level"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-4-architectural-design",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 4: Architectural Design",
-            "prompt": "Using the `spec.md` from the previous step, your deep codebase analysis, and all clarified requirements, create a high-level architectural design that seamlessly integrates with the existing system. Your output should be a `design.md` document that includes:\n1. **High-Level Approach:** A summary of the proposed solution that builds on existing patterns.\n2. **Component Breakdown:** Identify new or modified components, classes, or modules, showing how they fit within the current architecture.\n3. **Data Models:** Describe any changes to data structures or database schemas, considering existing data patterns.\n4. **API Contracts:** Define any new or changed API endpoints, following existing API conventions and patterns.\n5. **Key Interactions:** A diagram or description of how the major components will interact, both new and existing.\n6. **Integration Points:** Clearly identify how new components will integrate with existing systems and workflows.\n7. **Clarification Decisions:** Reference how the clarified requirements from Phase 2 influenced design decisions.\n8. **Complexity Considerations:** Address any complexity factors identified during re-triage.\n\nOutput markdown content in response; use edit_file tool to create actual design.md file if available, else request user upload.",
-            "agentRole": "You are a software architect specializing in translating business requirements into robust and scalable technical designs that seamlessly integrate with existing systems. Your task is to create a clear and comprehensive `design.md` that leverages existing architectural patterns while introducing necessary changes and incorporating all clarified requirements.",
-            "guidance": [
-                "The `design.md` should be detailed enough for an engineer to write an implementation plan from it.",
-                "This step is automatically skipped for Small tasks.",
-                "Ensure the design builds upon and aligns with the existing codebase architecture identified in your analysis",
-                "Reference specific clarification decisions that influenced the design",
-                "Consider complexity factors identified during re-triage"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-small-prep",
-            "runCondition": {"var": "taskComplexity", "equals": "Small"},
-            "title": "Phase Small: Preparation and Simplified Execution",
-            "prompt": "For this Small task, perform quick preparation before implementation:\n\n**QUICK PREP:**\n1. **Verify Assumptions:** Use tools (e.g., list_dir, grep_search) to confirm:\n   - Target files exist where expected\n   - Functions/components mentioned are present\n   - Dependencies are available\n\n2. **Complexity Check:** If you discover:\n   - Unexpected dependencies or architectural complexity\n   - Multiple integration points\n   - Significant testing requirements\n   **ESCALATE:** Recommend upgrading via re-triage (set proposedUpgrade=true) and pause for user confirmation.\n\n3. **Simple Plan:** Otherwise, create a brief plan with 2-5 discrete steps:\n   - What will be changed\n   - How it will be tested\n   - Expected outcomes\n\n**ESCAPE HATCH:** If complexities arise during this prep, recommend upgrading to Medium/Large via phase-2b re-triage rather than proceeding with insufficient analysis.\n\n**Report your findings as a simple checklist:**\nChecklist example:\n- [✅] File `src/utils.js` exists (verified via list_dir)\n- [✅] Function `calculateTotal()` found (verified via grep_search)\n- [✅] Dependencies confirmed in package.json\n- [✅] Simple 3-step plan created\n\nProceed to implementation if all checks pass, otherwise recommend re-triage.",
-            "agentRole": "You are an efficient task executor specializing in low-complexity work. Your strength is quickly validating assumptions and creating lightweight plans while maintaining awareness of when tasks exceed their initial scope. You excel at recognizing when to escalate rather than proceeding with insufficient analysis.",
-            "guidance": [
-                "This is a mini-version of PREP->IMPLEMENT->VERIFY for Small tasks",
-                "Use available tools to verify basic assumptions quickly",
-                "Escape to phase-2b re-triage if complexities are discovered",
-                "Keep the plan simple but actionable",
-                "Better to escalate than to proceed with insufficient preparation"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-5-planning",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 5: Create Detailed Implementation Plan",
-            "prompt": "Your goal is to produce a thorough and actionable `implementation_plan.md` based on the `spec.md`, `design.md`, your deep codebase analysis, and all clarified requirements. Do not write any code. Your plan must be detailed, broken into committable phases, and justified.\n\nYour plan must include these sections:\n1.  **Goal Clarification:** Your understanding of the goal, assumptions, and success criteria from the spec and clarifications.\n2.  **Impact Assessment:** Affected codebase parts, dependencies, and risks based on the design, codebase analysis, and clarified requirements.\n3.  **Implementation Strategy:** A list of discrete, actionable steps. Each step must detail the task, its rationale, inputs, and outputs.\n4.  **Testing Strategy:** Describe how the changes will be tested, building on existing testing patterns identified in your codebase analysis. Mandate achieving >80% test coverage where applicable.\n5.  **Failure Handling:** Define what to do if tests fail, tools don't work, or unexpected issues arise.\n6.  **Final Review Checklist:** A specific checklist of items that must be verified to consider this entire task complete. This will be used in the final review phase.\n\nOutput markdown content in response; use edit_file tool to create actual implementation_plan.md file if available, else request user upload.\n\nPresent this as a formal proposal that demonstrates deep understanding of the requirements, clarifications, and the existing codebase.",
-            "agentRole": "You are an experienced technical architect and project planner with expertise in breaking down complex development tasks into manageable, logical phases. Your strength is creating detailed, actionable plans that minimize risk while maximizing development efficiency and code quality, all while working within existing system constraints and incorporating all clarified requirements.",
-            "guidance": [
-                "The agent will now proceed to critique its own plan in the next step. Withhold your final approval until after that critique.",
-                "This step is automatically skipped for Small tasks based on the complexity classification",
-                "Leverage your codebase analysis and clarified requirements to ensure the plan works within existing architectural constraints",
-                "Reference how clarified requirements influenced the planning decisions",
-                "Include explicit failure handling protocols and quantitative metrics where applicable"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-5b-devil-advocate-review",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 5b: Devil's Advocate Plan Review",
-            "prompt": "Your task is to perform a 'devil's advocate' review of the implementation plan you just created in Phase 5. The objective is not to discard the plan, but to rigorously stress-test it and make it stronger. Your critique must be balanced and evidence-based.\n\nAnalyze the plan through the following lenses. For every point you make (positive or negative), you must cite specific evidence from the plan, the codebase analysis, clarified requirements, or the initial task description.\n\n1.  **Hidden Assumptions:** What assumptions does this plan make about the codebase, user behavior, or existing data that might be incorrect?\n2.  **Potential Risks & Unintended Side Effects:** What is the biggest risk of this plan? Could it impact performance, security, or another feature in a negative way?\n3.  **Overlooked Complexities or Edge Cases:** What specific edge cases (e.g., empty states, invalid inputs, race conditions) does the plan fail to explicitly address?\n4.  **Alternative Approaches:** Briefly propose at least one alternative technical approach. What are the pros and cons of the alternative versus the current plan?\n5.  **Plan Strengths:** To ensure a balanced review, explicitly state the strongest parts of the plan. What aspects are well-thought-out and likely to succeed?\n\nConclude with a balanced summary. If you found issues, provide concrete suggestions for how to amend the plan. Finally, **set the confidenceScore variable to your 1-10 rating** for the plan *if* your suggestions are implemented.",
-            "agentRole": "You are a skeptical but fair senior principal engineer with 15+ years of experience in critical system development. Your role is to identify potential failure points, hidden assumptions, and overlooked complexities in technical plans. You excel at constructive criticism that strengthens plans rather than destroys them. Approach this with the rigor of a senior engineer reviewing a mission-critical system design.",
-            "guidance": [
-                "This is a critical thinking step. The agent's goal is to find weaknesses in its *own* prior work to improve it. This is a sign of a high-functioning process.",
-                "Evaluate the agent's points. Not all 'risks' it identifies may be realistic. Use your judgment to decide which suggestions to incorporate into the plan.",
-                "After this review, you can ask the agent to create a final, amended version of the plan before you give your final approval to proceed with implementation.",
-                "This step is automatically skipped for Small tasks based on the complexity classification",
-                "CRITICAL: Set confidenceScore variable (1-10) in your response",
-                "For automationLevel=High with confidenceScore >8, auto-approve if no critical risks identified"
-            ],
-            "requireConfirmation": {
-                "or": [
-                    {"var": "automationLevel", "equals": "Low"},
-                    {"var": "automationLevel", "equals": "Medium"},
-                    {"and": [
-                        {"var": "automationLevel", "equals": "High"},
-                        {"var": "confidenceScore", "lt": 8}
-                    ]}
-                ]
-            }
-        },
-        {
-            "id": "phase-5c-finalize-plan",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 5c: Finalize Implementation Plan",
-            "prompt": "Review the initial `implementation_plan.md` from Phase 5 and the Devil's Advocate critique from Phase 5b. Your task is to create a final, consolidated implementation plan that incorporates the valid feedback from the review.\n\nYour output must be the final `implementation_plan.md`.\n\nAdditionally, explicitly list any suggestions from the review that you believe are valuable but out-of-scope for the current task. These should be formatted as potential tickets for future work.\n\nOutput updated markdown content in response; use edit_file tool to update actual implementation_plan.md file if available, else request user upload.",
-            "agentRole": "You are a pragmatic technical project manager. Your goal is to synthesize feedback, make decisive trade-offs, and produce a final, actionable plan that is ready for execution.",
-            "guidance": [
-                "This is the final plan that will be executed. Ensure it is clear, actionable, and reflects the best path forward.",
-                "The list of out-of-scope items helps capture valuable ideas without derailing the current task."
-            ],
-            "requireConfirmation": {
-                "or": [
-                    {"var": "automationLevel", "equals": "Low"},
-                    {"var": "automationLevel", "equals": "Medium"}
-                ]
-            }
-        },
-        {
-            "id": "phase-5d-plan-sanity-check",
-            "runCondition": { "var": "taskComplexity", "not_equals": "Small" },
-            "title": "Phase 5d: Plan Sanity Check",
-            "prompt": "Before starting implementation, perform a sanity check on the final `implementation_plan.md`. Your goal is to use your tools to quickly verify the plan's core assumptions against the current codebase. This is not a deep analysis, but a quick check for obvious errors.\n\nFor the key files, functions, classes, or APIs mentioned in the plan, perform the following checks:\n1.  **Existence Check:** Use tools like `grep_search` or `list_dir` to confirm that the files and primary functions/classes you plan to modify actually exist where you expect them to.\n2.  **Signature/API Check (if applicable):** Briefly check the function signatures or API endpoints you intend to use. Do they match the plan's assumptions? For example, if the plan assumes a function takes two arguments, verify that.\n3.  **Dependency Check:** If the plan relies on a specific library or module being available, quickly verify its presence (e.g., check `package.json`, `requirements.txt`, etc.).\n\n**If tools are unavailable, note fallback and proceed with manual verification request.**\n\n**Report your findings as a simple checklist:**\nChecklist example:\n- [✅] File `src/example.js` exists (verified via list_dir)\n- [✅] Function `calculateTotal()` found in `src/utils.js` (verified via grep_search)\n- [✅] Dependency `moment` is listed in `package.json`\n\nIf any check fails (❌), briefly explain the discrepancy and ask the user if the plan needs to be revised before proceeding.",
-            "agentRole": "You are a pragmatic QA engineer double-checking a plan before the development team starts work. Your job is to be quick, efficient, and focused on verifying concrete facts using tools. You are not re-evaluating the plan's logic, only its tangible connection to the codebase.",
-            "guidance": [
-                "This is a quick verification step, not a full re-analysis. The goal is to catch glaring errors before implementation begins.",
-                "Use your code-browsing tools (grep_search, list_dir) to validate the plan's assumptions.",
-                "If tools fail, fall back to alternatives like file_search or request manual verification",
-                "If a check fails, it's crucial to pause and get human confirmation before proceeding with a potentially flawed plan."
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-5e-update-context-doc",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 5e: Update Context Documentation with Final Plans",
-            "prompt": "Update the `CONTEXT.md` file with all the planning work completed in Phases 4-5. This ensures the context document remains current and comprehensive for potential handoffs.\n\n**For automationLevel=High, generate a summary-only version (limit 500 words); otherwise, full update.**\n\n**Add/Update these sections in `CONTEXT.md`:**\n\n## 4. ARCHITECTURAL DESIGN SUMMARY\n- High-level approach and rationale\n- Key components being added/modified\n- Integration points with existing systems\n- Design decisions and alternatives considered\n\n## 5. IMPLEMENTATION PLAN OVERVIEW\n- Goal clarification and success criteria\n- Implementation strategy overview\n- Key risks identified and mitigation strategies\n- Testing approach and patterns to follow\n- Failure handling protocols\n\n## 6. DEVILS ADVOCATE REVIEW INSIGHTS\n- Key concerns raised and how they were addressed\n- Plan improvements made based on the review\n- Confidence score and reasoning\n- Out-of-scope items identified for future work\n\n## 7. UPDATED WORKFLOW PROGRESS\n- ✅ Completed phases (0, 1, 2, 2b, 3, 3b, 4, 5, 5b, 5c, 5d, 5e)\n- 🔄 Current phase: Implementation (Phase 6)\n- ⏳ Remaining phases: 6, 7\n- 📁 Key files created: spec.md, design.md, implementation_plan.md, CONTEXT.md\n\n## 8. IMPLEMENTATION READINESS\n- Plan sanity check results\n- Files and dependencies verified\n- Ready-to-execute implementation steps\n- Potential handoff points during implementation\n\n**Use bullet points for scannability and maintain all previous sections while adding the new planning context.**",
-            "agentRole": "You are a meticulous technical documentation specialist focused on maintaining comprehensive project context. Your expertise lies in synthesizing complex planning work into clear, actionable documentation that enables seamless workflow continuation.",
-            "guidance": [
-                "This step is automatically skipped for Small tasks",
-                "Maintain the scannable structure while adding substantial new planning context",
-                "Ensure all critical planning decisions are captured for potential handoffs",
-                "Update progress tracking to reflect the current state accurately",
-                "Consider this update as crucial as the original context document creation",
-                "Limit output based on automation level; use bullet points for readability",
-                "After updating CONTEXT.md, commit the planning completion: 'docs(planning): finalize implementation plan and context' (auto-commit for High automation, suggest for Medium/Low)"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-6-iterative-implementation",
-            "title": "Phase 6: Iterative Implementation (PREP -> IMPLEMENT -> VERIFY)",
-            "prompt": "The implementation phase has now begun. You will now execute the approved `implementation_plan.md` step-by-step. Announce which step you are starting.\n\n**BRANCH SETUP:** Check git availability first with 'git status'. If git available, create a feature branch for isolation: Use a tool to run 'git checkout -b wip-[unique-task-id]' (generate a unique ID, e.g., from timestamp or task description) and track the featureBranch variable for later use. **If git not initialized or fails:** Skip branching/commits, log changes manually in CONTEXT.md with timestamps, warn user of no-git mode, and proceed with file-based tracking. Output exact git commands for user manual execution if needed.\n\n**STEP TRACKING:** Track total steps executed. If >20 steps without completion, pause and summarize progress for user intervention.\n\n**CONTEXT DOCUMENTATION:** Update `CONTEXT.md` after every 3 implementation steps, on failures, or when user requests changes/improvements with:\n- Progress summary (steps completed vs total)\n- Current implementation status\n- Issues encountered and resolutions\n- Files modified so far\n- Remaining work overview\n- Any changes to the original plan\n- Commit hashes from successful phases\n\nYou will execute each step using the PREP -> IMPLEMENT -> VERIFY cycle defined in the guidance below. This process will repeat until all steps in the plan are complete.",
-            "agentRole": "You are a meticulous senior software engineer focused on high-quality implementation. Your approach emphasizes careful preparation, precise execution, and thorough verification. You excel at following plans while adapting to unexpected discoveries during implementation, and you maintain excellent documentation for project continuity.",
-            "guidance": [
-                "**IMPORTANT**: Do not proceed to the next workflow phase (Final Review) until all steps in the `implementation_plan.md` are marked as complete and verified.",
-                "**STEP BOUNDS**: Track total steps executed. If >20 steps without completion, pause and ask user for guidance.",
-                "**CONTEXT UPDATES**: Update CONTEXT.md after every 3 steps, on failures, or when user requests changes",
-                "**Efficiency Tip:** For high-confidence plans, you may provide multiple step instructions at once. I will execute them sequentially, performing the P->I->V cycle for each, and will only pause to ask for input if I encounter a verification failure or ambiguity.",
-                "**PREP:** Before implementing each step, you must first PREPARE. Re-read the step's description, confirm the previous step was completed correctly, verify the plan for this step is still valid in the current codebase, and list all required inputs or files. Do not proceed if anything is unclear.",
-                "**IMPLEMENT:** After preparation is confirmed, you will IMPLEMENT the step. Focus only on this single step. Use your tools to make the necessary code changes, adhering to all quality standards.",
-                "**VERIFY:** Immediately after implementation, you must VERIFY your work. Your verification for this step **is not complete until you have**:\n1.  **Written necessary unit/integration tests** for the new logic (as per the testing strategy). Report metrics: Achieve >80% test coverage (use tools to measure); 0 regressions expected.\n2.  **Run the full test suite** to ensure no regressions were introduced. Use --quiet flags and output to files per custom instructions.\n3.  **Performed a critical self-review** of the changes against the plan, checking for code quality, side effects, and architectural alignment.\n\n**COMMIT:** After successful verification, commit your changes (if git available):\n- **For automationLevel=High:** Automatically commit with descriptive message using conventional commit format (e.g., 'feat(auth): add user login validation', 'fix(api): handle null response in getUserData', 'refactor(utils): extract common validation logic')\n- **For automationLevel=Medium/Low:** Suggest commit with message and ask for user confirmation\n- **If git unavailable:** Log changes in CONTEXT.md with timestamp, file list, and change summary for manual version control\n- **Commit Message Guidelines:** Use format 'type(scope): description' where type is feat/fix/refactor/test/docs, scope is the affected component/module, description is concise and imperative mood\n- **Always commit after:** Each completed implementation step (if verification passes), major milestones, before context updates, when user requests changes\n- **Never commit:** Broken code, failing tests, or unverified changes\n\n**ENHANCED FAILURE PROTOCOL:** If a verification failure cannot be resolved after two attempts:\n1. **Do not try a third time**\n2. **For tool failures (e.g., grep):** Fall back to alternatives like `file_search` or `web_search`\n3. **If test failures occur:** Output command for user (e.g., './gradlew test --quiet --warning-mode=none --info > test_output.txt') and request manual execution per custom instructions\n4. **For critical failures:** Revert changes on the branch (e.g., 'git reset --hard HEAD'). For irrecoverable failures, delete branch to clean up: 'git checkout main && git branch -D [featureBranch]'\n5. **Update CONTEXT.md** with the failure details and current status\n6. **Present a summary** of the problem, detail your failed attempts, and recommend a course of action to the user (e.g., 'revert this step and re-plan', 'request more information', 'proceed with known issue')\n\n**USER INTERVENTION PROTOCOL:** When user requests changes, improvements, or provides feedback:\n1. **Immediately update CONTEXT.md** with the user's request and reasoning\n2. **Document the current state** before making any changes\n3. **Record the modification** made and its impact on the overall plan\n4. **Update progress tracking** to reflect any plan adjustments or scope changes"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-6b-refinement-check",
-            "title": "Phase 6b: Agile Refinement Check",
-            "prompt": "After completing a chunk of implementation, evaluate if refinements are needed based on new insights. Set 'needsRefinement' context variable to true if updates to spec, design, or plan are required. If true, proceed to refinement steps; else, continue implementation or move to final review.",
-            "agentRole": "Agile refinement checker",
-            "runCondition": {"var": "implementationInProgress", "equals": true},
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-6c-update-spec",
-            "title": "Phase 6c: Update Specification",
-            "prompt": "Based on implementation insights, update spec.md with necessary changes. Justify updates and get user confirmation.",
-            "agentRole": "Specification updater",
-            "runCondition": {"var": "needsRefinement", "equals": true},
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-6d-update-design",
-            "title": "Phase 6d: Update Design",
-            "prompt": "Update design.md based on new insights. Maintain alignment with codebase.",
-            "agentRole": "Design updater",
-            "runCondition": {"var": "needsRefinement", "equals": true},
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-6e-update-plan",
-            "title": "Phase 6e: Update Implementation Plan",
-            "prompt": "Revise implementation_plan.md incorporating refinements. Reset 'needsRefinement' to false after updates.",
-            "agentRole": "Plan updater",
-            "runCondition": {"var": "needsRefinement", "equals": true},
-            "requireConfirmation": true
-        },
-        {
-            "id": "phase-7-final-review",
-            "title": "Phase 7: Final Review & Completion",
-            "prompt": "All planned steps have been implemented and verified. Your final goal is to perform a holistic review by validating the work against the **'Final Review Checklist'** from the `implementation_plan.md`.\n\nFor each item on that checklist, provide a confirmation and evidence that it has been met. Validate metrics against checklist (e.g., coverage percentage, test results).\n\n**After validation, create a final commit:**\n- Use conventional commit format: 'feat|fix|refactor(scope): final implementation - <brief summary>'\n- Include metrics in commit body (e.g., 'test coverage: 85%, all tests passing')\n- For automationLevel=High: auto-commit; Medium/Low: suggest and confirm\n\n**BRANCH CLEANUP:** Complete feature branch lifecycle (if git available):\n1. **Merge:** Propose 'git checkout main && git merge --squash [featureBranch] && git commit -m \"chore(merge): [task summary] with [metrics]\"'\n2. **Delete:** After merge: 'git branch -d [featureBranch]'\n3. **Automation:** High with confidenceScore >8 auto-executes; otherwise confirm\n4. **Conflicts:** Pause for user resolution if conflicts occur\n5. **No git:** Document final state in CONTEXT.md with file modification summary\n6. **Log merge hash** in CONTEXT.md (or timestamp if no git)\n\n**Additionally, create a comprehensive handoff document by updating `CONTEXT.md` with a final section:**\n\n## 9. FINAL COMPLETION STATUS\n- ✅ Implementation steps completed\n- ✅ Tests passing (metrics: coverage %, test count)\n- ✅ Review checklist validated\n- 📁 Files created/modified (with descriptions)\n- 🧪 Testing completed\n- 📋 Known issues/limitations\n- 🔄 Deployment/next steps\n- 📜 Git history: commits and merge hash\n\n## 10. HANDOFF SUMMARY\n- Accomplishments vs requirements\n- Key architectural decisions\n- Implementation details for maintainers\n- Recommended follow-up work\n- Contact points/documentation\n\nConclude with a summary of any potential follow-ups or new dependencies to note.",
-            "agentRole": "You are a quality assurance specialist and technical lead responsible for final project validation and comprehensive handoff documentation. Your expertise lies in comprehensive system testing, requirement verification, and ensuring deliverables meet all specified criteria while creating documentation that enables seamless future maintenance.",
-            "guidance": [
-                "This is the final quality check. Ensure the agent's summary and checklist validation align with your understanding of the completed work.",
-                "The final CONTEXT.md update should serve as a complete project archive",
-                "Include specific details that would help future developers understand and maintain the work",
-                "Ensure all promised deliverables have been completed and documented",
-                "Include quantitative metrics and validation results in the final status"
-            ],
-            "requireConfirmation": true
-        }
-    ]
-}