@exaudeus/workrail 3.15.0 → 3.17.0

package/workflows/scoped-documentation-workflow.json

@@ -2,7 +2,14 @@
   "id": "scoped-documentation-workflow",
   "name": "Scoped Documentation Workflow",
   "version": "2.0.0",
-  "description": "Use this to create documentation for a single, bounded subject \u2014 one class, one integration point, one mechanism, or one architecture decision. Enforces strict scope discipline to prevent documentation sprawl.",
+  "description": "Use this to create documentation for a single, bounded subject — one class, one integration point, one mechanism, or one architecture decision. Enforces strict scope discipline to prevent documentation sprawl.",
+  "about": "## Scoped Documentation Workflow\n\nUse this when you need to document **one specific, bounded subject** -- a single class, one integration contract, a particular algorithm, an architecture decision, or a single workflow step. The defining feature of this workflow is strict scope discipline: it explicitly defines what is \"in scope\" (explained in detail) vs. \"out of scope\" (referenced only, never explained), and enforces that boundary throughout analysis and writing.\n\n### What it produces\n\n- A focused documentation file covering the subject in depth.\n- A `SCOPE_MAP.md` that shows what is documented here vs. referenced elsewhere.\n- An optional `MAINTENANCE_NOTES.md` with guidance on when to update.\n\n### When to use it\n\n- You want docs for one class, module, mechanism, or concept -- not a whole system.\n- You've had documentation sprawl problems before and want enforced boundaries.\n- You're building a documentation set incrementally, one subject at a time.\n- The subject has clear integration points with other systems that should be referenced, not re-explained.\n\n### When NOT to use it\n\n- You need documentation that intentionally spans multiple components -- use the Document Creation workflow instead.\n- You're updating an existing doc -- use the Documentation Update workflow.\n\n### How to get good results\n\n- The first step asks you to review and approve a scope contract. Be precise here -- the whole workflow defends this boundary.\n- Out-of-scope items should already have their own documentation. If they don't, note that so the scope map can reflect it.\n- If you find the approved scope was too narrow or too broad during the workflow, you can request a scope renegotiation.",
+  "examples": [
+    "Document the RateLimiter class: its API, configuration options, and failure behavior",
+    "Write docs for the OAuth token refresh mechanism, scoped to our implementation only",
+    "Document the ADR for our choice to use event sourcing in the orders domain",
+    "Create a focused reference for the retry policy configuration in the HTTP client"
+  ],
   "clarificationPrompts": [
     "What specifically do you want to document? (feature, component, library, mechanism, interaction, architecture, process, etc.)",
     "Who will read this documentation? (team members, external users, new developers, architects, etc.)",
@@ -16,18 +23,18 @@
     "Agent can read files, analyze code, and write documentation"
   ],
   "metaGuidance": [
-    "SCOPE IS LAW: Define a boundary and defend it. REFERENCE out-of-scope items (one sentence + link). Never EXPLAIN them. One violation leads to more \u2014 protect the boundary.",
-    "REFERENCE vs EXPLAIN: Good \u2014 'This uses CacheManager (see Cache Docs) to store results.' Bad \u2014 'CacheManager works by maintaining an LRU cache that...' Never explain out-of-scope internals.",
-    "TEMPTATION LOGGING: Every time you almost explain an out-of-scope item, log it: 'Almost explained [X] but stopped \u2014 out of scope.' Zero logs on a complex subject is a red flag.",
-    "NOTES-FIRST DURABILITY: use output.notesMarkdown as the primary durable record. ANALYSIS.md, OUTLINE.md, SCOPE_CONTRACT.md are optional human-facing artifacts \u2014 not required workflow memory.",
-    "RUBRIC OVER VIBES: Score concrete dimensions with evidence sentences. Derive your next action from the rubric result \u2014 not from a gut feeling about whether things seem okay.",
+    "SCOPE IS LAW: Define a boundary and defend it. REFERENCE out-of-scope items (one sentence + link). Never EXPLAIN them. One violation leads to more — protect the boundary.",
+    "REFERENCE vs EXPLAIN: Good — 'This uses CacheManager (see Cache Docs) to store results.' Bad — 'CacheManager works by maintaining an LRU cache that...' Never explain out-of-scope internals.",
+    "TEMPTATION LOGGING: Every time you almost explain an out-of-scope item, log it: 'Almost explained [X] but stopped — out of scope.' Zero logs on a complex subject is a red flag.",
+    "NOTES-FIRST DURABILITY: use output.notesMarkdown as the primary durable record. ANALYSIS.md, OUTLINE.md, SCOPE_CONTRACT.md are optional human-facing artifacts — not required workflow memory.",
+    "RUBRIC OVER VIBES: Score concrete dimensions with evidence sentences. Derive your next action from the rubric result — not from a gut feeling about whether things seem okay.",
     "DEFAULT BEHAVIOR: self-execute with tools. Only ask the user for approvals at explicit checkpoints or for external knowledge you genuinely cannot determine yourself."
   ],
   "steps": [
     {
       "id": "phase-0-reconnaissance-and-scope",
       "title": "Phase 0: Reconnaissance & Scope Definition",
-      "prompt": "I want to create focused documentation for: \"[user's request]\"\n\n**How I work:** I handle most decisions autonomously and stop only for critical choices like scope approval. You can adjust anytime: say 'check with me more often' to add phase checkpoints, or 'just finish it' to minimize stops.\n\n**Step 1 \u2014 Reconnaissance (2-3 minutes):**\n\nExplore the subject quickly to understand the landscape before proposing scope:\n\n- Locate the subject (files, system definitions, process docs)\n- Identify primary interfaces and entry points\n- Map immediate dependencies (one level deep)\n- Check for existing documentation to avoid duplication\n- Note related components and assess complexity (simple/moderate/complex)\n\nReconnaissance findings:\n- **Primary Subject:** [what was requested]\n- **Type:** [code/system/concept/process/interaction]\n- **Located at:** [file paths, system names, or description]\n- **Related Components:** [list with brief descriptions]\n- **Dependencies:** [key dependencies identified]\n- **Existing Docs:** [found/not found]\n- **Complexity:** [Simple/Moderate/Complex]\n\n**Step 2 \u2014 Scope Proposal:**\n\nBased on reconnaissance, propose a scope contract:\n\n**Subject:** [One clear sentence describing what you're documenting]\n\n**IN SCOPE** (will be explained in detail):\n- [Specific component/feature/mechanism and its core behaviors]\n- [Common use cases and usage patterns]\n- [Integration points and interfaces]\n- [Important edge cases and design decisions]\n\n**OUT OF SCOPE** (will be referenced only, not explained):\n- [Dependency X] internals \u2014 referenced as prerequisite\n- [Related feature Y] \u2014 link to separate docs\n- [Historical context] \u2014 unless specifically needed\n\n**BOUNDARY CONDITIONS** (where in-scope meets out-of-scope):\n- [Interface with System A]: document our side, reference their docs\n- [Integration with Component B]: document the contract, not their internals\n\n**Target Audience:** [who will read this]\n**Success Criteria:** Reader can [specific outcome]\n**Estimated Length:** ~[N] words\n\n**Does this scope look right?** Reply with approval or adjustments. If no response, I'll interpret as approval and proceed.\n\nAfter approval: I'll proceed with autonomous analysis, checking back only for critical questions or validation issues.",
+      "prompt": "I want to create focused documentation for: \"[user's request]\"\n\n**How I work:** I handle most decisions autonomously and stop only for critical choices like scope approval. You can adjust anytime: say 'check with me more often' to add phase checkpoints, or 'just finish it' to minimize stops.\n\n**Step 1 — Reconnaissance (2-3 minutes):**\n\nExplore the subject quickly to understand the landscape before proposing scope:\n\n- Locate the subject (files, system definitions, process docs)\n- Identify primary interfaces and entry points\n- Map immediate dependencies (one level deep)\n- Check for existing documentation to avoid duplication\n- Note related components and assess complexity (simple/moderate/complex)\n\nReconnaissance findings:\n- **Primary Subject:** [what was requested]\n- **Type:** [code/system/concept/process/interaction]\n- **Located at:** [file paths, system names, or description]\n- **Related Components:** [list with brief descriptions]\n- **Dependencies:** [key dependencies identified]\n- **Existing Docs:** [found/not found]\n- **Complexity:** [Simple/Moderate/Complex]\n\n**Step 2 — Scope Proposal:**\n\nBased on reconnaissance, propose a scope contract:\n\n**Subject:** [One clear sentence describing what you're documenting]\n\n**IN SCOPE** (will be explained in detail):\n- [Specific component/feature/mechanism and its core behaviors]\n- [Common use cases and usage patterns]\n- [Integration points and interfaces]\n- [Important edge cases and design decisions]\n\n**OUT OF SCOPE** (will be referenced only, not explained):\n- [Dependency X] internals — referenced as prerequisite\n- [Related feature Y] — link to separate docs\n- [Historical context] — unless specifically needed\n\n**BOUNDARY CONDITIONS** (where in-scope meets out-of-scope):\n- [Interface with System A]: document our side, reference their docs\n- [Integration with Component B]: document the contract, not their internals\n\n**Target Audience:** [who will read this]\n**Success Criteria:** Reader can [specific outcome]\n**Estimated Length:** ~[N] words\n\n**Does this scope look right?** Reply with approval or adjustments. If no response, I'll interpret as approval and proceed.\n\nAfter approval: I'll proceed with autonomous analysis, checking back only for critical questions or validation issues.",
       "requireConfirmation": true,
       "validationCriteria": [
         {
@@ -54,14 +61,14 @@
       "promptBlocks": {
         "goal": "Analyze the subject thoroughly within the approved scope boundary and score evidence quality before proceeding.",
         "constraints": [
-          "Enforce scope during analysis: read and trace only in-scope files and behaviors. When you encounter an out-of-scope item, log it and move on \u2014 do not analyze it.",
+          "Enforce scope during analysis: read and trace only in-scope files and behaviors. When you encounter an out-of-scope item, log it and move on — do not analyze it.",
           "Notes-first: record analysis findings in notesMarkdown, not in ANALYSIS.md as a required artifact.",
-          "Derive the proceed/gather-more decision from the evidence rubric \u2014 not from a gut feeling."
+          "Derive the proceed/gather-more decision from the evidence rubric — not from a gut feeling."
         ],
         "procedure": [
           "Investigation approach: (1) Map interfaces and public API surface (in-scope only). (2) Trace key execution flows and behaviors. (3) Identify important mechanisms and patterns. (4) Extract 5+ representative examples from code or usage. (5) Document integration points at the interface/contract level only. (6) Note design decisions and tradeoffs.",
-          "Boundary enforcement (continuous) \u2014 when you encounter something outside scope: REFERENCE IT ('This integrates with [System X] via [interface]'), LINK TO DOCS ('For [System X] details, see [link]'), DO NOT EXPLAIN IT, DO NOT ANALYZE IT, LOG THE TEMPTATION ('Almost analyzed [X] but stopped \u2014 out of scope').",
-          "Evidence rubric \u2014 score all 4 dimensions before deciding to proceed. Score each dimension 0, 1, or 2 and write one evidence sentence for each.",
+          "Boundary enforcement (continuous) — when you encounter something outside scope: REFERENCE IT ('This integrates with [System X] via [interface]'), LINK TO DOCS ('For [System X] details, see [link]'), DO NOT EXPLAIN IT, DO NOT ANALYZE IT, LOG THE TEMPTATION ('Almost analyzed [X] but stopped — out of scope').",
+          "Evidence rubric — score all 4 dimensions before deciding to proceed. Score each dimension 0, 1, or 2 and write one evidence sentence for each.",
           "subjectBoundaryClarity: 0=boundary confirmed and clear, 1=likely correct but one area uncertain, 2=boundary still ambiguous",
           "behaviorCoverage: 0=all key behaviors identified with examples, 1=most behaviors covered with minor gaps, 2=significant behavior gaps remain",
           "examplesCollected: 0=5+ concrete examples extracted from subject, 1=2-4 examples found, 2=fewer than 2 verifiable examples",
@@ -70,7 +77,7 @@
           "If you find a critical scope issue (the subject is actually two distinct subjects, or a required dependency cannot be referenced without explaining it), surface this to the user before proceeding."
         ],
         "outputRequired": {
-          "analysisFindings": "Subject overview, core behaviors/components, integration points, examples (5+), design decisions \u2014 recorded in notesMarkdown",
+          "analysisFindings": "Subject overview, core behaviors/components, integration points, examples (5+), design decisions — recorded in notesMarkdown",
           "scopeBoundaryLog": "Every temptation stopped: what was encountered and why it was left out",
           "evidenceRubricScores": "All 4 dimensions scored with evidence sentences, plus gate decision (proceed or gather more with specifics)"
         },
@@ -90,18 +97,18 @@
         "goal": "Design the documentation structure and create a detailed outline that maps directly to the Phase 1 analysis findings.",
         "constraints": [
           "Every section must map to an in-scope item from Phase 1 analysis.",
-          "Out-of-scope items belong only in a 'Related Documentation' section \u2014 as references, never explanations.",
-          "Pull all content points from Phase 1 findings \u2014 do not invent new content that wasn't in the analysis.",
+          "Out-of-scope items belong only in a 'Related Documentation' section — as references, never explanations.",
+          "Pull all content points from Phase 1 findings — do not invent new content that wasn't in the analysis.",
           "Notes-first: record the outline in notesMarkdown, not only in OUTLINE.md."
         ],
         "procedure": [
-          "Step 1 \u2014 Choose structure type based on subject: Code subject: Overview \u2192 How It Works \u2192 Usage Guide \u2192 Reference \u2192 Edge Cases \u2192 Related Docs. System/concept: Overview \u2192 Components \u2192 Interactions \u2192 Integration \u2192 Examples \u2192 Related Docs. Process/workflow: Overview \u2192 Steps \u2192 Decision Points \u2192 Examples \u2192 Troubleshooting \u2192 Related Docs. Adjust sections based on what analysis actually found.",
-          "Step 2 \u2014 Create detailed outline. For each section, specify: content points sourced from Phase 1 analysis (with evidence references), examples to include (from Phase 1 examples), approximate word count target, whether this section documents in-scope items or references out-of-scope ones.",
-          "Step 3 \u2014 Scope compliance check on the outline. Review every section and confirm: Does it map to an in-scope item? Does it require explaining any out-of-scope dependency? Can the content be written entirely from Phase 1 findings?",
+          "Step 1 — Choose structure type based on subject: Code subject: Overview → How It Works → Usage Guide → Reference → Edge Cases → Related Docs. System/concept: Overview → Components → Interactions → Integration → Examples → Related Docs. Process/workflow: Overview → Steps → Decision Points → Examples → Troubleshooting → Related Docs. Adjust sections based on what analysis actually found.",
+          "Step 2 — Create detailed outline. For each section, specify: content points sourced from Phase 1 analysis (with evidence references), examples to include (from Phase 1 examples), approximate word count target, whether this section documents in-scope items or references out-of-scope ones.",
+          "Step 3 — Scope compliance check on the outline. Review every section and confirm: Does it map to an in-scope item? Does it require explaining any out-of-scope dependency? Can the content be written entirely from Phase 1 findings?",
           "If any section requires explaining an out-of-scope item: convert it to a reference, remove it, or surface a scope re-negotiation to the user. If any section cannot be written from Phase 1 findings: flag what additional analysis is needed and return to Phase 1."
         ],
         "outputRequired": {
-          "documentationStructure": "Section titles, word count targets, and content-source mapping \u2014 recorded in notesMarkdown",
+          "documentationStructure": "Section titles, word count targets, and content-source mapping — recorded in notesMarkdown",
           "scopeComplianceConfirmation": "All sections confirmed to map to in-scope items",
           "totalEstimatedWordCount": "Total word count estimate",
           "analysisGaps": "Any gaps requiring return to Phase 1 (if none, state none)"
@@ -109,7 +116,7 @@
         "verify": [
           "Every section maps to an in-scope item from Phase 1 analysis",
           "Out-of-scope items only appear in 'Related Documentation' section",
-          "All examples sourced from Phase 1 \u2014 none invented",
+          "All examples sourced from Phase 1 — none invented",
           "Outline recorded in notesMarkdown"
         ]
       },
@@ -121,16 +128,16 @@
       "promptBlocks": {
         "goal": "Write the documentation section by section, enforcing scope boundaries continuously and logging all boundary decisions.",
         "constraints": [
-          "Content must come from Phase 1 analysis and Phase 2 outline \u2014 do not introduce new claims or examples that weren't in the analysis.",
+          "Content must come from Phase 1 analysis and Phase 2 outline — do not introduce new claims or examples that weren't in the analysis.",
           "After every paragraph: check scope compliance. Am I explaining something in scope or referencing something out of scope?",
           "Mark boundaries clearly in the text so readers know what's in vs out.",
           "Notes-first: the documentation file is the primary artifact; ANALYSIS.md or OUTLINE.md sidecar files are optional."
         ],
         "procedure": [
-          "Writing approach \u2014 section by section. For each section from the Phase 2 outline: (1) Draft content from outline and Phase 1 findings. (2) Add examples from analysis (complete, not fragments). (3) Check scope compliance inline. (4) Write boundary markers for out-of-scope references. (5) Log any temptation to explain an out-of-scope item.",
-          "Scope boundary wording \u2014 use these patterns. Good (reference only): 'This uses the CacheManager (see Cache Documentation) to store results.' Good: 'For authentication details, see Auth Service Documentation.' Bad (explaining out-of-scope): 'The CacheManager works by maintaining an in-memory LRU cache that...'",
-          "After writing all sections \u2014 final scope audit. Read through the complete draft and count: lines documenting in-scope items (vast majority), lines referencing out-of-scope items (minimal), lines explaining out-of-scope items (must be zero). Fix any violations before advancing to Phase 4.",
-          "If you discover a critical inaccuracy (a claim you cannot verify from analysis), flag it for user confirmation in Phase 4 \u2014 don't silently remove it.",
+          "Writing approach — section by section. For each section from the Phase 2 outline: (1) Draft content from outline and Phase 1 findings. (2) Add examples from analysis (complete, not fragments). (3) Check scope compliance inline. (4) Write boundary markers for out-of-scope references. (5) Log any temptation to explain an out-of-scope item.",
+          "Scope boundary wording — use these patterns. Good (reference only): 'This uses the CacheManager (see Cache Documentation) to store results.' Good: 'For authentication details, see Auth Service Documentation.' Bad (explaining out-of-scope): 'The CacheManager works by maintaining an in-memory LRU cache that...'",
+          "After writing all sections — final scope audit. Read through the complete draft and count: lines documenting in-scope items (vast majority), lines referencing out-of-scope items (minimal), lines explaining out-of-scope items (must be zero). Fix any violations before advancing to Phase 4.",
+          "If you discover a critical inaccuracy (a claim you cannot verify from analysis), flag it for user confirmation in Phase 4 — don't silently remove it.",
           "Write the documentation to a file. Suggested filename: [SUBJECT]_Documentation.md or similar. Record the path in mainDocumentationFile."
         ],
         "outputRequired": {
@@ -151,7 +158,7 @@
     {
       "id": "phase-4-validation-and-delivery",
       "title": "Phase 4: Adversarial Validation & Delivery",
-      "prompt": "Now be the harshest critic before delivering.\n\n**VALIDATION RUBRIC \u2014 score all 4 dimensions with evidence:**\n\n**1. Scope Compliance**\n- PASS: zero unexplained out-of-scope items in the documentation\n- PARTIAL: minor violations found and fixed autonomously\n- FAIL: violations found that cannot be fixed without user input\n- Evidence: [sentence + violation count]\n- Action: FAIL triggers user input; PARTIAL acceptable with disclosure\n\n**2. Completeness**\n- PASS: all in-scope items from the scope contract are documented\n- PARTIAL: minor gaps (non-critical items missing)\n- FAIL: significant in-scope items missing\n- Evidence: [sentence + gap count]\n- Action: FAIL triggers autonomous content addition then re-validate; PARTIAL acceptable with disclosure\n\n**3. Accuracy**\n- PASS: all technical claims verifiable from Phase 1 analysis\n- PARTIAL: minor uncertainties clearly marked in documentation\n- FAIL: key claims uncertain \u2014 external confirmation required\n- Evidence: [sentence + uncertain claim count]\n- Action: FAIL triggers user checkpoint with specific questions; PARTIAL acceptable with disclosure\n\n**4. Clarity**\n- PASS: target audience can achieve the success criteria using this documentation\n- PARTIAL: some sections need clearer wording\n- FAIL: significant clarity gaps preventing successful use\n- Evidence: [sentence]\n- Action: FAIL triggers autonomous rewrite then re-validate; PARTIAL acceptable with disclosure\n\n---\n\n**Gate rules:**\n- scopeCompliance and completeness must both reach PASS for delivery\n- accuracy FAIL triggers user checkpoint \u2014 list specific questions below\n- clarity FAIL triggers autonomous rewrite\n- accuracy PARTIAL and clarity PARTIAL proceed with disclosure\n\n**If all gates pass or are acceptable for delivery:**\n\nCreate SCOPE_MAP.md:\n```\n# Scope Map: [Subject]\n\n## Documented Here (In Scope)\n- [Item]: [brief description] \u2014 see [Section]\n\n## Referenced Only (Out of Scope)\n- [Item]: [brief description] \u2014 [link if available]\n\n## Integration Points\n- [Where this connects to other systems / interface contracts]\n\n## Related Documentation\n- [Links with descriptions]\n```\n\nOptionally create MAINTENANCE_NOTES.md with: when to update this documentation, which sections to review for accuracy, scope boundary reminders (what stays referenced-only).\n\n**DELIVERY SUMMARY:**\n\n- Main documentation: [path] (~[N] words)\n- Scope map: SCOPE_MAP.md\n- Validation results: scopeCompliance=[X], completeness=[X], accuracy=[X], clarity=[X]\n- Scope discipline: [N] temptations stopped, 0 violations in final delivery\n- Audience: [target audience]\n- Success criteria: Reader can [outcome]\n\n---\n\n**IF accuracy FAIL \u2014 user checkpoint required:**\n\nBefore I can deliver, I need your input on accuracy:\n\n[List specific technical claims that need confirmation, with context for each]\n\nOnce you confirm, I'll finalize and deliver.",
+      "prompt": "Now be the harshest critic before delivering.\n\n**VALIDATION RUBRIC — score all 4 dimensions with evidence:**\n\n**1. Scope Compliance**\n- PASS: zero unexplained out-of-scope items in the documentation\n- PARTIAL: minor violations found and fixed autonomously\n- FAIL: violations found that cannot be fixed without user input\n- Evidence: [sentence + violation count]\n- Action: FAIL triggers user input; PARTIAL acceptable with disclosure\n\n**2. Completeness**\n- PASS: all in-scope items from the scope contract are documented\n- PARTIAL: minor gaps (non-critical items missing)\n- FAIL: significant in-scope items missing\n- Evidence: [sentence + gap count]\n- Action: FAIL triggers autonomous content addition then re-validate; PARTIAL acceptable with disclosure\n\n**3. Accuracy**\n- PASS: all technical claims verifiable from Phase 1 analysis\n- PARTIAL: minor uncertainties clearly marked in documentation\n- FAIL: key claims uncertain — external confirmation required\n- Evidence: [sentence + uncertain claim count]\n- Action: FAIL triggers user checkpoint with specific questions; PARTIAL acceptable with disclosure\n\n**4. Clarity**\n- PASS: target audience can achieve the success criteria using this documentation\n- PARTIAL: some sections need clearer wording\n- FAIL: significant clarity gaps preventing successful use\n- Evidence: [sentence]\n- Action: FAIL triggers autonomous rewrite then re-validate; PARTIAL acceptable with disclosure\n\n---\n\n**Gate rules:**\n- scopeCompliance and completeness must both reach PASS for delivery\n- accuracy FAIL triggers user checkpoint — list specific questions below\n- clarity FAIL triggers autonomous rewrite\n- accuracy PARTIAL and clarity PARTIAL proceed with disclosure\n\n**If all gates pass or are acceptable for delivery:**\n\nCreate SCOPE_MAP.md:\n```\n# Scope Map: [Subject]\n\n## Documented Here (In Scope)\n- [Item]: [brief description] — see [Section]\n\n## Referenced Only (Out of Scope)\n- [Item]: [brief description] — [link if available]\n\n## Integration Points\n- [Where this connects to other systems / interface contracts]\n\n## Related Documentation\n- [Links with descriptions]\n```\n\nOptionally create MAINTENANCE_NOTES.md with: when to update this documentation, which sections to review for accuracy, scope boundary reminders (what stays referenced-only).\n\n**DELIVERY SUMMARY:**\n\n- Main documentation: [path] (~[N] words)\n- Scope map: SCOPE_MAP.md\n- Validation results: scopeCompliance=[X], completeness=[X], accuracy=[X], clarity=[X]\n- Scope discipline: [N] temptations stopped, 0 violations in final delivery\n- Audience: [target audience]\n- Success criteria: Reader can [outcome]\n\n---\n\n**IF accuracy FAIL — user checkpoint required:**\n\nBefore I can deliver, I need your input on accuracy:\n\n[List specific technical claims that need confirmation, with context for each]\n\nOnce you confirm, I'll finalize and deliver.",
       "requireConfirmation": true,
       "validationCriteria": [
         {
@@ -178,4 +185,4 @@
       "hasValidation": true
     }
   ]
-}
+}

package/workflows/ui-ux-design-workflow.json

@@ -3,6 +3,13 @@
   "name": "UI/UX Design Workflow (v1 \u2022 Process-Enforced \u2022 Evidence-Driven)",
   "version": "0.1.0",
   "description": "Design UI/UX from scratch with enforced process. Makes problem framing structurally required before solution proposals, forces exploration of multiple design directions before convergence, and applies reviewer families for information architecture, UX laws, accessibility, edge cases, and content. Output: a design spec concrete enough to implement or review.",
+  "about": "## UI/UX Design Workflow\n\nThis workflow produces a design spec for a new feature, screen, component, or interaction. It is built around a single principle: problem framing must happen before any solutions are proposed. The workflow makes this structurally impossible to skip, which prevents the most common failure mode in AI-assisted design  -- going straight from \"I need a settings screen\" to a layout without ever asking who uses it or what they are trying to do.\n\n**What it does:**\nPhase 0 frames the problem by reading existing code patterns and asking only what tools cannot answer. Phase 1 generates 2-3 genuinely different design directions before any one is chosen. Phases 2-5 run parallel reviewer families  -- information architecture, UX laws (Hick's Law, Miller's Law, Fitts's Law, and others), accessibility (specific WCAG requirements, not just \"follow WCAG\"), edge cases (empty, error, loading, first-use), and content quality  -- then synthesize their findings, resolve contradictions, and write a spec only after all hard quality gates pass.\n\n**When to use it:**\n- You need to design a new screen, feature, or non-trivial component\n- You want explicit coverage of accessibility, edge states, and UX laws, not just a layout sketch\n- You need a spec concrete enough for an engineer to implement or a designer to review\n- Simple single-component changes also work through a lighter direct-spec path\n\n**What it produces:**\nA design spec with 8 sections: design decision, information architecture, interaction design, all element states, specific accessibility requirements, content copy, reviewer findings with citations, and open questions that still require human visual review.\n\n**How to get good results:**\nPoint the workflow to your codebase so it can read existing components and patterns. Provide the design system location if it is not in the repo. Share any known user pain points or research. The workflow will surface what it cannot determine on its own.",
+  "examples": [
+    "Design the empty state and onboarding flow for a new team dashboard feature",
+    "Design a settings panel for notification preferences with accessibility requirements",
+    "Design the error and loading states for the file upload component",
+    "Redesign the search results screen to reduce cognitive load for first-time users"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"

package/workflows/workflow-diagnose-environment.json

@@ -3,6 +3,12 @@
   "name": "Diagnostic: Environment & Subagents",
   "version": "1.0.0",
   "description": "Use this to diagnose MCP server, tool availability, or environment configuration issues. Probes for subagent access and generates a local configuration file.",
+  "about": "## Environment Diagnostic Workflow\n\nThis is a short, self-contained diagnostic that checks what capabilities are actually available in the current workspace  -- specifically whether subagent delegation works and whether WorkRail tools are accessible to those subagents.\n\n**What it does:**\nThe workflow actively probes for subagent access by attempting to contact a subagent and have it list available tools. Based on the result, it classifies the environment into one of three tiers: full delegation (Tier 3), proxy mode where subagents exist but lack tool access (Tier 2), or solo mode with no subagents available (Tier 1). It then writes a `.workrail/config.json` file recording the detected capability tier so other workflows can make informed delegation decisions.\n\n**When to use it:**\n- You are setting up WorkRail in a new workspace for the first time\n- A workflow that relies on subagent delegation is not working as expected\n- You suspect MCP server configuration is wrong but are not sure what tier you are in\n- You want a persistent record of what the current environment can actually do\n\n**What it produces:**\nA `.workrail/config.json` file with the detected mode (`delegate`, `proxy`, or `solo`) and subagent names if discovered. A summary of what capabilities were found.\n\n**How to get good results:**\nRun this workflow before starting complex multi-agent workflows. It takes only two steps and requires no input from you beyond starting it.",
+  "examples": [
+    "Check if subagent delegation is available in this workspace",
+    "Set up WorkRail config for a new project environment",
+    "Diagnose why delegation-dependent workflows are falling back to solo mode"
+  ],
   "steps": [
     {
       "id": "step-0-probe-capabilities",

package/workflows/workflow-for-workflows.json

@@ -3,6 +3,13 @@
   "name": "Progressive Workflow Creation Guide",
   "version": "0.1.0",
   "description": "Use this to author or modernize a WorkRail workflow. Guides through understanding the task, defining effectiveness targets, designing architecture and quality gates, drafting, validating, and handing off.",
+  "about": "## Workflow Authoring Workflow\n\nThis is the standard WorkRail workflow for creating a new workflow from scratch or modernizing an existing one. It is the trust gate for all other workflows: a workflow is not considered production-ready until it has passed through here.\n\n**What it does:**\nThe workflow walks through the full authoring lifecycle: understanding the task, choosing the right baseline and archetype, designing the phase and quality-gate architecture, drafting the workflow JSON, running structural validators, auditing state fields for bloat, simulating execution against real scenarios, running an adversarial quality review, and producing a final trust handoff. For modernization tasks it builds a value inventory first to ensure enforcement mechanisms, domain knowledge, and behavioral rules are preserved or equivalently replaced.\n\n**When to use it:**\n- You want to author a new WorkRail workflow for a recurring task or problem\n- You have an existing workflow that is outdated, uses legacy patterns (pseudo-DSL, regex validation, satisfaction-score loops), or produces shallow results\n- You want a workflow that will pass the WorkRail quality bar and be trusted to run in production\n\n**What it produces:**\nA validated, tagged workflow JSON file with a `validatedAgainstSpecVersion` stamp. A final trust handoff with readiness verdict, known failure modes, residual weaknesses, and testing guidance.\n\n**How to get good results:**\nDescribe the recurring task the workflow should solve, who will run it, and what a satisfying result looks like. For modernization, point to the existing workflow file. The workflow reads the schema and authoring spec itself  -- you do not need to know the JSON format in advance.",
+  "examples": [
+    "Create a new workflow for conducting weekly engineering retrospectives",
+    "Modernize the old exploration workflow to use v2 authoring patterns and remove pseudo-DSL",
+    "Author a workflow for triaging and prioritizing incoming support tickets",
+    "Upgrade the code review workflow to add adversarial reviewer families and hard gates"
+  ],
   "clarificationPrompts": [
     "What's your experience level with workflow creation? (New to this / Some experience / Very experienced)",
     "What type of workflow are you creating? (e.g., coding, analysis, content creation, process management)",

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

@@ -3,6 +3,13 @@
   "name": "Workflow Authoring Workflow (Quality Gate v2)",
   "version": "2.4.0",
   "description": "Use this to author or modernize a WorkRail workflow. Guides through understanding the task, defining effectiveness targets, designing architecture and quality gates, drafting, validating, assigning tags, and handing off.",
+  "about": "## Workflow Authoring Workflow\n\nThis is the standard WorkRail workflow for creating a new workflow from scratch or modernizing an existing one. It is the trust gate for all other workflows: a workflow is not considered production-ready until it has passed through here.\n\n**What it does:**\nThe workflow walks through the full authoring lifecycle: understanding the task, choosing the right baseline and archetype, designing the phase and quality-gate architecture, drafting the workflow JSON, running structural validators, auditing state fields for bloat, simulating execution against real scenarios, running an adversarial quality review, and producing a final trust handoff. For modernization tasks it builds a value inventory first to ensure enforcement mechanisms, domain knowledge, and behavioral rules are preserved or equivalently replaced.\n\n**When to use it:**\n- You want to author a new WorkRail workflow for a recurring task or problem\n- You have an existing workflow that is outdated, uses legacy patterns (pseudo-DSL, regex validation, satisfaction-score loops), or produces shallow results\n- You want a workflow that will pass the WorkRail quality bar and be trusted to run in production\n\n**What it produces:**\nA validated, tagged workflow JSON file with a `validatedAgainstSpecVersion` stamp. A final trust handoff with readiness verdict, known failure modes, residual weaknesses, and testing guidance.\n\n**How to get good results:**\nDescribe the recurring task the workflow should solve, who will run it, and what a satisfying result looks like. For modernization, point to the existing workflow file. The workflow reads the schema and authoring spec itself  -- you do not need to know the JSON format in advance.",
+  "examples": [
+    "Create a new workflow for conducting weekly engineering retrospectives",
+    "Modernize the old exploration workflow to use v2 authoring patterns and remove pseudo-DSL",
+    "Author a workflow for triaging and prioritizing incoming support tickets",
+    "Upgrade the code review workflow to add adversarial reviewer families and hard gates"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"
@@ -192,7 +199,7 @@
           "Decide the phase list, one-line goal for each phase, and overall ordering.",
           "Design loops with explicit exit rules, bounded maxIterations, and real reasons for another pass.",
           "Decide confirmation gates, delegation vs template injection vs direct execution, promptFragments, references, artifacts, and metaGuidance.",
-          "If `authoringMode = modernize_existing`, decide preserve-in-place, restructure, or rewrite. For each item in valueInventory, record: `preserved` (structurally present with equivalent enforcement), `replaced` (new mechanism prevents same failure mode — justify equivalence), or `dropped` (intentionally removed — justify the loss). Phase-level mapping alone is insufficient; track what was inside each restructured or removed phase."
+          "If `authoringMode = modernize_existing`, decide preserve-in-place, restructure, or rewrite. For each item in valueInventory, record: `preserved` (structurally present with equivalent enforcement), `replaced` (new mechanism prevents same failure mode  -- justify equivalence), or `dropped` (intentionally removed  -- justify the loss). Phase-level mapping alone is insufficient; track what was inside each restructured or removed phase."
         ],
         "outputRequired": {
           "notesMarkdown": "Structured workflow outline, loop design, confirmation design, delegation design, artifact plan, and modernization mapping.",
@@ -440,7 +447,7 @@
             "procedure": [
               "Trace the authored workflow step by step against the user's actual task or the closest realistic scenario.",
               "For each step, ask: what would the agent actually do, what context would it have, what would it likely produce, and what would the next step inherit?",
-              "Also trace at least one degraded or edge-case path — not just the happy path. Ask: what happens when a condition evaluates unexpectedly, a loop has nothing to iterate, a runCondition skips a phase, or the user provides minimal input? Quality gates that only protect the happy path are not quality gates.",
+              "Also trace at least one degraded or edge-case path  -- not just the happy path. Ask: what happens when a condition evaluates unexpectedly, a loop has nothing to iterate, a runCondition skips a phase, or the user provides minimal input? Quality gates that only protect the happy path are not quality gates.",
               "Identify likely weak steps, likely unsatisfying outputs, and likely false-confidence modes.",
               "For any loop in the workflow, explicitly check: does the exit condition have structural teeth (artifact contract, bounded maxIterations), or does it rely on prose instructions the engine cannot enforce?",
               "Fix issues directly in the workflow file when the right improvement is clear."
@@ -468,7 +475,7 @@
                 "var": "authoringMode",
                 "equals": "modernize_existing"
               },
-              "text": "For modernize_existing: after tracing the workflow forward, check each item in valueInventory. For each enforcement mechanism and domain knowledge item: would the modernized workflow produce the same behavior? Any item where the answer is no or weaker is a loss — fix it directly or record the accepted tradeoff with justification."
+              "text": "For modernize_existing: after tracing the workflow forward, check each item in valueInventory. For each enforcement mechanism and domain knowledge item: would the modernized workflow produce the same behavior? Any item where the answer is no or weaker is a loss  -- fix it directly or record the accepted tradeoff with justification."
             }
           ],
           "requireConfirmation": false
@@ -483,7 +490,7 @@
               "Reviewer-family or validator output is evidence, not authority."
             ],
             "procedure": [
-              "Score these dimensions 0-2 with one sentence of evidence each: `voiceClarity`, `ceremonyLevel`, `loopSoundness`, `delegationBoundedness`, `artifactClarity`, `taskEffectiveness`, `falseConfidenceResistance`, `stateMinimality`, `coverageSharpness`, `domainFit`, `handoffUtility`, `rigorAdaptability` (0 = adapts to complexity/rigor levels, 2 = single-weight), `enforcementStrength` (0 = behavioral rules have structural teeth; 2 = important rules are prose-only with no enforcement mechanism), and `modernizationDiscipline` (0 = every valueInventory item preserved, equivalently replaced with justification, or dropped with justification; 2 = items missing or replaced with weaker versions without justification — score 0 for create mode).",
+              "Score these dimensions 0-2 with one sentence of evidence each: `voiceClarity`, `ceremonyLevel`, `loopSoundness`, `delegationBoundedness`, `artifactClarity`, `taskEffectiveness`, `falseConfidenceResistance`, `stateMinimality`, `coverageSharpness`, `domainFit`, `handoffUtility`, `rigorAdaptability` (0 = adapts to complexity/rigor levels, 2 = single-weight), `enforcementStrength` (0 = behavioral rules have structural teeth; 2 = important rules are prose-only with no enforcement mechanism), and `modernizationDiscipline` (0 = every valueInventory item preserved, equivalently replaced with justification, or dropped with justification; 2 = items missing or replaced with weaker versions without justification  -- score 0 for create mode).",
               "If delegation is available and rigor is THOROUGH, run an adversarial review bundle with these lenses: `engine_native_reviewer`, `task_effectiveness_reviewer`, `state_economy_reviewer`, `false_confidence_reviewer`, `domain_fit_reviewer`, and `maintainer_reviewer`.",
               "Synthesize what the review confirmed, what it challenged, and what changed your mind.",
               "When scoring `falseConfidenceResistance`, explicitly check: do the workflow's quality gates protect edge cases and degraded paths, or only the happy path? A workflow that passes its own checks on ideal input but fails silently on minimal or unexpected input scores 2.",
@@ -521,7 +528,7 @@
                 "var": "authoringMode",
                 "equals": "modernize_existing"
               },
-              "text": "For modernize_existing: add a heritage_reviewer to the adversarial bundle. Its job is to check each valueInventory item and find what was lost or weakened — it ignores format improvements. It must answer: which enforcement mechanisms are now prose-only? Which domain knowledge items are absent? Which behavioral rules were removed without equivalent replacement? Heritage_reviewer findings drive enforcementStrength and modernizationDiscipline scores."
+              "text": "For modernize_existing: add a heritage_reviewer to the adversarial bundle. Its job is to check each valueInventory item and find what was lost or weakened  -- it ignores format improvements. It must answer: which enforcement mechanisms are now prose-only? Which domain knowledge items are absent? Which behavioral rules were removed without equivalent replacement? Heritage_reviewer findings drive enforcementStrength and modernizationDiscipline scores."
             }
           ],
           "requireConfirmation": false
@@ -584,21 +591,26 @@
       "id": "phase-7a-assign-tags",
       "title": "Phase 7a: Assign Tags",
       "promptBlocks": {
-        "goal": "Register the workflow in spec/workflow-tags.json by assigning 1-3 tags from the closed tag set.",
+        "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.",
         "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).",
           "Add the workflow ID as 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 file. Do not modify any other field in the tags file."
+          "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."
         ],
         "constraints": [
           "Only use tags from the closed set. Do not invent new tags.",
-          "If the workflow already has an entry, update it rather than adding a duplicate.",
-          "Tags should reflect what the workflow does, not what it is named."
+          "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.",
+          "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 and a one-line justification for each."
+          "notesMarkdown": "List the assigned tags with a one-line justification for each. Confirm about and examples were written."
         }
       },
       "requireConfirmation": false
@@ -612,7 +624,7 @@
           "Keep it concise. The workflow file is the deliverable, not the summary."
         ],
         "procedure": [
-          "Stamp the workflow file: read the current `version` from `spec/authoring-spec.json` and write `validatedAgainstSpecVersion: <N>` as a top-level field in the workflow JSON. Commit the change — the stamp has no effect if only saved locally.",
+          "Stamp the workflow file: read the current `version` from `spec/authoring-spec.json` and write `validatedAgainstSpecVersion: <N>` as a top-level field in the workflow JSON. Commit the change  -- the stamp has no effect if only saved locally.",
           "State the workflow file path and name, whether it was created or modernized, and what it does in one sentence.",
           "Summarize the step structure, loops, confirmations, and delegation profile.",
           "Report validation status, authoring-integrity status, and outcome-effectiveness status.",

package/workflows/wr.discovery.json

@@ -1,8 +1,15 @@
 {
   "id": "wr.discovery",
-  "name": "Discovery Workflow (Bundled \u2022 Exploration + Design Synthesis)",
+  "name": "Discovery Workflow (Bundled • Exploration + Design Synthesis)",
   "version": "3.1.0",
   "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.",
+  "about": "## Discovery Workflow\n\nThis workflow is for structured thinking through an ambiguous problem, opportunity, or decision  -- the kind where you are not sure of the right answer yet and jumping straight to solutions would be premature.\n\n**What it does:**\nThe workflow selects one of three emphasis paths based on your actual need: `landscape_first` for understanding the current state and comparing options, `full_spectrum` for important or ambiguous problems where both landscape grounding and reframing are needed, and `design_first` when the dominant risk is solving the wrong problem. It then moves through landscape research, stakeholder and problem framing, candidate direction generation, adversarial challenge, and an uncertainty-resolution stage that can close with a recommendation, a targeted research follow-up, or a prototype/test plan. A design document is maintained throughout as the human-facing artifact.\n\n**When to use it:**\n- You face a decision, architectural question, or design problem with no obvious right answer\n- You want to explore an opportunity space before committing to a direction\n- You suspect the stated problem might not be the real problem\n- You need a structured recommendation with explicit tradeoffs and alternatives rather than the first plausible answer\n\n**What it produces:**\nA design document covering: the selected path and framing, landscape takeaways, chosen direction and why it won, the strongest alternative and why it lost, confidence band, residual risks, and next actions.\n\n**How to get good results:**\nDescribe the problem, opportunity, or decision you want help thinking through. State what outcome you want (a recommendation, a comparison, a research plan, a prototype direction). The more context you provide upfront about constraints and anti-goals, the sharper the framing will be.",
+  "examples": [
+    "Decide whether to build a custom notification system or adopt a third-party service",
+    "Explore what the right architecture is for moving our monolith to services",
+    "Think through how to reduce checkout abandonment when the root cause is unclear",
+    "Work out whether to stay at my current company or take the offer at the startup"
+  ],
   "recommendedPreferences": {
     "recommendedAutonomy": "guided",
     "recommendedRiskPolicy": "conservative"