OpenSkillIndex← back to search
claude-codeproductivity

Claude-night-market architecture-aware-init

Architecture-aware project initialization combining online research with archetype selection.

install
source · Clone the upstream repo
git clone https://github.com/athola/claude-night-market
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/athola/claude-night-market "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/attune/skills/architecture-aware-init" ~/.claude/skills/athola-claude-night-market-architecture-aware-init && rm -rf "$T"
manifest: plugins/attune/skills/architecture-aware-init/SKILL.md
tags
#architecture#research#template#decision-making#project-setup
source content

Table of Contents

Architecture-Aware Project Initialization

Overview

Enhanced project initialization that combines:

  • Deep online research into current best practices for your project type
  • Archetype selection from the 14 paradigms in the archetypes plugin
  • Template customization based on chosen architecture
  • Decision documentation for future reference

When to Use This Skill

Use this skill when:

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

Use instead of 

project-init
when architecture is undecided. Use before 
project-specification
to establish 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

Step 1: Gather Project Context

Essential Information (ask user):

1. **Project Type**: What are you building?
   - Web API, CLI tool, data pipeline, desktop app, library, etc.

2. **Domain Complexity**: How complex are the business rules?
   - Simple (CRUD), Moderate (some business logic), Complex (many rules),
     Highly Complex (domain-specific language needed)

3. **Team Context**: Who will build and maintain this?
   - Team size: < 5 | 5-15 | 15-50 | 50+
   - Experience: Junior | Mixed | Senior | Expert
   - Distribution: Co-located | Remote | Distributed

4. **Non-Functional Requirements**:
   - Scalability needs (users, requests/sec, data volume)
   - Performance requirements
   - Security/compliance needs
   - Integration points (external systems, databases, APIs)

5. **Timeline & Constraints**:
   - Time to market: Rapid | Normal | Not urgent
   - Budget constraints
   - Technology constraints (must-use or must-avoid technologies)

Verification: Run the command with 

--help
flag to verify availability.

Step 2: Research Best Practices (
arch-init:research-completed
)

Online Research Queries (use WebSearch):

For the project type, search for:

# Primary: Architecture patterns for [project type] [year]
WebSearch("[project type] architecture best practices 2026")

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

# Tertiary: Framework-specific guidance
WebSearch("[framework] architecture patterns [project type]")

Verification: Run the command with 

--help
flag to verify availability.

Research Focus Areas:

  1. Current Industry Standards: What are practitioners recommending in 2026?
  2. Emerging Patterns: Any new architectural approaches gaining traction?
  3. Anti-Patterns: What practices are being actively discouraged?
  4. Technology Alignment: Which patterns work best with your chosen stack?
  5. Case Studies: Real-world examples of similar projects

Synthesize Findings into:

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

Step 3: Select Architecture Paradigm (
arch-init:paradigm-selected
)

Option A: Manual Selection Using archetypes Plugin

Invoke the architecture paradigms skill:

**Verification:** Run the command with `--help` flag to verify availability.
Skill(architecture-paradigms)

Verification: Run the command with 

--help
flag to verify availability.

This will guide you through selecting from the 14 available paradigms:

  • Layered Architecture
  • Functional Core, Imperative Shell
  • Hexagonal (Ports & 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: Automated Paradigm Matching

Use the decision matrix below to recommend a paradigm based on project context:

**Verification:** Run the command with `--help` flag to verify availability.
┌─────────────────────┬─────────┬─────────┬──────────┬─────────────┐
│ Project Context     │ Simple  │ Moderate│ Complex  │ Highly      │
│                     │ Domain  │ Domain  │ Domain   │ Complex     │
├─────────────────────┼─────────┼─────────┼──────────┼─────────────┤
│ < 5 engineers       │ Layered │ Layered │ Hexagonal│ Functional  │
│                     │         │ Hexag. │ Functional│ 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       │
└─────────────────────┴─────────┴─────────┴──────────┴─────────────┘

Verification: Run the command with 

--help
flag to verify availability.

Special Cases:

  • Real-time/Streaming: Event-Driven + Pipeline
  • Bursty/Cloud-Native: Serverless
  • Extensible Platform: Microkernel
  • Data Processing: Pipeline + Event-Driven
  • Legacy Integration: Hexagonal
  • High-Throughput Stateful: Space-Based

Step 4: Customize Templates (
arch-init:templates-customized
)

Template Adaptation Strategy:

  1. Load Base Templates for the chosen language (Python/Rust/TypeScript)
  2. Apply Architecture-Specific Modifications based on selected paradigm
  3. Generate Custom Configuration reflecting architectural choices
  4. Create Documentation explaining the architecture

Example Adaptations:

For Functional Core, Imperative Shell:

**Verification:** Run the command with `--help` flag to verify availability.
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

Verification: Run the command with 

--help
flag to verify availability.

For Hexagonal Architecture:

**Verification:** Run the command with `--help` flag to verify availability.
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

Verification: Run the command with 

--help
flag to verify availability.

For Microservices:

**Verification:** Run the command with `--help` flag to verify availability.
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

Verification: Run 

pytest -v
to verify tests pass.

Step 5: Create Architecture Decision Record (
arch-init:decision-recorded
)

Generate ADR documenting the architecture choice:

# 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 online research results]

### Key Considerations
- **Team Fit**: [Why this matches team size/experience]
- **Domain Fit**: [Why this matches problem complexity]
- **Technology Fit**: [Why this works with 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, etc.]

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

Verification: Run the command with 

--help
flag to verify availability.

Output: Complete Initialization Package

After completing this workflow, you'll have:

  1. Project Structure: Customized to chosen architecture
  2. Configuration: Architecture-appropriate tooling and dependencies
  3. Documentation: ADR explaining the architecture choice
  4. Guidance: Links to relevant paradigm skill for implementation
  5. Examples: Reference projects using similar architecture

Script Integration

Claude Code can invoke the architecture research and template customization scripts:

Architecture Research

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

Verification: Run 

python --version
to verify Python environment.

The researcher returns a recommendation with:

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

Template Customization

# Generate architecture-specific directory structure
uv run python plugins/attune/scripts/template_customizer.py \
  --paradigm cqrs-es \
  --language python \
  --project-name my-project \
  --output-dir ./my-project

Verification: Run 

python --version
to verify Python environment.

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

Full Interactive Flow

# Interactive architecture-aware initialization
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

Verification: Run 

python --version
to verify Python environment.

Using as Library (within Claude Code)

# Import and use programmatically
from architecture_researcher import ArchitectureResearcher, ProjectContext
from template_customizer import TemplateCustomizer

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

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

Verification: Run the command with 

--help
flag to verify availability.

Integration with Existing Commands

This skill enhances 

/attune:project-init
by adding an architecture selection phase:

# 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 based on research
/attune:project-init --arch <paradigm> # Initialize with chosen architecture

Verification: Run 

python --version
to verify Python environment.

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: Project type=Web API, Domain=Highly Complex, Team=5-15, Requirements=Security, Auditability

Step 2 - Research:

WebSearch("Python fintech API architecture patterns 2026")
WebSearch("financial services API audit trail architecture")
WebSearch("CQRS Event Sourcing Python examples")

Verification: Run 

python --version
to verify Python environment.

Step 3 - Selection: Research + Decision Matrix → CQRS + Event Sourcing

Step 4 - Templates: Customized structure for CQRS/ES with:

  • Command handling module
  • Query handling module
  • Event store configuration
  • Aggregate patterns
  • Projection handlers

Step 5 - ADR: Documenting why CQRS/ES for fintech (auditability, complex business rules, regulatory compliance)

Result: Project initialized with architecture-appropriate structure and clear decision rationale.

Related Skills

  • Skill(architecture-paradigms)
    - Comprehensive paradigm selection
  • Skill(architecture-paradigm-*)
    - Specific paradigm implementation guidance
  • Skill(attune:project-brainstorming)
    - Project ideation before architecture
  • Skill(attune:project-specification)
    - Requirements after architecture chosen

See Also

  • /attune:project-init
    - Basic project initialization
  • /attune:blueprint
    - Architecture planning after paradigm selection
  • Architecture paradigms README for paradigm details