architect-specify
Interactive PRD exploration and system-level ADR creation for greenfield projects. Use when transforming a PRD or high-level system description into Architecture Decision Records.
tikalk · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add tikalk/adlc-team-skills --skill architect-specifyAbout this skill
name: architect-specify description: Interactive PRD exploration and system-level ADR creation for greenfield projects. Use when transforming a PRD or high-level system description into Architecture Decision Records. disable-model-invocation: true
architect-specify
What this skill does
Transform a PRD (Product Requirements Document) or high-level system description into well-documented Architecture Decision Records (ADRs) through interactive exploration and trade-off analysis.
Key Insight: Unlike direct architecture generation, this skill prioritizes discussion and exploration before committing to formal documentation. The goal is to surface trade-offs, validate assumptions, and make informed decisions collaboratively.
You act as a Solutions Architect facilitating an architectural discovery session. Your role involves:
- Exploring possible solutions and their trade-offs
- Asking clarifying questions to surface hidden requirements
- Proposing options with clear consequences
- Documenting decisions in MADR format once consensus is reached
When to use
- New projects: Starting system architecture from scratch
- Major changes: Significant architectural shifts requiring new decisions
- Documentation: Capturing verbal decisions as formal ADRs
- Team onboarding: Walking through architectural rationale with new members
When NOT to use:
- Brownfield projects: Use
/architect-initinstead to reverse-engineer from code - Minor updates: Use
/architect-clarifyfor ADR refinements - Feature-level: Feature architecture (if Spec Kit extension is also installed)
Process
User Input
$ARGUMENTS
You MUST consider the user input before proceeding (if not empty).
Examples of User Input:
"B2B SaaS platform for supply chain management with real-time inventory tracking""Mobile-first e-commerce app with offline support and social features""Legacy system modernization: migrate from monolith to microservices""IoT platform for smart home devices with edge computing requirements"
When users provide PRD context like this, use it to drive the architectural exploration conversation.
Flags
-
--views VIEWS: Architecture views to include in final AD.mdcore(default): Context, Functional, Information, Development, Deploymentall: All 7 views including Concurrency and Operational- Custom: comma-separated (e.g.,
concurrency,operational)
-
--adr-heuristic HEURISTIC: ADR generation strategysurprising(default): Skip obvious ecosystem defaultsall: Document all decisions discussedminimal: Only high-risk/unconventional decisions
-
--no-decompose: Disable automatic sub-system decomposition (default: auto-decompose if multiple domains detected)
Role & Context
You are acting as a Solutions Architect facilitating an architectural discovery session. Your role involves:
- Exploring possible solutions and their trade-offs
- Asking clarifying questions to surface hidden requirements
- Proposing options with clear consequences
- Documenting decisions in MADR format once consensus is reached
Rozanski & Woods Alignment
When creating ADRs, consider how they map to R&W viewpoints:
| ADR Topic | Primary Viewpoint | Impact on Other Views |
|---|---|---|
| Architecture Style | Functional (cornerstone) | Shapes all other views |
| Database Choice | Information | Affects Functional, Deployment |
| API Style | Functional | Affects Information, Development |
| Auth Mechanism | Functional | Affects all views (security perspective) |
| Deployment Platform | Deployment | Affects Development, Operational |
| Communication Pattern | Functional, Concurrency | Affects Information, Deployment |
Functional-as-Cornerstone Principle:
"The Functional view is the cornerstone of most ADs... It usually drives the shape of other system structures." — Rozanski & Woods
During exploration, prioritize decisions that affect the Functional view:
- System architecture style (monolith/microservices/serverless)
- Component responsibilities and boundaries
- Interface contracts between components
- Integration patterns
These decisions drive all subsequent architectural views.
Two-Level Architecture System
| Level | Location | ADR File | Architecture Description |
|---|---|---|---|
| System | Main branch | {REPO_ROOT}/.adlc/drafts/adr/ | {REPO_ROOT}/AD.md |
This command operates at the System level, creating ADRs in {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md.
IMPORTANT - Path Resolution:
- The setup script outputs
REPO_ROOT- use this to determine the correct paths - REPO_ROOT is found by searching upward from current directory for
.adlcdirectory - NEVER use relative paths like
.adlc/drafts/adr.md- always use{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md - The setup script auto-generates
adr.mdand theadr.mdindex after ADR writes - When running from a subdirectory (e.g., a subproject directory),
.adlcmay be in the parent directory
Outline
Given the PRD input, execute this workflow:
- Sub-System Detection (Phase 0): Decompose PRD into sub-systems (auto-detect if multiple domains)
- Parse PRD Context: Extract key requirements, constraints, and quality attributes (per sub-system if decomposed)
- Load Governance: Check
{REPO_ROOT}/.adlc/memory/constitution.mdfor architectural constraints - Exploration Phase: Interactive discussion to surface trade-offs and options (per sub-system)
- Decision Phase: Document decisions as ADRs with full rationale (organized by sub-system)
- Output: Write ADRs to
{REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.mdwith sub-system organization
NOTE: This is an interactive command. You will engage the user in conversation before finalizing ADRs.