@exaudeus/workrail 3.14.0 → 3.16.0

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

@@ -2,7 +2,14 @@
   "id": "cross-platform-code-conversion",
   "name": "Cross-Platform Code Conversion",
   "version": "0.1.0",
-  "description": "Guides an agent through converting code from one platform to another (e.g., Android to iOS, iOS to Web). Triages files by difficulty, delegates easy literal translations to parallel subagents, then the main agent tackles platform-specific code requiring design decisions.",
+  "description": "Use this to convert code from one platform to another (e.g. Android to iOS, iOS to Web). Triages files by difficulty, parallelizes easy translations, and handles platform-specific design decisions.",
+  "about": "## Cross-Platform Code Conversion Workflow\n\nThis workflow guides an AI agent through converting code from one platform to another - for example, Android (Kotlin) to iOS (Swift), iOS to Web (TypeScript/React), or any similar migration. It handles everything from scoping and analysis through idiomatic conversion, build verification, and final handoff.\n\n### What it does\n\nThe workflow starts by scoping the migration and classifying its complexity (Small, Medium, or Large) and adaptation depth (low, moderate, or high). It then analyzes the source architecture to understand patterns, dependencies, concurrency models, and semantic contracts. Files are triaged into three buckets: mechanical translations delegated to subagents in parallel (Bucket A), library substitutions (Bucket B), and platform-specific code needing design decisions (Bucket C). For high-adaptation migrations, the workflow runs a full design generation phase to choose an idiomatic target-platform architecture before any code is written. Implementation proceeds batch by batch, with drift detection after each batch to catch files that turn out harder than classified. A final build-and-integration loop verifies the full converted codebase before handoff.\n\n### When to use it\n\nUse this workflow when migrating a module, feature, or full component from one platform to another. It is especially valuable when:\n- The source and target platforms have meaningfully different idioms (e.g., Kotlin coroutines vs Swift async/await, Hilt vs Swinject)\n- You want parallel delegation of mechanical work while keeping design-sensitive boundaries with the main agent\n- Semantic contracts (lifecycle, threading, cancellation, error handling) must be preserved across the migration\n- The target repo has existing architectural patterns the migrated code must fit into\n\nFor very small, straightforward file-by-file translations, the workflow includes a fast path that skips planning and triage.\n\n### What it produces\n\n- A triage matrix classifying every file into a conversion bucket\n- A semantic contract inventory for non-trivial migration boundaries\n- A target integration analysis mapping boundaries to their destination repo seams\n- Converted source files in the target platform's idioms\n- A passing build or typecheck on the full converted output\n- A handoff summary covering adaptation decisions, known gaps, and items needing manual review\n\n### How to get good results\n\n- Specify the exact scope of the migration - which files, modules, or features to convert\n- If the target repo is not in the same workspace, point the agent to it explicitly or configure the source-to-target path mapping\n- Review the triage and semantic contract inventory steps before conversion begins, especially for high-adaptation migrations\n- Flag any invariants that must survive the migration (API contracts, behavioral guarantees, threading assumptions)",
+  "examples": [
+    "Convert the Android messaging inbox feature from Kotlin/Coroutines to iOS Swift/Combine",
+    "Migrate the Android authentication module (Hilt + ViewModel) to a SwiftUI equivalent",
+    "Port the shared data models and repository layer from Android Kotlin to TypeScript for the web client",
+    "Convert the Android search feature UI layer from Jetpack Compose to SwiftUI"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
@@ -71,12 +78,15 @@
     {
       "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- 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`",
+      "prompt": "Read and analyze the source code through a conversion lens \u2014 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",
-          "when": { "var": "conversionComplexity", "equals": "Small" },
-          "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."
+          "when": {
+            "var": "conversionComplexity",
+            "equals": "Small"
+          },
+          "text": "For Small conversions, keep this lightweight. A quick read of the files in scope is enough \u2014 don't map the entire architecture. Focus on identifying any platform-specific code that would prevent a straight translation."
         }
       ],
       "requireConfirmation": {
@@ -89,11 +99,17 @@
       "title": "Small Conversion Fast Path",
       "runCondition": {
         "and": [
-          { "var": "conversionComplexity", "equals": "Small" },
-          { "var": "adaptationProfile", "equals": "low" }
+          {
+            "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, 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`",
+      "prompt": "For Small conversions, skip triage and planning \u2014 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
     },
     {
@@ -101,11 +117,17 @@
       "title": "Phase 2: Triage & Sort",
       "runCondition": {
         "or": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
-          { "var": "adaptationProfile", "not_equals": "low" }
+          {
+            "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- 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`",
+      "prompt": "Classify every file or module in scope into one of three buckets:\n\n**Bucket A \u2014 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 \u2014 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 \u2014 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
     },
     {
@@ -113,27 +135,45 @@
       "title": "Phase 3a: Semantic Contract Inventory",
       "runCondition": {
         "or": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
-          { "var": "adaptationProfile", "not_equals": "low" }
+          {
+            "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" },
+          "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" },
+          "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 }
+          {
+            "var": "hasUncertainBoundaries",
+            "equals": true
+          },
+          {
+            "var": "hasIntentionalBoundaryChanges",
+            "equals": true
+          }
         ]
       }
     },
@@ -142,20 +182,32 @@
       "title": "Phase 3b: Target Integration Analysis",
       "runCondition": {
         "or": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
-          { "var": "adaptationProfile", "not_equals": "low" }
+          {
+            "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" },
+          "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" },
+          "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."
         }
       ],
@@ -204,20 +256,32 @@
       "title": "Phase 3f: Plan Platform-Specific Conversions",
       "runCondition": {
         "or": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
-          { "var": "adaptationProfile", "not_equals": "low" }
+          {
+            "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-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."
+          "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 \u2014 only the ones relevant to the files in scope."
         },
         {
           "id": "phase-3f-high-adaptation",
-          "when": { "var": "adaptationProfile", "equals": "high" },
+          "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."
         }
       ],
@@ -230,11 +294,20 @@
         "and": [
           {
             "or": [
-              { "var": "conversionComplexity", "not_equals": "Small" },
-              { "var": "adaptationProfile", "not_equals": "low" }
+              {
+                "var": "conversionComplexity",
+                "not_equals": "Small"
+              },
+              {
+                "var": "adaptationProfile",
+                "not_equals": "low"
+              }
             ]
           },
-          { "var": "bucketACounts", "not_equals": 0 }
+          {
+            "var": "bucketACounts",
+            "not_equals": 0
+          }
         ]
       },
       "promptBlocks": {
@@ -270,8 +343,14 @@
       "title": "Phase 5: Convert Bucket B & C (Main Agent)",
       "runCondition": {
         "or": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
-          { "var": "adaptationProfile", "not_equals": "low" }
+          {
+            "var": "conversionComplexity",
+            "not_equals": "Small"
+          },
+          {
+            "var": "adaptationProfile",
+            "not_equals": "low"
+          }
         ]
       },
       "loop": {
@@ -331,14 +410,38 @@
           "title": "Verify Batch",
           "runCondition": {
             "or": [
-              { "var": "bucketDriftDetected", "equals": true },
-              { "var": "unexpectedDependency", "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 }
+              {
+                "var": "bucketDriftDetected",
+                "equals": true
+              },
+              {
+                "var": "unexpectedDependency",
+                "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": {
@@ -370,9 +473,18 @@
           },
           "requireConfirmation": {
             "or": [
-              { "var": "contractUncertain", "equals": true },
-              { "var": "integrationUncertain", "equals": true },
-              { "var": "architectureDriftDetected", "equals": true }
+              {
+                "var": "contractUncertain",
+                "equals": true
+              },
+              {
+                "var": "integrationUncertain",
+                "equals": true
+              },
+              {
+                "var": "architectureDriftDetected",
+                "equals": true
+              }
             ]
           }
         }
@@ -384,8 +496,14 @@
       "title": "Phase 6: Final Verification",
       "runCondition": {
         "or": [
-          { "var": "conversionComplexity", "not_equals": "Small" },
-          { "var": "adaptationProfile", "not_equals": "low" }
+          {
+            "var": "conversionComplexity",
+            "not_equals": "Small"
+          },
+          {
+            "var": "adaptationProfile",
+            "not_equals": "low"
+          }
         ]
       },
       "loop": {
@@ -401,7 +519,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- 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`",
+          "prompt": "Run a full build or typecheck on the entire converted codebase \u2014 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
         },
         {
@@ -422,15 +540,24 @@
       "promptFragments": [
         {
           "id": "phase-7-small-summary",
-          "when": { "var": "conversionComplexity", "equals": "Small" },
-          "text": "For Small conversions, keep the summary brief — just list what was converted, build status, and any issues."
+          "when": {
+            "var": "conversionComplexity",
+            "equals": "Small"
+          },
+          "text": "For Small conversions, keep the summary brief \u2014 just list what was converted, build status, and any issues."
         },
         {
           "id": "phase-7-full-summary",
           "when": {
             "or": [
-              { "var": "conversionComplexity", "not_equals": "Small" },
-              { "var": "adaptationProfile", "not_equals": "low" }
+              {
+                "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."

package/workflows/document-creation-workflow.json

@@ -2,7 +2,14 @@
   "id": "document-creation-workflow",
   "name": "Document Creation Workflow",
   "version": "1.0.0",
-  "description": "Create broad or comprehensive documentation spanning multiple components or systems. Suited for project READMEs, complete API documentation, user guides covering multiple features, and technical specifications. Uses complexity triage (Simple/Standard/Complex) to adapt rigor. For single, bounded subjects (one class, one integration), use scoped-documentation-workflow instead.",
+  "description": "Use this to create broad or comprehensive documentation spanning multiple components or systems — project READMEs, complete API docs, user guides, or technical specifications.",
+  "about": "## Document Creation Workflow\n\nThis workflow guides you through creating new documentation from scratch -- ranging from a simple project README to a full technical specification spanning multiple systems. It automatically calibrates depth to match the complexity of your request: simple tasks go straight to writing, while complex documentation gets a full analysis-and-planning phase first.\n\n### What it produces\n\nA complete, saved documentation file ready for use. Depending on complexity, it may also include a quality review pass covering accuracy, completeness, audience fit, usability, and style consistency.\n\n### When to use it\n\n- You need to create a **new** document (not update an existing one -- see the Documentation Update workflow for that).\n- The document spans one or more systems, components, or audiences.\n- Examples: project READMEs, API reference docs, user guides, onboarding docs, technical specifications, architecture overviews.\n\n### When NOT to use it\n\n- You want to update or refresh an existing doc -- use the Documentation Update workflow instead.\n- You need tight scope discipline for a single class or mechanism -- the Scoped Documentation workflow is better suited.\n\n### How to get good results\n\n- Be specific about the document type and intended audience upfront. The workflow probes for these, but the clearer your initial goal, the less back-and-forth.\n- If your project has existing documentation or style conventions, mention them -- the workflow will follow them.\n- For complex documentation, the workflow asks a small number of targeted questions it cannot answer from the codebase. Answer these concisely to keep momentum.",
+  "examples": [
+    "Create a README for the payments-service repo with setup, config, and deployment instructions",
+    "Write a full API reference for the new notifications SDK, including all endpoints and error codes",
+    "Create a user guide for the self-serve onboarding flow targeting non-technical customers",
+    "Write a technical specification for the proposed event-sourcing migration"
+  ],
   "preconditions": [
     "User has a clear idea of the document type and purpose.",
     "Relevant project files or information are available for reference.",
@@ -31,8 +38,14 @@
       "title": "Phase 1: Project Analysis",
       "runCondition": {
         "or": [
-          { "var": "docComplexity", "equals": "Standard" },
-          { "var": "docComplexity", "equals": "Complex" }
+          {
+            "var": "docComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "docComplexity",
+            "equals": "Complex"
+          }
         ]
       },
       "prompt": "Analyze the project to inform documentation strategy. Limit this analysis to 1500 words; prioritize documentation-relevant insights.\n\nCover:\n1. **Existing documentation landscape** — current docs, style patterns, gaps\n2. **Project architecture** — key components relevant to this document\n3. **User or developer workflows** — how documentation fits into user journeys\n4. **Technical constraints** — APIs, systems, integrations to document\n5. **Style conventions** — terminology, formatting, naming patterns to follow\n6. **Audience** — who will use this documentation and what they need to accomplish\n\nNote any complexity indicators that might warrant reclassifying `docComplexity` upward.",
@@ -43,8 +56,14 @@
       "title": "Phase 2: Targeted Requirements",
       "runCondition": {
         "or": [
-          { "var": "docComplexity", "equals": "Standard" },
-          { "var": "docComplexity", "equals": "Complex" }
+          {
+            "var": "docComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "docComplexity",
+            "equals": "Complex"
+          }
         ]
       },
       "prompt": "Based on your project analysis, ask 2 to 4 targeted questions that you genuinely cannot answer from the codebase or project files.\n\nFocus on clarifications that materially affect content or structure:\n- Specific scope boundaries (what to include or exclude)\n- Audience-specific requirements not evident from the code\n- Constraints, templates, or organizational standards to follow\n- Integration requirements with existing documentation systems\n\nDo not ask questions the analysis already answered.",
@@ -55,15 +74,24 @@
       "title": "Phase 3: Content Plan",
       "runCondition": {
         "or": [
-          { "var": "docComplexity", "equals": "Standard" },
-          { "var": "docComplexity", "equals": "Complex" }
+          {
+            "var": "docComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "docComplexity",
+            "equals": "Complex"
+          }
         ]
       },
       "prompt": "Create a content plan for this documentation in your notes.\n\nThe plan should cover:\n1. Document purpose and success criteria\n2. Target audience and their primary goals\n3. Section outline with one-line descriptions\n4. Writing strategy — tone, technical depth, key terminology\n5. Visual elements or code examples needed\n\nKeep the plan proportional to scope. The goal is a clear outline to execute against, not a heavyweight specification.",
       "promptFragments": [
         {
           "id": "phase-3-plan-complex",
-          "when": { "var": "docComplexity", "equals": "Complex" },
+          "when": {
+            "var": "docComplexity",
+            "equals": "Complex"
+          },
           "text": "For Complex documentation, also include: integration strategy (how this doc connects to the existing documentation ecosystem), maintenance ownership, and any stakeholder review requirements."
         }
       ],
@@ -80,15 +108,24 @@
       "title": "Phase 5: Quality Review",
       "runCondition": {
         "or": [
-          { "var": "docComplexity", "equals": "Standard" },
-          { "var": "docComplexity", "equals": "Complex" }
+          {
+            "var": "docComplexity",
+            "equals": "Standard"
+          },
+          {
+            "var": "docComplexity",
+            "equals": "Complex"
+          }
         ]
       },
       "prompt": "Review the documentation you just wrote using this rubric. For each dimension, provide a one-sentence evidence statement and a verdict of `pass` or `needs-work`.\n\n1. **Accuracy** — Does the content correctly describe the actual project or system? *(Evidence: cite one verified fact.)*\n2. **Completeness** — Does it cover all planned sections? *(Evidence: list planned vs completed sections.)*\n3. **Audience fit** — Is the technical depth right for the target reader? *(Evidence: identify one audience-appropriate choice made.)*\n4. **Usability** — Could a reader actually accomplish their goal using this doc? *(Evidence: trace one user journey through the doc.)*\n5. **Consistency** — Does it match project conventions for style, terminology, and format? *(Evidence: cite one convention followed.)*\n\nIf any dimension is `needs-work`, fix the issue immediately and re-assert the dimension as `pass` in your notes before continuing.",
       "promptFragments": [
         {
           "id": "phase-5-quality-review-complex",
-          "when": { "var": "docComplexity", "equals": "Complex" },
+          "when": {
+            "var": "docComplexity",
+            "equals": "Complex"
+          },
           "text": "Also review a sixth dimension:\n6. **Integration coherence** — Does the doc integrate correctly with the existing documentation ecosystem? *(Evidence: describe how it cross-links or relates to existing docs.)*"
         }
       ],
@@ -111,4 +148,4 @@
       "requireConfirmation": false
     }
   ]
-}
+}

package/workflows/documentation-update-workflow.json

@@ -2,7 +2,14 @@
   "id": "documentation-update-workflow",
   "name": "Documentation Update & Maintenance Workflow",
   "version": "2.0.0",
-  "description": "Update and maintain existing documentation. Uses git history to detect staleness, maps sections to current code, and systematically refreshes outdated content while preserving valuable accurate sections. For updating existing docs — not for creating new documentation.",
+  "description": "Use this to update and maintain existing documentation. Uses git history to detect staleness, maps sections to current code, and refreshes outdated content while preserving what's still accurate.",
+  "about": "## Documentation Update & Maintenance Workflow\n\nUse this when you have **existing** documentation that may be out of date and needs to be refreshed to match the current state of the codebase. The workflow uses git history as its primary evidence source: it checks when the docs were last committed, what changed in the relevant code since then, and classifies staleness before touching anything.\n\n### What it produces\n\nUpdated documentation files with stale or inaccurate sections corrected, missing coverage added, and removed content pruned. A completion summary is written to notes for future maintainers, including maintenance recommendations and sections at risk of going stale again quickly.\n\n### When to use it\n\n- A feature shipped and the docs were never updated.\n- You suspect a doc is outdated but aren't sure which parts.\n- You want a systematic, section-by-section audit rather than a quick edit.\n- The repo has git history covering both code and docs (the workflow degrades gracefully without git, but git history is the primary evidence source).\n\n### When NOT to use it\n\n- You are writing a doc from scratch -- use the Document Creation workflow instead.\n- You only need to fix a single known typo or sentence -- just edit the file directly.\n\n### How to get good results\n\n- Point the workflow at the specific documentation files and the code directories they describe.\n- The workflow will ask you to approve an update plan before making any edits -- review it carefully. This is the main checkpoint where you control scope.\n- If you want to defer lower-priority improvements, say so during plan review.",
+  "examples": [
+    "Update the API docs for the search service after last month's v3 endpoint changes",
+    "Refresh the developer onboarding guide -- it hasn't been updated since we migrated to Gradle 8",
+    "Audit the architecture decision records in docs/adr/ for accuracy against the current codebase",
+    "Update the GraphQL schema documentation to reflect recent breaking changes"
+  ],
   "preconditions": [
     "Target documentation files are accessible",
     "Agent has git access to the repository containing both docs and code",
@@ -97,4 +104,4 @@
       "requireConfirmation": false
     }
   ]
-}
+}

package/workflows/intelligent-test-case-generation.json

@@ -2,7 +2,14 @@
   "id": "intelligent-test-case-generation",
   "name": "Test Case Generation from Tickets",
   "version": "1.0.0",
-  "description": "Systematically extracts integration and end-to-end test cases from ticket requirements. Reads the ticket carefully, identifies boundary conditions and edge cases, traces affected code paths, and produces developer-readable test case descriptions ready for implementation.",
+  "description": "Use this to generate integration and end-to-end test cases from ticket requirements. Reads the ticket, traces affected code paths, identifies boundary conditions, and produces developer-readable test case descriptions.",
+  "about": "## Intelligent Test Case Generation\n\nThis workflow generates structured integration and end-to-end test cases directly from a ticket. It reads the ticket requirements, traces the affected code paths in the codebase, identifies boundary conditions and failure scenarios, and produces developer-readable test case descriptions that a developer can implement without guessing.\n\n**What it does:**\nThe workflow extracts every acceptance criterion from the ticket, traces which modules, endpoints, and integration boundaries are involved, identifies the existing test patterns in the repo (so generated cases match the team's style), then systematically generates happy path, boundary, and failure scenarios for each criterion. It checks coverage before writing, resolves ambiguities with you before generating anything uncertain, and finishes with a full test case list plus a coverage summary.\n\n**When to use it:**\n- When a ticket has clear acceptance criteria and you want comprehensive test coverage without manually reasoning through every edge case\n- When onboarding to a feature area and wanting to understand the expected behavior through its test scenarios\n- When a ticket spans multiple services or integration points and you need coverage across all of them\n- When preparing for a QA handoff or code review where test coverage must be explicitly demonstrated\n\n**What it produces:**\nNumbered test cases (TC-1, TC-2, ...) each with a title, acceptance criterion mapping, test type (Integration or E2E), risk level, preconditions, numbered test steps, expected result, and implementation notes. Cases are grouped by acceptance criterion and followed by a summary table. Open ambiguities and coverage gaps are disclosed explicitly.\n\n**How to get good results:**\nProvide the ticket in any standard format -- title, description, and acceptance criteria are enough. The workflow will trace the codebase itself. If the ticket has linked specs, API docs, or architecture diagrams, mention them. The more complete the acceptance criteria, the fewer clarifying questions the workflow will need to ask.",
+  "examples": [
+    "Generate test cases for ACEI-1591: expire cached conversations after 24 hours of inactivity",
+    "Write integration test scenarios for the ticket adding multi-factor authentication to the login flow",
+    "Generate E2E test cases for the checkout redesign ticket covering all payment method variations",
+    "Create test cases for the ticket migrating user profile storage from Postgres to the new profile service"
+  ],
   "preconditions": [
     "User provides a ticket (title, description, acceptance criteria) in any standard format.",
     "Agent has read access to the codebase for tracing affected paths and finding existing test patterns.",
@@ -31,7 +38,7 @@
         "var": "ambiguities",
         "not_equals": []
       },
-      "prompt": "Before generating test scenarios, resolve the ambiguities you found.\n\nFor each ambiguity in `ambiguities`:\n1. State what is unclear and why it matters for test design\n2. Propose the most reasonable interpretation based on context\n3. Ask me to confirm, adjust, or provide the missing information\n\nKeep questions targeted. If the ticket, codebase, or docs can answer the question, answer it yourself first.\n\nIf the user's response significantly changes the scope or adds new acceptance criteria, revisit Phase 1 scenario identification before continuing — do not carry stale scenarios forward.\n\nCapture:\n- `resolvedAmbiguities` -- list of ambiguities with chosen interpretation\n- `openAmbiguities` -- ambiguities the user still needs to resolve (initialize as empty)",
+      "prompt": "Before generating test scenarios, resolve the ambiguities you found.\n\nFor each ambiguity in `ambiguities`:\n1. State what is unclear and why it matters for test design\n2. Propose the most reasonable interpretation based on context\n3. Ask me to confirm, adjust, or provide the missing information\n\nKeep questions targeted. If the ticket, codebase, or docs can answer the question, answer it yourself first.\n\nIf the user's response significantly changes the scope or adds new acceptance criteria, revisit Phase 1 scenario identification before continuing \u2014 do not carry stale scenarios forward.\n\nCapture:\n- `resolvedAmbiguities` -- list of ambiguities with chosen interpretation\n- `openAmbiguities` -- ambiguities the user still needs to resolve (initialize as empty)",
       "requireConfirmation": true
     },
     {