Agentic Architecture

On invocation: announce "Running paad:agentic-architecture v1.31.0" before anything else.

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];
  "Write report to paad/architecture-reviews/" [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 actual code?" -> "Confidence >= 60?" [label="yes — verifier per finding"];
  "Confirmed by reading the actual code?" -> "DROP the finding" [label="no"];
  "Confidence >= 60?" -> "Concrete evidence present?" [label="yes"];
  "Confidence >= 60?" -> "DROP the finding" [label="no"];
  "Concrete evidence present?" -> "Validate impact level and category assignment" [label="yes (path, symbol, excerpt)"];
  "Concrete evidence present?" -> "DROP the finding" [label="no"];
  "Validate impact level and category assignment" -> "Reported by multiple specialists?";
  "Reported by multiple specialists?" -> "Merge duplicates, note the agreeing specialists" [label="yes"];
  "Reported by multiple specialists?" -> "Keep the finding" [label="no"];
  "Merge duplicates, note the agreeing specialists" -> "Keep the finding";

  "Keep the finding" -> "Write report to paad/architecture-reviews/";
  "DROP the finding" -> "Write report to paad/architecture-reviews/" [label="counted under Filtered out"];
  "Write report to paad/architecture-reviews/" -> "Report location, counts, 3-6 bullet summary";
  "Report location, counts, 3-6 bullet summary" -> "STOP: diagnosis only — do NOT propose fixes";
}

When NOT to Use This Skill

• You already have a recent report — re-running burns a session to regenerate what you have. Read the existing report in paad/architecture-reviews/ and use /fix-architecture, which handles staleness itself.
• The scope is a handful of files — architecture is about boundaries and relationships between components. Below that scale there's no structure to assess, and the report will pad.

Arguments

/agentic-architecture accepts optional $ARGUMENTS:

• /agentic-architecture — analyze the entire repository
• /agentic-architecture src/ — scope the analysis to a specific directory (useful for monorepos or analyzing one service)
• /agentic-architecture packages/api/ packages/shared/ — analyze multiple directories together

When a path is provided, focus the analysis on that scope but still note dependencies on code outside the scope.

Pre-flight Checks

1. Context window: If conversation has substantive history beyond invoking this skill, tell the user: "This analysis consumes significant context. Start a fresh session with /agentic-architecture to avoid context rot." Stop and wait.

Phase 1: Reconnaissance

Run these steps and collect results:

1. Repo identification:

   • Detect if this is a git repo (git rev-parse)
   • Determine repo name from git remote get-url origin (strip .git, take last segment) or basename of top-level directory
   • Set output filename accordingly

2. Repo overview:

   • Identify primary languages/frameworks
   • Identify key directories (apps/, services/, packages/, src/, lib/, etc.)
   • Estimate size: number of services/modules/packages

3. Dependency & structure snapshot:

   • Top-level modules/packages and their relationships
   • Quick import graph via heuristics (look for cross-layer imports, circular patterns)
   • Note positive structure signals (clean layering, bounded contexts)

4. Scan for steering files: CLAUDE.md, AGENTS.md, architecture docs, ADRs

5. Estimate scope size:

   • Small: <50 source files
   • Medium: 50-500 source files
   • Large: 500+ source files

6. Build manifest: source files grouped for specialists, annotated with module/package boundaries

Steering file caveat: Include in every agent prompt: "Steering files (CLAUDE.md, etc.) describe conventions but may be stale. If you find a contradiction between steering files and actual code, flag it as a finding."

Phase 2: Specialist Analysis (Parallel)

Dispatch these agents simultaneously using the Agent tool with subagent_type: paad:paad-analyst. Each receives: the file manifest, repo overview, steering file contents, and their specialist focus.

Specialists

Agent prompt template

Each specialist agent prompt must include:

• The file manifest for their scope
• Repo overview and structure snapshot
• Steering file contents with the staleness caveat
• Their assigned flaw types and strength categories with descriptions
• Instruction: "You are an architecture specialist focused on [DOMAIN]. Find both strengths and flaws in the assigned categories. For each finding report: the category (flaw type number or strength category), file:line, a short label, 1-2 sentence explanation, concrete evidence (path, symbol, excerpt), impact level (High/Medium/Low), and your confidence (0-100). Only report findings with confidence >= 60. Validate every candidate by reading the actual code — do not infer from file names alone. Do not modify any file in the repository. You may run read-only commands (existing tests, linters, type checkers) unchanged — their caches, coverage files, and build output are fine. If confirming a finding would require changing code, do not — cap that finding's confidence at 79 and state what would confirm it."

Structure & Boundaries additional instruction: "Look for: module-level mutable variables, singletons, static mutables; very large classes/files with high fan-in/fan-out; single logical changes requiring edits across many files; business logic in services while domain objects are just data bags; modules grouping unrelated behaviors; drifting responsibilities between layers; generic helper modules growing into grab-bags. Also look for the positive: clean module organization, high cohesion, strong domain modeling, pragmatic abstractions."

Coupling & Dependencies additional instruction: "Look for: concrete instantiations instead of abstractions, core depending on leaf modules, circular imports, abstractions requiring callers to know internals, excessive layers/interfaces for uncertain future needs, architecture optimized without evidence, DI obscuring control flow, components requiring specific call order. Also look for the positive: clean interfaces, stable dependency direction, minimal circular deps, consistent import conventions."

Integration & Data additional instruction: "Look for: microservices with heavy synchronous coupling, too many small network calls, everything requiring immediate responses, multiple services writing same data, services coupled through shared schemas, non-idempotent operations, API contracts without compatibility discipline, operations spanning systems without strategy. Also look for the positive: consistent API versioning, resilience patterns (timeouts, retries, circuit breakers, backpressure). If this is not a distributed system, mark distributed-specific categories as Not applicable."

Error Handling & Observability additional instruction: "Look for: functions doing more than signatures suggest, errors swallowed or over-generalized, missing logs/metrics/traces, scattered configs with unclear precedence, critical rules in frontend code, hard-coded magic values, inconsistent error/logging formats across services. Also look for the positive: consistent error taxonomy, structured logging with correlation IDs, centralized config, safe defaults."

Security & Code Quality additional instruction: "Look for: auth bolted on late, secrets in source, missing trust boundaries, unused packages/files/modules, unreachable code, stale feature flags, critical paths without tests. Also look for the positive: authN/Z patterns, secret management, least privilege, tests around critical paths, good test seams, deterministic tests."

Refactor history instruction (include in all agent prompts): "Before flagging a candidate flaw, use git log --oneline on the relevant files/directories to check whether the current code is the result of recent intentional work. A large file with many recent commits may be a completed refactor, not a neglected problem. Intentional design choices can still be flawed — check history to understand context, not to dismiss findings."

Scaling for large codebases (500+ source files): Partition files across 2 instances of each specialist.