Archiflow (create-archiflow)

Scaffold a multi-agent workflow for generating C4 architecture diagrams using LikeC4 DSL. Works with any agentic AI platform.

npx create-archiflow

What Is This?

A zero-dependency scaffolding tool that installs a complete AI-agent pipeline into your project. It creates a .agents/ directory containing everything an LLM needs to transform raw requirements (User Stories, PRDs, Excel files) into production-grade C4 architecture diagrams.

The installer detects your preferred agentic AI platform and generates the correct adapter file so the workflow is auto-discovered.

Quick Start

1. Install into your project

# Interactive — choose your AI platform
npx create-archiflow

# Non-interactive with preset
npx create-archiflow --preset cursor
npx create-archiflow --preset claude
npx create-archiflow --preset gemini

# Into a specific directory
npx create-archiflow ./my-architecture --preset cursor

# Multiple platforms
npx create-archiflow --preset cursor --preset claude

# All platforms at once
npx create-archiflow --preset all

2. Install Python tools (optional, for Excel extraction)

pip install pandas openpyxl

3. Run the pipeline

Use the slash commands in your AI assistant:

/c4-ingest   → Feed your .xlsx or PRD file
/c4-plan     → Scope which diagrams to generate
/c4-validate → Review & confirm architecture entities
/c4-build    → Generate LikeC4 code
/c4-log      → Document architectural decisions

Supported Platforms

The installer generates platform-specific adapter files so the workflow is auto-discovered:

| Platform | Preset | Adapter File Created | How It Works | |:--|:--|:--|:--| | Cursor | --preset cursor | .cursor/rules/c4-architect.mdc | MDC rule auto-activates on .c4, .xlsx files | | Claude Code | --preset claude | CLAUDE.md | Appends workflow instructions (Claude reads on startup) | | Gemini CLI | --preset gemini | .gemini/settings.json | Points to .agents/ for auto-discovery | | Windsurf | --preset windsurf | .windsurf/rules/c4-architect.md | Cascade reads rules directory automatically | | GitHub Copilot | --preset copilot | .github/copilot-instructions.md | Copilot Chat reads from .github/ | | Cline / Roo Code | --preset cline | .clinerules | Project-level instructions file | | Aider | --preset aider | CONVENTIONS.md | Appends to conventions (Aider reads on startup) | | Qwen | --preset qwen | .qwen/instructions.md | Load as system context in Qwen | | OpenAI / GPTs | --preset openai | .openai/instructions.md | Upload to Custom GPT knowledge base | | Generic (any LLM) | --preset generic | (none) | Point your LLM to .agents/manifest.yaml |

Tip: Use --preset all to generate adapters for every platform at once.

What Gets Created

your-project/
├── .agents/                          ← Core workflow (always created)
│   ├── manifest.yaml                 # Central registry — LLM reads this first
│   ├── orchestrator.md               # Pipeline controller
│   ├── agents/                       # 5 specialized AI personas
│   │   ├── ingestor.agent.md         #   Phase 1: Data extraction
│   │   ├── planner.agent.md          #   Phase 2: Scope planning
│   │   ├── gatekeeper.agent.md       #   Phase 3: Human validation
│   │   ├── builder.agent.md          #   Phase 4: Code generation
│   │   └── decision-logger.agent.md  #   Phase 5: Audit trail
│   ├── rules/                        # 4 business rules
│   │   ├── scoring-matrix.md         #   L3 trigger scoring
│   │   ├── likec4-structure.md       #   Code generation patterns
│   │   ├── naming-conventions.md     #   ID/naming standards
│   │   └── input-classification.md   #   Input routing decision tree
│   ├── templates/                    # 5 output format templates
│   ├── tools/                        # 3 Python utilities
│   │   ├── inspect_excel.py          #   Excel structure discovery
│   │   ├── extract_architecture_data.py  # Data extraction
│   │   └── score_calculator.py       #   L3 scoring calculator
│   ├── workflows/                    # 7 phase workflow files
│   └── skills/c4/SKILL.md           # LikeC4 DSL reference
│
├── .cursor/rules/c4-architect.mdc    ← Cursor adapter (if --preset cursor)
├── CLAUDE.md                         ← Claude adapter (if --preset claude)
├── .gemini/settings.json             ← Gemini adapter (if --preset gemini)
├── .windsurf/rules/c4-architect.md   ← Windsurf adapter (if --preset windsurf)
├── .github/copilot-instructions.md   ← Copilot adapter (if --preset copilot)
├── .clinerules                       ← Cline adapter (if --preset cline)
├── CONVENTIONS.md                    ← Aider adapter (if --preset aider)
└── ...

27 core files (132 KB) + 1 adapter file per platform.

The Pipeline

  INPUT                                                           OUTPUT
 ┌──────┐   ┌───────────┐   ┌─────────┐   ┌────────────┐   ┌─────────┐   ┌──────────┐
 │ .xlsx │──>│ INGESTOR  │──>│ PLANNER │──>│ GATEKEEPER │──>│ BUILDER │──>│ DECISION │
 │ PRD   │   │ Phase 1   │   │ Phase 2 │   │  Phase 3   │   │ Phase 4 │   │   LOG    │
 │ Brief │   │ ~2-5K tok │   │ ~500 tok│   │ ~50/corr.  │   │ ~1K tok │   │ Phase 5  │
 └──────┘   └───────────┘   └─────────┘   └────────────┘   └─────────┘   └──────────┘

| Phase | Agent | What It Does | Token Cost | |:--|:--|:--|:--| | 1. Ingestor | Data Analyst | Extracts & classifies raw input | 2,000–5,000 | | 2. Planner | Lead Architect | Scopes diagrams using scoring matrix | 300–500 | | 3. Gatekeeper | QA Reviewer | Human validation before code gen | ~50/correction | | 4. Builder | Code Generator | Produces LikeC4 .c4 files | 800–1,500 | | 5. Logger | Governance Analyst | Documents decisions and rationale | 100–200 |

Optimized total: ~3,000–7,000 tokens vs ~35,000–55,000 without the pipeline.

Platform-Specific Setup Guides

Cursor

npx create-archiflow --preset cursor

The installer creates .cursor/rules/c4-architect.mdc — a Cursor rule that activates automatically when you open .c4, .likec4, or .xlsx files. Type /c4-ingest in Cursor chat to start the pipeline.

Claude Code

npx create-archiflow --preset claude

The installer appends workflow instructions to CLAUDE.md in your project root. Claude Code reads this file automatically on startup. If CLAUDE.md already exists, the instructions are appended without overwriting.

Gemini CLI / Antigravity

npx create-archiflow --preset gemini

Gemini CLI auto-discovers workflows from the .agents/ directory. The installer also creates .gemini/settings.json to explicitly point to the agents directory. Use /c4-ingest in Gemini to start.

Windsurf (Codeium)

npx create-archiflow --preset windsurf

Creates .windsurf/rules/c4-architect.md which Cascade reads automatically for project context. Type /c4-ingest in Cascade chat.

GitHub Copilot

npx create-archiflow --preset copilot

Creates .github/copilot-instructions.md which Copilot Chat reads from your repository. If the file already exists, instructions are appended.

Cline / Roo Code

npx create-archiflow --preset cline

Creates .clinerules in the project root. Cline and Roo Code read this file for project-level instructions.

Aider

npx create-archiflow --preset aider

Appends workflow instructions to CONVENTIONS.md which Aider reads on startup. If the file already exists, instructions are appended.

Qwen / OpenAI / Any LLM

npx create-archiflow --preset qwen
npx create-archiflow --preset openai
npx create-archiflow --preset generic

For platforms without native auto-discovery, load .agents/manifest.yaml as system context in your LLM. The manifest maps all agents, tools, rules, and templates.

CLI Reference

npx create-archiflow [target-directory] [options]

Options:
  --preset <platform>   Skip interactive prompt (cursor|claude|gemini|windsurf|
                        copilot|cline|aider|qwen|openai|generic|all)
  --help, -h            Show help message
  --list, -l            List all files that will be created
  --force, -f           Overwrite existing .agents/ directory
  --dry-run             Show what would be created without doing it

Examples:
  npx create-archiflow                                # Interactive
  npx create-archiflow --preset cursor                # Cursor
  npx create-archiflow ./arch --preset claude          # Claude + directory
  npx create-archiflow --preset cursor --preset claude # Multiple
  npx create-archiflow --preset all                    # Every platform
  npx create-archiflow --dry-run --preset cursor       # Preview

How It Works — For LLM Developers

The system follows a multi-agent pipeline architecture:

1. manifest.yaml is the single entry point — any LLM reads this to understand the full system
2. Agents are specialized personas with defined tools, rules, and I/O contracts
3. Rules are shared business logic referenced by multiple agents
4. Templates enforce structured output between phases
5. Tools are Python scripts agents can execute for data extraction and scoring

This maps cleanly to:

• LangChain: Agents → Agent(), Tools → Tool(), Pipeline → Process()
• CrewAI: Agents → Agent(), Tasks → Task(), Rules → Backstory
• AutoGen: Agents → ConversableAgent, Orchestrator → GroupChatManager
• Multi-Agent Frameworks: Agents → Personas, Rules → Checklists, Tools → Utilities

Token-Cost Philosophy

Every token spent on the wrong architecture is a token wasted.

| Action | Cost | Strategy | |:--|:--|:--| | Raw Excel → LLM context | 30,000–50,000 | Never do this | | Filtered extraction (Phase 1) | 2,000–5,000 | ~90% reduction | | Table correction (Phase 3) | ~50 | Cheapest fix possible | | Code generation (Phase 4) | 800–1,500 | Happens once with confidence | | Code regeneration | 800–1,500 | Avoided by Phase 3 gate |

License

MIT