moai-workflow-project by modu-ai

---
name: moai-workflow-project
description: >
  Integrated project management system covering documentation, language initialization,
  template optimization, docs generation, and JIT document loading. Absorbed from
  moai-workflow-templates, moai-docs-generation, and moai-workflow-jit-docs.
license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Edit, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(uv:*), Bash(pip:*), Bash(ls:*), Bash(mkdir:*), Grep, Glob, WebFetch, WebSearch, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
user-invocable: false
metadata:
  version: "3.0.0"
  category: "workflow"
  status: "active"
  updated: "2026-04-25"
  modularized: "true"
  tags: "workflow, project, documentation, initialization, templates, boilerplate, scaffolding, jit-docs, docs-generation"
  aliases: "moai-workflow-project"
  related-skills: "moai-workflow-templates, moai-docs-generation, moai-workflow-jit-docs"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

# MoAI Extension: Triggers
triggers:
  keywords: ["project setup", "initialization", "project initialization", "project configuration", "project documentation", "multilingual", "language initialization", "template", "boilerplate", "scaffolding", "code template", "feedback template", "docs", "documentation", "API reference", "docs generation", "Sphinx", "MkDocs", "TypeDoc", "OpenAPI", "jit docs", "just in time docs", "project template", "GitHub issue", "template optimization", "how to", "implement", "best practices", "technology guide", "framework documentation"]
  phases: ["plan", "run", "sync"]
  agents: ["manager-project", "manager-docs", "builder-skill", "manager-spec", "expert-backend", "expert-frontend"]
---

# 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

<!-- moai:evolvable-start id="rationalizations" -->
## 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. |

<!-- moai:evolvable-end -->

<!-- moai:evolvable-start id="red-flags" -->
## 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)

<!-- moai:evolvable-end -->

<!-- moai:evolvable-start id="verification" -->
## 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

<!-- moai:evolvable-end -->

---

## 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

1. Identify template category: code boilerplate, feedback template, or project scaffold
2. Select template variant matching the project stack and language
3. Apply customization variables (project name, author, license, framework version)
4. Validate rendered output against schema or existing conventions
5. 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](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

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

Full generator configurations: [modules/docs-generation.md](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

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

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