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: Analyze & Recommend

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

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

• Map legacy aliases to current patterns:
  • clean -> Explicit Architecture
  • ddd -> Explicit Architecture
  • monolith -> Structured Modules
  • vertical -> Explicit Architecture (Vertical Slices)
• If structured is specified without a suffix (-layers or -vertical), ASK the user: "Which folder structure variant do you prefer for Structured Modules? 1. By Technical Layer (simpler) or 2. Vertical Slices by Model/Entity (better for large modules)". Wait for their answer before generating the artifact.
• If explicit is specified without a suffix (-layers or -vertical), ASK the user: "Which folder structure variant do you prefer for Explicit Architecture? 1. By Technical Layer or 2. Vertical Slices by Feature". Wait for their answer before generating the artifact.
• Use the resolved architecture directly, skip to Step 2

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 Layers) — domain-aware modular architecture organized by technical layers (controllers, services, repositories). Simpler, best for small-to-medium modules.
• Structured Modules (Vertical Slices) — domain-aware modular architecture organized by Vertical Slices (grouped by Model/Entity) where each entity has its own slice containing its controller, service, and repository. Best for growing projects that need structure now but may evolve into Explicit Architecture later.
• Explicit Architecture (Technical Layers) — pragmatic fusion of Clean, Hexagonal, Onion architectures. Code within bounded contexts is organized by technical layer (Domain, Application, Infrastructure, Presentation). Best for complex domains where layered boundaries must be strict.
• Explicit Architecture (Vertical Slices) — same Explicit Architecture principles, but code within each bounded context is organized by feature (vertical slices) containing their own Application, Infrastructure, and Presentation logic, while Domain stays shared. Best when features are independent and long-lived.
• Microservices — independent deployment, good for large teams with clear domain boundaries
• Layered Architecture — simple layers (presentation → business → data), good for smaller projects

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

Step 2: Generate the Architecture Artifact

Create the parent directory for the resolved architecture path if needed.

Generate the resolved architecture artifact (default: .ai-factory/ARCHITECTURE.md) with the following structure, adapted to the project's tech stack and language:

# Architecture: [Pattern Name]

## Overview
[1-2 paragraphs: what this architecture is and why it was chosen for THIS project]

## Decision Rationale
- **Project type:** [from DESCRIPTION.md]
- **Tech stack:** [language, framework]
- **Key factor:** [primary reason for this choice]

## Folder Structure
\`\`\`
[folder structure adapted to the project's tech stack]
[use actual framework conventions — e.g., Next.js app/ dir, Laravel app/ dir, Go cmd/ dir]
\`\`\`

## Dependency Rules
[What depends on what. Inner vs outer layers. Module boundaries.]

- ✅ [allowed dependency direction]
- ❌ [forbidden dependency direction]

## Layer/Module Communication
[How layers or modules communicate with each other]
- [pattern 1]
- [pattern 2]

## Key Principles
1. [Principle 1 — adapted to this project]
2. [Principle 2]
3. [Principle 3]

## Code Examples

### [Example 1 title]
\`\`\`[language]
[code example in the project's language/framework]
\`\`\`

### [Example 2 title]
\`\`\`[language]
[code example showing dependency rule]
\`\`\`

## Anti-Patterns
- ❌ [What NOT to do in this architecture]
- ❌ [Common mistake to avoid]

Rules for generation:

• Adapt ALL examples to the project's language and framework (don't use TypeScript examples for a Go project)
• Use the project's actual conventions (import paths, naming, etc.)
• Keep it practical — focus on rules that affect day-to-day development
• Folder structure should extend from what already exists in the project, not replace it

Step 3: Update DESCRIPTION.md

If the resolved DESCRIPTION.md path exists, add or update an architecture-pointer section in resolved language.artifacts. Use the resolved architecture path from config, not the default path literal.

## [Localized heading: Architecture]
[Localized sentence in resolved artifacts language referencing the resolved architecture artifact path for detailed architecture guidelines.]
[Localized label: Pattern]: [chosen pattern name]

Step 4: Update AGENTS.md

If AGENTS.md exists in the project root, add the resolved architecture artifact path to the localized "AI Context Files" table in resolved language.artifacts:

| [resolved-architecture-path] | [Localized architecture artifact description in resolved artifacts language] |

Only add if the resolved architecture path is not already present.

Step 5: Confirm

Present the confirmation in resolved language.ui and report the resolved architecture path:

[Localized success heading in `language.ui`]

[Localized pattern label in `language.ui`]: [chosen pattern]
[Localized file label in `language.ui`]: [resolved architecture path]

[Localized key-rules heading in `language.ui`]:
- [rule 1]
- [rule 2]
- [rule 3]

[Localized closing sentence in `language.ui` about workflow skills following these architecture guidelines.]

Artifact Ownership

• Primary ownership: the resolved architecture artifact path (default: .ai-factory/ARCHITECTURE.md).
• Respect config overrides: write to the resolved architecture path from config.yaml when provided.
• Allowed companion updates: architecture pointer in the resolved DESCRIPTION path from config.yaml, architecture row in AGENTS.md context table.
• Read-only context: roadmap, rules, research, and plan artifacts unless user explicitly requests otherwise.