architect

Turn approved architecture-design artifacts, with supporting review findings when present, into an incremental implementation/refactoring plan. Use when asked to plan a refactor, sequence remediation, or implement an approved target architecture. Produces a task-runner-compatible, verifiable plan that cites source findings, evidence, design decisions, contracts, or risks. NOT for applying changes (hand off to a mutator agent), designing target architecture (use architecture-design), or scoring (use architecture-scorecard).

Run a repeatable, evidence-based architecture review of an existing codebase. Use when asked to assess modularity, coupling, cohesion, dependency direction, circular dependencies, blast radius, fragile seams, shallow modules, testability, ownership boundaries, architectural drift, structural risk, or fit between intended and observed architecture. Drives local search/read/grep, code graph, GitNexus/change-history, AST/LSP, language, and operational tool evidence; scores with the scorecard and writes cited findings. NOT for line-level code review, target architecture design (use architecture-design), or implementation sequencing (use architecture-plan after design approval). When archfit is available, consumes and calibrates its deterministic facts without replacing independent review judgment.

Gather deterministic architecture-fitness evidence with archfit: full checks, scorecards, deltas, SARIF/JSON findings, tool coverage, and agent_tasks. Use when a repo has .archfit.yaml or the user wants architect to combine its review with archfit. Produces hard facts for architecture-review to calibrate, not a replacement for independent design judgment. NOT for running archfit LLM review as source-of-truth, changing archfit config, baselining findings, or applying fixes.

Gather persistent code-knowledge-graph evidence from the codebase-memory-mcp MCP server: architecture overview, type-resolved call edges, cycles, blast radius, module clusters, dead code, and cross-session ADR memory. Use when `mcp__codebase-memory-mcp__*` tools are available and you need graph-shaped structure, coupling, or impact evidence without re-reading files. A degraded or stale index is a coverage gap, not evidence. NOT for exact text discovery (use tools-code-search), syntactic patterns (use tools-ast-grep), or git change-coupling/churn (use tools-gitnexus); when this server is absent, fall back to tools-codegraph for the same graph evidence.

Turn approved architecture-design artifacts, with supporting review findings when present, into an incremental implementation/refactoring plan. Use when asked to plan a refactor, sequence remediation, or implement an approved target architecture. Produces a task-runner-compatible, verifiable plan that cites source findings, evidence, design decisions, contracts, or risks. NOT for applying changes (hand off to a mutator agent), designing target architecture (use architecture-design), or scoring (use architecture-scorecard).

Run a repeatable, evidence-based architecture review of an existing codebase. Use when asked to assess modularity, coupling, cohesion, dependency direction, circular dependencies, blast radius, fragile seams, shallow modules, testability, ownership boundaries, architectural drift, structural risk, or fit between intended and observed architecture. Drives local search/read/grep, code graph, GitNexus/change-history, AST/LSP, language, and operational tool evidence; scores with the scorecard and writes cited findings. NOT for line-level code review, target architecture design (use architecture-design), or implementation sequencing (use architecture-plan after design approval). When archfit is available, consumes and calibrates its deterministic facts without replacing independent review judgment.

Gather change-coupling and volatility evidence with GitNexus git-history graphs: files that change together, churn hotspots, historical blast radius, and impact over time. Use when scoring change_locality, corroborating Balanced Coupling volatility (domain role sets it; churn only supports it), or checking whether changes stay inside intended module boundaries. Index staleness is a coverage gap, not evidence. NOT for static call/dependency graphs (use tools-codegraph), exact text discovery (use tools-code-search), or syntactic pattern search (use tools-ast-grep).

Assess coupling with the Balanced Coupling model (integration strength, distance, volatility). Use when judging whether coupling is balanced or risky, scoring the coupling_balance dimension, or deciding what to flag as structural risk. Highest risk is high strength + high distance + high volatility together. NOT generic "decouple everything" advice. NOT for assigning the score itself (use architecture-scorecard) or for executable checks (use methodology-architecture-fitness).

Design a modular architecture from requirements, intended architecture notes, or an approved redesign brief. Use when asked to create architecture docs, define module boundaries, integration contracts, test specifications, or a target architecture before implementation. Blends Balanced Coupling, architecture-fitness thinking, and evidence from existing code when present. NOT for auditing current implementation quality (use architecture-review) or sequencing an already-approved design (use architecture-plan).

Assign architecture scores against the fixed rubric. Use when scoring or re-scoring architecture dimensions, choosing a band, setting confidence, or checking that a score is defensible. Enforces band-matches-value, evidence-per-score, and low-confidence caps. NOT for gathering evidence (use architecture-review) or writing plans (use architecture-plan).

Treat architecture intent as executable checks (fitness functions), not prose. Use when scoring the architecture_fitness dimension, recommending how to keep a boundary from re-rotting, or turning a finding into an enforceable check. Distinguishes checks that already run from checks you only recommend. NOT for judging coupling (use methodology-balanced-coupling) or assigning scores (use architecture-scorecard).

Design a modular architecture from requirements, intended architecture notes, or an approved redesign brief. Use when asked to create architecture docs, define module boundaries, integration contracts, test specifications, or a target architecture before implementation. Blends Balanced Coupling, architecture-fitness thinking, and evidence from existing code when present. NOT for auditing current implementation quality (use architecture-review) or sequencing an already-approved design (use architecture-plan).

Assign architecture scores against the fixed rubric. Use when scoring or re-scoring architecture dimensions, choosing a band, setting confidence, or checking that a score is defensible. Enforces band-matches-value, evidence-per-score, and low-confidence caps. NOT for gathering evidence (use architecture-review) or writing plans (use architecture-plan).

Gather deployment and runtime-architecture evidence from operational config: Helm, Kustomize, Kubernetes, Terraform/OpenTofu, Docker, GitHub Actions, policy tools, SBOM, and vulnerability scanners. Use when a target ships deploy units and you need runtime topology, deploy-time coupling, config drift, CI/CD, or supply-chain evidence for architecture review. NOT for application source graphs (use tools-codegraph or the language tool skills).

Gather TypeScript/JavaScript architecture evidence with dependency-cruiser, madge, knip, tsc, ESLint, and the package manager. Use when a TS/JS repo needs module graphs, workspace/package boundaries, import cycles, dependency direction, dead code, type errors, or boundary-rule violations for modularity and coupling review. NOT for Python (use tools-python), Go (use tools-go), exact text discovery (use tools-code-search), or generic structural patterns (use tools-ast-grep).

Gather structural-pattern architecture evidence with ast-grep syntax-tree queries. Use when checking module boundaries, layer violations, forbidden imports, direct DB/framework access, route declarations, exported surface area, or framework leaks across seams. Yields exact file:line evidence for modularity, coupling, and fragility claims. NOT for whole-graph dependency analysis (use tools-codegraph), exact text discovery (use tools-code-search), or semantic/type resolution (use tools-lsp-tree-sitter).

Produce and validate architecture-review report and plan artifacts: Markdown, YAML frontmatter, Mermaid diagrams, jq/yq checks, Graphviz/D2 graphs, links, spelling, and format. Use when writing or checking cited reports, system-map diagrams, score summaries, or refactoring plans. This is report-quality evidence, not architecture evidence. NOT for gathering findings (use tools-code-search, tools-codegraph, tools-ast-grep, tools-lsp-tree-sitter, language, and operational tool skills).

Gather local codebase evidence with fd, rg, git grep, git log, and targeted file reading. Use when starting an architecture review, building the system map, finding entrypoints, locating module boundaries, tracing exact text or config keys, or collecting file:line evidence for modularity, coupling, dependency, blast-radius, or fragility claims. Use before heavier AST, graph, LSP, language, or history tools. NOT for final architecture assessment (use architecture-review) or semantic/type resolution (use tools-lsp-tree-sitter or tools-codegraph).

Gather whole-repo dependency and semantic graph evidence with codegraph: definitions, references, call edges, cycles, hubs, fan-in/out, and blast radius. Use when assessing module boundaries, dependency direction, coupling, impact of change, or fragile graph shape at architecture-review scale. Index staleness is a coverage gap, not evidence. NOT for exact text discovery (use tools-code-search), single-pattern searches (use tools-ast-grep), or git-history change locality (use tools-gitnexus).

Gather Go architecture evidence with go list, go mod graph, goda, gopls, staticcheck, govulncheck, and go-callvis. Use when a Go module needs package graphs, import cycles, dependency direction, package-boundary checks, call/reference facts, dead code, vulnerabilities, or call graphs for modularity and coupling review. NOT for TS/JS (use tools-typescript), Python (use tools-python), exact text discovery (use tools-code-search), or generic structural patterns (use tools-ast-grep).

Gather resolved semantic evidence with LSP and syntax fallback with tree-sitter. Use when architecture findings need actual definitions, references, callers, implementations, diagnostics, or symbols rather than text matches — especially for coupling and boundary claims. Use tree-sitter when no language server is available or the question is purely syntactic. NOT for exact text discovery (use tools-code-search), repo-scale dependency graphs (use tools-codegraph), or git history (use tools-gitnexus).

Gather Python architecture evidence with import-linter, pydeps, pyright/basedpyright, ruff, deptry, pipdeptree, uv tree, radon/lizard, and vulture. Use when a Python repo needs import contracts, module graphs, layer-boundary checks, type state, complexity hotspots, dead code, or dependency health for modularity and coupling review. NOT for TS/JS (use tools-typescript), Go (use tools-go), exact text discovery (use tools-code-search), or generic structural patterns (use tools-ast-grep).