# Architecture Design

> Design a new CPP capability or service — choose between CQRS context service and Modern by Default patterns, define bounded contexts, events, APIs, and produce a design proposal with diagrams and trade-offs. Use when the user asks to "design", "architect", "plan the architecture of", or decide "how should we build X" for a CPP feature, service, integration, or cross-context change.

- **Type:** Skill
- **Install:** `agentstack add skill-hmcts-claude-architecture-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hmcts](https://agentstack.voostack.com/s/hmcts)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [hmcts](https://github.com/hmcts)
- **Source:** https://github.com/hmcts/claude/tree/main/plugin-draft/hmcts-sdlc-orchestrator/skills/architecture-design

## Install

```sh
agentstack add skill-hmcts-claude-architecture-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Architecture Design (CPP)

Produces a design proposal for a new CPP capability that fits the platform's CQRS/Event Sourcing context-service pattern **or** the Modern by Default (MbD) Spring Boot pattern, whichever suits best. Delegates deep analysis to the `architecture-designer` agent and hands off to scaffolding skills when the user approves.

## When to Use

Triggers: "design a service for…", "how should we architect…", "what's the right pattern for…", "plan a new context/MbD service", "model this bounded context", "design the event flow for…", "cross-context design for…".

**Do not use** for:
- Implementing an already-agreed design → use `springboot-service-from-template` or `context-scaffold`.
- Reviewing an existing design/PR → use `review-pr` or `code-reviewer`.
- Writing a formal OpenSpec change → use `openspec-propose` (this skill can feed into it).

## Required Input

Ask the user (once, all at once):

1. **Problem statement** — what capability or change is needed, and why.
2. **Users / triggers** — who or what initiates the flow (UI action, external event, scheduled job, another context).
3. **Expected outcome** — what state changes, what events/notifications, what reads the UI needs.
4. **Known constraints** — deadlines, compliance, existing services to integrate with, anything off-limits.
5. **Existing context** — is there already a context service or MbD service this should live in, or is this greenfield?

If the user's message already contains enough of this, skip the questions and proceed. Do not stall on missing details you can reasonably assume — make the assumption explicit in the output.

## Workflow

### Step 1 — Frame the problem
Restate the problem in one paragraph and list your assumptions. This anchors the design and exposes misunderstandings early.

### Step 2 — Survey the platform
Before designing, read the relevant neighbours so the design fits reality:

- `grep` for existing contexts / services mentioned in the problem across `cpp-context-*` and `cpp-mbd-*`.
- Read the closest 1–2 analogous services' top-level structure (`pom.xml` / `build.gradle`, one command handler, one event schema).
- Check `cpp-platform-core-domain` for existing shared schemas you should reuse.
- Check `cp-c4-architecture` if the context is already modelled.

Do this yourself with Read/Grep/Glob for small scopes. For anything non-trivial, delegate to the `architecture-designer` agent with a self-contained brief.

### Step 3 — Apply the pattern selection rubric

| Situation | Pattern |
|---|---|
| New greenfield capability, thin domain, REST/event integration | **MbD service** (`cpp-mbd-*`) — default |
| Extension of an existing context (new command/event/projection) | **Extend context** via `context-scaffold` |
| New bounded context with rich aggregate behaviour, audit/replay critical | **New CQRS context service** — justify explicitly |
| UI-only change | `cpp-ui-*` change only |
| Cross-cutting concern | Extend `cpp-platform-libraries` / `cp-framework-libraries` |
| Shared schema/types | Extend `cpp-platform-core-domain` |

MbD is the default. A new CQRS context service is a high-bar decision — require a written justification.

### Step 4 — Produce the design
Delegate to the `architecture-designer` agent with a prompt that includes:
- The restated problem and assumptions
- The surveyed neighbours (file paths)
- Any hard constraints from the user

Ask for the full design output format defined in the agent (Summary, Pattern & Rationale, Bounded Context, Components, Contracts, Diagrams, Cross-cutting, Deployment, Risks, Alternatives, Implementation Outline, Follow-ups).

### Step 5 — Present and iterate
Show the design to the user. Call out:
- The chosen pattern in one sentence.
- One-way-door decisions.
- Any assumptions that, if wrong, would change the recommendation.

Invite the user to push back before implementation begins.

### Step 6 — Hand off
Once the user approves, recommend the next skill:

- **MbD service** → `springboot-service-from-template`
- **Extending a context** → `context-scaffold`
- **Formal change proposal** → `openspec-propose` (wrap this design as the design artifact)
- **C4 model update** → edit `cp-c4-architecture` LikeC4 sources
- **Terraform/infra** → `terraform-validate` on the relevant module

Do not auto-invoke scaffolding skills — the user confirms first.

## Output Conventions

- **Mermaid** for inline container and sequence diagrams.
- **Repo names** and **module suffixes** spelled exactly (`-command`, `-event`, `-viewstore-liquibase`, etc.).
- **Package names** correct per CLAUDE.md: `uk.gov.hmcts.cp.*` for MbD, `uk.gov.moj.cpp.*` for existing CQRS services, `uk.gov.justice.*` for legacy only.
- **Events** named as past-tense facts; **commands** as imperative present tense.
- Cite file paths with `file:line` when referencing existing code.

## Anti-Patterns to Flag

When reviewing the user's premise, push back on:

- Proposing a new context service for what is really a read-model or integration (should be MbD).
- Cross-context synchronous REST chains instead of events for state propagation.
- Shared databases across contexts.
- Breaking event schema changes (must be additive).
- New code in legacy WildFly/Java EE stacks.
- Missing idempotency on event consumers.
- Command handlers that read from projections (stale-data bugs).

## Example Invocation

User: *"We need to let defence solicitors subscribe to hearing updates for their cases and get notifications when anything changes."*

1. Frame: subscription + notification capability; cross-context (hearing → subscriptions → defence UI).
2. Survey: check `cpp-context-subscriptions`, `cpp-context-hearing`, `cpp-ui-subscriptions`, `cpp-mbd-*` for existing notification plumbing.
3. Pattern: likely **extend `cpp-context-subscriptions`** for subscription state + **new `cpp-mbd-hearing-notifications`** for the notification dispatch pipeline.
4. Delegate to `architecture-designer` for the full design with events (`HearingUpdated` consumed, `HearingNotificationDispatched` emitted), APIs, diagrams, risks.
5. Hand off: `context-scaffold` for the subscription changes; `springboot-service-from-template` for the notification service.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hmcts](https://github.com/hmcts)
- **Source:** [hmcts/claude](https://github.com/hmcts/claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hmcts-claude-architecture-design
- Seller: https://agentstack.voostack.com/s/hmcts
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.