@exaudeus/workrail 3.7.0 → 3.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -245,8 +245,12 @@ support [conditions, loops, validation criteria](docs/authoring.md), and more.
|
|
|
245
245
|
|
|
246
246
|
- [All Workflows](docs/workflows.md) – Full list with detailed descriptions
|
|
247
247
|
- [Writing Workflows](docs/authoring.md) – Custom workflow creation guide
|
|
248
|
+
- [Workflow Authoring Principles (v2)](docs/authoring-v2.md) – Cross-workflow design rules and authoring principles
|
|
248
249
|
- [Configuration](docs/configuration.md) – Git repos, environment variables, local paths
|
|
249
250
|
- [Advanced Features](docs/advanced.md) – Loops, conditionals, validation
|
|
251
|
+
- **Integrations**
|
|
252
|
+
- [Claude Code Setup](docs/integrations/claude-code.md) – Complete guide for Desktop & CLI
|
|
253
|
+
- [Firebender Setup](docs/integrations/firebender.md) – Firebender integration
|
|
250
254
|
|
|
251
255
|
---
|
|
252
256
|
|
package/package.json
CHANGED
|
@@ -7,10 +7,6 @@
|
|
|
7
7
|
"recommendedAutonomy": "guided",
|
|
8
8
|
"recommendedRiskPolicy": "conservative"
|
|
9
9
|
},
|
|
10
|
-
"features": [
|
|
11
|
-
"wr.features.subagent_guidance",
|
|
12
|
-
"wr.features.memory_context"
|
|
13
|
-
],
|
|
14
10
|
"preconditions": [
|
|
15
11
|
"User specifies source and target platforms.",
|
|
16
12
|
"Agent has read access to the source codebase.",
|
|
@@ -22,6 +18,13 @@
|
|
|
22
18
|
"SCOPE DISCIPLINE: convert only what the user scoped. Do not expand to adjacent features or modules unless explicitly asked.",
|
|
23
19
|
"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.",
|
|
24
20
|
"PLATFORM CONVENTIONS: follow the target platform's conventions for project structure, naming, error handling, concurrency, and testing.",
|
|
21
|
+
"SEMANTIC CONTRACTS: preserve caller-visible guarantees and lifecycle behavior, not just type names or structure. Map contract-to-contract, not construct-to-construct.",
|
|
22
|
+
"ANTI-ANCHORING: existing target-platform conventions are evidence, not proof. Follow them only when they preserve the source boundary's intent and guarantees.",
|
|
23
|
+
"UNCERTAINTY STOPS PROGRESSION: if a non-trivial boundary cannot be mapped confidently, mark it uncertain and escalate instead of guessing.",
|
|
24
|
+
"TARGET REPO FIT: migrate into the target repo's actual architectural seams, not just the target platform's generic idioms.",
|
|
25
|
+
"EVIDENCE OVER FAMILIARITY: choose reuse, adaptation, or new integration points based on concrete target-repo evidence, not on the first similar-looking abstraction.",
|
|
26
|
+
"ADAPTATION DEPTH: when source and target architectures differ materially, plan the adaptation explicitly before implementation. Do not treat redesign as translation.",
|
|
27
|
+
"SEPARATE SIZE FROM ADAPTATION: a small migration can still require deep architectural adaptation. Do not use file count as a proxy for design difficulty.",
|
|
25
28
|
"BUILD PROOF: code that does not build is not done. Run build or typecheck after every conversion batch.",
|
|
26
29
|
"PRESERVE INTENT: the goal is functional equivalence, not line-by-line correspondence. Restructure when the target platform has a better way.",
|
|
27
30
|
"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 @@
|
|
|
33
36
|
{
|
|
34
37
|
"id": "phase-0-scope",
|
|
35
38
|
"title": "Phase 0: Scope & Platform Analysis",
|
|
36
|
-
"
|
|
39
|
+
"promptBlocks": {
|
|
40
|
+
"goal": "Understand the migration scope, platforms, target repo location, and rough size before any implementation begins.",
|
|
41
|
+
"constraints": [
|
|
42
|
+
"If the user has not specified scope boundaries, ask. Do not guess at scope.",
|
|
43
|
+
"Find the target repo yourself before asking the user.",
|
|
44
|
+
"Check saved repo mappings in agent config or memory before falling back to broader discovery."
|
|
45
|
+
],
|
|
46
|
+
"procedure": [
|
|
47
|
+
"Determine what is being converted: single file, module, feature, full component, or entire app.",
|
|
48
|
+
"Identify the source platform and target platform.",
|
|
49
|
+
"Estimate conversion size using file count and rough LOC.",
|
|
50
|
+
"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."
|
|
51
|
+
],
|
|
52
|
+
"outputRequired": {
|
|
53
|
+
"sourcePlatform": "The source platform being migrated from.",
|
|
54
|
+
"targetPlatform": "The target platform being migrated to.",
|
|
55
|
+
"conversionScope": "The bounded scope of the migration.",
|
|
56
|
+
"targetRepoPath": "Where the converted code should land.",
|
|
57
|
+
"estimatedSize": "A rough estimate of migration size.",
|
|
58
|
+
"conversionComplexity": "Small, Medium, or Large."
|
|
59
|
+
},
|
|
60
|
+
"verify": [
|
|
61
|
+
"The migration scope is explicit and bounded.",
|
|
62
|
+
"The target repo location is identified or intentionally escalated.",
|
|
63
|
+
"The complexity classification matches the actual size and risk of the work."
|
|
64
|
+
]
|
|
65
|
+
},
|
|
37
66
|
"requireConfirmation": {
|
|
38
67
|
"var": "conversionComplexity",
|
|
39
68
|
"not_equals": "Small"
|
|
@@ -42,7 +71,7 @@
|
|
|
42
71
|
{
|
|
43
72
|
"id": "phase-1-understand-source",
|
|
44
73
|
"title": "Phase 1: Understand Source Code",
|
|
45
|
-
"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`",
|
|
74
|
+
"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`",
|
|
46
75
|
"promptFragments": [
|
|
47
76
|
{
|
|
48
77
|
"id": "phase-1-small-light",
|
|
@@ -50,41 +79,146 @@
|
|
|
50
79
|
"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."
|
|
51
80
|
}
|
|
52
81
|
],
|
|
53
|
-
"requireConfirmation":
|
|
82
|
+
"requireConfirmation": {
|
|
83
|
+
"var": "adaptationProfile",
|
|
84
|
+
"equals": "high"
|
|
85
|
+
}
|
|
54
86
|
},
|
|
55
87
|
{
|
|
56
88
|
"id": "phase-small-fast-path",
|
|
57
89
|
"title": "Small Conversion Fast Path",
|
|
58
90
|
"runCondition": {
|
|
59
|
-
"
|
|
60
|
-
|
|
91
|
+
"and": [
|
|
92
|
+
{ "var": "conversionComplexity", "equals": "Small" },
|
|
93
|
+
{ "var": "adaptationProfile", "equals": "low" }
|
|
94
|
+
]
|
|
61
95
|
},
|
|
62
|
-
"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`",
|
|
96
|
+
"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`",
|
|
63
97
|
"requireConfirmation": false
|
|
64
98
|
},
|
|
65
99
|
{
|
|
66
100
|
"id": "phase-2-triage",
|
|
67
101
|
"title": "Phase 2: Triage & Sort",
|
|
68
102
|
"runCondition": {
|
|
69
|
-
"
|
|
70
|
-
|
|
103
|
+
"or": [
|
|
104
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
105
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
106
|
+
]
|
|
71
107
|
},
|
|
72
|
-
"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`",
|
|
108
|
+
"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`",
|
|
73
109
|
"requireConfirmation": true
|
|
74
110
|
},
|
|
75
111
|
{
|
|
76
|
-
"id": "phase-
|
|
77
|
-
"title": "Phase
|
|
112
|
+
"id": "phase-3a-semantic-contracts",
|
|
113
|
+
"title": "Phase 3a: Semantic Contract Inventory",
|
|
78
114
|
"runCondition": {
|
|
79
|
-
"
|
|
80
|
-
|
|
115
|
+
"or": [
|
|
116
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
117
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
118
|
+
]
|
|
119
|
+
},
|
|
120
|
+
"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`",
|
|
121
|
+
"promptFragments": [
|
|
122
|
+
{
|
|
123
|
+
"id": "phase-3a-medium-focused",
|
|
124
|
+
"when": { "var": "conversionComplexity", "equals": "Medium" },
|
|
125
|
+
"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."
|
|
126
|
+
},
|
|
127
|
+
{
|
|
128
|
+
"id": "phase-3a-high-adaptation",
|
|
129
|
+
"when": { "var": "adaptationProfile", "equals": "high" },
|
|
130
|
+
"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."
|
|
131
|
+
}
|
|
132
|
+
],
|
|
133
|
+
"requireConfirmation": {
|
|
134
|
+
"or": [
|
|
135
|
+
{ "var": "hasUncertainBoundaries", "equals": true },
|
|
136
|
+
{ "var": "hasIntentionalBoundaryChanges", "equals": true }
|
|
137
|
+
]
|
|
138
|
+
}
|
|
139
|
+
},
|
|
140
|
+
{
|
|
141
|
+
"id": "phase-3b-target-integration",
|
|
142
|
+
"title": "Phase 3b: Target Integration Analysis",
|
|
143
|
+
"runCondition": {
|
|
144
|
+
"or": [
|
|
145
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
146
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
147
|
+
]
|
|
148
|
+
},
|
|
149
|
+
"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`",
|
|
150
|
+
"promptFragments": [
|
|
151
|
+
{
|
|
152
|
+
"id": "phase-3b-medium-focused",
|
|
153
|
+
"when": { "var": "conversionComplexity", "equals": "Medium" },
|
|
154
|
+
"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."
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
"id": "phase-3b-high-adaptation",
|
|
158
|
+
"when": { "var": "adaptationProfile", "equals": "high" },
|
|
159
|
+
"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."
|
|
160
|
+
}
|
|
161
|
+
],
|
|
162
|
+
"requireConfirmation": {
|
|
163
|
+
"var": "hasUncertainIntegrationPoints",
|
|
164
|
+
"equals": true
|
|
165
|
+
}
|
|
166
|
+
},
|
|
167
|
+
{
|
|
168
|
+
"id": "phase-3c-design-brief",
|
|
169
|
+
"title": "Phase 3c: Prepare High-Adaptation Design Brief",
|
|
170
|
+
"runCondition": {
|
|
171
|
+
"var": "adaptationProfile",
|
|
172
|
+
"equals": "high"
|
|
173
|
+
},
|
|
174
|
+
"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`",
|
|
175
|
+
"requireConfirmation": false
|
|
176
|
+
},
|
|
177
|
+
{
|
|
178
|
+
"id": "phase-3d-design-generation",
|
|
179
|
+
"title": "Phase 3d: High-Adaptation Design Generation",
|
|
180
|
+
"runCondition": {
|
|
181
|
+
"var": "adaptationProfile",
|
|
182
|
+
"equals": "high"
|
|
81
183
|
},
|
|
82
|
-
"
|
|
184
|
+
"templateCall": {
|
|
185
|
+
"templateId": "wr.templates.routine.tension-driven-design",
|
|
186
|
+
"args": {
|
|
187
|
+
"deliverableName": "conversion-design-candidates.md"
|
|
188
|
+
}
|
|
189
|
+
},
|
|
190
|
+
"requireConfirmation": false
|
|
191
|
+
},
|
|
192
|
+
{
|
|
193
|
+
"id": "phase-3e-select-adaptation-approach",
|
|
194
|
+
"title": "Phase 3e: Select Adaptation Approach",
|
|
195
|
+
"runCondition": {
|
|
196
|
+
"var": "adaptationProfile",
|
|
197
|
+
"equals": "high"
|
|
198
|
+
},
|
|
199
|
+
"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`",
|
|
200
|
+
"requireConfirmation": true
|
|
201
|
+
},
|
|
202
|
+
{
|
|
203
|
+
"id": "phase-3f-plan-hard-items",
|
|
204
|
+
"title": "Phase 3f: Plan Platform-Specific Conversions",
|
|
205
|
+
"runCondition": {
|
|
206
|
+
"or": [
|
|
207
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
208
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
209
|
+
]
|
|
210
|
+
},
|
|
211
|
+
"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`",
|
|
83
212
|
"promptFragments": [
|
|
84
213
|
{
|
|
85
|
-
"id": "phase-
|
|
214
|
+
"id": "phase-3f-medium-focused",
|
|
86
215
|
"when": { "var": "conversionComplexity", "equals": "Medium" },
|
|
87
216
|
"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."
|
|
217
|
+
},
|
|
218
|
+
{
|
|
219
|
+
"id": "phase-3f-high-adaptation",
|
|
220
|
+
"when": { "var": "adaptationProfile", "equals": "high" },
|
|
221
|
+
"text": "For high-adaptation migrations, state clearly what is translated directly, what is adapted through seams or adapters, and what is intentionally redesigned."
|
|
88
222
|
}
|
|
89
223
|
],
|
|
90
224
|
"requireConfirmation": true
|
|
@@ -94,11 +228,40 @@
|
|
|
94
228
|
"title": "Phase 4: Delegate Bucket A (Parallel Subagents)",
|
|
95
229
|
"runCondition": {
|
|
96
230
|
"and": [
|
|
97
|
-
{
|
|
231
|
+
{
|
|
232
|
+
"or": [
|
|
233
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
234
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
235
|
+
]
|
|
236
|
+
},
|
|
98
237
|
{ "var": "bucketACounts", "not_equals": 0 }
|
|
99
238
|
]
|
|
100
239
|
},
|
|
101
|
-
"
|
|
240
|
+
"promptBlocks": {
|
|
241
|
+
"goal": "Delegate only safe mechanical conversion work from Bucket A while keeping all real judgment and synthesis with the main agent.",
|
|
242
|
+
"constraints": [
|
|
243
|
+
"Delegate only files that are not boundary-critical and do not require unresolved target integration analysis.",
|
|
244
|
+
"If `adaptationProfile` is `high`, delegate only clearly mechanical files with no boundary or integration ambiguity.",
|
|
245
|
+
"If a supposedly easy file affects a semantic boundary, a target-repo seam, or requires contract judgment, keep it with main-agent review."
|
|
246
|
+
],
|
|
247
|
+
"procedure": [
|
|
248
|
+
"If subagent delegation is not available in your environment, convert Bucket A files yourself sequentially instead.",
|
|
249
|
+
"For each batch in `bucketABatches`, delegate a bounded translation task using `sourcePlatform`, `targetPlatform`, `targetRepoPath`, and the specific files in that batch.",
|
|
250
|
+
"Instruct subagents to perform only platform-agnostic translation, follow target naming conventions, preserve the public API, and convert tests if they exist.",
|
|
251
|
+
"After all batches finish, spot-check the output, flag misclassified files, and move them back to the appropriate main-agent bucket.",
|
|
252
|
+
"Run build or typecheck on the Bucket A output before continuing."
|
|
253
|
+
],
|
|
254
|
+
"outputRequired": {
|
|
255
|
+
"bucketAComplete": "Whether Bucket A work is complete.",
|
|
256
|
+
"bucketABuildPassed": "Whether the delegated Bucket A output builds or typechecks cleanly.",
|
|
257
|
+
"reclassifiedFiles": "Any files that were delegated but need to return to main-agent handling."
|
|
258
|
+
},
|
|
259
|
+
"verify": [
|
|
260
|
+
"No ambiguous or boundary-critical files were delegated as mechanical work.",
|
|
261
|
+
"Delegated output was reviewed by the main agent before proceeding.",
|
|
262
|
+
"Misclassified files were re-routed instead of being silently accepted."
|
|
263
|
+
]
|
|
264
|
+
},
|
|
102
265
|
"requireConfirmation": false
|
|
103
266
|
},
|
|
104
267
|
{
|
|
@@ -106,8 +269,10 @@
|
|
|
106
269
|
"type": "loop",
|
|
107
270
|
"title": "Phase 5: Convert Bucket B & C (Main Agent)",
|
|
108
271
|
"runCondition": {
|
|
109
|
-
"
|
|
110
|
-
|
|
272
|
+
"or": [
|
|
273
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
274
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
275
|
+
]
|
|
111
276
|
},
|
|
112
277
|
"loop": {
|
|
113
278
|
"type": "forEach",
|
|
@@ -120,7 +285,45 @@
|
|
|
120
285
|
{
|
|
121
286
|
"id": "phase-5a-convert-batch",
|
|
122
287
|
"title": "Convert Current Batch",
|
|
123
|
-
"
|
|
288
|
+
"promptBlocks": {
|
|
289
|
+
"goal": "Convert the current Bucket B or C batch using the approved plan, contract inventory, and target-integration analysis.",
|
|
290
|
+
"constraints": [
|
|
291
|
+
"Follow target platform conventions.",
|
|
292
|
+
"Preserve public API contracts where possible.",
|
|
293
|
+
"Fit the target repo's actual architectural seams.",
|
|
294
|
+
"Add TODO comments for anything uncertain.",
|
|
295
|
+
"Convert tests alongside production code when source tests exist."
|
|
296
|
+
],
|
|
297
|
+
"procedure": [
|
|
298
|
+
"Convert `{{currentBatch.name}}` using the dependency mapping and idiom mapping from Phase 3f.",
|
|
299
|
+
"For any touched boundary, consult both `semanticContractInventory` and `targetIntegrationAnalysis`.",
|
|
300
|
+
"If `adaptationProfile` is `high`, also follow `architectureAdaptationPlan`.",
|
|
301
|
+
"If the chosen target construct, target seam, or reuse/adaptation decision changes, update the relevant artifact rows rather than letting implementation drift silently.",
|
|
302
|
+
"Also handle any `reclassifiedFiles` that returned from Bucket A delegation.",
|
|
303
|
+
"Run build or typecheck after this batch and fix failures before moving on."
|
|
304
|
+
],
|
|
305
|
+
"outputRequired": {
|
|
306
|
+
"batchFilesConverted": "The files converted in this batch.",
|
|
307
|
+
"batchBuildPassed": "Whether the batch builds or typechecks cleanly.",
|
|
308
|
+
"batchIssues": "Problems encountered while converting the batch.",
|
|
309
|
+
"bucketDriftDetected": "Whether the batch proved harder than its original bucket classification.",
|
|
310
|
+
"unexpectedDependency": "Whether the batch exposed a dependency missing from the prior plan.",
|
|
311
|
+
"buildBroke": "Whether build or typecheck failed after the batch.",
|
|
312
|
+
"contractDriftDetected": "Whether implementation forced a semantic-contract change.",
|
|
313
|
+
"contractRowsUpdated": "Whether semantic contract rows were revised.",
|
|
314
|
+
"contractUncertain": "Whether a touched boundary can no longer be mapped confidently.",
|
|
315
|
+
"integrationDriftDetected": "Whether implementation forced a change to target seam or reuse/adaptation choice.",
|
|
316
|
+
"integrationAnalysisUpdated": "Whether target integration rows were revised.",
|
|
317
|
+
"integrationUncertain": "Whether a touched boundary no longer has a confident target-repo fit.",
|
|
318
|
+
"architectureDriftDetected": "Whether high-adaptation implementation diverged from the architecture adaptation plan.",
|
|
319
|
+
"adaptationPlanUpdated": "Whether the architecture adaptation plan was revised for this batch."
|
|
320
|
+
},
|
|
321
|
+
"verify": [
|
|
322
|
+
"Any contract or integration drift is reflected explicitly in the tracked artifacts.",
|
|
323
|
+
"No touched boundary is left without a clear contract and target-fit status.",
|
|
324
|
+
"The batch is build-clean or the failure has been captured for immediate follow-up."
|
|
325
|
+
]
|
|
326
|
+
},
|
|
124
327
|
"requireConfirmation": false
|
|
125
328
|
},
|
|
126
329
|
{
|
|
@@ -130,13 +333,47 @@
|
|
|
130
333
|
"or": [
|
|
131
334
|
{ "var": "bucketDriftDetected", "equals": true },
|
|
132
335
|
{ "var": "unexpectedDependency", "equals": true },
|
|
133
|
-
{ "var": "buildBroke", "equals": true }
|
|
336
|
+
{ "var": "buildBroke", "equals": true },
|
|
337
|
+
{ "var": "contractDriftDetected", "equals": true },
|
|
338
|
+
{ "var": "contractUncertain", "equals": true },
|
|
339
|
+
{ "var": "integrationDriftDetected", "equals": true },
|
|
340
|
+
{ "var": "integrationUncertain", "equals": true },
|
|
341
|
+
{ "var": "architectureDriftDetected", "equals": true }
|
|
342
|
+
]
|
|
343
|
+
},
|
|
344
|
+
"promptBlocks": {
|
|
345
|
+
"goal": "Resolve unexpected batch drift before continuing so downstream work is not based on stale assumptions.",
|
|
346
|
+
"constraints": [
|
|
347
|
+
"Do not silently absorb drift.",
|
|
348
|
+
"If a boundary can no longer be mapped confidently, stop and surface it instead of guessing."
|
|
349
|
+
],
|
|
350
|
+
"procedure": [
|
|
351
|
+
"If `bucketDriftDetected`, update the idiom or dependency mapping from Phase 3f so later batches do not repeat the same surprise.",
|
|
352
|
+
"If `unexpectedDependency`, map it now and assess whether other batches also depend on it.",
|
|
353
|
+
"If `buildBroke`, determine whether the failure is local to this batch or cross-batch integration related, then fix it before continuing.",
|
|
354
|
+
"If `contractDriftDetected`, update `semanticContractInventory` to match the real implementation.",
|
|
355
|
+
"If `integrationDriftDetected`, update `targetIntegrationAnalysis` to match the actual target seam and reuse/adaptation choice.",
|
|
356
|
+
"If `architectureDriftDetected`, update `architectureAdaptationPlan` before continuing."
|
|
357
|
+
],
|
|
358
|
+
"outputRequired": {
|
|
359
|
+
"mappingUpdated": "Whether the implementation mapping was revised.",
|
|
360
|
+
"contractInventoryUpdated": "Whether the semantic contract inventory was revised.",
|
|
361
|
+
"targetIntegrationUpdated": "Whether the target integration analysis was revised.",
|
|
362
|
+
"adaptationPlanUpdated": "Whether the architecture adaptation plan was revised.",
|
|
363
|
+
"verificationPassed": "Whether the batch is safe to continue past."
|
|
364
|
+
},
|
|
365
|
+
"verify": [
|
|
366
|
+
"Any real drift is reflected in the planning artifacts.",
|
|
367
|
+
"Uncertainty is surfaced instead of hidden.",
|
|
368
|
+
"The next batch will not proceed from stale assumptions."
|
|
134
369
|
]
|
|
135
370
|
},
|
|
136
|
-
"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`",
|
|
137
371
|
"requireConfirmation": {
|
|
138
|
-
"
|
|
139
|
-
|
|
372
|
+
"or": [
|
|
373
|
+
{ "var": "contractUncertain", "equals": true },
|
|
374
|
+
{ "var": "integrationUncertain", "equals": true },
|
|
375
|
+
{ "var": "architectureDriftDetected", "equals": true }
|
|
376
|
+
]
|
|
140
377
|
}
|
|
141
378
|
}
|
|
142
379
|
]
|
|
@@ -146,8 +383,10 @@
|
|
|
146
383
|
"type": "loop",
|
|
147
384
|
"title": "Phase 6: Final Verification",
|
|
148
385
|
"runCondition": {
|
|
149
|
-
"
|
|
150
|
-
|
|
386
|
+
"or": [
|
|
387
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
388
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
389
|
+
]
|
|
151
390
|
},
|
|
152
391
|
"loop": {
|
|
153
392
|
"type": "while",
|
|
@@ -162,7 +401,7 @@
|
|
|
162
401
|
{
|
|
163
402
|
"id": "phase-6a-full-build",
|
|
164
403
|
"title": "Full Build and Integration Check",
|
|
165
|
-
"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`",
|
|
404
|
+
"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`",
|
|
166
405
|
"requireConfirmation": false
|
|
167
406
|
},
|
|
168
407
|
{
|
|
@@ -179,7 +418,7 @@
|
|
|
179
418
|
{
|
|
180
419
|
"id": "phase-7-handoff",
|
|
181
420
|
"title": "Phase 7: Handoff",
|
|
182
|
-
"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.",
|
|
421
|
+
"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.",
|
|
183
422
|
"promptFragments": [
|
|
184
423
|
{
|
|
185
424
|
"id": "phase-7-small-summary",
|
|
@@ -188,8 +427,13 @@
|
|
|
188
427
|
},
|
|
189
428
|
{
|
|
190
429
|
"id": "phase-7-full-summary",
|
|
191
|
-
"when": {
|
|
192
|
-
|
|
430
|
+
"when": {
|
|
431
|
+
"or": [
|
|
432
|
+
{ "var": "conversionComplexity", "not_equals": "Small" },
|
|
433
|
+
{ "var": "adaptationProfile", "not_equals": "low" }
|
|
434
|
+
]
|
|
435
|
+
},
|
|
436
|
+
"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."
|
|
193
437
|
}
|
|
194
438
|
],
|
|
195
439
|
"notesOptional": true,
|