@exaudeus/workrail 3.4.0 → 3.5.0

package/spec/workflow.schema.json

@@ -67,7 +67,7 @@
     },
     "metaGuidance": {
       "type": "array",
-      "description": "Persistent best practices that apply throughout the workflow",
+      "description": "Persistent behavioral rules surfaced on start and resume. Not repeated on every step advance. For external document pointers, use 'references' instead.",
       "items": {
         "type": "string",
         "minLength": 1,
@@ -142,6 +142,14 @@
         "$ref": "#/$defs/extensionPoint"
       },
       "uniqueItems": true
+    },
+    "references": {
+      "type": "array",
+      "description": "Workflow-declared references to external documents. Each reference is a pointer — content is never inlined. Declarations participate in the workflow hash; referenced file content does not.",
+      "items": {
+        "$ref": "#/$defs/workflowReference"
+      },
+      "uniqueItems": true
     }
   },
   "required": [
@@ -189,6 +197,49 @@
       "required": ["slotId", "purpose", "default"],
       "additionalProperties": false
     },
+    "workflowReference": {
+      "type": "object",
+      "description": "A pointer to an external document relevant to the workflow. Content is never inlined — the agent reads the file itself if needed.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier within the workflow",
+          "pattern": "^[a-z][a-z0-9_-]*$",
+          "minLength": 2,
+          "maxLength": 64
+        },
+        "title": {
+          "type": "string",
+          "description": "Human-readable title for the reference",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "source": {
+          "type": "string",
+          "description": "File path relative to workspace root",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "purpose": {
+          "type": "string",
+          "description": "Why this reference matters to the workflow",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "authoritative": {
+          "type": "boolean",
+          "description": "Whether this document is authoritative (agent should follow it strictly)"
+        },
+        "resolveFrom": {
+          "type": "string",
+          "enum": ["workspace", "package"],
+          "description": "Resolution base for source path. 'workspace' (default) resolves against the user's project root. 'package' resolves against the workrail package root (for files shipped with the workflow).",
+          "default": "workspace"
+        }
+      },
+      "required": ["id", "title", "source", "purpose", "authoritative"],
+      "additionalProperties": false
+    },
     "stepId": {
       "type": "string",
       "pattern": "^[a-z0-9-]+$",
@@ -246,7 +297,13 @@
         "functionDefinitions": { "type": "array", "items": { "$ref": "#/$defs/functionDefinition" } },
         "functionCalls": { "type": "array", "items": { "$ref": "#/$defs/functionCall" } },
         "functionReferences": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*\\(\\)$" } },
-        "templateCall": { "$ref": "#/$defs/templateCall" }
+        "templateCall": { "$ref": "#/$defs/templateCall" },
+        "promptFragments": {
+          "type": "array",
+          "description": "Conditional prompt fragments appended to the step's base prompt at render time. Each fragment is appended in declaration order when its 'when' condition matches the session context.",
+          "items": { "$ref": "#/$defs/promptFragment" },
+          "minItems": 1
+        }
       },
       "required": ["id", "title"],
       "additionalProperties": false
@@ -471,8 +528,37 @@
         "not": {
           "$ref": "#/$defs/condition",
           "description": "Logical NOT of a condition"
+        },
+        "in": {
+          "type": "array",
+          "description": "Check if variable value is in this array of allowed values"
+        }
+      },
+      "additionalProperties": false
+    },
+    "promptFragment": {
+      "type": "object",
+      "description": "A conditional prompt fragment appended to a step's base prompt at render time when its condition matches the session context.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this fragment within the step",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[a-z][a-z0-9_-]*$"
+        },
+        "when": {
+          "$ref": "#/$defs/condition",
+          "description": "Condition evaluated against session context at render time. If absent, fragment is always appended."
+        },
+        "text": {
+          "type": "string",
+          "description": "Prompt text appended when the condition matches. Must not contain {{wr.*}} tokens.",
+          "minLength": 1,
+          "maxLength": 4096
         }
       },
+      "required": ["id", "text"],
       "additionalProperties": false
     },
     "confirmationRule": {

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

@@ -0,0 +1,199 @@
+{
+  "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.",
+  "recommendedPreferences": {
+    "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.",
+    "Agent has write access to create target-platform files.",
+    "Agent can run build or typecheck tools for the target platform."
+  ],
+  "metaGuidance": [
+    "IDIOMATIC CONVERSION: translate patterns and idioms, not syntax. A Kotlin sealed class becomes a Swift enum with associated values, not a class hierarchy workaround.",
+    "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.",
+    "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.",
+    "TARGET REPO DISCOVERY: find the target repo yourself before asking. Check workspace roots, sibling dirs, monorepo modules, and agent config files first.",
+    "PERSIST REPO MAPPINGS: once a target repo is confirmed, offer to save the source-to-target mapping in the source repo's agent config so future runs skip discovery.",
+    "DRIFT DETECTION: if a file turns out harder than its bucket classification during conversion, stop and reclassify it. Do not silently absorb complexity."
+  ],
+  "steps": [
+    {
+      "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`",
+      "requireConfirmation": {
+        "var": "conversionComplexity",
+        "not_equals": "Small"
+      }
+    },
+    {
+      "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`",
+      "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."
+        }
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-small-fast-path",
+      "title": "Small Conversion Fast Path",
+      "runCondition": {
+        "var": "conversionComplexity",
+        "equals": "Small"
+      },
+      "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`",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-2-triage",
+      "title": "Phase 2: Triage & Sort",
+      "runCondition": {
+        "var": "conversionComplexity",
+        "not_equals": "Small"
+      },
+      "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`",
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-3-plan-hard-items",
+      "title": "Phase 3: Plan Platform-Specific Conversions",
+      "runCondition": {
+        "var": "conversionComplexity",
+        "not_equals": "Small"
+      },
+      "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`",
+      "promptFragments": [
+        {
+          "id": "phase-3-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."
+        }
+      ],
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-4-delegate-bucket-a",
+      "title": "Phase 4: Delegate Bucket A (Parallel Subagents)",
+      "runCondition": {
+        "and": [
+          { "var": "conversionComplexity", "not_equals": "Small" },
+          { "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`",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-5-convert-hard",
+      "type": "loop",
+      "title": "Phase 5: Convert Bucket B & C (Main Agent)",
+      "runCondition": {
+        "var": "conversionComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "forEach",
+        "items": "bucketBCBatches",
+        "itemVar": "currentBatch",
+        "indexVar": "batchIndex",
+        "maxIterations": 30
+      },
+      "body": [
+        {
+          "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`",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-5b-verify-batch",
+          "title": "Verify Batch",
+          "runCondition": {
+            "or": [
+              { "var": "bucketDriftDetected", "equals": true },
+              { "var": "unexpectedDependency", "equals": true },
+              { "var": "buildBroke", "equals": true }
+            ]
+          },
+          "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
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-6-verify",
+      "type": "loop",
+      "title": "Phase 6: Final Verification",
+      "runCondition": {
+        "var": "conversionComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "while",
+        "conditionSource": {
+          "kind": "artifact_contract",
+          "contractRef": "wr.contracts.loop_control",
+          "loopId": "final_verification_loop"
+        },
+        "maxIterations": 3
+      },
+      "body": [
+        {
+          "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`",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-6b-loop-decision",
+          "title": "Verification Loop Decision",
+          "prompt": "Decide whether verification needs another pass.\n\n- If the build fails or critical integration issues remain: continue.\n- If the build passes and remaining issues are minor: stop.\n- If you've hit the iteration limit: stop and record what remains.\n\nEmit the loop-control artifact:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue or stop\"\n  }]\n}\n```",
+          "requireConfirmation": false,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    },
+    {
+      "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.",
+      "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."
+        },
+        {
+          "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."
+        }
+      ],
+      "notesOptional": true,
+      "requireConfirmation": false
+    }
+  ]
+}

package/workflows/routines/parallel-work-partitioning.json

@@ -0,0 +1,43 @@
+{
+  "id": "routine-parallel-work-partitioning",
+  "name": "Parallel Work Partitioning Routine",
+  "version": "0.1.0",
+  "description": "Analyzes a set of work items and their dependencies, partitions them into independent batches that can be safely parallelized across subagents, and produces a sorted execution plan. Flags items with cross-dependencies for sequential handling by the main agent.",
+  "metaGuidance": [
+    "INDEPENDENCE IS THE PRIORITY: a batch is only parallel-safe if no item in it depends on any other item in any concurrent batch.",
+    "CONSERVATIVE CLASSIFICATION: when dependency is unclear, classify as sequential. Wrong parallelization is worse than missed parallelization.",
+    "MAIN AGENT OWNS HARD WORK: items needing judgment, design decisions, or cross-cutting context belong to the main agent, not subagents."
+  ],
+  "steps": [
+    {
+      "id": "step-inventory",
+      "title": "Step 1: Inventory Work Items",
+      "prompt": "List every work item in scope.\n\nFor each item, capture:\n- Item identifier (file path, module name, test case, doc section, etc.)\n- One-line description of what needs to be done\n- Estimated complexity: trivial / moderate / complex\n- Whether it requires judgment or design decisions (yes/no)\n\nDon't classify or sort yet. Just get the full inventory.\n\nCapture:\n- `workItems` (the full list)\n- `totalCount`",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-dependency-map",
+      "title": "Step 2: Map Dependencies",
+      "prompt": "For each work item, identify its dependencies on other items in the inventory.\n\nA dependency exists when:\n- Item B imports, references, or extends something in Item A\n- Item B's output format or API is consumed by Item A\n- Item B cannot be correctly completed without Item A being done first\n- Item B shares mutable state, configuration, or resources with Item A\n\nA dependency does NOT exist just because:\n- Items are in the same module or directory\n- Items use the same library or framework\n- Items are conceptually related but structurally independent\n\nProduce a dependency map: for each item, list which other items it depends on (if any). Items with no dependencies on other in-scope items are roots.\n\nCapture:\n- `dependencyMap`\n- `rootItems` (items with no in-scope dependencies)\n- `crossCuttingItems` (items that many others depend on)",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-classify",
+      "title": "Step 3: Classify Parallel vs. Sequential",
+      "prompt": "Classify each work item into one of two tracks:\n\n**Parallel track** — can be delegated to a subagent. ALL of these must be true:\n- No unresolved dependencies on other in-scope items (or all dependencies are already completed/in an earlier batch)\n- Trivial or moderate complexity\n- Does NOT require judgment, design decisions, or cross-cutting context\n- Can be verified independently (build, test, or review in isolation)\n- Failure is cheap to fix (a bad result can be caught and redone)\n\n**Sequential track** — must be handled by the main agent. ANY of these makes it sequential:\n- Has dependencies on items that haven't been completed yet\n- Complex or requires design decisions\n- Touches cross-cutting concerns (shared state, configuration, APIs used by many items)\n- Needs context from other items to be done correctly\n- Failure is expensive (wrong output cascades to other items)\n\nWhen in doubt, classify as sequential.\n\nCapture:\n- `parallelItems`\n- `sequentialItems`\n- `classificationRationale` (one line per item explaining the decision)",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-batch",
+      "title": "Step 4: Form Parallel Batches",
+      "prompt": "Group parallel-track items into batches that can run concurrently.\n\nBatching rules:\n- No two items in the same batch should depend on each other\n- No two items in the same batch should write to the same file or resource\n- Keep batches between 3-5 items for manageable subagent scope\n- Items that share a common dependency should be in the same batch or in batches that run after that dependency is resolved\n- Prefer grouping items by similarity (same file type, same kind of work) so each subagent gets coherent instructions\n\nAlso sort sequential-track items by dependency order (dependencies first).\n\nCapture:\n- `parallelBatches` (array of batches, each with item list and subagent instructions summary)\n- `sequentialOrder` (sorted list of sequential items)\n- `executionPlan` (the full plan: which parallel batches run first, then which sequential items, noting any sync points)",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-plan-delivery",
+      "title": "Step 5: Produce Execution Plan",
+      "prompt": "Write the final execution plan as a structured artifact in {deliverableName}.\n\nStructure:\n\n```markdown\n# Parallel Work Partitioning Plan\n\n## Summary\n- Total items: [count]\n- Parallel track: [count] items in [N] batches\n- Sequential track: [count] items\n- Cross-cutting items: [list]\n\n## Execution Order\n\n### Wave 1: Parallel Batches (delegate to subagents)\n\n#### Batch 1: [theme/description]\n- [item]: [one-line task]\n- [item]: [one-line task]\n**Subagent instructions**: [what the subagent needs to know]\n\n#### Batch 2: ...\n\n### Wave 2: Sequential Items (main agent)\n1. [item]: [one-line task] — depends on: [items]\n2. [item]: [one-line task] — depends on: [items]\n\n## Dependency Graph\n[Compact representation of which items depend on which]\n\n## Risk Notes\n- [Any items where classification was uncertain]\n- [Any sync points where parallel work must complete before sequential work starts]\n```\n\nCapture:\n- `planDelivered`",
+      "requireConfirmation": false
+    }
+  ]
+}

package/workflows/workflow-for-workflows.v2.json

@@ -0,0 +1,186 @@
+{
+  "id": "workflow-for-workflows",
+  "name": "Workflow Authoring Workflow (Lean, References-First)",
+  "version": "2.0.0",
+  "description": "Guides an agent through creating a new WorkRail workflow: understand the task, choose the shape, draft the JSON, validate with real validators, review the method, and optionally refine.",
+  "recommendedPreferences": {
+    "recommendedAutonomy": "guided",
+    "recommendedRiskPolicy": "conservative"
+  },
+  "preconditions": [
+    "User has a recurring task or problem the new workflow should solve.",
+    "Agent has access to file creation, editing, and terminal tools.",
+    "Agent can run workflow validators (npm run validate:registry or equivalent)."
+  ],
+  "metaGuidance": [
+    "REFERENCE HIERARCHY: treat workflow-schema as legal truth for structure. Treat authoring-spec as canonical current guidance for what makes a workflow good. Treat authoring-provenance as optional maintainer context only.",
+    "META DISTINCTION: you are creating a workflow, not executing one. Keep the authored workflow's concerns separate from this meta-workflow's execution.",
+    "DEFAULT BEHAVIOR: self-execute with tools. Only ask the user for business decisions about the workflow being created, not things you can learn from the schema, authoring spec, or example workflows.",
+    "AUTHORED VOICE: prompts in the created workflow must be user-voiced. No middleware narration, no pseudo-DSL, no tutorial framing, no teaching-product language.",
+    "VOICE ADAPTATION: the lean coding workflow is one voice example, not the universal template. Adapt vocabulary and tone to the created workflow's domain.",
+    "VOICE EXAMPLES: Coding: 'Review the changes in this MR.' Ops: 'Check whether the pipeline is healthy.' Content: 'Read the draft and check the argument.' NOT: 'The system will now perform a comprehensive analysis of...'",
+    "VALIDATION GATE: validate with real validators, not regex approximations. When validator output and authoring assumptions conflict, runtime wins.",
+    "ARTIFACT STRATEGY: the workflow JSON file is the primary output. Intermediate notes go in output.notesMarkdown. Do not create extra planning artifacts unless the workflow is genuinely complex.",
+    "V2 DURABILITY: use output.notesMarkdown as the primary durable record. Do not mirror execution state into CONTEXT.md or markdown checkpoint files.",
+    "ANTI-PATTERNS TO AVOID IN CREATED WORKFLOWS: no pseudo-function metaGuidance, no learning-path branching, no satisfaction-score loops, no heavy clarification batteries, no regex-as-primary-validation, no celebration phases.",
+    "NEVER COMMIT MARKDOWN FILES UNLESS USER EXPLICITLY ASKS."
+  ],
+  "references": [
+    {
+      "id": "workflow-schema",
+      "title": "Workflow JSON Schema",
+      "source": "spec/workflow.schema.json",
+      "resolveFrom": "package",
+      "purpose": "Canonical schema for validating structure and field semantics while authoring workflows. This is legal truth.",
+      "authoritative": true
+    },
+    {
+      "id": "authoring-spec",
+      "title": "Workflow Authoring Specification",
+      "source": "spec/authoring-spec.json",
+      "resolveFrom": "package",
+      "purpose": "Canonical authoring guidance, rule levels, and examples for composing workflows correctly. This is current authoring truth.",
+      "authoritative": true
+    },
+    {
+      "id": "authoring-provenance",
+      "title": "Workflow Authoring Provenance",
+      "source": "spec/authoring-spec.provenance.json",
+      "resolveFrom": "package",
+      "purpose": "Source-of-truth map showing what is canonical, derived, and non-canonical in workflow authoring guidance. Optional maintainer context.",
+      "authoritative": false
+    },
+    {
+      "id": "lean-coding-workflow",
+      "title": "Lean Coding Workflow (Modern Example)",
+      "source": "workflows/coding-task-workflow-agentic.lean.v2.json",
+      "resolveFrom": "package",
+      "purpose": "Current modern example of a well-authored workflow. Inspect for patterns, voice, loop semantics, prompt fragments, and delegation policy.",
+      "authoritative": false
+    }
+  ],
+  "steps": [
+    {
+      "id": "phase-0-understand",
+      "title": "Phase 0: Understand the Workflow to Create",
+      "prompt": "Before you write anything, understand what you're building.\n\nStart by reading:\n- `workflow-schema` reference (legal structure)\n- `authoring-spec` reference (what makes a workflow good)\n- `lean-coding-workflow` reference (modern example to inspect)\n\nThen understand the task from the user:\n- What recurring task or problem does this workflow solve?\n- Who runs it and how often?\n- What does success look like?\n- What constraints exist (tools, permissions, domain rules)?\n\nExplore first. Use tools to understand the domain if it involves code or a repo. Ask the user only what you genuinely cannot figure out yourself.\n\nThen classify:\n- `workflowComplexity`: Simple (linear, few steps) / Medium (branches, loops, or moderate step count) / Complex (multiple loops, delegation, extension points, many steps)\n- `rigorMode`: QUICK (simple linear workflow, low risk) / STANDARD (moderate complexity or domain risk) / THOROUGH (complex architecture, high stakes, needs review loops)\n\nCapture:\n- `workflowComplexity`\n- `rigorMode`\n- `taskDescription`\n- `intendedAudience`\n- `successCriteria`\n- `domainConstraints`\n- `openQuestions` (only real questions that need user input)",
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-1-shape",
+      "title": "Phase 1: Choose the Workflow Shape",
+      "runCondition": {
+        "var": "workflowComplexity",
+        "not_equals": "Simple"
+      },
+      "prompt": "Decide the architecture before you write JSON.\n\nBased on what you learned in Phase 0, decide:\n\n1. **Step structure**: how many phases, what each one does, what order\n2. **Loops**: does any phase need iteration? If so, what are the exit rules and max iterations?\n\nLoop design heuristics:\n- Add a loop ONLY when: (a) a quality gate may fail on first pass (validation, review), (b) each pass adds measurable value (progressive refinement), or (c) external feedback requires re-execution.\n- Do NOT loop when: (a) the agent can get it right in one pass with sufficient context, or (b) the full workflow is cheap enough to re-run entirely.\n- Every loop needs: an explicit exit condition (not vibes), a bounded maxIterations, and a decision step with outputContract.\n- Sensible defaults: validation ≈ 2-3, review/refinement ≈ 2, user-feedback ≈ 2-3 with confirmation gate. Go higher only with explicit justification in your notes.\n3. **Confirmation gates**: where does the user genuinely need to approve before proceeding? Don't add confirmations as ceremony.\n4. **Delegation**: does any step benefit from subagent routines? If so, which ones and why? Keep delegation bounded.\n5. **Prompt composition**: will any steps need promptFragments for rigor-mode branching? Will any steps share enough structure to use templates?\n6. **Extension points**: are there customizable slots that projects might want to override (e.g., a verification routine, a review routine)?\n7. **References**: should the created workflow declare its own references to external docs?\n8. **Artifacts**: what does each step produce? Which artifact is canonical for which concern?\n9. **metaGuidance**: what persistent behavioral rules should the agent see on start and resume?\n\nWrite the shape as a structured outline in your notes. Include:\n- Phase list with titles and one-line goals\n- Which phases loop and why\n- Which phases have confirmation gates and why\n- Context variables that flow between phases\n- Artifact ownership (which artifact is canonical for what)\n\nDon't write JSON yet.\n\nCapture:\n- `workflowOutline`\n- `loopDesign`\n- `confirmationDesign`\n- `delegationDesign`\n- `artifactPlan`\n- `contextModel` (the context variables the workflow will use and where they're set)\n- `voiceStrategy` (domain vocabulary, authority posture: directive/collaborative/supervisory, density calibration)",
+      "requireConfirmation": {
+        "or": [
+          { "var": "workflowComplexity", "not_equals": "Simple" },
+          { "var": "rigorMode", "not_equals": "QUICK" }
+        ]
+      }
+    },
+    {
+      "id": "phase-2-draft",
+      "title": "Phase 2: Draft the Workflow",
+      "prompt": "Write the workflow JSON file.\n\nUse the outline from Phase 1 and write the best first draft you can. Phase 3 will catch structural issues, so focus on getting the shape and voice right. Follow these rules:\n\n1. The schema (`workflow-schema` reference) defines what is structurally legal. Do not invent fields.\n2. The authoring spec (`authoring-spec` reference) defines what is good. Follow its active rules.\n3. Write prompts in the user's voice. The opening sentence of each step should sound like a direct ask, not system narration.\n4. Calibrate prompt density to the step's needs. Not all steps need the same level of detail:\n   - Sparse (expert audience, clear task): direct ask + capture footer only.\n   - Focused (expert audience, ambiguous task): direct ask + key criteria or trade-offs + capture.\n   - Guided (broad audience, clear task): direct ask + enumerated sub-steps + capture.\n   - Scaffolded (broad audience, ambiguous task): direct ask + context frame + sub-steps + heuristic + capture.\n   Default to Focused if unsure. Vary density across steps -- uniform density is a smell.\n5. Keep protocol requirements explicit. If a step must emit a specific artifact or capture specific context, say that plainly.\n6. Use promptFragments for conditional rigor-mode branches instead of duplicating entire steps.\n7. Loop decision steps must use `outputContract` with `wr.contracts.loop_control` and allow both `continue` and `stop` in the output example.\n8. Loops must have explicit exit rules, bounded maxIterations, and a clear reason for another pass.\n9. Confirmation gates are for real human decisions, not routine ceremony.\n10. metaGuidance should be clean behavioral rules, not pseudo-functions or teaching prose.\n11. Do not use regex validationCriteria as the primary quality gate. Use real validators.\n\nAsk the user what filename to use if they haven't specified one.\n\nWrite the file. Do not explain the JSON back to the user field by field.\n\nCapture:\n- `workflowFilePath`\n- `draftComplete`",
+      "promptFragments": [
+        {
+          "id": "phase-2-simple-fast",
+          "when": { "var": "workflowComplexity", "equals": "Simple" },
+          "text": "No shape outline exists for Simple workflows -- Phase 1 was skipped. Decide the step list now and draft directly. Keep it linear, 3-5 steps, no loops unless the task genuinely needs iteration. metaGuidance is optional for Simple workflows."
+        }
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-3-validate",
+      "type": "loop",
+      "title": "Phase 3: Validate and Fix",
+      "loop": {
+        "type": "while",
+        "conditionSource": {
+          "kind": "artifact_contract",
+          "contractRef": "wr.contracts.loop_control",
+          "loopId": "validation_loop"
+        },
+        "maxIterations": 3
+      },
+      "body": [
+        {
+          "id": "phase-3a-run-validation",
+          "title": "Run Validation",
+          "prompt": "Run the real workflow validators against the drafted workflow.\n\nUse the available validation tools or commands (e.g., `npm run validate:registry`, schema validation, or the MCP validation surface). Do not rely on reading the JSON and eyeballing it.\n\nIf validation passes cleanly, say so and move to the loop decision.\n\nIf validation fails:\n1. List the actual errors.\n2. Fix each one in the workflow file.\n3. Re-run validation to confirm the fixes worked.\n\nIf the validator reports something that conflicts with your authoring assumptions, the validator (runtime) wins. Update your understanding.\n\nCapture:\n- `validationErrors`\n- `validationPassed`",
+          "promptFragments": [
+            {
+              "id": "phase-3a-thorough",
+              "when": { "var": "rigorMode", "equals": "THOROUGH" },
+              "text": "After fixing structural errors, also check the workflow against the authoring spec rules manually. Score each active required-level rule as pass/fail and fix any failures before moving on."
+            }
+          ],
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-3b-loop-decision",
+          "title": "Validation Loop Decision",
+          "prompt": "Decide whether validation needs another pass.\n\n- If all errors are fixed and validation passes: stop.\n- If you fixed errors but haven't re-validated yet: continue.\n- If you've hit the iteration limit: stop and record what remains.\n\nEmit the loop-control artifact in this shape (`decision` must be `continue` or `stop`):\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue or stop\"\n  }]\n}\n```",
+          "requireConfirmation": false,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-3-escalation",
+      "title": "Validation Escalation",
+      "runCondition": {
+        "var": "validationPassed",
+        "equals": false
+      },
+      "prompt": "Validation did not pass after the maximum number of attempts.\n\nCheck whether the last validation run actually passed. If `validationPassed` is false or if you're uncertain, list the remaining errors and your assessment of their severity.\n\nThen present the options:\n1. Proceed with known issues documented in handoff notes.\n2. Stop workflow creation here so the user can intervene manually.\n\nDo not silently continue with a broken workflow.",
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-4-review",
+      "title": "Phase 4: Method Review",
+      "prompt": "The workflow is valid. Now check whether it's actually good.\n\nScore each dimension 0-2 with one sentence of evidence:\n\n- `voiceClarity`: 0 = prompts are direct user-voiced asks in the workflow's domain vocabulary, 1 = mostly user-voiced but borrows vocabulary from other domains or has middleware narration, 2 = reads like system documentation or sounds like a different domain\n- `ceremonyLevel`: 0 = confirmations only at real decision points, 1 = one or two unnecessary gates, 2 = over-asks the user or adds routine ceremony\n- `loopSoundness`: 0 = loops have explicit exit rules, bounded iterations, and real decision steps, 1 = minor issues with exit clarity, 2 = vibes-only exit conditions or unbounded loops (score 0 if no loops)\n- `delegationBoundedness`: 0 = delegation is bounded and explicit or absent, 1 = one delegation could be tighter, 2 = open-ended or ownership-transferring delegation (score 0 if no delegation)\n- `legacyPatterns`: 0 = no legacy anti-patterns, 1 = minor legacy residue, 2 = pseudo-DSL, learning paths, satisfaction loops, or regex-as-gate present\n- `artifactClarity`: 0 = clear what each artifact is for and which is canonical, 1 = mostly clear, 2 = ambiguous artifact ownership\n\nIf the total score is 0-2: the workflow is ready.\nIf the total score is 3-5: fix the worst dimensions before proceeding.\nIf the total score is 6+: this needs significant rework. Fix the worst dimensions here, re-validate, and record what you would change if you could redraft from scratch.\n\nFix any issues directly in the workflow file. Re-run validation if you changed structure.\n\nCapture:\n- `reviewScores`\n- `reviewPassed`\n- `fixesApplied`",
+      "promptFragments": [
+        {
+          "id": "phase-4-quick-skip",
+          "when": { "var": "rigorMode", "equals": "QUICK" },
+          "text": "For QUICK rigor, do a fast pass on voiceClarity and legacyPatterns only. Skip the full rubric unless something looks off."
+        },
+        {
+          "id": "phase-4-thorough-extra",
+          "when": { "var": "rigorMode", "equals": "THOROUGH" },
+          "text": "Also review:\n- Are the context captures complete and correctly named?\n- Do runConditions and promptFragment conditions use the right variables?\n- Is the metaGuidance minimal and non-redundant?\n- Would this workflow make sense to an agent that has never seen it before?"
+        },
+        {
+          "id": "phase-4-trace-walkthrough",
+          "when": { "var": "rigorMode", "not_equals": "QUICK" },
+          "text": "After scoring the rubric, trace through the workflow with the user's original task as the test scenario. For each step:\n- What context variables does it need? Are they available from prior steps?\n- What would the agent actually do given only the prompt and references?\n- What does it produce? Does the next step have everything it needs?\n\nFlag any context flow gaps, naming mismatches, or steps where the agent wouldn't know what to do. Fix them in the workflow file."
+        }
+      ],
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-5-refine",
+      "title": "Phase 5: Refinement",
+      "runCondition": {
+        "var": "rigorMode",
+        "not_equals": "QUICK"
+      },
+      "prompt": "The workflow is valid and reviewed. Check whether any of these improvements are worth making:\n\n1. **Prompt fragments**: are there steps with near-identical prompts that differ only by rigor mode? Extract the differences into promptFragments.\n2. **Extension points**: are there slots that different teams or projects would want to customize? Declare them.\n3. **References**: should the workflow point at external documents the agent should be aware of during execution?\n4. **Deduplication**: is there repeated prose across steps that could be moved to metaGuidance or a shared pattern?\n5. **Context templates**: are there simple variable substitutions that would make prompts cleaner?\n\nOnly make changes that genuinely improve the workflow. Do not refine for the sake of refining.\n\nIf you change anything, re-run validation.\n\nCapture:\n- `refinementsApplied`\n- `finalValidationPassed`",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-6-handoff",
+      "title": "Phase 6: Handoff",
+      "prompt": "Summarize what was created.\n\nInclude:\n- workflow file path and name\n- what the workflow does (one sentence)\n- step count and structure overview\n- loops, confirmations, and delegation if any\n- validation status\n- any known limitations or future improvements\n- how to test it: where to place the file and how to run it\n\nKeep it concise. The workflow file is the deliverable, not the summary.",
+      "notesOptional": true,
+      "requireConfirmation": false
+    }
+  ]
+}