design-clean-architecture

name	design-clean-architecture
description	Design clean architecture boundaries from an approved domain model with stable use-case and invariant IDs. Use when Codex needs layers, dependency direction, ports, adapters, module boundaries, placement rules, and forbidden dependencies before defining interfaces or writing code. Do not use for reviewing existing code or for interface contract design.

Design Clean Architecture

Goal

Translate an approved domain model into a clear architecture map with strict dependency rules and explicit boundaries between policy and implementation details.

Read Shared Contract Reference before producing the artifact.

Trigger boundary

• Use after domain modeling is approved and before interface contracts or implementation planning.
• Do not use for code review, contract review, or direct code generation.

Required input

• Required: approved domain-model.md or equivalent with metadata showing approval_status: approved and stable UC-* and INV-* IDs
• Optional: technology choices, existing codebase constraints, deployment context, non-functional requirements

Refusal and blocked policy

• Let domain and use cases drive structure.
• Apply framework and transport choices at the adapter edge, not in the core layers.
• Do not hard-code the design around MCP or any single integration pattern.
• Return BLOCKED when the upstream domain artifact is missing, not approved, or lacks stable UC-* and INV-* identifiers.
• Return BLOCKED when the request is actually to review existing code for boundary violations.

Workflow

1. Define the layers needed for the feature or service.
2. State allowed dependency direction between layers.
3. Map modules to the UC-* and INV-* records they protect.
4. Identify PORT-* interfaces and the ADAPTER-* components that satisfy or call them.
5. Define module boundaries, ownership, placement rules, and translation points.
6. List forbidden dependencies and common leakage risks.
7. Record open questions that affect boundary decisions.

Output contract

Write architecture.md or return equivalent Markdown using this structure:

# Clean Architecture Design

## Artifact Metadata
- artifact_id:
- artifact_type: architecture
- artifact_status: draft | current | superseded
- approval_status: pending_review | approved | changes_required | rejected
- approved_by_gate_profile: none | architecture-boundaries
- gate_report_ref: none | <ref>
- upstream_artifact_refs:

## Scope And Assumptions
...

## Layer Map
| layer | responsibility | may_depend_on | must_not_depend_on |
| --- | --- | --- | --- |

## Dependency Rules
- rule_id: RULE-*
- rule:
- reason:

## Modules And Ownership
| module_id | module | layer | supports_use_case_ids | protects_invariant_ids | responsibility | exposes |
| --- | --- | --- | --- | --- | --- | --- |

## Ports
- port_id: PORT-*
- port:
  owner_module_id:
  supports_use_case_ids:
  purpose:
  input_output_shape:

## Adapters
- adapter_id: ADAPTER-*
- adapter:
  implements_or_calls_port_id:
  infrastructure_detail:
  translation_boundary:

## Boundary Translation Points
- boundary:
  allowed_models:
  prohibited_leakage:
  related_port_or_adapter_id:

## Forbidden Dependencies
- rule_id: RULE-*
- forbidden_dependency:
- reason:

## Enforcement Hints
- rule_id: RULE-*
- check_in_review_or_code:

## Open Questions
- ...

Quality bar

• Make every rule enforceable in code review.
• Keep domain and use-case layers free of framework details.
• Use module boundaries that support later slice planning.
• Tailor the structure to the actual use cases instead of restating generic Clean Architecture slogans.
• Every PORT-* and MODULE-* should be justified by specific UC-* or INV-* references.
• Initialize artifact metadata with approval_status: pending_review until a gate or approver marks it otherwise.