MoAI Workflow Project - Integrated Project Management System
Comprehensive project management system integrating documentation generation, multilingual support, and template optimization into a unified architecture with intelligent automation and Claude Code integration.
Scope: Consolidates documentation management, language initialization, and template optimization into a 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 generation with multilingual support
- Language Initialization: Detection, configuration, localization
- Template Optimization: Analysis with performance optimization
- Unified Interface: Single entry point for all capabilities
Key Features:
- Automatic project type detection and template selection
- Multilingual documentation (English, Korean, Japanese, Chinese)
- Intelligent template optimization with benchmarking
- SPEC-driven documentation updates
- Multi-format export (Markdown, HTML, PDF)
Supported Project Types: web applications, mobile applications, CLI tools, libraries, ML projects.
Implementation Guide
Module Architecture
Three capability areas:
- Documentation Management: template-based generation, project type detection, multilingual support, SPEC integration, multi-format export
- Language Initialization: automatic detection, configuration management, agent prompt localization, locale management
- Template Optimization: complexity analysis, performance optimization, backup/recovery, benchmarking
Core Workflows
Three workflows: project initialization, documentation generation from SPEC, template performance optimization. Each follows a 3-step pattern (configure → execute → review results).
See core workflow walkthroughs for detailed step-by-step procedures.
Language and Localization
Automatic Language Detection: analyzes file content, configuration files, system locale, and directory structure.
Multilingual Documentation: language-specific directories (e.g., docs/ko, docs/en), language negotiation, automatic redirection.
Agent Prompt Localization: language-specific instructions, cultural context, token cost optimization.
See language and localization detail for token cost analysis and locale configuration.
Template Optimization
Performance Analysis: file size, complexity, performance bottlenecks, optimization opportunities, resource usage, backup recommendations.
Optimization Techniques: whitespace reduction, structure optimization, complexity reduction, performance caching.
Configuration Management
Integrated configuration covers project metadata, language settings + costs, documentation status, template optimization results, module initialization states.
Language Settings: conversation_language (user-facing), agent_prompt_language (internal, often English for cost), documentation language (per language).
Updates trigger configuration file modifications, documentation structure updates, template localization.
See configuration schema and language fields for full field reference and supported language metadata.
Advanced Implementation
For advanced patterns (custom templates, performance caching, batch processing, integration workflows), see references/reference.md and references/examples.md.
Resources
Performance Metrics
| Operation |
Typical Duration |
| Complete documentation generation |
2-5 seconds |
| Language detection analysis |
~500 ms |
| Template optimization |
10-30 seconds |
| Configuration updates |
~100 ms |
Memory: base ~50MB, large projects +10-50MB, optimization cache 5-20MB.
File sizes: documentation 50-200KB per project, optimization backups match originals, configuration 5-10KB.
Works Well With
- moai-foundation-core: Core execution patterns and SPEC-driven workflows
- moai-foundation-cc: Claude Code integration and configuration
- moai-workflow-docs: Unified documentation management
- moai-workflow-templates: Template optimization strategies
- moai-library-nextra: 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
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).
Documentation Generation (absorbed from moai-docs-generation)
Technical docs generation using Sphinx, MkDocs, TypeDoc, OpenAPI, and Nextra. Covers project configuration discovery, how to integrate with existing docs sites, and best practices for keeping framework documentation and technology guide content current.
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
JIT Document Loading (absorbed from moai-workflow-jit-docs)
JIT docs (just in time docs) — on-demand documentation discovery and loading based on user intent and conversation context.
Primary Tools
- WebSearch/WebFetch (
, ): 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)
- WebSearch/WebFetch (official, version-matched library docs)
- WebSearch + WebFetch (latest online resources)
Token budget: 5000 tokens per JIT load. Summarize if source exceeds budget.
1---
2name: moai-workflow-project
3description: >
4 Integrated project management system covering documentation, language initialization,
5 template optimization, docs generation, and JIT document loading. Absorbed from
6 moai-workflow-templates, moai-docs-generation, and moai-workflow-jit-docs.
7
8when_to_use: >
9 Use for integrated project management: documentation scaffolding
10 (product/structure/tech.md), multilingual language initialization,
11 template and boilerplate optimization, docs generation (Sphinx, MkDocs,
12 TypeDoc, OpenAPI), and JIT document loading.
13
14license: Apache-2.0
15compatibility: Designed for Claude Code
16allowed-tools: Read, Write, Edit, Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(uv:*), Bash(pip:*), Bash(ls:*), Bash(mkdir:*), Grep, Glob, WebFetch, WebSearch
17user-invocable: false
18metadata:
19 source: https://skillmd.com/skills/modu-ai/moai-workflow-project
20 version: "3.0.0"
21 category: "workflow"
22 status: "active"
23 updated: "2026-04-25"
24 modularized: "true"
25 tags: "workflow, project, documentation, initialization, templates, boilerplate, scaffolding, jit-docs, docs-generation"
26 aliases: "moai-workflow-project"
27 related-skills: "moai-workflow-spec, moai-workflow-docs-claim-check"
28
29# MoAI Extension: Progressive Disclosure
30progressive_disclosure:
31 enabled: true
32 level1_tokens: 100
33 level2_tokens: 5000
34---
35
36# MoAI Workflow Project - Integrated Project Management System
37
38Comprehensive project management system integrating documentation generation, multilingual support, and template optimization into a unified architecture with intelligent automation and Claude Code integration.
39
40Scope: Consolidates documentation management, language initialization, and template optimization into a single cohesive system supporting complete project lifecycle from initialization to maintenance.
41
42Target: Claude Code agents for project setup, documentation generation, multilingual support, and performance optimization.
43
44---
45
46## Quick Reference
47
48Core Capabilities:
49
50- Documentation Management: Template-based generation with multilingual support
51- Language Initialization: Detection, configuration, localization
52- Template Optimization: Analysis with performance optimization
53- Unified Interface: Single entry point for all capabilities
54
55Key Features:
56
57- Automatic project type detection and template selection
58- Multilingual documentation (English, Korean, Japanese, Chinese)
59- Intelligent template optimization with benchmarking
60- SPEC-driven documentation updates
61- Multi-format export (Markdown, HTML, PDF)
62
63Supported Project Types: web applications, mobile applications, CLI tools, libraries, ML projects.
64
65---
66
67## Implementation Guide
68
69### Module Architecture
70
71Three capability areas:
72
73- Documentation Management: template-based generation, project type detection, multilingual support, SPEC integration, multi-format export
74- Language Initialization: automatic detection, configuration management, agent prompt localization, locale management
75- Template Optimization: complexity analysis, performance optimization, backup/recovery, benchmarking
76
77### Core Workflows
78
79Three workflows: project initialization, documentation generation from SPEC, template performance optimization. Each follows a 3-step pattern (configure → execute → review results).
80
81See [core workflow walkthroughs](references/workflows.md) for detailed step-by-step procedures.
82
83### Language and Localization
84
85Automatic Language Detection: analyzes file content, configuration files, system locale, and directory structure.
86
87Multilingual Documentation: language-specific directories (e.g., `docs/ko`, `docs/en`), language negotiation, automatic redirection.
88
89Agent Prompt Localization: language-specific instructions, cultural context, token cost optimization.
90
91See [language and localization detail](references/language-localization.md) for token cost analysis and locale configuration.
92
93### Template Optimization
94
95Performance Analysis: file size, complexity, performance bottlenecks, optimization opportunities, resource usage, backup recommendations.
96
97Optimization Techniques: whitespace reduction, structure optimization, complexity reduction, performance caching.
98
99### Configuration Management
100
101Integrated configuration covers project metadata, language settings + costs, documentation status, template optimization results, module initialization states.
102
103Language Settings: conversation_language (user-facing), agent_prompt_language (internal, often English for cost), documentation language (per language).
104
105Updates trigger configuration file modifications, documentation structure updates, template localization.
106
107See [configuration schema and language fields](references/configuration.md) for full field reference and supported language metadata.
108
109---
110
111## Advanced Implementation
112
113For advanced patterns (custom templates, performance caching, batch processing, integration workflows), see [references/reference.md](references/reference.md) and [references/examples.md](references/examples.md).
114
115---
116
117## Resources
118
119### Performance Metrics
120
121| Operation | Typical Duration |
122|-----------|------------------|
123| Complete documentation generation | 2-5 seconds |
124| Language detection analysis | ~500 ms |
125| Template optimization | 10-30 seconds |
126| Configuration updates | ~100 ms |
127
128Memory: base ~50MB, large projects +10-50MB, optimization cache 5-20MB.
129
130File sizes: documentation 50-200KB per project, optimization backups match originals, configuration 5-10KB.
131
132---
133
134## Works Well With
135
136- moai-foundation-core: Core execution patterns and SPEC-driven workflows
137- moai-foundation-cc: Claude Code integration and configuration
138- moai-workflow-docs: Unified documentation management
139- moai-workflow-templates: Template optimization strategies
140- moai-library-nextra: Documentation architecture
141
142<!-- moai:evolvable-start id="rationalizations" -->
143## Common Rationalizations
144
145| Rationalization | Reality |
146|---|---|
147| "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. |
148| "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. |
149| "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. |
150| "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. |
151| "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. |
152
153<!-- moai:evolvable-end -->
154
155<!-- moai:evolvable-start id="red-flags" -->
156## Red Flags
157
158- product.md references features that do not exist in the codebase
159- tech.md lists a framework version that differs from the actual dependency file
160- structure.md missing directories that exist on disk
161- codemaps/ directory is empty or missing while the project has 10+ source files
162- /moai project last ran more than 30 days ago (check file modification dates)
163
164<!-- moai:evolvable-end -->
165
166<!-- moai:evolvable-start id="verification" -->
167## Verification
168
169- [ ] product.md exists and describes the current product scope (compare with README)
170- [ ] tech.md lists dependencies that match the actual lock file (package.json, go.mod, etc.)
171- [ ] structure.md top-level directories match `ls` output of the project root
172- [ ] codemaps/ contains at least one codemap file per major package or module
173- [ ] All three docs updated within the current session or since last structural change
174- [ ] No placeholder text ("TODO", "TBD") remains in generated documents
175
176<!-- moai:evolvable-end -->
177
178---
179
180## Template Optimization (absorbed from moai-workflow-templates)
181
182Code boilerplates, feedback templates, scaffolding, and project template optimization.
183
184### Core Capabilities
185
186- Code template library: FastAPI, React, Vue, Next.js boilerplates
187- GitHub issue feedback templates: 6 types (bug, feature, question, docs, perf, security)
188- Project template optimization: size reduction, complexity analysis, smart merging
189- Template version management, backup discovery and restoration
190
191### Template Application Workflow
192
1931. Identify template category: code boilerplate, feedback template, or project scaffold
1942. Select template variant matching the project stack and language
1953. Apply customization variables (project name, author, license, framework version)
1964. Validate rendered output against schema or existing conventions
1975. Optionally run template optimizer to reduce redundancy
198
199### Template Optimization Process
200
201Analysis metrics: file size, complexity score, redundancy ratio, load performance.
202Optimization techniques: whitespace reduction, deduplication, structure simplification.
203Always create backup before applying optimization (`backup: true`).
204
205---
206
207## Documentation Generation (absorbed from moai-docs-generation)
208
209Technical docs generation using Sphinx, MkDocs, TypeDoc, OpenAPI, and Nextra. Covers project configuration discovery, how to integrate with existing docs sites, and best practices for keeping framework documentation and technology guide content current.
210
211### Supported Generators
212
213| Generator | Use Case | Primary Format |
214|-----------|----------|----------------|
215| Sphinx | Python projects, API docs | RST / Markdown |
216| MkDocs | General projects | Markdown |
217| TypeDoc | TypeScript libraries | TypeScript JSDoc |
218| OpenAPI / Swagger | REST APIs | YAML / JSON |
219| Nextra | Next.js docs sites | MDX |
220
221### Generation Workflow
222
2231. Detect project type and select appropriate generator
2242. Extract documentation sources: docstrings, JSDoc, OpenAPI specs, SPEC documents
2253. Apply project language and branding from `.moai/config/sections/language.yaml`
2264. Generate output in configured format (Markdown, HTML, PDF)
2275. Update `/moai sync` artifacts: README, CHANGELOG, API reference
228
229---
230
231## JIT Document Loading (absorbed from moai-workflow-jit-docs)
232
233JIT docs (just in time docs) — on-demand documentation discovery and loading based on user intent and conversation context.
234
235### Primary Tools
236
237- WebSearch/WebFetch (``, ``): Official library docs
238- WebFetch / WebSearch: Latest online documentation
239- Read, Grep, Glob: Local project documentation
240
241### Trigger Patterns
242
243- User asks specific technical questions about a library or framework
244- Technology keyword detected (library name, framework name, API name)
245- Domain expertise required (authentication, database, deployment)
246- Implementation guidance needed during run phase
247
248### Loading Priority
249
2501. Local project docs (`.moai/`, README, SPEC documents)
2512. WebSearch/WebFetch (official, version-matched library docs)
2523. WebSearch + WebFetch (latest online resources)
253
254Token budget: 5000 tokens per JIT load. Summarize if source exceeds budget.