codesign

Prompt file imported from e2its/myrmion-AI-factory (.claude/commands/codesign.md). Fill in {{arguments}} before use. Copyright stays with the author.

CODESIGN — Feature Co-Creation

One planning stage (EVOL-048). This command owns a planning phase — the specification (spec.feature, user_journey, slice_map) — so it never enters the harness's plan mode (EnterPlanMode): a second approval would appear to cover decisions the user never made. Its own RDRs and approval steps are the one stage; the pre-write gate (gate.py plan) treats its branch class as planned by this phase.

This command delegates by name to the phase agent factory-codesign (.claude/agents/factory-codesign.md; spawn-policy: phase — the main session spawns it on the writer family, python3 scripts/gate.py agents --resolve --class phase, and hands it its corpus digest) — ONE context carrying both concerns:

• PO (product): Business analysis, BDD/Gherkin specs, event storming, acceptance criteria
• UX (experience): Visual mockups (HTML), WCAG compliance, design system adherence, user journey mapping

Both concerns co-create in one context — the spec informs the mock, the mock informs the spec.

Arguments: {{arguments}}

Step 0 — Applicability Roll-Call (MANDATORY)

Before any command-specific logic, the FIRST user-facing output of this command MUST be the canonical Applicability Roll-Call block. Invoke factory-applicability-discovery to produce it.

• Discovery is live — frontmatters scanned fresh from .claude/instructions/*.instructions.md, .claude/skills/Factory-*/SKILL.md, and .claude/rules/defect-prevention.md entries. New ADRs/DCs/instructions appear automatically the next turn.
• Block format and full algorithm: .claude/skills/factory-applicability-discovery/SKILL.md § Output.
• If the block does not appear on-screen, the command is mal-iniciado — halt and re-emit before any further output.
• This step runs BEFORE Step -1 (branch checkout). Step -1 still executes as the next mandatory pre-action gate.

Three Levels of Operation

1. Global Vision (--vision, --vision-refine, --vision-approve, --vision-propagate)

Visual identity and structure of the complete application. Executed once before iterating features.

Full protocol: See .claude/instructions/Factory-codesign-vision.instructions.md

• Creates docs/ux/vision/ artifacts: vision.md, app_shell.html, style_guide.html, page_templates.html, component_library.html, navigation_map.md
• Vision APPROVED is ALWAYS required before features with UI

2. Per-Feature Co-Creation (--start {ID}, --refine {ID})

Iterate to produce three co-created artifacts (+ a slice_map.md when slicing_strategy: incremental) per feature. Auto-approves when all applicable validations pass.

Full protocol: See .claude/instructions/Factory-codesign-feature.instructions.md Canonical generation order (the journey is the ROOT — EVOL-041):

• user_journey.md (journey-first: Part I experience — personas, Paso steps with the 9 fields Persona/Goal/Does/Sees/Feels 1-5/Pain/Ease/BDD Scenario/Mock Action, paths, pain map; Part II conceptual domain contract in plain business language. Single template, ALL scopes. 100% business-validatable — LAW-16)
• spec.feature (BDD/Gherkin with business rules; scenario titles = the journey's **BDD Scenario:** machine anchors)
• mock.html (pixel-perfect visual mockup; one imp-step per journey Paso — id="step-N" = the journey's **Mock Action:** anchor. UI scopes only)
• slice_map.md (capability-VALUE vertical-slice map — only when slicing_strategy: incremental; refined by BLUEPRINT into increment_plan.md)

--refine sub-steps (Iteration Execution — full pseudocode in the instruction file § Iteration Execution):

• 1.1 Impl-state probe — snapshot dev_plan.md [x] count + commits since last iteration cascade.
• 1.2 Iterative RDR loop — max 3 rounds (configurable via --max-rdr-rounds); converge-on-stability heuristic.
• 1.3 Apply changes — existing Change Classification + Tripartite Alignment re-run.
• 1.4 Aggregated changelog — append_iteration_entry() on spec.feature, user_journey.md, mock.html, and (when slicing_strategy: incremental) slice_map.md, with shared ITER-{FEAT}-{N+1} id (factory-iteration-model + factory-incremental-persistence). A re-slice runs check_slice_immutability pre-persist and fires CASCADE_SLICE_INTERNAL (slice_map → increment_plan).

3. External Authoring Sync (--sync {VISION|ID})

When docs/setup.md says codesign.authoring: external, CODESIGN is authored by the PO in a Claude Desktop project (PO package) and ENTERS the repo here. --sync adopts ONE ratified target verbatim and adds only what the factory owns (gates, frontmatter, iteration ledger, change classification, cascade, auto-approval checks as validation). It never generates and never edits PO content — a finding returns the target as NEEDS_INFO.

With external authoring, --start / --refine (and --vision / --vision-refine when the package covers the design system) are guarded: they block in plain language and point here — the guard runs after Step 0 and BEFORE Step -1, so a blocked command switches no branch and takes no lock. State sub-commands are never guarded. Absent key ⇒ internal ⇒ nothing changes.

Full protocol: See .claude/instructions/Factory-codesign-sync.instructions.md · operator steps: subproducts/po-package/RUNBOOK.md · upstream skill: factory-po-intake.

4. Lifecycle (--revise {ID}, --cancel {ID}, --deprecate {ID}, --reset {ID})

State sub-commands on an existing feature: --revise opens a new feature version (the only path for a breaking change to a MERGED scenario); --cancel / --deprecate set a terminal state; --reset returns NEEDS_INFO to DRAFT.

Full protocol: See .claude/instructions/Factory-codesign-feature.instructions.md § Command: --revise · § Terminal State Commands.

Scope & Slicing

Every feature declares two frontmatter fields in spec.feature that shape the rest of the pipeline:

• scope: full-stack | backend-only | frontend-only | integration. Per-feature, defaults to project_scope from docs/setup.md. Scope Compatibility Gate in Factory-codesign-feature.instructions.md BLOCKS when feature.scope is incompatible with project_scope (matrix: full-stack project accepts all; backend-only/integration accept backend-only+integration; frontend-only accepts only frontend-only). scope is immutable after APPROVED — changing it requires a fresh --start on a new FEAT-ID. Scope drives artefact presence: mock.html + Global UX Vision are N/A for backend-only/integration; user_journey.md is generated for ALL scopes from the single template (backend personas = business callers, Mock Action: —).
• slicing_strategy: incremental | monolithic. Default incremental. monolithic escape allowed only when the Trivial-Heuristic holds: scenarios_count ≤ 2 AND contract_operations ≤ 3 AND scope ≠ full-stack. Enforced at /blueprint --start (Trivial-Heuristic Gate) and /blueprint --approve (CVP Check 16). RDR required when ≥2 viable options exist. When incremental, CODESIGN emits docs/spec/{ID}/slice_map.md (capability-VALUE slicing, Stage 1); BLUEPRINT refines it into increment_plan.md (Stage 2, contract-aware) joined by cascade_source: SLICE-{FEAT}-N.
• consumes_contract: [FEAT-XXX, ...] (optional): cross-feature dependency declaration. Triggers Consumes-Contract Resolution Gate at /blueprint --start and propagates CASCADE_PENDING_ITERATION on upstream contract change.

Key Principles

• DRY: Consult config/codebase_inventory.json before creating new domain concepts (CIP Phase 0.5)
• user_journey.md § 6 Business Fields is the source of truth for WHICH business fields exist (plain language, no types — LAW-16); ARCH derives all typing in design.md and does NOT invent business fields
• Journey grammar (anchors, Feels 1-5, paths) is machine-validated by scripts/check-journey-grammar.sh (auto-approval CHECK 3)
• After --refine in Iteration Mode → CASCADE_PENDING_ITERATION to all downstream artifacts
• Vision compliance: All feature mockups MUST reference vision artifacts
• Iteration Changelog: Every --refine MUST append a changelog entry to the modified artifacts documenting what changed, what triggered the change, and which downstream artifacts are affected. This changelog serves as reference for the next agent in the pipeline.
• Worklog Attribution: APPEND_TO_WORKLOG with user_agent: "CODESIGN" — always the actual agent name.
• User Communication: Follow Agent Communication Protocol (.claude/skills/factory-agent-communication/SKILL.md) — entry announcement, phase milestones, completion summary.
• APPEND_TO_WORKLOG after each completed task
• Incremental Persistence: Follow IPP (.claude/skills/factory-incremental-persistence/SKILL.md) — skeleton-first write, section-atomic saves, resume-on-entry. See M-07 in codesign-feature instructions.

Changelog Format (for --refine)

## Changelog

| Date | Iteration | Source | Changes | Downstream Impact |
|------|-----------|--------|---------|-------------------|
| {ISO_DATE} | {N} → {N+1} | {user feedback / PO decision / UX finding} | {list of scenario/mock/journey changes} | {design.md, test_plan.md, dev_plan.md — marked CASCADE_PENDING_ITERATION} |

Pre-Command Protocol (MANDATORY)

• Before ANY file modification, execute the full Step -1 Auto-Branch Checkout Protocol from .claude/skills/factory-branching-strategy/SKILL.md
• This ensures correct branch checkout, cross-branch mismatch detection, dependency checks, and concurrency locking
• Branch naming: --vision / --sync VISION use feature/UX-VISION-global-app-design; --start {ID} / --sync {ID} use feature/{ID}-{slug}