Make the shape of the system a recorded strategic act. Read the brief, the glossary and the decision records, design the architecture twice, compare the candidates on complexity, and — after a human yes — record the paradigm, the architectural style, the context map and the patterns adopted or rejected as three anchors in the engineering article, a glossary section, and one decision record. Use at bootstrap hand-back before the first feature diff, when a planner sees the shape no longer fitting, or when `/housekeeping` or the architecture skill raises a style-level red flag.
86%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Nothing in the chain asked what shape a system is. The engineering article's Architecture section shipped as blanks, so the first feature diff picked a paradigm and a style by accident and every later diff conformed to the accident. This skill is the decision made deliberately, twice, and recorded where every later session reads it.
"Strategic" means Ousterhout's strategic programming: working code is not enough, and design is an investment made continuously and judged by the complexity it removes — complexity being dependencies plus obscurity, the two things that make a change cost more than it should. Evans's work on subdomains and bounded contexts is kept in full but under the kit's names — the context map and the subdomain classification — so one word never carries two meanings.
Project context — read these first, they are the parts this file cannot know:
- The brief: whatever says what the system is for — the conversation, the product article if the project declared one, the README. For an existing codebase, the code itself, read in fresh context (step 1).
- Domain language:
docs/domain-glossary.md. Every candidate is described in its names; the context map you write lands in its Context map section.- Decision records:
docs/adr/. Read the ones covering architecture before proposing anything; a candidate that contradicts a binding record is a different conversation.- The engineering article:
constitution/local-engineering.md(stamped from its template at bootstrap). Its Architecture section carries the three anchors this skill fills.- Capability tiers: this skill spawns subagents.
scripts/agents.config.shmaps a tier to a model andsh scripts/agents.lib.sh <tier>resolves one. Architecture isplannertier; an unmapped tier prints nothing and the spawn inherits this session's model, which is a working state.
.template, or the repo deliberately has none (a template repository is
one). The brief still runs: the decision record and the glossary carry it,
and the anchors arrive with the article the day it is stamped — say so in
the record's "More information".It decides and records; it does not implement. It never writes a line of
product code, and it writes nothing in the repo tree before the human says
yes — the one artifact it produces before the yes is the comparison report,
which lives outside the tree.
The output is a recommendation, then — after the yes — three anchor lines, a
glossary section and a decision record. Prefactoring the brief implies goes to
/to-tickets; a deepening it exposes goes to /improve-codebase-architecture.
AGENTS.md, agent trust boundary).List the subdomains the brief implies and mark each core (where the
product wins, and where the design investment goes), supporting (needed,
not differentiating) or generic (buy, copy, or take the plainest thing
that works). One line of reason each. A system with one subdomain is a
finding, not a failure: say so, and expect several anchors to read
none — <reason>.
Spawn two planner-tier subagents in fresh context — the same discipline
/improve-codebase-architecture applies to an interface, here applied to the
whole shape. Each gets the brief, the glossary, the subdomain classification
and the exploration's data, and a different constraint:
Each candidate states, in the glossary's words:
Each candidate is at most six hundred words; the comparison is read under a stop-and-decide, and length is where run-to-run variance hides.
Compare the two on Ousterhout's terms: where each one amplifies change (one decision, N edits), what it makes a newcomer hold in their head, and where it leaves unknown unknowns (a change with no obvious place to look). Then recommend one — or a hybrid, named — and say why. A menu is not a recommendation.
Two candidates that agree on paradigm and style have converged: report the convergence as a finding and scope the comparison to where they still differ (usually the map and the patterns). Only two candidates identical on all four points send you back to step 3 with a sharper pair of constraints. A hybrid was designed by nobody in fresh context, so name its untested seam — the join between the two designs — in the recommendation; the human decides whether that seam earns a third candidate before the yes.
Write the comparison as one self-contained file outside the repo tree, the
way /improve-codebase-architecture writes its review: resolve the OS temp
directory from $TMPDIR, falling back to /tmp (or %TEMP% on Windows),
write <tmpdir>/design-brief-<YYYYMMDDTHHMMSSZ>.md (or .html when a
browser is available; diagrams as real drawings, never ASCII art — shared
code craft §10), at most two pages, and tell the human the absolute path.
Stop here for a human yes before writing anything into the repo. The brief is a judgment call with an irreversible consequence — every later diff conforms to it — so it carries no autonomy label and no agent takes it solo. If the answer is no, or a different candidate, nothing in the repo tree has changed; revise and present again.
Write, in this order, in the shapes BRIEF-FORMAT.md gives exactly:
**Paradigm**:, **Architectural style**:, **Context map**:. Each is
the decision in one or two sentences, or none — <the reason>. Never a
blank: the gate's design-brief advisory reads these lines.The three writes are one local commit, docs(design-brief): …, so the
brief lands as one reviewable decision. This skill never pushes: delivery
is /implement's, and landing is the human's.
If the brief implies preparatory work — a seam to cut, a layer to introduce —
it goes to /to-tickets as prefactoring, sequenced before the feature slices
(shared invariant §10). A ticket that later introduces a new abstraction or
crosses a context edge cites this brief or reopens it.
/housekeeping, when its red-flag scan finds the style itself no
longer fits — shallow modules everywhere are a module problem; every change
crossing every context is a shape problem, and that reopens this brief./improve-codebase-architecture, when a deepening candidate contradicts
the recorded style. The brief is revised first; the deepening follows.none — <reason> on the anchors and move on. The advisory is silent once
one anchor carries a decision.Written for this kit. The design-it-twice mechanics are the architecture skill's INTERFACE-DESIGN.md applied at the scale of a whole system; the complexity vocabulary is John Ousterhout's (A Philosophy of Software Design), and the context-map vocabulary is Eric Evans's (Domain-Driven Design), kept under the kit's names.
agranado2k/tic-tac-toe-haskell
7554191
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.