agentleFS
unxedunxed/f4/.agents/skills/aif-architecture/SKILL.md

aif-architecture

Skill261 starsChanged 2 months agoBSD-3-ClauseView on GitHub

Generate architecture guidelines for the project. Analyzes tech stack from DESCRIPTION.md, recommends an architecture pattern, and creates .ai-factory/ARCHITECTURE.md. Use when setting up project architecture, asking "which architecture", or after /aif setup.

4 other projects use a version of this, 3 of them edited.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. 12 are common, 2 are distinctive, and 12 are very specific to this project.

  • 12

    Common

    Most of the 3 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

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

    line 17
  2. Very specific:

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

    line 21
  3. Very specific:

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

    line 23
  4. Very specific:

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

    line 28
  5. Common:

    Treat them as project-level overrides for this skill's general instructions

    line 53
  6. Very specific:

    When a skill-context rule conflicts with a general rule written in this SKILL.md,

    line 54
  7. Very specific:

    When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context

    line 56
  8. Common:

    Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience …

    line 57
  9. Common:

    Enforcement: After generating any output artifact, verify it against all skill-context rules.

    line 64
  10. Common:

    If any rule is violated — fix the output before presenting it to the user.

    line 65
  11. Very specific:

    If structured is specified without a suffix: ASK the user: "Which folder structure variant do you prefer for Structured Modules?

    line 89
  12. Very specific:

    If explicit is specified without a suffix: ASK the user: "Which folder structure variant do you prefer for Explicit Architecture?

    line 90
  13. Common:

    Use the resolved architecture directly, skip the recommendation step and proceed to Step 1.5

    line 91
  14. Common:

    Consider: team size, domain complexity, scale requirements, tech stack

    line 95
  15. Very specific:

    CRITICAL: Before generating the document, compare the chosen architecture's ideal folder structure (from references/architecture.md) …

    line 125
  16. Distinctive:

    If the project is empty or mostly matches: proceed to Step 2.

    line 127
  17. Very specific:

    If there are significant discrepancies: DO NOT silently merge the ideal architecture with the messy reality.

    line 128
  18. Distinctive:

    Wait for their decision before proceeding to Step 2.

    line 138
  19. Common:

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

    line 142
  20. Common:

    Use the project's actual conventions (import paths, naming, etc.)

    line 210
  21. Common:

    Keep it practical — focus on rules that affect day-to-day development

    line 211
  22. Very specific:

    If the resolved DESCRIPTION.md path exists, add or update an architecture-pointer section in resolved language.artifacts.

    line 216
  23. Common:

    Use the resolved architecture path from config, not the default path literal.

    line 217
  24. Very specific:

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

    line 227
  25. Common:

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

    line 233
  26. Common:

    Read-only context: roadmap, rules, research, and plan artifacts unless user explicitly requests otherwise.

    line 258

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Step 1.5: Codebase Alignment Check

CRITICAL: Before generating the document, compare the chosen architecture's ideal folder structure (from references/architecture.md) against the actual existing codebase structure.

  • If the project is empty or mostly matches: proceed to Step 2.
  • If there are significant discrepancies: DO NOT silently merge the ideal architecture with the messy reality. You MUST stop and ask the user how to proceed via AskUserQuestion:
The current project structure differs significantly from the ideal [Pattern Name] architecture.
[Briefly list 1-2 major differences]

How should we generate the ARCHITECTURE.md?
1. Adapt the guidelines to fit the existing application structure (document reality).
2. Generate the pure, strict architecture guidelines (requires refactoring the application later to match).

Wait for their decision before proceeding to Step 2.

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]

[If the user chose Option 2 (strict architecture) in Step 1.5, add the following section:]
## Legacy vs New Code Policy
- **New Features:** All new code MUST strictly follow the architecture defined in this document.
- **Legacy Code Modification:** Do NOT automatically refactor unrelated legacy code to fit this architecture. Touch legacy code only when necessary for bug fixes, when tasked with explicit refactoring, or when adapting it to be consumed by new features.
- **Interoperability:** When new code must call legacy code, isolate the interaction using adapters, interfaces, or facades so that legacy patterns do not pollute the new architecture.

[If the user chose Option 1 (adapt to reality) in Step 1.5, add the following lighter section:]
## Code Organization Note
- **New Features:** All new code should follow the architecture defined in this document where practical.
- **Existing Code:** Document the current structure as-is. When modifying existing code, prefer following the architectural conventions in this document, but do not force a rewrite of unrelated code.
- **Interoperability:** When new code must call existing code, prefer clean interfaces but do not refactor purely for structural alignment.

## 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
  • Base the generated folder structure on the user's decision in Step 1.5 (either adapted to reality or strict pure architecture). Do not automatically merge them without user consent.

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.