Architecture Aware Init

Architecture-Aware Project Initialization

Overview

Project initialization that combines online research, archetype selection, template customization, and decision documentation into one workflow. Use this skill when the architecture is undecided and the choice deserves justification.

When to Use This Skill

• Starting a new project and unsure which architecture fits best
• Wanting modern, industry-standard architecture choices
• Needing justification for architectural decisions
• Wanting templates customized to the chosen paradigm

Use instead of project-init when architecture is undecided. Use before project-specification to establish the architectural foundation.

Required TodoWrite Items

1. arch-init:research-completed: Online research completed 2. arch-init:paradigm-selected: Architecture paradigm chosen 3. arch-init:templates-customized: Templates adapted to paradigm 4. arch-init:decision-recorded: ADR created

5-Step Workflow

Steps 1-2: Gather context, research best practices

Load modules/research-flow.md for the full project-context questionnaire and the three-tier search strategy. Output: a synthesis brief that feeds Step 3.

Step 3: Select the architecture paradigm

Load modules/paradigm-selection.md for the decision matrix (team size by domain complexity) and the special-case overrides (streaming, serverless, microkernel, etc.). Two routes:

• Use the archetypes:architecture-paradigms skill for guided

exploration.

• Use the matrix directly for a fast recommendation.

Step 4-5: Customize templates and record the decision

Load modules/scaffold-generation.md for the paradigm-specific directory layouts (Functional Core / Hexagonal / Microservices shown; others delegated to the corresponding archetypes:architecture-paradigm-{name} skill) and the ADR template.

Output: Initialization Package

After completing the workflow, the project has:

1. A directory structure matched to the chosen architecture 2. Configuration that reflects the paradigm (test layout, tooling, dependency hints) 3. An ADR explaining why this paradigm was chosen 4. Links to the relevant paradigm skill for ongoing implementation guidance 5. References to similar real-world projects from Step 2

Script Integration

The interactive workflow above is the default. For automation, load modules/script-integration.md for the three Python helpers under plugins/attune/scripts/ (architecture researcher, template customizer, full interactive flow) and library-style import examples.

Integration with Existing Commands

This skill enhances /attune:project-init by adding an architecture-selection phase before scaffolding:

# Standard initialization (no architecture decision)
/attune:project-init --lang python --name my-project

# Architecture-aware initialization
/attune:brainstorm                  # Explore project needs
Skill(architecture-aware-init)      # Select architecture
/attune:project-init --arch <paradigm> --name my-project

Example Session

User: "I'm creating a Python web API for a fintech application. Team of 8 developers, complex business rules, need high security and audit trails."

• Step 1 context: Web API, highly complex domain, 5-15

engineers, security and auditability requirements.

• Step 2 research: queries for fintech API patterns, audit-trail

architecture, CQRS+ES Python examples.

• Step 3 selection: research plus decision matrix yields CQRS +

Event Sourcing.

• Step 4 templates: command-handler module, query-handler

module, event store, aggregate patterns, projection handlers.

• Step 5 ADR: documents why CQRS/ES fits (auditability, complex

rules, regulatory compliance).

Result: project initialized with paradigm-appropriate structure and clear decision rationale.

Related Skills

• Skill(archetypes:architecture-paradigms): paradigm catalog
• Skill(archetypes:architecture-paradigm-*): per-paradigm

implementation guidance

• Skill(attune:project-brainstorming): ideation before

architecture

• Skill(attune:project-specification): requirements after

the paradigm is chosen

See Also

• /attune:project-init: basic project initialization
• /attune:blueprint: architecture planning after paradigm

selection

• plugins/archetypes/README.md: full paradigm reference

Paradigm Selection

Step 3 of the architecture-aware-init workflow: pick the architecture paradigm using either the archetypes plugin or the decision matrix below.

Option A: Use the archetypes plugin

Invoke the catalog directly:

Skill(architecture-paradigms)

This guides through the 14 paradigms with comparison tables and trade-off discussion. Use this when the user wants to explore options or learn the paradigm space.

Available paradigms:

• Layered Architecture
• Functional Core, Imperative Shell
• Hexagonal (Ports and Adapters)
• Modular Monolith
• Microservices
• Service-Based Architecture
• Event-Driven Architecture
• CQRS + Event Sourcing
• Serverless
• Space-Based Architecture
• Pipeline Architecture
• Microkernel Architecture
• Client-Server Architecture

Option B: Decision matrix

Use this when the user has a clear context and wants a fast recommendation.

+---------------------+---------+---------+----------+-------------+
| Project Context     | Simple  | Moderate| Complex  | Highly      |
|                     | Domain  | Domain  | Domain   | Complex     |
+---------------------+---------+---------+----------+-------------+
| < 5 engineers       | Layered | Layered | Hexagonal| Functional  |
|                     |         | Hexag.  | Function.| Core        |
+---------------------+---------+---------+----------+-------------+
| 5-15 engineers      | Layered | Modular | Modular  | Hexagonal   |
|                     |         | Monolith| Monolith | + FC,IS     |
+---------------------+---------+---------+----------+-------------+
| 15-50 engineers     | Modular | Micro-  | Micro-   | CQRS/ES     |
|                     | Monolith| services| services | + Event     |
+---------------------+---------+---------+----------+-------------+
| 50+ engineers       | Micro-  | Micro-  | Event-   | Microkernel |
|                     | services| services| Driven   | or Space-   |
|                     |         | + Event |          | Based       |
+---------------------+---------+---------+----------+-------------+

Special cases (override the matrix)

Output of Step 3

Mark arch-init:paradigm-selected only after both:

1. The paradigm name is recorded. 2. The reasoning is captured (which row of the matrix or which special-case rule applied, and why).

The reasoning feeds the ADR generated in Step 5.

Architecture Research Flow

Steps 1-2 of the architecture-aware-init workflow: gather project context, then research current best practices online.

Step 1: Gather Project Context

Ask the user for the following information before any research:

Project Type

• Web API, CLI tool, data pipeline, desktop app, library, mobile,

embedded, etc.

Domain Complexity

• Simple (CRUD only)
• Moderate (some business logic)
• Complex (many rules, workflows)
• Highly Complex (domain-specific language needed)

Team Context

• Team size: < 5 | 5-15 | 15-50 | 50+
• Experience: Junior | Mixed | Senior | Expert
• Distribution: Co-located | Remote | Distributed

Non-Functional Requirements

• Scalability needs (users, requests/sec, data volume)
• Performance requirements
• Security and compliance needs
• Integration points (external systems, databases, APIs)

Timeline and Constraints

• Time to market: Rapid | Normal | Not urgent
• Budget constraints
• Technology constraints (must-use or must-avoid)

Mark arch-init:research-completed only after the answers are captured. Skipping context-gathering is the most common cause of a mismatched paradigm choice in Step 3.

Step 2: Research Best Practices

Run three search tiers using WebSearch:

# Tier 1: project-type level
WebSearch("[project type] architecture best practices 2026")

# Tier 2: language-specific
WebSearch("[language] [project type] architecture patterns 2026")

# Tier 3: framework-specific
WebSearch("[framework] architecture patterns [project type]")

Focus the synthesis on five questions:

1. What are practitioners actually recommending right now? 2. Are any new patterns gaining traction in this space? 3. Which practices are being actively discouraged (anti-patterns)? 4. Which patterns work best with the chosen stack? 5. Are there real-world case studies of similar projects?

Synthesis Output

Produce a short brief with:

• Recommended architecture(s) for this project type
• Key trade-offs to consider
• Red flags or anti-patterns to avoid
• Technology-specific considerations

Hand the brief into Step 3 (paradigm selection). The decision matrix in modules/paradigm-selection.md consumes this brief directly.

Scaffold Generation

Steps 4-5 of the architecture-aware-init workflow: customize project templates to the chosen paradigm, then record the decision in an ADR.

Step 4: Customize Templates

Adaptation strategy:

1. Load base templates for the chosen language (Python, Rust, TypeScript, etc.). 2. Apply paradigm-specific modifications. 3. Generate configuration that reflects the architectural choices (test layout, dependency hints, lint targets). 4. Create an in-repo doc explaining the architecture for future contributors.

Example: Functional Core, Imperative Shell

src/
├── core/                    # Pure business logic
│   ├── domain.py            # Domain models
│   ├── operations.py        # Pure functions
│   └── commands.py          # Command objects
└── adapters/                # Side effects
    ├── database.py          # DB operations
    ├── api.py               # HTTP operations
    └── filesystem.py        # File operations

Example: Hexagonal Architecture

src/
├── domain/                  # Business logic (no framework deps)
│   ├── models.py
│   ├── services.py
│   └── ports/               # Interfaces
│       ├── input.py         # Use cases
│       └── output.py        # Repository interfaces
└── infrastructure/          # Framework-specific code
    ├── persistence/         # Repositories
    ├── web/                 # Controllers
    └── messaging/           # Event handlers

Example: Microservices

project/
├── services/
│   ├── service-a/           # Independent service
│   │   ├── src/
│   │   ├── tests/
│   │   ├── Dockerfile
│   │   └── pyproject.toml
│   └── service-b/           # Independent service
│       ├── src/
│       ├── tests/
│       ├── Dockerfile
│       └── pyproject.toml
├── api-gateway/
├── shared/
│   └── events/
└── docker-compose.yml

For paradigms not shown, consult the corresponding archetypes:architecture-paradigm-{name} skill for the canonical template.

Mark arch-init:templates-customized once the directory layout matches the paradigm and the documentation is in place.

Step 5: Architecture Decision Record

Generate an ADR using this template:

# Architecture Decision Record: [Paradigm Name]

## Date
[Current date]

## Status
Accepted | Proposed | Deprecated | Superseded by [link]

## Context
[Project type, team size, domain complexity, key requirements]

## Decision
[Chosen architecture paradigm]

## Rationale

### Research Findings
[Summarize the brief produced in Step 2]

### Key Considerations
- Team Fit: [why this matches team size and experience]
- Domain Fit: [why this matches problem complexity]
- Technology Fit: [why this works with the chosen stack]
- Scalability: [how this addresses scaling needs]

### Alternatives Considered
1. [Alternative 1]: rejected because [reason]
2. [Alternative 2]: rejected because [reason]

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1] with mitigation: [strategy]
- [Trade-off 2] with mitigation: [strategy]

## Implementation
- Templates: [which templates were customized]
- Key Patterns: [patterns to follow]
- Anti-Patterns: [what to avoid]
- Resources: [links to paradigm skill, examples, references]

## References
- [Paradigm skill link]
- [Research sources from Step 2]
- [Example projects]

Mark arch-init:decision-recorded once the ADR is committed in the repo (typically docs/adr/0001-architecture-choice.md).

Script Integration

The skill is interactive by default but ships with three Python scripts under plugins/attune/scripts/ for automation and reuse.

Architecture Research Script

uv run python plugins/attune/scripts/architecture_researcher.py \
  --project-type web-api \
  --domain-complexity complex \
  --team-size 5-15 \
  --language python \
  --output-json

Returns a recommendation with:

• Primary paradigm and rationale
• Trade-offs and mitigations
• Alternative paradigms considered
• Confidence level

Template Customizer Script

uv run python plugins/attune/scripts/template_customizer.py \
  --paradigm cqrs-es \
  --language python \
  --project-name my-project \
  --output-dir ./my-project

Creates the paradigm-appropriate directory structure (e.g., commands/, queries/, events/ for CQRS).

Full Interactive Flow

# Interactive
uv run python plugins/attune/scripts/attune_arch_init.py \
  --name my-project \
  --lang python

# Non-interactive with explicit architecture
uv run python plugins/attune/scripts/attune_arch_init.py \
  --name my-project \
  --lang python \
  --arch hexagonal \
  --accept-recommendation

Library Usage from Claude Code

from architecture_researcher import ArchitectureResearcher, ProjectContext
from template_customizer import TemplateCustomizer
from pathlib import Path

context = ProjectContext(
    project_type="web-api",
    domain_complexity="complex",
    team_size="5-15",
    language="python",
)
researcher = ArchitectureResearcher(context)
recommendation = researcher.recommend()

customizer = TemplateCustomizer(
    paradigm=recommendation.primary,
    language="python",
    project_name="my-project",
)
customizer.apply_structure(Path("./my-project"))