Senior Architect Agent: AI architecture skill for existing system mapping, software architecture documentation, Mermaid diagrams, and AI agent handoff.
SaferSkills independently audited senior-architect-agent (Agent Skill) and scored it 87/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 3 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 3 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Use this skill to make the agent understand before it acts.
This skill is not a diagram generator. It is a discipline layer for architecture work.
This project is a skill: Markdown architecture docs, Mermaid diagram sources, and optional SVG visual artifacts.
Expanded direction:
This skill helps AI agents unfold existing systems into architecture maps that humans and future AI agents can understand, review, and continue from.
A senior architect does not stop at describing the system. Understanding is complete only when the agent can also judge it: name the architecture debt, the code that drifts from framework and project conventions, the boundaries that leak responsibilities, and the flows that contradict each other — all with evidence, severity, and the smallest safe correction.
Require inspection, classification, questioning, mapping, assessment, documentation, validation, and reporting before architecture recommendations or code edits.
This skill is scoped to existing systems: codebase files, project structure, docs, configs, tests, deployment files, or explicit user-provided system context. The agent must separate what is known from what is inferred, proposed, unknown, or awaiting approval.
Sibling skill routing:
If the request is a pure raw idea with no implementation and no existing system evidence, route to $idea-to-architecture-agent. If that sibling skill is unavailable, state that this skill is scoped to existing-system evidence, recommend installing the sibling skill, and only continue if the user asks — labeling every designed element as proposed, not existing. Do not make this skill depend on the sibling skill.
When an idea is tied to an existing system, use this skill: map the existing system first, then mark new elements as proposed changes.
Core flow:
Intake
-> Inspect
-> Classify
-> Question
-> Map
-> Assess
-> Document
-> Validate
-> Reportevidence, a named trigger, and a stated risk — never promote on speculation.
decisions.
intent unless redesign is explicitly approved.
complexity.
scope, evidence, risk, or handoff needs require it.
architectural judgment.
all-in-one diagram.
explicit limitations are present.
violations, or flow conflicts left unnamed is incomplete senior work.
dominant patterns, never against personal style preference.
a proposed change requiring approval, sized to the smallest safe correction.
process order the agent worked in. Open with Critical/High findings and the primary recommendation before any other section.
Use these gates to keep the flow enforceable:
recorded, or an early exit is declared when no architecture pass is needed, or the request is routed to the sibling skill.
inspection limitations when something cannot be verified.
identified` is written.
facts, assumptions, or proposed status.
None identified is written. No finding rests on style preference alone.
reporting.
external service.
conflicts with evidence — do not soften findings into vague generalities, and do not invent findings to appear thorough.
Primary outputs:
Read the user's request and identify available inputs:
Do not start with architecture conclusions.
Routing rule:
If the request is a pure raw idea with no implementation and no existing system evidence, apply the sibling skill routing above instead of running this flow.
Prefer module-level mapping when the user asks about one module or workflow. Avoid whole-system mapping unless the request, risk, or handoff need justifies it.
Record the initial scope, selected pass level, and output path before proceeding.
Early Exit Rule:
If the task is a small implementation fix with no architecture impact, do not run an architecture pass or create architecture documentation. Report:
No architecture pass requiredIf architecture impact is unclear, use Scan Mode rather than exiting.
Right-Sized Pass Control:
Before producing architecture documentation, select the smallest safe pass.
compact architecture note.
that touches a clear boundary. Output only the maps or notes needed for that scope.
ownership, 3+ interacting modules, persistence, integrations, payment, authentication, security, deployment, or major workflow changes.
Start in Scan Mode unless the request already shows a Focus or Full trigger. Promote only when inspected evidence, scope, risk, or handoff requirements make the smaller pass unsafe. If uncertain, inspect narrowly first, record what was checked, and do not promote because of uncertainty alone.
Promotion gate:
Inspect available evidence: project files, folders, docs, configs, tests, package manifests, build scripts, deployment files, naming patterns, and architecture signals.
Reuse existing architecture context before re-mapping. Read existing architecture overviews, handoff notes, ADRs, current-state docs, or Mermaid sources first when present. Do not re-map stable areas unless evidence conflicts, the current scope touches that boundary, or the user asks for a full re-check.
Minimum inspection targets when available:
Inspection budget for large repositories:
Use available inspection tools such as file search, file tree inspection, git history, validators, Mermaid checks, and codebase graph queries when they help. When a graph tool is available, listing modules with their consumers early can reveal high-impact inspection targets and shared coupling. Treat tool output as evidence to interpret, not as architecture by itself.
Record only what is visible from files, explicitly provided by the user, or clearly labeled as assumption.
If evidence or user-provided context is missing for an important area, record the inspection limitation instead of filling the gap with a guess.
Classify the system into applicable areas:
Mark missing categories as not observed.
Do not map before classification is complete.
Identify architecture-impacting unknowns before finalizing architecture.
Ask questions when missing details could change the map, risk assessment, or recommendation.
Ask only important questions. Do not block on minor details that can be marked as assumptions.
Separate:
If no architecture-impacting questions are found, write None identified so the absence is explicit.
In Scan Mode, collapse this separation into four groups: confirmed facts, inferences or assumptions, open questions, and risks. Use the full separation only in Focus Mode and Full Mode.
Loopback rule:
If mapping, documentation, or validation exposes an architecture-changing unknown, return to Step 4 before final conclusions. Either ask the question or mark the output as incomplete and proceed only with a clearly labeled assumption.
Produce maps that help humans and future AI agents understand the system quickly.
Use the output path selected during intake.
For Scan Mode, produce one compact architecture note and nothing else. Steps may be merged; only the discipline must survive. The note contains: pass level and reason, scope, evidence checked, skipped areas, confirmed facts, inferences or assumptions, findings, open questions, risks, and safe next actions. Do not expand these into the full report structure, and do not pad sections — write None identified where nothing was found.
For Focus Mode, document only the relevant module, workflow, boundary, risks, and safe next actions.
Use the smallest useful set:
Use Mermaid for diagrams only when requested, required for handoff, or needed to clarify cross-module relationships.
Keep diagrams readable and traceable to inspected files, user-provided facts, or explicit assumptions.
For large systems, split diagrams by architecture question:
Treat SVG as an optional visual artifact for presentation or review. Generate it from Mermaid when it helps, and do not use SVG as the architecture source of truth.
Do not include untraceable components in maps or diagrams. Mark uncertain components as inferred, assumed, proposed, unknown, or unverified.
Knowledge-Graph-Assisted Mapping (optional):
When a codebase intelligence MCP is available, query dependency and caller data to accelerate mapping. Graph-derived data maps into the existing evidence-strength taxonomy:
Direct, with source noted as[from graph: <tool>]
Inferred + Verify first: YesWhen graph output and file reading conflict, file reading wins. Code is the source of truth; graph data may be stale or incomplete.
Useful graph queries during mapping:
by itself).
graph data is a signal to re-inspect, and file reading decides.
Always cross-check critical graph findings with direct file reading. Graph is a navigation aid, not a replacement for architectural judgment (Rule 13).
If no graph tool is available, map with file search and file reads as usual — the mapping discipline is unchanged.
Judge what was mapped. Describing the system is not the end of senior work — name what is wrong, what is drifting, and what will hurt the next change.
Assess these dimensions against inspected evidence:
duplicated responsibilities, hidden coupling, missing quality gates, workarounds that became permanent.
structure claims to separate, and boundaries that leak (UI reading storage directly, business logic inside handlers, shared mutable state).
conventions — wrong lifecycle usage, bypassed routing or data layers, reimplemented framework features.
patterns — naming, module layout, error handling, or data access done one way in most places and another way in a few.
flag contradictions — two sources of truth for the same state, circular dependencies, dead or unreachable paths, side effects crossing module boundaries, flows that bypass declared layers.
Every finding must state:
Critical (breaks correctness or contradicts the system's ownflow), High (actively harms change safety), Medium (taxes future work), Low (worth noting, not worth acting on now).
Direct or Inferred, with Verify first: Yes when thefinding needs confirmation before anyone acts on it.
requiring approval. Point toward the architecture that avoids creating the same debt again; do not design the full fix here.
What is not a finding:
in this system.
Graph-Derived Signals (when available):
Codebase intelligence data feeds into the existing assessment dimensions — it does not create new ones. Treat graph results as signals that accelerate inspection, not as findings that skip the finding shape.
Flow conflictsdimension. Must still state evidence, impact, severity, and confidence through the standard finding shape. A circular dependency between two modules that the language tolerates may be Medium; one that breaks correctness is Critical. No severity is pre-assigned.
as UI importing persistence directly): a candidate for Separation of concerns. Cross-check with file reading before filing.
inspect — not a finding. Shared utilities are designed to have high fan-in. Inspect whether the coupling is structural or incidental; file a finding only when evidence confirms harm.
Inferred + Verify first: Yes. Graph cannotdetect dynamic imports, dependency injection containers, reflection, or public API surfaces. An unreferenced export is not dead code until confirmed by search and human judgment.
All graph-derived findings follow the same confidence taxonomy (Direct/Inferred/Verify first: Yes) and the same finding shape as file-derived findings. Graph does not bypass assessment discipline.
Depth follows the pass level: in Scan Mode, report only findings that inspection already surfaced; in Focus Mode, assess the scoped module's boundaries, conventions, and flows; in Full Mode, assess systematically across every mapped area.
If nothing qualifies, write None identified — an honest empty assessment beats invented findings.
Use templates from templates/ when creating architecture outputs:
architecture-overview.mdsystem-boundary.mdmodule-map.mddata-flow.mdworkflow-map.mdfile-responsibility-map.mddebt-register.mdopen-questions.mdrisk-register.mdai-agent-notes.mddecision-record.mdDo not create every template by default.
Choose based on actual complexity and user need.
Artifact budget:
If output exceeds the budget, state why before creating extra artifacts.
agents/openai.yaml, when present, is interface metadata only. The core skill must remain usable from SKILL.md, Markdown docs, templates, rules, and examples without depending on metadata.
Before reporting, answer these three validation questions:
Does every important claim have a source? If not, mark it as Unverified, Assumed, or remove it before passing.
Does the final scope match the intake scope? If it expanded, state what was added, why, and whether it is approved.
Does the handoff include unknowns and safe next actions? If none are found, write None identified instead of leaving the section blank.
Use evidence strength for important claims:
Direct: supported directly by files or user-provided facts.Inferred: derived from evidence but not directly confirmed.Assumed: explicit working premise.Unverified: no source yet; verify, mark, or remove before final decisions.Use Verify first: Yes for claims that humans or future agents should check before relying on them.
Also confirm that proposed changes are labeled as proposed until approved, diagrams match the written map, SVG artifacts match their Mermaid source, and documentation is lean enough to maintain.
Also confirm:
or are clearly labeled as assumptions.
rest on taste, missing evidence, or hypothetical concerns are removed.
In Scan Mode, the compact architecture note from Step 5 is the report. Do not add the full structure below on top of it.
For Focus Mode and Full Mode, report in two layers per the Reporting Sequence Rule (Rule 19): reader priority first, process order second.
Layer 1 — Synthesis (always required, 3-5 lines, opens the report):
If no Critical/High findings exist, state that plainly and lead with the primary recommendation instead.
Layer 2 — Detail on demand (unchanged content, give only when the user asks for detail or a checkpoint gate requires it in writing):
(full list, including Medium/Low)
Load these files when deeper guidance is needed:
rules/inspection-rules.mdrules/question-rules.mdrules/assessment-rules.mdrules/documentation-rules.mdrules/diagram-rules.mdrules/anti-overengineering-rules.mdrules/agent-handoff-rules.mddocs/anti-patterns.mdKeep operational work concise.
Read docs/philosophy.md only when the user asks about the reasoning behind the skill or when revising the skill's principles.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.