/moai project

Analyzes your project’s codebase and automatically generates the foundational documents the AI needs to understand the project.

Info

Slash command: In Claude Code, type /moai:project to run this command directly. Typing just /moai shows the list of all available subcommands.

/moai project is the project documentation generation command of the MoAI-ADK workflow. It analyzes your project’s source code, configuration files, and directory structure to help the AI understand the project quickly.

From the agentic-harness perspective, this command lays the harness’s foundation. Instead of letting the agent re-discover the codebase from scratch every session, project knowledge is pinned down in files — file-based persistent memory is a fundamental pattern of harness design, and /moai project creates its starting point. It also has a tokenomics effect: exploration cost that would repeat every session is replaced by a one-time document generation.

Info

Why do you need project documentation?

Claude Code knows nothing about your project when a new conversation starts. Through the documents generated by /moai project, the AI comes to understand:

• What this project does (product.md)
• How the code is organized (structure.md)
• What technologies it uses (tech.md)

With these documents in place, later commands like /moai plan and /moai run can perform accurate, project-context-aware work.

> /moai project

Run it without any arguments or options and it automatically analyzes the current project directory.

/moai project generates 3 core documents plus an architecture codemap under the .moai/project/ directory:

.moai/
└── project/
    ├── product.md      # Project overview
    ├── structure.md    # Directory structure analysis
    ├── tech.md         # Tech stack information
    └── codemaps/       # Architecture codemaps (Phase 9)

Along with document generation, automatic harness composition tailored to the project is also part of this command’s role — based on the analyzed tech stack, a project-specific agent team (harness) can be composed as well. See /moai harness for the details of harness creation.

Contains the project’s core information:

Analyzes the project’s file and folder organization:

Organizes the technology information used in the project:

/moai project runs a different workflow depending on the project type.

flowchart TD
    Start["/moai project run"] --> Q1{Project type?}

    Q1 -->|New project| New["Phase 2: deep interview
(Stage A + B)"]
    Q1 -->|Existing project| Exist["Phase 3: codebase analysis"]

    New --> NewQ["Project purpose"]
    New --> NewL["Primary language"]
    New --> NewD["Project description"]

    NewQ --> Gen["Phase 6: document generation"]
    NewL --> Gen
    NewD --> Gen

    Exist --> Exp["Explore agent
codebase analysis"]
    Exp --> Conf["Phase 5: user confirmation"]

    Conf -->|Approve| Gen
    Conf -->|Cancel| End["Exit"]

    Gen --> Audit["Phase 7: plan-auditor independent audit"]
    Audit --> CM["Phase 9: codemap generation"]
    CM --> LSP["Phase 10: LSP check"]
    LSP --> Complete["Phase 14: done"]

The project type is checked first.

Warning

[HARD] rule: the project type must be asked first. The user’s project situation is confirmed before any codebase analysis.

Question: What type of project is this?

If you chose a new project, a two-stage Deep Interview is conducted — a clarity-score-based Stage A (Vision-Domain / Technology-Constraints / Scope, variable rounds up to project.max_rounds) plus a mandatory Stage B expansion-axis round. The following information is collected:

Question 1 - Project purpose:

• Web Application: frontend, backend, or full-stack web app
• API Service: REST API, GraphQL, or microservices
• CLI Tool: command-line utility or automation tool
• Library/Package: reusable code library or SDK

Question 2 - Primary language:

• Python: backend, data science, automation
• TypeScript/JavaScript: web, Node.js, frontend
• Go: high-performance services, CLI tools
• Other: Rust, Java, Ruby, etc. (detailed follow-up)

Question 3 - Project description (free input):

• Project name
• Main features or goals
• Target users

Initial documents are generated from the collected information, then the flow moves to Phase 6 document generation.

If you chose an existing project, the analysis is delegated to the Explore agent.

Info

Agent delegation: codebase analysis is performed by the Explore subagent. MoAI only collects the results and presents them to the user.

Analysis goals:

• Project structure: main directories, entry points, architecture patterns
• Tech stack: languages, frameworks, core dependencies
• Core features: main features and the location of business logic
• Build system: build tools, package managers, scripts

Explore agent output:

• Detected primary language
• Identified frameworks
• Architecture patterns (MVC, Clean Architecture, Microservices, etc.)
• Key directory mapping (source, tests, config, docs)
• Dependency catalog
• Entry-point identification

After codebase analysis, a two-stage Deep Interview is also conducted for existing projects — a clarity-score-based Stage A (Ownership-Goal / Constraints / Scope-Priority, variable rounds up to project.max_rounds) plus a mandatory Stage B expansion-axis round. It draws out the ownership, goals, and priorities that the analysis results alone do not reveal.

The analysis results are shown to the user for approval.

Displayed contents:

• Detected languages
• Frameworks
• Architecture
• List of core features

Options:

• Proceed: continue with document generation
• Detailed review: review the analysis details first
• Cancel: adjust the project setup

Document generation is delegated to the manager-docs agent.

Handed-off contents:

• Phase 3 analysis results (or Phase 2 interview input)
• Phase 5 user confirmation
• Output directory: .moai/project/
• Language: the config’s conversation_language

Generated files:

After document generation, the plan-auditor subagent conditionally audits the artifacts independently and drives a retry loop when needed — applying the independent-audit principle (the agent that built it does not inspect its own results) to project document generation as well.

Explore + manager-docs generate architecture codemaps in .moai/project/codemaps/.

Checks whether an LSP server matching the detected tech stack is installed.

Per-language LSP mapping (16 languages supported):

Options when LSP is not installed:

• Continue without LSP: proceed to completion
• Show installation guide: display the setup guide for the detected language
• Auto-install now: install via an Agent(general-purpose) devops scope (confirmation required)

Displays a completion message in the user’s language.

• List of generated files
• Location: .moai/project/
• Status: success or partial completion

Next-step options:

• Write a SPEC: define a feature specification with /moai plan
• Review documents: open and review the generated files
• Start a new session: clear the context and start fresh

After the basic document generation (Phase 0-4), /moai project performs extended phases that comprehensively configure the project environment.

flowchart TD
    A["Phase 4: Completion
(basic document generation)"] --> B["Phase 8
harness-spec.yaml"]
    B --> C["Phase 11
MCP provisioning"]
    C --> D["Phase 12
Dev Methodology"]
    D --> E["Phase 13
DB detection"]
    E --> F["Phase 14
completion summary"]
    F --> G{"Create a harness?"}
    G -->|Yes| H["Phase 15
v4 Builder entry"]
    H --> I["Phase 16
5-Layer activation"]
    G -->|No| J["Exit"]
    I --> J

Generates .moai/project/harness-spec.yaml from the interview answers. This file, with its 8-field schema, acts as a bridge conveying project context to the harness builder — it is extracted automatically from the interview.md answers without user interaction.

Detects the tech stack and selects suitable MCP servers from mcp-matrix.yaml. After orchestrator approval, it appends to .mcp.json (an additive write) — it does not overwrite existing MCP settings.

Detects DB keywords via Grep/Glob to generate db-detection.json. Supported DB engine categories:

• Relational/SQL: PostgreSQL, MySQL, MariaDB, SQLite, Oracle, SQL Server, CockroachDB, Supabase, Neon, Planetscale
• NoSQL Document: MongoDB, Firestore, Firebase, Couchbase
• NoSQL Key-Value: Redis, DynamoDB, Cassandra, ScyllaDB, Riak
• Search/Analytics: Elasticsearch, ClickHouse, Snowflake, InfluxDB

Phase 15 redirects to the v4 harness builder — Context-First Discovery + the orchestrator-direct 4-phase Builder (ANALYZE → PLAN → GENERATE → ACTIVATE) creates the harness. Phase 16 performs 5-Layer activation by installing the CLAUDE.md marker + registering the main.md router, and runs a smoke gate after creation.

Info

Phase 15-16 are optional — they proceed if harness creation is needed when /moai project runs, and otherwise it completes at Phase 14.

• Applying MoAI-ADK to a new project for the first time - the AI needs foundational documents to understand the project
• Adopting MoAI-ADK in an existing project - documents are auto-generated even for projects that already have code

• After a major project restructuring - when the directory structure or tech stack has changed
• After adopting a major new technology - e.g. a database change or a framework addition
• When a new team member joins the project - onboard with up-to-date documentation

Warning

/moai project overwrites existing documents. If you have manual edits, back them up before running.

First initialize the project in the terminal, then start Claude Code.

# Initialize the project in the terminal
$ moai init my-api-project
$ cd my-api-project

# Generate project docs in Claude Code
> /moai project

Since this is a new project, choose “New project.”

AI: Choose your project type:
1. New project (starting from scratch)
2. Existing project (has code)

User: 1

The AI switches to new-project information gathering mode.

Choose the project’s purpose.

AI: Choose the project purpose:
1. Web Application
2. API Service
3. CLI Tool
4. Library/Package

User: 2

Choose API Service to indicate a REST API server project.

Choose the programming language you will use.

AI: Choose the primary language:
1. Python
2. TypeScript/JavaScript
3. Go
4. Other

User: 1

Choose Python to set up a backend API server development environment.

Enter detailed information about the project.

AI: Describe your project (name, goals, target users):

User: A REST API server. It has user authentication and data management. It is a tool for developers.

This information is used to generate the product.md document.

The AI generates the documents automatically from the collected information.

[Generating documents...]

Done! 3 documents were created in the .moai/project/ directory.

Generated documents:

• .moai/project/product.md - project overview
• .moai/project/structure.md - directory structure
• .moai/project/tech.md - tech stack

Move to a project that already has code and initialize MoAI-ADK.

# Move to the existing project directory
$ cd ~/projects/existing-api

# Initialize MoAI-ADK
$ moai init

# Generate project docs in Claude Code
> /moai project

Choose the existing-project option.

AI: Choose your project type:
1. New project (starting from scratch)
2. Existing project (has code)

User: 2

Proceeding in existing-project mode starts the codebase analysis.

The Explore agent analyzes the project automatically.

[Explore agent is analyzing the codebase...]

Analysis results:
- Language: Python 3.12
- Framework: FastAPI 0.115
- Database: PostgreSQL 16
- Architecture: Clean Architecture
- Core features:
  * User authentication
  * Data CRUD
  * API endpoint management

The agent automatically identifies the project’s structure, dependencies, and patterns.

Review the analysis results and approve document generation.

Generate documents from this analysis?
1. Proceed
2. Detailed review
3. Cancel

User: 1

If the analysis is accurate, choose “Proceed” to continue with document generation.

The manager-docs agent generates the documents from the analysis results.

[manager-docs agent is generating documents...]

Done! The following files were created:
- .moai/project/product.md
- .moai/project/structure.md
- .moai/project/tech.md

Each document covers a different aspect of the project.

Confirms that the development environment is properly configured.

The LSP server 'pyright' is installed.

Choose your next step:
1. Write a SPEC (/moai plan)
2. Review documents
3. Start a new session

Since the LSP server is installed, you can start development right away.

Generate the documents when first setting up the project.

> /moai project

This step only needs to be done once per project.

Once project docs exist, the AI understands the project.

> /moai plan "Implement user authentication"

Since the AI already knows the project’s tech stack and structure, it can generate a more accurate SPEC.

Info

/moai project typically needs to run only once or twice per project. There is no need to run it every time; re-run it only when the project structure has changed significantly.

flowchart TD
    Start["/moai project run"] --> Phase0["Phase 1: type detection"]
    Phase0 --> Phase05["Phase 2: deep interview
(new project)"]
    Phase0 --> Phase1["Phase 3: codebase analysis
(existing project)"]

    Phase1 --> Explore["Explore subagent
code analysis delegation"]
    Explore --> Phase2["Phase 5: user confirmation"]

    Phase05 --> Phase3["Phase 6: document generation"]
    Phase2 -->|Approve| Phase3

    Phase3 --> Docs["manager-docs subagent
document generation delegation"]
    Docs --> Audit["Phase 7: plan-auditor audit"]
    Audit --> Phase35["Phase 10: LSP check"]

    Phase35 --> DevOps["Agent(general-purpose) devops
LSP installation (optional)"]
    DevOps --> Phase4["Phase 14: done"]

You can still create a SPEC, but since the AI does not know the project’s tech stack or structure, it may make inaccurate technical judgments. Running /moai project first is always recommended.

/moai project operates locally only. Your code is not sent to external servers, and the generated documents are stored locally in the .moai/project/ directory.

Yes, monorepo structures are supported. Run it from the root directory and it analyzes the entire project structure.

Document generation proceeds even without an LSP server. However, code-quality diagnostics may be limited in the later /moai run phase. Phase 10 provides LSP installation guidance.

• Quick Start - Full workflow tutorial
• /moai plan - Next step: SPEC document creation
• /moai harness - Creating a project-specific harness
• SPEC-Based Development - Detailed SPEC methodology
• Subagent Catalog - Explore and manager-docs agent details