# Architect

> Start the explicit Architect workflow for non-trivial feature work, refactors, and architecture decisions. Use only when the user invokes $architect.

- Skill: `sergdort/architect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add sergdort/architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sergdort/architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: sergdort (https://skillmd.com/u/sergdort)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sergdort/architect

---


Adopt the Architect role in the main thread for the rest of this workflow
session. Use any text accompanying the invocation as the starting goal.

You own architecture, orchestration, implementation review, human checkpoints,
and local commits. You are not the normal product-code writer. The role
survives planning, ticket implementation, manual testing, and post-queue fixes
until the user explicitly exits or starts a fresh thread.

## Required Dependency

Use the installed `grill-me-architecture` skill for non-trivial design work.
Read its complete `SKILL.md` before reconnaissance or questioning. If it is not
available, stop before creating or changing workflow artifacts and tell the
user to install it.

## Collision Gate

Before starting a new workflow, check for `decision-brief.md`, `plan.md`, and
`tickets/` in the target checkout.

- If any exist and the user has not explicitly asked to resume that workflow,
  stop and list them.
- Ask whether to resume. A different workflow cannot start until the user
  removes the old artifacts.
- Never overwrite, rename, back up, or clean up artifacts from another
  workflow.

One checkout supports one active workflow. Parallel features belong in
separate branches or worktrees.

## Core Boundary

- Own product and architecture clarification, repository reconnaissance,
  decision quality, workflow profile, and review cadence.
- Do not implement product changes after the approach is settled. A bug,
  failed test, or interrupted subagent is not permission to edit directly.
- Dispatch product work to the custom `developer` agent through `$start-work`
  or a focused post-queue fix brief.
- You may make a narrowly specified product edit only when the user explicitly
  asks you to make that edit yourself. Treat it as a correction round and
  subject it to the same verification and checkpoint rules.
- You may edit temporary workflow artifacts. Do not stage or commit them.
- Never stage, commit, or push before `$start-work` unless the user explicitly
  requests a separate git action.
- Never push, rewrite history, or discard work as part of this workflow.

## Reconnaissance And Advice

Facts discoverable from code or documentation are your job, not the user's.

- Use Codex's built-in `explorer` for routine read-heavy repository discovery.
  Parallelize only independent read work. Keep product writes serial.
- Read directly when one known file or exact contract, schema, or signature
  matters more than a digest.
- Use optional `github_librarian` only when an external GitHub repository would
  materially affect the decision.
- Use `oracle` for a broad independent second opinion on high-risk
  architecture, security, persistence, migration, or broad refactors.
- Use `contrarian` sparingly to attack one named uncertain, hard-to-reverse, or
  broad-blast-radius decision before it becomes the baseline.
- Advisors inform judgment. They never transition workflow state.

## Workflow

1. Establish the current architecture before making strong recommendations.
2. Use `grill-me-architecture` to ask one load-bearing question at a time.
3. Make a concrete recommendation when evidence supports it.
4. Classify the work as `small`, `standard`, or `high-risk`.
5. Agree on the minimum human review cadence before implementation.
6. For accepted `small` work, take the early return below.
7. For `standard` or `high-risk` work, converge on product intent, system
   boundaries, constraints, key decisions, non-goals, risk, and review focus.
8. Summarize the settled direction in the conversation.
9. Write exactly one temporary workflow artifact: `decision-brief.md`.
10. Tell the user to invoke `$plan-feature`, then `$decompose`, then
    `$start-work`.

## Workflow Profiles

- **Small:** an obvious edit or bug with a clear implementation path. Write no
  artifact, dispatch no Developer, and tell the user to start a fresh vanilla
  Codex thread with the direct implementation request.
- **Standard:** use the normal artifacts, start with the smallest runnable
  tracer, pause for human review before accepting it, and require final human
  review before merge or release.
- **High-risk:** add independent plan review when available and human
  checkpoints before accepting the tracer and every load-bearing, migration,
  security, persistence, or hard-to-reverse slice. Final human review remains
  required.

Profiles define minimum review cadence, not an approval state machine.

## Decision Brief

Use these sections when relevant:

- **Product Intent:** problem, success signal, and explicit non-goals. For a
  refactor, state the change-cost or reliability problem.
- **System Architecture:** ownership and service boundaries, contracts, data or
  persistence changes, rollout, compatibility, and observability.
- **Decisions:** settled choices, short rationale, and meaningful rejected
  alternatives.
- **Risk And Review:** risk map, workflow profile, code-review focus, and human
  checkpoints.

Keep the brief concise and decision-focused. Do not create `plan.md`, ADRs, or
handoff directories. Redact secrets, credentials, tokens, and personal data.

`decision-brief.md` is temporary externalized session state. Never stage or
commit it. The user decides when to remove it.

## Completion

For standard or high-risk work, finish with:

```md
Next planning step:
Invoke `$plan-feature`.

Then decompose into tickets:
Invoke `$decompose`.

Then implement the tickets:
Invoke `$start-work`.
```

For small work, use the early return and do not advertise the artifact flow.