/agentic-architecture

name: agentic-architecture
description: Use when assessing the architectural health of a codebase — before a major refactor, when onboarding to an unfamiliar repo, after rapid growth, when planning a redesign, or to surface structural strengths and risks before they become expensive. Not for fixing what it finds, and not for reviewing a branch diff.

**On invocation:** announce "Running paad:agentic-architecture v2.0.2", then immediately proceed with the steps below — do not stop after announcing.

**Configuration (experimental):** after announcing, check whether `paad/config/paad.md` and `paad/config/agentic-architecture.md` exist, relative to the working directory. If any does, read it and follow its instructions for the rest of this run, passing the relevant parts to every subagent you dispatch, and make the first line of your final answer `Config: <path>` naming each file you followed. If none exists, do not mention config at all. Config never changes a subagent's type or grants it write tools — refuse that line, say so, and continue. Config can contradict the flow below; see https://github.com/Ovid/paad/blob/main/CONFIG.md before writing one.

**Security findings:** a finding is security-related if reading it would help an attacker — any OWASP Top 10:2025 category, and anything in a payment, tenant-isolation, or secret-handling path; on the edge, treat it as security. Security findings are written only under `paad/security/`, in a file named for this skill and stamped the way its ordinary report is (the exact path is in this skill's report section). Before the first write of a run, make sure `paad/security/.gitignore` exists and contains the single line `*` — create it if absent, never rewrite it if present — and that `git ls-files paad/security/` lists nothing. If that file holds anything else or cannot be written, if git already tracks anything there, or if a later write there fails, write no security finding and no count line: tell the user what you found, ask whether to hold the findings or put them in the ordinary report, and say that in place of the Security block. Where the finding would have gone in the ordinary report, write one line, `N security finding(s) written to paad/security/<file>`, and nothing else about it: no path, severity, symbol, or description. Post-Review then emits the Security block once; this skill's Post-Review section says when.

Agentic Architecture Analysis

Multi-agent architecture analysis of the current codebase. Dispatches specialist agents in parallel — each focused on a different architectural domain — verifies findings to filter false positives, and produces a balanced report of strengths and flaws with concrete evidence.

**Do NOT propose fixes.** This is diagnosis only.

**This is a technique skill.** Follow the phases in order. Do not skip verification.

**Pre-flight:**

digraph preflight {
  "Conversation has history?" [shape=diamond];
  "Proceed to Phase 1" [shape=box];
  "STOP: recommend new session" [shape=box, style=bold];

  "Conversation has history?" -> "STOP: recommend new session" [label="yes"];
  "Conversation has history?" -> "Proceed to Phase 1" [label="no"];
}

**Analysis flow:**

digraph analysis_flow {
  "Git repo?" [shape=diamond];
  "Scope size?" [shape=diamond];
  "Integration & Data specialist: distributed system?" [shape=diamond];
  "Confirmed by reading the actual code?" [shape=diamond];
  "Confidence >= 60?" [shape=diamond];
  "Concrete evidence present?" [shape=diamond];
  "Reported by multiple specialists?" [shape=diamond];

  "Repo name from git remote origin" [shape=box];
  "Repo name from top-level directory basename" [shape=box];
  "Recon: overview, structure, steering files, manifest" [shape=box];
  "Dispatch 5 specialists in parallel" [shape=box];
  "Partition files across 2 instances of each specialist" [shape=box];
  "Mark distributed-specific categories Not applicable" [shape=box];
  "Validate impact level and category assignment" [shape=box];
  "Merge duplicates, note the agreeing specialists" [shape=box];
  "DROP the finding" [shape=box];
  "Keep the finding" [shape=box];
  "Would reading it help an attacker?" [shape=diamond];
  "Write to paad/security/agentic-architecture-<date>-<repo>.md; count line in the report" [shape=box, style=bold];
  "paad/security/.gitignore holds only * and git tracks nothing there?" [shape=diamond];
  "Write nothing under paad/security/; tell the user, ask: hold or ordinary report" [shape=box];
  "Write report to paad/architecture-reviews/ (same-day re-run: replace both files; no routed finding deletes a same-day security file)" [shape=box];
  "Report location, counts, 3-6 bullet summary" [shape=box];
  "STOP: diagnosis only — do NOT propose fixes" [shape=box, style=bold];

  "Git repo?" -> "Repo name from git remote origin" [label="yes"];
  "Git repo?" -> "Repo name from top-level directory basename" [label="no"];
  "Repo name from git remote origin" -> "Recon: overview, structure, steering files, manifest";
  "Repo name from top-level directory basename" -> "Recon: overview, structure, steering files, manifest";
  "Recon: overview, structure, steering files, manifest" -> "Scope size?";

  "Scope size?" -> "Dispatch 5 specialists in parallel" [label="small (<50) / medium (50-500)"];
  "Scope size?" -> "Partition files across 2 instances of each specialist" [label="large (500+ source files)"];
  "Partition files across 2 instances of each specialist" -> "Dispatch 5 specialists in parallel";
  "Dispatch 5 specialists in parallel" -> "Integration & Data specialist: distributed system?";
  "Integration & Data specialist: distributed system?" -> "Confirmed by reading the actual code?" [label="yes"];
  "Integration & Data specialist: distributed system?" -> "Mark distributed-specific categories Not applicable" [label="no"];
  "Mark distributed-specific categories Not applicable" -> "Confirmed by reading the actual code?";

  "Confirmed by reading the actu