Skip to content
user

architect

Understand what exists, choose where to look, and act on evidence.

5 skills3 human gates20–90 min/session
Install this pack Read the reference

The contract

Use it when
You need to understand, harden, optimize, scale, modernize, rationalize, design, diagram, or review an architecture.
You type
Assess this architecture and provide an action plan.
You provide
The repository or system boundary, the decision you need to make, and approval for any evidence beyond ordinary read-only inspection.
You receive
A corrected current-state model, evidence coverage, attention hotspots, bounded findings, and traced action waves; or the routed design, diagram, or review artifact.

Where you decide

The agent pauses at these points. You choose whether to continue, redirect, or stop.

Correct the conceptual current stateDecision 1 of 3Choose the hotspot drill-downsDecision 2 of 3Accept the evidence and action priorityDecision 3 of 3

What changes when you install this

After installing architect, a broad request such as 'Assess architecture and provide an action plan' follows one progressive method instead of collapsing into a folder or compliance audit. architect-assess separates target evidence, enterprise context, and reusable pack knowledge; supports survey, standard, and deep stopping depths; and asks before private retrieval, execution, runtime evidence, experiments, or writes. architect-design owns future-state choices, architect-diagram owns the picture, architect-review owns supplied-artifact critique, and design-reviewer supplies the independent cold-context pass. Saved architecture-design and current-architecture outputs resolve separately; the user-scope pack remains useful in chat-only and explicit personal-workspace modes, while compatible repositories consume Core's semantic-surface-resolution.v1 and other repositories receive a zero-write portable handoff. The generated architecture-lenses-reference skill is internal knowledge routing, not a fifth user workflow.

The journey

Assess architecture and provide an action plan.

1. Frame the decision

  • You provide: the request above, optionally adding hardening, optimization, growth, transformation, or disposition intent.
  • Agent does: bounds the target and evidence, selects standard mode, names enterprise knowledge it can detect, and stays read-only.
  • You decide: correct scope or continue.
  • Output: an assessment charter with exclusions and unknowns.
  • State: read-only

2. Correct the current-state map

  • You provide: a boundary correction, or continue.
  • Agent does: inventories required evidence and maps context, runtime, modules, data, interactions, delivery/operations, and trust/identity.
  • You decide: accept the model before Focus.
  • Output: the conceptual model, evidence ledger, shape/workload hypotheses, and important unknowns.
  • State: read-only

3. Choose the hotspots

  • You provide: an added, removed, or redirected hotspot, or continue.
  • Agent does: shows consequence, pressure, coupling/concentration, verification weakness, exposure, and confidence separately.
  • You decide: stop with a survey or accept the drill-down set.
  • Output: an attention heat map and bounded hotspot cards. Heat is not finding severity.
  • State: read-only

4. Investigate and act

  • You provide: a request to continue in standard mode and separate approval for any executable, private, runtime, stakeholder, or experimental evidence.
  • Agent does: traces normal, side-effect, and failure/recovery paths; proves or refutes hypotheses; and sequences findings into action waves.
  • You decide: act, request more proof, or route a future-state choice.
  • Output: findings, strengths, unknowns, lens coverage, completion proof, containment, and one next decision.
  • State: draft

5. Save or review

  • You provide: “Save this assessment” or “Review this assessment report.”
  • Agent does: classifies the saved artifact as current architecture or architecture design, names chat-only, personal-workspace, repository-resolved, or repository-handoff mode, surfaces the final local path before an approved write only for a confined writable mode, stops a repository handoff without writing, or sends the supplied artifact through independent review without rescanning.
  • You decide: accept the report as decision evidence or revise it.
  • Output: <resolved destination>/<topic-slug>/assessment.md when saved, a portable repository handoff when Core is unavailable, or an inline severity-tagged report critique.
  • State: confirmed-write

Human gates

For each gate, everything you need to make a confident decision.

  • Correct the conceptual current state

    Trigger
    After Map shows the system boundary, views, evidence ledger, and unknowns
    Time
    5–15 minutes
    What to check, good, bad, consequence

    What to check

    • Are repositories, deployables, runtimes, data stores, and external systems distinguished?
    • Are responsibilities and trust boundaries recognizable?
    • Are inferred or missing dependencies marked instead of invented?

    What good looks like

    A conceptual model the team recognizes, with observed, inferred, reported, and unknown elements kept distinct.

    What bad looks like

    A directory tree relabeled as architecture, or a repo boundary treated as the whole production system.

    Consequence of skipping

    A wrong model distorts hotspot selection and every later finding; correct it before expensive investigation.

  • Choose the hotspot drill-downs

    Trigger
    After Focus shows raw attention dimensions and proposed hotspot cards
    Time
    5–10 minutes
    What to check, good, bad, consequence

    What to check

    • Do the raw signals and counter-evidence justify investigation?
    • Which user journey or quality scenario could be affected?
    • Is the proposed drill-down bounded and decision-relevant?

    What good looks like

    A small accepted set of hotspots with evidence pointers, plausible consequences, unknowns, and next checks.

    What bad looks like

    Heat treated as severity, or every large/churned file queued for equal investigation.

    Consequence of skipping

    Survey may stop here; standard and deep spend their investigation budget only on the accepted set.

  • Accept the evidence and action priority

    Trigger
    After Close presents findings, strengths, unknowns, action waves, coverage, and confidence
    Time
    15–30 minutes
    What to check, good, bad, consequence

    What to check

    • Does each finding trace evidence to a mechanism and stakeholder or measurable scenario?
    • Does every wave cite finding IDs, dependencies, completion proof, and containment or rollback?
    • Are active defects contained before generalized controls and broad modernization?
    • Which remaining uncertainty could change the decision?

    What good looks like

    Actions fit the assessment intent and can be proven complete without erasing strengths or unknowns.

    What bad looks like

    A generic cleanup or rewrite backlog derived from heat, style, file size, or best-practice claims.

    Consequence of skipping

    You decide whether to act, gather more evidence, save the report, or route a future-state choice to architect-design.

Typical session

Agent turns
4–10
Human gates
3
Wall-clock time
20–90 min

Install

agentbundle install --pack architect --scope user

Skills in this pack

  • architect-assess3 gates

    Maps and pressure-tests the implemented architecture through Frame, Map, Focus, Investigate, Act, and Close.

  • architect-design2 gates

    Shapes a Stage-0 concept, writes a Google-style design doc, and converges it against review.

  • architect-diagram1 gate

    Draws the system, flow, state, data model, or deployment topology in Mermaid.

  • architect-review1 gate

    Critiques an assessment, design doc, diagram, RFC, or ADR with a rubric-routed verdict and severity-tagged findings.

  • architecture-lenses-reference

    Supplies the architect pack's generated, read-only knowledge paths to its workflows; it is not a user-facing workflow.

Technical reference & next steps