architecture
| Field | Value |
|---|---|
| Type | Skill |
| Source | ~/.copilot/skills/architecture/SKILL.md |
| Description | Front door for system architecture, tech evaluation, monorepo layout, legacy discovery, tech-debt scoring, and fullstack scaffolding. Trigger on “design system architecture”, “ADR”, “monolith vs microservices”, “choose a database”, “dependency analysis”, “compare frameworks”, “TCO analysis”, “should we adopt X”, “build vs buy”, “monorepo”, “turborepo”, “nx”, “pnpm workspace”, “package boundaries”, “explain this repo”, “onboard me on this codebase”, “AS400”, “COBOL”, “CICS”, “mainframe”, “legacy modernization”, “find tech debt”, “prioritize refactoring”, “code quality audit”, “debt dashboard”, “scaffold a new project”, “what stack should I use”, or “build me a fullstack X”. Does NOT do org strategy (exec), React/CSS (frontend), schema/query tuning (database), CI/CD or Kubernetes (platform), or incident response. Output: an ADR, comparison report, workspace layout, discovery doc, scored debt inventory, or scaffolded project — per the routing table below. |
Bundled Pages
| Group | Name | Source |
|---|---|---|
| Assets | Expected_output_comparison | ~/.copilot/skills/architecture/assets/expected_output_comparison.json |
| Assets | Historical_debt_2024 01 15 | ~/.copilot/skills/architecture/assets/historical_debt_2024-01-15.json |
| Assets | Historical_debt_2024 02 01 | ~/.copilot/skills/architecture/assets/historical_debt_2024-02-01.json |
| Assets | Sample_debt_inventory | ~/.copilot/skills/architecture/assets/sample_debt_inventory.json |
| Assets | Sample_input_structured | ~/.copilot/skills/architecture/assets/sample_input_structured.json |
| Assets | Sample_input_tco | ~/.copilot/skills/architecture/assets/sample_input_tco.json |
| Assets | Sample_input_text | ~/.copilot/skills/architecture/assets/sample_input_text.json |
| Assets Sample_codebase Src | Frontend | ~/.copilot/skills/architecture/assets/sample_codebase/src/frontend.js |
| Assets Sample_codebase Src | Payment_processor | ~/.copilot/skills/architecture/assets/sample_codebase/src/payment_processor.py |
| Assets Sample_codebase Src | User_service | ~/.copilot/skills/architecture/assets/sample_codebase/src/user_service.py |
| Expected_outputs | Sample_dashboard_output | ~/.copilot/skills/architecture/expected_outputs/sample_dashboard_output.json |
| Expected_outputs | Sample_prioritization_output | ~/.copilot/skills/architecture/expected_outputs/sample_prioritization_output.json |
| Expected_outputs | Sample_scan_output | ~/.copilot/skills/architecture/expected_outputs/sample_scan_output.json |
| References | ADR Authoring — Architecture Patterns, Workflows, and Decision Guides | ~/.copilot/skills/architecture/references/adr-authoring.md |
| References | Fullstack Project Scaffolding and Code-Quality Audits | ~/.copilot/skills/architecture/references/fullstack-scaffolding.md |
| References | Legacy & Codebase Discovery — Archaeology Before Migration | ~/.copilot/skills/architecture/references/discovery.md |
| References | Monorepo Layout — pnpm Workspaces + Turborepo/Nx | ~/.copilot/skills/architecture/references/monorepo.md |
| References | Tech Debt — Classification, Prioritization, and Communication | ~/.copilot/skills/architecture/references/tech-debt.md |
| References | Tech Stack Evaluation — Metrics, Workflows, and Examples | ~/.copilot/skills/architecture/references/tech-stack-evaluation.md |
| References Discovery | Business Rule Mining | ~/.copilot/skills/architecture/references/discovery/business-rule-mining.md |
| References Discovery | CICS Online Transaction Decoder | ~/.copilot/skills/architecture/references/discovery/cics-online.md |
| References Discovery | Data Model Extraction | ~/.copilot/skills/architecture/references/discovery/data-model-extraction.md |
| References Discovery | Dependency Mapping | ~/.copilot/skills/architecture/references/discovery/dependency-mapping.md |
| References Discovery | IBM i / AS400 Decoder | ~/.copilot/skills/architecture/references/discovery/ibm-i-as400.md |
| References Discovery | Legacy Diagram Patterns (Mermaid) | ~/.copilot/skills/architecture/references/discovery/mermaid-legacy-patterns.md |
| References Discovery | Legacy Terminology Glossary | ~/.copilot/skills/architecture/references/discovery/glossary.md |
| References Discovery | Mainframe COBOL Decoder | ~/.copilot/skills/architecture/references/discovery/mainframe-cobol.md |
| References Discovery | Modern-Legacy Platforms Decoder | ~/.copilot/skills/architecture/references/discovery/modern-legacy-platforms.md |
| References Discovery | Modernization Strategy | ~/.copilot/skills/architecture/references/discovery/modernization-strategy.md |
| References Discovery | Onboarding Document Template (docs/onboard.md) | ~/.copilot/skills/architecture/references/discovery/onboard-template.md |
| References Discovery | Sample corpora for legacy-system discovery practice | ~/.copilot/skills/architecture/references/discovery/sample-corpora.md |
| References Discovery | The 7-Phase Discovery Playbook | ~/.copilot/skills/architecture/references/discovery/discovery-playbook.md |
| Resources | Lints | ~/.copilot/skills/architecture/lints.toml |
| Scripts | Architecture_diagram_generator | ~/.copilot/skills/architecture/scripts/architecture_diagram_generator.py |
| Scripts | Code_quality_analyzer | ~/.copilot/skills/architecture/scripts/code_quality_analyzer.py |
| Scripts | Debt_dashboard | ~/.copilot/skills/architecture/scripts/debt_dashboard.py |
| Scripts | Debt_prioritizer | ~/.copilot/skills/architecture/scripts/debt_prioritizer.py |
| Scripts | Debt_scanner | ~/.copilot/skills/architecture/scripts/debt_scanner.py |
| Scripts | Dependency_analyzer | ~/.copilot/skills/architecture/scripts/dependency_analyzer.py |
| Scripts | Ecosystem_analyzer | ~/.copilot/skills/architecture/scripts/ecosystem_analyzer.py |
| Scripts | Format_detector | ~/.copilot/skills/architecture/scripts/format_detector.py |
| Scripts | Inventory | ~/.copilot/skills/architecture/scripts/inventory.py |
| Scripts | Lint | ~/.copilot/skills/architecture/scripts/lint.py |
| Scripts | Lint_adr | ~/.copilot/skills/architecture/scripts/lint_adr.py |
| Scripts | Lint_adr | ~/.copilot/skills/architecture/scripts/lint_adr.sh |
| Scripts | Lint_comparison | ~/.copilot/skills/architecture/scripts/lint_comparison.sh |
| Scripts | Lint_workspace_config | ~/.copilot/skills/architecture/scripts/lint_workspace_config.py |
| Scripts | Lint_workspace_config | ~/.copilot/skills/architecture/scripts/lint_workspace_config.sh |
| Scripts | Migration_analyzer | ~/.copilot/skills/architecture/scripts/migration_analyzer.py |
| Scripts | Project_architect | ~/.copilot/skills/architecture/scripts/project_architect.py |
| Scripts | Project_scaffolder | ~/.copilot/skills/architecture/scripts/project_scaffolder.py |
| Scripts | Report_generator | ~/.copilot/skills/architecture/scripts/report_generator.py |
| Scripts | Security_assessor | ~/.copilot/skills/architecture/scripts/security_assessor.py |
| Scripts | Stack_comparator | ~/.copilot/skills/architecture/scripts/stack_comparator.py |
| Scripts | Tco_calculator | ~/.copilot/skills/architecture/scripts/tco_calculator.py |
Source Content
Architecture
| Domain | System design, tech evaluation, repo shape, legacy archaeology, debt, scaffolding |
| Role | Architecture front door — decisions, comparisons, discovery, and structure |
| Output | ADRs, comparison reports, workspace configs, discovery docs, debt inventories, project trees |
This skill absorbed senior-architect, tech-stack-evaluator, monorepo-architect, discovery, tech-debt-tracker, and senior-fullstack. senior-fullstack dissolved into this skill: its scaffolding and code-quality-audit material moved to references/fullstack-scaffolding.md; its frontend-specific linter (check_frontend.sh) already lives in the frontend skill and was not duplicated here.
Route by task
| You’re… | Read | Gate with |
|---|---|---|
| Making an ADR-shaped system design decision | references/adr-authoring.md | scripts/lint_adr.sh |
| Comparing frameworks, databases, clouds, or vendors with TCO | references/tech-stack-evaluation.md | scripts/lint_comparison.sh |
| Laying out a pnpm-workspaces/Turborepo (or Nx) monorepo | references/monorepo.md | scripts/lint_workspace_config.sh |
| Understanding a legacy or unfamiliar system before changing it | references/discovery.md + references/discovery/ | python3 ~/.copilot/skills/technical-writing/scripts/lint.py docs/onboard.md |
| Finding, scoring, or sequencing tech-debt paydown | references/tech-debt.md | scripts/debt_scanner.py then scripts/debt_prioritizer.py |
| Scaffolding a fullstack project or auditing code quality | references/fullstack-scaffolding.md | scripts/project_scaffolder.py / scripts/code_quality_analyzer.py |
| Drawing an architecture diagram from project structure | references/adr-authoring.md (Part 1) | scripts/architecture_diagram_generator.py |
| Analyzing dependency coupling or circular imports | references/adr-authoring.md (Part 1) | scripts/dependency_analyzer.py |
References load lazily — a quick ADR lint never pays for the discovery playbook, and a monorepo config check never pays for the debt taxonomy.
House rules
- ADR-shaped, always. Context, 2–4 real options (including a “do less” option), decision, consequences — never just a recommendation. Cite the
adrskill’s template and lifecycle for the canonical format. - Trade-offs are explicit and sourced. Comparisons cite real benchmarks, GitHub data, and pricing — no vibes-based scoring. TCO includes hidden costs: hiring, training, integration, migration, opportunity cost.
- Conway’s Law is checked early. Team shape and architecture shape must fit; if they don’t, change one of them before shipping the ADR.
- Reversibility decides rigor. One-way doors get more scrutiny than two-way doors; name which kind of door this is.
- Boundaries enforced in lint, not docs. Monorepo package boundaries, layer violations, and coupling rules live in a linter/config, not a wiki page someone will stop reading.
- Discovery before migration, always. For any legacy or unfamiliar system, inventory → data model → business rules → dependencies → tests → doc → disposition, in that order. Never score a disposition before the first four artifacts exist.
- Debt is scored, not moralized. Every debt item carries impact, effort, and cost-of-delay; sequence paydown around real upcoming feature work, never a standalone freeze.
- Boundaries named before code. Fullstack scaffolds draw front/API/data/async seams before any file is generated, and every JS/TS scaffold is TypeScript-strict with Zod at every boundary.
- No invented capacity or APIs. Numbers cite sources or are flagged as estimates; every code snippet runs on the stated version.
Use me for
- ADRs for high-impact technical decisions, architecture pattern selection, dependency/coupling analysis.
- Framework, database, cloud, or vendor comparisons with weighted criteria and multi-year TCO.
- Monorepo layout, package boundaries, change-based CI, and library versioning.
- Reverse-engineering a legacy or unfamiliar codebase — modern or mainframe/IBM i/CICS — into an onboarding doc and a modernization disposition.
- Finding, classifying, and sequencing technical debt paydown.
- Scaffolding a new fullstack project or auditing an existing one for quality.
Don’t use me for
- React/CSS/component implementation, Storybook, TanStack, Zod schemas →
frontend. - Schema design or Postgres query tuning →
database. - CI/CD pipelines, Kubernetes, Helm, observability →
platform. - Org design, hiring strategy, board-level capital allocation →
exec. - AppSec review or FedRAMP control mapping →
security. - PRDs, user stories, sprint prioritization →
product. - Live incident response →
platform(on-call/incident material). - Reviewing a specific PR line-by-line →
quality.
How I work
- Frame the problem. What’s changing, what’s the time horizon, what’s reversible vs. one-way?
- Route using the table above to the right reference and script.
- Generate real options, not a single foregone recommendation — 2–4 for an ADR, weighted criteria for a comparison, a scored table per subsystem for a discovery disposition.
- Show the work. Cite sources, line ranges, or benchmark URLs; mark confidence where it’s inferred.
- Validate with the script named in the routing table before handing anything over.
- Name the handoff. State which deeper skill (
frontend,backend,database,platform) picks up the next layer.
Self-rubric (run before I respond)
- ADR-shaped where a decision is being made — options, trade-offs, consequences, not just a pick.
- Sources cited for every comparison claim; no invented benchmarks or capacity numbers.
- Conway’s Law and reversibility both considered for architecture decisions.
- Discovery artifacts (inventory, data model, rules, dependencies) exist before any disposition is scored.
- Debt items carry impact, effort, and cost-of-delay — never a bare list.
- Scaffolds draw boundaries before generating code, and are TypeScript-strict with Zod at every boundary.
- The right deeper skill is named for anything outside this skill’s scope.
- Validation script for the task at hand exits 0.
References
references/adr-authoring.md— architecture pattern catalog, system-design workflows, and the tech decision guide (database/cache/queue/auth/frontend/cloud/API matrices).references/tech-stack-evaluation.md— scoring formulas, TCO math, ecosystem-health metrics, and worked comparison/TCO/migration/security examples.references/monorepo.md— pnpm-workspaces + Turborepo/Nx layout, boundary enforcement, change-based CI, versioning.references/discovery.md— the 7-phase discovery playbook summary and the routing table intoreferences/discovery/.references/discovery/discovery-playbook.md— the full 7-phase method: inputs, outputs, AI prompts, pitfalls, definition-of-done per phase.references/discovery/ibm-i-as400.md— IBM i/AS400 decoder (RPG, DDS, CL, DB2 for i).references/discovery/mainframe-cobol.md— COBOL/JCL/VSAM decoder.references/discovery/cics-online.md— CICS pseudo-conversational transaction decoder.references/discovery/modern-legacy-platforms.md— .NET Web Forms, Java EE, VB6, Oracle Forms, classic PHP field guide.references/discovery/data-model-extraction.md— decode-gotcha catalog (packed decimal, EBCDIC, REDEFINES, OCCURS, dates) and ERD/field-dictionary method.references/discovery/business-rule-mining.md— where rules hide per platform, the extraction method, the rule-catalog template.references/discovery/dependency-mapping.md— call graph, CRUD matrix, batch-job DAG, integration inventory.references/discovery/modernization-strategy.md— the decision flowchart, strategy catalog (rehost/replatform/refactor/encapsulate/strangler/rebuild/replace/retain), scoring rubric, anti-patterns.references/discovery/mermaid-legacy-patterns.md— canonical diagram skeletons (ERD, call graph, batch DAG, state lifecycle, user journey, system context).references/discovery/onboard-template.md— the fixed 14-section structure ofdocs/onboard.md.references/discovery/glossary.md— plain-English decoder for AS400/mainframe/COBOL/CICS terms.references/discovery/sample-corpora.md— real public repos to practice discovery on.references/tech-debt.md— debt classification taxonomy, prioritization frameworks (CoD/WSJF/RICE/quadrants), stakeholder communication templates.references/fullstack-scaffolding.md— stack decision matrix, scaffolding workflow, fullstack architecture patterns, dev workflows, and tech-stack comparisons.scripts/lint_adr.sh/scripts/lint_adr.py— ADR skeleton and unresolved-marker checker.scripts/architecture_diagram_generator.py— generates Mermaid/PlantUML/ASCII diagrams from project structure.scripts/dependency_analyzer.py— dependency tree, circular-dependency detection, coupling score.scripts/project_architect.py— detects architectural patterns and layer violations in an existing codebase.scripts/lint_comparison.sh— validates a tech comparison report’s consistency and named trade-off.scripts/stack_comparator.py/scripts/tco_calculator.py/scripts/ecosystem_analyzer.py/scripts/security_assessor.py/scripts/migration_analyzer.py/scripts/format_detector.py/scripts/report_generator.py— tech-stack evaluation tools.scripts/lint_workspace_config.sh/scripts/lint_workspace_config.py— validates monorepo workspace config JSON and glob resolution.scripts/inventory.py— deterministic legacy-artifact inventory (phase 1 of discovery).scripts/debt_scanner.py/scripts/debt_prioritizer.py/scripts/debt_dashboard.py— tech-debt scan, prioritize, and trend-dashboard pipeline.scripts/project_scaffolder.py— scaffolds a fullstack project tree.scripts/code_quality_analyzer.py— scores an existing codebase’s security/complexity/deps/coverage/docs.assets/— sample fixtures for the tech-stack-evaluation and tech-debt scripts (sample_input_tco.json,sample_debt_inventory.json,sample_codebase/,historical_debt_*.json).expected_outputs/— expected shapes for the tech-debt scripts (sample_scan_output.json,sample_dashboard_output.json,sample_prioritization_output.json).