---
module: paradigm-selection
category: decision-support
dependencies:
- archetypes:architecture-paradigms
estimated_tokens: 700
---

# 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)

| Workload                  | Paradigm                     |
|---------------------------|------------------------------|
| Real-time / Streaming     | Event-Driven and Pipeline      |
| Bursty / Cloud-Native     | Serverless                   |
| Extensible Platform       | Microkernel                  |
| Data Processing           | Pipeline and Event-Driven      |
| Legacy Integration        | Hexagonal                    |
| High-Throughput Stateful  | Space-Based                  |

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

---
module: research-flow
category: data-gathering
dependencies: []
estimated_tokens: 600
---

# 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`:

```bash
# 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.

---
module: scaffold-generation
category: project-scaffolding
dependencies: []
estimated_tokens: 800
---

# 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:

```markdown
# 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`).

---
module: script-integration
category: tooling
dependencies: []
estimated_tokens: 500
---

# 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

```bash
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

```bash
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

```bash
# 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

```python
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"))
```