@exaudeus/workrail 3.40.0 → 3.42.0

package/spec/shape.schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://workrail.dev/spec/shape.schema.json",
+  "$comment": "Future target: when wr.shaping produces structured output, this schema defines its shape. For now the workflow writes pitch.md only.",
+  "title": "WorkRail Shape",
+  "description": "Aspirational output schema for wr.shaping -- not yet produced by the workflow. Current output is pitch.md.",
+  "type": "object",
+  "required": ["shaping_run_id", "frame", "solution", "context_pack", "acceptance_criteria", "rabbit_holes", "no_gos", "assumptions_log", "decomposition", "pitch_md", "build_readiness_score"],
+  "additionalProperties": false,
+  "properties": {
+    "shaping_run_id": { "type": "string", "description": "UUID for this shaping run" },
+    "workflow_version": { "type": "string" },
+    "frame": {
+      "type": "object",
+      "required": ["problem_story_md", "appetite"],
+      "properties": {
+        "problem_story_md": { "type": "string", "minLength": 20, "description": "Specific story: When [person] [situation], they need [job], but today [what fails]" },
+        "appetite": {
+          "type": "object",
+          "required": ["sizing_bucket"],
+          "properties": {
+            "sizing_bucket": { "type": "string", "enum": ["xs", "s", "m", "l", "xl"] },
+            "calendar_days": { "type": "number" },
+            "token_budget_est": { "type": "number" },
+            "agent_turns_est": { "type": "number" },
+            "files_touched_est": { "type": "number" }
+          }
+        },
+        "forces": {
+          "type": "object",
+          "properties": {
+            "push": { "type": "array", "items": { "type": "string" } },
+            "pull": { "type": "array", "items": { "type": "string" } },
+            "anxiety": { "type": "array", "items": { "type": "string" } },
+            "habit": { "type": "array", "items": { "type": "string" } }
+          }
+        }
+      }
+    },
+    "solution": {
+      "type": "object",
+      "required": ["breadboard_md", "elements"],
+      "properties": {
+        "breadboard_md": { "type": "string" },
+        "elements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "description", "classification"],
+            "properties": {
+              "name": { "type": "string" },
+              "description": { "type": "string" },
+              "classification": { "type": "string", "enum": ["interface", "invariant", "exclusion"] }
+            }
+          }
+        },
+        "rationale_md": { "type": "string" },
+        "alternatives_considered": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "sketch": { "type": "string" },
+              "rejected_because": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "context_pack": {
+      "type": "object",
+      "required": ["touch_globs", "do_not_touch_globs"],
+      "properties": {
+        "touch_globs": { "type": "array", "items": { "type": "string" } },
+        "do_not_touch_globs": { "type": "array", "items": { "type": "string" } },
+        "reuse_utilities": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "symbol", "reason_to_reuse"],
+            "properties": {
+              "path": { "type": "string" },
+              "symbol": { "type": "string" },
+              "signature": { "type": "string" },
+              "reason_to_reuse": { "type": "string" }
+            }
+          }
+        },
+        "conventions_md": { "type": "string" },
+        "related_prior_art": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path_or_pr": { "type": "string" },
+              "relevance": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "acceptance_criteria": {
+      "type": "object",
+      "required": ["gherkin", "verification_commands"],
+      "properties": {
+        "gherkin": { "type": "string" },
+        "verification_commands": { "type": "array", "items": { "type": "string" } },
+        "example_map": { "type": "object" }
+      }
+    },
+    "rabbit_holes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["risk", "severity", "mitigation"],
+        "properties": {
+          "risk": { "type": "string" },
+          "severity": { "type": "string", "enum": ["low", "medium", "critical"] },
+          "mitigation": { "type": "string" },
+          "patch_applied": { "type": "boolean" }
+        }
+      }
+    },
+    "no_gos": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+    "assumptions_log": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "assumption", "confidence"],
+        "properties": {
+          "step": { "type": "string" },
+          "assumption": { "type": "string" },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "rationale": { "type": "string" }
+        }
+      }
+    },
+    "decomposition": {
+      "type": "object",
+      "required": ["walking_skeleton", "atomic_subtasks"],
+      "properties": {
+        "walking_skeleton": {
+          "type": "object",
+          "properties": {
+            "description": { "type": "string" },
+            "files": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "atomic_subtasks": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "required": ["id", "title"],
+            "properties": {
+              "id": { "type": "string" },
+              "title": { "type": "string" },
+              "depends_on": { "type": "array", "items": { "type": "string" } },
+              "est_context_window": { "type": "string" },
+              "acceptance_scenario_refs": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "pitch_md": { "type": "string", "minLength": 100 },
+    "pitch_structured": { "type": "object" },
+    "build_readiness_score": {
+      "type": "object",
+      "required": ["rubric_pass_count", "critical_blockers"],
+      "properties": {
+        "rubric_pass_count": { "type": "integer", "minimum": 0, "maximum": 5 },
+        "critical_blockers": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/spec/workflow-tags.json

@@ -10,7 +10,10 @@
         "refactoring or improving existing code",
         "converting code between platforms or languages"
       ],
-      "examples": ["coding-task-workflow-agentic", "cross-platform-code-conversion"]
+      "examples": [
+        "coding-task-workflow-agentic",
+        "cross-platform-code-conversion"
+      ]
     },
     {
       "id": "review_audit",
@@ -20,7 +23,10 @@
         "auditing a service for production readiness",
         "checking architecture for scalability issues"
       ],
-      "examples": ["mr-review-workflow-agentic", "production-readiness-audit"]
+      "examples": [
+        "mr-review-workflow-agentic",
+        "production-readiness-audit"
+      ]
     },
     {
       "id": "investigation",
@@ -29,7 +35,10 @@
         "diagnosing a bug or unexpected behavior in code",
         "diagnosing tool, environment, or MCP server issues"
       ],
-      "examples": ["bug-investigation-agentic", "workflow-diagnose-environment"]
+      "examples": [
+        "bug-investigation-agentic",
+        "workflow-diagnose-environment"
+      ]
     },
     {
       "id": "design",
@@ -37,9 +46,14 @@
       "when": [
         "designing a UI or UX feature from scratch",
         "exploring and thinking through a problem or decision",
-        "generating and comparing design candidates"
+        "generating and comparing design candidates",
+        "shaping a fuzzy problem into a bounded, implementation-ready pitch before coding begins"
       ],
-      "examples": ["ui-ux-design-workflow", "wr.discovery"]
+      "examples": [
+        "ui-ux-design-workflow",
+        "wr.discovery",
+        "wr.shaping"
+      ]
     },
     {
       "id": "documentation",
@@ -49,7 +63,10 @@
         "updating or maintaining existing documentation",
         "writing documentation for a single bounded component or concept"
       ],
-      "examples": ["document-creation-workflow", "documentation-update-workflow"]
+      "examples": [
+        "document-creation-workflow",
+        "documentation-update-workflow"
+      ]
     },
     {
       "id": "tickets",
@@ -59,7 +76,10 @@
         "grooming and refining a backlog",
         "generating test cases from ticket requirements"
       ],
-      "examples": ["adaptive-ticket-creation", "ticket-grooming"]
+      "examples": [
+        "adaptive-ticket-creation",
+        "ticket-grooming"
+      ]
     },
     {
       "id": "learning",
@@ -69,7 +89,10 @@
         "designing a presentation",
         "making a major personal decision like where to relocate"
       ],
-      "examples": ["personal-learning-materials-creation-branched", "presentation-creation"]
+      "examples": [
+        "personal-learning-materials-creation-branched",
+        "presentation-creation"
+      ]
     },
     {
       "id": "routines",
@@ -80,7 +103,10 @@
         "running a hypothesis challenge or adversarial review",
         "running a final verification pass"
       ],
-      "examples": ["routine-context-gathering", "routine-hypothesis-challenge"]
+      "examples": [
+        "routine-context-gathering",
+        "routine-hypothesis-challenge"
+      ]
     },
     {
       "id": "authoring",
@@ -89,45 +115,204 @@
         "creating a new WorkRail workflow from scratch",
         "modernizing or updating an existing workflow"
       ],
-      "examples": ["workflow-for-workflows"]
+      "examples": [
+        "workflow-for-workflows"
+      ]
     }
   ],
   "workflows": {
-    "adaptive-ticket-creation": { "tags": ["tickets"] },
-    "architecture-scalability-audit": { "tags": ["review_audit"] },
-    "bug-investigation-agentic": { "tags": ["investigation"] },
-    "coding-task-workflow-agentic": { "tags": ["coding"] },
-    "cross-platform-code-conversion": { "tags": ["coding"] },
-    "document-creation-workflow": { "tags": ["documentation"] },
-    "documentation-update-workflow": { "tags": ["documentation"] },
-    "intelligent-test-case-generation": { "tags": ["tickets", "coding"] },
-    "mr-review-workflow-agentic": { "tags": ["review_audit"] },
-    "personal-learning-course-design": { "tags": ["learning"] },
-    "personal-learning-materials-creation-branched": { "tags": ["learning"] },
-    "presentation-creation": { "tags": ["learning"] },
-    "production-readiness-audit": { "tags": ["review_audit"] },
-    "relocation-workflow-us": { "tags": ["learning"] },
-    "routine-context-gathering": { "tags": ["routines"] },
-    "routine-design-review": { "tags": ["routines"] },
-    "routine-execution-simulation": { "tags": ["routines"] },
-    "routine-feature-implementation": { "tags": ["routines", "coding"] },
-    "routine-final-verification": { "tags": ["routines"] },
-    "routine-hypothesis-challenge": { "tags": ["routines"] },
-    "routine-ideation": { "tags": ["routines"] },
-    "routine-parallel-work-partitioning": { "tags": ["routines"] },
-    "routine-philosophy-alignment": { "tags": ["routines"] },
-    "routine-plan-analysis": { "tags": ["routines"] },
-    "routine-plan-generation": { "tags": ["routines"] },
-    "routine-tension-driven-design": { "tags": ["routines"] },
-    "scoped-documentation-workflow": { "tags": ["documentation"] },
-    "ticket-grooming": { "tags": ["tickets"] },
-    "ui-ux-design-workflow": { "tags": ["design"] },
-    "workflow-diagnose-environment": { "tags": ["investigation"] },
-    "workflow-for-workflows": { "tags": ["authoring"] },
-    "wr.discovery": { "tags": ["design", "investigation"] },
-    "classify-task-workflow": { "tags": ["routines", "coding"] },
-    "test-artifact-loop-control": { "tags": ["coding"], "hidden": true },
-    "test-session-persistence": { "tags": ["coding"], "hidden": true },
-    "test-missing-context": { "tags": ["coding"], "hidden": true }
+    "adaptive-ticket-creation": {
+      "tags": [
+        "tickets"
+      ]
+    },
+    "architecture-scalability-audit": {
+      "tags": [
+        "review_audit"
+      ]
+    },
+    "bug-investigation-agentic": {
+      "tags": [
+        "investigation"
+      ]
+    },
+    "coding-task-workflow-agentic": {
+      "tags": [
+        "coding"
+      ]
+    },
+    "cross-platform-code-conversion": {
+      "tags": [
+        "coding"
+      ]
+    },
+    "document-creation-workflow": {
+      "tags": [
+        "documentation"
+      ]
+    },
+    "documentation-update-workflow": {
+      "tags": [
+        "documentation"
+      ]
+    },
+    "intelligent-test-case-generation": {
+      "tags": [
+        "tickets",
+        "coding"
+      ]
+    },
+    "mr-review-workflow-agentic": {
+      "tags": [
+        "review_audit"
+      ]
+    },
+    "personal-learning-course-design": {
+      "tags": [
+        "learning"
+      ]
+    },
+    "personal-learning-materials-creation-branched": {
+      "tags": [
+        "learning"
+      ]
+    },
+    "presentation-creation": {
+      "tags": [
+        "learning"
+      ]
+    },
+    "production-readiness-audit": {
+      "tags": [
+        "review_audit"
+      ]
+    },
+    "relocation-workflow-us": {
+      "tags": [
+        "learning"
+      ]
+    },
+    "routine-context-gathering": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-design-review": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-execution-simulation": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-feature-implementation": {
+      "tags": [
+        "routines",
+        "coding"
+      ]
+    },
+    "routine-final-verification": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-hypothesis-challenge": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-ideation": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-parallel-work-partitioning": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-philosophy-alignment": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-plan-analysis": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-plan-generation": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "routine-tension-driven-design": {
+      "tags": [
+        "routines"
+      ]
+    },
+    "scoped-documentation-workflow": {
+      "tags": [
+        "documentation"
+      ]
+    },
+    "ticket-grooming": {
+      "tags": [
+        "tickets"
+      ]
+    },
+    "ui-ux-design-workflow": {
+      "tags": [
+        "design"
+      ]
+    },
+    "workflow-diagnose-environment": {
+      "tags": [
+        "investigation"
+      ]
+    },
+    "workflow-for-workflows": {
+      "tags": [
+        "authoring"
+      ]
+    },
+    "wr.discovery": {
+      "tags": [
+        "design",
+        "investigation"
+      ]
+    },
+    "classify-task-workflow": {
+      "tags": [
+        "routines",
+        "coding"
+      ]
+    },
+    "test-artifact-loop-control": {
+      "tags": [
+        "coding"
+      ],
+      "hidden": true
+    },
+    "test-session-persistence": {
+      "tags": [
+        "coding"
+      ],
+      "hidden": true
+    },
+    "test-missing-context": {
+      "tags": [
+        "coding"
+      ],
+      "hidden": true
+    },
+    "wr.shaping": {
+      "tags": [
+        "design",
+        "tickets"
+      ]
+    }
   }
-}
+}