maestro-flow 0.4.2 → 0.4.3

package/workflows/execute.md

@@ -6,6 +6,33 @@ Core principle: **Execute per-plan, not per-phase.** Each plan's wave DAG runs i
 
 ---
 
+## Iron Law
+
+**VERIFY EACH TASK OUTPUT BEFORE MARKING COMPLETE.**
+
+Every task completion requires:
+1. Run convergence criteria checks (not just code review)
+2. Confirm output matches task definition expectations
+3. Evidence of verification in the task summary
+
+No task may be marked "completed" based on agent self-report alone.
+
+---
+
+## Red Flags — These Thoughts Mean STOP
+
+If you catch yourself thinking any of these, STOP and verify:
+
+- "The agent said it's done, so it must be done"
+- "I'll batch-verify all tasks at the end instead of per-task"
+- "This task is too simple to need verification"
+- "The warning isn't relevant, I'll ignore it"
+- "Let me mark it complete and fix the issue later"
+
+All of these mean: **run convergence criteria check NOW before marking the task complete**.
+
+---
+
 ## Prerequisites
 
 - Plan exists in scratch directory: `plan.json` + `.task/TASK-*.json`

package/workflows/plan.md

@@ -47,6 +47,7 @@ OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
 | `--dir <path>` | Use arbitrary directory instead of phase resolution (skip roadmap validation) |
 | `--revise [instructions]` | Revise existing plan (skip P1-P3, load → modify → P4). Auto-discovers latest plan or use `--dir` |
 | `--check <plan-dir>` | Standalone plan verification (P4 only, read-only) |
+| `--tdd` | Generate TDD task chains (RED-GREEN-REFACTOR triplets). Load `@~/.maestro/workflows/tdd.md` for discipline and task structure |
 
 ---
 
@@ -55,9 +56,19 @@ OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
 ```
 --check <plan-dir>  → Check Mode (P4 only, read-only)
 --revise            → Revise Mode (load → modify → P4)
+--tdd               → TDD Mode: P1 → P2 → P3 (with TDD task chain generation) → P4 → P4.5 → P5
 default             → Create Mode: P1 → P2 → P3 → P4 → P4.5 → P5
 ```
 
+### TDD Mode
+
+When `--tdd` is active:
+1. Read `@~/.maestro/workflows/tdd.md` for TDD discipline, Iron Law, and task chain structure
+2. In P3 (Planning), decompose each behavior into RED-GREEN-REFACTOR triplets per `tdd.md § Task Chain Generation`
+3. Set `plan.json.tdd_mode = true` and include `tdd_groups[]`
+4. Wave assignment follows TDD dependency rules: `{N}a → {N}b → {N}c`
+5. Output is standard plan.json + .task/TASK-*.json — consumable by `maestro-execute` without modification
+
 ---
 
 ## P1: Context Collection

package/workflows/review.md

@@ -4,6 +4,37 @@ Tiered multi-dimensional code review with parallel agents, severity classificati
 
 ---
 
+## Spec Compliance Pre-Check (Phase 0)
+
+**Before any dimensional code quality review**, verify the implementation matches its spec:
+
+1. Load `convergence.criteria[]` from each `.task/TASK-{NNN}.json` in the phase
+2. For each criterion, check if the code implements it (grep for functions, endpoints, components named in the criterion)
+3. Classify each: **MET** (evidence found) | **UNMET** (not implemented) | **PARTIAL** (incomplete)
+
+| Result | Action |
+|--------|--------|
+| All MET | Proceed to Step 1 (dimensional review) |
+| Any UNMET | Report as spec_compliance_failures, add to findings with severity=critical, dimension="spec-compliance" |
+| Any PARTIAL | Report with severity=high |
+
+This prevents code that is well-written but doesn't meet requirements from passing review.
+
+---
+
+## Receiving Review Feedback
+
+When external review feedback is received (from human reviewers, PR comments, or other agents):
+
+1. **Verify before implementing** — Check each suggestion against codebase reality. Reviewer may lack full context.
+2. **Technical acknowledgment only** — No performative agreement ("You're absolutely right!", "Great point!"). Just state the fix or provide technical reasoning.
+3. **Push back when wrong** — If a suggestion would break existing functionality, violate architecture constraints, or is technically incorrect for this codebase, explain why with evidence.
+4. **YAGNI check** — If reviewer suggests adding a feature/abstraction, verify it's actually needed. Unused features should be questioned.
+5. **Implement one at a time** — Fix one item, test, then move to next. Never batch-implement all feedback at once.
+6. **Priority order** — Blocking issues (breaks, security) → Simple fixes (typos, imports) → Complex fixes (refactoring, logic).
+
+---
+
 ## Prerequisites
 
 - Phase execution completed (task summaries exist)
@@ -428,7 +459,8 @@ Next steps:
 |---------|------------|
 | PASS | Skill({ skill: "quality-test", args: "{phase}" }) for UAT, or Skill({ skill: "maestro-milestone-audit" }) if UAT already passed |
 | WARN | Review findings, then Skill({ skill: "quality-test", args: "{phase}" }) — acknowledge warnings before proceeding |
-| BLOCK | Fix critical issues first: Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) -> Skill({ skill: "maestro-execute", args: "{phase}" }) -> re-run Skill({ skill: "quality-review", args: "{phase}" }) |
+| BLOCK (≤3 findings, all medium/low) | **Lightweight fix loop**: fix inline → re-run review on affected files only → repeat until PASS/WARN (max 2 iterations) |
+| BLOCK (>3 findings or any critical) | Full fix cycle: Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) -> Skill({ skill: "maestro-execute", args: "{phase}" }) -> re-run Skill({ skill: "quality-review", args: "{phase}" }) |
 
 ---
 

package/workflows/tdd.md

@@ -0,0 +1,257 @@
+# TDD Workflow
+
+Test-Driven Development discipline for plan generation and execution. Invoked when `maestro-plan --tdd` is used. Transforms feature requirements into RED-GREEN-REFACTOR task chains that `maestro-execute` can consume.
+
+---
+
+## Iron Law
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.**
+
+Write code before the test? Delete it. Start over.
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Delete means delete
+
+---
+
+## Red-Green-Refactor Cycle
+
+Every feature/behavior follows this mandatory sequence:
+
+```
+RED: Write failing test → verify it fails correctly
+GREEN: Write minimal code to pass → verify ALL tests pass
+REFACTOR: Clean up → verify tests still pass
+```
+
+Each cycle produces exactly 3 tasks in the plan. No steps may be skipped or merged.
+
+---
+
+## Red Flags — These Thoughts Mean STOP
+
+- "This is too simple to need TDD"
+- "I'll write tests after to verify"
+- "Let me explore the implementation first, then add tests"
+- "I'll keep the code as reference and write tests first"
+- "TDD will slow me down"
+- "I already manually tested this"
+- "Tests after achieve the same goals"
+
+All of these mean: **follow the cycle anyway**.
+
+---
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing — you never saw them catch the bug. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc != systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Need to explore first" | Fine. Throw away exploration, start fresh with TDD. |
+| "Test hard = design unclear" | Listen to the test. Hard to test = hard to use. Simplify the interface. |
+| "TDD will slow me down" | TDD is faster than debugging in production. |
+
+---
+
+## Task Chain Generation
+
+When `maestro-plan --tdd` is active, each behavior/feature decomposes into a TDD triplet:
+
+### Structure
+
+For each behavior B (derived from requirements or convergence criteria):
+
+```
+TASK-{N}a: RED — Write failing test for B
+TASK-{N}b: GREEN — Implement minimal code to pass B
+TASK-{N}c: REFACTOR — Clean up B implementation (optional, skip if nothing to clean)
+```
+
+### TASK-{N}a: RED — Write Failing Test
+
+```json
+{
+  "id": "TASK-{N}a",
+  "title": "RED: Write failing test for {behavior}",
+  "type": "test",
+  "action": "Write test that describes expected behavior. Test MUST fail before implementation exists.",
+  "implementation": [
+    "Identify the behavior to test from requirement",
+    "Write one minimal test — one behavior per test, clear name",
+    "Use real code, not mocks (unless external dependency)",
+    "Run test: verify it FAILS (not errors) with expected failure message",
+    "If test passes: wrong test — testing existing behavior, fix test",
+    "If test errors: fix error, re-run until it fails correctly"
+  ],
+  "convergence": {
+    "criteria": [
+      "Test file exists at {test_path}",
+      "Test run exits non-zero (test fails, not errors)",
+      "Failure message matches expected behavior gap"
+    ],
+    "verification": "Run test command, confirm RED status (failure, not error)"
+  },
+  "meta": {
+    "tdd_phase": "red",
+    "tdd_group": "{N}"
+  }
+}
+```
+
+### TASK-{N}b: GREEN — Write Minimal Code
+
+```json
+{
+  "id": "TASK-{N}b",
+  "title": "GREEN: Implement minimal code for {behavior}",
+  "type": "feature",
+  "depends_on": ["TASK-{N}a"],
+  "action": "Write the simplest code that makes the failing test pass. No features beyond what the test requires.",
+  "implementation": [
+    "Read the failing test to understand exactly what is needed",
+    "Write minimal production code — just enough to pass",
+    "Do NOT add features, refactor other code, or improve beyond the test",
+    "Do NOT add options, configurability, or flexibility not required by test",
+    "Run test: verify it PASSES",
+    "Run full test suite: verify no regressions (all other tests still pass)",
+    "If test fails: fix code, NOT test",
+    "If other tests fail: fix now"
+  ],
+  "convergence": {
+    "criteria": [
+      "Test from TASK-{N}a passes (exit 0)",
+      "Full test suite passes (no regressions)",
+      "No warnings or errors in test output"
+    ],
+    "verification": "Run test command, confirm GREEN status (all pass, clean output)"
+  },
+  "meta": {
+    "tdd_phase": "green",
+    "tdd_group": "{N}"
+  }
+}
+```
+
+### TASK-{N}c: REFACTOR — Clean Up
+
+```json
+{
+  "id": "TASK-{N}c",
+  "title": "REFACTOR: Clean up {behavior} implementation",
+  "type": "refactor",
+  "depends_on": ["TASK-{N}b"],
+  "action": "Remove duplication, improve names, extract helpers. Keep tests green. Do NOT add behavior.",
+  "implementation": [
+    "Review code from TASK-{N}b for duplication, naming, structure",
+    "Apply refactoring while keeping ALL tests green",
+    "Remove duplication across the new and existing code",
+    "Improve variable and function names for clarity",
+    "Extract helpers only if reuse is immediate (not speculative)",
+    "Run full test suite after each refactoring step",
+    "If any test fails during refactoring: undo last change, re-run"
+  ],
+  "convergence": {
+    "criteria": [
+      "Full test suite passes (same as GREEN, no regressions)",
+      "No new behavior added beyond what tests cover"
+    ],
+    "verification": "Run full test suite, confirm still GREEN"
+  },
+  "meta": {
+    "tdd_phase": "refactor",
+    "tdd_group": "{N}"
+  }
+}
+```
+
+---
+
+## Wave Assignment
+
+TDD triplets are sequential within each group but groups can parallelize if independent:
+
+```
+Wave 1: TASK-1a (RED for feature A),  TASK-2a (RED for feature B)    — parallel if independent
+Wave 2: TASK-1b (GREEN for feature A), TASK-2b (GREEN for feature B)  — parallel
+Wave 3: TASK-1c (REFACTOR for A),     TASK-2c (REFACTOR for B)       — parallel
+```
+
+Within a group, the dependency chain is always: `{N}a → {N}b → {N}c`.
+
+---
+
+## Integration with plan.json
+
+When `--tdd` is active, the plan.json output includes:
+
+```json
+{
+  "tdd_mode": true,
+  "tdd_groups": [
+    {
+      "group": 1,
+      "behavior": "User can login with email and password",
+      "tasks": ["TASK-1a", "TASK-1b", "TASK-1c"]
+    }
+  ]
+}
+```
+
+The standard `plan.json.waves[]` and `.task/TASK-*.json` structure is preserved — `maestro-execute` consumes it without modification.
+
+---
+
+## Execution Enforcement
+
+When `maestro-execute` processes a TDD plan (detected by `plan.json.tdd_mode == true`):
+
+### RED task verification
+- After TASK-{N}a completes, verify test exists AND fails
+- If test passes: mark task BLOCKED with reason "Test passes before implementation — wrong test"
+
+### GREEN task verification
+- After TASK-{N}b completes, verify ALL tests pass
+- If the RED test still fails: mark task BLOCKED, provide failure output
+- If other tests regress: mark task BLOCKED, list regressed tests
+
+### REFACTOR task verification
+- After TASK-{N}c completes, verify ALL tests still pass
+- If any test fails: undo changes, mark as needing re-attempt
+
+---
+
+## Good Tests
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One thing per test. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear** | Name describes behavior | `test('test1')`, `test('it works')` |
+| **Shows intent** | Demonstrates desired API | Obscures what code should do |
+| **Real code** | Uses actual implementations | Mocks everything, tests mock behavior |
+
+---
+
+## When to Skip REFACTOR
+
+TASK-{N}c (REFACTOR) may be omitted from the plan when:
+- GREEN code is already clean (no duplication, good names)
+- The change is truly trivial (single-line fix)
+
+When skipped, mark in plan.json: `"refactor_skipped": true, "reason": "GREEN code already clean"`
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No test framework detected | Abort: "No test infrastructure found. Set up testing first." |
+| RED test passes immediately | BLOCKED: "Test passes before implementation — rewrite test" |
+| GREEN test still fails after implementation | Retry once with more context, then BLOCKED |
+| REFACTOR breaks tests | Undo refactoring, mark as BLOCKED |
+| Cannot write meaningful test | AskUserQuestion: "Behavior '{B}' is hard to test. Should we: (1) simplify the interface, (2) skip TDD for this behavior, (3) use integration test instead?" |

package/workflows/verify.md

@@ -4,6 +4,63 @@ Dual verification: Goal-Backward structural verification + Nyquist test coverage
 
 ---
 
+## Iron Law
+
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE IN THIS MESSAGE.**
+
+Before any success/completion claim:
+1. IDENTIFY — What command proves this claim?
+2. RUN — Execute the FULL command (fresh, in this message — never cite prior runs)
+3. READ — Read FULL output, check exit code, count failures
+4. VERIFY — Does the output actually confirm the claim?
+5. ONLY THEN — Make the claim, with evidence inline
+
+---
+
+## Forbidden Wording
+
+These phrases are BANNED in verification reports and completion claims:
+- "Should work now"
+- "Probably passes"
+- "Seems correct"
+- "Looks good"
+- "I'm confident that..."
+- "Based on my review, this is complete"
+- Any expression of satisfaction BEFORE running verification commands
+
+Replace with evidence: `"Tests pass: 42/42 green (exit 0)"`, `"All 5 truths VERIFIED with file:line evidence"`.
+
+---
+
+## Red Flags — These Thoughts Mean STOP
+
+If you catch yourself thinking any of these, STOP and run verification first:
+
+- "I just wrote this code, it definitely works"
+- "The changes are too small to break anything"
+- "I already verified this earlier in the conversation"
+- "The tests passed before, they'll pass now"
+- "I can see from the code that it's correct"
+- "Let me just mark this complete and move on"
+
+All of these mean: **run the verification command NOW, read the output, then report**.
+
+---
+
+## Rationalization Table
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "I just made a one-line change" | One-line changes cause the most insidious bugs |
+| "Tests passed earlier" | Code changed since then — earlier results are stale |
+| "I can read the code is correct" | Reading is not running — subtle runtime errors are invisible in code review |
+| "The build succeeded" | Build success ≠ functional correctness |
+| "It works for the happy path" | Edge cases, error paths, and boundary conditions need verification too |
+| "Verification would take too long" | Skipping verification costs more time when bugs surface later |
+| "The agent said it's done" | Agent reports are claims, not evidence — verify independently |
+
+---
+
 ## Prerequisites
 
 - Phase execution completed (or partially completed)