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
lsoutput 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 syncartifacts: 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.