@exaudeus/workrail 3.6.2 → 3.7.1

package/README.md

@@ -245,8 +245,12 @@ support [conditions, loops, validation criteria](docs/authoring.md), and more.
 
 - [All Workflows](docs/workflows.md) – Full list with detailed descriptions
 - [Writing Workflows](docs/authoring.md) – Custom workflow creation guide
+- [Workflow Authoring Principles (v2)](docs/authoring-v2.md) – Cross-workflow design rules and authoring principles
 - [Configuration](docs/configuration.md) – Git repos, environment variables, local paths
 - [Advanced Features](docs/advanced.md) – Loops, conditionals, validation
+- **Integrations**
+  - [Claude Code Setup](docs/integrations/claude-code.md) – Complete guide for Desktop & CLI
+  - [Firebender Setup](docs/integrations/firebender.md) – Firebender integration
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.6.2",
+  "version": "3.7.1",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

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

@@ -175,20 +175,17 @@ Retrieves workflow information with configurable detail level. Supports progress
   "jsonrpc": "2.0",
   "id": 2,
   "result": {
-    "id": "coding-task-workflow-with-loops",
-    "name": "Excellent Adaptive Coding Workflow",
-    "description": "A comprehensive workflow for AI-assisted coding",
+    "id": "coding-task-workflow-agentic",
+    "name": "Lean Agentic Coding Task Workflow",
+    "description": "Lean workflow for executing coding tasks with scoped design, bounded delegation, and explicit verification.",
     "version": "0.1.0",
-    "preconditions": ["User has a clear task description"],
-    "clarificationPrompts": ["What is the complexity level?"],
-    "metaGuidance": ["Follow PREP -> IMPLEMENT -> VERIFY pattern"],
-    "totalSteps": 8,
+    "preconditions": ["Task description is available and any required codebase or artifact access is accessible to the agent."],
+    "metaGuidance": ["Stay outcome-focused and evidence-based throughout the task."],
+    "totalSteps": 14,
     "firstStep": {
-      "id": "phase-0-intelligent-triage",
-      "title": "Phase 0: Intelligent Task Triage & Complexity Analysis",
-      "prompt": "**ANALYZE**: Evaluate the provided task for complexity indicators...",
-      "agentRole": "You are a technical assessment specialist...",
-      "guidance": ["Be thorough in your analysis"],
+      "id": "phase-0-understand-and-classify",
+      "title": "Phase 0: Understand & Classify",
+      "prompt": "Understand this before you touch anything....",
       "requireConfirmation": true
     }
   }
@@ -201,14 +198,13 @@ Retrieves workflow information with configurable detail level. Supports progress
   "jsonrpc": "2.0",
   "id": 2,
   "result": {
-    "id": "coding-task-workflow-with-loops",
-    "name": "Excellent Adaptive Coding Workflow",
-    "description": "A comprehensive workflow for AI-assisted coding",
+    "id": "coding-task-workflow-agentic",
+    "name": "Lean Agentic Coding Task Workflow",
+    "description": "Lean workflow for executing coding tasks with scoped design, bounded delegation, and explicit verification.",
     "version": "0.1.0",
-    "preconditions": ["User has a clear task description"],
-    "clarificationPrompts": ["What is the complexity level?"],
-    "metaGuidance": ["Follow PREP -> IMPLEMENT -> VERIFY pattern"],
-    "totalSteps": 8
+    "preconditions": ["Task description is available and any required codebase or artifact access is accessible to the agent."],
+    "metaGuidance": ["Stay outcome-focused and evidence-based throughout the task."],
+    "totalSteps": 14
   }
 }
 ```

package/workflows/cross-platform-code-conversion.v2.json

@@ -7,10 +7,6 @@
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
   },
-  "features": [
-    "wr.features.subagent_guidance",
-    "wr.features.memory_context"
-  ],
   "preconditions": [
     "User specifies source and target platforms.",
     "Agent has read access to the source codebase.",
@@ -22,6 +18,13 @@
     "SCOPE DISCIPLINE: convert only what the user scoped. Do not expand to adjacent features or modules unless explicitly asked.",
     "DEPENDENCY MAPPING: never assume a library exists on the target platform. Map each dependency to its target equivalent or flag it as needing a custom solution.",
     "PLATFORM CONVENTIONS: follow the target platform's conventions for project structure, naming, error handling, concurrency, and testing.",
+    "SEMANTIC CONTRACTS: preserve caller-visible guarantees and lifecycle behavior, not just type names or structure. Map contract-to-contract, not construct-to-construct.",
+    "ANTI-ANCHORING: existing target-platform conventions are evidence, not proof. Follow them only when they preserve the source boundary's intent and guarantees.",
+    "UNCERTAINTY STOPS PROGRESSION: if a non-trivial boundary cannot be mapped confidently, mark it uncertain and escalate instead of guessing.",
+    "TARGET REPO FIT: migrate into the target repo's actual architectural seams, not just the target platform's generic idioms.",
+    "EVIDENCE OVER FAMILIARITY: choose reuse, adaptation, or new integration points based on concrete target-repo evidence, not on the first similar-looking abstraction.",
+    "ADAPTATION DEPTH: when source and target architectures differ materially, plan the adaptation explicitly before implementation. Do not treat redesign as translation.",
+    "SEPARATE SIZE FROM ADAPTATION: a small migration can still require deep architectural adaptation. Do not use file count as a proxy for design difficulty.",
     "BUILD PROOF: code that does not build is not done. Run build or typecheck after every conversion batch.",
     "PRESERVE INTENT: the goal is functional equivalence, not line-by-line correspondence. Restructure when the target platform has a better way.",
     "TRIAGE FIRST: not all code is equal. Separate trivial translations from code needing real design decisions. Delegate the easy stuff, focus on the hard stuff.",
@@ -33,7 +36,33 @@
     {
       "id": "phase-0-scope",
       "title": "Phase 0: Scope & Platform Analysis",
-      "prompt": "Understand what you're converting before you touch anything.\n\nFigure out:\n- What is being converted? (single file, module, feature, full component, entire app)\n- What is the source platform? (Android/Kotlin, iOS/Swift, Web/React, etc.)\n- What is the target platform?\n- How large is the conversion scope? (file count, rough LOC)\n- Where does the converted code go? Find the target repo yourself before asking the user.\n\nIf the user hasn't specified scope boundaries, ask. Don't guess at scope.\n\nThen classify the conversion:\n- `conversionComplexity`: Small (1-3 files, straightforward translation) / Medium (a module or feature, mixed difficulty) / Large (many modules, significant platform-specific code)\n\nUse this guidance:\n- Small: few files, mostly mechanical, low risk of idiom mismatch\n- Medium: a module or feature with some platform-specific code mixed in\n- Large: many files, deep platform coupling, multiple idiom mapping decisions\n\nCapture:\n- `sourcePlatform`\n- `targetPlatform`\n- `conversionScope`\n- `targetRepoPath`\n- `estimatedSize`\n- `conversionComplexity`",
+      "promptBlocks": {
+        "goal": "Understand the migration scope, platforms, target repo location, and rough size before any implementation begins.",
+        "constraints": [
+          "If the user has not specified scope boundaries, ask. Do not guess at scope.",
+          "Find the target repo yourself before asking the user.",
+          "Check saved repo mappings in agent config or memory before falling back to broader discovery."
+        ],
+        "procedure": [
+          "Determine what is being converted: single file, module, feature, full component, or entire app.",
+          "Identify the source platform and target platform.",
+          "Estimate conversion size using file count and rough LOC.",
+          "Classify `conversionComplexity` as Small, Medium, or Large using this guidance: Small = 1-3 files and mostly mechanical; Medium = module or feature with mixed difficulty; Large = many files with deep platform coupling and multiple idiom-mapping decisions."
+        ],
+        "outputRequired": {
+          "sourcePlatform": "The source platform being migrated from.",
+          "targetPlatform": "The target platform being migrated to.",
+          "conversionScope": "The bounded scope of the migration.",
+          "targetRepoPath": "Where the converted code should land.",
+          "estimatedSize": "A rough estimate of migration size.",
+          "conversionComplexity": "Small, Medium, or Large."
+        },
+        "verify": [
+          "The migration scope is explicit and bounded.",
+          "The target repo location is identified or intentionally escalated.",
+          "The complexity classification matches the actual size and risk of the work."
+        ]
+      },
       "requireConfirmation": {
         "var": "conversionComplexity",
         "not_equals": "Small"
@@ -42,7 +71,7 @@
     {
       "id": "phase-1-understand-source",
       "title": "Phase 1: Understand Source Code",
-      "prompt": "Read and analyze the source code through a conversion lens — what will be easy to convert, what will be hard, and why.\n\nMap out:\n- Architecture and module structure\n- Key patterns used (MVI, MVVM, dependency injection, etc.)\n- External dependencies and what they do\n- Entry points and public API surface\n- Platform coupling depth: is the code cleanly layered or is platform-specific code smeared throughout? This directly determines how much falls into easy vs. hard buckets.\n- Concurrency model: Coroutines, Combine, RxJS, async/await? This is often the single hardest mapping decision.\n- DI approach: Dagger/Hilt, Swinject, Koin? DI frameworks rarely map 1:1.\n- Test coverage shape: unit tests on business logic (convert easily), UI tests (likely rewrite), integration tests (depends on infra).\n- Shared code boundaries: is there already a shared/common module that might not need conversion at all?\n\nCapture:\n- `sourceArchitecture`\n- `dependencies`\n- `publicApiSurface`\n- `platformCouplingAssessment`\n- `concurrencyModel`\n- `testCoverageShape`",
+      "prompt": "Read and analyze the source code through a conversion lens — what will be easy to convert, what will be hard, and why.\n\nMap out:\n- Architecture and module structure\n- Key patterns used (MVI, MVVM, dependency injection, etc.)\n- External dependencies and what they do\n- Entry points and public API surface\n- Platform coupling depth: is the code cleanly layered or is platform-specific code smeared throughout? This directly determines how much falls into easy vs. hard buckets.\n- Concurrency model: Coroutines, Combine, RxJS, async/await? This is often the single hardest mapping decision.\n- DI approach: Dagger/Hilt, Swinject, Koin? DI frameworks rarely map 1:1.\n- Test coverage shape: unit tests on business logic (convert easily), UI tests (likely rewrite), integration tests (depends on infra).\n- Shared code boundaries: is there already a shared/common module that might not need conversion at all?\n- Non-trivial migration boundaries: public APIs, externally consumed module boundaries, and lifecycle/state/concurrency/resource boundaries that callers depend on.\n- Caller-visible guarantees for those boundaries. Examples include lifecycle/ownership, laziness vs eagerness, shared vs per-consumer behavior, cancellation/disposal, ordering/replay/buffering, failure behavior, threading/scheduling, or consistency/transaction guarantees.\n- Adaptation depth: classify whether the migration is `low`, `moderate`, or `high` adaptation based on architectural mismatch, missing target-side equivalents, lifecycle/state/concurrency mismatch, and the amount of adapter or redesign work needed.\n\nIdentify which files define or materially affect those boundaries and which of them will require target-repo integration analysis.\n\nCapture:\n- `sourceArchitecture`\n- `dependencies`\n- `publicApiSurface`\n- `platformCouplingAssessment`\n- `concurrencyModel`\n- `testCoverageShape`\n- `semanticBoundaryCandidates`\n- `boundaryCriticalFiles`\n- `adaptationProfile`",
       "promptFragments": [
         {
           "id": "phase-1-small-light",
@@ -50,41 +79,146 @@
           "text": "For Small conversions, keep this lightweight. A quick read of the files in scope is enough — don't map the entire architecture. Focus on identifying any platform-specific code that would prevent a straight translation."
         }
       ],
-      "requireConfirmation": false
+      "requireConfirmation": {
+        "var": "adaptationProfile",
+        "equals": "high"
+      }
     },
     {
       "id": "phase-small-fast-path",
       "title": "Small Conversion Fast Path",
       "runCondition": {
-        "var": "conversionComplexity",
-        "equals": "Small"
+        "and": [
+          { "var": "conversionComplexity", "equals": "Small" },
+          { "var": "adaptationProfile", "equals": "low" }
+        ]
       },
-      "prompt": "For Small conversions, skip triage and planning — just convert.\n\n- Translate the files to the target platform idiomatically\n- Follow target platform naming and structure conventions\n- Map any dependencies to target equivalents\n- Convert tests if they exist\n- Run build or typecheck to verify\n\nIf something turns out harder than expected (deep platform coupling, no clean dependency equivalent), update `conversionComplexity` to `Medium` and stop. The full triage and planning pipeline will activate for the remaining work.\n\nCapture:\n- `filesConverted`\n- `buildPassed`\n- `conversionComplexity`",
+      "prompt": "For Small conversions, skip triage and planning — just convert.\n\n- Translate the files to the target platform idiomatically\n- Follow target platform naming and structure conventions\n- Map any dependencies to target equivalents\n- Convert tests if they exist\n- Run build or typecheck to verify\n\nIf something turns out harder than expected (deep platform coupling, no clean dependency equivalent, or meaningful architectural mismatch), update `conversionComplexity` to `Medium`, update `adaptationProfile` to `moderate` or `high` based on the newly discovered mismatch, and stop. The full triage and planning pipeline will activate for the remaining work.\n\nCapture:\n- `filesConverted`\n- `buildPassed`\n- `conversionComplexity`\n- `adaptationProfile`",
       "requireConfirmation": false
     },
     {
       "id": "phase-2-triage",
       "title": "Phase 2: Triage & Sort",
       "runCondition": {
-        "var": "conversionComplexity",
-        "not_equals": "Small"
+        "or": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "var": "adaptationProfile", "not_equals": "low" }
+        ]
       },
-      "prompt": "Classify every file or module in scope into one of three buckets:\n\n**Bucket A — Literal translation**: Platform-agnostic business logic, data models, utilities, pure functions. These use no platform-specific APIs or libraries. Conversion is mechanical: translate the language syntax, follow target naming conventions, done. These will be delegated to subagents.\n\n**Bucket B — Library substitution**: Code that uses platform-specific libraries (networking, persistence, serialization, DI) but follows standard patterns. These need dependency mapping but the structure stays the same.\n\n**Bucket C — Platform-specific**: Code deeply tied to the platform (UI layer, lifecycle management, concurrency/threading, navigation, platform APIs). These need design decisions about target-platform idioms.\n\nFor each file or module, list:\n- File/module name\n- Bucket (A, B, or C)\n- One-line reason for classification\n- Dependencies it has on other files in scope (so we know conversion order)\n\nSort the work items within each bucket by dependency order (convert dependencies first).\n\nGroup Bucket A files into parallel batches of 3-5 files each. Each batch should contain files with no cross-dependencies so subagents can work independently.\n\nGroup Bucket B and C files into sequential batches by dependency order.\n\nEach batch should have: `name` (short label), `bucket` (A, B, or C), and `files` (list of file paths).\n\nCapture:\n- `bucketABatches` (parallel batches for subagent delegation)\n- `bucketBCBatches` (sequential batches for main agent)\n- `bucketACounts`\n- `bucketBCounts`\n- `bucketCCounts`",
+      "prompt": "Classify every file or module in scope into one of three buckets:\n\n**Bucket A — Literal translation**: Platform-agnostic business logic, data models, utilities, pure functions. These use no platform-specific APIs or libraries. Conversion is mechanical: translate the language syntax, follow target naming conventions, done. These will be delegated to subagents.\n\n**Bucket B — Library substitution**: Code that uses platform-specific libraries (networking, persistence, serialization, DI) but follows standard patterns. These need dependency mapping but the structure stays the same.\n\n**Bucket C — Platform-specific**: Code deeply tied to the platform (UI layer, lifecycle management, concurrency/threading, navigation, platform APIs). These need design decisions about target-platform idioms.\n\nFor each file or module, list:\n- File/module name\n- Bucket (A, B, or C)\n- One-line reason for classification\n- Dependencies it has on other files in scope (so we know conversion order)\n- Whether it is `boundaryCritical` for a non-trivial migration boundary\n- Which semantic boundaries it affects from `semanticBoundaryCandidates`\n- Whether it will require target-repo integration analysis\n\nBoundary-critical files must not be treated as blind mechanical translation just because the syntax looks simple. If a file materially affects a semantic boundary or destination-repo seam, keep it with main-agent review.\n\nSort the work items within each bucket by dependency order (convert dependencies first).\n\nGroup Bucket A files into parallel batches of 3-5 files each. Each batch should contain files with no cross-dependencies so subagents can work independently.\n\nGroup Bucket B and C files into sequential batches by dependency order.\n\nEach batch should have: `name` (short label), `bucket` (A, B, or C), and `files` (list of file paths).\n\nCapture:\n- `bucketABatches` (parallel batches for subagent delegation)\n- `bucketBCBatches` (sequential batches for main agent)\n- `bucketACounts`\n- `bucketBCounts`\n- `bucketCCounts`\n- `boundaryCriticalItems`",
       "requireConfirmation": true
     },
     {
-      "id": "phase-3-plan-hard-items",
-      "title": "Phase 3: Plan Platform-Specific Conversions",
+      "id": "phase-3a-semantic-contracts",
+      "title": "Phase 3a: Semantic Contract Inventory",
       "runCondition": {
-        "var": "conversionComplexity",
-        "not_equals": "Small"
+        "or": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "var": "adaptationProfile", "not_equals": "low" }
+        ]
+      },
+      "prompt": "Before planning implementation, create a compact semantic contract inventory for the non-trivial migration boundaries in scope.\n\nFocus on:\n- Public APIs\n- Externally consumed module boundaries\n- Lifecycle/state/concurrency/resource boundaries that callers rely on\n\nFor each boundary, record:\n- `boundary`: short identifier for the surface\n- `sourceSurface`: source API or construct\n- `keyGuarantees`: the caller-visible guarantees that must remain true\n- `targetConstruct`: chosen target type or pattern\n- `status`: `preserved`, `intentionally_changed`, or `uncertain`\n- `rationale`\n- `verificationPlan`\n\nUse examples of semantic dimensions as examples only, not a mandatory checklist: lifecycle/ownership, laziness vs eagerness, shared vs per-consumer behavior, cancellation/disposal, ordering/replay/buffering, failure behavior, threading/scheduling, or consistency/transaction guarantees.\n\nIf a boundary cannot be mapped confidently, mark it `uncertain` rather than guessing.\n\nCapture:\n- `semanticContractInventory`\n- `hasUncertainBoundaries`\n- `hasIntentionalBoundaryChanges`",
+      "promptFragments": [
+        {
+          "id": "phase-3a-medium-focused",
+          "when": { "var": "conversionComplexity", "equals": "Medium" },
+          "text": "For Medium conversions, inventory only the non-trivial boundaries actually touched by the scoped work. Don't expand this into a whole-system audit."
+        },
+        {
+          "id": "phase-3a-high-adaptation",
+          "when": { "var": "adaptationProfile", "equals": "high" },
+          "text": "For high-adaptation migrations, cover every touched non-trivial boundary and explicitly call out where the contract is likely to be preserved, intentionally changed, or under architectural pressure."
+        }
+      ],
+      "requireConfirmation": {
+        "or": [
+          { "var": "hasUncertainBoundaries", "equals": true },
+          { "var": "hasIntentionalBoundaryChanges", "equals": true }
+        ]
+      }
+    },
+    {
+      "id": "phase-3b-target-integration",
+      "title": "Phase 3b: Target Integration Analysis",
+      "runCondition": {
+        "or": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "var": "adaptationProfile", "not_equals": "low" }
+        ]
+      },
+      "prompt": "For each touched non-trivial migration boundary, analyze how it should fit into the target repo.\n\nThis step is about destination-repo fit, not source semantic guarantees. `semanticContractInventory` defines what must remain true. This step defines where the migrated boundary belongs and what target seams it must satisfy.\n\nFocus only on touched boundaries, not the whole target repo.\n\nFor each boundary, record:\n- `boundary`\n- `targetArea`: target module/layer/package/file area it belongs in\n- `existingPattern`: nearest relevant target abstraction or convention\n- `integrationPoints`: callers, adapters, DI/state/navigation/lifecycle hooks, persistence/network seams, or other required target touchpoints\n- `constraints`: repo-specific rules this boundary must satisfy\n- `decision`: `reuse_as_is`, `reuse_with_adapter`, `extend_existing`, `introduce_new`, or `defer_pending_decision`\n- `fitAssessment`: why the nearest existing abstraction is appropriate, insufficient, or misleading\n- `integrationRisk`: `low`, `medium`, or `high`\n- `uncertain`: `true` or `false`\n- `evidenceFiles`: concrete target files observed\n- `evidenceSymbols`: concrete target symbols observed\n- `rationale`\n\nUse concrete evidence from the target repo. Existing target code is evidence, not authority.\n\nCapture:\n- `targetIntegrationAnalysis`\n- `hasUncertainIntegrationPoints`",
+      "promptFragments": [
+        {
+          "id": "phase-3b-medium-focused",
+          "when": { "var": "conversionComplexity", "equals": "Medium" },
+          "text": "For Medium conversions, analyze only the touched boundaries that need real destination-repo decisions. Do not expand this into a broad target-architecture survey."
+        },
+        {
+          "id": "phase-3b-high-adaptation",
+          "when": { "var": "adaptationProfile", "equals": "high" },
+          "text": "For high-adaptation migrations, compare at least one plausible alternative target area or seam for each important boundary and explain why the chosen fit is still the best one."
+        }
+      ],
+      "requireConfirmation": {
+        "var": "hasUncertainIntegrationPoints",
+        "equals": true
+      }
+    },
+    {
+      "id": "phase-3c-design-brief",
+      "title": "Phase 3c: Prepare High-Adaptation Design Brief",
+      "runCondition": {
+        "var": "adaptationProfile",
+        "equals": "high"
+      },
+      "prompt": "Prepare a concise design brief for the high-adaptation design routine.\n\nSummarize:\n- the migration scope and non-goals\n- the most important rows from `semanticContractInventory`\n- the most important rows from `targetIntegrationAnalysis`\n- the architectural tensions driving adaptation difficulty\n- the constraints that make this migration more than straightforward translation\n\nTurn that into explicit routine inputs:\n- `problemStatement`: what design problem the routine should solve\n- `acceptanceCriteria`: the contract and target-fit outcomes the design must satisfy\n- `nonGoals`: what the migration should not expand into\n- `relevantFiles`: the most important source and target files the routine should study\n- `philosophySources`: any repo rules or sources that should constrain the design\n\nWrite the human-readable brief to `conversion-design-brief.md`, but make the captured context variables the primary handoff to the routine.\n\nCapture:\n- `designBriefReady`\n- `problemStatement`\n- `acceptanceCriteria`\n- `nonGoals`\n- `relevantFiles`\n- `philosophySources`",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3d-design-generation",
+      "title": "Phase 3d: High-Adaptation Design Generation",
+      "runCondition": {
+        "var": "adaptationProfile",
+        "equals": "high"
       },
-      "prompt": "For Bucket B and Bucket C items, plan the conversion before writing code.\n\nFor Bucket B (library substitution):\n- Map each source dependency to its target-platform equivalent\n- If no equivalent exists, flag it and propose an alternative\n\nFor Bucket C (platform-specific):\n- Threading/concurrency model mapping\n- UI framework mapping\n- DI framework mapping\n- State management mapping\n- Error handling mapping\n- Navigation patterns\n- Lifecycle management approach\n- Testing framework mapping\n\nFor anything with no clean target equivalent, propose an idiomatic solution and explain the tradeoff.\n\nBucket A items don't need a plan. They're mechanical translation handled by subagents.\n\nCapture:\n- `idiomMapping`\n- `dependencyMapping`\n- `tradeoffs`",
+      "templateCall": {
+        "templateId": "wr.templates.routine.tension-driven-design",
+        "args": {
+          "deliverableName": "conversion-design-candidates.md"
+        }
+      },
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3e-select-adaptation-approach",
+      "title": "Phase 3e: Select Adaptation Approach",
+      "runCondition": {
+        "var": "adaptationProfile",
+        "equals": "high"
+      },
+      "prompt": "Read `conversion-design-candidates.md`, compare the candidates against `semanticContractInventory` and `targetIntegrationAnalysis`, and choose the adaptation approach.\n\nBe explicit about:\n- what the design work confirmed\n- what changed your mind\n- what target-repo fit or contract pressure matters most\n- what architecture-level adaptation is intentional rather than accidental\n\nCapture:\n- `selectedAdaptationApproach`\n- `runnerUpAdaptationApproach`\n- `architectureAdaptationPlan`\n- `adaptationPivotTriggers`\n- `adaptationFailureModes`",
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-3f-plan-hard-items",
+      "title": "Phase 3f: Plan Platform-Specific Conversions",
+      "runCondition": {
+        "or": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "var": "adaptationProfile", "not_equals": "low" }
+        ]
+      },
+      "prompt": "For Bucket B and Bucket C items, plan the conversion before writing code.\n\nUse both `semanticContractInventory` and `targetIntegrationAnalysis` as required inputs. If `adaptationProfile` is `high`, also use `architectureAdaptationPlan` as a required input. The implementation plan must preserve boundary contracts and fit the target repo's actual seams.\n\nFor Bucket B (library substitution):\n- Map each source dependency to its target-platform equivalent\n- If no equivalent exists, flag it and propose an alternative\n\nFor Bucket C (platform-specific):\n- Threading/concurrency model mapping\n- UI framework mapping\n- DI framework mapping\n- State management mapping\n- Error handling mapping\n- Navigation patterns\n- Lifecycle management approach\n- Testing framework mapping\n- Target module/layer placement and adapter seams\n\nFor anything with no clean target equivalent, propose an idiomatic solution and explain the tradeoff.\n\nBucket A items don't need a plan. They're mechanical translation handled by subagents.\n\nCapture:\n- `idiomMapping`\n- `dependencyMapping`\n- `tradeoffs`",
       "promptFragments": [
         {
-          "id": "phase-3-medium-focused",
+          "id": "phase-3f-medium-focused",
           "when": { "var": "conversionComplexity", "equals": "Medium" },
           "text": "For Medium conversions, focus the plan on the items that actually need design decisions. Don't exhaustively map every dimension — only the ones relevant to the files in scope."
+        },
+        {
+          "id": "phase-3f-high-adaptation",
+          "when": { "var": "adaptationProfile", "equals": "high" },
+          "text": "For high-adaptation migrations, state clearly what is translated directly, what is adapted through seams or adapters, and what is intentionally redesigned."
         }
       ],
       "requireConfirmation": true
@@ -94,11 +228,40 @@
       "title": "Phase 4: Delegate Bucket A (Parallel Subagents)",
       "runCondition": {
         "and": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
+          {
+            "or": [
+              { "var": "conversionComplexity", "not_equals": "Small" },
+              { "var": "adaptationProfile", "not_equals": "low" }
+            ]
+          },
           { "var": "bucketACounts", "not_equals": 0 }
         ]
       },
-      "prompt": "Delegate all Bucket A batches to subagents in parallel. If subagent delegation is not available in your environment, convert Bucket A files yourself sequentially — they're mechanical translations.\n\nFor each batch in `bucketABatches`, spawn a subagent with these instructions:\n- Source platform: `{{sourcePlatform}}`\n- Target platform: `{{targetPlatform}}`\n- Target repo: `{{targetRepoPath}}`\n- Files to convert: (list the specific files in this batch)\n- Task: translate these files from the source language to the target language. Follow target platform naming conventions. These are platform-agnostic files — no library substitution or idiom mapping needed. Preserve the public API. Convert tests if they exist.\n\nRun batches in parallel. Each subagent works independently on files with no cross-dependencies.\n\nWhen all subagents finish, review their output:\n- Spot-check a few converted files for quality\n- Flag any files a subagent misclassified as easy (actually needs library substitution or platform-specific handling)\n- Move misclassified files back to the appropriate bucket for main agent handling\n\nRun build or typecheck on the Bucket A output to catch issues early.\n\nCapture:\n- `bucketAComplete`\n- `bucketABuildPassed`\n- `reclassifiedFiles`",
+      "promptBlocks": {
+        "goal": "Delegate only safe mechanical conversion work from Bucket A while keeping all real judgment and synthesis with the main agent.",
+        "constraints": [
+          "Delegate only files that are not boundary-critical and do not require unresolved target integration analysis.",
+          "If `adaptationProfile` is `high`, delegate only clearly mechanical files with no boundary or integration ambiguity.",
+          "If a supposedly easy file affects a semantic boundary, a target-repo seam, or requires contract judgment, keep it with main-agent review."
+        ],
+        "procedure": [
+          "If subagent delegation is not available in your environment, convert Bucket A files yourself sequentially instead.",
+          "For each batch in `bucketABatches`, delegate a bounded translation task using `sourcePlatform`, `targetPlatform`, `targetRepoPath`, and the specific files in that batch.",
+          "Instruct subagents to perform only platform-agnostic translation, follow target naming conventions, preserve the public API, and convert tests if they exist.",
+          "After all batches finish, spot-check the output, flag misclassified files, and move them back to the appropriate main-agent bucket.",
+          "Run build or typecheck on the Bucket A output before continuing."
+        ],
+        "outputRequired": {
+          "bucketAComplete": "Whether Bucket A work is complete.",
+          "bucketABuildPassed": "Whether the delegated Bucket A output builds or typechecks cleanly.",
+          "reclassifiedFiles": "Any files that were delegated but need to return to main-agent handling."
+        },
+        "verify": [
+          "No ambiguous or boundary-critical files were delegated as mechanical work.",
+          "Delegated output was reviewed by the main agent before proceeding.",
+          "Misclassified files were re-routed instead of being silently accepted."
+        ]
+      },
       "requireConfirmation": false
     },
     {
@@ -106,8 +269,10 @@
       "type": "loop",
       "title": "Phase 5: Convert Bucket B & C (Main Agent)",
       "runCondition": {
-        "var": "conversionComplexity",
-        "not_equals": "Small"
+        "or": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "var": "adaptationProfile", "not_equals": "low" }
+        ]
       },
       "loop": {
         "type": "forEach",
@@ -120,7 +285,45 @@
         {
           "id": "phase-5a-convert-batch",
           "title": "Convert Current Batch",
-          "prompt": "Convert the current batch: `{{currentBatch.name}}`\n\nThis is Bucket B or C code that needs your full context.\n\n- **Bucket B**: Follow the dependency mapping from Phase 3. Substitute libraries, keep structure.\n- **Bucket C**: Follow the idiom mapping from Phase 3. Restructure where the target platform has a better way.\n\nAlso handle any `reclassifiedFiles` that were moved back from Bucket A delegation.\n\nFor all files:\n- Follow target platform conventions\n- Preserve public API contracts where possible\n- Add TODO comments for anything uncertain\n- Convert tests alongside production code when source tests exist\n\nRun build or typecheck after this batch. If it fails, fix it before moving on.\n\nTrack whether this batch required:\n- `bucketDriftDetected`: a file turned out to be harder than its bucket classification (e.g., Bucket B file needed Bucket C-level design decisions)\n- `unexpectedDependency`: a dependency was discovered that wasn't in the Phase 3 mapping\n- `buildBroke`: build or typecheck failed after this batch\n\nCapture:\n- `batchFilesConverted`\n- `batchBuildPassed`\n- `batchIssues`\n- `bucketDriftDetected`\n- `unexpectedDependency`\n- `buildBroke`",
+          "promptBlocks": {
+            "goal": "Convert the current Bucket B or C batch using the approved plan, contract inventory, and target-integration analysis.",
+            "constraints": [
+              "Follow target platform conventions.",
+              "Preserve public API contracts where possible.",
+              "Fit the target repo's actual architectural seams.",
+              "Add TODO comments for anything uncertain.",
+              "Convert tests alongside production code when source tests exist."
+            ],
+            "procedure": [
+              "Convert `{{currentBatch.name}}` using the dependency mapping and idiom mapping from Phase 3f.",
+              "For any touched boundary, consult both `semanticContractInventory` and `targetIntegrationAnalysis`.",
+              "If `adaptationProfile` is `high`, also follow `architectureAdaptationPlan`.",
+              "If the chosen target construct, target seam, or reuse/adaptation decision changes, update the relevant artifact rows rather than letting implementation drift silently.",
+              "Also handle any `reclassifiedFiles` that returned from Bucket A delegation.",
+              "Run build or typecheck after this batch and fix failures before moving on."
+            ],
+            "outputRequired": {
+              "batchFilesConverted": "The files converted in this batch.",
+              "batchBuildPassed": "Whether the batch builds or typechecks cleanly.",
+              "batchIssues": "Problems encountered while converting the batch.",
+              "bucketDriftDetected": "Whether the batch proved harder than its original bucket classification.",
+              "unexpectedDependency": "Whether the batch exposed a dependency missing from the prior plan.",
+              "buildBroke": "Whether build or typecheck failed after the batch.",
+              "contractDriftDetected": "Whether implementation forced a semantic-contract change.",
+              "contractRowsUpdated": "Whether semantic contract rows were revised.",
+              "contractUncertain": "Whether a touched boundary can no longer be mapped confidently.",
+              "integrationDriftDetected": "Whether implementation forced a change to target seam or reuse/adaptation choice.",
+              "integrationAnalysisUpdated": "Whether target integration rows were revised.",
+              "integrationUncertain": "Whether a touched boundary no longer has a confident target-repo fit.",
+              "architectureDriftDetected": "Whether high-adaptation implementation diverged from the architecture adaptation plan.",
+              "adaptationPlanUpdated": "Whether the architecture adaptation plan was revised for this batch."
+            },
+            "verify": [
+              "Any contract or integration drift is reflected explicitly in the tracked artifacts.",
+              "No touched boundary is left without a clear contract and target-fit status.",
+              "The batch is build-clean or the failure has been captured for immediate follow-up."
+            ]
+          },
           "requireConfirmation": false
         },
         {
@@ -130,13 +333,47 @@
             "or": [
               { "var": "bucketDriftDetected", "equals": true },
               { "var": "unexpectedDependency", "equals": true },
-              { "var": "buildBroke", "equals": true }
+              { "var": "buildBroke", "equals": true },
+              { "var": "contractDriftDetected", "equals": true },
+              { "var": "contractUncertain", "equals": true },
+              { "var": "integrationDriftDetected", "equals": true },
+              { "var": "integrationUncertain", "equals": true },
+              { "var": "architectureDriftDetected", "equals": true }
+            ]
+          },
+          "promptBlocks": {
+            "goal": "Resolve unexpected batch drift before continuing so downstream work is not based on stale assumptions.",
+            "constraints": [
+              "Do not silently absorb drift.",
+              "If a boundary can no longer be mapped confidently, stop and surface it instead of guessing."
+            ],
+            "procedure": [
+              "If `bucketDriftDetected`, update the idiom or dependency mapping from Phase 3f so later batches do not repeat the same surprise.",
+              "If `unexpectedDependency`, map it now and assess whether other batches also depend on it.",
+              "If `buildBroke`, determine whether the failure is local to this batch or cross-batch integration related, then fix it before continuing.",
+              "If `contractDriftDetected`, update `semanticContractInventory` to match the real implementation.",
+              "If `integrationDriftDetected`, update `targetIntegrationAnalysis` to match the actual target seam and reuse/adaptation choice.",
+              "If `architectureDriftDetected`, update `architectureAdaptationPlan` before continuing."
+            ],
+            "outputRequired": {
+              "mappingUpdated": "Whether the implementation mapping was revised.",
+              "contractInventoryUpdated": "Whether the semantic contract inventory was revised.",
+              "targetIntegrationUpdated": "Whether the target integration analysis was revised.",
+              "adaptationPlanUpdated": "Whether the architecture adaptation plan was revised.",
+              "verificationPassed": "Whether the batch is safe to continue past."
+            },
+            "verify": [
+              "Any real drift is reflected in the planning artifacts.",
+              "Uncertainty is surfaced instead of hidden.",
+              "The next batch will not proceed from stale assumptions."
             ]
           },
-          "prompt": "Something unexpected happened in this batch. Before moving on, check what went wrong.\n\nIf `bucketDriftDetected`: the file was harder than classified. Update the idiom or dependency mapping from Phase 3 so downstream batches don't hit the same surprise. Record what changed.\n\nIf `unexpectedDependency`: a dependency wasn't in the Phase 3 plan. Map it now and check whether other batches depend on the same thing.\n\nIf `buildBroke`: diagnose whether the failure is local to this batch or a cross-batch integration issue. Fix it before continuing.\n\nIf the drift is severe enough that the Phase 3 plan is unreliable, say so. Don't silently absorb complexity.\n\nCapture:\n- `mappingUpdated`\n- `verificationPassed`",
           "requireConfirmation": {
-            "var": "bucketDriftDetected",
-            "equals": true
+            "or": [
+              { "var": "contractUncertain", "equals": true },
+              { "var": "integrationUncertain", "equals": true },
+              { "var": "architectureDriftDetected", "equals": true }
+            ]
           }
         }
       ]
@@ -146,8 +383,10 @@
       "type": "loop",
       "title": "Phase 6: Final Verification",
       "runCondition": {
-        "var": "conversionComplexity",
-        "not_equals": "Small"
+        "or": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "var": "adaptationProfile", "not_equals": "low" }
+        ]
       },
       "loop": {
         "type": "while",
@@ -162,7 +401,7 @@
         {
           "id": "phase-6a-full-build",
           "title": "Full Build and Integration Check",
-          "prompt": "Run a full build or typecheck on the entire converted codebase — both subagent-converted and main-agent-converted code together.\n\nCheck for:\n- Build/compile errors from cross-batch integration issues\n- Inconsistencies between subagent output and main agent output (naming, patterns)\n- Non-idiomatic patterns that slipped through\n- Missing error handling at module boundaries\n- Threading or concurrency issues across modules\n- Broken public API contracts\n\nFix each issue. If a fix is a band-aid over a deeper mapping problem, go back and fix the mapping.\n\nCapture:\n- `fullBuildPassed`\n- `integrationIssues`\n- `issuesFixed`",
+          "prompt": "Run a full build or typecheck on the entire converted codebase — both subagent-converted and main-agent-converted code together.\n\nCheck for:\n- Build/compile errors from cross-batch integration issues\n- Inconsistencies between subagent output and main agent output (naming, patterns)\n- Non-idiomatic patterns that slipped through\n- Missing error handling at module boundaries\n- Threading or concurrency issues across modules\n- Broken public API contracts\n- Contract inventory drift: every row in `semanticContractInventory` is still accounted for, no `uncertain` rows remain, preserved contracts still look preserved, and intentional changes are still justified\n- Target integration drift: code landed in the intended target layer/module, reuse/adaptation decisions still fit the observed target seams, and no unresolved target integration uncertainties remain\n- High-adaptation architecture drift: if `adaptationProfile` is `high`, the final code still matches `architectureAdaptationPlan` and any deviations are explicit and justified\n\nFix each issue. If a fix is a band-aid over a deeper mapping problem, go back and fix the mapping.\n\nCapture:\n- `fullBuildPassed`\n- `integrationIssues`\n- `issuesFixed`",
           "requireConfirmation": false
         },
         {
@@ -179,7 +418,7 @@
     {
       "id": "phase-7-handoff",
       "title": "Phase 7: Handoff",
-      "prompt": "Summarize what was converted.\n\nInclude:\n- Source and target platforms\n- Total files converted\n- Build/typecheck status\n- Known gaps, TODOs, or limitations\n- What would need manual attention\n\nKeep it concise. The converted code is the deliverable.",
+      "prompt": "Summarize what was converted.\n\nInclude:\n- Source and target platforms\n- Total files converted\n- Build/typecheck status\n- Adaptation profile used\n- Known gaps, TODOs, or limitations\n- What would need manual attention\n\nKeep it concise. The converted code is the deliverable.",
       "promptFragments": [
         {
           "id": "phase-7-small-summary",
@@ -188,8 +427,13 @@
         },
         {
           "id": "phase-7-full-summary",
-          "when": { "var": "conversionComplexity", "not_equals": "Small" },
-          "text": "Also include: bucket breakdown (A/B/C counts), delegation results (how many files delegated, subagent quality, any reclassified), key idiom mapping decisions, and dependency substitutions."
+          "when": {
+            "or": [
+              { "var": "conversionComplexity", "not_equals": "Small" },
+              { "var": "adaptationProfile", "not_equals": "low" }
+            ]
+          },
+          "text": "Also include: bucket breakdown (A/B/C counts), delegation results (how many files delegated, subagent quality, any reclassified), key idiom mapping decisions, dependency substitutions, notable preserved contracts, notable target integration decisions, any intentional semantic changes, the selected adaptation approach, any architecture adaptation choices, and any boundaries needing manual review."
         }
       ],
       "notesOptional": true,

package/workflows/coding-task-workflow-with-loops.json

@@ -1,521 +0,0 @@
-{
-    "id": "coding-task-workflow-with-loops",
-    "name": "Excellent Adaptive Coding Workflow with Devil's Advocate Review",
-    "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.",
-        "Git repository is recommended for version control and commits (workflow degrades gracefully if unavailable)."
-    ],
-    "metaGuidance": [
-        "**FUNCTION DEFINITIONS:** fun updateDecisionLog() = 'Update Decision Log in CONTEXT.md: file paths/ranges, excerpts, why important, outcome impact. Limit 3-5 files/decision.'",
-        "fun useTools() = 'Use tools to verify—never guess. Expand file reads to imports/models/interfaces/classes/deps. Trace all dependencies.'",
-        "fun createFile(filename) = 'Use edit_file to create/update {filename}. NEVER output full content in chat—only summarize. If fails, request user help & log command.'",
-        "fun applyUserRules() = 'Apply & reference user-defined rules, patterns & preferences. Document alignment in Decision Log. Explain rule influence in decisions.'",
-        "fun matchPatterns() = 'Use codebase_search/grep to find similar patterns. Reference Decision Log patterns. Match target area unless user rules override.'",
-        "fun addResumptionJson(phase) = 'Update CONTEXT.md with: 1) workflow_get (id: coding-task-workflow-with-loops, mode: preview), 2) workflow_next JSON with workflowId, completedSteps up to {phase}, all continue_workflow context keys.'",
-        "fun gitCommit(type, msg) = 'If git available: commit with {type}: {msg}. If unavailable: log in CONTEXT.md with timestamp.'",
-        "fun verifyImplementation() = '1) Test coverage >80%, 2) Run full test suite, 3) Self-review. Max 2 attempts before failure protocol.'",
-        "fun checkAutomation(action) = 'High: auto-{action} if confidence >8. Medium: request confirmation. Low: extra confirmations.'",
-        "fun trackProgress(completed, current) = '✅ Completed: {completed}, 🔄 Current: {current}, ⏳ Remaining phases, 📁 Files created.'",
-        "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:** If git unavailable/fails, skip commits/branches, log changes in CONTEXT.md with timestamps. Warn at phase-6. Document file mods for manual VC.",
-        "**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 variables across steps via context/external state/response metadata. Reset flags (e.g., proposedDowngrade) after confirmation.",
-        "Use safe git: feature branches, commit on success, clear messages, revert on fail. Log 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.",
-        "When you see function calls like updateDecisionLog() or createFile(spec.md), refer to the function definitions above for full instructions.",
-        "For resumption: Include function definitions in CONTEXT.md so new sessions understand these references. Always provide explicit workflow_get and workflow_next instructions.",
-        "Auto-advance: after completing each step, immediately get the next step; only pause for explicit requireConfirmation or missing critical inputs."
-    ],
-    "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 these keys in the next `continue_workflow` call's `context` object 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-0b-user-rules-identification",
-            "title": "Phase 0b: Identify Relevant User Rules",
-            "prompt": "**OBJECTIVE:** Review and explicitly list all user-defined rules, preferences, and patterns that are relevant to this task.\n\n**ACTIONS:**\n1. **Check for user rules** in:\n   - User preferences/settings\n   - Project documentation\n   - Previous instructions or context\n   - Memory/knowledge base\n\n2. **Categorize rules by type:**\n   - **Architecture:** Design patterns, system structure preferences\n   - **Coding Standards:** Naming conventions, code style, formatting\n   - **Libraries/Frameworks:** Preferred tools, banned dependencies\n   - **Testing:** Test structure, coverage requirements, frameworks\n   - **Documentation:** Comment styles, doc generation preferences\n   - **Git/Version Control:** Commit message formats, branching strategies\n   - **Other:** Any project-specific guidelines\n\n3. **Filter for relevance:** Only list rules that apply to this specific task\n\n4. **Create explicit list:** Format as a clear, numbered list that will be referenced throughout the workflow\n\n**OUTPUT EXAMPLE:**\n```\nRelevant User Rules for this task:\n1. Architecture: Use dependency injection pattern\n2. Architecture: Prefer immutability patterns\n3. Coding: Use camelCase for functions, PascalCase for classes\n4. Libraries: Prefer native solutions over external dependencies\n5. Testing: Minimum 80% coverage, use Jest framework\n6. Git: Use conventional commits format\n```\n\n**Set these as `userRules` context variable for reference in all subsequent steps.**",
-            "agentRole": "You are a meticulous requirements analyst focused on capturing and clarifying all user-defined constraints and preferences. Your role is to ensure no important rule or preference is overlooked.",
-            "guidance": [
-                "This step runs for ALL complexity levels (Small, Medium, Large)",
-                "Be thorough but concise - capture the essence of each rule",
-                "If no explicit rules exist, note that and proceed with standard practices",
-                "These rules will be referenced throughout the workflow",
-                "Update this list if new rules are discovered during the workflow"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-0c-overview-gathering",
-            "runCondition": {
-                "or": [
-                    {"var": "taskComplexity", "equals": "Large"},
-                    {
-                        "and": [
-                            {"var": "taskComplexity", "equals": "Medium"},
-                            {"var": "requestDeepAnalysis", "equals": true}
-                        ]
-                    }
-                ]
-            },
-            "title": "Phase 0c: High-Level Architecture Overview",
-            "prompt": "Before deep analysis, gather a high-level overview of the codebase architecture to guide subsequent focused explorations.\n\n**OVERVIEW TASKS:**\n1. **Project Structure:** Use `list_dir` to map the directory structure and identify key areas\n2. **Entry Points:** Use `grep_search` and `read_file` to locate and understand main entry points (e.g., main.ts, index.js, app.js)\n3. **Configuration:** Read package.json, tsconfig.json, or similar files to understand dependencies and setup\n4. **Key Patterns:** Use `grep_search` to identify architectural patterns (e.g., dependency injection, MVC, microservices)\n5. **Task Relevance:** Note which modules/areas seem most relevant to the current task\n\n**OUTPUT REQUIREMENTS:**\n- Summarize the overall architecture in 500 words or less\n- Identify 3-5 key areas that warrant deeper investigation for this task\n- Note any discovered patterns that align with or conflict with user rules\n- Set `architectureOverview` context variable with your findings\n\n**Start the Decision Log:** createFile(CONTEXT.md) and updateDecisionLog() with top 3-5 files, why important, how they'll guide analysis.\n\n**Remember:** useTools() for every architectural insight.",
-            "agentRole": "You are an architectural scout mapping the codebase landscape. Your role is to quickly identify the project's structure, key patterns, and areas relevant to the task at hand. You excel at using tools efficiently to build a mental map that will guide deeper exploration.",
-            "guidance": [
-                "This step provides context for more focused deep dives",
-                "Use tools liberally but efficiently - broad strokes first",
-                "The overview should inform where to focus in subsequent analysis",
-                "Start the Decision Log that will be maintained throughout the workflow",
-                "Note alignment/conflicts with user rules from the start"
-            ],
-            "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-small-implement",
-            "runCondition": {"var": "taskComplexity", "equals": "Small"},
-            "title": "Phase Small: Simple Implementation",
-            "prompt": "Execute the simple plan you created in the preparation phase.\n\n**IMPLEMENTATION:**\n1. Review user rules from Phase 0b\n2. Work through your 2-5 step plan\n3. applyUserRules() in all changes\n4. Write basic tests as needed\n5. Verify each change works\n\n**GUIDELINES:**\n- matchPatterns() from codebase\n- Keep changes focused and minimal\n- If complexity emerges, recommend upgrade to Medium/Large\n- gitCommit(type, message) after success\n\n**VERIFICATION:**\n- Run relevant tests\n- Quick self-review\n- Ensure objectives met\n- Confirm applyUserRules()\n\nThis is streamlined for genuinely simple tasks.",
-            "agentRole": "You are implementing a simple, low-risk task. Execute efficiently while maintaining quality. If unexpected complexity arises, escalate rather than proceeding with inadequate rigor.",
-            "guidance": [
-                "Execute the plan from phase-small-prep",
-                "Keep implementation lightweight but correct",
-                "Escalate if complexity exceeds Small task scope",
-                "Single commit at the end for all changes"
-            ],
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-1-multi-analysis",
-            "type": "loop",
-            "title": "Phase 1: Multi-Step Focused Codebase Analysis",
-            "runCondition": {
-                "or": [
-                    {"var": "taskComplexity", "equals": "Large"},
-                    {
-                        "and": [
-                            {"var": "taskComplexity", "equals": "Medium"},
-                            {"var": "requestDeepAnalysis", "equals": true}
-                        ]
-                    }
-                ]
-            },
-            "loop": {
-                "type": "for",
-                "count": 4,
-                "maxIterations": 4,
-                "iterationVar": "analysisStep"
-            },
-            "body": [
-                {
-                    "id": "phase-1-step-structure",
-                    "title": "Analysis Step 1/4: Structure",
-                    "prompt": "**STEP 1: STRUCTURAL MAPPING**\\n\\nBuild on phase-0c overview, dive deeper into structure:\\n\\n1. Module organization (packages/services)\\n2. Core components (controllers/services/models)\\n3. Architectural patterns from overview\\n4. File naming conventions\\n5. Code organization\\n\\n**Actions:** useTools() with list_dir, grep_search (class/interface/export), read 2-3 files\\n\\n**Output (400 words):**\\n- Structure summary\\n- User rules alignment\\n- Areas for next steps\\n\\nupdateDecisionLog() with 3-5 key files",
-                    "agentRole": "You are conducting focused analysis step 1 of 4. Your expertise lies in understanding code structure and organization. Use tools extensively and never make assumptions.",
-                    "guidance": [
-                        "This is step 1 of a 4-step analysis process",
-                        "Each step builds on the previous findings",
-                        "Use tools liberally - verify everything",
-                        "Update the Decision Log with key discoveries",
-                        "Respect word limits to prevent context bloat",
-                        "Note alignment/conflicts with user rules"
-                    ],
-                    "runCondition": {"var": "analysisStep", "equals": 1},
-                    "requireConfirmation": false
-                },
-                {
-                    "id": "phase-1-step-modules",
-                    "title": "Analysis Step 2/4: Modules",
-                    "prompt": "**STEP 2: TASK-RELEVANT MODULES**\\n\\nFocus on task-specific modules:\\n\\n1. Target areas from mapping\\n2. Core business logic\\n3. Data models (interfaces/types/schemas)\\n4. API contracts\\n5. Pattern implementation\\n\\n**Actions:** useTools() and matchPatterns() with codebase_search, read complete files (with imports), trace flows\\n\\n**Output (400 words):**\\n- Module responsibilities\\n- Patterns to match\\n- Integration points\\n\\nupdateDecisionLog() with core logic files",
-                    "agentRole": "You are conducting focused analysis step 2 of 4. Your expertise lies in identifying and analyzing task-specific components. Use tools extensively and never make assumptions.",
-                    "guidance": [
-                        "This is step 2 of a 4-step analysis process",
-                        "Each step builds on the previous findings",
-                        "Use tools liberally - verify everything",
-                        "Update the Decision Log with key discoveries",
-                        "Respect word limits to prevent context bloat",
-                        "Note alignment/conflicts with user rules"
-                    ],
-                    "runCondition": {"var": "analysisStep", "equals": 2},
-                    "requireConfirmation": false
-                },
-                {
-                    "id": "phase-1-step-dependencies",
-                    "title": "Analysis Step 3/4: Dependencies",
-                    "prompt": "**STEP 3: DEPENDENCIES & FLOWS**\\n\\nTrace dependencies and execution:\\n\\n1. Import mapping\\n2. Data flow tracing\\n3. Integration points\\n4. Side effects\\n5. Testing patterns\\n\\n**Actions:** useTools() to follow imports, find test files, trace error handling\\n\\n**Output (400 words):**\\n- Dependency map\\n- Integration challenges\\n- Testing strategies\\n- Risk indicators\\n\\nupdateDecisionLog() with dependencies and test approaches",
-                    "agentRole": "You are conducting focused analysis step 3 of 4. Your expertise lies in tracing dependencies and system flows. Use tools extensively and never make assumptions.",
-                    "guidance": [
-                        "This is step 3 of a 4-step analysis process",
-                        "Each step builds on the previous findings",
-                        "Use tools liberally - verify everything",
-                        "Update the Decision Log with key discoveries",
-                        "Respect word limits to prevent context bloat",
-                        "Note alignment/conflicts with user rules"
-                    ],
-                    "runCondition": {"var": "analysisStep", "equals": 3},
-                    "requireConfirmation": false
-                },
-                {
-                    "id": "phase-1-step-patterns",
-                    "title": "Analysis Step 4/4: Patterns",
-                    "prompt": "**STEP 4: PATTERN DISCOVERY**\\n\\nIdentify established patterns relevant to the task type. Analyze if this is a pattern-heavy task (tests, telemetry, logging, APIs, UI components).\\n\\n**Actions:** useTools() extensively - codebase_search for concepts, grep_search for pattern markers, read_file for full examples\\n\\n**Output (400 words):**\\n- Pattern types discovered\\n- Reference implementations (with file paths)\\n- Key conventions to follow\\n- Pattern alignment recommendations\\n\\nupdateDecisionLog() with pattern templates and reference files",
-                    "agentRole": "You are conducting focused analysis step 4 of 4. Your expertise lies in discovering and documenting established implementation patterns for the specific task type. Use tools extensively and never make assumptions.",
-                    "guidance": [
-                        "This is step 4 of a 4-step analysis process",
-                        "Each step builds on the previous findings",
-                        "Use tools liberally - verify everything",
-                        "Update the Decision Log with key discoveries",
-                        "Respect word limits to prevent context bloat",
-                        "Note alignment/conflicts with user rules",
-                        "TASK TYPE ANALYSIS: Determine if this is adding tests (find test utilities, mocking patterns), telemetry/analytics (find tracking implementations, event schemas), logging/monitoring (find log formats, monitoring integrations), API endpoints (find route patterns, validation, error handling), UI components (find component patterns, styling conventions), or other pattern-heavy work",
-                        "PATTERN SEARCH STRATEGY: Use codebase_search with queries like 'How is [telemetry|testing|logging|API] implemented?'. Use grep_search for pattern markers (e.g., track, analytics, test, describe, log). Find 3-5 reference implementations similar to your task. Look for shared utilities, helpers, or base classes. Check for pattern documentation in README or docs",
-                        "PATTERN EXTRACTION: Document file structure and naming conventions, common imports and dependencies, implementation approach (functional vs class-based), error handling patterns, configuration patterns, and testing approach for this type of feature",
-                        "PATTERN VALIDATION: List discovered patterns with file references. Note any conflicting patterns or multiple approaches. Ask user: 'Found these pattern examples: [list files]. Should I follow these patterns, or are there other preferred examples?' Set establishedPatterns context variable",
-                        "FOCUS ON REUSABILITY: Patterns help avoid reinventing the wheel. Look especially for utility functions, base classes, shared components, or established conventions that should be followed"
-                    ],
-                    "runCondition": {"var": "analysisStep", "equals": 4},
-                    "requireConfirmation": false
-                }
-            ],
-            "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": "Create a precise specification from Phase 1 analysis, Phase 2 clarifications, and any re-triage insights.\n\n**Spec Sections:**\n- Task Description [from clarifications]\n- Key Objectives & Success Criteria\n- Scope and Constraints\n\n**Must Include:**\n- Existing patterns/conventions from analysis\n- System integration approach\n- Impact on components/workflows\n- Testing/quality alignment\n- Phase 2 decisions\n- Complexity insights\n- applyUserRules()\n- matchPatterns()\n\n**Actions:**\n- createFile(spec.md)\n- updateDecisionLog()\n- Sanity check complexity level",
-            "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 CONTEXT.md capturing workflow progress. High automation: 1000 words; else 2000.\n\n**Include Sections:**\n\n1. ORIGINAL TASK CONTEXT\n- Task description, complexity level, re-triage decisions, automation level\n\n2. USER RULES AND PREFERENCES\n- Rules from Phase 0b, task impact, new discoveries\n\n3. CODEBASE ANALYSIS SUMMARY\n- Patterns, components, testing, dependencies, complexity indicators\n\n4. DECISION LOG\n- Phase 0c: Files/patterns/impact\n- Phase 1: Key files per sub-step\n- Phase 2: Clarification decisions\n- Phase 3: Spec influences\n\n5. CLARIFICATIONS AND DECISIONS\n- Q&A, resolved ambiguities, scope, technical approach\n\n6. SPECIFICATION SUMMARY\n- Objectives, constraints, design principles, integration\n\n7. WORKFLOW PROGRESS\n- trackProgress(0-3b, Phase 4)\n- ⏳ Remaining: 4-7\n- 📋 Context vars set\n\n8. RESUMPTION INSTRUCTIONS\n**How to Resume:**\n1. Call workflow_get with id: \"coding-task-workflow-with-loops\", mode: \"preview\"\n2. Call workflow_next with the JSON from addResumptionJson(phase-3b)\n3. Include function definitions from metaGuidance for reference\n\n9. HANDOFF INSTRUCTIONS\n- Files to attach: spec.md, CONTEXT.md\n- Key files from Decision Log\n- Critical decisions\n\ncreateFile(CONTEXT.md)",
-            "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": "Create architectural design from spec.md, analysis, and requirements.\n\n**Design Sections:**\n1. High-Level Approach (builds on patterns)\n2. Component Breakdown (new/modified)\n3. Data Models (schemas/structures)\n4. API Contracts (follow conventions)\n5. Key Interactions (components diagram)\n6. Integration Points\n7. Phase 2 Decisions Impact\n8. Complexity Factors\n9. Pattern Alignment (cite files)\n10. applyUserRules()\n\n**Actions:**\n- matchPatterns()\n- useTools()\n- createFile(design.md)\n- updateDecisionLog()",
-            "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-5-planning",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "title": "Phase 5: Create Detailed Implementation Plan",
-            "prompt": "Create detailed implementation_plan.md from spec.md, design.md, analysis.\n\n**Plan Sections:**\n1. Goal Clarification - understanding from spec/clarifications\n2. applyUserRules() - how plan follows user patterns\n3. Pattern Matching Strategy - existing code templates per step\n4. Impact Assessment - affected parts, deps, risks\n5. Implementation Strategy - discrete steps with rationale/I/O\n6. Testing Strategy - follow existing patterns (cite files)\n7. Failure Handling - test fails, tool issues\n8. Final Review Checklist - completion criteria\n\n**Actions:**\n- matchPatterns() for each step\n- useTools() to find examples\n- createFile(implementation_plan.md)\n- updateDecisionLog()",
-            "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 initial `implementation_plan.md` from Phase 5 and Devil's Advocate critique from Phase 5b. Create final, consolidated plan incorporating valid feedback.\n\n**Output:**\n- Final implementation_plan.md\n- List valuable but out-of-scope suggestions as future tickets\n\ncreateFile(implementation_plan.md) with final version.",
-            "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 CONTEXT.md with Phases 4-5 work. checkAutomation(summary): 500 words for High, else full.\n\n**Add/Update Sections:**\n\n4. DECISION LOG (EXPANDED)\n- Phase 4 Design: Files/patterns shaping architecture\n- Phase 5 Planning: Code examples for implementation\n- Pattern Matches: Template files\n\n5. ARCHITECTURAL DESIGN SUMMARY\n- Approach & rationale\n- Components added/modified\n- Integration points\n- Design decisions\n- Pattern alignment\n\n6. IMPLEMENTATION PLAN OVERVIEW\n- Goals & success criteria\n- Strategy overview\n- Risks & mitigation\n- Testing approach\n- Failure handling\n\n7. DEVILS ADVOCATE INSIGHTS\n- Concerns addressed\n- Plan improvements\n- Confidence score\n- Out-of-scope items\n\n8. WORKFLOW PROGRESS\n- trackProgress(0-5e, Implementation)\n- ⏳ Remaining: 6, 7\n- 📁 Files: spec/design/plan/CONTEXT.md\n\n9. RESUMPTION INSTRUCTIONS\n**How to Resume:**\n1. Call workflow_get with id: \"coding-task-workflow-with-loops\", mode: \"preview\"\n2. Call workflow_next with the JSON from addResumptionJson(phase-5e)\n3. Include function definitions from metaGuidance for reference\n\n10. IMPLEMENTATION READINESS\n- Sanity check results\n- Verified files/deps\n- Key files to re-read\n\ncreateFile(CONTEXT.md) with bullets for scannability.",
-            "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-count-steps",
-            "title": "Phase 6 Preparation: Count Implementation Steps",
-            "prompt": "Before starting the implementation loop, count the discrete implementation steps in the approved `implementation_plan.md`.\n\n**Your task:**\n1. Read the implementation_plan.md\n2. Count each discrete, actionable step from the Implementation Strategy section\n3. Set `totalImplementationSteps` to the count (e.g., 8)\n\n**What counts as a step:**\n- Each bullet point or numbered item that represents a concrete implementation task\n- Each item that would result in a code change or file creation\n- Each item that could be a logical git commit\n\n**Example:**\nIf the plan has:\n- Create user model\n- Add authentication service\n- Implement validation\n- Write tests\n\nThen set `totalImplementationSteps` = 4\n\n**IMPORTANT:** Only count, don't extract or store the steps. You'll read them directly from the plan during implementation.",
-            "agentRole": "You are preparing the implementation phase by counting the steps to enable progress tracking.",
-            "guidance": [
-                "Count only actionable implementation steps",
-                "Don't include meta-tasks like 'review' or 'document'",
-                "This enables progress tracking without bloating context"
-            ],
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "requireConfirmation": false
-        },
-        {
-            "id": "phase-6-iterative-implementation",
-            "type": "loop",
-            "title": "Phase 6: Iterative Implementation Loop (PREP -> IMPLEMENT -> VERIFY)",
-            "runCondition": {"var": "taskComplexity", "not_equals": "Small"},
-            "loop": {
-                "type": "for",
-                "count": "totalImplementationSteps",
-                "indexVar": "currentStepNumber",
-                "maxIterations": 25
-            },
-            "body": [
-                {
-                    "id": "phase-6-prep",
-                    "title": "PREP: Prepare for Step {{currentStepNumber + 1}}",
-                    "prompt": "**PREPARATION PHASE for Step {{currentStepNumber + 1}}/{{totalImplementationSteps}}**\n\nBefore implementing this step, you must first PREPARE:\n\n1. **Read implementation_plan.md** and locate step #{{currentStepNumber + 1}}\n2. **Extract step details**: Note the title, description, and expected outputs\n3. **Confirm prerequisites**: Verify the previous step (if any) was completed correctly\n4. **Validate current state**: Ensure the plan for this step is still valid in the current codebase\n5. **List requirements**: Identify all required inputs, files, or dependencies\n\n**BRANCH SETUP (first iteration only):** If this is the first implementation step ({{currentStepNumber}} === 0):\n- Check git availability with 'git status'\n- If available, create feature branch: 'git checkout -b wip-[unique-task-id]'\n- Track the featureBranch variable for later use\n- If git unavailable: Skip branching, log in CONTEXT.md\n\n**Do not proceed if anything is unclear or missing.**",
-                    "agentRole": "You are preparing to implement a specific step from the plan. Be meticulous in verifying all prerequisites are met before proceeding.",
-                    "guidance": [
-                        "This is step {{currentStepNumber + 1}} of {{totalImplementationSteps}} total implementation steps",
-                        "Read the step directly from implementation_plan.md",
-                        "Focus only on preparation - implementation comes next",
-                        "If this is the first step, handle git branch setup"
-                    ],
-                    "requireConfirmation": false
-                },
-                {
-                    "id": "phase-6-implement",
-                    "title": "IMPLEMENT: Execute Step {{currentStepNumber + 1}}",
-                    "prompt": "**IMPLEMENTATION PHASE for Step {{currentStepNumber + 1}}/{{totalImplementationSteps}}**\n\nNow implement the step you just prepared for:\n\n**Instructions:**\n1. Re-read step #{{currentStepNumber + 1}} from implementation_plan.md\n2. Focus only on this single step\n3. useTools() to make code changes\n4. Follow quality standards\n5. Adapt to unexpected discoveries\n6. createFile() for ALL code changes\n\n**Remember:** applyUserRules() and matchPatterns() throughout.\n\n**Progress Tracking:**\n- This is step {{currentStepNumber + 1}} of {{totalImplementationSteps}}\n- If we've done > 20 steps total, pause for user intervention\n\n**CONTEXT UPDATES:** If this is every 3rd step ({{currentStepNumber + 1}} % 3 === 0):\n- Update CONTEXT.md\n- addResumptionJson(phase-6-implement)\n- updateDecisionLog()\n- List files modified with line ranges\n\n",
-                    "agentRole": "You are implementing a specific step from the approved plan. Focus on precise execution while maintaining code quality.",
-                    "guidance": [
-                        "Implement only what this step requires",
-                        "Track progress for potential intervention",
-                        "Update context documentation every 3 steps"
-                    ],
-                    "requireConfirmation": false
-                },
-                {
-                    "id": "phase-6-verify",
-                    "title": "VERIFY: Validate Step {{currentStepNumber + 1}}",
-                    "prompt": "**VERIFICATION PHASE for Step {{currentStepNumber + 1}}/{{totalImplementationSteps}}**\n\nVerify the implementation is complete and correct:\n\n**Required:** verifyImplementation()\n\n**COMMIT Decision (if all passes):**\n- checkAutomation(commit)\n- gitCommit(type, scope: description)\n- If git unavailable: Log in CONTEXT.md\n\n**FAILURE PROTOCOL:** If verification fails after 2 attempts:\n1. Do not try a third time\n2. Fall back to alternative tools\n3. updateDecisionLog() with failure details\n4. Present summary and recommendations\n5. Set 'verificationFailed' context variable to true\n\n",
-                    "agentRole": "You are verifying the implementation meets all quality standards. Be thorough but respect failure bounds.",
-                    "guidance": [
-                        "All three verification steps must pass",
-                        "Track failure attempts (max 2)",
-                        "Commit only after successful verification",
-                        "Update context on failures"
-                    ],
-                    "runCondition": { "var": "verificationFailed", "not_equals": true },
-                    "requireConfirmation": false
-                }
-            ],
-            "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": "Perform final review against **'Final Review Checklist'** from `implementation_plan.md`.\n\n**Validate:** applyUserRules() compliance throughout. For each checklist item, provide confirmation and evidence.\n\n**Additional validation:**\n- User rules/preferences compliance\n- Architectural patterns match specs\n- Naming conventions and code style\n- Library/framework usage\n- matchPatterns() verification\n\n**Final commit:**\n- gitCommit(feat|fix|refactor, final implementation - summary)\n- Include metrics in body\n- checkAutomation(commit)\n\n**Branch cleanup (if git):**\n1. Merge: git checkout main && git merge --squash [featureBranch]\n2. Delete: git branch -d [featureBranch]\n3. checkAutomation(merge) with confidence >8\n4. Pause for conflicts\n5. Log in CONTEXT.md if no git\n\n**Update CONTEXT.md final sections:**\n\n## 9. COMPLETE DECISION LOG\nFull updateDecisionLog() with all files, patterns, user rules, design decisions\n\n## 10. FINAL STATUS\n- trackProgress(ALL, Complete)\n- ✅ Tests passing (metrics)\n- ✅ Checklist validated\n- ✅ applyUserRules() verified\n- 📁 Files modified (line ranges)\n- 📋 Known issues\n- 📜 Git history\n\n## 11. FINAL RESUMPTION\n**How to Resume (if needed for extensions):**\n1. Call workflow_get with id: \"coding-task-workflow-with-loops\", mode: \"preview\"\n2. Call workflow_next with the JSON from addResumptionJson(phase-7-final-review)\n**Note:** Task complete. This is for future extensions or follow-up work.\n\n## 12. HANDOFF\n- Accomplishments with file refs\n- Architecture decisions\n- Patterns established/followed\n- Follow-up recommendations\n\ncreateFile(CONTEXT.md) with final content.",
-            "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
-        }
-    ]
-}