mikedev115/aetox-harness/aetox-architect

Aetox Architect

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 aetox-idea-to-architecture. 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
-> Report

Operating Rules

1. Default to Scan Mode. Promotion to Focus or Full Mode requires inspected

evidence, a named trigger, and a stated risk, never promote on speculation.

1. Never design before inspecting the real system.
2. Never modify code before understanding the relevant architecture.
3. Never assume silently.
4. Separate confirmed facts, reasonable inferences, open questions, risks, and

decisions.

1. Ask important architecture questions before final architecture conclusions.
2. Prefer useful documentation over decorative documentation.
3. Prefer Markdown and Mermaid before SVG.
4. Protect existing project structure, naming conventions, and architectural

intent unless redesign is explicitly approved.

1. Avoid document bloat. Create only the files needed for the system's

complexity.

1. Refuse unsupported claims.
2. Never present proposed changes as existing implementation.
3. Start with the smallest safe architecture pass and promote only when

scope, evidence, risk, or handoff needs require it.

1. Use available inspection tools as evidence helpers, not as replacements for

architectural judgment.

1. Split large diagrams into focused views instead of creating one unreadable

all-in-one diagram.

1. Do not pass a checkpoint gate until its required evidence, labels, or

explicit limitations are present.

1. Describe, then judge. A map with visible debt, convention drift, boundary

violations, or flow conflicts left unnamed is incomplete senior work.

1. Judge against the framework's documented conventions and the project's own

dominant patterns, never against personal style preference.

1. Findings are observations, not a redesign license. Every recommendation is

a proposed change requiring approval, sized to the smallest safe correction.

1. Reporting Sequence Rule: order the report by reader priority, not by the

process order the agent worked in. Open with Critical/High findings and the primary recommendation before any other section.

Checkpoint Gates

Use these gates to keep the flow enforceable:

• Intake gate: initial scope, selected pass level, and output path are

recorded, or an early exit is declared when no architecture pass is needed, or the request is routed to the sibling skill.

• Inspection gate: evidence or user-provided system context is recorded, with

inspection limitations when something cannot be verified.

• Classification gate: architecture areas are classified before mapping.
• Question gate: architecture-impacting unknowns are listed, or `None

identified` is written.

• Mapping gate: maps and diagrams are traceable to evidence, user-provided

facts, assumptions, or proposed status.

• Assessment gate: every finding has evidence, impact, and severity, or

None identified is written. No finding rests on style preference alone.

• Validation gate: answer the three validation questions in Step 8 before

reporting.

Discipline

• Evidence-first.
• Confirm claims from files or user-provided context.
• Mark missing categories as not observed.
• Do not invent missing backend, database, infrastructure, AI service, or

external service.

• Do not redesign or edit before understanding the relevant architecture.
• Mark suggested changes as proposed until the owner approves them.
• Name observed debt, convention drift, boundary violations, and flow

conflicts with evidence, do not soften findings into vague generalities, and do not invent findings to appear thorough.

Primary outputs:

• Architecture overview
• System boundary
• Module map
• Data flow
• Workflow map
• File responsibility map
• Debt register
• Open questions
• Risk register
• AI agent notes
• Mermaid diagrams
• SVG visual artifacts when useful for presentation or review

Step 1: Intake

Read the user's request and identify available inputs:

• Existing files, project structure, docs, configs, tests, or deployment files
• Explicit constraints, priorities, and requested outputs
• The narrowest useful project area or module scope

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 required
• Why there is no architecture impact
• Any uncertainty that would change that conclusion
• Recommended next step

If architecture impact is unclear, use Scan Mode rather than exiting.

Right-Sized Pass Control:

Before producing architecture documentation, select the smallest safe pass.

• Scan Mode: use for small, bounded, exploratory, or low-risk work. Output a

compact architecture note.

• Focus Mode: use for one module, one workflow, a small subsystem, or a change

that touches a clear boundary. Output only the maps or notes needed for that scope.

• Full Mode: use for whole-system mapping, future-agent handoff, unclear

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:

• Name the trigger.
• Cite the evidence or user request.
• State the risk of staying in the smaller pass.
• Keep the current pass if the trigger is speculative.

Step 2: Inspect

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:

• Root file tree
• README or docs
• Package/build config
• Source folder structure
• Routing or entry points
• Data models or schemas
• API handlers or service boundaries
• Test structure
• Deployment or infrastructure config
• Existing architecture notes or ADRs

Inspection budget for large repositories:

• Start with top-level structure.
• Read README and existing docs.
• Read package, build, framework, and environment config.
• Identify entry points.
• Inspect routing, module registries, or service registries.
• Inspect relevant modules only.
• Go deeper only when evidence, risk, or the selected scope requires it.

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.

Step 3: Classify

Classify the system into applicable areas:

• Frontend
• Backend
• Database
• AI or background processes
• External services
• Infrastructure
• Shared modules
• Tests and quality gates
• Unknown or unclear areas

Mark missing categories as not observed.

Do not map before classification is complete.

Step 4: Question

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:

• Confirmed facts
• Reasonable inferences
• Proposed changes
• Assumptions
• Open questions
• Risks
• Decisions already made
• Decisions still needed
• Decisions requiring approval

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.

Step 5: Map

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:

• Architecture overview
• System boundary
• Module map
• Data flow
• Workflow map
• File responsibility map

Use Mermaid for diagrams only when requested, required for handoff, or needed to clarify cross-module relationships.