القائمة
Claude Code command: /mma-flow — MMA-native design-to-merged-code SDLC playbook that resumes from durable artifacts
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Use when a grounded idea needs to be grilled into a formal spec — runs a relentless one-decision-at-a-time requirement interview, resolving mechanical questions via workers and putting only real decisions to the user, then dispatches mma-spec. Not for grounding a raw idea (use mma-explore first) or for work where a spec already exists (use mma-plan).
Use when you have an ad-hoc implementation or research task WITHOUT a plan file on disk and you want it to run on a cheap worker instead of consuming main-context tokens
Use when a plan or spec file exists on disk (any markdown with task headings — .mma/plans/*.md, a TODO list, a spec doc) and you need to implement one or more tasks from it sequentially in one worker session
Use when a raw idea or problem needs grounding before it's designed — captures a braindump, fans out divergent internal-codebase investigation + external research + prior-learnings recall in parallel, then synthesises the results into a written exploration.md (Background · Current State · Rough Direction). Not for "where is X" single-answer questions (use mma-investigate).
Use when you're about to design or attempt something and want to know what THIS project already learned — ask a vague conceptual question (no tags or keywords needed); a read-only worker searches the learnings graph and returns the relevant prior lessons + how they relate. Fire before re-treading ground that may already have been explored. NOT for recording a new learning (mma-journal-record), codebase questions (mma-investigate), or external research (mma-research).
Use when you've learned something worth remembering — a decision, design rationale, user behavior pattern, process learning, research finding, or style convention. Records it to the persistent team knowledge graph for future sessions.
| name | mma-flow |
| description | Claude Code command: /mma-flow — MMA-native design-to-merged-code SDLC playbook that resumes from durable artifacts |
| when_to_use | User explicitly invokes /mma-flow. This is a Claude Code command, not an auto-matched skill. |
| version | 0.0.0-unreleased |
A Claude Code command (the user types /mma-flow) that orchestrates the MMA SDLC
from idea to merged PR. Not a server endpoint, not an auto-matched skill, not
available on other clients — invoked explicitly. Its only input is the initial
brain dump (the user's raw idea), taken directly at invocation and fed to D1. A
bare invocation (no braindump — headless cron, or the user just typed the
command) takes nothing: Stage 0 LOCATE picks up from the durable artifacts on disk. A
braindump naming work already on disk resumes that flow; a braindump naming NEW work
starts a fresh flow even when unrelated artifacts exist (see Stage 0 — LOCATE).
mma-flow is a thin orchestrator. It runs the stages in order; at each stage it does only three things:
SKILL.md; it is the source of how. mma-flow
never re-explains a skill's internals.prompt and which ride
a file (target.paths).Everything else — how explore fans out, what a journal entry should capture, how an audit weighs findings — lives in that skill, not here. mma-flow carries only the stage order, the wiring, and the flow-level policy (the Common blocks).
Every worker dispatch is POST /task?cwd=<repo-root>; poll GET /task/:taskId to a
terminal 200. "Main agent" = you, in-session; "worker" = a delegated MMA task.
Wire shorthand: exploration.md / spec / plan mean the current dated artifact
under .mma/…/ (LOCATE resolves the exact file); <scratchpad> is your session temp
dir, outside any repo, for throwaway dispatch scaffolds.
.mma/explorations/<stem>.md (mints the stem — see Common: Artifact stem)<scratchpad>/decisions.md, exploration.md] (1st authoritative, 2nd grounding; decisions.md is a throwaway tmp scaffold)
title → prompt ; optional subset → components[].mma/specs/<stem>.md (inherited from the dated exploration source — no outputPath threaded).mma/plans/<stem>--<repo-slug>.md under the parent (single repo: <stem>.md)mma/<slug> branch in each target repomma/<slug> ; gh pr create --base <that repo's source branch>gh pr merge --mergeRun on every invocation. Read durable evidence from disk and resume at the earliest stage not yet complete for all target repos. Session-local evidence (a clean review, whole-repo green) isn't durable — if only that is missing after an interruption, fall back to the nearest durable gate (B6 or B7). This is deliberate: LOCATE resolves the durable BOUNDARIES (spec, plan, branch, commits, PR, merge) from disk/git; audit/review/verify/journal are session-local, so a fresh-session resume re-runs them (safe and idempotent) rather than trusting stale session state. A repo skipped at B8 (no writable remote) is recorded in the backlog so LOCATE won't re-select it forever.
Braindump vs. resume — decide this first. Before consulting the table, settle
which flow LOCATE is even acting on. /mma-flow is invoked either with a braindump
argument or bare, and that argument decides new-vs-resume:
.mma/explorations/ +
.mma/specs/ for an artifact covering THAT work:
<existing slug> or start fresh, then proceed. This is
the one permitted setup-only stop (Common: Never-halt) — never guess.The table below then applies to the SELECTED flow's artifacts (a NEW flow has neither exploration nor spec, so it lands on the D1 row).
| Resume signal (durable git/disk + session-local) | Resume |
|---|---|
| No exploration and no spec | D1 |
| Exploration, no spec | D2 → D3 |
| Spec, no plan | B1 → B2 |
Plan, but not every target repo has an mma/<slug> branch | B3 (if plan not audited this session) → B4 |
| Every repo branched; some repo has no commits past its source branch | B5 |
| Every repo has commits; no clean review this session (all repos) | B6 |
| Review clean this session; whole-repo green not yet proven (all repos) | B7 |
| Green proven (all repos); some repo has no PR and isn't backlog-skipped | B8 |
| Some repo's PR open, not merged | B9 |
| Every repo merged or backlog-skipped; no journal this session | B10 |
| Every repo merged or backlog-skipped; journal recorded this session | done |
Multi-artifact: once the braindump-vs-resume decision has selected a flow, resolve its
exact files by stem under .mma/…/ (Common: Artifact stem — same stem end to end, so
this is an exact match, not a fuzzy one). If the user's current message points at a
specific artifact, use it. A bare resume with several flows on disk defaults to the
most-recent spec under .mma/specs/ and the plan sharing its stem. Artifact roots
resolve in the primary repo.
Escalating gate, hard cap 5 rounds, never halts. Each round is judged on its OWN findings — applying fixes never clears the gate; only a fresh round that comes back within threshold does.
| Round | Advance when the round's own findings have… |
|---|---|
| 1–3 | 0 critical AND 0 high |
| 4–5 | 0 critical (high tolerated → backlog) |
proceed: false — the flow never stops here.The flow never halts on content — audit/review/verification findings, missing credentials, deferred decisions all drain to the backlog and the flow advances. It may stop only on unresolved setup ambiguity it cannot decide autonomously (missing repo path, branch-name collision) — never on a finding or a decision.
Backlog: one file — .mma/backlogs/<stem>.json in the primary repo (same stem as the
rest of the chain — see Common: Artifact stem).
.mma/ is gitignored — see Common: Fixes inline).{ item, assumptionMade, blastRadius, blockedWork }.The audit/review PASS runs on a worker; the FIX does not. The main agent applies
every fix directly with Edit on the real file — never via mma-delegate or
mma-execute-plan.
Why: those are worktree routes — the worker edits a copy that git merges back.
Spec/plan artifacts live under .mma/, which is gitignored, so the merge silently
discards the edits (and the worker still reports success) → the loop never
converges. B6 targets tracked source, where inline Edit also applies cleanly —
keep it inline for consistency.
If a fix is genuinely too large for inline, route it through a worktree:false
type (orchestrate), which edits in place — never delegate/execute_plan.
Bump the version each fix round. The .mma/ design artifacts (exploration, spec,
plan) carry YAML frontmatter (version + updated_at). After applying a round's fixes
to a spec (B1) or plan (B3), increment that file's version by 1 and set updated_at
to today's date — once per round, after the round's edits, not once per finding. So
version: N means the artifact survived N-1 audit-fix rounds. A round that clears the
gate with zero findings makes no edit and no bump.
<slug> = the slug half of the stem (Common: Artifact stem) — the same string across
artifacts and branch. The branch is never slugged independently; read it off the
exploration/spec filename.
Per repo (see Common: Multi-repo):
srcBranch=$(git -C <repo> rev-parse --abbrev-ref HEAD) # B4
git -C <repo> checkout -b mma/<slug>
git -C <repo> push -u origin mma/<slug> # B8
gh pr create --base <srcBranch> --head mma/<slug> # B8, run from <repo>
gh pr merge <n> --merge # B9
PR title: build(<slug>): <one-line spec summary>.
Open a repo's PR only after B7 passes for that repo this session.
srcBranch is captured at B4 for in-session use. On a fresh-session resume it's gone,
so default --base to the repo's default branch (origin/HEAD). Branching from a
non-default source isn't guaranteed to survive resume — note it in the brain dump if
it matters.
B8 prerequisites (per repo): writable origin on GitHub · gh authenticated ·
source branch still on the remote. Any missing → backlog entry, skip that repo's
PR, continue with the rest (Common: Never-halt).
The product may be one repo or several sibling repos under a parent workspace. Which one you're in is DETECTED, not declared.
Topology detection (run once, at flow start). Enumerate the immediate child
directories of the invocation cwd and test each for a .git entry (file OR directory).
Detection does not recurse into subdirectories and does not follow symlinks — it
only inspects immediate child directories.
CLAUDE.md is optional context enrichment only (what each sub-project is). Its absence
never blocks detection or the flow; detection is purely structural.
Involved-repo confirmation (multi-repo mode, before D1 investigation/recall). Propose
the detected git children as the involved repo set and let the user confirm, remove a
repo, or ADD a non-git immediate child directory (path-confined: reject any ..,
absolute path, or non-immediate-child). If the confirmed set is empty or invalid,
re-prompt — never proceed. If two child names normalize to the same lowercase-kebab
slug (a slug collision), halt and re-prompt for explicit disambiguating slug overrides
before proposing the set — plan filenames and journal topics must stay unique.
Parent owns everything (multi-repo mode). The parent workspace owns the entire
.mma/ tree — journal, explorations, specs, plans, backlogs — reached by dispatching the
design/journal legs with cwd = parent workspace. Forge durable design docs go to the
parent design/<stem>.md (only when that step runs), never a child repo. Sub-repos hold
code, branches, and PRs only.
One spec → one plan per repo (fan-out at B2). One shared spec captures the goal.
Fan out one mma-plan dispatch per involved repo — each scoped to exactly one repo,
each writing .mma/plans/<stem>--<repo-slug>.md under the parent. B3 audits each per-repo
plan; B5 dispatches each repo's own plan. This is one plan per repo, not one combined
plan (see mma-plan).
Journal scoping. Journal record + recall run against the parent journal with
topic = <repo-slug> (lowercase-kebab) so product-level knowledge slices per repo.
Per-target git, B4–B9. Each involved target is handled by its own git status:
execute_plan (worktree) → review → verify → PR → merge.execute_plan runs in-place (no worktree, edits the folder
directly); skip branch/PR/merge and record delivered in-place, no PR (non-git target)
in the backlog. Git is never forced. B5 still copies each secondary repo's plan into its
cwd for the worker (copyToWorktree is cwd-relative); the parent/single repo needs no copy.Barrier per stage: finish a stage across ALL involved repos before advancing; LOCATE resumes at the earliest stage not complete for all of them.
One flow, one join key — the stem <date>-<slug>. ls .mma/*/<stem>.* and the
mma/<slug> branch recover the whole chain (exploration → spec → plan → backlog).
<slug> from the topic title and stamps
today's date; its SKILL.md owns the slug rule — mma-flow never restates or re-derives
it. The exploration filename IS the stem, and the date is frozen here — a multi-day
flow stays on one key.outputPath. Each
stage hands the prior dated artifact to the next as a target.paths source, so
mma-spec and mma-plan reuse its stem verbatim server-side (see their SKILL.md
outputPath rows). Undated scaffolds (the scratchpad decisions.md) are skipped, so
only the exploration/spec dictates the stem. This is the SAME mechanism a direct
skill call gets — the chain holds with or without the flow..mma/backlogs/<stem>.json and the
branch mma/<slug>. On resume, LOCATE recovers it the same way — off disk, no
persisted state.All artifacts live under the parent workspace's .mma/ (the invocation cwd — the parent
in multi-repo mode, the single repo otherwise); sub-repos hold only branches, code, and PRs.
All share one <stem> = <date>-<slug>, minted at D1 (see Common: Artifact stem):
.mma/explorations/<stem>.md D1 — grounding; not needed once a spec exists
.mma/specs/<stem>.md D3 — one shared spec
.mma/plans/<stem>--<repo-slug>.md B2 — one plan PER involved repo (single repo: <stem>.md)
.mma/backlogs/<stem>.json lazy; uncommitted (see Common: Never-halt)
design/<stem>.md Forge durable design docs (only if that step runs)
No server schema, task type, or HTTP route is added — /mma-flow is client-side.
Never halts on content (see Common: Never-halt). Stops only on setup ambiguity:
mma/<slug> already exists and matches this flow → switch to it, rerun LOCATE.gh missing/unauth for a repo at B8 → skip that repo's PR (backlog), continue.gh pr merge fails for a repo at B9 → leave that PR open, merge the rest, note it.