Cmon Design

When an understand packet exists, use it as the verified entry context for:

• relevant repo area
• prior artifacts
• reusable local patterns
• constraints and unresolved unknowns

When to Use

Use this skill when any of these are true:

• the work is a greenfield project or new product surface
• the work introduces a user-facing CLI, API, UI, or operator surface
• the work introduces persistent state, config, storage, or workflow modes
• the work has multiple commands, workflows, states, or failure paths
• the work introduces a non-trivial user or operator flow
• the work has multiple important states such as loading, empty, partial success, error, or retry
• interfaces or system boundaries need to be defined before planning
• architecture choices materially affect user-visible behavior
• the plan would otherwise have to invent missing design decisions

Skip this skill only when all of these are true:

• the change is tightly bounded
• the work is not a greenfield or newly introduced product surface
• no new user-facing surface, persistent state, config surface, or multi-mode workflow is being introduced
• no meaningful flow or state design is being introduced
• requirements are already specific enough that planning would not need to invent behavior

Hard Gate

Do not implement from this skill.

Do not use this skill to write the implementation plan.

The only normal next step is:

• write or update the design artifact
• then move to cmon:challenge(mode=design)

Core Contract

cmon:design answers:

• what the user or operator sees in each relevant state
• how the flow moves from step to step
• where boundaries and interfaces sit
• which ambiguities must be resolved before planning

It does not answer:

• exact files to edit
• commit sequencing
• test command choreography
• production code shape

Ownership Model

Use one clear owner for the design artifact.

The owner is responsible for:

• drafting the design
• deciding what ambiguity must be removed before planning
• incorporating relevant challenge from other lenses
• consuming the current understand packet rather than rediscovering upstream context ad hoc

Non-owner lenses are responsible for:

• surfacing risks
• challenging weak assumptions
• forcing clarity where the draft would otherwise create downstream implementation churn

Required Artifact

Write the result to:

• docs/designs/ for product, interaction, or operator-facing design specs
• docs/architecture/ only when the design decision is primarily architectural and repo-level

Use templates/design/design-spec-template.md as the default structure. Use templates/design/design-run-manifest-template.md when owner mode or challenge scope should be explicit before drafting starts.

The artifact must include:

• design goals
• requirements trace
• user or system flow
• important states and failure handling
• interface and boundary decisions
• human review summary covering what is being built, why, and how users or operators interact with it
• Markdown-native explanatory structures such as tables, Mermaid flowcharts, state diagrams, sequence diagrams, or graphs when they improve auditability
• unresolved design blockers

Quality Gate

Before handing off to cmon:challenge(mode=design), review the artifact against these dimensions:

• flow clarity
• state completeness
• boundary clarity
• user or operator experience clarity
• operability and failure realism
• ambiguity left for the implementer

If any dimension is materially weak, revise the design artifact before challenge.

The cross-role challenge flow now belongs to cmon:challenge(mode=design). Older design-local challenger prompts are legacy references, not the canonical gate.

The canonical design challenge uses:

• templates/workflow/challenge-run-manifest-template.md
• templates/challenge/challenge-context-template.md
• templates/challenge/lens-invocation-template.md
• agents/challenge/design/product-challenger.md
• agents/challenge/design/engineering-challenger.md
• agents/challenge/design/ops-challenger.md
• agents/challenge/challenge-synthesizer.md

Hard Rules

• No implementation plan in disguise
• No exact file map or execution sequence
• No unresolved design ambiguity pushed downstream when it changes implementation shape
• No generic phrases such as "clean UI" or "handle errors gracefully" without explicit design meaning

Handoff

Record the handoff using:

• templates/workflow/stage-transition-decision-template.md

If approved and non-blocking:

• proceed -> cmon:challenge(mode=design)

If not:

• revise -> cmon:design
• revise the design artifact and continue design work

If upstream requirements or task framing instability prevent responsible design closure:

• block

The operational execution and manual procedure are documented in:

• docs/architecture/2026-04-07-design-execution-v0.md
• docs/architecture/2026-04-07-design-operating-procedure-v0.md