@exaudeus/workrail 3.74.3 → 3.76.0

package/workflows/routines/tension-driven-design.json

@@ -1,13 +1,13 @@
 {
   "id": "wr.routine-tension-driven-design",
   "name": "Tension-Driven Design Generation",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "metricsProfile": "none",
   "features": [
     "wr.features.capabilities",
     "wr.features.subagent_guidance"
   ],
-  "description": "Generates design candidates grounded in real tensions. Supports standalone and parallel-executor modes. In executor mode, anchors to an assigned focus angle from the goal string and ranks candidates without recommending a winner -- the calling agent owns synthesis and selection.",
+  "description": "Generates candidates grounded in real tensions for any problem domain. Supports standalone and parallel-executor modes. In executor mode, anchors to an assigned focus angle and ranks without recommending -- the calling agent owns synthesis and selection.",
   "clarificationPrompts": [
     "What problem should this design solve? (When spawned as an executor, the full fact packet and assigned focus angle should be in the goal string.)",
     "What acceptance criteria, invariants, and constraints must it respect?",
@@ -19,11 +19,11 @@
     "Agent has read access to the codebase"
   ],
   "metaGuidance": [
-    "PURPOSE: generate genuinely different design candidates grounded in real problem tensions, not abstract perspectives.",
-    "ROLE: you are a designer, not an auditor or implementer. Think deeply about the problem before proposing solutions.",
-    "PHILOSOPHY: the dev's coding philosophy is a design constraint, not an afterthought review lens. Discover it and use it.",
-    "SIMPLICITY BIAS: always consider whether the problem even needs an architectural solution. The simplest change that works is a valid candidate.",
-    "REPO PATTERNS: study how the codebase already solves similar problems. The best design often adapts an existing pattern.",
+    "PURPOSE: generate genuinely different candidates grounded in real tensions for any problem domain -- software, product, UX, personal, or general.",
+    "ROLE: you are a designer and strategic thinker, not an auditor or implementer. Think deeply about the problem before proposing solutions.",
+    "PRINCIPLES: the decision-maker's principles and constraints are a design constraint, not an afterthought. Discover them (step 1) and use them throughout.",
+    "SIMPLICITY BIAS: always consider whether the problem needs an ambitious solution at all. The simplest option that works is a valid candidate.",
+    "EXISTING PATTERNS: study how similar problems have been solved before in this context. The best solution often adapts an existing pattern rather than inventing from scratch.",
     "HONESTY: for each candidate, state what you gain, what you give up, and how it fails. Optimize for useful comparison, not persuasion.",
     "EXECUTOR MODE: if goal contains 'FOCUS ANGLE:', you are a parallel executor. Generate candidates anchored to that angle only. Step 4 ranks, does not recommend. Main agent owns synthesis and selection.",
     "OUTPUT FILE: use the filename from 'OUTPUT FILE:' in your goal string, defaulting to design-candidates.md."
@@ -38,22 +38,22 @@
     },
     {
       "id": "step-discover-philosophy",
-      "title": "Step 1: Discover the Dev's Philosophy",
-      "prompt": "Discover the dev's coding philosophy and preferences before designing anything.\n\nIf PHILOSOPHY SOURCES were provided in step 0, go read those sources directly (they are file paths or Memory entry names).\n\nIf no philosophy sources were provided, discover from scratch:\n1. Memory MCP (if available): call `mcp_memory_conventions`, `mcp_memory_prefer`, `mcp_memory_recall` to retrieve learned preferences\n2. Active session rules / CLAUDE.md / AGENTS.md: read any rules or philosophy documents in context\n3. Repo patterns: infer preferences from how the codebase works -- error handling, mutability, test style, architecture\n\nNote any philosophy conflicts (stated rules vs actual repo patterns).\n\nWorking notes:\n- Philosophy sources consulted\n- Key principles discovered\n- Conflicts between stated and practiced philosophy\n- Which principles are likely to constrain this design",
-      "agentRole": "You are discovering what the dev actually cares about before designing solutions.",
+      "title": "Step 1: Discover Principles and Constraints",
+      "prompt": "Discover the decision-maker's principles, preferences, and constraints before designing anything. The approach depends on the problem domain.\n\nIf PHILOSOPHY SOURCES were provided in step 0, go read those sources directly first.\n\nIf no philosophy sources were provided, discover based on domain:\n\n**For software / architecture problems:**\n1. Memory MCP (if available): call `mcp_memory_conventions`, `mcp_memory_prefer`, `mcp_memory_recall`\n2. Read CLAUDE.md, AGENTS.md, .cursor/rules/ or equivalent\n3. Infer from repo patterns: error handling, mutability, test style, type safety, architecture decisions\nNote conflicts between stated rules and actual repo patterns.\n\n**For product / strategy problems:**\n1. Look for product principles, north star metrics, company mission, OKRs\n2. Memory MCP for stated product values or past decisions\n3. Infer from existing product decisions: what tradeoffs were previously accepted?\n\n**For UX / design problems:**\n1. Look for design system docs, accessibility guidelines, brand principles\n2. Infer from existing UI decisions: what patterns are already established?\n\n**For personal / career problems:**\n1. Memory MCP for stated values, priorities, past decisions the user has shared\n2. Infer from what the user has said they care about most\n\n**For general problems:**\n1. Identify the decision-maker's stated priorities and constraints\n2. Note what tradeoffs they have accepted in the past\n\nWorking notes:\n- Sources consulted\n- Key principles discovered\n- Conflicts between stated principles and past behavior\n- Which principles are likely to constrain this design",
+      "agentRole": "You are discovering what the decision-maker actually cares about before designing solutions.",
       "requireConfirmation": false
     },
     {
       "id": "step-understand-deeply",
       "title": "Step 2: Understand the Problem Deeply",
-      "prompt": "Understand the problem before proposing anything.\n\nIf TENSIONS and a REFRAMED PROBLEM were extracted in step 0, use them as your starting point -- do not re-investigate what the main agent already resolved. Build on that foundation and add what the main agent may have missed from your assigned angle's perspective.\n\nReason through:\n- What are the core tensions in this problem?\n- How does the codebase already solve similar problems? Study the most relevant existing patterns -- analyze the architectural decisions and constraints they protect, not just list files.\n- Where does the problem most likely live? Is the requested location the real seam, or just where the symptom appears?\n- What nearby callers, consumers, sibling paths, or contracts must remain consistent if that boundary changes?\n- What is the simplest naive solution? Why is it insufficient? (If it IS sufficient, note that -- it may be the best candidate.)\n- What makes this problem hard? What would a junior developer miss?\n- Which of the dev's philosophy principles are under pressure from this problem's constraints?\n- If in executor mode: what does the problem look like specifically from your assigned angle? What tensions does your angle ask you to prioritize?\n\nWorking notes:\n- Core tensions (2-4 real tradeoffs, not generic labels)\n- Existing patterns analysis (decisions, invariants they protect)\n- Likely seam / plausible boundaries\n- Nearby impact surface that must stay consistent\n- Naive solution and why it's insufficient (or sufficient)\n- What makes this hard\n- Philosophy principles under pressure\n- How your assigned angle (if in executor mode) shapes your view of the problem",
+      "prompt": "Understand the problem before proposing anything.\n\nIf TENSIONS and a REFRAMED PROBLEM were extracted in step 0, use them as your starting point -- do not re-investigate what the main agent already resolved. Build on that foundation and add what the main agent may have missed from your assigned angle's perspective.\n\nReason through these universal questions first:\n- What are the core tensions in this problem? (e.g., speed vs quality, simplicity vs flexibility, short-term vs long-term)\n- What is the simplest naive solution? Why is it insufficient? (If it IS sufficient, note that -- it may be the best candidate.)\n- What makes this problem hard? What would someone without deep context miss?\n- Which principles discovered in step 1 are under pressure from this problem's constraints?\n- If in executor mode: what does the problem look like specifically from your assigned angle?\n\nThen reason through domain-specific questions:\n\n**For software / architecture problems:**\n- How does the codebase already solve similar problems? Study existing patterns -- the decisions they encode, the invariants they protect.\n- Where does the problem most likely live? Is the requested location the real seam?\n- What nearby callers, consumers, sibling paths, or contracts must remain consistent?\n\n**For product / strategy problems:**\n- What does the competitive and user landscape look like for this decision?\n- What decisions has the team made before that constrain or inform this one?\n- What signals (data, user research, market trends) are relevant?\n\n**For UX / design problems:**\n- What existing patterns in the design system constrain or inform this?\n- What are the user's mental models and where does the current design break them?\n- What edge cases and accessibility implications need to be considered?\n\n**For personal problems:**\n- What are the real stakes and who else is affected?\n- What is the decision-maker's actual track record with similar decisions?\n- What are they optimizing for, stated and unstated?\n\n**For general problems:**\n- Who are the stakeholders and what do they actually need?\n- What existing constraints or commitments narrow the solution space?\n\nWorking notes:\n- Core tensions (2-4 real tradeoffs, not generic labels)\n- Domain-specific context (patterns, landscape, constraints)\n- Naive solution and why it's insufficient (or sufficient)\n- What makes this hard\n- Principles under pressure\n- How your assigned angle (if in executor mode) shapes your view",
       "agentRole": "You are reasoning deeply about the problem space before generating any solutions.",
       "requireConfirmation": false
     },
     {
       "id": "step-generate-candidates",
       "title": "Step 3: Generate Candidates from Tensions",
-      "prompt": "Generate design candidates that resolve the identified tensions differently.\n\nIf in executor mode (FOCUS ANGLE was set in step 0):\n- All candidates must be anchored to your assigned angle. Do not generate generic candidates that ignore it.\n- You are NOT required to include the simplest possible change or the standard repo-pattern candidate unless they genuinely arise from your angle. Those are covered by other executors or by the main agent's synthesis.\n- Generate 2-3 candidates that each explore your angle from a different sub-direction -- vary the scope, the boundary, or the tradeoff accepted, but keep all of them anchored to the angle.\n- One candidate should be the most ambitious expression of your angle. One should be the most constrained. Others fill the space between.\n\nIf running standalone:\n- MANDATORY candidates:\n  1. The simplest possible change that satisfies acceptance criteria. If the problem doesn't need an architectural solution, say so.\n  2. Follow the existing repo pattern -- adapt what the codebase already does for similar problems. Don't invent when you can adapt.\n- Additional candidates (1-2 more): each must resolve the identified tensions DIFFERENTLY, not just vary surface details.\n\nFor each candidate, produce:\n- One-sentence summary of the approach\n- Which tensions it resolves and which it accepts\n- Boundary solved at, and why that boundary is the best fit\n- The specific failure mode you'd watch for\n- How it relates to existing repo patterns (follows / adapts / departs)\n- What you gain and what you give up\n- Impact surface beyond the immediate task\n- Scope judgment: too narrow / best-fit / too broad, with concrete evidence\n- Which philosophy principles it honors and which it conflicts with (by name)\n\nRules:\n- Candidates must be genuinely different in shape, not just wording\n- If all candidates converge on the same approach, note it honestly rather than manufacturing fake diversity\n- Broader scope requires concrete evidence\n- Cite specific files or patterns when they materially shape a candidate\n- Specify each candidate at the level of concrete shape, not concept labels: 'typed store' is not a specification; 'append-only per-run JSON file at a deterministic path, written atomically via temp-rename, read by coordinator before each spawn' is",
+      "prompt": "Generate design candidates that resolve the identified tensions differently.\n\nIf in executor mode (FOCUS ANGLE was set in step 0):\n- All candidates must be anchored to your assigned angle. Do not generate generic candidates that ignore it.\n- You are NOT required to include the simplest possible change or the standard repo-pattern candidate unless they genuinely arise from your angle. Those are covered by other executors or by the main agent's synthesis.\n- Generate 2-3 candidates that each explore your angle from a different sub-direction -- vary the scope, the boundary, or the tradeoff accepted, but keep all of them anchored to the angle.\n- One candidate should be the most ambitious expression of your angle. One should be the most constrained. Others fill the space between.\n\nIf running standalone:\n- MANDATORY candidates vary by domain:\n  - **Software:** (1) simplest possible change that satisfies acceptance criteria -- if no architectural solution is needed, say so; (2) adapt the existing codebase pattern -- don't invent when you can extend\n  - **Product:** (1) lowest-friction option that achieves the core outcome; (2) highest-differentiation option that maximizes long-term positioning\n  - **UX:** (1) incremental improvement within existing patterns; (2) clean-slate redesign that best serves the user's mental model\n  - **Personal:** (1) most conservative/reversible option; (2) most aligned with stated values even if uncomfortable\n  - **General:** (1) most conservative option; (2) most ambitious option\n- Additional candidates (1-2 more): each must resolve the identified tensions DIFFERENTLY, not just vary surface details.\n\nFor each candidate, produce:\n- One-sentence summary of the approach\n- Which tensions it resolves and which it accepts\n- The boundary or seam this solution addresses, and why that boundary is the right fit\n- The specific failure mode you'd watch for\n- How it relates to existing patterns or precedents (follows / adapts / departs)\n- What you gain and what you give up\n- Impact surface beyond the immediate problem\n- Scope judgment: too narrow / best-fit / too broad, with concrete evidence\n- Which principles from step 1 it honors and which it conflicts with (by name)\n\nRules:\n- Candidates must be genuinely different in shape, not just wording\n- If all candidates converge on the same approach, note it honestly rather than manufacturing fake diversity\n- Broader scope requires concrete evidence\n- Be specific: 'typed store' is not a specification; 'append-only per-run JSON file at a deterministic path, written atomically via temp-rename, read before each spawn' is. Apply the same concreteness to non-software domains: 'focus on enterprise' is not a strategy; 'target CTOs at 500-2000 person companies with a self-serve trial that converts to annual contracts' is.",
       "agentRole": "You are generating genuinely diverse design candidates grounded in real tensions.",
       "requireConfirmation": false
     },

package/workflows/workflow-for-workflows.json

@@ -647,26 +647,20 @@
       "id": "phase-7a-assign-tags",
       "title": "Phase 7a: Assign Tags",
       "promptBlocks": {
-        "goal": "Register the workflow in the catalog: assign tags in spec/workflow-tags.json and write about and examples fields into the workflow JSON so humans and agents can discover and understand the workflow.",
+        "goal": "Choose the right tags for the workflow and write the about and examples fields into the workflow JSON so humans and agents can discover and understand it.",
         "procedure": [
-          "Read spec/workflow-tags.json to see the available tags and their 'when' phrases.",
           "Based on the workflow's purpose and description, select 1-3 tags from the closed set (coding, review_audit, investigation, design, documentation, tickets, learning, routines, authoring).",
-          "Check whether the workflow ID already exists in the `workflows` section. If it does, update the existing entry tags rather than adding a duplicate. If it does not exist, add a new entry under 'workflows' in spec/workflow-tags.json: { \"tags\": [\"<tag1>\"] }.",
-          "If the workflow is a test fixture or internal utility not meant for end-user discovery, add 'hidden': true.",
-          "Save the tags file. Do not modify any other field.",
           "Write the 'about' field into the workflow JSON: a markdown string (100-400 words) written for a human deciding whether to use this workflow. Cover what it does, when to use it, what it produces, and how to get good results. This is a user-facing surface -- not agent instructions (use metaGuidance for that).",
-          "Write the 'examples' field into the workflow JSON: an array of 2-4 short, concrete goal strings (10-120 chars each) showing what this workflow is used for. Each example should be specific enough to be informative -- not generic ('implement a feature'). These appear in list_workflows output so agents can communicate concrete goal phrasing to users.",
-          "Skip 'about' and 'examples' only if the workflow is marked hidden: true."
+          "Write the 'examples' field into the workflow JSON: an array of 2-4 short, concrete goal strings (10-120 chars each) showing what this workflow is used for. Each example should be specific enough to be informative -- not generic ('implement a feature'). These appear in list_workflows output so agents can communicate concrete goal phrasing to users."
         ],
         "constraints": [
-          "Only use tags from the closed set. Do not invent new tags.",
-          "If the workflow already has an entry in the tags file, update it rather than adding a duplicate.",
-          "Tags should reflect what the workflow does, not what it is named.",
+          "Only use tags from the closed set in spec/workflow-tags.json. Do not invent new tags.",
+          "Do not write tags into the workflow JSON file -- the tags field is not part of the workflow schema. Tags are for catalog registration only, and external users do not have access to the package's spec/workflow-tags.json.",
           "Write 'about' for humans, not agents -- do not copy metaGuidance or step prompt text into it.",
           "Examples must be specific to this workflow; reject generic examples that would fit any workflow."
         ],
         "outputRequired": {
-          "notesMarkdown": "List the assigned tags with a one-line justification for each. Confirm about and examples were written."
+          "notesMarkdown": "State the chosen tags with a one-line justification for each. Confirm about and examples were written into the workflow JSON."
         }
       },
       "requireConfirmation": false

package/workflows/wr.discovery.json

@@ -1,7 +1,7 @@
 {
   "id": "wr.discovery",
   "name": "Discovery Workflow",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "metricsProfile": "research",
   "validatedAgainstSpecVersion": 3,
   "description": "Use this to explore and think through a problem end-to-end. Moves between landscape exploration, problem framing, candidate generation, adversarial challenge, and uncertainty resolution.",
@@ -180,9 +180,10 @@
           "If `goalWasSolutionStatement = true`, set `problemStatement` from `reframedProblem` rather than from the stated goal. Record the original stated goal as `statedGoal` in the design doc so the distinction is visible.",
           "Choose `landscape_first` when my dominant need is understanding the current landscape or comparing options. Choose `full_spectrum` when both landscape grounding and reframing are needed. Choose `design_first` when the dominant risk is solving the wrong problem or shaping the wrong concept. If `goalWasSolutionStatement = true`, bias toward `design_first` unless the stated solution is clearly the correct framing.",
           "Set `rigorMode` to exactly one of: `QUICK`, `STANDARD`, `THOROUGH`. This is NOT the same as `pathRecommendation` -- do not use path names as rigor values. For architectural or system design problems, default to `THOROUGH`. For one-off decisions or well-bounded comparisons, use `STANDARD`. Use `QUICK` only when speed is explicitly more important than depth.",
-          "Set `solutionAmbitiousness` to exactly one of: `minimal_viable` (smallest thing that satisfies the criteria), `best_fit` (right solution for the stated constraints), `ideal_architecture` (best solution achievable, constraints relaxed). For architectural and system design problems, default to `ideal_architecture` unless the user has explicitly constrained scope. Record this in the design doc.",
+          "Set `solutionAmbitiousness` to exactly one of: `minimal_viable` (smallest thing that satisfies the criteria), `best_fit` (right solution for the stated constraints), `ideal_solution` (best solution achievable, constraints relaxed). For architectural, system design, and strategic problems, default to `ideal_solution` unless the user has explicitly constrained scope. Record this in the design doc.",
+          "Set `problemDomain` to exactly one of: `software` (technical architecture, system design, code decisions), `product` (product strategy, feature decisions, roadmap), `ux` (user experience, interface, interaction design), `personal` (career, life decisions, personal choices), `general` (anything that doesn't fit the above). This drives conditional behavior in candidate generation -- domain-specific patterns, philosophy sources, and decision criteria. Record this in the design doc.",
           "Create or update `designDocPath` with sections for Context / Ask, Path Recommendation, Constraints / Anti-goals, Landscape Packet, Problem Frame Packet, Candidate Directions, Challenge Notes, Resolution Notes, Decision Log, and Final Summary.",
-          "Set these keys in the next `continue_workflow` call's `context` object: `problemStatement`, `desiredOutcome`, `coreConstraints`, `antiGoals`, `primaryUncertainty`, `knownApproaches`, `importantStakeholders`, `rigorMode`, `automationLevel`, `pathRecommendation`, `pathRationale`, `designDocPath`, `solutionAmbitiousness`.",
+          "Set these keys in the next `continue_workflow` call's `context` object: `problemStatement`, `desiredOutcome`, `coreConstraints`, `antiGoals`, `primaryUncertainty`, `knownApproaches`, `importantStakeholders`, `rigorMode`, `automationLevel`, `pathRecommendation`, `pathRationale`, `designDocPath`, `solutionAmbitiousness`, `problemDomain`.",
           "Also set `goal` in the context object: one sentence describing what you are trying to accomplish. This populates the session title in the Workspace console immediately."
         ],
         "verify": [
@@ -190,7 +191,8 @@
           "If `goalWasSolutionStatement = true`, the `problemStatement` reflects the reframed problem, not the stated solution.",
           "The design doc exists and the path recommendation is recorded there.",
           "`rigorMode` is exactly one of QUICK, STANDARD, THOROUGH -- not a path name or free-form string.",
-          "`solutionAmbitiousness` is set and recorded in the design doc. For architectural problems, `ideal_architecture` is the default unless scope was explicitly constrained."
+          "`solutionAmbitiousness` is set and recorded in the design doc. For architectural and strategic problems, `ideal_solution` is the default unless scope was explicitly constrained.",
+          "`problemDomain` is set and recorded in the design doc."
         ]
       },
       "requireConfirmation": {
@@ -401,7 +403,7 @@
           "Update `designDocPath` using `problemFrameTemplate`.",
           "Before finishing, name ONE specific concrete condition that would make the current framing wrong -- not a generic caveat, but a specific thing that if discovered to be true would change the path or direction. Record this as `primaryFramingRisk` in the design doc.",
           "Capture the tensions as a structured list -- not just a count. Record `identifiedTensions` as an array of one-sentence tension descriptions (e.g. 'completeness vs token budget', 'typed contracts vs evolving interfaces'). This is the list that will be passed verbatim to candidate generation executors.",
-          "Record `philosophySources` as a list of file paths or Memory entry names that encode the dev's philosophy (e.g. 'CLAUDE.md', 'AGENTS.md', '.cursor/rules/'). If none exist, record an empty list.",
+          "Record `philosophySources` as a list of file paths or Memory entry names that encode the decision-maker's principles and constraints. For `problemDomain = 'software'`: look for 'CLAUDE.md', 'AGENTS.md', '.cursor/rules/'. For `problemDomain = 'product'`: look for product principles docs, north star metrics, strategy docs. For `problemDomain = 'ux'`: look for design system docs, accessibility guidelines, brand principles. For `problemDomain = 'personal'`: look for personal values, stated priorities, life goals the user has shared. For `problemDomain = 'general'`: look for any stated principles or constraints the user has surfaced. If none exist, record an empty list.",
           "Set these keys in the next `continue_workflow` call's `context` object: `problemFrame`, `primaryUsers`, `tensionCount`, `successCriteriaCount`, `framingRiskCount`, `needsChallenge`, `retriageNeeded`, `identifiedTensions`, `philosophySources`."
         ],
         "verify": [
@@ -444,7 +446,7 @@
           "Update `designDocPath` using `problemFrameTemplate`.",
           "Before finishing, name ONE specific concrete condition that would make the current framing wrong -- not a generic caveat, but a specific thing that if discovered to be true would change the path or direction. Record this as `primaryFramingRisk` in the design doc.",
           "Capture the tensions as a structured list -- not just a count. Record `identifiedTensions` as an array of one-sentence tension descriptions (e.g. 'completeness vs token budget', 'typed contracts vs evolving interfaces'). This is the list that will be passed verbatim to candidate generation executors.",
-          "Record `philosophySources` as a list of file paths or Memory entry names that encode the dev's philosophy (e.g. 'CLAUDE.md', 'AGENTS.md', '.cursor/rules/'). If none exist, record an empty list.",
+          "Record `philosophySources` as a list of file paths or Memory entry names that encode the decision-maker's principles and constraints. For `problemDomain = 'software'`: look for 'CLAUDE.md', 'AGENTS.md', '.cursor/rules/'. For `problemDomain = 'product'`: look for product principles docs, north star metrics, strategy docs. For `problemDomain = 'ux'`: look for design system docs, accessibility guidelines, brand principles. For `problemDomain = 'personal'`: look for personal values, stated priorities, life goals the user has shared. For `problemDomain = 'general'`: look for any stated principles or constraints the user has surfaced. If none exist, record an empty list.",
           "Set these keys in the next `continue_workflow` call's `context` object: `problemFrame`, `primaryUsers`, `tensionCount`, `successCriteriaCount`, `framingRiskCount`, `needsChallenge`, `retriageNeeded`, `identifiedTensions`, `philosophySources`."
         ],
         "verify": [
@@ -527,15 +529,15 @@
         ],
         "procedure": [
           "Produce a concise synthesis of the opportunity, the 3-5 criteria the final direction must satisfy, the strongest framing risk, and the current best explanation of what success looks like. Also surface which of the `challengedAssumptions` from phase-0a are still unresolved -- any candidate that silently bets on a challenged assumption must name it as a risk.",
-          "When generating `decisionCriteria`: criteria that come from constraints and anti-goals are necessary but not sufficient. They are compatibility thresholds -- every viable candidate will satisfy them. At least one criterion must be quality-aspirational: derived from `idealEndState`, not from constraints. Quality-aspirational criteria ask 'which candidate is best?' not 'which candidates pass?'. Good examples: 'which requires the fewest changes to add a new phase?', 'which would a senior engineer be proudest of in two years?', 'which best reflects the architecture we want to be running against in 12 months?'. If `solutionAmbitiousness = 'ideal_architecture'`, this quality-aspirational criterion is mandatory -- not optional.",
+          "When generating `decisionCriteria`: criteria that come from constraints and anti-goals are necessary but not sufficient. They are compatibility thresholds -- every viable candidate will satisfy them. At least one criterion must be quality-aspirational: derived from `idealEndState`, not from constraints. Quality-aspirational criteria ask 'which candidate is best?' not 'which candidates pass?'. Examples by domain -- software: 'which requires the fewest changes to add a new phase?', 'which would a senior engineer be proudest of in two years?'; product: 'which best positions us for the market shift we expect in 18 months?', 'which gives us the most learning per unit of investment?'; ux: 'which best serves users who are stressed or in a hurry?', 'which scales to the full vision without a redesign?'; personal: 'which aligns best with the values I've said matter most?', 'which would I regret least in 10 years?'; general: 'which creates the most optionality for future decisions?'. If `solutionAmbitiousness = 'ideal_solution'`, this quality-aspirational criterion is mandatory -- not optional.",
           "Set `candidateCountTarget` adaptively: QUICK = 2-3, STANDARD = 3-4, THOROUGH = 4-5.",
-          "If a `visionDocPath` exists in context or is discoverable in the workspace (e.g. `docs/vision.md`), read it now. Then answer: (1) How does solving this problem serve the overarching vision? If it doesn't serve the vision, say so explicitly -- that is important signal. (2) Which vision goals does this design need to leave room for, even if it doesn't implement them yet? Name at least one seam or constraint the design must honor for the vision to remain achievable. (3) Does any candidate direction foreclose a vision goal that matters? If yes, name it. Add at least one vision-alignment criterion to `decisionCriteria`. If no vision doc exists, use your best understanding of the project's direction from context.",
+          "Identify and read the overarching vision or north-star document for this problem. For `problemDomain = 'software'`: look for `docs/vision.md`, `VISION.md`, or a product vision section in project docs. For `problemDomain = 'product'`: look for a product strategy doc, company mission, or OKRs. For `problemDomain = 'ux'`: look for a design vision, brand guide, or experience principles. For `problemDomain = 'personal'`: look for stated personal goals or values the user has shared. For `problemDomain = 'general'`: ask yourself what the overarching goal behind this decision is. Then answer: (1) How does solving this problem serve the overarching vision? If it doesn't, say so explicitly. (2) Which long-term goals does this decision need to leave room for? Name at least one seam or constraint the solution must honor. (3) Does any candidate direction foreclose something that matters long-term? Add at least one vision-alignment criterion to `decisionCriteria`. If no vision document exists, use your best understanding of the direction from context.",
           "Set these keys in the next `continue_workflow` call's `context` object: `decisionCriteria`, `riskiestAssumption`, `candidateCountTarget`, `needsPrototype`, `needsFurtherResearch`, `pathReady`."
         ],
         "verify": [
           "You can explain why this is the right path and what a good answer must satisfy.",
           "Remaining uncertainty is categorized explicitly instead of left fuzzy.",
-          "At least one `decisionCriterion` is quality-aspirational (derived from `idealEndState`), not just a compatibility threshold from constraints. If `solutionAmbitiousness = 'ideal_architecture'`, this is not optional.",
+          "At least one `decisionCriterion` is quality-aspirational (derived from `idealEndState`), not just a compatibility threshold from constraints. If `solutionAmbitiousness = 'ideal_solution'`, this is not optional.",
           "At least one `decisionCriterion` is vision-aligned -- it tests whether the direction serves the project's overarching goals, not just the immediate problem."
         ]
       },
@@ -588,17 +590,17 @@
           "id": "p2-ideal-architecture-criteria",
           "when": {
             "var": "solutionAmbitiousness",
-            "equals": "ideal_architecture"
+            "equals": "ideal_solution"
           },
-          "text": "Because `solutionAmbitiousness = 'ideal_architecture'`: the decision criteria must include at least one that directly tests against `idealEndState`. Constraint-satisfaction criteria alone will cause the most conservative candidate to win by default -- every viable option satisfies them. The quality-aspirational criterion is what makes the ambitious candidate compete on its own terms rather than just surviving a challenge."
+          "text": "Because `solutionAmbitiousness = 'ideal_solution'`: the decision criteria must include at least one that directly tests against `idealEndState`. Constraint-satisfaction criteria alone will cause the most conservative candidate to win by default -- every viable option satisfies them. The quality-aspirational criterion is what makes the ambitious candidate compete on its own terms rather than just surviving a challenge."
         },
         {
           "id": "p2-vision-alignment",
           "when": {
             "var": "solutionAmbitiousness",
-            "equals": "ideal_architecture"
+            "equals": "ideal_solution"
           },
-          "text": "Because this is an architectural decision: challenge your `decisionCriteria` against the vision explicitly. Ask: 'If we build this, does it make the next architectural decision easier or harder? Does it create the right seams for what the vision says comes next? Does it foreclose anything the vision names as important?' A criterion that only tests whether the design solves today's problem is insufficient -- at least one criterion must test whether the design is the right building block for tomorrow's."
+          "text": "Because `solutionAmbitiousness = 'ideal_solution'`: challenge your `decisionCriteria` against the long-term vision explicitly. Ask: 'If we choose this, does it make the next decision easier or harder? Does it create the right seams for what comes next? Does it foreclose anything that matters long-term?' A criterion that only tests whether the solution solves today's problem is insufficient -- at least one criterion must test whether it is the right building block for tomorrow's."
         }
       ],
       "requireConfirmation": false
@@ -679,9 +681,9 @@
           "id": "p3b-ideal-architecture-target",
           "when": {
             "var": "solutionAmbitiousness",
-            "equals": "ideal_architecture"
+            "equals": "ideal_solution"
           },
-          "text": "Because `solutionAmbitiousness = 'ideal_architecture'`: require at least one candidate that directly targets `idealEndState` from phase-0a. This candidate represents the best achievable outcome if effort and scope were no constraint. If it turns out to also be the most practical candidate, say so explicitly. If no candidate reaches the ideal end state, that gap must be named and justified in phase-3d -- it cannot be left implicit."
+          "text": "Because `solutionAmbitiousness = 'ideal_solution'`: require at least one candidate that directly targets `idealEndState` from phase-0a. This candidate represents the best achievable outcome if effort and scope were no constraint. If it turns out to also be the most practical candidate, say so explicitly. If no candidate reaches the ideal end state, that gap must be named and justified in phase-3d -- it cannot be left implicit."
         }
       ],
       "requireConfirmation": false
@@ -733,7 +735,7 @@
           "If `delegationAvailable = true` and (`rigorMode != QUICK` or `pathRecommendation = full_spectrum`), decide whether a delegated challenge is likely to sharpen the decision enough to be worth the extra step. If yes, spawn ONE WorkRail Executor running `routine-hypothesis-challenge` against the leading option. If not, keep the challenge in your own hands and say why.",
           "If `delegationAvailable = true` and `rigorMode = THOROUGH`, decide whether an execution simulation would materially sharpen the decision. If yes, you may also spawn ONE WorkRail Executor running `routine-execution-simulation`.",
           "Choose `selectedDirection` and `runnerUpDirection`.",
-          "Quality ceiling check: explicitly compare the selected direction to `idealEndState` from phase-0a. Answer: does the selected direction reach the ideal end state? If not, name exactly what it falls short of and why that shortfall is justified. If `solutionAmbitiousness = 'ideal_architecture'` and the selected direction is the most conservative or lowest-scope candidate, you must provide a specific reason each more ambitious candidate was ruled out -- 'too complex' or 'too much work' are not acceptable reasons on their own. Scope is a legitimate constraint only when it is a real stated constraint, not a default preference.",
+          "Quality ceiling check: explicitly compare the selected direction to `idealEndState` from phase-0a. Answer: does the selected direction reach the ideal end state? If not, name exactly what it falls short of and why that shortfall is justified. If `solutionAmbitiousness = 'ideal_solution'` and the selected direction is the most conservative or lowest-scope candidate, you must provide a specific reason each more ambitious candidate was ruled out -- 'too complex' or 'too much work' are not acceptable reasons on their own. Scope is a legitimate constraint only when it is a real stated constraint, not a default preference.",
           "Record `acceptedTradeoffs`, `identifiedFailureModes`, and what would trigger a switch.",
           "Update `designDocPath` Decision Log with why the winner won, why the runner-up lost, and how the winner compares to `idealEndState`.",
           "Set these keys in the next `continue_workflow` call's `context` object: `selectedDirection`, `runnerUpDirection`, `acceptedTradeoffs`, `identifiedFailureModes`, `hasStrongAlternative`, `needsPrototype`, `needsFurtherResearch`, `recommendationConfidenceBand`."
@@ -1144,7 +1146,8 @@
         ],
         "procedure": [
           "Update `designDocPath` with a final summary containing the selected path, problem framing, landscape takeaways, chosen direction, strongest alternative, why it lost, confidence band, residual risks, and next actions.",
-          "In the final chat output, tell me the selected path, the chosen direction, the key reason it won, and where to find `designDocPath`."
+          "In the final chat output, tell me the selected path, the chosen direction, the key reason it won, and where to find `designDocPath`.",
+          "When writing the final answer, also emit an enriched wr.discovery_handoff artifact in your complete_step call:\n{\n  \"kind\": \"wr.discovery_handoff\",\n  \"version\": 1,\n  \"selectedDirection\": \"<one sentence: the chosen approach>\",\n  \"designDocPath\": \"<path to design doc, or empty string>\",\n  \"confidenceBand\": \"high\" | \"medium\" | \"low\",\n  \"keyInvariants\": [\"<invariant that must hold>\", ...],\n  \"rejectedDirections\": [{\"direction\": \"<approach>\", \"reason\": \"<why rejected>\"}, ...],\n  \"implementationConstraints\": [\"<thing the coding agent MUST NOT violate>\", ...],\n  \"keyCodebaseLocations\": [{\"path\": \"<file path>\", \"relevance\": \"<why relevant>\"}, ...]\n}\nThe implementationConstraints and keyCodebaseLocations fields are especially important -- they orient the coding agent without requiring it to re-run discovery."
         ],
         "verify": [
           "The design doc reads like a coherent human artifact.",

package/workflows/wr.shaping.json

@@ -95,7 +95,7 @@
         "var": "isTrivial",
         "not_equals": true
       },
-      "prompt": "Generate 6 fat-marker solution sketches with genuine diversity.\n\nFor each sketch:\n- 3-5 elements described in one sentence each\n- How the elements connect\n- What it explicitly does NOT do\n- Whether it stays close to the obvious solution or deviates (be honest -- at least 2 sketches must deviate meaningfully from the most obvious approach)\n\nStay at the product level. Elements describe what the feature does -- screens, flows, policies, affordances -- not how it is built. No file paths, no function names, no system internals.\n\nUse breadboard notation for connection: **Place A → Place B when [user action]**. All words, no visual layout.\n\nAfter generating 6, select the 4 most diverse. Explicitly include the unconventional ones -- they are what makes the divergence valuable.\n\nNote any shared blind spots: things all 6 sketches ignored.\n\nCapture:\n- `candidateShapes` (array of 4: {framing, elements[], notDoing, deviatesFromObvious: boolean, description})\n- `sharedBlindSpots`",
+      "prompt": "Generate 6 fat-marker solution sketches with genuine diversity.\n\nFor each sketch:\n- 3-5 elements described in one sentence each\n- How the elements connect\n- What it explicitly does NOT do\n- Whether it stays close to the obvious solution or deviates (be honest -- at least 2 sketches must deviate meaningfully from the most obvious approach)\n\nStay at the product level. Elements describe what the feature does -- screens, flows, policies, affordances -- not how it is built. No file paths, no function names, no system internals.\n\nUse breadboard notation for connection: **Place A \u2192 Place B when [user action]**. All words, no visual layout.\n\nAfter generating 6, select the 4 most diverse. Explicitly include the unconventional ones -- they are what makes the divergence valuable.\n\nNote any shared blind spots: things all 6 sketches ignored.\n\nCapture:\n- `candidateShapes` (array of 4: {framing, elements[], notDoing, deviatesFromObvious: boolean, description})\n- `sharedBlindSpots`",
       "requireConfirmation": false
     },
     {
@@ -115,7 +115,7 @@
         "var": "isTrivial",
         "not_equals": true
       },
-      "prompt": "Expand the chosen shape into a breadboard and element list. Stay at the product level throughout.\n\n**Breadboard (words only):**\n- **Places** -- screens, dialogs, states, endpoints (from the user's perspective)\n- **Affordances** -- buttons, fields, actions -- listed under their place\n- **Connections** -- 'Place A → Place B when [user action]'\n\nNo visual layout. No code. No system internals. Words and arrows only.\n\n**Element list:**\nFor each element, one sentence classified as:\n- **Interface** -- something the user sees or interacts with (a surface, a flow, a visible state)\n- **Invariant** -- a behavioral constraint (a policy, a rule, what must always be true)\n- **Exclusion** -- functionality explicitly NOT included\n\nReject any element that:\n- Describes HOW to build something (implementation detail)\n- Uses vague modifiers without a concrete noun ('improve', 'better', 'scalable')\n\n**Structural validation for solution_roughness=high:** every element must be Interface, Invariant, or Exclusion describing product behavior -- not code structure, not technical implementation.\n\nCapture:\n- `breadboardMd` (breadboard in markdown)\n- `elements` (array: {name, description, classification: 'interface'|'invariant'|'exclusion'})",
+      "prompt": "Expand the chosen shape into a breadboard and element list. Stay at the product level throughout.\n\n**Breadboard (words only):**\n- **Places** -- screens, dialogs, states, endpoints (from the user's perspective)\n- **Affordances** -- buttons, fields, actions -- listed under their place\n- **Connections** -- 'Place A \u2192 Place B when [user action]'\n\nNo visual layout. No code. No system internals. Words and arrows only.\n\n**Element list:**\nFor each element, one sentence classified as:\n- **Interface** -- something the user sees or interacts with (a surface, a flow, a visible state)\n- **Invariant** -- a behavioral constraint (a policy, a rule, what must always be true)\n- **Exclusion** -- functionality explicitly NOT included\n\nReject any element that:\n- Describes HOW to build something (implementation detail)\n- Uses vague modifiers without a concrete noun ('improve', 'better', 'scalable')\n\n**Structural validation for solution_roughness=high:** every element must be Interface, Invariant, or Exclusion describing product behavior -- not code structure, not technical implementation.\n\nCapture:\n- `breadboardMd` (breadboard in markdown)\n- `elements` (array: {name, description, classification: 'interface'|'invariant'|'exclusion'})",
       "assessmentRefs": [
         "solution-roughness"
       ],
@@ -190,8 +190,11 @@
     {
       "id": "finalize",
       "title": "Step 9: Write pitch.md",
-      "prompt": "Write the shaped pitch to disk.\n\n1. **If isTrivial=true:** write a minimal pitch.md using `trivialTaskDescription` from Step 1 as the problem (do not pick from `candidateProblems` -- Step 2 was skipped). Content: the raw task description, then 'Appetite: xs. Single bounded change, no design decisions required.' Record `divergenceMarker: 'efficiency_skip'`.\n\n2. **Otherwise:** write `.workrail/current-pitch.md` with the full pitch from Step 7. Also archive to `.workrail/pitches/YYYY-MM-DD-[slugified-problem].md`.\n\nFirst ensure the directory exists:\n```\nmkdir -p .workrail/pitches\n```\n\nSummary to print:\n- Problem: [one sentence]\n- Appetite: [sizingBucket, calendarDays days]\n- Solution: [element names]\n- Rabbit holes: [count] identified\n- Assumptions flagged for review: [count of confidence < 0.6 entries]\n- Files written: [paths]\n- Next: hand pitch.md to a human engineering team, or run coding-task-workflow-agentic",
-      "requireConfirmation": false
+      "prompt": "Write the shaped pitch to disk.\n\n1. **If isTrivial=true:** write a minimal pitch.md using `trivialTaskDescription` from Step 1 as the problem (do not pick from `candidateProblems` -- Step 2 was skipped). Content: the raw task description, then 'Appetite: xs. Single bounded change, no design decisions required.' Record `divergenceMarker: 'efficiency_skip'`.\n\n2. **Otherwise:** write `.workrail/current-pitch.md` with the full pitch from Step 7. Also archive to `.workrail/pitches/YYYY-MM-DD-[slugified-problem].md`.\n\nFirst ensure the directory exists:\n```\nmkdir -p .workrail/pitches\n```\n\nSummary to print:\n- Problem: [one sentence]\n- Appetite: [sizingBucket, calendarDays days]\n- Solution: [element names]\n- Rabbit holes: [count] identified\n- Assumptions flagged for review: [count of confidence < 0.6 entries]\n- Files written: [paths]\n- Next: hand pitch.md to a human engineering team, or run coding-task-workflow-agentic\n\nAfter writing pitch.md, emit a wr.shaping_handoff artifact in your complete_step call:\n{\n  \"kind\": \"wr.shaping_handoff\",\n  \"version\": 1,\n  \"pitchPath\": \"<absolute path to .workrail/current-pitch.md>\",\n  \"selectedShape\": \"<one sentence: which solution shape was chosen>\",\n  \"appetite\": \"<time budget: e.g. 'Small batch (1-2 days)', 'Medium (1 week)'>\",\n  \"keyConstraints\": [\"<design constraint the coding agent must respect>\", ...],\n  \"rabbitHoles\": [\"<scope trap to avoid during implementation>\", ...],\n  \"outOfScope\": [\"<explicitly ruled out>\", ...],\n  \"validationChecklist\": [\"<verifiable acceptance criterion for the review agent>\", ...]\n}\nThe validationChecklist items should be specific and verifiable: \"All existing tests pass\", \"No new DB columns added\", \"Auth middleware is not modified\".",
+      "requireConfirmation": false,
+      "outputContract": {
+        "contractRef": "wr.contracts.shaping_handoff"
+      }
     }
   ]
 }