Directory Structure Guide: Complete Factory Project Overview

What You'll Learn

• ✅ Understand the complete directory structure of a Factory project
• ✅ Know the purpose of each directory and file
• ✅ Understand how artifacts are stored
• ✅ Master configuration file usage and modification methods

Core Concept

Factory projects use a clear, layered directory structure that separates configuration, code, artifacts, and documentation. Understanding these directory structures helps you quickly locate files, modify configurations, and debug issues.

Factory projects have two forms:

Form 1: Source Repository (cloned from GitHub) Form 2: Initialized Project (generated by factory init)

This tutorial focuses on Form 2—the initialized Factory project structure, as this is the directory you'll work with daily.

---

Complete Factory Project Structure

my-app/                          # Your Factory project root directory
├── .factory/                    # Factory core configuration directory (do not manually modify)
│   ├── pipeline.yaml             # Pipeline definition (7 stages)
│   ├── config.yaml               # Project configuration file (tech stack, MVP constraints, etc.)
│   ├── state.json                # Pipeline running state (current stage, completed stages)
│   ├── agents/                   # Agent definitions (AI assistant task descriptions)
│   ├── skills/                   # Skill modules (reusable knowledge)
│   ├── policies/                 # Policy documents (permissions, failure handling, code standards)
│   └── templates/                # Configuration templates (CI/CD, Git Hooks)
├── .claude/                      # Claude Code configuration directory (auto-generated)
│   └── settings.local.json       # Claude Code permission configuration
├── input/                        # User input directory
│   └── idea.md                   # Structured product idea (generated by Bootstrap)
└── artifacts/                    # Pipeline artifact directory (outputs from 7 stages)
    ├── prd/                      # PRD artifact
    │   └── prd.md                # Product Requirements Document
    ├── ui/                       # UI artifact
    │   ├── ui.schema.yaml        # UI structure definition
    │   └── preview.web/          # Previewable HTML prototype
    │       └── index.html
    ├── tech/                     # Tech artifact
    │   └── tech.md               # Technical architecture document
    ├── backend/                  # Backend code (Express + Prisma)
    │   ├── src/                  # Source code
    │   ├── prisma/               # Database configuration
    │   │   ├── schema.prisma     # Prisma data model
    │   │   └── seed.ts           # Seed data
    │   ├── tests/                # Tests
    │   ├── docs/                 # API documentation
    │   ├── package.json
    │   ├── tsconfig.json
    │   └── README.md
    ├── client/                   # Frontend code (React Native)
    │   ├── src/                  # Source code
    │   ├── __tests__/            # Tests
    │   ├── app.json
    │   ├── package.json
    │   └── README.md
    ├── validation/               # Validation artifact
    │   └── report.md             # Code quality validation report
    ├── preview/                  # Preview artifact
    │   ├── README.md             # Deployment and running guide
    │   └── GETTING_STARTED.md    # Quick start guide
    ├── _failed/                  # Failed artifact archive
    │   └── <stage-id>/           # Artifacts from failed stages
    └── _untrusted/               # Unauthorized artifact isolation
        └── <stage-id>/           # Files written by unauthorized agents

---

.factory/ Directory Explained

The .factory/ directory is the core of the Factory project, containing pipeline definitions, Agent configurations, and policy documents. This directory is automatically created by the factory init command and typically doesn't need manual modification.

pipeline.yaml - Pipeline Definition

Purpose: Defines the execution order, inputs/outputs, and exit criteria for the 7 stages.

Key Content:

• 7 stages: bootstrap, prd, ui, tech, code, validation, preview
• For each stage: Agent, input files, output files
• Exit criteria: validation standards for stage completion

Example:

stages:
  - id: bootstrap
    description: Initialize project idea
    agent: agents/bootstrap.agent.md
    inputs: []
    outputs:
      - input/idea.md
    exit_criteria:
      - idea.md exists
      - idea.md describes a coherent product idea

When to modify: Typically no need to modify, unless you want to customize the pipeline flow.

config.yaml - Project Configuration File

Purpose: Configures tech stack, MVP constraints, UI preferences, and other global settings.

Main Configuration Items:

• preferences: Tech stack preferences (backend language, database, frontend framework, etc.)
• mvp_constraints: MVP scope control (max pages, max models, etc.)
• ui_preferences: UI design preferences (aesthetic direction, color scheme)
• pipeline: Pipeline behavior (checkpoint mode, failure handling)
• advanced: Advanced options (Agent timeout, concurrency control)

Example:

preferences:
  backend:
    language: typescript
    framework: express
    database: sqlite
  mvp_constraints:
    max_pages: 3
    enable_auth: false

When to modify: When you want to adjust the tech stack or change the MVP scope.

state.json - Pipeline State

Purpose: Records the pipeline's running state, supporting checkpoint resumption.

Key Content:

• status: Current status (idle/running/waiting_for_confirmation/paused/failed)
• current_stage: Current execution stage
• completed_stages: List of completed stages
• last_updated: Last update time

When to modify: Auto-updated, do not manually modify.

agents/ - Agent Definition Directory

Purpose: Defines the responsibilities, inputs/outputs, and execution constraints for each Agent.

File List:

File	Description
orchestrator.checkpoint.md	Orchestrator core definition (pipeline coordination)
orchestrator-implementation.md	Orchestrator implementation guide (development reference)
bootstrap.agent.md	Bootstrap Agent (structured product idea)
prd.agent.md	PRD Agent (generate requirements document)
ui.agent.md	UI Agent (design UI prototype)
tech.agent.md	Tech Agent (design technical architecture)
code.agent.md	Code Agent (generate code)
validation.agent.md	Validation Agent (validate code quality)
preview.agent.md	Preview Agent (generate deployment guide)

When to modify: Typically no need to modify, unless you want to customize a specific Agent's behavior.

skills/ - Skill Module Directory

Purpose: Reusable knowledge modules, each Agent loads corresponding Skill files.

Directory Structure:

skills/
├── bootstrap/skill.md         # Product idea structuring
├── prd/skill.md               # PRD generation
├── ui/skill.md                # UI design
├── tech/skill.md              # Technical architecture + database migrations
├── code/skill.md              # Code generation + tests + logging
│   └── references/            # Code generation reference templates
│       ├── backend-template.md   # Production-ready backend template
│       └── frontend-template.md  # Production-ready frontend template
└── preview/skill.md           # Deployment configuration + quick start guide

When to modify: Typically no need to modify, unless you want to extend a specific Skill's capabilities.

policies/ - Policy Document Directory

Purpose: Defines policies for permissions, failure handling, code standards, etc.

File List:

File	Description
capability.matrix.md	Capability boundary matrix (Agent read/write permissions)
failure.policy.md	Failure handling policy (retry, rollback, manual intervention)
context-isolation.md	Context isolation policy (save tokens)
error-codes.md	Unified error code standard
code-standards.md	Code standards (coding style, file structure)
pr-template.md	PR template and code review checklist
changelog.md	Changelog generation standard

When to modify: Typically no need to modify, unless you want to adjust policies or standards.

templates/ - Configuration Template Directory

Purpose: Configuration templates for CI/CD, Git Hooks, etc.

File List:

File	Description
cicd-github-actions.md	CI/CD configuration (GitHub Actions)
git-hooks-husky.md	Git Hooks configuration (Husky)

When to modify: Typically no need to modify, unless you want to customize the CI/CD flow.

---

.claude/ Directory Explained

settings.local.json - Claude Code Permission Configuration

Purpose: Defines directories and operation permissions that Claude Code can access.

When generated: Auto-generated during factory init.

When to modify: Typically no need to modify, unless you want to adjust the permission scope.

---

input/ Directory Explained

idea.md - Structured Product Idea

Purpose: Stores structured product idea, generated by Bootstrap Agent.

When generated: After Bootstrap stage completion.

Content Structure:

• Problem definition
• Target users
• Core value
• Assumptions
• Out of scope

When to modify: If you want to adjust the product direction, you can manually edit it, then re-run Bootstrap or subsequent stages.

---

artifacts/ Directory Explained

The artifacts/ directory is where pipeline artifacts are stored. Each stage writes artifacts to the corresponding subdirectory.

prd/ - PRD Artifact Directory

Artifact Files:

• prd.md: Product Requirements Document

Content:

• User stories
• Features list
• Non-functional requirements
• Out of scope

When generated: After PRD stage completion.

ui/ - UI Artifact Directory

Artifact Files:

• ui.schema.yaml: UI structure definition (pages, components, interactions)
• preview.web/index.html: Previewable HTML prototype

Content:

• Page structure (number of pages, layout)
• Component definitions (buttons, forms, lists, etc.)
• Interaction flows (navigation, transitions)
• Design system (color scheme, fonts, spacing)

When generated: After UI stage completion.

Preview method: Open preview.web/index.html in a browser.

tech/ - Tech Artifact Directory

Artifact Files:

• tech.md: Technical architecture document

Content:

• Tech stack selection (backend, frontend, database)
• Data model design
• API endpoint design
• Security policies
• Performance optimization recommendations

When generated: After Tech stage completion.

backend/ - Backend Code Directory

Artifact Files:

backend/
├── src/                      # Source code
│   ├── routes/               # API routes
│   ├── services/             # Business logic
│   ├── middleware/           # Middleware
│   └── utils/               # Utility functions
├── prisma/                   # Prisma configuration
│   ├── schema.prisma         # Prisma data model
│   └── seed.ts              # Seed data
├── tests/                    # Tests
│   ├── unit/                 # Unit tests
│   └── integration/          # Integration tests
├── docs/                     # Documentation
│   └── api-spec.yaml        # API specification (Swagger)
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

Content:

• Express backend server
• Prisma ORM (SQLite/PostgreSQL)
• Vitest testing framework
• Swagger API documentation

When generated: After Code stage completion.

client/ - Frontend Code Directory

Artifact Files:

client/
├── src/                      # Source code
│   ├── screens/              # Screens
│   ├── components/           # Components
│   ├── navigation/           # Navigation configuration
│   ├── services/             # API services
│   └── utils/               # Utility functions
├── __tests__/               # Tests
│   └── components/          # Component tests
├── assets/                  # Static assets
├── app.json                 # Expo configuration
├── package.json
├── tsconfig.json
└── README.md

Content:

• React Native + Expo
• React Navigation
• Jest + React Testing Library
• TypeScript

When generated: After Code stage completion.

validation/ - Validation Artifact Directory

Artifact Files:

• report.md: Code quality validation report

Content:

• Dependency installation validation
• TypeScript type checking
• Prisma schema validation
• Test coverage

When generated: After Validation stage completion.

preview/ - Preview Artifact Directory

Artifact Files:

• README.md: Deployment and running guide
• GETTING_STARTED.md: Quick start guide

Content:

• Local running steps
• Docker deployment configuration
• CI/CD pipeline
• Access URLs and demo flow

When generated: After Preview stage completion.

_failed/ - Failed Artifact Archive

Purpose: Stores artifacts from failed stages for debugging.

Directory Structure:

_failed/
├── bootstrap/
├── prd/
├── ui/
├── tech/
├── code/
├── validation/
└── preview/

When generated: After a stage fails twice consecutively.

_untrusted/ - Unauthorized Artifact Isolation

Purpose: Stores files written by unauthorized agents to prevent contaminating main artifacts.

Directory Structure:

_untrusted/
├── bootstrap/
├── prd/
├── ui/
├── tech/
├── code/
├── validation/
└── preview/

When generated: When an agent attempts to write to an unauthorized directory.

---

Common Questions

1. Can I manually modify files under .factory/?

Caution When Modifying

Not recommended to directly modify files under .factory/ unless you are very clear about what you're doing. Incorrect modifications may cause the pipeline to fail to run normally.

If you need to customize configuration, prioritize modifying the config.yaml file.

2. Can I manually modify files under artifacts/?

Yes. Files under artifacts/ are pipeline output artifacts. You can:

• Modify input/idea.md or artifacts/prd/prd.md to adjust product direction
• Manually fix code in artifacts/backend/ or artifacts/client/
• Adjust styles in artifacts/ui/preview.web/index.html

After modification, you can re-run the pipeline from the corresponding stage.

3. How to handle files under _failed/ and _untrusted/?

• _failed/: Check the failure cause, fix the issue, then re-run the stage.
• _untrusted/: Confirm if the file should exist. If so, move it to the correct directory.

4. What to do if state.json is corrupted?

If state.json is corrupted, you can run the following command to reset:

factory reset

5. How to check the current status of the pipeline?

Run the following command to check the current status:

factory status

---

Summary

In this lesson, we covered the complete directory structure of Factory projects in detail:

• ✅ .factory/: Factory core configuration (pipeline, agents, skills, policies)
• ✅ .claude/: Claude Code permission configuration
• ✅ input/: User input (idea.md)
• ✅ artifacts/: Pipeline artifacts (prd, ui, tech, backend, client, validation, preview)
• ✅ _failed/ and _untrusted/: Failed and unauthorized artifact archives

Understanding these directory structures helps you quickly locate files, modify configurations, and debug issues.

---

Next Lesson Preview

In the next lesson, we'll learn Code Standards.

You'll learn:

• TypeScript coding standards
• File structure and naming conventions
• Comment and documentation requirements
• Git commit message standards