Aif Architecture

Architecture - Generate Architecture Guidelines

Generate .ai-factory/ARCHITECTURE.md with architecture decisions tailored to the project.

Workflow

Step 0: Load Config & Project Context

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description and paths.architecture
• Language: language.ui for prompts and language.artifacts for generated architecture content

When invoked by /aif, assume .ai-factory/config.yaml has already been written for the current setup run and already contains the resolved language.ui / language.artifacts values.

If config.yaml doesn't exist, use defaults:

• DESCRIPTION.md: .ai-factory/DESCRIPTION.md
• ARCHITECTURE.md: .ai-factory/ARCHITECTURE.md
• Language: en (English)

THEN: Read .ai-factory/DESCRIPTION.md (use path from config) if it exists to understand:

• Tech stack (language, framework, database, ORM)
• Project size and complexity
• Core features and requirements
• Non-functional requirements

If .ai-factory/DESCRIPTION.md does not exist:

⚠️  No project description found.

Run /aif first to set up project context, or describe your project manually:
- What are you building?
- Tech stack (language, framework, database)?
- Team size?
- Expected scale?

Allow standalone usage — if user provides manual input, use that instead.

Read .ai-factory/skill-context/aif-architecture/SKILL.md — MANDATORY if the file exists.

This file contains project-specific rules accumulated by /aif-evolve from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project.

How to apply skill-context rules:

• Treat them as project-level overrides for this skill's general instructions
• When a skill-context rule conflicts with a general rule written in this SKILL.md, the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
• When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
• Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient
• CRITICAL: skill-context rules apply to ALL outputs of this skill — including the ARCHITECTURE.md template. The template in this SKILL.md is a base structure. If a skill-context rule says "architecture doc MUST include X" or "MUST cover section Y" — you MUST augment the template accordingly. Generating ARCHITECTURE.md that violates skill-context rules is a bug.

Enforcement: After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user.

Step 1: Recommend Architecture

Based on project context, evaluate against the decision matrix and recommend an architecture:

If $ARGUMENTS specifies an architecture (e.g., /aif-architecture explicit):

• Direct mapping (no suffix needed):
  • layers → Layered Architecture
  • microservices → Microservices
  • structured → Structured Modules (ask variant — see below)
  • explicit → Explicit Architecture (ask variant — see below)
• Legacy aliases (deprecated, mapped to current patterns — may be removed in future):
  • clean → Explicit Architecture
  • ddd → Explicit Architecture
  • monolith → Structured Modules
  • vertical → Explicit Architecture (Vertical Slice By Entity)
• With suffix (variant is determined, no need to ask):
  • structured-layers → Structured Modules (Technical Layer)
  • structured-vertical → Structured Modules (Vertical Slices By Entity)
  • explicit-layers → Explicit Architecture (Technical Layer)
  • explicit-vertical → Explicit Architecture (Vertical Slice By Entity)
  • explicit-flat → Explicit Architecture (Flat Vertical Slice - Simplified)
• Without suffix (ask user to choose variant):
  • If structured is specified without a suffix: ASK the user: "Which folder structure variant do you prefer for Structured Modules? 1. Technical Layer (simpler) or 2. Vertical Slices by Entity (better for large modules)". Wait for their answer before generating the artifact.
  • If explicit is specified without a suffix: ASK the user: "Which folder structure variant do you prefer for Explicit Architecture? 1. Technical Layer or 2. Explicit Architecture (Vertical Slice By Entity) or 3. Explicit Architecture (Flat Vertical Slice - Simplified)". Wait for their answer before generating the artifact.
• Use the resolved architecture directly, skip the recommendation step and proceed to Step 1.5

If no specific architecture requested:

• Evaluate the project against the decision matrix (see references/architecture.md)
• Consider: team size, domain complexity, scale requirements, tech stack
• Present recommendation via AskUserQuestion:

Based on your project context:
- [reason 1 from project analysis]
- [reason 2 from project analysis]

Which architecture pattern should we use?

1. [Recommended pattern] (Recommended) — [why it fits]
2. [Alternative 1] — [brief reason]
3. [Alternative 2] — [brief reason]
4. [Alternative 3] — [brief reason]

Architecture options:

• Structured Modules (Technical Layer)
• Structured Modules (Vertical Slices By Entity)
• Explicit Architecture (Technical Layer)
• Explicit Architecture (Vertical Slice By Entity)
• Explicit Architecture (Flat Vertical Slice - Simplified)
• Microservices
• Layered Architecture (See references/architecture.md for detailed descriptions of these patterns to formulate your recommendation).

CRITICAL INSTRUCTION: You MUST read references/architecture.md before generating the ARCHITECTURE.md artifact to ensure correct terminology, dependency directions.