MoAI Workflow Project - Integrated Project Management System

Purpose: Comprehensive project management system that integrates documentation generation, multilingual support, and template optimization into unified architecture with intelligent automation and Claude Code integration.

Scope: Consolidates documentation management, language initialization, and template optimization into single cohesive system supporting complete project lifecycle from initialization to maintenance.

Target: Claude Code agents for project setup, documentation generation, multilingual support, and performance optimization.

Quick Reference

Core Capabilities:

Documentation Management: Template-based documentation generation with multilingual support
Language Initialization: Language detection, configuration, and localization management
Template Optimization: Advanced template analysis and performance optimization
Unified Interface: Single entry point integrating all capabilities

Key Features:

Automatic project type detection and template selection
Multilingual documentation generation supporting English, Korean, Japanese, and Chinese
Intelligent template optimization with performance benchmarking
SPEC-driven documentation updates
Multi-format export including Markdown, HTML, and PDF

Supported Project Types:

Web applications
Mobile applications
Command-line interface tools
Libraries and packages
Machine learning projects

Implementation Guide

Module Architecture

Documentation Management Capabilities:

Template-based documentation generation
Project type detection for web, mobile, CLI, library, and ML projects
Multilingual support with localized content
SPEC data integration for automatic updates
Multi-format export capabilities

Language Initialization Capabilities:

Automatic language detection from project content
Comprehensive language configuration management
Agent prompt localization with cost optimization
Domain-specific language support
Locale management and cultural adaptation

Template Optimization Capabilities:

Advanced template analysis with complexity metrics
Performance optimization with size reduction
Intelligent backup and recovery system
Benchmarking and performance tracking
Automated optimization recommendations

Core Workflows

Complete Project Initialization Workflow:

Step 1: Initialize the project management system by specifying the project directory path

Step 2: Execute complete setup with the following configuration parameters:

Language setting: Specify the primary language code such as "en" for English or "ko" for Korean
User name: Provide the developer or team name for personalization
Domains: List the project domains such as backend, frontend, and mobile
Project type: Specify the project type such as web_application
Optimization enabled: Set to true to enable template optimization during initialization

Step 3: Review initialization results which include:

Language configuration with token cost analysis
Documentation structure creation status
Template analysis and optimization report
Multilingual documentation setup confirmation

Documentation Generation from SPEC Workflow:

Step 1: Prepare SPEC data with the following structure:

Identifier: Unique SPEC ID such as SPEC-001
Title: Feature or component title
Description: Brief description of the implementation
Requirements: List of specific requirements
Status: Current status such as Planned, In Progress, or Complete
Priority: Priority level such as High, Medium, or Low
API Endpoints: List of endpoint definitions including path, method, and description

Step 2: Generate comprehensive documentation from the SPEC data

Step 3: Review generated documentation which includes:

Feature documentation with requirements
API documentation with endpoint details
Updated project documentation files
Multilingual versions if configured

Template Performance Optimization Workflow:

Step 1: Analyze current templates to gather metrics

Step 2: Configure optimization options:

Backup first: Set to true to create backup before optimization
Apply size optimizations: Enable to reduce file sizes
Apply performance optimizations: Enable to improve loading times
Apply complexity optimizations: Enable to simplify template structures
Preserve functionality: Ensure all features remain intact

Step 3: Execute optimization and review results:

Size reduction percentage achieved
Performance improvement metrics
Backup creation confirmation
Detailed optimization report

Language and Localization

Automatic Language Detection Process:

The system analyzes the project for language indicators using the following methods:

File content analysis examining comments and strings
Configuration file examination for locale settings
System locale detection
Directory structure patterns

Multilingual Documentation Structure:

When creating documentation for multiple languages, the system generates:

Language-specific documentation directories such as docs/ko for Korean and docs/en for English
Language negotiation configuration
Automatic redirection setup between language versions

Agent Prompt Localization:

The localization system provides:

Language-specific instructions for agents
Cultural context adaptations
Token cost optimization recommendations for multilingual prompts

Template Optimization

Performance Analysis Process:

Template analysis provides the following metrics:

File size and complexity measurements
Performance bottleneck identification
Optimization opportunity scoring
Resource usage patterns
Backup recommendations

Intelligent Optimization Process:

The optimization system applies the following techniques:

Whitespace and redundancy reduction
Template structure optimization
Complexity reduction techniques
Performance caching improvements

Configuration Management

Integrated Configuration Status:

The project status includes:

Project metadata and type classification
Language configuration and associated costs
Documentation completion status
Template optimization results
Module initialization states

Language Settings Update Process:

When updating language settings, configure the following parameters:

Conversation language: The language for user-facing responses
Agent prompt language: The language for internal agent instructions, often kept as English for cost optimization
Documentation language: The language for generated documentation

Updates trigger the following automatic changes:

Configuration file modifications
Documentation structure updates
Template localization adjustments

Advanced Implementation

For advanced patterns including custom template development, performance optimization strategies, and integration workflows, see reference.md which covers:

Custom Templates: Creating project-type-specific documentation templates
Performance Caching: Implementing template caching for improved performance
Batch Processing: Efficiently processing multiple templates simultaneously
Integration Workflows: Complete project lifecycle and multilingual management

Resources

Configuration Structure

Project Configuration Fields:

Project name: The display name for the project
Project type: Classification such as web_application, mobile_application, or cli_tool
Initialization timestamp: When the project was initialized
Language configuration: Conversation, agent prompt, and documentation language settings
System version: The project management system version
Initialization status: Whether all modules are fully initialized

Language Configuration Fields for Each Supported Language:

Name: Display name in English
Native name: Display name in the native language
Code: Language code such as en, ko, ja, or zh
Locale: System locale string
Agent prompt language: Whether to use English or localized prompts
Token cost impact: Percentage increase in token usage for non-English prompts

Performance Metrics

Documentation Generation Performance:

Complete documentation generation typically completes within 2 to 5 seconds
Language detection analysis completes within approximately 500 milliseconds
Template optimization duration varies from 10 to 30 seconds depending on project size
Configuration updates complete within approximately 100 milliseconds

Memory Usage Characteristics:

Base system requires approximately 50MB RAM
Large projects may require an additional 10 to 50MB depending on template count
Optimization cache uses approximately 5 to 20MB for performance improvements

File Size Impact:

Documentation files range from 50 to 200KB per project
Optimization backups match the size of original templates
Configuration files range from 5 to 10KB for complete project setup

Works Well With

moai-foundation-core: Core execution patterns and SPEC-driven development workflows
moai-foundation-cc: Claude Code integration and configuration
moai-workflow-docs: Unified documentation management
moai-workflow-templates: Template optimization strategies
moai-library-nextra: Advanced documentation architecture

Common Rationalizations

Rationalization	Reality
"project docs are a one-time setup, no need to keep them current"	Stale product.md and tech.md mislead every SPEC written against them. They are living documents.
"structure.md will stay accurate since the codebase does not change much"	Every PR that adds a directory invalidates structure.md. Sync on every /moai project invocation.
"I know the tech stack, I do not need tech.md"	tech.md is not for you. It is for every agent that consults the project context before acting.
"codemaps take too long to generate"	codemaps are the only artifact that gives agents file-level awareness without reading every file. The cost pays for itself.
"I will write project docs after the feature is done"	Post-hoc docs capture what was built, not what was intended. Pre-feature docs guide the build.

Red Flags

product.md references features that do not exist in the codebase
tech.md lists a framework version that differs from the actual dependency file
structure.md missing directories that exist on disk
codemaps/ directory is empty or missing while the project has 10+ source files
/moai project last ran more than 30 days ago (check file modification dates)

Verification

product.md exists and describes the current product scope (compare with README)
tech.md lists dependencies that match the actual lock file (package.json, go.mod, etc.)
structure.md top-level directories match ls output of the project root
codemaps/ contains at least one codemap file per major package or module
All three docs updated within the current session or since last structural change
No placeholder text ("TODO", "TBD") remains in generated documents

Template Optimization (absorbed from moai-workflow-templates)

Code boilerplates, feedback templates, scaffolding, and project template optimization.

Core Capabilities

Code template library: FastAPI, React, Vue, Next.js boilerplates
GitHub issue feedback templates: 6 types (bug, feature, question, docs, perf, security)
Project template optimization: size reduction, complexity analysis, smart merging
Template version management, backup discovery and restoration

Template Application Workflow

Identify template category: code boilerplate, feedback template, or project scaffold
Select template variant matching the project stack and language
Apply customization variables (project name, author, license, framework version)
Validate rendered output against schema or existing conventions
Optionally run template optimizer to reduce redundancy

Template Optimization Process

Analysis metrics: file size, complexity score, redundancy ratio, load performance. Optimization techniques: whitespace reduction, deduplication, structure simplification. Always create backup before applying optimization (backup: true).

Full template library and optimization patterns: modules/templates.md

Documentation Generation (absorbed from moai-docs-generation)

Technical documentation generation using Sphinx, MkDocs, TypeDoc, OpenAPI, and Nextra.

Supported Generators

Generator	Use Case	Primary Format
Sphinx	Python projects, API docs	RST / Markdown
MkDocs	General projects	Markdown
TypeDoc	TypeScript libraries	TypeScript JSDoc
OpenAPI / Swagger	REST APIs	YAML / JSON
Nextra	Next.js docs sites	MDX

Generation Workflow

Detect project type and select appropriate generator
Extract documentation sources: docstrings, JSDoc, OpenAPI specs, SPEC documents
Apply project language and branding from .moai/config/sections/language.yaml
Generate output in configured format (Markdown, HTML, PDF)
Update /moai sync artifacts: README, CHANGELOG, API reference

Full generator configurations: modules/docs-generation.md

JIT Document Loading (absorbed from moai-workflow-jit-docs)

On-demand documentation discovery and loading based on user intent and conversation context.

Primary Tools

Context7 MCP (mcp__context7__resolve-library-id, mcp__context7__get-library-docs): Official library docs
WebFetch / WebSearch: Latest online documentation
Read, Grep, Glob: Local project documentation

Trigger Patterns

User asks specific technical questions about a library or framework
Technology keyword detected (library name, framework name, API name)
Domain expertise required (authentication, database, deployment)
Implementation guidance needed during run phase

Loading Priority

Local project docs (.moai/, README, SPEC documents)
Context7 MCP (official, version-matched library docs)
WebSearch + WebFetch (latest online resources)

Token budget: 5000 tokens per JIT load. Summarize if source exceeds budget.

moai-workflow-project