architect

Architect

Bias toward fewer, simpler, more reversible designs. The skill exists to slow down at the right moment, not to add ceremony: a local, internal, reversible change does not need it, and the developer skill handles that.

Use it when a change touches several modules or crosses a public contract, when an abstraction (interface, base class, plugin point, schema) or a migration is proposed, when someone asks for alternatives, a second opinion or an ADR, and when a plan or a spec is reviewed.

Operating mode

1. Frame before proposing

Restate the goal in one sentence, the constraints the user stated plus those the existing system implies (performance, security, compatibility, deadlines), and the non-goal. Solving the wrong problem is the costliest design error, so when the goal is too vague to frame, ask one question.

2. Surface at least two alternatives

A single proposal is a draft, not a design. For each non-trivial decision sketch two viable options and say in one line what each buys and what it costs:

Option A: <approach>
  Trade-off: <what A buys, at the cost of what>
Option B: <alternative>
  Trade-off: <what B buys, at the cost of what>
Recommendation: <A or B>, because <the constraint that breaks the tie>.

Do not invent a strawman to flatter the recommendation. When only one path is viable, say so and say why the others are not.

3. Ripple-effect analysis

For the recommended option list the blast radius: the files and modules that change, the public contracts that shift (API, schema, CLI, environment variables), the downstream consumers (other repositories, services, agents) and the reversibility (trivial, awkward or one-way). A one-way change gets an ADR, an awkward one a migration plan, a trivial one neither: over-documenting is its own cost.

When the change touches a skill's or an agent's scripts/, the built copies of the CLI trees are regenerated by the repository's build and ship in the same commit, so name that step in the blast radius; leaving it out makes the components check fail. <!-- crewrig-repo-only:start --> The build script is scripts/build-components.ts; it exists only in the CrewRig repository. <!-- crewrig-repo-only:end -->

4. Byte accounting for size-constrained plans

When a plan claims to bring something under a size, byte or token budget by moving, trimming or rewriting content, every savings figure comes from a measurement of the exact span, taken before the figure goes into the plan. Line counts and prose heuristics are not measurements, and a figure that is only a scoping estimate is labelled as one.

Run node scripts/measure-span.ts <file> <first>-<last>... --current <bytes> --budget <bytes> --margin <bytes> on the spans to move: it prints the exact bytes of each range, the total, the projected size and the margin. Exit 0 means the margin clears the threshold you set; exit 1 means a finding, either over budget or a margin thinner than the threshold, so add headroom (another candidate span) or flag the risk in the plan; exit 2 is a usage mistake; exit 3 means the file is unreadable or a range goes past its last line. State the threshold in the plan: a plan that lands 3 bytes under budget has no room for the next edit.

5. Output formats

Output	When	Where
Inline summary	Local, reversible decision	Chat reply
ADR (markdown)	One-way or contract change	docs/adr/NNNN-<slug>.md
RFC (issue)	Cross-team or cross-project	GitHub issue with label rfc

The layout and numbering of an ADR come from the doc-writer skill: its new-adr.ts lays the ADR out and its lint-adr.ts checks it. That skill is a separate install, so when doc-writer is not installed say so explicitly and use the repository order, Status first, then Context, Decision and Consequences, the last listing the positive, negative and neutral effects. Keep each section short (the Context a few sentences, none over ten lines) and record the rejected alternatives. A Context that needs two pages means the decision is not crisp yet.

6. Briefing sub-agents

When delegating a focused task (tester, security, doc-writer) put the call-graph context of each file in the brief: the entry points that invoke it in production, the sibling scripts that share its lifecycle (pre-checks, cleanup, idempotency guards) and the preconditions the harness provides without enforcing them. Copy the relevant blast-radius rows verbatim. A brief that names one file in isolation produces false positives, such as a missing guard that an upstream sibling already provides; that is a brief defect, not a sub-agent defect.

Grounding discipline

Read references/shared-grounding-discipline.md. In an ADR, an RFC or a design note, a claim about an environment variable, a command, a schema field, a path or a named guarantee ("atomic", "idempotent", "stateless") needs a source: a path with a line range, a command output or a sentence of the brief. A name you cannot trace is written as "assumption — verify before relying on this", or left out, never stated as a fact.

Finding class taxonomy

Read references/shared-finding-class-taxonomy.md. When this skill reviews a plan or a spec, every finding it emits, blocking or not, carries exactly one class: line whose value is tech, arch or spec; when the class is ambiguous, escalate to the upstream class rather than defaulting to tech.

Reviewer seat

Plan and spec reviews are seated: every pass is attributed to one seat, carries a seat: line and, from its second pass, reads a bounded scope (docs/reviewer-seat.md). Two facts are specific to this skill:

• Plan reviewer (plan/<ticket>): the seat: line goes right after the ### Verdict: … line; identifiers are v<N>-F<M>; from pass two the verdict opens with a traceability audit of every prior identifier; plan v2 and later are posted as deltas with a cumulative table.
• Spec reviewer (specs/<ticket>): identifiers are s<N>-F<M>, where <N> counts the seat's passes across every artifact; a delta-spec pull request is a replaced artifact, examined in full while every prior finding is still audited.

A plan or verdict comment stays within 12288 bytes: check it with wc -c < comment.md, and where the pr-reviewer skill is installed also with its check-comment-size.ts script. Check the verdict's format with the lint-verdict.ts script of the pr-reviewer skill, run as node <that skill's scripts directory>/lint-verdict.ts --surface plan --transport plan --ordinal <N> [--prior-ids <ids>] <file>: exit 1 lists malformed tags, identifiers or a misplaced seat line to fix before posting.

That skill is a separate install, so look for it before relying on it. When it is absent, say so in the verdict ("lint-verdict.ts not available: manual check") and apply references/verdict-manual-check.md instead; skipping the check silently is not an option, since a malformed finding costs the author a round trip.

Friction

Read references/shared-friction-reporting.md; when a signal fires, use the harness-report skill.