From mcd-flow
MCD-Flow Phase 1 — Detect language, generate SPEC_MANIFEST, statechart (.mmd), and type definitions. Dispatched by /mcd orchestrator with model opus.
How this command is triggered — by the user, by Claude, or both
Slash command
/mcd-flow:mcd-planThe summary Claude sees in its command listing — used to decide when to auto-load this command
You are executing **MCD-Flow Phase 1: The Architect**.
All file operations happen inside the worktree path provided by the orchestrator. Do not touch the main workspace.
---
## Your Inputs
- `.mcd/requirements.md` — read this first. All design decisions must be grounded in the requirements. If this file does not exist, proceed from the feature prompt only.
---
## Step 1: Detect Language & Write Config
Read `${CLAUDE_PLUGIN_ROOT}/references/language-profiles.md` to see the built-in profiles and detection rules.
Detect the language from markers in the project root (the directory conta...You are executing MCD-Flow Phase 1: The Architect.
All file operations happen inside the worktree path provided by the orchestrator. Do not touch the main workspace.
.mcd/requirements.md — read this first. All design decisions must be grounded in the requirements. If this file does not exist, proceed from the feature prompt only.Read ${CLAUDE_PLUGIN_ROOT}/references/language-profiles.md to see the built-in profiles and detection rules.
Detect the language from markers in the project root (the directory containing the worktree, not the worktree itself — look at the parent repo):
| Marker | Profile |
|---|---|
package.json | typescript |
pyproject.toml or requirements.txt | python |
go.mod | go |
| none | prompt the user to pick one of the built-in profiles, or describe a custom profile |
If a marker exists but the project's actual toolchain differs (e.g. a Python project using unittest rather than pytest), ask the user:
Detected marker: <marker>
Inferred profile: <language>
Is this correct, or override? [keep / override]
Write the chosen profile to <worktree>/.mcd/config.json using the exact schema from references/language-profiles.md. All later phases rely on this file.
Check if .mcd/manifest.json exists in the worktree:
<src_dir>, <types_dir>, <test_dir> (from config) for current state. Apply the rules below.Additive by default. Only extend — do not modify existing entities, transitions, or type signatures unless the prompt explicitly requires it.
| Change type | Rule |
|---|---|
| New entity | Add to entities[], add new type file, add new tests |
| New feature / flow | Append to features[] and flows[], extend statechart |
| New statechart state or transition | Add alongside existing; do not reorder or rename existing states |
| Modify existing entity field | Require explicit user confirmation before changing a type already referenced in skeleton/filled files |
| Remove entity, field, or transition | Treat as breaking. Stop and confirm with user before proceeding |
| Rename anything | Treat as breaking. Stop and confirm with user before proceeding |
Version bump: Increment patch (1.0.x) for additive-only. Increment minor (1.x.0) if any existing type file is modified.
Do not regenerate tests or skeletons for transitions that already exist and are unchanged.
.mcd/manifest.json{
"version": "1.0.0",
"feature": "<slugified-feature-name>",
"created": "<ISO 8601 timestamp>",
"updated": "<ISO 8601 timestamp>",
"entities": [...],
"features": [...],
"flows": [...],
"dependencies": {},
"statechart_file": ".mcd/statechart.mmd",
"statechart": { ... }
}
Rules:
version: "1.0.0" greenfield; increment patch on diffsentities: every domain object — fields with name + type, relations with entity + cardinalityfeatures: each capabilityflows: step-by-step sequences for each featuredependencies: external packages needed (name → version range) — use ecosystem-native format from .mcd/config.json.languagestatechart_file: always .mcd/statechart.mmdrequirements.md.Write the statechart both as a human-readable .mmd (Mermaid) file and as the machine-readable statechart field inside the manifest.
.mcd/statechart.mmd:
stateDiagram-v2
[*] --> idle
idle --> validating : SUBMIT / validateInput
validating --> processing : VALID / processFeature
validating --> error_validation : INVALID / handleValidationError
validating --> error_timeout : after 5000ms / handleTimeout
processing --> complete : SUCCESS / finalizeFeature
processing --> error_processing : FAILURE / handleProcessingError
error_validation --> idle : RETRY
error_processing --> idle : RETRY
error_timeout --> idle : RETRY
complete --> [*]
Rules:
stateDiagram-v2EVENT / actionNameafter Nms for timeout transitionsstatechart field inside manifest.json:
Required:
initial: starting state namestates: every state, including all error.* substates and at least one { "type": "final" } stateafter timeout entrytransitions: one object per event — from, event, to, action, input type name, output type nameError states are mandatory. For every happy-path transition, define the corresponding error state and handler action.
{
"initial": "idle",
"states": {
"idle": { "on": { "SUBMIT": "validating" } },
"validating": {
"on": { "VALID": "processing", "INVALID": "error.validation" },
"after": { "5000": "error.timeout" }
},
"processing": { "on": { "SUCCESS": "complete", "FAILURE": "error.processing" } },
"complete": { "type": "final" },
"error": {
"states": {
"validation": { "on": { "RETRY": "idle" } },
"processing": { "on": { "RETRY": "idle" } },
"timeout": { "on": { "RETRY": "idle" } }
}
}
},
"transitions": [
{
"from": "idle",
"event": "SUBMIT",
"to": "validating",
"action": "validateInput",
"input": "FeatureInput",
"output": "ValidationResult"
}
]
}
Every transitions[].action becomes an exported function in the skeleton (Phase 2).
Create files in <types_dir> (from .mcd/config.json) — one per domain entity or concern. Use <file_ext> for filenames.
Rules:
transitions[].input or transitions[].output must be exported here.validation_lib idiom from .mcd/config.json.Per-language examples:
typescript (validation_lib: zod):
import { z } from 'zod'
export const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
passwordHash: z.string(),
createdAt: z.date(),
})
export type User = z.infer<typeof UserSchema>
python (validation_lib: pydantic):
from datetime import datetime
from pydantic import BaseModel, EmailStr
from uuid import UUID
class User(BaseModel):
id: UUID
email: EmailStr
password_hash: str
created_at: datetime
go (validation_lib: go-playground/validator):
package types
import "time"
type User struct {
ID string `json:"id" validate:"required,uuid"`
Email string `json:"email" validate:"required,email"`
PasswordHash string `json:"password_hash" validate:"required"`
CreatedAt time.Time `json:"created_at"`
}
For other validation_lib values (custom profile), apply the same discipline: express types + runtime validation in idiomatic form, no business logic.
.mcd/registry.jsonTimestamp via date -u +"%Y-%m-%dT%H:%M:%SZ":
{
"phase1": { "status": "complete", "timestamp": "<ISO>" },
"files": {}
}
Print a structured summary:
=== MCD-Flow Phase 1 Complete ===
Feature: <name>
Language: <typescript|python|go|...>
Entities: <count> — <list>
Features: <count> — <list>
Statechart states: <count> — <list including error states>
Statechart transitions: <count>
<event>: <action> (<Input> → <Output>)
...
Timeout states: <count> — <list>
Statechart diagram: .mcd/statechart.mmd
Type files: <list>
Note: Oracle tests are generated in Phase 3 (Audit) after the skeleton exists.
Ask: "Approve spec to continue to Phase 2 (skeleton)? [y/n]"
npx claudepluginhub fusuyfusuy/mcd-flow --plugin mcd-flow