architecture

Architecture as Code

Create, manage, and query Architecture Decision Records (ADRs) and maintain an interactive LikeC4 architecture model. ADRs are version-controlled markdown; the C4 model is version-controlled LikeC4 DSL (.c4). All artifacts live in knowledge-base/engineering/architecture/.

Sub-commands

| Command | Description | |---------|-------------| | architecture create [title] | Create a new ADR with the next sequential number | | architecture list | Display all ADRs with status, title, and date | | architecture supersede <N> [title] | Mark ADR-N as superseded and create its replacement | | architecture diagram [type] | Create or update the LikeC4 model and its views (context, container, component) | | architecture add-container <id> | Add a container/database element to the model | | architecture add-component <id> | Add a component element to the model | | architecture add-relationship <from> <to> | Add a relationship between two model elements | | architecture render | Validate the LikeC4 project (likec4 validate) and report element/view counts | | architecture assess [feature] | Assess a feature against the NFR register and principles register | | architecture principle list | Display the architecture principles register |

If no sub-command is provided, display the table above and ask which sub-command to run.

Arguments

$ARGUMENTS is parsed for a sub-command and optional parameters:

architecture [sub-command] [arguments...]

Phase 0: Prerequisites

Verify the knowledge-base directory exists:

if [[ ! -d "knowledge-base" ]]; then
  echo "No knowledge-base/ directory found. Create one first or run /soleur:sync."
  # Stop execution
fi

Create the architecture directories if they do not exist:

mkdir -p knowledge-base/engineering/architecture/decisions
mkdir -p knowledge-base/engineering/architecture/diagrams

Branch safety check (defense-in-depth): Run git branch --show-current. If the result is main or master, abort with: "Error: architecture skill cannot run on main/master. Checkout a feature branch first."

Sub-command: create

Create a new ADR with the next sequential number.

Steps

1. Determine next ADR number. List existing ADRs in knowledge-base/engineering/architecture/decisions/:

``bash ls knowledge-base/engineering/architecture/decisions/ADR-*.md 2>/dev/null | sort -V | tail -1 ``

Extract the highest number and increment by 1. If no ADRs exist, start at 001.

1. Get the title. If a title was provided in $ARGUMENTS, use it. Otherwise, use AskUserQuestion: "What architectural decision are you recording?"

1. Generate the filename. Convert the title to kebab-case: ADR-<NNN>-<kebab-title>.md

1. Read the ADR template from [adr-template.md](./references/adr-template.md). The template now documents two labeled body shapes (terse / rich) under the ## Choosing the shape section. Read that section before proceeding.

1. Ask the shape rubric. Present the 5 triggers from the template's ## Choosing the shape section and pick between the terse and rich shapes. Use AskUserQuestion with options:

• "No — terse (3 sections)"
• "Yes — rich (8 sections)"
• "Unsure — walk me through each trigger"

If the contributor picks "Unsure," ask each of the 5 triggers as its own yes/no AskUserQuestion. Compute: any yes → rich, all no → terse.

Pipeline mode default. If running inside /soleur:one-shot or any other non-interactive caller (no AskUserQuestion available, only $ARGUMENTS context), default to terse. Rich-shape ADRs in pipeline mode require the caller to pass shape: rich explicitly in $ARGUMENTS, or the rubric falls through to terse.

1. Write the ADR file. Create knowledge-base/engineering/architecture/decisions/ADR-<NNN>-<kebab-title>.md using the chosen shape's body block from the template. Fill in frontmatter:
2. adr: ADR-<NNN>
3. title: <title>
4. status: active
5. date: <today YYYY-MM-DD>

1. Gather context. Ask the user (or use $ARGUMENTS context if running in pipeline). The prompt list branches on the shape chosen in step 5:

Terse branch (3 prompts):

• Context: What motivates this decision?
• Decision: What is the change being made?
• Consequences: What becomes easier or harder?

Rich branch (8 prompts):

• Context: What motivates this decision?
• Considered Options: What alternatives were evaluated? (list with pros/cons and links to tentative C4 model changes)
• Decision: Which option was chosen and why?
• Consequences: What becomes easier or harder?
• Cost Impacts: How much does this change increase or reduce costs? (reference knowledge-base/operations/expenses.md for baseline; use "None" if no impact)
• NFR Impacts: Which non-functional requirements are affected? Read [nfr-reference.md](./references/nfr-reference.md) for the assessment checklist and common patterns by decision type. Reference NFR IDs from knowledge-base/engineering/architecture/nfr-register.md. Use "None" if no impact.
• Principle Alignment: Which architectural principles does this decision align with or deviate from? Read knowledge-base/engineering/architecture/principles-register.md for the register. Reference AP-NNN IDs. Use "None" if no impact.
• Diagram: (optional) Should a LikeC4 diagram be included or updated?

1. Write the ADR body with the gathered context. If a diagram was requested (rich branch only), update the consolidated LikeC4 model using [likec4-reference.md](./references/likec4-reference.md) (see the diagram sub-command) and embed the relevant view with a `likec4-view block.

8.5. Domain-model register check. If this ADR records or changes a business rule — an entity invariant, an ownership/access model, or a relationship encoded in a migration constraint / RLS policy / resolver-guard — update the affected row(s) in [knowledge-base/engineering/architecture/domain-model.md](../../../../knowledge-base/engineering/architecture/domain-model.md) in the same change: add or amend the rule with a citation back to this ADR. Rule IDs are immutable — supersede (mark + link the successor row), never reuse. If the ADR is purely a technology/process decision with no entity-invariant impact, skip silently.

1. Announce: "Created ADR-<NNN>: <title> at knowledge-base/engineering/architecture/decisions/ADR-<NNN>-<kebab-title>.md"

Sub-command: list

Display all ADRs with their status, number, title, and date.

Steps

1. Scan the decisions directory:

``bash ls knowledge-base/engineering/architecture/decisions/ADR-*.md 2>/dev/null ``

1. If no ADRs exist: Display "No ADRs found. Run /soleur:architecture create to create one."

1. For each ADR file: Read the YAML frontmatter and extract adr, title, status, date.

1. Display as a table:

``text | # | Title | Status | Date | |---|-------|--------|------| | ADR-001 | Use LikeC4 for diagrams | active | 2026-03-27 | | ADR-002 | PWA-first architecture | superseded | 2026-03-20 | ``

Sub-command: supersede

Mark an existing ADR as superseded and create its replacement.

Steps

1. Parse the ADR number from $ARGUMENTS. If not provided, use AskUserQuestion: "Which ADR number to supersede?"

1. Find the existing ADR by matching ADR-<NNN>-*.md in knowledge-base/engineering/architecture/decisions/.

1. If not found: Display "ADR-<NNN> not found." and stop.

1. If already superseded: Display "ADR-<NNN> is already superseded by ADR-<M>." and stop.

1. Get the replacement title. If provided in $ARGUMENTS, use it. Otherwise, use AskUserQuestion: "What is the title of the replacement decision?"

1. Create the replacement ADR using the create sub-command flow (next seque