moai-adk 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of moai-adk might be problematic. Click here for more details.
- moai_adk/cli/commands/backup.py +25 -1
- moai_adk/cli/commands/doctor.py +30 -4
- moai_adk/cli/commands/init.py +19 -0
- moai_adk/cli/commands/status.py +28 -0
- moai_adk/cli/commands/update.py +43 -3
- moai_adk/core/project/phase_executor.py +2 -1
- moai_adk/templates/.claude/commands/alfred/3-sync.md +23 -6
- moai_adk/templates/CLAUDE.md +362 -226
- {moai_adk-0.5.2.dist-info → moai_adk-0.5.4.dist-info}/METADATA +2 -2
- {moai_adk-0.5.2.dist-info → moai_adk-0.5.4.dist-info}/RECORD +13 -13
- {moai_adk-0.5.2.dist-info → moai_adk-0.5.4.dist-info}/WHEEL +0 -0
- {moai_adk-0.5.2.dist-info → moai_adk-0.5.4.dist-info}/entry_points.txt +0 -0
- {moai_adk-0.5.2.dist-info → moai_adk-0.5.4.dist-info}/licenses/LICENSE +0 -0
moai_adk/cli/commands/backup.py
CHANGED
|
@@ -1,4 +1,28 @@
|
|
|
1
|
-
"""Backup command
|
|
1
|
+
"""Backup command
|
|
2
|
+
|
|
3
|
+
Create a backup of the current project including:
|
|
4
|
+
- .claude/ (entire directory)
|
|
5
|
+
- .moai/ (excluding specs and reports)
|
|
6
|
+
- CLAUDE.md
|
|
7
|
+
|
|
8
|
+
Backup location: .moai-backups/YYYYMMDD-HHMMSS/
|
|
9
|
+
|
|
10
|
+
## Skill Invocation Guide (English-Only)
|
|
11
|
+
|
|
12
|
+
### Related Skills
|
|
13
|
+
- **moai-foundation-git**: For Git workflow and backup management
|
|
14
|
+
- Trigger: Before creating critical backups, review Git state
|
|
15
|
+
- Invocation: `Skill("moai-foundation-git")` for backup naming conventions
|
|
16
|
+
|
|
17
|
+
### When to Invoke Skills in Related Workflows
|
|
18
|
+
1. **Before backup creation**:
|
|
19
|
+
- Run `Skill("moai-foundation-git")` to document current Git branch state
|
|
20
|
+
- Tag backup with feature branch name for easier recovery
|
|
21
|
+
|
|
22
|
+
2. **After restoration from backup**:
|
|
23
|
+
- Verify with `Skill("moai-foundation-tags")` that TAGs are intact
|
|
24
|
+
- Run `Skill("moai-foundation-trust")` to validate toolchain
|
|
25
|
+
"""
|
|
2
26
|
from pathlib import Path
|
|
3
27
|
|
|
4
28
|
import click
|
moai_adk/cli/commands/doctor.py
CHANGED
|
@@ -8,6 +8,30 @@ System diagnostics command:
|
|
|
8
8
|
- Validate project structure
|
|
9
9
|
- Inspect language-specific tool chains
|
|
10
10
|
- Diagnose slash command loading issues (--check-commands)
|
|
11
|
+
|
|
12
|
+
## Skill Invocation Guide (English-Only)
|
|
13
|
+
|
|
14
|
+
### Related Skills
|
|
15
|
+
- **moai-foundation-langs**: For language toolchain verification and detection
|
|
16
|
+
- Trigger: Use `--verbose` or `--fix` flag to inspect language-specific tools
|
|
17
|
+
- Invocation: `Skill("moai-foundation-langs")` for detailed language stack analysis
|
|
18
|
+
|
|
19
|
+
- **moai-foundation-trust**: For TRUST 5-principles verification after fixing tools
|
|
20
|
+
- Trigger: After running doctor with `--fix` to validate improvements
|
|
21
|
+
- Invocation: `Skill("moai-foundation-trust")` to verify code quality toolchain
|
|
22
|
+
|
|
23
|
+
### When to Invoke Skills in Related Workflows
|
|
24
|
+
1. **After doctor diagnosis**:
|
|
25
|
+
- Run `Skill("moai-foundation-trust")` to validate that all TRUST tools are properly configured
|
|
26
|
+
- Run `Skill("moai-foundation-langs")` to confirm language-specific toolchains
|
|
27
|
+
|
|
28
|
+
2. **When tools are missing** (`--fix` flag):
|
|
29
|
+
- Use suggested fixes from doctor command
|
|
30
|
+
- Follow up with `Skill("moai-foundation-langs")` to validate corrections
|
|
31
|
+
|
|
32
|
+
3. **Debugging slash command issues** (`--check-commands`):
|
|
33
|
+
- Run `Skill("moai-cc-commands")` if commands fail to load
|
|
34
|
+
- Check `.claude/commands/` directory structure and permissions
|
|
11
35
|
"""
|
|
12
36
|
|
|
13
37
|
import json
|
|
@@ -168,11 +192,13 @@ def _suggest_fixes(tools: dict[str, bool], language: str | None) -> None:
|
|
|
168
192
|
|
|
169
193
|
def _get_install_command(tool: str, language: str | None) -> str:
|
|
170
194
|
"""Return the install command for a given tool (helper)"""
|
|
171
|
-
# Common tools
|
|
195
|
+
# Common tools with preferred package managers
|
|
172
196
|
install_commands = {
|
|
173
|
-
|
|
174
|
-
"
|
|
175
|
-
"
|
|
197
|
+
# Python tools (prefer uv)
|
|
198
|
+
"pytest": "uv pip install pytest",
|
|
199
|
+
"mypy": "uv pip install mypy",
|
|
200
|
+
"ruff": "uv pip install ruff",
|
|
201
|
+
# JavaScript tools
|
|
176
202
|
"vitest": "npm install -D vitest",
|
|
177
203
|
"biome": "npm install -D @biomejs/biome",
|
|
178
204
|
"eslint": "npm install -D eslint",
|
moai_adk/cli/commands/init.py
CHANGED
|
@@ -6,6 +6,25 @@
|
|
|
6
6
|
Project initialization command (interactive/non-interactive):
|
|
7
7
|
- Interactive Mode: Ask user for project settings
|
|
8
8
|
- Non-Interactive Mode: Use defaults or CLI options
|
|
9
|
+
|
|
10
|
+
## Skill Invocation Guide (English-Only)
|
|
11
|
+
|
|
12
|
+
### Related Skills
|
|
13
|
+
- **moai-foundation-langs**: For language detection and stack configuration
|
|
14
|
+
- Trigger: When language parameter is not specified (auto-detection)
|
|
15
|
+
- Invocation: Called implicitly during project initialization for language matrix detection
|
|
16
|
+
|
|
17
|
+
### When to Invoke Skills in Related Workflows
|
|
18
|
+
1. **After project initialization**:
|
|
19
|
+
- Run `Skill("moai-foundation-trust")` to verify project structure and toolchain
|
|
20
|
+
- Run `Skill("moai-foundation-langs")` to validate detected language stack
|
|
21
|
+
|
|
22
|
+
2. **Before first SPEC creation**:
|
|
23
|
+
- Use `Skill("moai-alfred-language-detection")` to confirm language selection
|
|
24
|
+
|
|
25
|
+
3. **Project reinitialization** (`--force`):
|
|
26
|
+
- Skills automatically adapt to new project structure
|
|
27
|
+
- No manual intervention required
|
|
9
28
|
"""
|
|
10
29
|
|
|
11
30
|
import json
|
moai_adk/cli/commands/status.py
CHANGED
|
@@ -5,6 +5,34 @@ Project status display:
|
|
|
5
5
|
- Read project information from config.json
|
|
6
6
|
- Show the number of SPEC documents
|
|
7
7
|
- Summarize the Git status
|
|
8
|
+
|
|
9
|
+
## Skill Invocation Guide (English-Only)
|
|
10
|
+
|
|
11
|
+
### Related Skills
|
|
12
|
+
- **moai-foundation-tags**: For detailed TAG inventory and orphan detection
|
|
13
|
+
- Trigger: When you need to verify TAG chain integrity beyond what status shows
|
|
14
|
+
- Invocation: `Skill("moai-foundation-tags")` to scan full project for orphan TAGs
|
|
15
|
+
|
|
16
|
+
- **moai-foundation-trust**: For comprehensive TRUST 5-principles verification
|
|
17
|
+
- Trigger: After status shows SPECs exist, to validate code quality
|
|
18
|
+
- Invocation: `Skill("moai-foundation-trust")` to verify all quality gates
|
|
19
|
+
|
|
20
|
+
- **moai-foundation-git**: For detailed Git workflow information
|
|
21
|
+
- Trigger: When Git status shows "Modified" and you need workflow guidance
|
|
22
|
+
- Invocation: `Skill("moai-foundation-git")` for GitFlow automation details
|
|
23
|
+
|
|
24
|
+
### When to Invoke Skills in Related Workflows
|
|
25
|
+
1. **Before starting new SPEC creation**:
|
|
26
|
+
- Run `Skill("moai-foundation-tags")` to verify no orphan TAGs exist from previous work
|
|
27
|
+
- Check the SPEC count from status command
|
|
28
|
+
|
|
29
|
+
2. **After modifications to code/docs**:
|
|
30
|
+
- If status shows "Modified", run `Skill("moai-foundation-git")` for commit strategy
|
|
31
|
+
- Follow up with `Skill("moai-foundation-trust")` to validate code quality
|
|
32
|
+
|
|
33
|
+
3. **Periodic health checks**:
|
|
34
|
+
- Run status command regularly
|
|
35
|
+
- When SPEC count grows, verify with `Skill("moai-foundation-tags")` and `Skill("moai-foundation-trust")`
|
|
8
36
|
"""
|
|
9
37
|
|
|
10
38
|
import json
|
moai_adk/cli/commands/update.py
CHANGED
|
@@ -1,4 +1,36 @@
|
|
|
1
|
-
"""Update command
|
|
1
|
+
"""Update command
|
|
2
|
+
|
|
3
|
+
Update MoAI-ADK to the latest version available on PyPI.
|
|
4
|
+
Includes:
|
|
5
|
+
- Version checking from PyPI
|
|
6
|
+
- Template and configuration updates
|
|
7
|
+
- Backward compatibility validation
|
|
8
|
+
|
|
9
|
+
## Skill Invocation Guide (English-Only)
|
|
10
|
+
|
|
11
|
+
### Related Skills
|
|
12
|
+
- **moai-foundation-trust**: For post-update validation
|
|
13
|
+
- Trigger: After updating MoAI-ADK version
|
|
14
|
+
- Invocation: `Skill("moai-foundation-trust")` to verify all toolchains still work
|
|
15
|
+
|
|
16
|
+
- **moai-foundation-langs**: For language detection after update
|
|
17
|
+
- Trigger: After updating, confirm language stack is intact
|
|
18
|
+
- Invocation: `Skill("moai-foundation-langs")` to re-detect and validate language configuration
|
|
19
|
+
|
|
20
|
+
### When to Invoke Skills in Related Workflows
|
|
21
|
+
1. **After successful update**:
|
|
22
|
+
- Run `Skill("moai-foundation-trust")` to validate all TRUST 5 gates
|
|
23
|
+
- Run `Skill("moai-foundation-langs")` to confirm language toolchain still works
|
|
24
|
+
- Run project doctor command for full system validation
|
|
25
|
+
|
|
26
|
+
2. **Before updating**:
|
|
27
|
+
- Create backup with `python -m moai_adk backup`
|
|
28
|
+
- Run `Skill("moai-foundation-tags")` to document current TAG state
|
|
29
|
+
|
|
30
|
+
3. **If update fails**:
|
|
31
|
+
- Use backup to restore previous state
|
|
32
|
+
- Debug with `python -m moai_adk doctor --verbose`
|
|
33
|
+
"""
|
|
2
34
|
from __future__ import annotations
|
|
3
35
|
|
|
4
36
|
import json
|
|
@@ -344,8 +376,16 @@ def update(path: str, force: bool, check: bool) -> None:
|
|
|
344
376
|
console.print("\n[green]✓ Update complete![/green]")
|
|
345
377
|
if latest_version and version.parse(current_version) < version.parse(latest_version):
|
|
346
378
|
console.print(
|
|
347
|
-
"[yellow]⚠ Python package still on older version.
|
|
348
|
-
|
|
379
|
+
"[yellow]⚠ Python package still on older version.[/yellow]"
|
|
380
|
+
)
|
|
381
|
+
console.print(
|
|
382
|
+
"[cyan]Upgrade options:[/cyan]"
|
|
383
|
+
)
|
|
384
|
+
console.print(
|
|
385
|
+
" 1. uv tool (recommended): uv tool upgrade moai-adk"
|
|
386
|
+
)
|
|
387
|
+
console.print(
|
|
388
|
+
" 2. pip (legacy): pip install --upgrade moai-adk"
|
|
349
389
|
)
|
|
350
390
|
console.print("\n[cyan]ℹ️ Next step: Run /alfred:0-project update to optimize template changes[/cyan]")
|
|
351
391
|
|
|
@@ -15,6 +15,7 @@ import subprocess
|
|
|
15
15
|
from collections.abc import Callable
|
|
16
16
|
from datetime import datetime
|
|
17
17
|
from pathlib import Path
|
|
18
|
+
from typing import Any
|
|
18
19
|
|
|
19
20
|
from rich.console import Console
|
|
20
21
|
|
|
@@ -166,7 +167,7 @@ class PhaseExecutor:
|
|
|
166
167
|
def execute_configuration_phase(
|
|
167
168
|
self,
|
|
168
169
|
project_path: Path,
|
|
169
|
-
config: dict[str, str | bool],
|
|
170
|
+
config: dict[str, str | bool | dict[Any, Any]],
|
|
170
171
|
progress_callback: ProgressCallback | None = None,
|
|
171
172
|
) -> list[str]:
|
|
172
173
|
"""Phase 4: generate configuration.
|
|
@@ -99,7 +99,9 @@ Users can run the command as follows:
|
|
|
99
99
|
|
|
100
100
|
Analyze project status to determine synchronization scope, develop a systematic synchronization plan, and receive user confirmation.
|
|
101
101
|
|
|
102
|
-
**The
|
|
102
|
+
**The tag-agent performs comprehensive TAG verification (full project scope), and doc-syncer analyzes Git changes and establishes synchronization plan.**
|
|
103
|
+
|
|
104
|
+
⚠️ **Important**: Tag-agent must verify the ENTIRE PROJECT for TAG orphans, not just changed files. Full-project scope is MANDATORY.
|
|
103
105
|
|
|
104
106
|
### 🔍 TAG chain navigation (optional)
|
|
105
107
|
|
|
@@ -129,12 +131,27 @@ Invoking the Task tool (Explore agent):
|
|
|
129
131
|
**In STEP 1, call doc-syncer and tag-agent using the Task tool**:
|
|
130
132
|
|
|
131
133
|
```
|
|
132
|
-
1. Tag-agent call (TAG verification):
|
|
134
|
+
1. Tag-agent call (TAG verification - FULL PROJECT SCOPE):
|
|
133
135
|
- subagent_type: "tag-agent"
|
|
134
|
-
- description: "Verify TAG system"
|
|
135
|
-
- prompt: "Please
|
|
136
|
-
|
|
137
|
-
|
|
136
|
+
- description: "Verify TAG system across entire project"
|
|
137
|
+
- prompt: "Please perform a COMPREHENSIVE TAG system verification across the ENTIRE PROJECT.
|
|
138
|
+
|
|
139
|
+
**Required scope**: Scan all source files, not just changed files.
|
|
140
|
+
|
|
141
|
+
**Verification items**:
|
|
142
|
+
1. @SPEC TAGs in .moai/specs/ directory
|
|
143
|
+
2. @TEST TAGs in tests/ directory
|
|
144
|
+
3. @CODE TAGs in src/ directory
|
|
145
|
+
4. @DOC TAGs in docs/ directory
|
|
146
|
+
|
|
147
|
+
**Orphan detection** (MANDATORY):
|
|
148
|
+
- Detect @CODE TAGs without matching @SPEC
|
|
149
|
+
- Detect @SPEC TAGs without matching @CODE
|
|
150
|
+
- Detect @TEST TAGs without matching @SPEC
|
|
151
|
+
- Detect @DOC TAGs without matching @SPEC/@CODE
|
|
152
|
+
|
|
153
|
+
**Output format**: Provide complete list of orphan TAGs with locations.
|
|
154
|
+
|
|
138
155
|
(Optional) Explore results: $EXPLORE_RESULTS"
|
|
139
156
|
|
|
140
157
|
2. doc-syncer call (synchronization plan):
|
moai_adk/templates/CLAUDE.md
CHANGED
|
@@ -97,44 +97,12 @@ The **Explore** agent excels at navigating large codebases.
|
|
|
97
97
|
- 🔍 Dependency relationships must be analyzed
|
|
98
98
|
- 🔍 You're planning a refactor and need impact analysis
|
|
99
99
|
|
|
100
|
-
**Usage
|
|
101
|
-
|
|
102
|
-
```python
|
|
103
|
-
# 1. Deep code analysis
|
|
104
|
-
Task(
|
|
105
|
-
subagent_type="Explore",
|
|
106
|
-
description="Analyze the full implementation of TemplateProcessor",
|
|
107
|
-
prompt="""Please analyze the TemplateProcessor class implementation:
|
|
108
|
-
- Class definition location
|
|
109
|
-
- Key method implementations
|
|
110
|
-
- Dependent classes/modules
|
|
111
|
-
- Related tests
|
|
112
|
-
thoroughness level: very thorough"""
|
|
113
|
-
)
|
|
114
|
-
|
|
115
|
-
# 2. Domain-specific search (inside commands)
|
|
116
|
-
Task(
|
|
117
|
-
subagent_type="Explore",
|
|
118
|
-
description="Find files related to the AUTH domain",
|
|
119
|
-
prompt="""Find every file related to the AUTH domain:
|
|
120
|
-
- SPEC documents, tests, implementation (src), documentation
|
|
121
|
-
thoroughness level: medium"""
|
|
122
|
-
)
|
|
123
|
-
|
|
124
|
-
# 3. Natural language questions (auto-delegated by Alfred)
|
|
125
|
-
User: "Where is JWT authentication implemented in this project?"
|
|
126
|
-
→ Alfred automatically delegates to Explore
|
|
127
|
-
→ Explore returns the relevant file list
|
|
128
|
-
→ Alfred reads only the necessary files
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
**thoroughness levels** (declare explicitly inside the prompt text):
|
|
132
|
-
|
|
133
|
-
**thoroughness levels** (declare explicitly inside the prompt text):
|
|
100
|
+
**Usage**: Use `Task(subagent_type="Explore", ...)` for deep codebase analysis. Declare `thoroughness: quick|medium|very thorough` in the prompt.
|
|
134
101
|
|
|
135
|
-
|
|
136
|
-
-
|
|
137
|
-
-
|
|
102
|
+
**Examples**:
|
|
103
|
+
- Deep analysis: "Analyze TemplateProcessor class and its dependencies" (thoroughness: very thorough)
|
|
104
|
+
- Domain search: "Find all AUTH-related files in SPEC/tests/src/docs" (thoroughness: medium)
|
|
105
|
+
- Natural language: "Where is JWT authentication implemented?" → Alfred auto-delegates
|
|
138
106
|
|
|
139
107
|
### Claude Skills (55 packs)
|
|
140
108
|
|
|
@@ -152,41 +120,11 @@ Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive D
|
|
|
152
120
|
| Claude Code Ops | 1 | Session management |
|
|
153
121
|
| **Total** | **55** | Complete knowledge capsule library |
|
|
154
122
|
|
|
155
|
-
### Foundation Tier (6)
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
| `moai-foundation-tags` | TAG inventory & orphan detection | `/alfred:3-sync` |
|
|
161
|
-
| `moai-foundation-specs` | SPEC metadata policy and versioning | `/alfred:1-plan` |
|
|
162
|
-
| `moai-foundation-ears` | EARS templates and requirement phrasing | `/alfred:1-plan` |
|
|
163
|
-
| `moai-foundation-git` | GitFlow automation & PR policy | Plan/Run/Sync |
|
|
164
|
-
| `moai-foundation-langs` | Language detection & Skill preload | SessionStart, `/alfred:2-run` |
|
|
165
|
-
|
|
166
|
-
### Essentials Tier (4)
|
|
167
|
-
|
|
168
|
-
| Skill | Purpose | Auto-load |
|
|
169
|
-
| -------------------------- | --------------------------------------------- | ------------------------------------------ |
|
|
170
|
-
| `moai-essentials-debug` | Failure diagnosis & reproduction checklist | Auto when `/alfred:2-run` detects failures |
|
|
171
|
-
| `moai-essentials-perf` | Performance analysis & profiling strategies | On demand |
|
|
172
|
-
| `moai-essentials-refactor` | Refactoring patterns & code-smell remediation | `/alfred:2-run` |
|
|
173
|
-
| `moai-essentials-review` | Code review checklist & quality feedback | `/alfred:3-sync` |
|
|
174
|
-
|
|
175
|
-
### Alfred Tier (11) — Internal workflow orchestration
|
|
176
|
-
|
|
177
|
-
| Skill | Purpose | Auto-load |
|
|
178
|
-
| -------------------------------------- | ------------------------------------ | --------------------------------- |
|
|
179
|
-
| `moai-alfred-code-reviewer` | Automated code quality review | `/alfred:3-sync` |
|
|
180
|
-
| `moai-alfred-debugger-pro` | Advanced debugging strategies | `/alfred:2-run` failures |
|
|
181
|
-
| `moai-alfred-ears-authoring` | EARS syntax validation & templates | `/alfred:1-plan` |
|
|
182
|
-
| `moai-alfred-git-workflow` | GitFlow automation patterns | Plan/Run/Sync |
|
|
183
|
-
| `moai-alfred-language-detection` | Stack detection & Skill preload | SessionStart, `/alfred:0-project` |
|
|
184
|
-
| `moai-alfred-performance-optimizer` | Performance profiling & optimization | On demand |
|
|
185
|
-
| `moai-alfred-refactoring-coach` | Refactoring guidance & patterns | `/alfred:2-run` |
|
|
186
|
-
| `moai-alfred-spec-metadata-validation` | SPEC metadata policy enforcement | `/alfred:1-plan` |
|
|
187
|
-
| `moai-alfred-tag-scanning` | TAG integrity & orphan detection | `/alfred:3-sync` |
|
|
188
|
-
| `moai-alfred-trust-validation` | TRUST 5 principle verification | All phases |
|
|
189
|
-
| `moai-alfred-interactive-questions` | Interactive user surveys & menus | On demand |
|
|
123
|
+
### Foundation Tier (6): `moai-foundation-trust`, `moai-foundation-tags`, `moai-foundation-specs`, `moai-foundation-ears`, `moai-foundation-git`, `moai-foundation-langs` (TRUST/TAG/SPEC/EARS/Git/language detection)
|
|
124
|
+
|
|
125
|
+
### Essentials Tier (4): `moai-essentials-debug`, `moai-essentials-perf`, `moai-essentials-refactor`, `moai-essentials-review` (Debug/Perf/Refactor/Review workflows)
|
|
126
|
+
|
|
127
|
+
### Alfred Tier (11): `moai-alfred-code-reviewer`, `moai-alfred-debugger-pro`, `moai-alfred-ears-authoring`, `moai-alfred-git-workflow`, `moai-alfred-language-detection`, `moai-alfred-performance-optimizer`, `moai-alfred-refactoring-coach`, `moai-alfred-spec-metadata-validation`, `moai-alfred-tag-scanning`, `moai-alfred-trust-validation`, `moai-alfred-interactive-questions` (code review, debugging, EARS, Git, language detection, performance, refactoring, metadata, TAG scanning, trust validation, interactive questions)
|
|
190
128
|
|
|
191
129
|
### Domain Tier (10) — `moai-domain-backend`, `web-api`, `frontend`, `mobile-app`, `security`, `devops`, `database`, `data-science`, `ml`, `cli-tool`
|
|
192
130
|
|
|
@@ -196,6 +134,340 @@ Alfred relies on 55 Claude Skills grouped by tier. Skills load via Progressive D
|
|
|
196
134
|
|
|
197
135
|
Skills keep the core knowledge lightweight while allowing Alfred to assemble the right expertise for each request.
|
|
198
136
|
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 🎯 Skill Invocation Rules (English-Only)
|
|
140
|
+
|
|
141
|
+
### ✅ Mandatory Skill Explicit Invocation
|
|
142
|
+
|
|
143
|
+
**CRITICAL**: When you receive a request containing the following keywords, you **MUST** explicitly invoke the corresponding Skill using `Skill("skill-name")` syntax. DO NOT use direct tools (Read, Grep, Bash) as substitutes.
|
|
144
|
+
|
|
145
|
+
| User Request Keywords | Skill to Invoke | Invocation Syntax | Prohibited Actions |
|
|
146
|
+
|---|---|---|---|
|
|
147
|
+
| **TRUST validation**, code quality check, quality gate, coverage check, test coverage, linting, type safety | `moai-foundation-trust` | `Skill("moai-foundation-trust")` | ❌ Direct ruff/mypy/pytest execution |
|
|
148
|
+
| **TAG validation**, tag check, orphan detection, TAG scan, TAG chain verification | `moai-foundation-tags` | `Skill("moai-foundation-tags")` | ❌ Direct rg search without Skill context |
|
|
149
|
+
| **SPEC validation**, spec check, SPEC metadata, YAML frontmatter validation | `moai-foundation-specs` | `Skill("moai-foundation-specs")` | ❌ Direct YAML reading |
|
|
150
|
+
| **EARS syntax**, requirement authoring, requirement specification, ubiquitous language | `moai-foundation-ears` | `Skill("moai-foundation-ears")` | ❌ Generic requirement templates |
|
|
151
|
+
| **Git workflow**, branch management, PR policy, GitFlow automation, commit strategy | `moai-foundation-git` | `Skill("moai-foundation-git")` | ❌ Direct git commands without workflow context |
|
|
152
|
+
| **Language detection**, stack detection, language matrix, language identification | `moai-foundation-langs` | `Skill("moai-foundation-langs")` | ❌ Hardcoded file extension checks |
|
|
153
|
+
| **Debugging**, error analysis, bug fix, troubleshooting, stack trace analysis | `moai-essentials-debug` | `Skill("moai-essentials-debug")` | ❌ Generic error handling |
|
|
154
|
+
| **Refactoring**, code improvement, design patterns, code smell detection | `moai-essentials-refactor` | `Skill("moai-essentials-refactor")` | ❌ Direct code modifications |
|
|
155
|
+
| **Performance optimization**, profiling, bottleneck detection, performance tuning | `moai-essentials-perf` | `Skill("moai-essentials-perf")` | ❌ Guesswork-based optimization |
|
|
156
|
+
| **Code review**, quality review, SOLID principles, best practices | `moai-essentials-review` | `Skill("moai-essentials-review")` | ❌ Generic code review |
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
### 📦 Skill Tier Architecture (55 Skills Total)
|
|
161
|
+
|
|
162
|
+
Alfred's 55 Skills are organized into 6 tiers, each with specific responsibilities and auto-trigger conditions:
|
|
163
|
+
|
|
164
|
+
| **Tier** | **Count** | **Purpose** | **Auto-Trigger Conditions** | **Examples** |
|
|
165
|
+
|---|---|---|---|---|
|
|
166
|
+
| **Foundation** | 6 | Core TRUST/TAG/SPEC/EARS/Git/Language principles | Keyword detection in user request | `moai-foundation-trust`, `moai-foundation-tags`, `moai-foundation-specs`, `moai-foundation-ears`, `moai-foundation-git`, `moai-foundation-langs` |
|
|
167
|
+
| **Essentials** | 4 | Debug/Perf/Refactor/Review workflows | Error detection, refactor triggers, performance concerns | `moai-essentials-debug`, `moai-essentials-perf`, `moai-essentials-refactor`, `moai-essentials-review` |
|
|
168
|
+
| **Alfred** | 11 | Workflow orchestration (SPEC authoring, TDD, sync, Git) | Command execution (`/alfred:*`), agent requests | `moai-alfred-ears-authoring`, `moai-alfred-tag-scanning`, `moai-alfred-spec-metadata-validation`, `moai-alfred-trust-validation`, `moai-alfred-interactive-questions`, and 6 more |
|
|
169
|
+
| **Domain** | 10 | Specialized domain expertise | Domain-specific keywords | `moai-domain-backend`, `moai-domain-frontend`, `moai-domain-web-api`, `moai-domain-database`, `moai-domain-security`, and 5 more |
|
|
170
|
+
| **Language** | 23 | Language-specific best practices | File extension detection (`.py`, `.ts`, `.go`, `.rs`, etc.) | Python, TypeScript, Go, Rust, Java, Kotlin, Swift, Dart, C/C++, C#, Scala, Ruby, PHP, JavaScript, SQL, Shell, and more |
|
|
171
|
+
| **Ops** | 1 | Claude Code session settings | Session start/configuration | `moai-cc-settings`, `moai-cc-memory`, `moai-cc-hooks`, `moai-cc-commands`, `moai-cc-agents`, `moai-cc-skills`, `moai-cc-mcp-plugins` |
|
|
172
|
+
| **Total** | **55** | Complete knowledge capsule library | Progressive Disclosure (metadata → content → supporting) | — |
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
### 📋 Progressive Disclosure Pattern
|
|
177
|
+
|
|
178
|
+
Skills load dynamically using the Progressive Disclosure principle:
|
|
179
|
+
|
|
180
|
+
1. **Metadata Phase**: Skill name, description, and trigger keywords are available at session start (~50 bytes each).
|
|
181
|
+
2. **Content Phase**: Full `SKILL.md` content loads when an agent or user explicitly invokes `Skill("skill-name")`.
|
|
182
|
+
3. **Supporting Phase**: Templates, examples, and tools load only when required by the Skill's workflow (JIT loading).
|
|
183
|
+
|
|
184
|
+
**Benefits**:
|
|
185
|
+
- Lightweight session startup (55 skills @ 50 bytes = ~3 KB metadata)
|
|
186
|
+
- Fast context switching (only loaded skills consume tokens)
|
|
187
|
+
- Extensible architecture (new Skills integrate without session overhead)
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
### 💡 Example Workflows (English-Only Documentation)
|
|
192
|
+
|
|
193
|
+
#### Example 1: TRUST 5 Validation Workflow
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
User: "Check code quality for {{codebase_language}}"
|
|
197
|
+
|
|
198
|
+
Claude: I'll validate code quality using TRUST 5-principles.
|
|
199
|
+
|
|
200
|
+
Skill("moai-foundation-trust")
|
|
201
|
+
|
|
202
|
+
[After Skill loads]
|
|
203
|
+
|
|
204
|
+
**TRUST 5 Validation Results**:
|
|
205
|
+
|
|
206
|
+
1. **T**est First: pytest coverage ≥ 85%
|
|
207
|
+
2. **R**eadable: ruff lint, complexity ≤ 10
|
|
208
|
+
3. **U**nified: mypy strict typing
|
|
209
|
+
4. **S**ecured: trivy scan, input validation
|
|
210
|
+
5. **T**rackable: @TAG coverage in code
|
|
211
|
+
|
|
212
|
+
Verification complete. All gates passed ✅
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
#### Example 2: TAG Orphan Detection Workflow
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
User: "Verify TAG system integrity"
|
|
219
|
+
|
|
220
|
+
Claude: I'll scan the entire project for TAG chain integrity.
|
|
221
|
+
|
|
222
|
+
Skill("moai-foundation-tags")
|
|
223
|
+
|
|
224
|
+
[After Skill loads]
|
|
225
|
+
|
|
226
|
+
**TAG Inventory**:
|
|
227
|
+
- @SPEC TAGs: 12 found
|
|
228
|
+
- @TEST TAGs: 12 found
|
|
229
|
+
- @CODE TAGs: 12 found
|
|
230
|
+
- @DOC TAGs: 11 found
|
|
231
|
+
|
|
232
|
+
**Orphan Detection**:
|
|
233
|
+
- @CODE without @SPEC: 0 ❌ (all valid)
|
|
234
|
+
- @SPEC without @CODE: 1 ⚠️ (VERIFICATION-001)
|
|
235
|
+
- @TEST without @SPEC: 0 ✅
|
|
236
|
+
- @DOC without @SPEC/@CODE: 1 ⚠️ (CLAUDE-001 - template doc)
|
|
237
|
+
|
|
238
|
+
**Chain Status**: 99% complete (1 SPEC ready for CODE, 1 template doc expected)
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
#### Example 3: EARS Requirement Authoring Workflow
|
|
242
|
+
|
|
243
|
+
```
|
|
244
|
+
User: "Create SPEC-AUTH-002 for multi-factor authentication"
|
|
245
|
+
|
|
246
|
+
Claude: I'll guide you through EARS-based requirement authoring.
|
|
247
|
+
|
|
248
|
+
Skill("moai-foundation-ears")
|
|
249
|
+
|
|
250
|
+
[After Skill loads]
|
|
251
|
+
|
|
252
|
+
**EARS Requirement Template**:
|
|
253
|
+
|
|
254
|
+
Ubiquitous: The system shall support multi-factor authentication (MFA).
|
|
255
|
+
|
|
256
|
+
Event-driven: WHEN a user provides valid credentials, THEN the system requests an MFA verification code.
|
|
257
|
+
|
|
258
|
+
State: IF the user has MFA enabled, THEN authentication must complete MFA verification.
|
|
259
|
+
|
|
260
|
+
Optional: IF the user is on a trusted device, THEN MFA can be skipped (configurable).
|
|
261
|
+
|
|
262
|
+
Constraints: MFA verification codes expire after 5 minutes. Maximum 3 retry attempts per session.
|
|
263
|
+
|
|
264
|
+
[Generates SPEC-AUTH-002.md with YAML frontmatter]
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
#### Example 4: Debugging with Error Context Workflow
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
User: "TypeError: Cannot read property 'name' of undefined at src/services/user.ts:42"
|
|
271
|
+
|
|
272
|
+
Claude: I'll analyze the error and diagnose the root cause.
|
|
273
|
+
|
|
274
|
+
Skill("moai-essentials-debug")
|
|
275
|
+
|
|
276
|
+
[After Skill loads]
|
|
277
|
+
|
|
278
|
+
**Error Analysis**:
|
|
279
|
+
- **Error Type**: TypeError (null/undefined access)
|
|
280
|
+
- **Location**: src/services/user.ts:42
|
|
281
|
+
- **Root Cause**: Missing null check for user object returned from fetchUser()
|
|
282
|
+
- **Related SPEC**: @SPEC:USER-003
|
|
283
|
+
- **Related Test**: @TEST:USER-003 (edge case missing)
|
|
284
|
+
|
|
285
|
+
**Recommended Fix**:
|
|
286
|
+
```{{codebase_language}}
|
|
287
|
+
// Before
|
|
288
|
+
const userName = user.name;
|
|
289
|
+
|
|
290
|
+
// After
|
|
291
|
+
if (!user) {
|
|
292
|
+
throw new NotFoundError('User not found');
|
|
293
|
+
}
|
|
294
|
+
const userName = user.name;
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
[Provides fix-forward guidance with edge case handling]
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
### ✅ When to Invoke Skills Explicitly
|
|
303
|
+
|
|
304
|
+
Use explicit Skill invocation when:
|
|
305
|
+
|
|
306
|
+
1. **User mentions any keyword** from the Mandatory Skill table above
|
|
307
|
+
2. **Ambiguous request** requires standardized best practices
|
|
308
|
+
3. **Quality verification** is needed (TRUST, TAG, SPEC, etc.)
|
|
309
|
+
4. **Architecture decisions** require domain expertise
|
|
310
|
+
5. **Error analysis** requires structured debugging workflow
|
|
311
|
+
|
|
312
|
+
### ❌ When NOT to Invoke Skills
|
|
313
|
+
|
|
314
|
+
You can skip Skill invocation when:
|
|
315
|
+
|
|
316
|
+
- User has already provided specific, complete instructions
|
|
317
|
+
- Task follows standard conventions with no ambiguity
|
|
318
|
+
- Technical constraints allow only one valid approach
|
|
319
|
+
- User explicitly states "just implement it" (already decided)
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
### Example: Correct Skill Usage
|
|
324
|
+
|
|
325
|
+
#### ❌ **Incorrect Response** (No Skill Invocation)
|
|
326
|
+
|
|
327
|
+
```
|
|
328
|
+
User: "Check code quality"
|
|
329
|
+
|
|
330
|
+
Claude: [Direct tool usage]
|
|
331
|
+
- Bash(ruff check src/)
|
|
332
|
+
- Bash(mypy src/)
|
|
333
|
+
- Read .moai/config.json
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
**Problem**: Bypasses standardized TRUST 5-principles checklist and misses quality context.
|
|
337
|
+
|
|
338
|
+
#### ✅ **Correct Response** (Skill Invocation)
|
|
339
|
+
|
|
340
|
+
```
|
|
341
|
+
User: "Check code quality"
|
|
342
|
+
|
|
343
|
+
Claude: I'll validate code quality using TRUST 5-principles.
|
|
344
|
+
|
|
345
|
+
Skill("moai-foundation-trust")
|
|
346
|
+
|
|
347
|
+
[After Skill loads]
|
|
348
|
+
1. Test First: pytest coverage ≥85%
|
|
349
|
+
2. Readable: ruff lint
|
|
350
|
+
3. Unified: mypy strict
|
|
351
|
+
4. Secured: trivy scan
|
|
352
|
+
5. Trackable: TAG validation
|
|
353
|
+
|
|
354
|
+
Let me verify each principle...
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
**Benefits**:
|
|
358
|
+
- ✅ Standardized workflow across all projects
|
|
359
|
+
- ✅ Consistent quality criteria based on latest TRUST 5 specification
|
|
360
|
+
- ✅ Up-to-date tool versions and configurations
|
|
361
|
+
- ✅ Language-specific adaptations ({{codebase_language}} toolchain)
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## 🎯 Interactive Question Rules
|
|
366
|
+
|
|
367
|
+
### Mandatory AskUserQuestion Usage
|
|
368
|
+
|
|
369
|
+
**IMPORTANT**: When the user needs to make a **choice** or **decision**, you **MUST** use AskUserQuestion. DO NOT make assumptions or implement directly.
|
|
370
|
+
|
|
371
|
+
| Situation Type | Examples | Invocation | Required |
|
|
372
|
+
|---------------|----------|------------|----------|
|
|
373
|
+
| **Multiple valid approaches exist** | Database choice (PostgreSQL vs MongoDB), state management library (Redux vs Zustand), test framework selection | `AskUserQuestion(...)` | ✅ Required |
|
|
374
|
+
| **Architecture/design decisions** | Microservices vs monolithic, client-side vs server-side rendering, authentication method (JWT vs OAuth) | `AskUserQuestion(...)` | ✅ Required |
|
|
375
|
+
| **Ambiguous or high-level requirements** | "Add a dashboard", "Optimize performance", "Add multi-language support" | `AskUserQuestion(...)` | ✅ Required |
|
|
376
|
+
| **Requests affecting existing components** | Refactoring scope, backward compatibility, migration strategy | `AskUserQuestion(...)` | ✅ Required |
|
|
377
|
+
| **User experience/business logic decisions** | UI layout, data display method, workflow order | `AskUserQuestion(...)` | ✅ Required |
|
|
378
|
+
|
|
379
|
+
### Optional AskUserQuestion Usage
|
|
380
|
+
|
|
381
|
+
You can proceed without AskUserQuestion in the following situations:
|
|
382
|
+
|
|
383
|
+
- ✅ User has already provided clear instructions
|
|
384
|
+
- ✅ Standard conventions or best practices are obvious
|
|
385
|
+
- ✅ Technical constraints allow only one approach
|
|
386
|
+
- ✅ User explicitly states "just implement it, I've already decided"
|
|
387
|
+
|
|
388
|
+
### Example: Correct AskUserQuestion Usage
|
|
389
|
+
|
|
390
|
+
#### ❌ **Incorrect Response** (Making assumptions)
|
|
391
|
+
|
|
392
|
+
```
|
|
393
|
+
User: "Add a dashboard page"
|
|
394
|
+
|
|
395
|
+
Claude: [Proceeding without asking]
|
|
396
|
+
- Tech: React + TypeScript
|
|
397
|
+
- Layout: Left sidebar + main content
|
|
398
|
+
- Chart library: Recharts
|
|
399
|
+
- Data source: Direct REST API calls
|
|
400
|
+
|
|
401
|
+
Starting implementation...
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
**Problem**: High risk of rework due to not understanding actual user intent.
|
|
405
|
+
|
|
406
|
+
#### ✅ **Correct Response** (Asking questions)
|
|
407
|
+
|
|
408
|
+
```
|
|
409
|
+
User: "Add a dashboard page"
|
|
410
|
+
|
|
411
|
+
Claude: I'll need to clarify a few decisions for the dashboard implementation.
|
|
412
|
+
|
|
413
|
+
AskUserQuestion(...)
|
|
414
|
+
|
|
415
|
+
[Example questions]
|
|
416
|
+
- "Data source?" → [REST API | GraphQL | Local state]
|
|
417
|
+
- "Primary chart type?" → [Time series | Category comparison | Distribution]
|
|
418
|
+
- "Real-time updates needed?" → [Yes | No | Every 10 seconds]
|
|
419
|
+
- "Access restrictions?" → [Admin only | Logged-in users | Public]
|
|
420
|
+
|
|
421
|
+
[After user responses]
|
|
422
|
+
Confirmed selections:
|
|
423
|
+
- Data: REST API
|
|
424
|
+
- Charts: Time series
|
|
425
|
+
- Real-time: No
|
|
426
|
+
- Access: Logged-in users
|
|
427
|
+
|
|
428
|
+
Now implementing based on these requirements...
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
**Benefits**: Clear intent understanding, minimized rework, accurate implementation.
|
|
432
|
+
|
|
433
|
+
### Best Practices for AskUserQuestion
|
|
434
|
+
|
|
435
|
+
1. **Limit to 3-5 questions**
|
|
436
|
+
- ✅ "Choose from 3 mutually exclusive options"
|
|
437
|
+
- ❌ "10+ options" (user fatigue)
|
|
438
|
+
|
|
439
|
+
2. **Options must be specific**
|
|
440
|
+
- ✅ "PostgreSQL (ACID, JSON support)", "MongoDB (horizontal scaling, flexible schema)"
|
|
441
|
+
- ❌ "Database 1", "Database 2"
|
|
442
|
+
|
|
443
|
+
3. **Always include "Other" option**
|
|
444
|
+
- User's choice may not be listed
|
|
445
|
+
- "Other" allows custom input
|
|
446
|
+
|
|
447
|
+
4. **Summary step after selection**
|
|
448
|
+
- Display user selections summary
|
|
449
|
+
- "Proceed with these choices?" final confirmation
|
|
450
|
+
|
|
451
|
+
5. **Integrate with Context Engineering**
|
|
452
|
+
- Analyze existing code/SPEC before AskUserQuestion
|
|
453
|
+
- Provide context like "Your project currently uses X"
|
|
454
|
+
|
|
455
|
+
### When NOT to Use AskUserQuestion
|
|
456
|
+
|
|
457
|
+
❌ When user has already given specific instructions:
|
|
458
|
+
```
|
|
459
|
+
User: "Implement state management using Zustand"
|
|
460
|
+
→ AskUserQuestion unnecessary (already decided)
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
❌ When only one technical choice exists:
|
|
464
|
+
```
|
|
465
|
+
User: "Improve type safety in TypeScript"
|
|
466
|
+
→ AskUserQuestion unnecessary (type system is fixed)
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
199
471
|
### Agent Collaboration Principles
|
|
200
472
|
|
|
201
473
|
- **Command precedence**: Command instructions outrank agent guidelines; follow the command if conflicts occur.
|
|
@@ -217,22 +489,6 @@ Skills keep the core knowledge lightweight while allowing Alfred to assemble the
|
|
|
217
489
|
- Record any manual model switch in the task notes (who, why, expected benefit).
|
|
218
490
|
- Combine both models when needed: e.g., Sonnet plans a refactor, Haiku formats and validates the resulting docs.
|
|
219
491
|
|
|
220
|
-
### Alfred Command Execution Pattern (Shared)
|
|
221
|
-
|
|
222
|
-
Alfred commands follow a three-phase loop, with an optional bootstrap stage for `/alfred:0-project`.
|
|
223
|
-
|
|
224
|
-
- **Phase 0 — Bootstrap (optional)**
|
|
225
|
-
Capture project metadata, create `.moai/config.json` and project docs, detect languages, and stage the recommended Skill packs.
|
|
226
|
-
|
|
227
|
-
- **Phase 1 — Analyze & Plan**
|
|
228
|
-
Understand scope, constraints, and desired outputs; review existing context (files, specs, tests); outline the execution plan and surface risks.
|
|
229
|
-
|
|
230
|
-
- **Phase 2 — Execute**
|
|
231
|
-
Run the approved steps in order, log progress in the task thread, escalate blockers immediately with mitigation options, and record decisions.
|
|
232
|
-
|
|
233
|
-
- **Phase 3 — Sync & Handoff**
|
|
234
|
-
Update docs, TAG inventory, and reports; verify quality gates; summarize outcomes; and suggest the next command or manual follow-up.
|
|
235
|
-
|
|
236
492
|
### Alfred's Next-Step Suggestion Principles
|
|
237
493
|
|
|
238
494
|
#### Pre-suggestion Checklist
|
|
@@ -277,16 +533,7 @@ Before suggesting the next step, always verify:
|
|
|
277
533
|
|
|
278
534
|
#### Suggestion Priorities
|
|
279
535
|
|
|
280
|
-
1. Resolve production blockers.
|
|
281
|
-
2. Restore failing tests or pipelines.
|
|
282
|
-
3. Close gaps against the SPEC.
|
|
283
|
-
4. Improve developer experience or automation.
|
|
284
|
-
|
|
285
|
-
#### Status Commands
|
|
286
|
-
|
|
287
|
-
- `/alfred status`: Summary of current phase and active agents.
|
|
288
|
-
- `/alfred queue`: Pending actions with owners.
|
|
289
|
-
- `/alfred blockers`: Known blockers and mitigation status.
|
|
536
|
+
1. Resolve production blockers → 2. Restore failing tests → 3. Close gaps against SPEC → 4. Improve DX/automation.
|
|
290
537
|
|
|
291
538
|
### Error Message Standard (Shared)
|
|
292
539
|
|
|
@@ -381,42 +628,13 @@ Claude Code now features an **Interactive Question Tool** powered by the `moai-a
|
|
|
381
628
|
|
|
382
629
|
### How It Works
|
|
383
630
|
|
|
384
|
-
When you provide a high-level request, Alfred
|
|
631
|
+
When you provide a high-level request, Alfred invokes `moai-alfred-interactive-questions` to clarify via structured TUI menus:
|
|
385
632
|
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
[QUESTION 1] How should the completion page be implemented?
|
|
392
|
-
┌─────────────────────────────────────────────────────┐
|
|
393
|
-
│ ▶ Create a new public page │ ← arrow keys to select
|
|
394
|
-
│ Modify existing page structure │
|
|
395
|
-
│ Use environment-based gating │
|
|
396
|
-
│ │
|
|
397
|
-
│ (press ↑↓ to navigate, enter to confirm) │
|
|
398
|
-
└─────────────────────────────────────────────────────┘
|
|
399
|
-
↓
|
|
400
|
-
[QUESTION 2] Who should see the completion page?
|
|
401
|
-
┌─────────────────────────────────────────────────────┐
|
|
402
|
-
│ Only participants (authenticated users) │
|
|
403
|
-
│ ▶ All visitors (public) │
|
|
404
|
-
│ Based on time window │
|
|
405
|
-
│ │
|
|
406
|
-
│ (press ↑↓ to navigate, enter to confirm) │
|
|
407
|
-
└─────────────────────────────────────────────────────┘
|
|
408
|
-
↓
|
|
409
|
-
[REVIEW] Summary of your selections
|
|
410
|
-
┌─────────────────────────────────────────────────────┐
|
|
411
|
-
│ ✓ Implementation: New public page │
|
|
412
|
-
│ ✓ User experience: All visitors (public) │
|
|
413
|
-
│ │
|
|
414
|
-
│ Ready to submit? │
|
|
415
|
-
│ [Submit answers] [← Go back] │
|
|
416
|
-
└─────────────────────────────────────────────────────┘
|
|
417
|
-
↓
|
|
418
|
-
Execution with confirmed specifications
|
|
419
|
-
```
|
|
633
|
+
1. **Analyze** codebase & context
|
|
634
|
+
2. **Present** concrete options (3-5 per question)
|
|
635
|
+
3. **Capture** user selections via arrow keys + enter
|
|
636
|
+
4. **Review** summary before submission
|
|
637
|
+
5. **Execute** with confirmed intent
|
|
420
638
|
|
|
421
639
|
**Where it's used**:
|
|
422
640
|
|
|
@@ -477,103 +695,21 @@ Execution with confirmed specifications
|
|
|
477
695
|
- Reference existing code patterns ("like the auth flow in `/src/auth.ts`")
|
|
478
696
|
- Mention constraints or non-negotiables upfront
|
|
479
697
|
|
|
480
|
-
### Example:
|
|
481
|
-
|
|
482
|
-
**User Request**: "Competition is over. Add a completion page."
|
|
483
|
-
|
|
484
|
-
#### Step 1: Code Analysis
|
|
485
|
-
|
|
486
|
-
Alfred scans the codebase and detects:
|
|
487
|
-
|
|
488
|
-
- Existing `/end` page (auth required, shows results)
|
|
489
|
-
- Need for clarification on scope and user behavior
|
|
490
|
-
|
|
491
|
-
#### Step 2: Interactive Survey (moai-alfred-interactive-questions activated)
|
|
492
|
-
|
|
493
|
-
```text
|
|
494
|
-
────────────────────────────────────────────────────────────────
|
|
495
|
-
ALFRED: How should the completion page be implemented?
|
|
496
|
-
────────────────────────────────────────────────────────────────
|
|
497
|
-
|
|
498
|
-
┌─ IMPLEMENTATION APPROACH ────────────────────────────────────┐
|
|
499
|
-
│ │
|
|
500
|
-
│ ▶ Create a new public page (/competition-closed) │
|
|
501
|
-
│ • Unguarded route, visible to all visitors │
|
|
502
|
-
│ • No authentication required │
|
|
503
|
-
│ │
|
|
504
|
-
│ Modify existing /end page with conditional logic │
|
|
505
|
-
│ • Check if competition is active before showing results │
|
|
506
|
-
│ │
|
|
507
|
-
│ Use environment-based gating │
|
|
508
|
-
│ • Set NEXT_PUBLIC_COMPETITION_CLOSED=true │
|
|
509
|
-
│ • Redirect all traffic to completion screen │
|
|
510
|
-
│ │
|
|
511
|
-
│ Use ↑↓ arrows to navigate, ENTER to select │
|
|
512
|
-
│ Type custom answer or press ESC to cancel │
|
|
513
|
-
└──────────────────────────────────────────────────────────────┘
|
|
514
|
-
|
|
515
|
-
→ Selection: Create a new public page (/competition-closed)
|
|
516
|
-
```
|
|
517
|
-
|
|
518
|
-
```text
|
|
519
|
-
────────────────────────────────────────────────────────────────
|
|
520
|
-
ALFRED: For logged-in participants accessing the new page?
|
|
521
|
-
────────────────────────────────────────────────────────────────
|
|
522
|
-
|
|
523
|
-
┌─ USER BEHAVIOR ──────────────────────────────────────────────┐
|
|
524
|
-
│ │
|
|
525
|
-
│ Show submission history │
|
|
526
|
-
│ • Redirect to /end page, display results & timeline │
|
|
527
|
-
│ │
|
|
528
|
-
│ ▶ Show simple completion message only │
|
|
529
|
-
│ • Display "Competition concluded" notice │
|
|
530
|
-
│ • No historical data shown │
|
|
531
|
-
│ │
|
|
532
|
-
│ Custom behavior based on user role │
|
|
533
|
-
│ • Different experience per role type │
|
|
534
|
-
│ │
|
|
535
|
-
│ Use ↑↓ arrows to navigate, ENTER to select │
|
|
536
|
-
│ Type custom answer or press ESC to cancel │
|
|
537
|
-
└──────────────────────────────────────────────────────────────┘
|
|
538
|
-
|
|
539
|
-
→ Selection: Show simple completion message only
|
|
540
|
-
```
|
|
541
|
-
|
|
542
|
-
#### Step 3: Review & Confirmation
|
|
543
|
-
|
|
544
|
-
```text
|
|
545
|
-
────────────────────────────────────────────────────────────────
|
|
546
|
-
ALFRED: Review your answers
|
|
547
|
-
────────────────────────────────────────────────────────────────
|
|
548
|
-
|
|
549
|
-
┌─ SUMMARY ────────────────────────────────────────────────────┐
|
|
550
|
-
│ │
|
|
551
|
-
│ ✓ Implementation approach: │
|
|
552
|
-
│ Create a new public page (/competition-closed) │
|
|
553
|
-
│ │
|
|
554
|
-
│ ✓ User behavior: │
|
|
555
|
-
│ Show simple completion message only │
|
|
556
|
-
│ │
|
|
557
|
-
│ Ready to submit these answers? │
|
|
558
|
-
│ │
|
|
559
|
-
│ [✓ Submit answers] [← Go back and modify] │
|
|
560
|
-
│ │
|
|
561
|
-
└──────────────────────────────────────────────────────────────┘
|
|
562
|
-
|
|
563
|
-
→ Action: Submit answers (enter)
|
|
564
|
-
```
|
|
698
|
+
### Example: Using AskUserQuestion in Practice
|
|
565
699
|
|
|
566
|
-
|
|
700
|
+
When Alfred detects ambiguity (e.g., "Add a completion page"), it invokes `AskUserQuestion` to gather precise intent:
|
|
567
701
|
|
|
568
|
-
|
|
702
|
+
**Typical flow**:
|
|
703
|
+
1. Alfred analyzes existing code (detects `/end` page, auth patterns)
|
|
704
|
+
2. Calls `AskUserQuestion` with 2-3 structured questions
|
|
705
|
+
3. User selects via arrow keys (✓ confirms → next question)
|
|
706
|
+
4. Alfred summarizes selections & executes with SPEC → TDD → Sync
|
|
569
707
|
|
|
570
|
-
|
|
571
|
-
-
|
|
572
|
-
-
|
|
573
|
-
- ✅ Generates with SPEC → TDD → Sync flow
|
|
708
|
+
**Example questions**:
|
|
709
|
+
- "Implementation approach?" → [New page | Modify existing | Environment gating]
|
|
710
|
+
- "User visibility?" → [Auth required | Public | Based on time]
|
|
574
711
|
|
|
575
|
-
**Result**:
|
|
576
|
-
No guessing. No ambiguity. Direct execution. 🎯
|
|
712
|
+
**Result**: Precise, intentional implementation matching confirmed specifications. ✅
|
|
577
713
|
|
|
578
714
|
## Commands · Sub-agents · Skills · Hooks
|
|
579
715
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: moai-adk
|
|
3
|
-
Version: 0.5.
|
|
3
|
+
Version: 0.5.4
|
|
4
4
|
Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
|
|
5
5
|
Project-URL: Homepage, https://github.com/modu-ai/moai-adk
|
|
6
6
|
Project-URL: Repository, https://github.com/modu-ai/moai-adk
|
|
@@ -1247,7 +1247,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
|
|
|
1247
1247
|
| **v0.4.7** | 📖 Korean language optimization + SPEC-First principle documentation | 2025-10-22 |
|
|
1248
1248
|
| **v0.4.6** | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
|
|
1249
1249
|
|
|
1250
|
-
> 📦 **Install Now**: `
|
|
1250
|
+
> 📦 **Install Now**: `uv tool install moai-adk==0.4.11` or `pip install moai-adk==0.4.11`
|
|
1251
1251
|
|
|
1252
1252
|
---
|
|
1253
1253
|
|
|
@@ -3,11 +3,11 @@ moai_adk/__main__.py,sha256=vDQDlH6B9Pvp0dZBopngY1ctWubDdkB7uRyDFEjBxmM,2424
|
|
|
3
3
|
moai_adk/cli/__init__.py,sha256=tidIaJnd4Pje_5QYRq7OvRRst4T3kaPlkw5QcPQ3l1Y,135
|
|
4
4
|
moai_adk/cli/main.py,sha256=mHACHi27AP2N7fg7zhzOo1tlF1Jrlw1_AcbxMfpGLVE,306
|
|
5
5
|
moai_adk/cli/commands/__init__.py,sha256=TrAIWcJRGXh1mY8itSzWm-W0nnybzQIFOuh6oksKWO0,680
|
|
6
|
-
moai_adk/cli/commands/backup.py,sha256=
|
|
7
|
-
moai_adk/cli/commands/doctor.py,sha256=
|
|
8
|
-
moai_adk/cli/commands/init.py,sha256=
|
|
9
|
-
moai_adk/cli/commands/status.py,sha256=
|
|
10
|
-
moai_adk/cli/commands/update.py,sha256=
|
|
6
|
+
moai_adk/cli/commands/backup.py,sha256=jKdm9P55RIIdaBLhXYDQdbn2ThQDVDrc9_No48uHB7A,2493
|
|
7
|
+
moai_adk/cli/commands/doctor.py,sha256=keyU2PwwiUGuQViQVDlXKCqLmi6F1JDW3JEOOY64wgk,9831
|
|
8
|
+
moai_adk/cli/commands/init.py,sha256=yQZlW5hjBGdMXlvtlbWqaFHPIfFQZyhlW3EBMLNF_BI,11372
|
|
9
|
+
moai_adk/cli/commands/status.py,sha256=VgShdUwlDOc0Bl5gVx7wHSKn-z2YLy6BLdVPflpIKX8,3645
|
|
10
|
+
moai_adk/cli/commands/update.py,sha256=qfKP7PsKe73rn37ENMe6i2aXStZ3HBM-uS9TWlWEZ98,14746
|
|
11
11
|
moai_adk/cli/prompts/__init__.py,sha256=a4_ctS4KEvGtmM9j7z8XIlMkpftohjVb9woUwZu38gE,136
|
|
12
12
|
moai_adk/cli/prompts/init_prompts.py,sha256=OZ_T-b4XfkyXQsKXTwLcDYwmLbaf0k5oZfbi_asTH9M,5226
|
|
13
13
|
moai_adk/core/__init__.py,sha256=1sJO-PHEKF1NmYjeOPPPzn_HRgYln3CKlCpUH4E2Jrs,129
|
|
@@ -25,7 +25,7 @@ moai_adk/core/project/backup_utils.py,sha256=-zEXIhGsM-MdX1voUIpKxLlR57Y-lqLEZSi
|
|
|
25
25
|
moai_adk/core/project/checker.py,sha256=B94mGLHDZkjQnFDgV8sknJDms5oIiHeyKcgxWI87-f8,9523
|
|
26
26
|
moai_adk/core/project/detector.py,sha256=ADVg36yvyqJEPQVNc_x9iInF9dzi7YZqqXfDq2XL17Q,4230
|
|
27
27
|
moai_adk/core/project/initializer.py,sha256=cR4I7bvoREOQDd0QNee676iOh6Vf3REy2601YnRVTYc,6636
|
|
28
|
-
moai_adk/core/project/phase_executor.py,sha256=
|
|
28
|
+
moai_adk/core/project/phase_executor.py,sha256=_g04sO_4tRACg8FPDeQNj7SqqJCObgiHYBej7UCU684,10259
|
|
29
29
|
moai_adk/core/project/validator.py,sha256=gH9ywTMQTwqtqBVrMWj5_bPYFrVzjHuFoU4QdeVa1O4,5756
|
|
30
30
|
moai_adk/core/quality/__init__.py,sha256=_uNsbThBLmVLWZCPmEgfFyQqJx3tdef9jhkP9QoHuJY,222
|
|
31
31
|
moai_adk/core/quality/trust_checker.py,sha256=CN067AiublAH46IBAKEV_I-8Wc0bNaR2dMnMf9n5oBg,15198
|
|
@@ -38,7 +38,7 @@ moai_adk/core/template/languages.py,sha256=V0wLcxCIOve9Q_0_NhrHGQevSIN_MB612GwrO
|
|
|
38
38
|
moai_adk/core/template/merger.py,sha256=ZV8_U1HZJ3bfAtgyNmSxgj8KdTMt4eUnUG6kVVRT7bE,6909
|
|
39
39
|
moai_adk/core/template/processor.py,sha256=W4M3BNrlfA0dHRwvPWIkJmJwhkNDglXaNzsYBoVTSnQ,17019
|
|
40
40
|
moai_adk/templates/.gitignore,sha256=6VNKResdDpyaii3cmJA4pOLwK2PhYARIWkUODYtKyxg,310
|
|
41
|
-
moai_adk/templates/CLAUDE.md,sha256=
|
|
41
|
+
moai_adk/templates/CLAUDE.md,sha256=rMOoWb-kwXh_xqOnyFSM2d0-O4Bs3PLttKUOSe7YNjo,43428
|
|
42
42
|
moai_adk/templates/__init__.py,sha256=6MV1gCB7PLZMiL4gaD_dZSKxtcQyo45MMTuN8fVdchA,104
|
|
43
43
|
moai_adk/templates/.claude/settings.json,sha256=SwjID_m0XWmHT12lqkhJXL1Sh30zAr9_tk4drQ9x9K8,3149
|
|
44
44
|
moai_adk/templates/.claude/agents/alfred/cc-manager.md,sha256=nyiNtcSqvLKK8Mp88hhTFBqrpsRiTqtNTpnAo1m0qQg,8048
|
|
@@ -56,7 +56,7 @@ moai_adk/templates/.claude/agents/alfred/trust-checker.md,sha256=DtjKjDo-aYBxvz_
|
|
|
56
56
|
moai_adk/templates/.claude/commands/alfred/0-project.md,sha256=c0aCthvHu57Eg4QHB3MeoviguBTK6yUw8g4fyq-5-jA,45556
|
|
57
57
|
moai_adk/templates/.claude/commands/alfred/1-plan.md,sha256=4Afx44Xx1yp4kp5FwrJg4QxMt-NBkkfgNNi05lk0glg,21792
|
|
58
58
|
moai_adk/templates/.claude/commands/alfred/2-run.md,sha256=UMscmBrpqysmWoKvwyGXEnCEzDWVeS5VEvvYABFYC4g,20194
|
|
59
|
-
moai_adk/templates/.claude/commands/alfred/3-sync.md,sha256=
|
|
59
|
+
moai_adk/templates/.claude/commands/alfred/3-sync.md,sha256=d_ET4i7mD7SV-9-QlNtdGXg4ViaWaadvREO8zZ32-h4,22247
|
|
60
60
|
moai_adk/templates/.claude/hooks/alfred/HOOK_SCHEMA_VALIDATION.md,sha256=5dd6KRFQXzp0L8lAWKRN7Momgg_8XNV1QZ6VGs03_pc,9064
|
|
61
61
|
moai_adk/templates/.claude/hooks/alfred/README.md,sha256=8JirNg3Jn2OUFmHySYBd8QxQgPkG7kcev86Zkf80asY,6852
|
|
62
62
|
moai_adk/templates/.claude/hooks/alfred/alfred_hooks.py,sha256=ILYbruVD1o284wmKPFaE2LPARekVtecpcovCvqy7eEc,7570
|
|
@@ -261,8 +261,8 @@ moai_adk/templates/.moai/project/tech.md,sha256=REecMv8wOvutt-pQZ5nlGk5YdReTan7A
|
|
|
261
261
|
moai_adk/utils/__init__.py,sha256=VnVfQzzKHvKw4bNdEw5xdscnRQYFrnr-v_TOBr3naPs,225
|
|
262
262
|
moai_adk/utils/banner.py,sha256=znppKd5yo-tTqgyhgPVJjstrTrfcy_v3X1_RFQxP4Fk,1878
|
|
263
263
|
moai_adk/utils/logger.py,sha256=g-m07PGKjK2bKRIInfSn6m-024Bedai-pV_WjZKDeu8,5064
|
|
264
|
-
moai_adk-0.5.
|
|
265
|
-
moai_adk-0.5.
|
|
266
|
-
moai_adk-0.5.
|
|
267
|
-
moai_adk-0.5.
|
|
268
|
-
moai_adk-0.5.
|
|
264
|
+
moai_adk-0.5.4.dist-info/METADATA,sha256=uLHzOOwLwI-OrQAbLihJTLb0kPJH8-8UKnW8XTpQKo8,62659
|
|
265
|
+
moai_adk-0.5.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
266
|
+
moai_adk-0.5.4.dist-info/entry_points.txt,sha256=P9no1794UipqH72LP-ltdyfVd_MeB1WKJY_6-JQgV3U,52
|
|
267
|
+
moai_adk-0.5.4.dist-info/licenses/LICENSE,sha256=M1M2b07fWcSWRM6_P3wbZKndZvyfHyYk_Wu9bS8F7o8,1069
|
|
268
|
+
moai_adk-0.5.4.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|