Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Search & research

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-specify

About 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-init instead to reverse-engineer from code
  • Minor updates: Use /architect-clarify for 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.md

    • core (default): Context, Functional, Information, Development, Deployment
    • all: All 7 views including Concurrency and Operational
    • Custom: comma-separated (e.g., concurrency,operational)
  • --adr-heuristic HEURISTIC: ADR generation strategy

    • surprising (default): Skip obvious ecosystem defaults
    • all: Document all decisions discussed
    • minimal: 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 TopicPrimary ViewpointImpact on Other Views
Architecture StyleFunctional (cornerstone)Shapes all other views
Database ChoiceInformationAffects Functional, Deployment
API StyleFunctionalAffects Information, Development
Auth MechanismFunctionalAffects all views (security perspective)
Deployment PlatformDeploymentAffects Development, Operational
Communication PatternFunctional, ConcurrencyAffects 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:

  1. System architecture style (monolith/microservices/serverless)
  2. Component responsibilities and boundaries
  3. Interface contracts between components
  4. Integration patterns

These decisions drive all subsequent architectural views.

Two-Level Architecture System

LevelLocationADR FileArchitecture Description
SystemMain 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 .adlc directory
  • 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.md and the adr.md index after ADR writes
  • When running from a subdirectory (e.g., a subproject directory), .adlc may be in the parent directory

Outline

Given the PRD input, execute this workflow:

  1. Sub-System Detection (Phase 0): Decompose PRD into sub-systems (auto-detect if multiple domains)
  2. Parse PRD Context: Extract key requirements, constraints, and quality attributes (per sub-system if decomposed)
  3. Load Governance: Check {REPO_ROOT}/.adlc/memory/constitution.md for architectural constraints
  4. Exploration Phase: Interactive discussion to surface trade-offs and options (per sub-system)
  5. Decision Phase: Document decisions as ADRs with full rationale (organized by sub-system)
  6. Output: Write ADRs to {REPO_ROOT}/.adlc/drafts/adr/ADR-{NNN}.md with sub-system organization

NOTE: This is an interactive command. You will engage the user in conversation before finalizing ADRs.

Ex

Read the complete source ↗