@exaudeus/workrail 0.0.16 → 0.0.17

package/package.json

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

package/workflows/coding-task-workflow.json

@@ -1,13 +1,14 @@
 {
     "id": "coding-task-workflow",
     "name": "Excellent Adaptive Coding Workflow with Devil's Advocate Review",
-    "version": "0.7.0",
+    "version": "0.8.0",
     "description": "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."
+        "The agent has access to the relevant codebase files.",
+        "Git repository is recommended for version control and commits (workflow degrades gracefully if unavailable)."
     ],
     "metaGuidance": [
         "This workflow follows the ANALYZE -> CLARIFY -> PREP -> IMPLEMENT -> VERIFY pattern with bidirectional dynamic re-triage capabilities.",
@@ -25,8 +26,12 @@
         "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.",
-        "Maintain existing coding conventions and architectural patterns found in the codebase."
+        "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": [
         {
@@ -275,14 +280,15 @@
                 "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"
+                "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**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\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.",
+            "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.",
@@ -290,15 +296,15 @@
                 "**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. 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 (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**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:** Consider escalating by reverting changes using git reset\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"
+                "**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-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**Additionally, create a comprehensive handoff document by updating `CONTEXT.md` with a final section:**\n\n## 9. FINAL COMPLETION STATUS\n- ✅ All implementation steps completed\n- ✅ All tests passing (include metrics: coverage %, test count)\n- ✅ Final review checklist validated\n- 📁 Files created/modified (complete list with descriptions)\n- 🧪 Testing completed (unit, integration, manual)\n- 📋 Known issues or limitations (if any)\n- 🔄 Deployment/next steps (if applicable)\n\n## 10. HANDOFF SUMMARY\n- What was accomplished vs original requirements\n- Key architectural decisions made and why\n- Important implementation details for future maintainers\n- Recommended follow-up work or improvements\n- Contact points or documentation for questions\n\nConclude with a summary of any potential follow-ups or new dependencies to note.",
+            "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.",