@exaudeus/workrail 1.17.1 → 2.1.0

package/README.md

@@ -31,8 +31,8 @@ to conclusions.
 WorkRail replaces the human effort of guiding an agent step-by-step.
 
 Instead of one system prompt that fades over time, WorkRail drip-feeds instructions through
-the [Model Context Protocol](https://modelcontextprotocol.org). The agent calls `workflow_next`,
-gets ONE step, completes it, calls again. Future steps stay hidden until previous ones are done.
+the [Model Context Protocol](https://modelcontextprotocol.org). The agent calls `start_workflow`,
+gets the first step, completes it, calls `continue_workflow`. Future steps stay hidden until previous ones are done.
 
 **The agent can't skip to implementation because it doesn't know those steps exist yet.**
 
@@ -44,7 +44,7 @@ You                      Agent                     WorkRail
  │  "Fix the auth bug"     │                          │
  │────────────────────────>│                          │
  │                         │                          │
- │                         │  workflow_next()         │
+ │                         │  start_workflow()        │
  │                         │─────────────────────────>│
  │                         │                          │
  │                         │   Step 1: Understand     │
@@ -55,7 +55,7 @@ You                      Agent                     WorkRail
  │    see exactly?"        │                          │
  │<────────────────────────│                          │
  │                         │                          │
- │         ...             │  workflow_next()         │
+ │         ...             │  continue_workflow()     │
  │                         │─────────────────────────>│
  │                         │                          │
  │                         │   Step 2: Plan your      │
@@ -81,21 +81,21 @@ Agent: "I see the issue! In auth.js line 42, there's a null check that
 You:   "There's a bug in the auth flow"
 
 Agent: "I'll use the bug-investigation workflow."
-        → workflow_next()
+        → start_workflow()
        
        Step 1: Investigation Setup
        "Before I investigate, I need to understand the problem.
         What exactly happens when it fails? Can you share the error?"
        
        [Documents bug, reproduction steps, environment]
-        → workflow_next()
+        → continue_workflow()
        
        Step 2: Plan Investigation
        "I'll trace execution from login through the auth middleware.
         Key areas: token validation, session lookup, error handling."
        
        [Creates investigation plan before touching code]
-        → workflow_next()
+        → continue_workflow()
        
        Step 3: Form Hypotheses
        "Based on my analysis, three possible causes:
@@ -164,13 +164,13 @@ The agent will find the workflow, start at step 1, and proceed systematically.
 
 ## Included Workflows
 
-20+ workflows included for development, debugging, review, documentation, and more:
+30+ workflows included for development, debugging, review, documentation, and more:
 
 | Workflow | When to Use |
 |----------|-------------|
-| `coding-task-workflow-with-loops` | Feature development with analysis, planning, and review |
-| `bug-investigation` | Systematic debugging with hypothesis testing |
-| `mr-review-workflow` | Code review with architecture and security checks |
+| `coding-task-workflow-agentic` | Feature development with notes-first durability and audit loops |
+| `bug-investigation-agentic` | Systematic debugging with evidence-based analysis |
+| `mr-review-workflow-agentic` | Code review with parallel reviewer families |
 | `exploration-workflow` | Understanding an unfamiliar codebase |
 | `document-creation-workflow` | Technical documentation with structure |
 

package/dist/application/use-cases/raw-workflow-file-scanner.d.ts

@@ -1,6 +1,6 @@
 import type { WorkflowDefinition } from '../../types/workflow-definition.js';
 export declare function findWorkflowJsonFiles(baseDirReal: string): Promise<string[]>;
-export type VariantKind = 'v2' | 'agentic' | 'standard';
+export type VariantKind = 'lean' | 'v2' | 'agentic' | 'standard';
 export interface ParsedRawWorkflowFile {
     readonly kind: 'parsed';
     readonly filePath: string;

package/dist/application/use-cases/raw-workflow-file-scanner.js

@@ -77,6 +77,8 @@ async function scanRawWorkflowFiles(baseDirReal) {
 }
 function detectVariantKind(relativeFilePath) {
     const normalized = relativeFilePath.replace(/\\/g, '/');
+    if (normalized.includes('.lean.'))
+        return 'lean';
     if (normalized.includes('.v2.'))
         return 'v2';
     if (normalized.includes('.agentic.'))

package/dist/application/use-cases/validate-workflow-registry.js

@@ -191,7 +191,7 @@ function deriveVariantResolutions(loadedWorkflows, allRawFiles, source) {
             const availableVariants = rawFilesForId.map(f => f.variantKind);
             const selectedRaw = rawFilesForId.find(f => f.definition.id === id);
             const selectedVariant = selectedRaw?.variantKind ?? 'standard';
-            if (selectedVariant === 'v2' || selectedVariant === 'agentic') {
+            if (selectedVariant === 'lean' || selectedVariant === 'v2' || selectedVariant === 'agentic') {
                 result.set(id, {
                     kind: 'feature_flag_selected',
                     selectedVariant,
@@ -199,6 +199,7 @@ function deriveVariantResolutions(loadedWorkflows, allRawFiles, source) {
                     enabledFlags: {
                         v2Tools: selectedVariant === 'v2',
                         agenticRoutines: selectedVariant === 'agentic',
+                        leanWorkflows: selectedVariant === 'lean',
                     },
                 });
             }

package/dist/config/feature-flags.js

@@ -45,6 +45,14 @@ exports.FEATURE_FLAG_DEFINITIONS = [
         since: '0.8.3',
         stable: false,
     },
+    {
+        key: 'leanWorkflows',
+        envVar: 'WORKRAIL_ENABLE_LEAN_WORKFLOWS',
+        defaultValue: false,
+        description: 'Enable lean workflow variants (.lean.) that merge phases and reduce token usage while preserving quality',
+        since: '0.10.0',
+        stable: false,
+    },
     {
         key: 'authoritativeDescriptions',
         envVar: 'WORKRAIL_AUTHORITATIVE_DESCRIPTIONS',
@@ -56,10 +64,10 @@ exports.FEATURE_FLAG_DEFINITIONS = [
     {
         key: 'v2Tools',
         envVar: 'WORKRAIL_ENABLE_V2_TOOLS',
-        defaultValue: false,
-        description: 'Enable WorkRail v2 MCP tools and .v2.json workflow overrides behind an explicit opt-in flag',
+        defaultValue: true,
+        description: 'WorkRail v2 MCP tools (list_workflows, start_workflow, continue_workflow, checkpoint_workflow, resume_session) and .v2.json workflow overrides',
         since: '0.9.0',
-        stable: false,
+        stable: true,
     },
 ];
 function parseBoolean(value, defaultValue) {

package/dist/infrastructure/storage/file-workflow-storage.js

@@ -55,6 +55,9 @@ class FileWorkflowStorage {
                         continue;
                     }
                 }
+                if (!this.featureFlags.isEnabled('leanWorkflows') && file.includes('.lean.')) {
+                    continue;
+                }
                 if (!this.featureFlags.isEnabled('v2Tools') && file.includes('.v2.')) {
                     continue;
                 }
@@ -78,12 +81,14 @@ class FileWorkflowStorage {
         const flags = {
             v2Tools: this.featureFlags.isEnabled('v2Tools'),
             agenticRoutines: this.featureFlags.isEnabled('agenticRoutines'),
+            leanWorkflows: this.featureFlags.isEnabled('leanWorkflows'),
         };
         for (const [id, files] of idToFiles) {
             const candidates = files.map(f => ({
-                variantKind: f.file.includes('.v2.') ? 'v2'
-                    : f.file.includes('.agentic.') ? 'agentic'
-                        : 'standard',
+                variantKind: f.file.includes('.lean.') ? 'lean'
+                    : f.file.includes('.v2.') ? 'v2'
+                        : f.file.includes('.agentic.') ? 'agentic'
+                            : 'standard',
                 identifier: f.file,
             }));
             const selection = (0, workflow_resolution_1.selectVariant)(candidates, flags);

package/dist/infrastructure/storage/workflow-resolution.d.ts

@@ -1,19 +1,21 @@
 import type { Workflow } from '../../types/workflow.js';
 export type SourceRef = number;
+export type VariantKind = 'lean' | 'v2' | 'agentic' | 'standard';
 export type VariantResolution = {
     readonly kind: 'only_variant';
 } | {
     readonly kind: 'feature_flag_selected';
-    readonly selectedVariant: 'v2' | 'agentic' | 'standard';
-    readonly availableVariants: readonly ('v2' | 'agentic' | 'standard')[];
+    readonly selectedVariant: VariantKind;
+    readonly availableVariants: readonly VariantKind[];
     readonly enabledFlags: {
         readonly v2Tools: boolean;
         readonly agenticRoutines: boolean;
+        readonly leanWorkflows: boolean;
     };
 } | {
     readonly kind: 'precedence_fallback';
-    readonly selectedVariant: 'v2' | 'agentic' | 'standard';
-    readonly availableVariants: readonly ('v2' | 'agentic' | 'standard')[];
+    readonly selectedVariant: VariantKind;
+    readonly availableVariants: readonly VariantKind[];
 };
 export type ResolutionReason = {
     readonly kind: 'unique';
@@ -39,15 +41,16 @@ export declare function resolveWorkflowCandidates(candidates: readonly {
     readonly workflows: readonly Workflow[];
 }[], variantResolutions: ReadonlyMap<string, ReadonlyMap<SourceRef, VariantResolution>>): readonly ResolvedWorkflow[];
 export interface VariantCandidate {
-    readonly variantKind: 'v2' | 'agentic' | 'standard';
+    readonly variantKind: VariantKind;
     readonly identifier: string;
 }
 export interface VariantSelectionFlags {
     readonly v2Tools: boolean;
     readonly agenticRoutines: boolean;
+    readonly leanWorkflows: boolean;
 }
 export interface VariantSelectionResult {
-    readonly selectedVariant: 'v2' | 'agentic' | 'standard';
+    readonly selectedVariant: VariantKind;
     readonly selectedIdentifier: string;
     readonly resolution: VariantResolution;
 }

package/dist/infrastructure/storage/workflow-resolution.js

@@ -79,9 +79,22 @@ function selectVariant(candidates, flags) {
         };
     }
     const availableVariants = candidates.map(c => c.variantKind);
+    const leanCandidate = candidates.find(c => c.variantKind === 'lean');
     const v2Candidate = candidates.find(c => c.variantKind === 'v2');
     const agenticCandidate = candidates.find(c => c.variantKind === 'agentic');
     const standardCandidate = candidates.find(c => c.variantKind === 'standard');
+    if (flags.leanWorkflows && leanCandidate) {
+        return {
+            selectedVariant: 'lean',
+            selectedIdentifier: leanCandidate.identifier,
+            resolution: {
+                kind: 'feature_flag_selected',
+                selectedVariant: 'lean',
+                availableVariants,
+                enabledFlags: flags,
+            },
+        };
+    }
     if (flags.v2Tools && v2Candidate) {
         return {
             selectedVariant: 'v2',
@@ -117,7 +130,7 @@ function selectVariant(candidates, flags) {
             },
         };
     }
-    const fallback = v2Candidate ?? agenticCandidate ?? candidates[0];
+    const fallback = leanCandidate ?? v2Candidate ?? agenticCandidate ?? candidates[0];
     return {
         selectedVariant: fallback.variantKind,
         selectedIdentifier: fallback.identifier,

package/dist/manifest.json

@@ -154,12 +154,12 @@
       "bytes": 374
     },
     "application/use-cases/raw-workflow-file-scanner.d.ts": {
-      "sha256": "6ddfdcc57820ae745ff6c0a9d4fa2079d7ff19442758674da2e60bf08a398d59",
-      "bytes": 805
+      "sha256": "c9b699b4a011b968d389662430ff9bf32d4ce3fcda5cc5ddc99b08f2e69697df",
+      "bytes": 814
     },
     "application/use-cases/raw-workflow-file-scanner.js": {
-      "sha256": "be0b6e552d76da3da1de67737b23ab33e510a0e418c80a77645398ebead5eeee",
-      "bytes": 3272
+      "sha256": "25b2e07a39f67734287b35887326234f5b8b8e1e0c65792513dad2dd8d73a0e0",
+      "bytes": 3334
     },
     "application/use-cases/validate-step-output.d.ts": {
       "sha256": "d1505a7f507da6bbf59515c734dace381ac1a96d98f4495e469f9e3ad9c75941",
@@ -190,8 +190,8 @@
       "bytes": 3107
     },
     "application/use-cases/validate-workflow-registry.js": {
-      "sha256": "b17995afe2408f8a3a98ea6553a12ab768a4a1e547cef0165748daaac7a27981",
-      "bytes": 8851
+      "sha256": "5f0c40d6539abe4a5f4b7bb66c56d032b7e42f28eb5ae6444adb9b03593d891f",
+      "bytes": 8948
     },
     "application/validation.d.ts": {
       "sha256": "c7b6485357e0085fbdefca553ef78e570bf8448b272c62f1ddd4a2f9b45b2982",
@@ -326,8 +326,8 @@
       "bytes": 1512
     },
     "config/feature-flags.js": {
-      "sha256": "c7c5a4db2a0d5f86a9cf91c9a7e2c74f89ce7f1012b93c8237a3d70a783d2b45",
-      "bytes": 6908
+      "sha256": "b42066c19fce793fe7bafb1ecb264d05c8e453fff32263f9e8cbcea7e59ddc6b",
+      "bytes": 7256
     },
     "core/error-handler.d.ts": {
       "sha256": "80451f12ac8e185133ec3dc4c57285491a785f27525ed21e729db1da3f61010d",
@@ -526,8 +526,8 @@
       "bytes": 1428
     },
     "infrastructure/storage/file-workflow-storage.js": {
-      "sha256": "3dfbbf4e3bb5255938da543bda07b5a8b9e41f73a5b0d364e2cab16f92b04de7",
-      "bytes": 8280
+      "sha256": "e5cfd6f8a7fed72961e041aa9c92765c28f4b9872c16e7cbdbd533f0177ea0f0",
+      "bytes": 8562
     },
     "infrastructure/storage/git-workflow-storage.d.ts": {
       "sha256": "67d7f10e12c78c674ced83da378cd159465d4b09176d8dfca240864b0d6f38c2",
@@ -586,12 +586,12 @@
       "bytes": 3014
     },
     "infrastructure/storage/workflow-resolution.d.ts": {
-      "sha256": "4866dfa9659fdd9c8c6383d27d8ac43e0214fb0ff65a468f3d88becd907dee91",
-      "bytes": 2357
+      "sha256": "81929a188f570488a83cbc387aa32734dbb1fadaae8589c48ff9aa1ea3a6dad5",
+      "bytes": 2389
     },
     "infrastructure/storage/workflow-resolution.js": {
-      "sha256": "04eeed7fe7f8a627272805b668d262c27c1295c4794c47b843a11fb419d2bb37",
-      "bytes": 5565
+      "sha256": "202c244209088acb15f1b0556c569607086e1cb71cf7faa77fbae902d682dfd2",
+      "bytes": 6034
     },
     "mcp-server.d.ts": {
       "sha256": "d673b4cf9770aa74de28e921e964459c094bdb89a8970623afda340fe1707293",
@@ -625,6 +625,14 @@
       "sha256": "83c9585400cc7c20cac3691b8771b9ce8cdc508ba7f5d083a96f7ed975aabc05",
       "bytes": 5967
     },
+    "mcp/handlers/shared/request-workflow-reader.d.ts": {
+      "sha256": "39b3db1251f5db4da36a14a1b3dba76bdd0cefd5b24637e03307901a3994a12b",
+      "bytes": 927
+    },
+    "mcp/handlers/shared/request-workflow-reader.js": {
+      "sha256": "8e67f92fe93883e6620b4564a1c98c5402ac74f002049b8f8f136008778e2152",
+      "bytes": 2297
+    },
     "mcp/handlers/shared/with-timeout.d.ts": {
       "sha256": "31ca3db008cb5cd439e0d1132bc4b29be0900c403c452931e3a24a50e45beb54",
       "bytes": 117
@@ -770,12 +778,12 @@
       "bytes": 12661
     },
     "mcp/handlers/v2-execution/start.d.ts": {
-      "sha256": "333f9f36756d2ce55249c6af45198a17b51aa9c6448e063f7621fcd61879f2bf",
-      "bytes": 2684
+      "sha256": "15d5e5f4a4613df286279075640e43a130179f39b9157b50d4d9e4123bcae6b3",
+      "bytes": 2868
     },
     "mcp/handlers/v2-execution/start.js": {
-      "sha256": "0c6800d22f93a36b45236d17993b445de131e00a72eac8dbd98e2f4d8d9f2b29",
-      "bytes": 15208
+      "sha256": "cb40e5ec1d1461f41ce88722110af9f11396ab1d828d6eccb0b1b29a9ca68b65",
+      "bytes": 16769
     },
     "mcp/handlers/v2-resume.d.ts": {
       "sha256": "d88f6c35bcaf946666c837b72fda3702a2ebab5e478eb90f7b4b672a0e5fa24f",
@@ -802,12 +810,12 @@
       "bytes": 3817
     },
     "mcp/handlers/v2-workflow.d.ts": {
-      "sha256": "9fbd4d44854e2060c54982b21e72c608970bb2bd107bb15a8388b26c6b492e55",
-      "bytes": 397
+      "sha256": "5c9590f121dd3708c516be3febe41d0be47531d643462b86b99b778ef0b54498",
+      "bytes": 396
     },
     "mcp/handlers/v2-workflow.js": {
-      "sha256": "bed0ffc401958c14343158e142e4be344bad49cabc95f99a811d872bc76989a7",
-      "bytes": 6027
+      "sha256": "e869550933484b473ee51e4f66b29324c17213b87f3fc8bbb3e098ffc00d6f88",
+      "bytes": 7034
     },
     "mcp/handlers/v2-workspace-resolution.d.ts": {
       "sha256": "45cdf30b7989d16201b4569c6c109e9ccea04c76fd044af1471fe57faa49da3a",
@@ -846,8 +854,8 @@
       "bytes": 882
     },
     "mcp/server.js": {
-      "sha256": "5086b482d2eb3c42caac637282a5361b4db6e5d14aaeeb7c5ffdf75d211af0d8",
-      "bytes": 13422
+      "sha256": "c07f8a6e8f89f7620a063673859dcc458212b068237949acff253f15856afd5f",
+      "bytes": 14174
     },
     "mcp/tool-description-provider.d.ts": {
       "sha256": "1d46abc3112e11b68e57197e846f5708293ec9b2281fa71a9124ee2aad71e41b",
@@ -862,8 +870,8 @@
       "bytes": 132
     },
     "mcp/tool-descriptions.js": {
-      "sha256": "b689f4b8d83398a9ee7cf8ff5b36536bccd458b65040e801de3693937dc4aab6",
-      "bytes": 17639
+      "sha256": "854176e258cdc25d6067836157a03682b6c8843bc8fd7b447fef96b4bb4cba6d",
+      "bytes": 18124
     },
     "mcp/tool-factory.d.ts": {
       "sha256": "0fe3c6b863b2d7aef0c3d659ff54f3a9ee8a0a3c2005b6565d2f8ad517bc7211",
@@ -914,8 +922,8 @@
       "bytes": 747
     },
     "mcp/types.d.ts": {
-      "sha256": "2ef7f9c1bffbe365b06469dfad43b45c4ae3b5292dd269b33423bf1c8c9c7c43",
-      "bytes": 4355
+      "sha256": "d61a7d2b9a5f389d9fbf0092f6d38c3e6bb2925f41dce0270ed0c2e54ca856c9",
+      "bytes": 4533
     },
     "mcp/types.js": {
       "sha256": "d10c4070e4c3454d80f0fa9cdc0e978c69c53c13fd09baa8710fcd802fed8926",
@@ -962,12 +970,12 @@
       "bytes": 3119
     },
     "mcp/v2/tools.d.ts": {
-      "sha256": "f789303c98e8b3d53c9b8c22b0cf99548c54907cfde3c5c67ca4036fab7d156c",
-      "bytes": 6567
+      "sha256": "9915bd42c9ab096875021a24c0c97ad112331595e5d734abdd2856f9f49f80e4",
+      "bytes": 6884
     },
     "mcp/v2/tools.js": {
-      "sha256": "8534b0a7c08877b30022914f32b2e7b739aca4112f55762a56c89599df7fa3dd",
-      "bytes": 7875
+      "sha256": "e3755649cb0fbf6332a7f330dec558bf998489533c95d7684c4668a4c566896e",
+      "bytes": 8360
     },
     "mcp/validation/bounded-json.d.ts": {
       "sha256": "82203ac6123d5c6989606c3b5405aaea99ab829c8958835f9ae3ba45b8bc8fd5",

package/dist/mcp/handlers/shared/request-workflow-reader.d.ts

@@ -0,0 +1,19 @@
+import type { IWorkflowReader } from '../../../types/storage.js';
+import type { IFeatureFlagProvider } from '../../../config/feature-flags.js';
+export interface RequestWorkflowReaderOptions {
+    readonly featureFlags: IFeatureFlagProvider;
+    readonly workspacePath?: string;
+    readonly resolvedRootUris?: readonly string[];
+    readonly serverCwd?: string;
+}
+export declare function hasRequestWorkspaceSignal(options: {
+    readonly workspacePath?: string;
+    readonly resolvedRootUris?: readonly string[];
+}): boolean;
+export declare function resolveRequestWorkspaceDirectory(options: {
+    readonly workspacePath?: string;
+    readonly resolvedRootUris?: readonly string[];
+    readonly serverCwd?: string;
+}): string;
+export declare function toProjectWorkflowDirectory(workspaceDirectory: string): string;
+export declare function createWorkflowReaderForRequest(options: RequestWorkflowReaderOptions): IWorkflowReader;

package/dist/mcp/handlers/shared/request-workflow-reader.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasRequestWorkspaceSignal = hasRequestWorkspaceSignal;
+exports.resolveRequestWorkspaceDirectory = resolveRequestWorkspaceDirectory;
+exports.toProjectWorkflowDirectory = toProjectWorkflowDirectory;
+exports.createWorkflowReaderForRequest = createWorkflowReaderForRequest;
+const path_1 = __importDefault(require("path"));
+const url_1 = require("url");
+const enhanced_multi_source_workflow_storage_js_1 = require("../../../infrastructure/storage/enhanced-multi-source-workflow-storage.js");
+const schema_validating_workflow_storage_js_1 = require("../../../infrastructure/storage/schema-validating-workflow-storage.js");
+function hasRequestWorkspaceSignal(options) {
+    return Boolean(options.workspacePath) || (options.resolvedRootUris?.length ?? 0) > 0;
+}
+function resolveRequestWorkspaceDirectory(options) {
+    if (options.workspacePath && path_1.default.isAbsolute(options.workspacePath)) {
+        return options.workspacePath;
+    }
+    const rootUri = options.resolvedRootUris?.[0];
+    if (rootUri) {
+        const fsPath = fileUriToFsPath(rootUri);
+        if (fsPath) {
+            return fsPath;
+        }
+    }
+    return options.serverCwd ?? process.cwd();
+}
+function toProjectWorkflowDirectory(workspaceDirectory) {
+    return path_1.default.basename(workspaceDirectory) === 'workflows'
+        ? workspaceDirectory
+        : path_1.default.join(workspaceDirectory, 'workflows');
+}
+function createWorkflowReaderForRequest(options) {
+    const workspaceDirectory = resolveRequestWorkspaceDirectory(options);
+    const projectWorkflowDirectory = toProjectWorkflowDirectory(workspaceDirectory);
+    const storage = new enhanced_multi_source_workflow_storage_js_1.EnhancedMultiSourceWorkflowStorage({ projectPath: projectWorkflowDirectory }, options.featureFlags);
+    return new schema_validating_workflow_storage_js_1.SchemaValidatingCompositeWorkflowStorage(storage);
+}
+function fileUriToFsPath(uri) {
+    if (!uri.startsWith('file://'))
+        return null;
+    try {
+        return (0, url_1.fileURLToPath)(uri);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/mcp/handlers/v2-execution/start.d.ts

@@ -6,14 +6,16 @@ import { type SessionId, type RunId, type NodeId, type WorkflowHash } from '../.
 import type { Sha256PortV2 } from '../../../v2/ports/sha256.port.js';
 import type { TokenCodecPorts } from '../../../v2/durable-core/tokens/token-codec-ports.js';
 import { ResultAsync as RA } from 'neverthrow';
+import { type ValidationPipelineDepsPhase1a } from '../../../application/services/workflow-validation-pipeline.js';
 import { type ObservationEventData } from '../../../v2/durable-core/domain/observation-builder.js';
 import { type StartWorkflowError } from '../v2-execution-helpers.js';
 import * as z from 'zod';
 export declare function loadAndPinWorkflow(args: {
     readonly workflowId: string;
-    readonly workflowService: import('../../../application/services/workflow-service.js').WorkflowService;
+    readonly workflowReader: Pick<import('../../../types/storage.js').IWorkflowReader, 'getWorkflowById'>;
     readonly crypto: Sha256PortV2;
     readonly pinnedStore: import('../../../v2/ports/pinned-workflow-store.port.js').PinnedWorkflowStorePortV2;
+    readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
 }): RA<{
     readonly workflow: import('../../../types/workflow.js').Workflow;
     readonly workflowHash: WorkflowHash;

package/dist/mcp/handlers/v2-execution/start.js

@@ -10,7 +10,7 @@ const workflow_js_1 = require("../../../types/workflow.js");
 const index_js_1 = require("../../../v2/durable-core/ids/index.js");
 const workflow_hash_ref_js_1 = require("../../../v2/durable-core/ids/workflow-hash-ref.js");
 const neverthrow_1 = require("neverthrow");
-const v1_to_v2_shim_js_1 = require("../../../v2/read-only/v1-to-v2-shim.js");
+const workflow_validation_pipeline_js_1 = require("../../../application/services/workflow-validation-pipeline.js");
 const hashing_js_1 = require("../../../v2/durable-core/canonical/hashing.js");
 const observation_builder_js_1 = require("../../../v2/durable-core/domain/observation-builder.js");
 const workflow_source_js_1 = require("../../../types/workflow-source.js");
@@ -23,9 +23,10 @@ const v2_execution_helpers_js_1 = require("../v2-execution-helpers.js");
 const constants_js_1 = require("../../../v2/durable-core/constants.js");
 const index_js_2 = require("./index.js");
 const start_construction_js_1 = require("../../../v2/durable-core/domain/start-construction.js");
+const request_workflow_reader_js_1 = require("../shared/request-workflow-reader.js");
 function loadAndPinWorkflow(args) {
-    const { workflowId, workflowService, crypto, pinnedStore } = args;
-    return neverthrow_1.ResultAsync.fromPromise(workflowService.getWorkflowById(workflowId), (e) => ({
+    const { workflowId, workflowReader, crypto, pinnedStore, validationPipelineDeps } = args;
+    return neverthrow_1.ResultAsync.fromPromise(workflowReader.getWorkflowById(workflowId), (e) => ({
         kind: 'precondition_failed',
         message: e instanceof Error ? e.message : String(e),
     }))
@@ -39,14 +40,25 @@ function loadAndPinWorkflow(args) {
         return (0, neverthrow_1.okAsync)({ workflow });
     })
         .andThen(({ workflow }) => {
-        const normalizeResult = (0, v1_to_v2_shim_js_1.normalizeV1WorkflowToPinnedSnapshot)(workflow);
-        if (normalizeResult.isErr()) {
+        const pipelineOutcome = (0, workflow_validation_pipeline_js_1.validateWorkflowPhase1a)(workflow, validationPipelineDeps);
+        if (pipelineOutcome.kind !== 'phase1a_valid') {
+            const message = pipelineOutcome.kind === 'schema_failed'
+                ? `Schema validation failed: ${pipelineOutcome.errors.map(e => e.message ?? e.instancePath).join('; ')}`
+                : pipelineOutcome.kind === 'structural_failed'
+                    ? `Structural validation failed: ${pipelineOutcome.issues.join('; ')}`
+                    : pipelineOutcome.kind === 'v1_compilation_failed'
+                        ? `Compilation failed: ${pipelineOutcome.cause.message}`
+                        : pipelineOutcome.kind === 'normalization_failed'
+                            ? `Normalization failed: ${pipelineOutcome.cause.message}`
+                            : pipelineOutcome.kind === 'executable_compilation_failed'
+                                ? `Executable compilation failed: ${pipelineOutcome.cause.message}`
+                                : 'Unknown validation failure';
             return (0, neverthrow_1.errAsync)({
                 kind: 'workflow_compile_failed',
-                message: normalizeResult.error.message,
+                message,
             });
         }
-        const compiled = normalizeResult.value;
+        const compiled = pipelineOutcome.snapshot;
         const workflowHashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(compiled, crypto);
         if (workflowHashRes.isErr()) {
             return (0, neverthrow_1.errAsync)({ kind: 'hash_computation_failed', message: workflowHashRes.error.message });
@@ -215,12 +227,23 @@ function mintStartTokens(args) {
     });
 }
 function executeStartWorkflow(input, ctx) {
-    const { gate, sessionStore, snapshotStore, pinnedStore, crypto, tokenCodecPorts, idFactory } = ctx.v2;
+    const { gate, sessionStore, snapshotStore, pinnedStore, crypto, tokenCodecPorts, idFactory, validationPipelineDeps } = ctx.v2;
+    const workflowReader = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
+        workspacePath: input.workspacePath,
+        resolvedRootUris: ctx.v2.resolvedRootUris,
+    })
+        ? (0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
+            featureFlags: ctx.featureFlags,
+            workspacePath: input.workspacePath,
+            resolvedRootUris: ctx.v2.resolvedRootUris,
+        })
+        : ctx.workflowService;
     return loadAndPinWorkflow({
         workflowId: input.workflowId,
-        workflowService: ctx.workflowService,
+        workflowReader,
         crypto,
         pinnedStore,
+        validationPipelineDeps,
     })
         .andThen(({ workflow, firstStep, workflowHash, pinnedWorkflow }) => {
         const anchorsRA = (0, v2_workspace_resolution_js_1.resolveWorkspaceAnchors)(ctx.v2, input.workspacePath)

package/dist/mcp/handlers/v2-workflow.d.ts

@@ -1,4 +1,4 @@
 import type { ToolContext, ToolResult } from '../types.js';
 import type { V2InspectWorkflowInput, V2ListWorkflowsInput } from '../v2/tools.js';
-export declare function handleV2ListWorkflows(_input: V2ListWorkflowsInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
+export declare function handleV2ListWorkflows(input: V2ListWorkflowsInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
 export declare function handleV2InspectWorkflow(input: V2InspectWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;

package/dist/mcp/handlers/v2-workflow.js

@@ -11,13 +11,24 @@ const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const TIMEOUT_MS = 30000;
 const with_timeout_js_1 = require("./shared/with-timeout.js");
-async function handleV2ListWorkflows(_input, ctx) {
+const request_workflow_reader_js_1 = require("./shared/request-workflow-reader.js");
+async function handleV2ListWorkflows(input, ctx) {
     const guard = (0, types_js_1.requireV2Context)(ctx);
     if (!guard.ok)
         return guard.error;
     const { crypto, pinnedStore } = guard.ctx.v2;
-    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(ctx.workflowService.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
-        .andThen((summaries) => neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(ctx.workflowService.getWorkflowById(s.id), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).andThen((wf) => {
+    const workflowReader = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
+        workspacePath: input.workspacePath,
+        resolvedRootUris: guard.ctx.v2.resolvedRootUris,
+    })
+        ? (0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
+            featureFlags: ctx.featureFlags,
+            workspacePath: input.workspacePath,
+            resolvedRootUris: guard.ctx.v2.resolvedRootUris,
+        })
+        : ctx.workflowService;
+    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
+        .andThen((summaries) => neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(workflowReader.getWorkflowById(s.id), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).andThen((wf) => {
         if (!wf) {
             return (0, neverthrow_1.okAsync)({
                 workflowId: s.id,
@@ -79,7 +90,17 @@ async function handleV2InspectWorkflow(input, ctx) {
     if (!guard.ok)
         return guard.error;
     const { crypto, pinnedStore } = guard.ctx.v2;
-    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(ctx.workflowService.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
+    const workflowReader = (0, request_workflow_reader_js_1.hasRequestWorkspaceSignal)({
+        workspacePath: input.workspacePath,
+        resolvedRootUris: guard.ctx.v2.resolvedRootUris,
+    })
+        ? (0, request_workflow_reader_js_1.createWorkflowReaderForRequest)({
+            featureFlags: ctx.featureFlags,
+            workspacePath: input.workspacePath,
+            resolvedRootUris: guard.ctx.v2.resolvedRootUris,
+        })
+        : ctx.workflowService;
+    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
         .andThen((workflow) => {
         if (!workflow) {
             return (0, neverthrow_1.errAsync)((0, types_js_1.errNotRetryable)('NOT_FOUND', `Workflow not found: ${input.workflowId}`));

package/dist/mcp/server.js

@@ -41,6 +41,8 @@ const container_js_1 = require("../di/container.js");
 const tokens_js_1 = require("../di/tokens.js");
 const assert_never_js_1 = require("../runtime/assert-never.js");
 const token_codec_ports_js_1 = require("../v2/durable-core/tokens/token-codec-ports.js");
+const validation_js_1 = require("../application/validation.js");
+const v1_to_v2_shim_js_1 = require("../v2/read-only/v1-to-v2-shim.js");
 const index_js_1 = require("../v2/infra/local/workspace-anchor/index.js");
 const workspace_roots_manager_js_1 = require("./workspace-roots-manager.js");
 const index_js_2 = require("../v2/infra/local/directory-listing/index.js");
@@ -94,6 +96,14 @@ async function createToolContext() {
             const dataDir = container_js_1.container.resolve(tokens_js_1.DI.V2.DataDir);
             const fsPort = container_js_1.container.resolve(tokens_js_1.DI.V2.FileSystem);
             const directoryListing = new index_js_2.LocalDirectoryListingV2(fsPort);
+            const validationEngine = container_js_1.container.resolve(tokens_js_1.DI.Infra.ValidationEngine);
+            const compiler = container_js_1.container.resolve(tokens_js_1.DI.Services.WorkflowCompiler);
+            const validationPipelineDeps = {
+                schemaValidate: validation_js_1.validateWorkflowSchema,
+                structuralValidate: validationEngine.validateWorkflowStructureOnly.bind(validationEngine),
+                compiler,
+                normalizeToExecutable: v1_to_v2_shim_js_1.normalizeV1WorkflowToPinnedSnapshot,
+            };
             v2 = {
                 gate,
                 sessionStore,
@@ -103,6 +113,7 @@ async function createToolContext() {
                 crypto,
                 idFactory,
                 tokenCodecPorts,
+                validationPipelineDeps,
                 resolvedRootUris: [],
                 workspaceResolver: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),
                 dataDir,

package/dist/mcp/tool-descriptions.js

@@ -49,7 +49,9 @@ This tool provides:
 - Schema version and metadata information`,
         list_workflows: `Lists available workflows using WorkRail v2 (feature-flagged). Returns workflow metadata plus pinned snapshot hashes for deterministic execution.
 
-Use this to discover workflows before attempting multi-step tasks. When a workflow exists for the user's request, following it means following the user's structured instructions.`,
+Use this to discover workflows before attempting multi-step tasks. When a workflow exists for the user's request, following it means following the user's structured instructions.
+
+Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace instead of the server's fallback directory.`,
         inspect_workflow: `Inspect a workflow structure before starting it (WorkRail v2, feature-flagged).
 
 Use this to understand what steps the workflow will guide you through. The workflow is a step-by-step plan the user (or workflow author) created for this type of task.
@@ -58,6 +60,8 @@ Returns:
 - metadata mode: Just name and description
 - preview mode: Full step-by-step breakdown (default)
 
+Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace.
+
 Remember: inspecting is read-only. Call start_workflow when ready to begin.`,
         start_workflow: `Begin following a workflow's step-by-step instructions (WorkRail v2, feature-flagged).
 
@@ -192,7 +196,9 @@ Returns the complete schema definition including required fields, valid patterns
 
 Workflows are the user's pre-defined instructions for complex tasks. When a workflow exists for the user's request, you MUST use it instead of improvising your own approach.
 
-Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.`,
+Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.
+
+Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace.`,
         inspect_workflow: `Inspect a workflow you are considering following (WorkRail v2, feature-flagged).
 
 Use this to understand the workflow's structure before starting. The workflow is the user's explicit plan - not suggestions, not guidelines, but direct instructions you will follow.
@@ -200,6 +206,7 @@ Use this to understand the workflow's structure before starting. The workflow is
 Parameters:
 - workflowId: The workflow to inspect
 - mode: 'metadata' (name/description only) or 'preview' (full step breakdown)
+- workspacePath: optional absolute workspace path for correct project-scoped workflow resolution
 
 This is read-only. Call start_workflow when ready to commit to following the workflow.`,
         start_workflow: `Begin executing the user's workflow instructions (WorkRail v2, feature-flagged).

package/dist/mcp/types.d.ts

@@ -16,6 +16,7 @@ import type { WorkspaceContextResolverPortV2 } from '../v2/ports/workspace-ancho
 import type { DataDirPortV2 } from '../v2/ports/data-dir.port.js';
 import type { DirectoryListingPortV2 } from '../v2/ports/directory-listing.port.js';
 import type { SessionSummaryProviderPortV2 } from '../v2/ports/session-summary-provider.port.js';
+import type { ValidationPipelineDepsPhase1a } from '../application/services/workflow-validation-pipeline.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -55,6 +56,7 @@ export interface V2Dependencies {
     readonly crypto: CryptoPortV2;
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
+    readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
     readonly resolvedRootUris?: readonly string[];
     readonly workspaceResolver?: WorkspaceContextResolverPortV2;
     readonly dataDir?: DataDirPortV2;

package/dist/mcp/v2/tools.d.ts

@@ -1,16 +1,25 @@
 import { z } from 'zod';
 import type { ToolAnnotations } from '../tool-factory.js';
-export declare const V2ListWorkflowsInput: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const V2ListWorkflowsInput: z.ZodObject<{
+    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "strip", z.ZodTypeAny, {
+    workspacePath?: string | undefined;
+}, {
+    workspacePath?: string | undefined;
+}>;
 export type V2ListWorkflowsInput = z.infer<typeof V2ListWorkflowsInput>;
 export declare const V2InspectWorkflowInput: z.ZodObject<{
     workflowId: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<["metadata", "preview"]>>;
+    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
     mode: "metadata" | "preview";
+    workspacePath?: string | undefined;
 }, {
     workflowId: string;
     mode?: "metadata" | "preview" | undefined;
+    workspacePath?: string | undefined;
 }>;
 export type V2InspectWorkflowInput = z.infer<typeof V2InspectWorkflowInput>;
 export declare const V2StartWorkflowInput: z.ZodObject<{

package/dist/mcp/v2/tools.js

@@ -2,17 +2,21 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ResumeSessionInput = exports.V2ContinueWorkflowInput = exports.V2ContinueWorkflowInputShape = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
 const zod_1 = require("zod");
-exports.V2ListWorkflowsInput = zod_1.z.object({});
+const workspacePathField = zod_1.z.string()
+    .refine((p) => p.startsWith('/'), 'workspacePath must be an absolute path (starting with /)')
+    .optional()
+    .describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve project-scoped workflow variants against the correct workspace. If omitted, WorkRail uses MCP roots when available, then falls back to the server process directory.');
+exports.V2ListWorkflowsInput = zod_1.z.object({
+    workspacePath: workspacePathField,
+});
 exports.V2InspectWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level: metadata (name and description only) or preview (full step-by-step breakdown, default)'),
+    workspacePath: workspacePathField,
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),
-    workspacePath: zod_1.z.string()
-        .refine((p) => p.startsWith('/'), 'workspacePath must be an absolute path (starting with /)')
-        .optional()
-        .describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to anchor this session to your workspace for future resume_session discovery. Pass this on every start_workflow call. If omitted, WorkRail uses the server process directory which may not match your workspace.'),
+    workspacePath: workspacePathField.describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve the correct project-scoped workflow variant and to anchor this session to your workspace for future resume_session discovery. Pass this on every start_workflow call. If omitted, WorkRail uses MCP roots when available, then falls back to the server process directory.'),
 });
 exports.V2ContinueWorkflowInputShape = zod_1.z.object({
     intent: zod_1.z.enum(['advance', 'rehydrate']).optional().describe('What you want to do. Auto-inferred from ackToken if omitted: ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "1.17.1",
+  "version": "2.1.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {

package/workflows/coding-task-workflow-agentic.lean.v2.json

@@ -0,0 +1,224 @@
+{
+  "id": "coding-task-workflow-agentic",
+  "name": "Agentic Task Dev Workflow (Lean • Notes-First • WorkRail Executor)",
+  "version": "2.1.0",
+  "description": "Lean variant of the agentic coding workflow. Merges triage, inputs gate, context gathering, and re-triage into a single Understand & Classify phase. Reduces context variable count and removes top-level clarificationPrompts. Same quality guarantees with fewer tokens.",
+  "recommendedPreferences": {
+    "recommendedAutonomy": "guided",
+    "recommendedRiskPolicy": "conservative"
+  },
+  "preconditions": [
+    "User provides a task description or equivalent objective.",
+    "Agent has codebase read access and can run the tools needed for analysis and validation.",
+    "A deterministic validation path exists (tests, build, or an explicit verification strategy).",
+    "If the task touches critical paths, rollback or containment strategy can be defined."
+  ],
+  "metaGuidance": [
+    "DEFAULT BEHAVIOR: self-execute with tools. Only ask the user for business decisions, missing external artifacts, or permissions you cannot resolve.",
+    "V2 DURABILITY: use output.notesMarkdown as the primary durable record. Do NOT mirror execution state into CONTEXT.md or any markdown checkpoint file.",
+    "ARTIFACT STRATEGY: `implementation_plan.md` is the only default human-facing artifact for non-small tasks. `spec.md` or `design.md` are optional and should be created only when they materially improve handoff or reviewability.",
+    "OWNERSHIP & DELEGATION: the main agent owns strategy, decisions, synthesis, and implementation. Delegate only bounded cognitive routines via WorkRail Executor. Never hand off full task ownership or rely on named Builder/Researcher identities.",
+    "SUBAGENT SYNTHESIS: treat subagent output as evidence, not conclusions. State your hypothesis before delegating, then interrogate what came back: what was missed, wrong, or new? Say what changed your mind or what you still reject, and why.",
+    "PARALLELISM: when reads, audits, or delegations are independent, run them in parallel inside the phase. Parallelize cognition; serialize synthesis and canonical writes.",
+    "PHILOSOPHY LENS: apply the user's coding philosophy (from active session rules) as the evaluation lens. Flag violations by principle name, not as generic feedback. If principles conflict, surface the tension explicitly instead of silently choosing.",
+    "PHILOSOPHY CHECKS: watch for immutability, architectural fixes over patches, illegal states unrepresentable, explicit domain types, reduced path explosion, type safety, exhaustiveness, and errors as data.",
+    "PHILOSOPHY CHECKS (cont): validate at boundaries, fail fast on invariant violations, prefer determinism and small pure functions, use data-driven control flow, DI at boundaries, YAGNI with discipline, and atomicity.",
+    "PHILOSOPHY CHECKS (cont): treat graceful degradation, observability, fakes over mocks, and focused interfaces as first-class review concerns.",
+    "DRIFT HANDLING: when reality diverges from the plan, update the plan artifact and re-audit deliberately rather than accumulating undocumented drift.",
+    "NEVER COMMIT MARKDOWN FILES UNLESS USER EXPLICITLY ASKS."
+  ],
+  "steps": [
+    {
+      "id": "phase-0-understand-and-classify",
+      "title": "Phase 0: Understand & Classify",
+      "prompt": "Build understanding and classify the task in one pass.\n\nStep 1 — Early exit check:\nBefore any exploration, verify that acceptance criteria or expected behavior exist. If they are completely absent and cannot be inferred, ask the user and stop. Do NOT ask questions you can resolve with tools.\n\nStep 2 — Explore:\nUse tools to build the minimum complete understanding needed to design correctly. Read independent files in parallel when possible.\n\nGather:\n- key entry points and call chain sketch\n- relevant files, modules, and functions\n- existing repo patterns with concrete file references\n- testing strategy already present in the repo\n- risks and unknowns\n- explicit invariants and non-goals\n\nStep 3 — Discover the dev's philosophy and preferences:\nDiscover what the dev cares about using this fallback chain (try each, use all that are available):\n1. Memory MCP (if available): call `mcp_memory_conventions`, `mcp_memory_prefer`, `mcp_memory_recall` to retrieve learned preferences and coding philosophy\n2. Active session rules / Firebender rules: read any rules, commands, or philosophy documents already in context\n3. Repo patterns: infer preferences from how the codebase already works — error handling style, mutability patterns, test approach, naming conventions, architecture patterns\n4. Ask the dev: only if the above sources are contradictory or clearly insufficient for this task\n\nDo NOT distill into a summary — record WHERE the philosophy lives (which rules, which Memory entries, which repo files exemplify it) so later phases can reference the source directly.\n\nIf stated rules conflict with actual repo patterns (e.g., rules say 'prefer immutability' but the module uses MutableStateFlow), note the conflict in `philosophyConflicts` — this is valuable signal for design decisions.\n\nStep 4 — Classify (informed by exploration):\nNow that you have real context, classify:\n- `taskComplexity`: Small / Medium / Large\n- `riskLevel`: Low / Medium / High\n- `rigorMode`: QUICK / STANDARD / THOROUGH\n- `automationLevel`: High / Medium / Low\n- `prStrategy`: SinglePR / MultiPR\n\nDecision guidance:\n- QUICK: small, low-risk, clear path, little ambiguity\n- STANDARD: medium scope or moderate risk\n- THOROUGH: large scope, architectural uncertainty, or high-risk change\n\nStep 5 — Optional deeper context (post-classification):\nIf `rigorMode` is STANDARD or THOROUGH and understanding still feels incomplete or the call chain is too fuzzy, and delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-context-gathering` with focus=COMPLETENESS and focus=DEPTH. Synthesize both outputs before finishing this step.\n\nSet context variables:\n- `taskComplexity`\n- `riskLevel`\n- `rigorMode`\n- `automationLevel`\n- `prStrategy`\n- `contextSummary`\n- `candidateFiles`\n- `invariants`\n- `nonGoals`\n- `openQuestions`\n- `philosophySources` — pointers to where the dev's philosophy lives (rules, Memory entries, repo files), not a summary\n- `philosophyConflicts` — conflicts between stated rules and actual repo patterns (if any)\n\nRules:\n- answer your own questions with tools whenever possible\n- only keep true human-decision questions in `openQuestions`\n- keep `openQuestions` bounded to the minimum necessary\n- classify AFTER exploring, not before",
+      "requireConfirmation": {
+        "or": [
+          { "var": "taskComplexity", "equals": "Large" },
+          { "var": "riskLevel", "equals": "High" }
+        ]
+      }
+    },
+    {
+      "id": "phase-1-architecture-decision",
+      "title": "Phase 1: Architecture Decision (Generate, Compare, Challenge, Select)",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Design the architecture through deep understanding, not surface-level generation.\n\nPart A — Understand the problem deeply:\n- What are the core tensions in this problem? (e.g., performance vs simplicity, flexibility vs type safety, backward compatibility vs clean design)\n- How does the codebase already solve similar problems? Study the most relevant existing patterns — don't just list files, analyze the architectural decisions and constraints they protect.\n- What's the simplest naive solution? Why is it insufficient? (If it IS sufficient, that's your leading candidate — the burden of proof is on complexity.)\n- What makes this problem hard? What would a junior developer miss?\n\nPart B — Identify tensions and constraints (including philosophy):\n- Extract 2-4 real tradeoffs from your understanding (not generic labels like 'simplicity' or 'maintainability')\n- These tensions drive candidate generation — each candidate resolves them differently\n- Filter `philosophySources` to the principles actually under pressure for THIS problem. Which of the dev's philosophy principles constrain the solution space? For example: does the simplest solution require mutable state when the dev prefers immutability? Does the existing pattern use exceptions when the dev prefers Result types? Would the cleanest approach violate their preference for small interfaces?\n- If `philosophyConflicts` exist for this area of the codebase, surface them as explicit tensions the design must resolve: follow the stated rule, follow the existing pattern, or reconcile them\n\nPart C — State your hypothesis before delegating:\nBefore spawning any subagents, write 2-3 sentences: what do you currently believe the best approach is, and what concerns you most about it? This is your reference point for interrogating subagent output later.\n\nPart D — Generate candidates from tensions:\n- QUICK: self-generate candidates from your tensions. Include mandatory candidates: (1) simplest possible change that satisfies acceptance criteria, (2) follow existing repo pattern.\n- STANDARD: spawn ONE WorkRail Executor running `routine-tension-driven-design` with your tensions, philosophy sources, and problem understanding as input. Simultaneously, spawn ONE WorkRail Executor running `routine-hypothesis-challenge`: 'What constraints or failure modes would make you choose a fundamentally different approach? Propose one, grounded in real reasons.'\n- THOROUGH: spawn ONE WorkRail Executor running `routine-tension-driven-design`, ONE running `routine-hypothesis-challenge` (adversarial divergence), and ONE running `routine-execution-simulation`: 'Trace through the leading approach's 3 most likely failure scenarios step by step.'\n- For STANDARD with riskLevel=High: also spawn the execution simulation subagent.\n\nThe main agent ALWAYS self-generates its own candidates too (at minimum the two mandatory ones: simplest change + existing pattern). Subagent candidates supplement, not replace, your own thinking.\n\nPart E — Interrogate subagent output (if subagents were used):\nDo NOT summarize subagent findings as your own. Instead, interrogate against your hypothesis:\n- Where do subagent findings challenge your hypothesis? Are they right or did they miss context?\n- What did they surface that you genuinely hadn't considered?\n- Where are they just restating the obvious or echoing each other?\n- What did they get wrong or overweight?\nState explicitly: what you changed your mind about and why, or what you held firm on despite their input and why.\n\nPart F — Compare via tradeoffs (not checklists):\nFor each surviving candidate, produce:\n- One-sentence summary of the approach\n- Which tensions it resolves and which it accepts\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- Which of the dev's philosophy principles it honors and which it conflicts with — be specific (principle name + how)\n\nPart G — Challenge the leading option:\n- STANDARD: optionally challenge with ONE WorkRail Executor running `routine-hypothesis-challenge`\n- THOROUGH: challenge top 1-2 candidates using ONE or TWO WorkRail Executors running `routine-hypothesis-challenge`\n\nPart H — Select:\nSet context variables:\n- `selectedApproach` — the chosen design with rationale tied back to tensions\n- `runnerUpApproach` — the next-best option and why it lost\n- `architectureRationale` — which tensions were resolved and which were accepted\n- `pivotTriggers` — specific conditions under which you'd switch to the runner-up\n- `keyRiskToMonitor` — the failure mode of the selected approach\n- `acceptedTradeoffs` — what the selected approach gives up (feeds directly into design review)\n- `identifiedFailureModes` — per-candidate failure modes (feeds directly into design review)\n\nRules:\n- the main agent owns the final decision; subagents contribute depth, not decisions\n- if the simplest solution satisfies acceptance criteria, prefer it — complexity must justify itself\n- if the challenged leading candidate no longer looks best, switch deliberately rather than defending sunk cost\n- subagents go deep on specific questions, not wide on generic plans",
+      "requireConfirmation": {
+        "or": [
+          { "var": "automationLevel", "equals": "Low" },
+          { "var": "taskComplexity", "equals": "Large" },
+          { "var": "riskLevel", "equals": "High" }
+        ]
+      }
+    },
+    {
+      "id": "phase-2-design-review",
+      "type": "loop",
+      "title": "Phase 2: Design Review",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "while",
+        "conditionSource": {
+          "kind": "artifact_contract",
+          "contractRef": "wr.contracts.loop_control",
+          "loopId": "design_review_loop"
+        },
+        "maxIterations": 2
+      },
+      "body": [
+        {
+          "id": "phase-2a-review-design",
+          "title": "Review Design for Gaps, Issues, and Improvements",
+          "prompt": "Review the selected architecture using the explicit tradeoffs and failure modes from Phase 1 as your review criteria — not a generic gaps checklist.\n\nTargeted review (derived from Phase 1 outputs):\n1. Are the `acceptedTradeoffs` actually acceptable? For each accepted tradeoff, verify it won't violate acceptance criteria or invariants under realistic conditions.\n2. Are the `identifiedFailureModes` actually handled? For each failure mode, trace through the design and confirm there's a mitigation path. If not, flag it.\n3. Does the selected approach's relationship to existing repo patterns hold up? If it 'adapts' an existing pattern, verify the adaptation doesn't break the invariants the original pattern protects.\n4. Is there a simpler version of the selected approach that still satisfies acceptance criteria? (Complexity must continue to justify itself.)\n\nCompare against the runner-up:\n- Are there elements from the runner-up that would strengthen the selected approach without adding complexity?\n- Would a hybrid resolve an accepted tradeoff that's bothering you?\n\nPhilosophy alignment: does the architecture respect the user's active coding rules?\n\nBefore delegating, state your current assessment: what do you think the strongest and weakest parts of the design are right now?\n\nMode-adaptive delegation:\n- QUICK: self-review only\n- STANDARD: optionally spawn ONE WorkRail Executor running `routine-hypothesis-challenge` focused specifically on the accepted tradeoffs and failure modes\n- THOROUGH: spawn TWO WorkRail Executors — `routine-hypothesis-challenge` on tradeoffs + `routine-execution-simulation` on failure modes\n\nAfter receiving subagent output (if used), interrogate it against your pre-assessment. Do not adopt their framing wholesale. State what changed your thinking and what didn't.\n\nIf issues are found, fix the design (update `selectedApproach`, `architectureRationale`, `pivotTriggers`, `acceptedTradeoffs`, `identifiedFailureModes`) before continuing.\n\nSet context variables:\n- `designFindings`\n- `designRevised`",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-2b-loop-decision",
+          "title": "Design Review Loop Decision",
+          "prompt": "Provide a loop control artifact.\n\nDecision rules:\n- if `designFindings` is non-empty and design was revised -> continue (verify the revision)\n- if `designFindings` is empty -> stop\n- if max iterations reached -> stop and document remaining concerns\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "requireConfirmation": false,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-3-plan-and-test-design",
+      "title": "Phase 3: Slice, Plan, and Test Design",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Create or update the human-facing implementation artifact: `implementation_plan.md`.\n\nThis phase combines slicing, plan drafting, philosophy alignment, and test design.\n\nThe plan must include:\n1. Problem statement\n2. Acceptance criteria\n3. Non-goals\n4. Philosophy-driven constraints (from the user's active rules)\n5. Invariants\n6. Selected approach + rationale + runner-up\n7. Vertical slices\n8. Work packages only when they improve execution or enable safe parallelism\n9. Test design\n10. Risk register\n11. PR packaging strategy\n12. Philosophy alignment per slice:\n   - [principle] -> [satisfied / tension / violated + 1-line why]\n\nSet context variables:\n- `implementationPlan`\n- `slices`\n- `testDesign`\n- `estimatedPRCount`\n- `followUpTickets` (initialize if needed)\n- `unresolvedUnknownCount`\n- `planConfidenceBand`\n\nRules:\n- keep `implementation_plan.md` concrete enough for another engineer to implement without guessing\n- use work packages only when they create real clarity; do not over-fragment work\n- use the user's coding philosophy as the primary planning lens, and name tensions explicitly\n- set `unresolvedUnknownCount` to the number of still-open issues that would materially affect implementation quality\n- set `planConfidenceBand` to Low / Medium / High based on how ready the plan actually is",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-4-plan-audit",
+      "type": "loop",
+      "title": "Phase 4: Plan Audit (Review, Fix, Decide)",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "while",
+        "conditionSource": {
+          "kind": "artifact_contract",
+          "contractRef": "wr.contracts.loop_control",
+          "loopId": "plan_audit_loop"
+        },
+        "maxIterations": 2
+      },
+      "body": [
+        {
+          "id": "phase-4a-audit-and-refocus",
+          "title": "Audit Plan and Apply Fixes",
+          "prompt": "Audit the plan and fix what you find in one pass.\n\nPart A -- Audit:\n- completeness / missing work\n- weak assumptions and risks\n- invariant coverage\n- slice boundary quality\n- philosophy alignment against the user's active rules\n- regression check against `resolvedFindings` (if present): if a previously resolved issue reappeared, treat it as Critical\n\nPhilosophy rules:\n- flag findings by principle name\n- Red / Orange findings go into `planFindings`\n- Yellow tensions are informational only and do NOT block loop exit\n\nBefore delegating, state your hypothesis: what do you think the plan's biggest weakness is right now? What are you most and least confident about?\n\nMode-adaptive delegation:\n- QUICK: self-audit only\n- STANDARD: if delegation is available, spawn THREE WorkRail Executors SIMULTANEOUSLY running `routine-plan-analysis`, `routine-hypothesis-challenge`, and `routine-philosophy-alignment`; include `routine-execution-simulation` only when runtime or state-flow risk is material\n- THOROUGH: if delegation is available, spawn FOUR WorkRail Executors SIMULTANEOUSLY running `routine-plan-analysis`, `routine-hypothesis-challenge`, `routine-execution-simulation`, and `routine-philosophy-alignment`\n\nInterrogate subagent output (if used):\n- Do NOT treat auditor findings as your findings. They are raw input from junior analysts.\n- Where 2+ auditors flag the same issue -> likely real, but verify it yourself\n- Where one auditor flags a unique concern -> investigate; is it genuine or did they miss context?\n- Where auditors conflict -> reason through it yourself rather than splitting the difference\n- State what changed your assessment of the plan and what didn't\n\nPart B -- Refocus (apply fixes immediately):\n- update `implementation_plan.md` to incorporate amendments\n- update `slices` if the plan shape changed\n- extract out-of-scope work into `followUpTickets`\n- track resolved findings (cap at 10, drop oldest)\n\nSet context variables:\n- `planFindings`\n- `planConfidence`\n- `resolvedFindings`\n- `followUpTickets`\n\nRules:\n- the main agent is synthesizer and final decision-maker\n- do not delegate sequentially when audit routines are independent\n- do not silently accept plan drift; reflect changes in the plan artifact immediately",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-4b-loop-decision",
+          "title": "Loop Exit Decision",
+          "prompt": "Provide a loop control artifact.\n\nDecision rules:\n- if `planFindings` is non-empty -> continue\n- if `planFindings` is empty -> stop, but enumerate what was checked to justify the clean pass\n- if max iterations reached -> stop and document remaining concerns\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "requireConfirmation": true,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-5-small-task-fast-path",
+      "title": "Phase 5: Small Task Fast Path",
+      "runCondition": {
+        "var": "taskComplexity",
+        "equals": "Small"
+      },
+      "prompt": "For Small tasks:\n- confirm target locations and relevant patterns with tools\n- implement the smallest correct change\n- verify with tests/build or a deterministic check\n- apply the user's coding philosophy as the active review lens before finalizing\n- provide a concise PR-ready summary\n\nDo not create heavyweight planning artifacts unless risk unexpectedly grows.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-6-implement-slices",
+      "type": "loop",
+      "title": "Phase 6: Implement Slice-by-Slice",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "forEach",
+        "items": "slices",
+        "itemVar": "currentSlice",
+        "indexVar": "sliceIndex",
+        "maxIterations": 20
+      },
+      "body": [
+        {
+          "id": "phase-6a-implement-slice",
+          "title": "Implement Slice",
+          "prompt": "Implement slice `{{currentSlice.name}}`.\n\nBefore writing code, do a quick inline check:\n- if pivot triggers have fired or plan assumptions are clearly stale, stop and return to planning instead of coding through it\n- if target files or symbols no longer match the plan, stop and re-plan\n\nImplementation rules:\n- the main agent owns implementation\n- delegate only targeted cognitive routines via the WorkRail Executor (challenge, simulation, philosophy review), not the whole slice\n- read independent files in parallel when possible\n- implement incrementally and keep the slice within its intended boundary\n- apply the user's coding philosophy as the active implementation lens\n- run tests and build after implementation to confirm the slice works\n\nTrack whether this slice required:\n- a new special-case (`specialCaseIntroduced`)\n- an unplanned abstraction (`unplannedAbstractionIntroduced`)\n- unexpected file changes outside planned scope (`unexpectedScopeChange`)\n\nSet `verifyNeeded` to true if ANY of:\n- `sliceIndex` is odd (verify every 2 slices)\n- `specialCaseIntroduced = true`\n- `unplannedAbstractionIntroduced = true`\n- `unexpectedScopeChange = true`\n- tests or build failed\n\nIf `prStrategy = MultiPR`, stop with a concise PR package for user review.\n\nSet context variables:\n- `specialCaseIntroduced`\n- `unplannedAbstractionIntroduced`\n- `unexpectedScopeChange`\n- `verifyNeeded`",
+          "requireConfirmation": {
+            "var": "prStrategy",
+            "equals": "MultiPR"
+          }
+        },
+        {
+          "id": "phase-6b-verify-slice",
+          "title": "Verify Slice",
+          "runCondition": {
+            "var": "verifyNeeded",
+            "equals": true
+          },
+          "prompt": "Evaluate what was just implemented with fresh eyes.\n\nReview:\n- does the implementation match the plan intent, not just the letter?\n- are there hidden assumptions or edge cases the implementation glossed over?\n- do invariants still hold?\n- are there philosophy-alignment regressions?\n- if multiple slices have passed since last verification, review all unverified slices together\n\nBefore delegating (if applicable), state: what is your honest assessment of the slice you just implemented? Where are you least confident?\n\nMode-adaptive delegation:\n- QUICK: self-verify only\n- STANDARD: if a fresh-eye trigger fired (`specialCaseIntroduced`, `unplannedAbstractionIntroduced`, or `unexpectedScopeChange`), optionally spawn ONE or TWO WorkRail Executors running `routine-hypothesis-challenge` and `routine-philosophy-alignment`\n- THOROUGH: if any fresh-eye trigger fired, spawn up to THREE WorkRail Executors running `routine-hypothesis-challenge`, `routine-execution-simulation`, and `routine-philosophy-alignment`\n\nAfter receiving subagent output (if used), interrogate: did they find something you genuinely missed, or are they flagging things you already considered and accepted? State what changed your assessment.\n\nSet context variables:\n- `verificationFindings`\n- `verificationFailed`\n\nRule:\n- if serious concerns are found, stop and return to planning or ask the user\n- do not rubber-stamp; this step exists specifically to catch what the implementation step missed",
+          "requireConfirmation": {
+            "var": "verificationFailed",
+            "equals": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-7-final-verification",
+      "type": "loop",
+      "title": "Phase 7: Final Verification & Handoff",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "while",
+        "conditionSource": {
+          "kind": "artifact_contract",
+          "contractRef": "wr.contracts.loop_control",
+          "loopId": "final_verification_loop"
+        },
+        "maxIterations": 2
+      },
+      "body": [
+        {
+          "id": "phase-7a-verify-and-fix",
+          "title": "Verify Integration and Fix Issues",
+          "prompt": "Perform integration verification across all implemented slices.\n\nRequired:\n- verify acceptance criteria\n- map invariants to concrete proof (tests, build results, explicit reasoning)\n- run whole-task validation commands\n- identify any invariant violations or regressions\n- confirm the implemented result aligns with the user's coding philosophy, naming any tensions explicitly\n- review cumulative drift across all slices\n- check whether repeated small compromises added up to a larger pattern problem\n\nIf issues are found, fix them immediately:\n- apply code fixes\n- re-run affected tests\n- update `implementation_plan.md` if the fix changed boundaries or approach\n\nSet context variables:\n- `integrationFindings`\n- `integrationPassed`\n- `regressionDetected`",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-7b-loop-decision",
+          "title": "Final Verification Loop Decision",
+          "prompt": "Provide a loop control artifact.\n\nDecision rules:\n- if `integrationFindings` is non-empty and fixes were applied -> continue (re-verify the fixes)\n- if `integrationFindings` is empty or all issues resolved -> stop and produce handoff\n- if max iterations reached -> stop and document remaining concerns\n\nWhen stopping, include the handoff summary:\n- acceptance criteria status\n- invariant status\n- test/build summary\n- concise PR/MR description draft (why, test plan, rollout notes)\n- follow-up tickets\n- any philosophy tensions accepted intentionally and why\n\nKeep the handoff concise and executive-level. Do not auto-merge or push unless the user explicitly asks.\n\nOutput exactly:\n```json\n{\n  \"artifacts\": [{\n    \"kind\": \"wr.loop_control\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "requireConfirmation": true,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    }
+  ]
+}

package/workflows/routines/philosophy-alignment.json

@@ -5,9 +5,9 @@
   "description": "Independently evaluates a plan or implementation artifact against the user's coding philosophy. Produces findings by principle name and distinguishes blocking violations from acceptable tensions.",
   "clarificationPrompts": [
     "What artifact should I review? (plan, architecture summary, implementation diff, files)",
-    "What philosophy principles or user rules should I apply?",
     "What mode is this review in? (plan, architecture, implementation)",
-    "What artifact name should I produce?"
+    "What artifact name should I produce?",
+    "Are `philosophySources` and `philosophyConflicts` available in context? (if not, I will discover from scratch)"
   ],
   "preconditions": [
     "A review artifact is available",
@@ -24,30 +24,30 @@
   ],
   "steps": [
     {
-      "id": "step-understand-scope",
-      "title": "Step 1: Understand the Artifact and Scope",
-      "prompt": "Understand what you are reviewing.\n\nRead and summarize:\n- the artifact under review\n- the review mode (plan, architecture, implementation)\n- the relevant philosophy principles / user rules\n- any supporting files or repo patterns needed for evidence\n\nIdentify:\n- which principles are actually touched by this artifact\n- where violations are most likely to appear\n- where principle tensions may naturally arise\n\nWorking notes:\n- Review scope\n- Applicable principles\n- Likely risk areas\n- Possible tension zones",
-      "agentRole": "You are understanding the review scope before judging the design quality.",
+      "id": "step-discover-philosophy",
+      "title": "Step 1: Discover the Dev's Philosophy",
+      "prompt": "Discover the dev's coding philosophy and preferences. Check `philosophySources` context variable first — if it contains pointers to rules, Memory entries, or repo files, go read those sources directly.\n\nIf `philosophySources` is empty or unavailable, discover from scratch using this fallback chain:\n1. Memory MCP (if available): call `mcp_memory_conventions`, `mcp_memory_prefer`, `mcp_memory_recall` to retrieve learned preferences\n2. Active session rules / Firebender rules: read any rules or philosophy documents in context\n3. Repo patterns: infer preferences from how the codebase works — error handling, mutability, test style, naming, architecture\n\nAlso check `philosophyConflicts` — if stated rules conflict with repo patterns, note which apply to this review.\n\nWorking notes:\n- Philosophy sources consulted\n- Key principles discovered\n- Conflicts between stated and practiced philosophy",
+      "agentRole": "You are discovering what the dev actually cares about before judging their code against it.",
       "requireConfirmation": false
     },
     {
-      "id": "step-select-principles",
-      "title": "Step 2: Select the Relevant Principles",
-      "prompt": "Select the subset of principles that materially apply.\n\nRules:\n- do not pretend every principle matters equally for every artifact\n- prioritize the principles actually implicated by the design or implementation\n- note any principles that are out of scope for this review\n\nWorking notes:\n- High-priority principles\n- Secondary principles\n- Out-of-scope principles",
+      "id": "step-understand-scope",
+      "title": "Step 2: Understand the Artifact and Select Principles",
+      "prompt": "Understand what you are reviewing and select the principles that matter.\n\nRead and summarize:\n- the artifact under review\n- the review mode (plan, architecture, implementation)\n- any supporting files or repo patterns needed for evidence\n\nSelect the subset of discovered principles that materially apply:\n- do not pretend every principle matters equally for every artifact\n- prioritize the principles actually implicated by the design or implementation\n- note any principles that are out of scope for this review\n\nIdentify:\n- which principles are actually touched by this artifact\n- where violations are most likely to appear\n- where principle tensions may naturally arise\n\nWorking notes:\n- Review scope\n- High-priority principles\n- Secondary principles\n- Likely risk areas\n- Possible tension zones",
       "agentRole": "You are focusing the review on the principles that actually matter for this artifact.",
       "requireConfirmation": false
     },
     {
       "id": "step-evaluate-artifact",
-      "title": "Step 3: Evaluate Principle-by-Principle",
+      "title": "Step 3: Evaluate Principle-by-Principle (from source, not summary)",
       "prompt": "Evaluate the artifact against each relevant principle.\n\nFor each principle, determine:\n- what the artifact does well\n- what violates the principle, if anything\n- whether this is a Red violation, Orange issue, or Yellow tension\n- what change or justification would resolve it\n\nSeverity guide:\n- Red = blocking violation of a key philosophy principle\n- Orange = meaningful design quality issue that should be fixed or justified\n- Yellow = principle tension or trade-off that may be acceptable if explicit\n\nWorking notes:\n- Findings by principle\n- Evidence / citations\n- Severity\n- Recommended action or required justification",
       "agentRole": "You are performing a principle-by-principle review with specific, evidence-based findings.",
       "requireConfirmation": false
     },
     {
       "id": "step-identify-tensions",
-      "title": "Step 4: Identify Principle Tensions",
-      "prompt": "Identify where principles conflict.\n\nLook for cases like:\n- simplicity vs extensibility\n- YAGNI vs architecture cleanliness\n- explicitness vs verbosity\n- atomicity vs implementation complexity\n\nFor each tension:\n- name the principles involved\n- explain the trade-off\n- say what decision still needs to be made or documented\n\nWorking notes:\n- Principle tensions\n- Why they exist\n- What decision or explicit acceptance is needed",
+      "title": "Step 4: Identify Principle Tensions (including stated vs practiced)",
+      "prompt": "Identify where principles conflict.\n\nLook for cases like:\n- simplicity vs extensibility\n- YAGNI vs architecture cleanliness\n- explicitness vs verbosity\n- atomicity vs implementation complexity\n- stated philosophy vs actual repo patterns (e.g., rules say immutability but module uses mutable state)\n\nFor each tension:\n- name the principles involved\n- explain the trade-off\n- say what decision still needs to be made or documented\n\nWorking notes:\n- Principle tensions\n- Why they exist\n- What decision or explicit acceptance is needed",
       "agentRole": "You are surfacing real trade-offs instead of flattening them into fake certainty.",
       "requireConfirmation": false
     },

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

@@ -0,0 +1,63 @@
+{
+  "id": "routine-tension-driven-design",
+  "name": "Tension-Driven Design Generation",
+  "version": "1.0.0",
+  "description": "Generates design candidates by deeply understanding a problem, identifying real tensions and constraints (including the dev's philosophy), and producing candidates that resolve those tensions differently. Each candidate includes explicit tradeoffs, failure modes, and philosophy alignment. Replaces perspective-based generation with constraint-driven generation for higher-quality, genuinely diverse candidates.",
+  "clarificationPrompts": [
+    "What problem should this design solve?",
+    "What acceptance criteria, invariants, and constraints must it respect?",
+    "Are `philosophySources` and `philosophyConflicts` available in context? (if not, I will discover from scratch)",
+    "What artifact name should I produce?"
+  ],
+  "preconditions": [
+    "Problem statement is available",
+    "Acceptance criteria and non-goals are available",
+    "Relevant files, patterns, or codebase references are available",
+    "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.",
+    "HONESTY: for each candidate, state what you gain, what you give up, and how it fails. Optimize for useful comparison, not persuasion."
+  ],
+  "steps": [
+    {
+      "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\nCheck `philosophySources` context variable first — if it contains pointers to rules, Memory entries, or repo files, go read those sources directly.\n\nIf `philosophySources` is empty or unavailable, 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 / Firebender rules: 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 `philosophyConflicts` (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.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-understand-deeply",
+      "title": "Step 2: Understand the Problem Deeply",
+      "prompt": "Understand the problem before proposing anything.\n\nReason through:\n- What are the core tensions in this problem? (e.g., performance vs simplicity, flexibility vs type safety, backward compatibility vs clean design)\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- What's 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\nWorking notes:\n- Core tensions (2-4 real tradeoffs, not generic labels)\n- Existing patterns analysis (decisions, invariants they protect)\n- Naive solution and why it's insufficient (or sufficient)\n- What makes this hard\n- Philosophy principles under pressure",
+      "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\nMANDATORY candidates:\n1. The simplest possible change that satisfies acceptance criteria. If the problem doesn't need an architectural solution, say so.\n2. Follow the existing repo pattern — adapt what the codebase already does for similar problems. Don't invent when you can adapt.\n\nAdditional candidates (1-2 more):\n- Each must resolve the identified tensions DIFFERENTLY, not just vary surface details\n- Each must be grounded in a real constraint or tradeoff, not an abstract perspective label\n- Consider philosophy conflicts: if the stated philosophy disagrees with repo patterns, one candidate could follow the stated philosophy and another could follow the established pattern\n\nFor each candidate, produce:\n- One-sentence summary of the approach\n- Which tensions it resolves and which it accepts\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- 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, that's signal — note it honestly rather than manufacturing fake diversity\n- cite specific files or patterns when they materially shape a candidate",
+      "agentRole": "You are generating genuinely diverse design candidates grounded in real tensions.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-compare-and-recommend",
+      "title": "Step 4: Compare via Tradeoffs and Recommend",
+      "prompt": "Compare candidates through tradeoff analysis, not checklists.\n\nFor the set of candidates, assess:\n- Which tensions does each resolve best?\n- Which has the most manageable failure mode?\n- Which best fits the dev's philosophy? Where are the philosophy conflicts?\n- Which is most consistent with existing repo patterns?\n- Which would be easiest to evolve or reverse if assumptions are wrong?\n\nProduce a clear recommendation with rationale tied back to tensions and philosophy. If two candidates are close, say so and explain what would tip the decision.\n\nSelf-critique your recommendation:\n- What's the strongest argument against your pick?\n- What would make you switch to a different candidate?\n- What assumption, if wrong, would invalidate this design?\n\nWorking notes:\n- Comparison matrix (tensions x candidates)\n- Recommendation and rationale\n- Strongest counter-argument\n- Pivot conditions",
+      "agentRole": "You are comparing candidates honestly and recommending based on tradeoffs, not advocacy.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-deliver",
+      "title": "Step 5: Deliver the Design Candidates",
+      "prompt": "Create `{deliverableName}`.\n\nRequired structure:\n- Problem Understanding (tensions, what makes it hard)\n- Philosophy Constraints (which principles matter, any conflicts)\n- Candidates (each with: summary, tensions resolved/accepted, failure mode, repo-pattern relationship, gains/losses, philosophy fit)\n- Comparison and Recommendation\n- Self-Critique (strongest counter-argument, pivot conditions)\n- Open Questions for the Main Agent\n\nThe main agent will interrogate this output — it is raw investigative material, not a final decision. Optimize for honest, useful analysis over polished presentation.",
+      "agentRole": "You are delivering design analysis for the main agent to interrogate and build on.",
+      "requireConfirmation": false
+    }
+  ]
+}