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)

1. An ADR explaining why this paradigm was chosen
2. Links to the relevant paradigm skill for ongoing

implementation guidance

1. 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

Exit Criteria

• [ ] All four TodoWrite items are checked off:

arch-init:research-completed, arch-init:paradigm-selected,

arch-init:templates-customized, arch-init:decision-recorded.

• [ ] An ADR file exists in the initialized project explaining why the selected paradigm was

chosen, referencing evidence from the Step 2 research synthesis.

• [ ] The project directory structure matches the layout prescribed by the chosen

archetypes:architecture-paradigm-* skill (verified by listing the created directories).

• [ ] If the paradigm is undecided after research, the skill surfaces the top two candidates

with trade-offs and waits for explicit user selection rather than defaulting silently.