@exaudeus/workrail 1.15.0 → 1.16.0

package/dist/config/feature-flags.js

@@ -57,7 +57,7 @@ exports.FEATURE_FLAG_DEFINITIONS = [
         key: 'v2Tools',
         envVar: 'WORKRAIL_ENABLE_V2_TOOLS',
         defaultValue: false,
-        description: 'Enable WorkRail v2 MCP tools (Slices 1–3: list/inspect/start/continue) behind an explicit opt-in flag',
+        description: 'Enable WorkRail v2 MCP tools and .v2.json workflow overrides behind an explicit opt-in flag',
         since: '0.9.0',
         stable: false,
     },

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

@@ -73,6 +73,9 @@ class FileWorkflowStorage {
                         continue;
                     }
                 }
+                if (!this.featureFlags.isEnabled('v2Tools') && file.includes('.v2.')) {
+                    continue;
+                }
                 const filePathRaw = path_1.default.resolve(this.baseDirReal, file);
                 assertWithinBase(filePathRaw, this.baseDirReal);
                 const stats = (0, fs_1.statSync)(filePathRaw);
@@ -92,17 +95,19 @@ class FileWorkflowStorage {
         }
         for (const [id, files] of idToFiles) {
             let selected = files[0];
-            if (this.featureFlags.isEnabled('agenticRoutines')) {
-                const agenticEntry = files.find(f => f.file.includes('.agentic.'));
-                if (agenticEntry) {
-                    selected = agenticEntry;
-                }
+            const isV2Enabled = this.featureFlags.isEnabled('v2Tools');
+            const isAgenticEnabled = this.featureFlags.isEnabled('agenticRoutines');
+            const v2Entry = files.find(f => f.file.includes('.v2.'));
+            const agenticEntry = files.find(f => f.file.includes('.agentic.'));
+            const standardEntry = files.find(f => !f.file.includes('.agentic.') && !f.file.includes('.v2.'));
+            if (isV2Enabled && v2Entry) {
+                selected = v2Entry;
             }
-            else {
-                const standardEntry = files.find(f => !f.file.includes('.agentic.'));
-                if (standardEntry) {
-                    selected = standardEntry;
-                }
+            else if (isAgenticEnabled && agenticEntry) {
+                selected = agenticEntry;
+            }
+            else if (standardEntry) {
+                selected = standardEntry;
             }
             const filePath = path_1.default.resolve(this.baseDirReal, selected.file);
             const stats = (0, fs_1.statSync)(filePath);

package/dist/manifest.json

@@ -302,8 +302,8 @@
       "bytes": 1512
     },
     "config/feature-flags.js": {
-      "sha256": "2881b750bbaeb9af57ae2acfa476ed94f7da2a95781478b9713d978f30700356",
-      "bytes": 6920
+      "sha256": "c7c5a4db2a0d5f86a9cf91c9a7e2c74f89ce7f1012b93c8237a3d70a783d2b45",
+      "bytes": 6908
     },
     "core/error-handler.d.ts": {
       "sha256": "80451f12ac8e185133ec3dc4c57285491a785f27525ed21e729db1da3f61010d",
@@ -502,8 +502,8 @@
       "bytes": 1455
     },
     "infrastructure/storage/file-workflow-storage.js": {
-      "sha256": "e4d5f57112885efc6dca15e545071159afc824774a82e8b5b610ca8557c0054d",
-      "bytes": 8579
+      "sha256": "ae9ad3c208c85d10c6bdcd9ffae1e88a3924ed412d19fa858e4ec886c6338426",
+      "bytes": 8947
     },
     "infrastructure/storage/git-workflow-storage.d.ts": {
       "sha256": "67d7f10e12c78c674ced83da378cd159465d4b09176d8dfca240864b0d6f38c2",

package/package.json

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

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

@@ -41,7 +41,7 @@
     "DECISION LOG: Entry includes Decision, Why (1-3 bullets), Impacted files (≤5), User feedback, Surprises. Cap 8 bullets.",
     "VARIABLE TYPES: Strings: taskComplexity, rigorMode, prStrategy, selectedApproach, runnerUpApproach, leadingCandidate, architectureRationale, keyRiskToMonitor, selectedSliceStrategy.",
     "VARIABLE TYPES: Strings (cont): pivotSeverity (none/MINOR/MODERATE/MAJOR), pivotReturnPhase, cleanSlateDivergence (None/Minor/Major).",
-    "VARIABLE TYPES: Arrays: approaches, pivotTriggers, preMortemFindings, sliceStrategies, planningGaps, integrationGaps, integrationVerificationFindings, invariantViolations. Numbers: planConfidence, sliceIndex.",
+    "VARIABLE TYPES: Arrays: approaches, pivotTriggers, preMortemFindings, sliceStrategies, planningGaps, integrationGaps, integrationVerificationFindings, invariantViolations, resolvedFindings. Numbers: planConfidence, sliceIndex.",
     "VARIABLE TYPES: Booleans: continuePlanning, pivotTriggered, planningComplete, validationFailed, slicePlanStale, majorConcernsRaised.",
     "VARIABLE TYPES: Booleans (cont): spikeFailure, assumptionsValidated, planningGapsFound, integrationGapsFound, integrationVerificationPassed, integrationVerificationFailed, regressionDetected."
   ],
@@ -311,19 +311,19 @@
         {
           "id": "phase-5a-draft-implementation-plan",
           "title": "Plan Artifact Draft/Update",
-          "prompt": "Create or update the **Plan Artifact** (deterministic schema).\n\n**Write-or-paste rule:** attempt to write/update `implementation_plan.md`. If file writing fails, output full content in chat (canonical).\n\n**Plan Artifact headings (concise, complete):**\n\n1) Problem statement\n2) Acceptance criteria (bullets)\n3) Non-goals (bullets)\n4) **User rules/preferences applied:**\n   - Relevant `userRules` + how plan respects them.\n   - Deviations: rationale + mitigation + user decision (counts toward `maxQuestions`).\n5) Invariants (reference `invariants`)\n6) Proposed approach (1–2 paragraphs)\n7) Architecture decision (reference Phase 3/3b outputs):\n   - Selected approach: reference `selectedApproach`\n   - Rationale: reference `architectureRationale`\n   - Runner-up (Plan B): reference `runnerUpApproach`\n   - Key risk: reference `keyRiskToMonitor`\n   - Full alternatives: see CONTEXT.md Approaches section\n8) **Vertical slices** (match `slices`: scope, done-definition, files, verification)\n\n   **Work Packages inside each slice (mode-dependent):**\n   - QUICK: skip work packages\n   - STANDARD: optional; recommended when slice is high-risk or multi-layer\n   - THOROUGH: required for non-trivial slices\n\n   Each work package (WP):\n   - ID: `S<sliceIndex>-WP<k>` (e.g., S1-WP1)\n   - Goal: one coherent outcome\n   - Targets (allowlist): dirs/files (+ allowed new files)\n   - Forbidden (denylist): files/dirs not to touch\n   - Budget: maxModified (5 STANDARD/8 THOROUGH), maxNew (2/3)\n   - Done-definition: 2–5 bullets\n   - Verification: 1–3 commands/tests\n   - Dependencies: contracts/types from other WPs (if parallel)\n\n   **Parallelism rule:** parallelize only if Targets don't overlap. Final WP must be \"Hook-up/Integration\" when parallel was used.\n\n9) Test plan (unit/integration/e2e; cite repo patterns)\n10) Risk register (risks + mitigation + rollback/flag)\n11) PR packaging (Single/Multi + rule)\n\n**Set context variables:**\n- `planArtifact`\n- `implementationPlan`\n\n**VERIFY:** concrete enough for another engineer to implement without guessing.",
+          "prompt": "Create or update the **Plan Artifact** (deterministic schema).\n\n**Write-or-paste rule:** attempt to write/update `implementation_plan.md`. If file writing fails, output full content in chat (canonical).\n\n**Plan Artifact headings (concise, complete):**\n\n1) Problem statement\n2) Acceptance criteria (bullets)\n3) Non-goals (bullets)\n4) **User rules/preferences applied:**\n   - Relevant `userRules` + how plan respects them.\n   - Deviations: rationale + mitigation + user decision (counts toward `maxQuestions`).\n5) Invariants (reference `invariants`)\n6) Proposed approach (1–2 paragraphs)\n7) Architecture decision (reference Phase 3/3b outputs):\n   - Selected approach: reference `selectedApproach`\n   - Rationale: reference `architectureRationale`\n   - Runner-up (Plan B): reference `runnerUpApproach`\n   - Key risk: reference `keyRiskToMonitor`\n   - Full alternatives: see CONTEXT.md Approaches section\n8) **Vertical slices** (match `slices`: scope, done-definition, files, verification)\n\n   **Work Packages inside each slice (mode-dependent):**\n   - QUICK: skip work packages\n   - STANDARD: optional; recommended when slice is high-risk or multi-layer\n   - THOROUGH: required for non-trivial slices\n\n   Each work package (WP):\n   - ID: `S<sliceIndex>-WP<k>` (e.g., S1-WP1)\n   - Goal: one coherent outcome\n   - Targets (allowlist): dirs/files (+ allowed new files)\n   - Forbidden (denylist): files/dirs not to touch\n   - Budget: maxModified (5 STANDARD/8 THOROUGH), maxNew (2/3)\n   - Done-definition: 2–5 bullets\n   - Verification: 1–3 commands/tests\n   - Dependencies: contracts/types from other WPs (if parallel)\n\n   **Parallelism rule:** parallelize only if Targets don't overlap. Final WP must be \"Hook-up/Integration\" when parallel was used.\n\n9) Test plan (unit/integration/e2e; cite repo patterns)\n10) Risk register (risks + mitigation + rollback/flag)\n11) PR packaging (Single/Multi + rule)\n12) **Philosophy alignment per slice** (for each slice, include):\n   - For each design principle touched by this slice: [principle] → [satisfied / tension / violated + 1-line why]\n   - The audit step will independently verify these self-assessments. Be honest — violations caught early are cheaper than violations caught in review.\n\n**Set context variables:**\n- `planArtifact`\n- `implementationPlan`\n\n**VERIFY:** concrete enough for another engineer to implement without guessing.",
           "requireConfirmation": false
         },
         {
           "id": "phase-5b-plan-audit-mode-adaptive",
           "title": "Plan Audit (Subagent-Friendly)",
-          "prompt": "**Mission: Find gaps, issues, and inconsistencies in this plan.**\n\nActively look for:\n- **Gaps**: What's missing? What's not covered?\n- **Weak assumptions**: What could be wrong? What are we taking for granted?\n- **Inconsistencies**: Do parts contradict each other? Does the plan match the invariants?\n- **Risks**: What could go wrong? What hasn't been stress-tested?\n\n---\n\n**Mode behavior:**\n- QUICK: self-audit only\n- STANDARD: self-audit; delegate once if subagents exist\n- THOROUGH: parallel delegation if subagents exist\n\n**If subagents + `rigorMode=THOROUGH`:**\n\nYou have permission to spawn THREE subagents SIMULTANEOUSLY for parallel plan validation.\n\nDelegate to WorkRail Executor THREE TIMES with scoped context:\n\n**Delegation 1 — Plan Analysis:**\n- routine: routine-plan-analysis\n- plan: implementation_plan.md\n- requirements: [From Phase 2 invariants + acceptance criteria]\n- constraints: [Filtered userRules: architecture, testing, patterns]\n- context (file-reference-first, max 500 words if pasting):\n  - Read: CONTEXT.md (userRules section), implementation_plan.md\n  - Read: spec.md, design.md (if exist)\n  - Invariants + locks (if locksMatrix exists)\n  - Feature brief: problem statement + architecture decision + key constraints\n- deliverable: plan-analysis.md\n\n**Delegation 2 — Hypothesis Challenge:**\n- routine: routine-hypothesis-challenge\n- rigor: 3\n- hypotheses: [Plan's key assumptions about architecture, dependencies, invariant satisfaction]\n- evidence: implementation_plan.md\n- context:\n  - Read: implementation_plan.md\n  - Filtered userRules: error handling, edge cases, validation rules\n  - Invariants (especially high-risk ones)\n  - Feature brief: problem + acceptance criteria + non-goals\n- deliverable: plan-challenges.md\n\n**Delegation 3 — Execution Simulation:**\n- routine: routine-execution-simulation\n- entry_point: [Riskiest slice entry function]\n- inputs: [Expected inputs and state]\n- trace_depth: 3 (follow calls to understand failure modes)\n- context:\n  - Read: implementation_plan.md (riskiest slice section)\n  - Filtered userRules: performance, data flow, state management\n  - Invariants touched by risky slice\n  - Feature brief: architecture decision + risk register\n- deliverable: simulation-results.md\n\n**Self-check before delegating (required):**\n✅ Each delegation includes filtered userRules (not full list)\n✅ Each includes invariants + locks (if applicable)\n✅ Each includes feature brief (file refs or <500 word excerpt)\n✅ Each has specific focus/lens\n\n**If subagents + `rigorMode=STANDARD`:**\nDelegate ONCE using Plan Analysis with full context (not filtered).\n\n\n**Note:** delegationMode was detected in phase-0c and cached in CONTEXT.md\n**Else:** self-audit (same three lenses).\n\n**Output:**\n- Findings: Critical / Major / Minor\n- Plan amendments\n\n---\n\n**CLEAN-SLATE CHECK (STANDARD+, if findings exist):**\n\nBefore applying amendments, briefly answer:\n\n> \"If I started fresh right now, knowing everything I've learned, would I choose the same approach?\"\n\n1. Without looking at current plan, sketch in 1 sentence what approach you'd take\n2. Compare to `selectedApproach`:\n   - **Same**: Proceed with amendments\n   - **Minor variation**: Note the insight; consider incorporating\n   - **Fundamentally different**: STOP. Set `cleanSlateDivergence = Major`\n\n**If fundamentally different:**\n- Document why fresh thinking differs\n- Return to Phase 3b with fresh approach as new candidate, OR\n- Document why current approach is still better despite fresh thinking\n\n**Set:** `planFindings`, `planAmendments`, `planConfidence` (1–10), `cleanSlateDivergence` (None/Minor/Major)",
+          "prompt": "**Mission: Find gaps, issues, and inconsistencies in this plan.**\n\nActively look for:\n- **Gaps**: What's missing? What's not covered?\n- **Weak assumptions**: What could be wrong? What are we taking for granted?\n- **Inconsistencies**: Do parts contradict each other? Does the plan match the invariants?\n- **Risks**: What could go wrong? What hasn't been stress-tested?\n\n---\n\n**Mode behavior:**\n- QUICK: self-audit only\n- STANDARD: self-audit; delegate once if subagents exist\n- THOROUGH: parallel delegation if subagents exist\n\n**If subagents + `rigorMode=THOROUGH`:**\n\nYou have permission to spawn THREE subagents SIMULTANEOUSLY for parallel plan validation.\n\nDelegate to WorkRail Executor THREE TIMES with scoped context:\n\n**Delegation 1 — Plan Analysis:**\n- routine: routine-plan-analysis\n- plan: implementation_plan.md\n- requirements: [From Phase 2 invariants + acceptance criteria]\n- constraints: [Filtered userRules: architecture, testing, patterns]\n- context (file-reference-first, max 500 words if pasting):\n  - Read: CONTEXT.md (userRules section), implementation_plan.md\n  - Read: spec.md, design.md (if exist)\n  - Invariants + locks (if locksMatrix exists)\n  - Feature brief: problem statement + architecture decision + key constraints\n- deliverable: plan-analysis.md\n\n**Delegation 2 — Hypothesis Challenge:**\n- routine: routine-hypothesis-challenge\n- rigor: 3\n- hypotheses: [Plan's key assumptions about architecture, dependencies, invariant satisfaction]\n- evidence: implementation_plan.md\n- context:\n  - Read: implementation_plan.md\n  - Filtered userRules: error handling, edge cases, validation rules\n  - Invariants (especially high-risk ones)\n  - Feature brief: problem + acceptance criteria + non-goals\n- deliverable: plan-challenges.md\n\n**Delegation 3 — Execution Simulation:**\n- routine: routine-execution-simulation\n- entry_point: [Riskiest slice entry function]\n- inputs: [Expected inputs and state]\n- trace_depth: 3 (follow calls to understand failure modes)\n- context:\n  - Read: implementation_plan.md (riskiest slice section)\n  - Filtered userRules: performance, data flow, state management\n  - Invariants touched by risky slice\n  - Feature brief: architecture decision + risk register\n- deliverable: simulation-results.md\n\n**Self-check before delegating (required):**\n✅ Each delegation includes filtered userRules (not full list)\n✅ Each includes invariants + locks (if applicable)\n✅ Each includes feature brief (file refs or <500 word excerpt)\n✅ Each has specific focus/lens\n\n**If subagents + `rigorMode=STANDARD`:**\nDelegate ONCE using Plan Analysis with full context (not filtered).\n\n\n**Note:** delegationMode was detected in phase-0c and cached in CONTEXT.md\n**Else:** self-audit (same three lenses).\n\n**Output:**\n- Findings: Critical / Major / Minor\n- Plan amendments\n\n---\n\n**CLEAN-SLATE CHECK (STANDARD+, if findings exist):**\n\nBefore applying amendments, briefly answer:\n\n> \"If I started fresh right now, knowing everything I've learned, would I choose the same approach?\"\n\n1. Without looking at current plan, sketch in 1 sentence what approach you'd take\n2. Compare to `selectedApproach`:\n   - **Same**: Proceed with amendments\n   - **Minor variation**: Note the insight; consider incorporating\n   - **Fundamentally different**: STOP. Set `cleanSlateDivergence = Major`\n\n**If fundamentally different:**\n- Document why fresh thinking differs\n- Return to Phase 3b with fresh approach as new candidate, OR\n- Document why current approach is still better despite fresh thinking\n\n---\n\n**REGRESSION CHECK (iteration 2+, if `resolvedFindings` is non-empty):**\n\nBefore running the forward-looking audit, verify each item in `resolvedFindings`:\n- Is the resolution still valid in the current plan?\n- Has the amendment been reverted or contradicted by subsequent changes?\n\nIf ANY regression found: add to `planFindings` with severity Critical and prefix \"REGRESSION: previously resolved finding reverted.\"\n\n---\n\n**PHILOSOPHY ALIGNMENT CHECK (mandatory, all modes):**\n\nReview the plan against the user's coding philosophy and design principles from `userRules`.\n\nThis evaluates DESIGN QUALITY — not plan consistency. Stale acceptance criteria, missing requirements, and coverage gaps are covered by the completeness audit above.\n\nIf no philosophy or design principles are found in `userRules`, skip this section and note \"No philosophy principles configured.\"\n\n**Required output format** (structured table):\nFor each violation or tension found:\n\n| Principle | Violation | Severity | Action |\n|-----------|-----------|----------|--------|\n| [Principle name from userRules] | [What violates it and why] | Red / Orange / Yellow | [Specific fix or justification needed] |\n\nSeverity guide:\n- **Red** (blocking) = must fix before implementation. Add to `planFindings`.\n- **Orange** (design quality) = should fix; document if intentionally accepted. Add to `planFindings`.\n- **Yellow** (tension) = tension between principles; document the tradeoff. Do NOT add to `planFindings` — these are informational only.\n\nChecklist — actively check: immutability, error handling model (Result/sealed vs exceptions), test doubles strategy (fakes vs mocks), dead code, naming clarity, abstraction level, type safety, exhaustiveness.\n\nIf NO violations found: explicitly state \"Philosophy check: no violations found\" with brief evidence (e.g., \"error handling uses Result<T> per philosophy; test doubles are fakes not mocks\"). Do NOT rubber-stamp. If you find zero violations on a non-trivial plan, double-check naming, dead code, and abstraction choices.\n\n**Set:** `planFindings`, `planAmendments`, `planConfidence` (1–10), `cleanSlateDivergence` (None/Minor/Major)",
           "requireConfirmation": false
         },
         {
           "id": "phase-5c-refocus-and-ticket-extraction",
           "title": "Refocus: Amendments + Tickets + Drift Detection",
-          "prompt": "Apply amendments and refocus.\n\n**Do:**\n- Update `planArtifact` + `implementationPlan` to incorporate `planAmendments`.\n- Extract out-of-scope work into `followUpTickets`.\n- Ensure plan follows `invariants` and stays slice-oriented.\n\n**Drift detection:**\n- If user introduced new constraints/preferences, update `userRules` and log in `CONTEXT.md`.\n\n**CONTEXT LOGGING:** Update CONTEXT.md Decision Log (follow format from metaGuidance) - record amendments accepted/rejected and why, user pushback, and scope/rules/verification drift\n\n**Set:** `followUpTickets`\n\n**VERIFY:** plan is coherent and PR-sized by slice.",
+          "prompt": "Apply amendments and refocus.\n\n**Do:**\n- Update `planArtifact` + `implementationPlan` to incorporate `planAmendments`.\n- Extract out-of-scope work into `followUpTickets`.\n- Ensure plan follows `invariants` and stays slice-oriented.\n\n**RESOLVED FINDINGS LEDGER (required):**\n\nWhen applying amendments, maintain the `resolvedFindings` context variable:\n- For each finding resolved in this iteration, add an entry: { finding: \"...\", resolution: \"...\", iteration: N }\n- Cap at 10 entries (if exceeded, drop oldest entries first)\n- This ledger carries forward to the next audit pass for regression checking\n\n**Set:** `resolvedFindings` (array, append new resolutions)\n\n**Drift detection:**\n- If user introduced new constraints/preferences, update `userRules` and log in `CONTEXT.md`.\n\n**CONTEXT LOGGING:** Update CONTEXT.md Decision Log (follow format from metaGuidance) - record amendments accepted/rejected and why, user pushback, and scope/rules/verification drift\n\n**Set:** `followUpTickets`\n\n**VERIFY:** plan is coherent and PR-sized by slice.",
           "requireConfirmation": {
             "or": [
               {

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

@@ -0,0 +1,257 @@
+{
+  "id": "coding-task-workflow-agentic",
+  "name": "Agentic Task Dev Workflow (v2 • Notes-First • WorkRail Executor)",
+  "version": "2.0.0",
+  "description": "A v2-first coding workflow that keeps the high-quality architecture and audit loops from the legacy task workflow while removing CONTEXT.md ceremony, Builder ownership, and unnecessary phase serialization. Uses notesMarkdown as the durable default, keeps implementation_plan.md as the human planning artifact, and applies the user's coding philosophy as the primary evaluation lens.",
+  "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."
+  ],
+  "clarificationPrompts": [
+    "What are the acceptance criteria and explicit non-goals?",
+    "What invariants must not change?",
+    "Are there rollout, migration, or environment constraints?",
+    "Are there existing repo patterns or examples that must be followed?"
+  ],
+  "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.",
+    "MAIN AGENT OWNS EXECUTION: the main agent owns strategy, decisions, synthesis, and implementation. Delegate only specific cognitive routines via the WorkRail Executor when the step explicitly tells you to.",
+    "SUBAGENT MODEL: use the WorkRail Executor only. Do not refer to or rely on named Builder/Researcher identities.",
+    "AUDITOR MODEL: prefer delegation for auditing, challenge, simulation, and ideation. Do not hand off full task ownership.",
+    "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 as the active 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.",
+    "VERTICAL SLICES: plan and implement as independently reviewable and verifiable slices. Parallelize only when targets do not overlap.",
+    "VALIDATION: prefer compile-time safety and deterministic verification. Use tests and type/build validation as the first-line proof.",
+    "TRIGGERS: WorkRail can only react to explicit fields the agent emits. Use narrow observable fields, not hidden introspection, to decide when fresh cognitive review is needed.",
+    "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-triage-and-mode",
+      "title": "Phase 0: Triage (Complexity • Risk • PR Strategy)",
+      "prompt": "Analyze the task and choose the right rigor.\n\nClassify:\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- `maxParallelism`: 0 / 3 / 4\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\nParallelism guidance:\n- QUICK: no delegation by default\n- STANDARD: few delegation moments, but allow multiple parallel executors at each moment\n- THOROUGH: same pattern, but with one extra delegation moment and broader parallel validation\n\nAlso capture `userRules` from the active session instructions and explicit philosophy. Keep them as a focused list of concrete, actionable rules.\n\nSet context variables: `taskComplexity`, `riskLevel`, `rigorMode`, `automationLevel`, `prStrategy`, `maxParallelism`, `userRules`.\n\nAsk the user to confirm only if the rigor or PR strategy materially affects delivery expectations.",
+      "requireConfirmation": true
+    },
+    {
+      "id": "phase-0b-minimum-inputs-gate",
+      "title": "Phase 0b: Minimum Inputs Gate",
+      "prompt": "If critical information is missing, ask only for the minimum required to proceed.\n\nAsk for:\n- acceptance criteria or expected behavior (if absent)\n- non-goals (if unclear)\n- environment or permission constraints (if they materially block progress)\n- pointers to relevant code areas only if codebase search cannot answer it\n\nDo NOT ask questions you can resolve with tools.",
+      "requireConfirmation": {
+        "or": [
+          { "var": "automationLevel", "equals": "Low" },
+          { "var": "automationLevel", "equals": "Medium" }
+        ]
+      }
+    },
+    {
+      "id": "phase-1-context-and-invariants",
+      "title": "Phase 1: Context + Invariants (Notes-First, Parallel-Aware)",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Build the minimum complete understanding needed to design correctly.\n\nDo the main context gathering yourself using tools. Read independent files in parallel when possible.\n\nDeliverable:\n- key entry points and call chain sketch\n- relevant files/modules/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\nSet context variables:\n- `contextSummary`\n- `candidateFiles`\n- `invariants`\n- `nonGoals`\n- `openQuestions`\n- `contextUnknownCount`\n- `contextAuditNeeded`\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- set `contextUnknownCount` to the number of unresolved technical unknowns that still matter\n- set `contextAuditNeeded` to true if understanding still feels incomplete or the call chain is still too fuzzy\n\nMode-adaptive audit:\n- QUICK: no delegation; self-check only\n- STANDARD: if `contextAuditNeeded = true` or risk is High and delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-context-gathering` with focus=COMPLETENESS and focus=DEPTH, then synthesize both outputs before finishing this step\n- THOROUGH: if delegation is available, spawn TWO WorkRail Executors SIMULTANEOUSLY running `routine-context-gathering` with focus=COMPLETENESS and focus=DEPTH, then synthesize both outputs before finishing this step",
+      "requireConfirmation": false
+    },
+    {
+      "id": "phase-1b-retriage-after-context",
+      "title": "Phase 1b: Re-Triage After Context",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Reassess the initial triage now that context is real instead of hypothetical.\n\nReview:\n- `contextUnknownCount`\n- number of systems/components actually involved\n- number of critical invariants discovered\n- whether the task now looks broader or riskier than Phase 0 suggested\n\nDo:\n- confirm or adjust `taskComplexity`\n- confirm or adjust `riskLevel`\n- confirm or adjust `rigorMode`\n- confirm or adjust `maxParallelism`\n\nRules:\n- upgrade rigor if the real architecture surface or uncertainty is larger than expected\n- downgrade only if the task is genuinely simpler than it first appeared\n- if you change the mode, explain why using concrete evidence from the context gathering step\n\nSet context variables:\n- `taskComplexity`\n- `riskLevel`\n- `rigorMode`\n- `maxParallelism`\n- `retriageChanged` (true/false)",
+      "requireConfirmation": {
+        "or": [
+          { "var": "retriageChanged", "equals": true },
+          { "var": "automationLevel", "equals": "Low" }
+        ]
+      }
+    },
+    {
+      "id": "phase-2-architecture-decision",
+      "title": "Phase 2: Architecture Decision (Generate • Compare • Challenge • Select)",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Make the architecture decision in one coherent phase instead of serializing every thinking mode into a separate step.\n\nPart A — Prepare a neutral fact packet:\n- problem statement\n- acceptance criteria\n- non-goals\n- invariants\n- constraints\n- `userRules`\n- relevant files / pattern examples\n- current risks and unknowns\n\nPart B — Generate candidate plans:\n- QUICK: self-generate at least 3 genuinely different approaches\n- STANDARD: if delegation is available, spawn TWO or THREE WorkRail Executors SIMULTANEOUSLY running `routine-plan-generation` with different perspectives (for example simplicity, maintainability, pragmatic)\n- THOROUGH: if delegation is available, spawn THREE or FOUR WorkRail Executors SIMULTANEOUSLY running `routine-plan-generation` with different perspectives (for example simplicity, maintainability, architecture-first, rollback-safe)\n\nPart C — Diversity gate before commitment:\n- assign each candidate plan a short `candidatePlanFamily` label\n- check whether the candidates are materially different in shape, not just wording\n- if all candidates cluster on the same pattern family, generate at least one more plan from a deliberately different perspective before selecting\n- set `candidateDiversityAdequate = true|false`\n\nPart D — Compare candidate plans:\n- invariant fit\n- philosophy alignment (`userRules` as active lens)\n- risk profile\n- implementation shape\n- likely reviewability / PR shape\n\nPart E — Challenge the best one or two:\n- STANDARD: optionally challenge the leading candidate with ONE WorkRail Executor running `routine-hypothesis-challenge`\n- THOROUGH: challenge the top 1-2 candidate plans using ONE or TWO WorkRail Executors running `routine-hypothesis-challenge`\n\nPart F — Decide:\nSet context variables:\n- `approaches`\n- `alternativesConsideredCount`\n- `candidatePlanFamilies`\n- `candidateDiversityAdequate`\n- `hasRunnerUp`\n- `selectedApproach`\n- `runnerUpApproach`\n- `architectureRationale`\n- `keyRiskToMonitor`\n- `pivotTriggers`\n- `architectureConfidenceBand`\n\nRules:\n- the main agent owns the final decision\n- subagents generate candidate plans; they do not decide the winner\n- if the challenged leading candidate no longer looks best, switch deliberately rather than defending sunk cost",
+      "requireConfirmation": {
+        "or": [
+          { "var": "automationLevel", "equals": "Low" },
+          { "var": "taskComplexity", "equals": "Large" },
+          { "var": "riskLevel", "equals": "High" }
+        ]
+      }
+    },
+    {
+      "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. Applied `userRules` and philosophy-driven constraints\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-iterations",
+      "type": "loop",
+      "title": "Phase 4: Plan Audit Loop (Audit → Refocus → Decide)",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "while",
+        "conditionSource": {
+          "kind": "artifact_contract",
+          "contractRef": "wr.contracts.loop_control",
+          "loopId": "plan_audit_loop"
+        },
+        "maxIterations": 5
+      },
+      "body": [
+        {
+          "id": "phase-4a-plan-audit",
+          "title": "Plan Audit (Correctness + Philosophy + Regression)",
+          "prompt": "Audit the plan before implementation.\n\nAlways perform:\n- completeness / missing work\n- weak assumptions and risks\n- invariant coverage\n- slice boundary quality\n- philosophy alignment against `userRules`\n- regression check against `resolvedFindings` (if present)\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- if no philosophy principles are configured, say so explicitly and continue\n\nRegression check:\n- if `resolvedFindings` is non-empty, verify previous resolutions still hold\n- if a previously resolved issue has reappeared, add a Critical regression finding\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\nParallel-output synthesis rules:\n- if 2+ auditors flag the same issue, treat it as high priority by default\n- if one auditor flags a concern no one else sees, investigate it but do not automatically block unless it is clearly severe\n- if outputs conflict, document the conflict explicitly and resolve it before finalizing `planFindings`\n- if philosophy review yields Red findings and no stronger conflicting evidence exists, they must remain blocking\n\nSet context variables:\n- `planFindings`\n- `planAmendments`\n- `planConfidence`\n- `cleanSlateDivergence`\n- `planFindingsCountBySeverity`\n- `philosophyFindingsCountBySeverity`\n- `auditConsensusLevel`\n\nRules:\n- use the main agent as synthesizer and final decision-maker\n- do not delegate sequentially when the audit routines are independent",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-4b-refocus",
+          "title": "Refocus Plan and Track Resolved Findings",
+          "prompt": "Apply plan amendments and refocus.\n\nDo:\n- update `implementation_plan.md` to incorporate `planAmendments`\n- update `slices` if the plan shape changed\n- extract out-of-scope work into `followUpTickets`\n- maintain `resolvedFindings` as an array of { finding, resolution, iteration }\n- cap `resolvedFindings` at 10 entries, dropping oldest first\n\nSet context variables:\n- `resolvedFindings`\n- `followUpTickets`\n\nRule:\n- do not silently accept plan drift; if the audit changed the shape of the work, reflect it in the plan artifact immediately",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-4c-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    \"loopId\": \"plan_audit_loop\",\n    \"decision\": \"continue\"\n  }]\n}\n```",
+          "requireConfirmation": true,
+          "outputContract": {
+            "contractRef": "wr.contracts.loop_control"
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-5-planning-ready-gate",
+      "title": "Phase 5: Planning Ready Gate",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Verify that planning is complete enough to start implementation.\n\nRequired checks:\n- selected approach and rationale exist\n- runner-up exists\n- pivot triggers are concrete enough to act on\n- slices are defined with scope, verification, and boundaries\n- `implementation_plan.md` reflects the current intended work\n- no unresolved planning gaps remain that would block implementation\n- `alternativesConsideredCount` shows real exploration happened\n\nSet context variables:\n- `planningGaps`\n- `planningComplete`\n\nRule:\n- if any gap can be fixed immediately, fix it now and do not carry it forward as a gap\n- only stop for user input when a true decision is missing",
+      "requireConfirmation": {
+        "or": [
+          { "var": "automationLevel", "equals": "Low" },
+          { "var": "taskComplexity", "equals": "Large" },
+          { "var": "riskLevel", "equals": "High" }
+        ]
+      }
+    },
+    {
+      "id": "phase-6-small-task-fast-path",
+      "title": "Phase 6: 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-7-implement-slices",
+      "type": "loop",
+      "title": "Phase 7: Implement Slice-by-Slice",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "loop": {
+        "type": "forEach",
+        "items": "slices",
+        "itemVar": "currentSlice",
+        "indexVar": "sliceIndex",
+        "maxIterations": 20
+      },
+      "body": [
+        {
+          "id": "phase-7a-slice-preflight",
+          "title": "Slice Preflight",
+          "prompt": "Before implementing slice `{{currentSlice.name}}`, verify:\n- pivot triggers have not fired\n- the plan assumptions are still fresh enough\n- target files and symbols still match the plan\n- the slice remains reviewable and bounded\n\nSet context variables:\n- `pivotTriggered`\n- `pivotSeverity`\n- `pivotReturnPhase`\n- `slicePlanStale`\n- `validationFailed`\n\nIf drift or invalid assumptions are discovered, stop and return to planning deliberately rather than coding through it.",
+          "requireConfirmation": {
+            "or": [
+              { "var": "pivotTriggered", "equals": true },
+              { "var": "slicePlanStale", "equals": true },
+              { "var": "validationFailed", "equals": true }
+            ]
+          }
+        },
+        {
+          "id": "phase-7b-implement-slice",
+          "title": "Implement Slice",
+          "prompt": "Implement slice `{{currentSlice.name}}`.\n\nMain-agent-first rules:\n- the main agent owns implementation\n- do not hand off slice ownership to a Builder identity\n- if you need specialized help, delegate only targeted cognitive routines via the WorkRail Executor (for example challenge, simulation, philosophy review, or plan analysis), 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\nDuring implementation, explicitly track whether the slice required:\n- a new special-case (`specialCaseIntroduced`)\n- an unplanned abstraction (`unplannedAbstractionIntroduced`)\n\nIf this slice uses work packages, use them as guidance, not ceremony.",
+          "requireConfirmation": false
+        },
+        {
+          "id": "phase-7c-verify-slice",
+          "title": "Verify Slice",
+          "prompt": "Verify slice `{{currentSlice.name}}`.\n\nAlways:\n- run planned verification commands\n- update or add tests when needed\n- ensure invariants still hold\n- check philosophy-alignment regressions introduced by the implementation\n\nFresh-eye validation triggers:\n- if `specialCaseIntroduced = true`\n- if `unplannedAbstractionIntroduced = true`\n- if this slice touched unexpected files\n- if runtime behavior still feels uncertain\n\nMode-adaptive validation:\n- QUICK: self-verify unless a fresh-eye trigger fires\n- STANDARD: if delegation is available and any fresh-eye trigger fires, spawn TWO or THREE WorkRail Executors SIMULTANEOUSLY running `routine-hypothesis-challenge`, `routine-execution-simulation`, and optionally `routine-philosophy-alignment`\n- THOROUGH + high-risk or any fresh-eye trigger: if delegation is available, spawn FOUR WorkRail Executors SIMULTANEOUSLY running `routine-hypothesis-challenge`, `routine-execution-simulation`, `routine-plan-analysis`, and `routine-philosophy-alignment`\n\nParallel-output synthesis rules:\n- if 2+ validators independently raise the same serious concern, treat it as blocking by default\n- if exactly one validator raises a concern, attempt to understand and resolve it before escalating\n- if validators disagree, record the disagreement explicitly and prefer the safer path when uncertainty remains high\n\nSet context variables:\n- `sliceVerified`\n- `verificationFindings`\n- `verificationFailed`\n- `verificationApprovalRequired`\n- `verificationRetried`\n- `verificationConcernCount`\n- `verificationConsensusLevel`\n\nRule:\n- if 2+ independent validators raise serious concerns, stop and return to planning or ask the user which path to take",
+          "requireConfirmation": {
+            "or": [
+              { "var": "verificationApprovalRequired", "equals": true },
+              { "var": "verificationFailed", "equals": true }
+            ]
+          }
+        },
+        {
+          "id": "phase-7d-drift-and-pr-gate",
+          "title": "Drift and PR Gate",
+          "prompt": "After a verified slice:\n- compare actual changed scope against the slice plan\n- if the slice drifted, update `implementation_plan.md` immediately and record the reason in notes\n- if `prStrategy = MultiPR`, stop here with a concise PR package for user review before continuing\n\nSet context variables:\n- `planDrift`\n- `rulesDrift`\n- `changedFilesOutsidePlannedScope`\n- `scopeDriftDetected`\n\nRule:\n- do not rely on markdown sidecar state; notesMarkdown is the durable recap and `implementation_plan.md` is the human artifact",
+          "requireConfirmation": {
+            "or": [
+              { "var": "prStrategy", "equals": "MultiPR" },
+              { "var": "planDrift", "equals": true },
+              { "var": "rulesDrift", "equals": true }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      "id": "phase-8-integration-verification",
+      "title": "Phase 8: Integration Verification",
+      "runCondition": {
+        "var": "taskComplexity",
+        "not_equals": "Small"
+      },
+      "prompt": "Perform final integration verification.\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 still aligns with the user's coding philosophy, naming any tensions explicitly\n- review cumulative drift across all slices, not just the current one\n- check whether repeated small compromises added up to a larger pattern problem\n\nSet context variables:\n- `integrationVerificationPassed`\n- `integrationVerificationFailed`\n- `integrationVerificationFindings`\n- `regressionDetected`\n- `invariantViolations`\n- `crossSliceDriftDetected`",
+      "requireConfirmation": {
+        "or": [
+          { "var": "integrationVerificationFailed", "equals": true },
+          { "var": "regressionDetected", "equals": true }
+        ]
+      }
+    },
+    {
+      "id": "phase-9-final-handoff",
+      "title": "Phase 9: Final Handoff",
+      "prompt": "Provide final validation and handoff.\n\nInclude:\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\nRules:\n- keep the final handoff concise and executive-level\n- `implementation_plan.md` should only be updated if slices or boundaries changed during execution\n- do not auto-merge or push unless the user explicitly asks",
+      "requireConfirmation": true
+    }
+  ]
+}

package/workflows/routines/feature-implementation.json

@@ -2,7 +2,7 @@
   "id": "routine-feature-implementation",
   "name": "Feature Implementation Routine",
   "version": "1.0.0",
-  "description": "Implements code precisely according to detailed plans and specifications. Follows existing patterns, writes tests, and maintains code quality. Designed for delegation to Builder subagent or manual execution by main agent.",
+  "description": "Implements code precisely according to a detailed approved plan within a bounded scope. Follows existing patterns, writes tests, and maintains code quality. Intended as an optional execution utility, not the default strategy for the main coding workflow.",
   "clarificationPrompts": [
     "What plan file should I implement? (e.g., implementation-plan.md)",
     "What files should I modify or create?",
@@ -18,9 +18,9 @@
   ],
   "metaGuidance": [
     "**ROUTINE PURPOSE:**",
-    "This routine implements code following a detailed plan. It emphasizes precision, pattern adherence, incremental progress, and thorough testing.",
+    "This routine implements code following a detailed plan within a tightly bounded scope. It emphasizes precision, pattern adherence, incremental progress, and thorough testing.",
     "**CORE PRINCIPLES:**",
-    "- FOLLOW THE PLAN: Implement exactly as specified, don't improvise",
+    "- FOLLOW THE PLAN: Implement exactly as specified, don't improvise architecture",
     "- MATCH PATTERNS: Follow existing codebase conventions",
     "- TEST AS YOU GO: Write tests for each step before moving on",
     "- FLAG AMBIGUITIES: Don't guess, ask for clarification",
@@ -32,7 +32,8 @@
     "**IMPLEMENTATION STRATEGY:**",
     "Read-Implement-Test: For each step, read the plan, implement the code, write tests, verify tests pass, then move to next step",
     "Incremental Verification: After each step, check compilation, tests, and pattern adherence",
-    "Flag Early: If you encounter ambiguity, missing patterns, or conflicts, stop and flag immediately"
+    "Flag Early: If you encounter ambiguity, missing patterns, or conflicts, stop and flag immediately",
+    "INTENDED USE: best for approved, low-ambiguity, bounded work where the main agent wants execution help rather than fresh strategic thinking"
   ],
   "steps": [
     {

package/workflows/routines/philosophy-alignment.json

@@ -0,0 +1,62 @@
+{
+  "id": "routine-philosophy-alignment",
+  "name": "Philosophy Alignment Routine",
+  "version": "1.0.0",
+  "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?"
+  ],
+  "preconditions": [
+    "A review artifact is available",
+    "Philosophy principles or user rules are available",
+    "Relevant files or references are available if needed for evidence",
+    "Agent has read access to the supplied artifact and supporting files"
+  ],
+  "metaGuidance": [
+    "PURPOSE: evaluate design quality against named philosophy principles.",
+    "ROLE: you are an auditor, not a generator or implementer.",
+    "FINDINGS: report by principle name, never as generic style feedback.",
+    "SEVERITY: distinguish Red violations, Orange issues, and Yellow tensions.",
+    "TENSIONS: if principles conflict, surface the conflict explicitly instead of silently choosing."
+  ],
+  "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.",
+      "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",
+      "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",
+      "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",
+      "agentRole": "You are surfacing real trade-offs instead of flattening them into fake certainty.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-deliver",
+      "title": "Step 5: Deliver the Philosophy Review",
+      "prompt": "Create `{deliverableName}`.\n\nRequired structure:\n- Executive Summary\n- Findings by Principle\n- Red Violations\n- Orange Issues\n- Yellow Tensions\n- Missing Justifications\n- Overall Verdict (Aligned / Revise / Blocked)\n- Recommended Next Actions\n\nRules:\n- use principle names directly\n- avoid generic wording like \"clean this up\" without tying it to a principle\n- be explicit about what is a tension versus a true violation",
+      "agentRole": "You are delivering a clear philosophy review that the main agent can act on directly.",
+      "requireConfirmation": false
+    }
+  ]
+}

package/workflows/routines/plan-generation.json

@@ -0,0 +1,63 @@
+{
+  "id": "routine-plan-generation",
+  "name": "Plan Generation Routine",
+  "version": "1.0.0",
+  "description": "Generates a complete candidate implementation plan from a neutral fact packet. Designed for parallel use across multiple perspectives so the main agent can compare or synthesize plans.",
+  "clarificationPrompts": [
+    "What problem should this plan solve?",
+    "What acceptance criteria, invariants, and constraints must it respect?",
+    "What perspective should this plan optimize for? (simplicity, maintainability, architecture-first, rollback-safe, pragmatic, performance)",
+    "What artifact name should I produce?"
+  ],
+  "preconditions": [
+    "Problem statement is available",
+    "Acceptance criteria and non-goals are available",
+    "Invariants and constraints are available",
+    "Relevant files, patterns, or references are available",
+    "Agent has read access to the provided context"
+  ],
+  "metaGuidance": [
+    "PURPOSE: generate one complete implementation plan from a factual packet.",
+    "ROLE: you are a generator, not an auditor or implementer.",
+    "PERSPECTIVE: optimize for the requested lens without pretending other trade-offs do not exist.",
+    "OUTPUT: produce a coherent plan another engineer could evaluate or implement.",
+    "SELF-CRITIQUE: include why your plan might be wrong or where another plan may be better."
+  ],
+  "steps": [
+    {
+      "id": "step-understand-problem",
+      "title": "Step 1: Understand the Planning Problem",
+      "prompt": "Understand the task before proposing a plan.\n\nRead and summarize:\n- problem statement\n- acceptance criteria\n- non-goals\n- invariants\n- constraints\n- user rules / coding philosophy\n- relevant files and pattern examples\n\nIdentify:\n- the core architectural decision points\n- the main risk areas\n- the trade-off space implied by the requested perspective\n\nWorking notes:\n- Problem summary\n- Hard constraints\n- Architecture decision points\n- Risks to plan around\n- Perspective lens to optimize for",
+      "agentRole": "You are understanding the planning problem deeply before proposing a solution.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-choose-plan-strategy",
+      "title": "Step 2: Choose a Plan Strategy",
+      "prompt": "Choose a plan strategy for the requested perspective.\n\nDecide:\n- what this plan optimizes for\n- what trade-offs it accepts\n- what the overall implementation shape should be\n- how work should be sliced for reviewability and verification\n\nWorking notes:\n- Optimization target\n- Accepted trade-offs\n- Overall plan shape\n- Slicing strategy\n- Verification posture",
+      "agentRole": "You are selecting the planning strategy that best fits the requested perspective.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-generate-plan",
+      "title": "Step 3: Generate the Candidate Plan",
+      "prompt": "Generate a complete candidate implementation plan.\n\nThe plan must include:\n1. Problem statement\n2. Acceptance criteria\n3. Non-goals\n4. Applied constraints and user rules\n5. Invariants\n6. Proposed approach\n7. Slice plan\n8. Verification / test strategy\n9. Risk register\n10. PR packaging strategy\n11. Philosophy alignment highlights\n\nRules:\n- be concrete enough that another engineer could implement it without guessing\n- make real sequencing and scoping choices\n- avoid vague \"investigate later\" placeholders unless explicitly justified\n- cite relevant files or examples when they materially shape the plan",
+      "agentRole": "You are generating a complete and concrete candidate implementation plan.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-self-critique",
+      "title": "Step 4: Self-Critique the Plan",
+      "prompt": "Critique your own plan before delivering it.\n\nAssess:\n- what this plan is strongest at\n- where it is weak\n- which invariants are hardest to preserve\n- where implementation drift is most likely\n- what a rival plan might do better\n\nWorking notes:\n- Strengths\n- Weaknesses\n- Highest-risk assumptions\n- Most likely failure modes\n- Better rival-plan scenarios",
+      "agentRole": "You are honestly critiquing your own generated plan to make it useful for comparison.",
+      "requireConfirmation": false
+    },
+    {
+      "id": "step-deliver",
+      "title": "Step 5: Deliver the Candidate Plan",
+      "prompt": "Create `{deliverableName}`.\n\nRequired structure:\n- Executive Summary\n- Perspective / Optimization Target\n- Candidate Implementation Plan\n- Slice Plan\n- Verification Strategy\n- Risk Register\n- Philosophy Alignment Highlights\n- Why This Plan Might Be Wrong\n- Recommended Questions for the Main Agent to Resolve\n\nThe main agent will compare this plan against other candidate plans, so optimize for clarity, completeness, and honest trade-off documentation rather than persuasion.",
+      "agentRole": "You are delivering a complete candidate plan for the main agent to compare or synthesize.",
+      "requireConfirmation": false
+    }
+  ]
+}