| name | mx-flow |
| description | Full development workflow orchestrator: brainstorm → plan → scope analysis → worktree → convergent TDD/review loop → verify → PR. One human gate (spec approval); all other gates auto-proceed. Use when starting a new feature or significant change from scratch. Usage: /mx-flow <topic>; /mx-flow finish <name> for post-merge cleanup.
|
| author | Maxence Yang |
| github | https://github.com/maxence2997/mx-harness |
| source | https://github.com/maxence2997/mx-harness/tree/main/mx-flow |
| user-invocable | true |
| allowed-tools | ["Bash","Read","Glob","Grep","Edit","Write","Agent","Task"] |
mx-flow
Trigger
/mx-flow <topic> ← full pipeline: idea to PR
/mx-flow finish <name> ← post-merge cleanup (read references/finish.md and follow it)
Non-negotiables
Violating any of these is a workflow failure. They bind every phase and
every sub-agent this skill dispatches.
- Worktree before any code edit — before making any code change,
verify the working directory is a git worktree
(
git rev-parse --git-dir contains worktrees/). If not, STOP and run
Phase 4 first.
- Iron Law — no production code without a failing test first. Code
written before its test exists must be deleted and reimplemented after
the test is in place. No exceptions.
- Never weaken a gate to get green — no
--no-verify, no lint
suppressions to silence a finding, no deleting/skipping a failing test,
no rewriting a RED test to match broken behavior, no relaxed assertions,
no widened timeouts. A gate fighting you is a design signal: apply the
wrong-direction rubric (doctrine below) — change approach or ask.
- Review before verify — do not enter Phase 6 unless mx-team-review
and mx-review-triage have run on the current branch diff at least once
in this session. If unsure, check for a review report in
.mx/<name>/tmp/.
- Retry budget — the same task failing verification twice (regardless
of approach) → stop retrying. In a harness with sub-agents, escalate to
the strongest tier with the full failure trail (what was tried, exact
diffs, exact errors); otherwise present that trail to the user with
concrete options. Never a third identical attempt. (Small-tier/haiku
workers get only ONE attempt before escalating — counting rule:
mx-doctrine model-dispatch §6.)
Gates
mx-flow pauses at one human gate (spec approval). All other gates
auto-proceed — reports are still shown for visibility. Gates are review
opportunities, not "y/n continue" prompts.
| Gate | Behaviour |
|---|
| GATE 1 — Spec | Human. Show the draft spec; discuss and adjust until the user explicitly confirms. Do not proceed without approval. |
| GATE 2 — Task list | Auto. Show the task list for visibility, then proceed immediately. |
| GATE 3 — Triage | Auto. Show the triage report, auto-approve all "fix" items, execute immediately. |
| GATE 4 — PR | Auto. Draft and publish the PR autonomously; show the draft for visibility. Pause only if the agent cannot determine how to proceed (no remote, ambiguous platform, missing credentials). |
The convergent-loop safety limit (3 iterations, Phase 5) always applies —
its escalation requires human input regardless.
Orchestrated sub-skills: the sub-skills this flow invokes contain
their own interactive pauses. This gate table overrides those pauses at
GATE 2/3/4. From their side: mx-team-review, mx-review-triage, and mx-pr
each carry an "Orchestrated mode" section stating the same; mx-commit is
orchestrated by passing --auto (no section needed); mx-brainstorm's only
pause is GATE 1, which stays human.
Doctrine
Shared execution doctrine ships in the sibling mx-doctrine skill. Paths
resolve as ${CLAUDE_SKILL_DIR}/../mx-doctrine/references/<file> — if a
file is missing (partial install), say so once and use the fallback noted
at each reference site.
model-dispatch.md — model tiers for every sub-agent this flow spawns
(§4 has a table of mx-flow's dispatch sites); escalation ladder (§6).judgment-rubrics.md — when done is done (§2), when to stop and ask
(§3), wrong-direction signals (§4), quality floor (§5).delegation-templates.md — prompt shapes if you need an ad-hoc
sub-agent beyond the ones this file specifies.
Fallback when mx-doctrine is absent: dispatch execution sub-agents at the
mid tier (sonnet), decisions/reviews at the strongest available; apply
the Non-negotiables above literally.
Overview
Phase 1 Brainstorm → Design spec + ADR (/mx-brainstorm)
[GATE 1] Spec approval ← human (only hard gate)
Phase 2 Plan → Ordered task list (built-in)
Phase 3 Scope → Plan audit: order, split, complexity (built-in)
Phase 4 Worktree → Isolated branch + baseline (built-in)
── convergent loop (max 3 iterations) ──────────────
Phase 5a TDD (per task) → Commit (built-in + /mx-commit)
Phase 5b Review → Triage (/mx-team-review + /mx-review-triage)
→ if fixes: back to TDD
→ if clean: exit loop
────────────────────────────────────────────────────
Phase 6 Verify → Tests + plan + content check (built-in)
Phase 7 PR → Draft → publish (/mx-pr)
Phase 8 Finish → Clean up branch + worktree (references/finish.md, post-merge)
Path resolution
All phases use two base directories. Resolve them once at the start.
REPO_ROOT=$(git rev-parse --show-toplevel)
PROJECT=$(basename "$REPO_ROOT")
| Variable | Path | Contains |
|---|
GLOBAL_MX | ~/.mx/<project>/<name>/ | spec.md, adr.md (permanent) |
LOCAL_MX | <repo-root>/.mx/<name>/ | plan.md, scope.yaml, worktree/, tmp/ (ephemeral) |
~/.mx/<project>/ai-learning.md is also in GLOBAL (project-level, not per-feature)- Create directories as needed:
mkdir -p for both GLOBAL_MX and LOCAL_MX
- On Windows:
GLOBAL_MX = %USERPROFILE%\.mx\<project>\<name>\
Phase 0 — Initialize
Before anything else:
- Derive the feature name from the topic (kebab-case, ≤ 4 words).
Example:
write-timeout-error-propagation
- Resolve GLOBAL_MX and LOCAL_MX per the path resolution section above
- Create both directories if they do not exist
- Check
.gitignore — ensure .mx/ is gitignored:
if [ ! -f "$REPO_ROOT/.gitignore" ]; then
echo '.mx/' > "$REPO_ROOT/.gitignore"
elif ! grep -q '^\.mx/$' "$REPO_ROOT/.gitignore"; then
echo '.mx/' >> "$REPO_ROOT/.gitignore"
fi
If .gitignore was created or modified, commit it:
git add .gitignore && git commit -m "chore: add .mx/ to .gitignore"
- Read relevant context — based on the topic, use Glob and Read to
collect information the brainstorm will need:
- Files, modules, or packages mentioned explicitly in the topic
- Related code that is likely in scope (e.g. if topic mentions a
component, read adjacent files)
- Any design docs, behaviour specs, or CLAUDE.md files that apply
- Read broadly enough that the first brainstorm question is grounded in
actual code
- Announce clearly:
mx-flow started
Feature : <feature-name>
Spec : ~/.mx/<project>/<name>/spec.md (will be written after GATE 1)
Plan : .mx/<name>/plan.md
Phase : 1 — Brainstorm
Do this before asking any questions or writing any files.
Phase 1 — Brainstorm
Run /mx-brainstorm with the following context:
- The GLOBAL_MX directory has already been created in Phase 0
- The topic is already provided — begin asking clarifying questions
immediately, do not ask if the user wants to start
Follow mx-brainstorm's full procedure. It owns the spec and ADR output
(written to GLOBAL_MX).
GATE 1: Present the draft spec. Do not proceed until the user
explicitly confirms.
Phase 2 — Plan
Decompose the approved spec into a concrete, ordered task list.
Planning principles
These bind every task you write in this phase. The TDD loop in Phase 5
executes the plan literally — if the plan over-reaches, the implementation
will too. Lock scope here, not later.
Simplicity first — minimum code that satisfies the spec.
- No tasks beyond what the spec requires.
- No abstractions, interfaces, or "flexibility" layers the spec did not
ask for.
- No error handling for impossible scenarios.
- No speculative configuration, feature flags, or extension points "for
the future".
- If a single function would do, do not invent a class. If a class would
do, do not invent a package.
Surgical changes — touch only what the spec requires.
- Do not plan to "improve" adjacent code, comments, or formatting that the
spec did not call out.
- Do not plan refactors of code that is not broken.
- Match existing style and structure even if a different style would be
your preference.
- If you notice unrelated dead code or technical debt, mention it once to
the user — do not silently add a cleanup task.
- Orphans your tasks create (now-unused imports, variables, helpers)
must be cleaned in the same task. Pre-existing dead code is out of
scope unless the user approves.
The test for every task: it traces directly to a sentence in the spec. If
it does not, drop it or ask the user.
2.1 — Read the design spec
Read GLOBAL_MX/spec.md in full.
Also read relevant existing code (entry points, interfaces, test files) to
understand the current structure before decomposing.
2.2 — Decompose into tasks
Break the spec into the smallest tasks where each task:
- Implements one behavior (not a file, not a layer)
- Maps to one commit type (
feat, fix, refactor, test, chore, doc)
- Has a concrete expected test: what to write, what it verifies,
expected output
- Can be committed independently without breaking the build
Forbidden content in any task:
TBD or TODO- "similar to Task N"
- "add error handling" (without specifying what error and how)
- "update tests" (without specifying which behavior)
- Pseudo-code or vague descriptions
Task format:
### Task N — <type>: <subject (≤ 50 chars)>
**What**: <one sentence describing the behavior added or changed>
**Test**: <what test to write — file, scenario, expected result>
**Files**: <which files will change>
2.3 — Order the tasks
Order tasks so that:
- Infrastructure / scaffolding comes first
- Each task builds on previous ones without requiring future tasks
- Tests for a behavior come in the same task as the implementation (not
before, not after)
2.4 — Write the plan
Write LOCAL_MX/plan.md:
# <name> — Plan
> Design spec: ~/.mx/<project>/<name>/spec.md
## Tasks
- [ ] Task 1 — feat: <subject>
- [ ] Task 2 — test: <subject>
- [ ] Task 3 — fix: <subject>
Show the full task breakdown (with Task N details) to the user for review.
GATE 2: Show the task list for visibility, then proceed immediately.
Announce: Task list auto-approved.
Allow the user to add, remove, reorder, or rewrite tasks if they intervene
before auto-proceed.
Phase 3 — Scope analysis
Audit the plan before any code is written: read the spec, the plan, and
the repo, then verify every task is grounded in real files and symbols,
correctly ordered, and cut at the right granularity — fixing plan.md
where it is not. The audit's machine-readable record is
.mx/<name>/scope.yaml. This phase runs
inline in the parent, autonomously — no sub-agent by default, no user
gate; print a one-line summary at the end for visibility.
Why inline (2026-07-15): by the end of Phase 2 the spec, the plan, and
the relevant code are already in the parent's context — a sub-agent has
to rebuild all of it from disk, and the dispatch round-trips were
observed to cost more wall-clock than the analysis itself. Canonical
rule: mx-doctrine model-dispatch §2 (do inline).
Never skip this phase — it is the last cheap place to catch a bad task
split. A vague or oversized task found here costs one plan edit; found
in Phase 5 it costs TDD rounds against the retry budget. Phase 5 also
reads scope.yaml per task as advisory context (where to look first,
how much effort to expect).
3.1 — Audit (inline)
Work from what Phases 1–2 already put in context. Re-read
GLOBAL_MX/spec.md or LOCAL_MX/plan.md only if they are no longer in
context (compacted or resumed session).
- Confirm, don't explore: per task, use targeted Glob/Grep to pin down
the files and symbols it will touch — verify a predicted path exists,
locate the module that owns a function. Phase 2.1 already did the
broad reading; do not start repo-wide exploration here.
- For each task in plan.md, infer the schema fields below (3.2), scoring
complexity against the rubric (3.3)
- Audit the split, and fix
plan.md directly where it fails — rewriting
and renumbering is safe here, nothing has executed yet:
- Ordering: every
depends_on must point to an earlier task. A
forward dependency → reorder the plan.
- Too big: one task hiding several behaviors (an L whose
predicted_touches don't relate, or a What that needs "and") →
split it into one-behavior tasks per the Phase 2.2 rules.
- Overlap: two tasks predicting the same file+symbol with no
depends_on between them → add the missing dependency, or merge
them if they are really one behavior.
- Vague: cannot pin the task to files/symbols → mark
vague: true;
the refinement pass (3.4) handles it.
- Write
.mx/<name>/scope.yaml directly, keeping the counts (vague,
reordered, split, merged) for the 3.6 summary.
Escape hatch — delegate only on context loss. If the spec and plan
are NOT in context AND re-acquiring the repo picture would exceed the
inline-reading limits in model-dispatch §2's delegate table (the
Explore rows), dispatch ONE Explore
sub-agent (mid tier) briefed with: the spec path, the plan path, the repo
root, the schema (3.2), the rubric (3.3), and a directive — read-only
analysis, return the complete scope YAML as your final message. The
parent writes .mx/<name>/scope.yaml from that returned YAML (Explore
sub-agents cannot write files) and applies step 3's plan fixes itself
from the returned metadata. One dispatch maximum; the refinement pass
(3.4) never re-dispatches.
3.2 — Schema
- id: task-1
task: "<verbatim copy of plan.md bullet>"
predicted_files:
- internal/cache/adapter.go
- internal/cache/adapter_test.go
predicted_touches:
- RedisClient.Get
- RedisClient.Set
depends_on: []
complexity: M
complexity_reason: "two new files, ~80 LOC, follows existing adapter pattern"
vague: false
vague_reason: ""
depends_on should reflect either shared files (two tasks edit the
same file → ordering matters) or logical preconditions (task B calls a
symbol introduced by task A). When unsure, add the dependency rather than
omit it.
3.3 — Complexity rubric
| Level | Criteria |
|---|
| S | ≤ ~30 LOC, single file, predicted 1 TDD round, no external integration |
| M | ~30–150 LOC, 2–3 files, predicted 1–2 TDD rounds, may touch one integration boundary |
| L | > 150 LOC, multi-module, ≥ 2 TDD rounds expected, or non-trivial external integration (DB / network / filesystem / external API) |
When signals are ambiguous, bias toward higher complexity and more
dependencies. Over-estimating costs nothing; under-estimating hides a
task that should have been split and burns TDD rounds against the retry
budget.
3.4 — Refinement pass (max 2 passes)
After the first pass, inspect scope.yaml for vague: true entries.
Pass 1 → Pass 2. If any task is vague, rewrite those specific bullets
in plan.md using vague_reason as guidance — name the file(s), the
function/endpoint, the interface contract; a targeted Read/Grep to settle
the open question is fine. Then re-infer those tasks only. Tasks that
were not vague stay untouched.
After Pass 2. The result is final. Any task still marked vague: true
keeps its conservative default (complexity: L) and proceeds. Bouncing
further has diminishing returns — the task is one that requires hands-on
discovery during TDD.
Cap is 2 passes. Never loop indefinitely, and never re-dispatch the
escape-hatch sub-agent for refinement — resolve vagueness inline or apply
the defaults.
3.5 — Fallback on failure
If the analysis cannot produce valid YAML for every task (unparseable
plan, or the escape-hatch sub-agent timed out, crashed, or returned
invalid YAML), write a minimal scope.yaml directly:
- id: task-N
task: "<copy from plan.md>"
predicted_files: []
predicted_touches: []
depends_on: []
complexity: L
complexity_reason: "scope analysis failed; conservative default applied"
vague: true
vague_reason: "scope analysis failed; safe fallback applied"
Every task gets the same shape. Downstream phases treat the plan as
unaudited and proceed in plan order. The flow does not block.
3.6 — Summary
Print one line to the user for visibility (not a gate):
Scope audit: <N> tasks — <V> rewritten (vague), <R> reordered, <P> split, <G> merged; complexity <a>S/<b>M/<c>L.
If the plan needed no fixes:
Scope audit: <N> tasks, split confirmed — no fixes needed; complexity <a>S/<b>M/<c>L.
If the fallback fired:
Scope audit: failed → conservative defaults recorded, plan proceeds unaudited.
Then auto-proceed to Phase 4.
Phase 4 — Worktree
Create an isolated git worktree for the feature branch.
4.1 — Determine branch name
Apply branch naming convention:
| Change type | Prefix |
|---|
| New feature | feat/<name> |
| Bug fix | bugfix/<name> |
| Quick fix (config, docs, CI) | fix/<name> |
| Maintenance, deps, tooling | chore/<name> |
If the user provided a name without a prefix, ask which prefix applies.
If the name already has a correct prefix, proceed.
4.2 — Create the worktree
First, resolve the base branch in this order:
- Check if
develop exists (local or remote):
git rev-parse --verify develop 2>/dev/null || git rev-parse --verify origin/develop 2>/dev/null
- If found → use
develop as base
- Otherwise, check if
main exists:
git rev-parse --verify main 2>/dev/null || git rev-parse --verify origin/main 2>/dev/null
- If found → use
main as base
- If neither exists → ask the user which branch to base from
Then create the worktree under LOCAL_MX:
git worktree add .mx/<name>/worktree -b <branch-name> <base-branch>
Verify it was created:
git worktree list
4.3 — Run project setup
From within the worktree directory, auto-detect and run setup:
cd .mx/<name>/worktree
if [ -f go.mod ]; then go mod download; fi
if [ -f package.json ]; then
if [ -f pnpm-lock.yaml ]; then pnpm install
elif [ -f yarn.lock ]; then yarn install
else npm install; fi
fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
if [ -f Cargo.toml ]; then cargo build; fi
4.4 — Verify baseline
Run the full test suite to confirm the worktree starts clean.
Auto-detect the runner in this priority order (this is the canonical
runner-detection rule — Phases 5 and 6 reuse it):
Makefile with a check or test target → make check or make testpackage.json with a test script → npm test / yarn test / pnpm test- Language detection:
.go → go test ./..., .rs → cargo test,
.py → pytest, .cs → dotnet test, .swift → swift test
If baseline fails:
Report the failures and ask the user whether to proceed or investigate
first. Do not proceed silently with a failing baseline.
4.5 — Report
Worktree ready at .mx/<name>/worktree/
Branch : <branch-name>
Baseline: <N> tests passing
Phase 5 — Convergent loop
5a — TDD cycle (per task, serial in the parent)
Execute the plan one task at a time, in plan order, in the parent — do
not dispatch tasks to sub-agents. A task sub-agent rebuilds context the
parent already holds warm, and parallel local execution only overlaps
model time while multiplying machine costs (per-worktree setup, full
test suites contending for the same cores); its failure paths re-ran
tasks serially anyway. Parallel batch dispatch was removed 2026-07-15 —
lesson recorded in mx-doctrine model-dispatch §2.
Phase 3's audit validated the ordering, so plan order satisfies every
depends_on. Before starting a task, read its scope.yaml entry as
advisory context: predicted_files/predicted_touches say where to
look first, complexity sets the effort expectation. If scope.yaml
is missing, proceed in plan order without the hints.
Philosophy: Vertical Slices Only
WRONG (horizontal slicing):
RED: test1, test2, test3
GREEN: impl1, impl2, impl3 ← never do this
RIGHT (vertical slices):
RED → GREEN: test1 → impl1
RED → GREEN: test2 → impl2
RED → GREEN: test3 → impl3
Writing tests in bulk produces tests that verify imagined behavior, not
actual behavior. Each test must respond to what you learned from the
previous cycle.
For each [ ] task in the plan:
Read the task — Read LOCAL_MX/plan.md and identify the next [ ]
task. Read its full specification (What, Test, Files). Read the relevant
existing code before writing anything.
Tracer bullet (first task only) — For the first task of a new feature,
write one minimal test that proves the end-to-end path works — even if it
only touches a stub. This confirms the test infrastructure is wired
correctly before building out.
Red: write the failing test — Write the test as specified in the task.
Test quality rules:
- Tests verify behavior through public interfaces, not implementation
details
- A good test reads like a specification: "user can do X given Y"
- The test must fail before any production code is written
- Run the test and observe the failure — if it passes immediately, the
test is wrong
Run it with the runner from Phase 4.4. Confirm the test fails with the
expected error (missing symbol, assertion failure, etc.). A test that
passes without implementation proves nothing.
Green: minimal implementation — Write the simplest code that makes
the test pass.
Rules:
- Only enough code to pass the current test
- Do not anticipate future tests
- Do not add features not required by the current test
- Speculative code is forbidden
Comment policy (enforced while writing, not only at review) —
Canonical source:
${CLAUDE_SKILL_DIR}/../mx-team-review/references/principles.md →
P2 — Comment (Why). Essentials:
- Default: no comment. Add one only when WHY is non-obvious to a
future reader.
- Forbidden: comments that restate WHAT the code does, empty doc
summaries (
/// Creates an order.), vague pronouns (this,
the above, as mentioned).
- Required for: magic numbers, framework-default overrides,
business-rule enforcement, external workarounds (link the issue),
TODO/FIXME (link or explain why and when).
- Style: lead with WHY, name the concrete subject + triggering
scenario, hard limit 3 lines. If it needs more, the code probably
needs to change instead.
If you find yourself writing a "WHAT" comment, delete it and improve the
identifier name instead.
Run the test again — confirm it passes.
Run the full suite — confirm nothing else broke.
If GREEN won't come — the same task failing twice triggers
Non-negotiable 5 (retry budget). Weakening the test to pass is
Non-negotiable 3. There is no third identical attempt.
Refactor — Only after GREEN, look for improvements:
- Extract duplication
- Improve naming
- Simplify logic
- Apply existing patterns from the codebase
Rules:
- Never refactor while RED
- Run tests after each refactor step — if anything breaks, revert
immediately
- Refactor is optional; skip if the code is already clean
Exit condition checklist — Before marking the task done, verify all
six conditions:
□ RED observed: test failure was seen with actual output (not assumed)
□ GREEN confirmed: test passes after implementation
□ Full suite clean: no new failures introduced by this change
□ Comment policy: no WHAT-comments, no vague pronouns, magic numbers/workarounds explain WHY, every comment ≤3 lines
□ Plan updated: task marked [x] in .mx/<name>/plan.md
□ Committed: /mx-commit --auto completed for this task
If any item is unchecked, do not advance to the next task.
After each task completes, take the next [ ] task in plan order. Exit
to 5b when all tasks are done or a milestone is reached.
5b — Review (at milestone)
Run /mx-team-review on the diff since the branch was created, using the
base branch resolved in Phase 4.2:
git diff $(git merge-base HEAD <base-branch>)..HEAD
Run /mx-review-triage with --source review directly (no auto-detect).
GATE 3: Show the triage summary, auto-approve all "fix" items, execute
immediately (commits go through /mx-commit --auto). "Track" items are
still written to TODOS.md and "Skip" items noted in the report — both
without pausing. Announce: Triage auto-approved — executing <N> fixes.
After fixes are applied:
- If fixes were made → run the test suite → back to 5a for any new tasks,
increment iteration counter
- If clean (no fixes needed) → exit the loop
Loop safety limit
The convergent loop has a maximum of 3 iterations (one iteration = one
full tdd → review → triage cycle).
If the loop reaches 3 iterations without converging to clean:
[ESCALATE] Convergent loop has not resolved after 3 iterations.
Current state:
Iteration: 3/3
Remaining findings: <list>
Options:
[A] Continue — extend the loop (you take responsibility)
[B] Redesign — the findings suggest a design issue; revisit ~/.mx/<project>/<name>/spec.md (design spec)
[C] Abort — discard this branch and start fresh
Three iterations without convergence usually indicates a design problem,
not a code problem.
Do not continue automatically. Wait for the user to choose.
Phase 6 — Verify and commit
Final verification gate. No partial checks accepted.
6.1 — Run full test suite
Run the complete test suite with the runner from Phase 4.4. No partial
runs.
Read the full output. Count failures.
If any test fails: report the failures with output, stop. Do not
proceed.
If all pass: state the count explicitly: N tests passing, 0 failures.
6.2 — Check plan completion
Read LOCAL_MX/plan.md.
For every task line, verify its status:
[x] — completed[ ] — pending
If any task is still [ ], list them and stop. Do not claim completion
with open tasks.
If all tasks are [x], report: All N tasks complete.
6.3 — Remind ai-learning
Show this reminder:
Update ~/.mx/<project>/ai-learning.md before closing this session.
Format:
| Date | Issue or Learning | Root Cause | Prevention Rule |
| ---------- | ----------------- | ---------- | --------------- |
| YYYY-MM-DD | <what happened> | <why> | <how to avoid> |
Record at least one entry — even if no mistakes were made.
Acceptable entries: techniques confirmed, observations, rules verified.
6.4 — Gate result
Only if 6.1 and 6.2 both pass:
Verification passed.
Tests: N passing, 0 failures
Plan: N/N tasks complete
Ready to commit and push.
If verification passes, run /mx-commit --auto for any remaining staged
changes.
6.5 — Content check (autonomous cleanup)
Clean the branch history before the PR phase: two autonomous passes —
Pass 1 removes net-zero churn (commits/hunks that cancel each other on
the branch), Pass 2 folds small fixups into their logical parent. Each
pass is guarded by a tree-hash invariant and reverts itself on any
mismatch. No user prompt.
Execute the canonical procedure: read and follow
${CLAUDE_SKILL_DIR}/../mx-pr/references/content-check.md, with
<base-branch> = the base branch resolved in Phase 4.2 (if that value is
no longer in context, re-derive it with the same develop-then-main rule).
If the content-check file is missing, announce Content-check reference missing — skipping here; Phase 7 will run mx-pr's own copy if mx-pr is installed and proceed to Phase 7 without rewriting any history.
Phase 6 ends here. Proceed to Phase 7.
Abort path
When verification fails, present three recovery options:
[VERIFICATION FAILED]
<specific failure: test output / open tasks>
Recovery options:
[A] Investigate — return to Phase 5a to fix the failing test or task
Re-entry: specify which task or failing test to address first
[B] Adjust plan — the failure reveals that a task definition was wrong
Re-entry: edit .mx/<name>/plan.md, then re-run Phase 5a for that task
[C] Abort branch — this branch is not recoverable
Will preserve: ~/.mx/<project>/<name>/spec.md and adr.md (design spec)
Will discard: .mx/<name>/plan.md
Reminder: git worktree remove .mx/<name>/worktree
Wait for the user to choose. Do not attempt to fix anything automatically.
Phase 7 — PR
Run /mx-pr (if the mx-pr skill is not installed, tell the user the flow
ends here and hand them the branch name and base branch — do not improvise
a PR). It will:
- Run the content check again (no-op if Phase 6.5 already cleaned)
- Draft the PR description from the spec and git log
- Publish or hand off
GATE 4 applies: auto-proceed — draft the PR and publish directly. Show
the draft for visibility but do not wait for confirmation (mx-pr's
"Orchestrated mode" section defers to this gate). Only pause and ask the
user if:
- No git remote is configured
- Multiple remotes exist and the target is ambiguous
- Platform credentials are missing or authentication fails
- Any other situation where the agent cannot determine the correct action
Announce: PR auto-published.
After /mx-pr completes (published or skipped), announce:
mx-flow complete.
After merge: /mx-flow finish <name>
Phase 8 — Finish (post-merge cleanup)
Triggered by /mx-flow finish <name>, independently from the main
pipeline. Read ${CLAUDE_SKILL_DIR}/references/finish.md and follow it in
full.
Summary of what it does: confirm the PR is merged → delete plan.md and
scope.yaml → preserve the spec and ADR under ~/.mx/<project>/<name>/ →
clean .mx/<name>/tmp/ (user picks) → git worktree remove (never
--force automatically) → git branch -d (never -D automatically) →
summary. If the reference file is missing, follow this summary literally
and stop at any git refusal to ask the user.
