claude-code-architect-designer

Skills: !ls "${CLAUDE_PROJECT_DIR:-.}/.claude/skills"

Agents: !ls "${CLAUDE_PROJECT_DIR:-.}/.claude/agents"

Rules: !ls "${CLAUDE_PROJECT_DIR:-.}/.claude/rules"

Decision records (the latest is the most recent): !ls "${CLAUDE_PROJECT_DIR:-.}/.claude/decisions"

$ARGUMENTS

# Claude Code Architect Designer

Decides which of the nine forms of extension resolves the scenario, and writes it. The nine:

6b isn't a fourth reason to write an agent — it's reason 2 of § 5 of the decision matrix (restrict tools) applied to an external connection instead of a built-in one. An agent only exists in the first place per the three reasons already in references/decision-matrix.md § 5; 6b just answers which tools it gets once that's settled.

This is a multi-step procedure — interview, classify, propose, write — hence a skill. As a rule it would break invariant 1 of @CLAUDE.md: a rule about when to create skills and agents would have to mention skills and agents, and rules/ is a leaf.

Pinned to opus: what it designs is enforced in every later session (@.claude/decisions/0081-skill-model-required-per-class.md).

Read references/decision-matrix.md and @docs/pt-br/11-pitfalls.md before asking — the matrix decides the form, the pitfalls page says which silent traps (the runtime's and this repository's: territories, frozen folders, ownership splits) the design must not walk into. Use AskUserQuestion — at most 4 questions per call, so 2 to 3 calls. Don't proceed with a missing answer: each axis below eliminates candidate forms, and an unanswered axis leaves the decision guessing.

Apply the decision table in references/decision-matrix.md (§ 2; § 2.1 whenever axis 2 named an external system; § 2.2 whenever axis 7 answered that the rule cannot fail; § 2.3 whenever axes 18-20 applied). Then run the eleven invariants of @CLAUDE.md as a veto — the most commonly violated are 1 (a rule that mentions a skill), 5 (an agent without one of the three reasons), 6 (prose where a guarantee was available, and its mirror: a hook for something the model gets right on its own — and, for Form 9, a mod standing in for the guarantee), 2 for Form 9 (a rule restated in TypeScript instead of read from ArchHook.jar), and, for MCP, 11 (a literal secret in .mcp.json). A proposal that fails an invariant is not presented as viable: it appears with the score it deserves and the reason for rejection.

Two to four options, ordered by score, always including the "create nothing" hypothesis when it is defensible. Each in this form, in this order:

1. Title — proposed filename, in kebab-case
2. Motivator — the interview axis that justifies it
3. Pros
4. Cons — includes the invariant it strains, if any
5. Score 0-10 — rubric in references/decision-matrix.md, § Rubric
6. Visual — file tree or ASCII graph of who calls whom
7. CI — axis 17's answer for this option, one of three: the existing job and step that

And at the end, a references table: for each decision, the concrete source (@claude-help.md § N, @CLAUDE.md invariant N, or the repo file that serves as precedent). A claim about the runtime without a source is decoration — cut it.

What Phase 3 produced — options, scores, rejected alternatives, the references table — evaporates at the end of the session. Six months from now nobody knows why the piece is a skill and not an agent, and the twenty-axis interview starts over from scratch.

When to save a file. Only if at least one of these is true:

• Two or more options scored ≥ 5 — there was a real choice.
• The top-scoring option strains an invariant of @CLAUDE.md.
• Axis 8 answered "both" — the piece also goes to the generated project.
• Axis 13 answered "both" — the MCP server is declared in .mcp.json and in
• The approved option is Form 7c or Form 8 — always, with no exception. A new mode in
• The approved option is Form 9 — always, too. A mod adds a second language, a

1. Generate from the templates/ exemplar matching the approved form. For Form 6a, the
2. Frontmatter: native fields only, list in references/frontmatter-fields.md. An
3. No metadata: in frontmatter. Ownership, reads, and handoff go in the ## Contract
4. Code boilerplate goes to templates/<name>.example inside the skill that emits it,
5. No literal secret, ever, in a .mcp.json this skill writes or edits — invariant
6. ${VAR} / ${VAR:-default}, oauth, or headersHelper only. If the interview's
7. Forms 7 and 8 — five rules, none of them optional. They execute; a mistake here

Files created, files changed, the decision record path (or the sentence explaining why there wasn't one), the validate and schema output, the CI line — the job and step that cover the piece, the test step 9 wrote with its green and red runs, or the reason nothing is testable — and — whenever a hook or a permissions rule was written — the restart warning, in its own line: .claude/settings.json is read only at session startup, so nothing written in Forms 7a or 8 takes effect until claude is restarted. Say it even if the user already knows; a hook believed to be active and silently absent is worse than no hook. For Form 9 the same line, plus two: the marketplace registers only once the folder's workspace trust was accepted, and a mod edited in a git worktree does not load from there — the relative marketplace path resolves against the main checkout.

~/.claude/settings.json and .claude/settings.local.json. Personal and machine-local configuration, same exclusion as local-scope MCP below: not versioned, not shared, not this skill's concern. A hook the team doesn't get isn't enforcement, it's one person's habit. settings.local.json in particular is where a permission granted mid-session lands — moving one of those into the versioned file is a decision the user makes, and this skill only writes it when asked outright.

A second hook file. Form 7c is a mode inside ArchHook.java, never .claude/hooks/<Other>.java. Enforcement stays in one executable that the generated project receives whole from the export mode; a second file would have to be copied, registered, and kept in sync separately, and the first one to fall out of sync fails silently. A Form 9 mod is not one: it enforces nothing, calls ArchHook.jar for every answer it shows, and nothing breaks when it does not load.

A mod as the guarantee, or a mod in the generated project. A mod does not load in claude -p, VS Code, a cloud session or under --safe-mode, so a rule that must always hold stays Form 7 or 8 (invariant 6). And nothing under .claude/mods/ travels: a project would inherit a second language, a version floor and an unsandboxed process its owner never reviewed (0131). Changing that is a new decision, not a propagation row.

The built-in plugin-authoring skill and ~/.claude/dev-mods/. Same reason as the skill-creator plugin below: it writes a generic mod into a personal directory the next cleanup deletes, with no knowledge of the mods block, the marketplace or the guarantee a mod must sit on.