# Program Architecture

> Turns a settled design into the architecture of the program that implements it, working a design tree from how the code is distributed, to what the entrypoint does in order, to the contract of each part, with the user settling every leaf. Stays above function signatures, file lists and tests. Use after design, before code.

- Skill: `asermax/program-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add asermax/program-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asermax/program-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: asermax (https://skillmd.com/u/asermax)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asermax/program-architecture

---


Load mahou:basics first, then mahou:design. Everything in `design` applies here as written: the tree, the rounds, the question format, the facts rule, how a branch is opened, stated, questioned, represented and rendered, and how the result is recorded. Then read `.mahou/program-architecture.md` if present.

# Program architecture

Takes a design the user has settled and works out the architecture of the program that implements it: how the code is distributed and shipped, what the program does from its entrypoint to its exit, and what each part agrees with the rest.

## What the level is

`design` stops above endpoints, functions and files. This skill starts there and stops short of the code.

The decisions it settles are the ones a reader meets before they read a function body. Package names, command and flag names, configuration keys, the names and members of the contracts between parts, the order of calls, what a failure at each step does: those are examples of the level, not a list of it. Whatever else has to be decided before the program can be written belongs here too.

The decisions it leaves alone are the ones the code itself carries. Function signatures, the module-by-module file list inside a part and test cases are examples again, and so is anything else a reader could paste.

A leaf that could be answered differently, and would change what a reader of the finished program sees, belongs here. A leaf the design, the language or a library already answers is not a leaf.

## Opening

1. Read the settled design, or the notes that record it. A `mahou:docs-scout` reads the notes so they stay out of this conversation.

2. List what has to be designed, ordered so each item builds on the last:

   - How the code is distributed: packages, what is published, what is built and how it runs.
   - What the program does: the entrypoint, the order of the steps, what each failure does, what the process returns.
   - One item per part the flow named, for its contract.

3. Wait for the user's corrections. Drop items that are code, absorb items that belong inside another, and add the ones the design requires.

4. Build the tree. The root is "Program architecture" and each item is a branch, every branch pending.

## Working a branch

As `design` describes it, against its types table extended with the rows below. When a branch matches one of `design`'s own types, use that reference as written.

| The branch is about | Reference |
|---|---|
| How the code is distributed, published and run | `references/types/package-layout.md` |
| What the program does in order, and what it returns | `references/types/control-flow.md` |

A branch that fits no row in either table is worked out with the user, as in `design`.

## Recording

As `design` describes it, except that the notes describe parts of a program. A part with no note gets one. When a note already describes the same part at the design's level, extend it rather than write a second one, since two notes about one part end up contradicting each other.

## What this skill is not

It does not write code, does not choose function or file names, does not plan the work into issues, and does not commit.