moai-adk 0.8.1__py3-none-any.whl → 0.8.3__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.

Files changed (87) hide show
  1. moai_adk/cli/commands/update.py +15 -4
  2. moai_adk/core/config/migration.py +1 -1
  3. moai_adk/core/issue_creator.py +7 -3
  4. moai_adk/core/tags/__init__.py +86 -0
  5. moai_adk/core/tags/ci_validator.py +433 -0
  6. moai_adk/core/tags/cli.py +283 -0
  7. moai_adk/core/tags/generator.py +109 -0
  8. moai_adk/core/tags/inserter.py +99 -0
  9. moai_adk/core/tags/mapper.py +126 -0
  10. moai_adk/core/tags/parser.py +76 -0
  11. moai_adk/core/tags/pre_commit_validator.py +355 -0
  12. moai_adk/core/tags/reporter.py +957 -0
  13. moai_adk/core/tags/tags.py +149 -0
  14. moai_adk/core/tags/validator.py +897 -0
  15. moai_adk/templates/.claude/agents/alfred/cc-manager.md +25 -2
  16. moai_adk/templates/.claude/agents/alfred/debug-helper.md +24 -12
  17. moai_adk/templates/.claude/agents/alfred/doc-syncer.md +19 -12
  18. moai_adk/templates/.claude/agents/alfred/git-manager.md +20 -12
  19. moai_adk/templates/.claude/agents/alfred/implementation-planner.md +19 -12
  20. moai_adk/templates/.claude/agents/alfred/project-manager.md +29 -2
  21. moai_adk/templates/.claude/agents/alfred/quality-gate.md +25 -2
  22. moai_adk/templates/.claude/agents/alfred/skill-factory.md +30 -2
  23. moai_adk/templates/.claude/agents/alfred/spec-builder.md +26 -11
  24. moai_adk/templates/.claude/agents/alfred/tag-agent.md +30 -8
  25. moai_adk/templates/.claude/agents/alfred/tdd-implementer.md +27 -12
  26. moai_adk/templates/.claude/agents/alfred/trust-checker.md +25 -2
  27. moai_adk/templates/.claude/commands/alfred/0-project.md +5 -0
  28. moai_adk/templates/.claude/commands/alfred/1-plan.md +82 -19
  29. moai_adk/templates/.claude/commands/alfred/2-run.md +72 -15
  30. moai_adk/templates/.claude/commands/alfred/3-sync.md +74 -14
  31. moai_adk/templates/.claude/hooks/alfred/.moai/cache/version-check.json +9 -0
  32. moai_adk/templates/.claude/hooks/alfred/README.md +258 -145
  33. moai_adk/templates/.claude/hooks/alfred/TROUBLESHOOTING.md +471 -0
  34. moai_adk/templates/.claude/hooks/alfred/alfred_hooks.py +92 -57
  35. moai_adk/templates/.claude/hooks/alfred/core/version_cache.py +198 -0
  36. moai_adk/templates/.claude/hooks/alfred/notification__handle_events.py +102 -0
  37. moai_adk/templates/.claude/hooks/alfred/post_tool__log_changes.py +102 -0
  38. moai_adk/templates/.claude/hooks/alfred/pre_tool__auto_checkpoint.py +108 -0
  39. moai_adk/templates/.claude/hooks/alfred/session_end__cleanup.py +102 -0
  40. moai_adk/templates/.claude/hooks/alfred/session_start__show_project_info.py +102 -0
  41. moai_adk/templates/.claude/hooks/alfred/{core → shared/core}/project.py +286 -19
  42. moai_adk/templates/.claude/hooks/alfred/shared/core/version_cache.py +198 -0
  43. moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/session.py +21 -7
  44. moai_adk/templates/.claude/hooks/alfred/stop__handle_interrupt.py +102 -0
  45. moai_adk/templates/.claude/hooks/alfred/subagent_stop__handle_subagent_end.py +102 -0
  46. moai_adk/templates/.claude/hooks/alfred/user_prompt__jit_load_docs.py +120 -0
  47. moai_adk/templates/.claude/settings.json +5 -5
  48. moai_adk/templates/.claude/skills/moai-foundation-ears/SKILL.md +9 -6
  49. moai_adk/templates/.claude/skills/moai-spec-authoring/README.md +56 -56
  50. moai_adk/templates/.claude/skills/moai-spec-authoring/SKILL.md +101 -100
  51. moai_adk/templates/.claude/skills/moai-spec-authoring/examples/validate-spec.sh +3 -3
  52. moai_adk/templates/.claude/skills/moai-spec-authoring/examples.md +219 -219
  53. moai_adk/templates/.claude/skills/moai-spec-authoring/reference.md +287 -287
  54. moai_adk/templates/.github/ISSUE_TEMPLATE/spec.yml +9 -11
  55. moai_adk/templates/.github/PULL_REQUEST_TEMPLATE.md +9 -21
  56. moai_adk/templates/.github/workflows/moai-release-create.yml +100 -0
  57. moai_adk/templates/.github/workflows/moai-release-pipeline.yml +182 -0
  58. moai_adk/templates/.github/workflows/release.yml +49 -0
  59. moai_adk/templates/.github/workflows/tag-report.yml +261 -0
  60. moai_adk/templates/.github/workflows/tag-validation.yml +176 -0
  61. moai_adk/templates/.moai/config.json +6 -1
  62. moai_adk/templates/.moai/hooks/install.sh +79 -0
  63. moai_adk/templates/.moai/hooks/pre-commit.sh +66 -0
  64. moai_adk/templates/CLAUDE.md +39 -40
  65. moai_adk/templates/src/moai_adk/core/__init__.py +5 -0
  66. moai_adk/templates/src/moai_adk/core/tags/__init__.py +86 -0
  67. moai_adk/templates/src/moai_adk/core/tags/ci_validator.py +433 -0
  68. moai_adk/templates/src/moai_adk/core/tags/cli.py +283 -0
  69. moai_adk/templates/src/moai_adk/core/tags/pre_commit_validator.py +355 -0
  70. moai_adk/templates/src/moai_adk/core/tags/reporter.py +957 -0
  71. moai_adk/templates/src/moai_adk/core/tags/validator.py +897 -0
  72. {moai_adk-0.8.1.dist-info → moai_adk-0.8.3.dist-info}/METADATA +240 -14
  73. {moai_adk-0.8.1.dist-info → moai_adk-0.8.3.dist-info}/RECORD +85 -50
  74. moai_adk/templates/.claude/hooks/alfred/HOOK_SCHEMA_VALIDATION.md +0 -313
  75. moai_adk/templates/.moai/memory/config-schema.md +0 -444
  76. /moai_adk/templates/.claude/hooks/alfred/{core → shared/core}/__init__.py +0 -0
  77. /moai_adk/templates/.claude/hooks/alfred/{core → shared/core}/checkpoint.py +0 -0
  78. /moai_adk/templates/.claude/hooks/alfred/{core → shared/core}/context.py +0 -0
  79. /moai_adk/templates/.claude/hooks/alfred/{core → shared/core}/tags.py +0 -0
  80. /moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/__init__.py +0 -0
  81. /moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/notification.py +0 -0
  82. /moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/tool.py +0 -0
  83. /moai_adk/templates/.claude/hooks/alfred/{handlers → shared/handlers}/user.py +0 -0
  84. /moai_adk/templates/.moai/memory/{issue-label-mapping.md → ISSUE-LABEL-MAPPING.md} +0 -0
  85. {moai_adk-0.8.1.dist-info → moai_adk-0.8.3.dist-info}/WHEEL +0 -0
  86. {moai_adk-0.8.1.dist-info → moai_adk-0.8.3.dist-info}/entry_points.txt +0 -0
  87. {moai_adk-0.8.1.dist-info → moai_adk-0.8.3.dist-info}/licenses/LICENSE +0 -0
@@ -51,9 +51,11 @@ def handle_session_start(payload: HookPayload) -> HookResult:
51
51
  - FIX: Prevent duplicate output of clear step (only compact step is displayed)
52
52
  - UPDATE: Migrated to Claude Code standard Hook schema
53
53
  - HOTFIX: Add graceful degradation for timeout scenarios (Issue #66)
54
+ - Phase 3: Add major version warning and release notes display (@TEST:MAJOR-UPDATE-001-07/08)
54
55
 
55
56
  @TAG:CHECKPOINT-EVENT-001
56
57
  @TAG:HOOKS-TIMEOUT-001
58
+ @CODE:MAJOR-UPDATE-WARN-001
57
59
  """
58
60
  # Claude Code SessionStart runs in several stages (clear, compact, etc.)
59
61
  # Ignore the "clear" stage and output messages only at the "compact" stage
@@ -113,14 +115,26 @@ def handle_session_start(payload: HookPayload) -> HookResult:
113
115
 
114
116
  # Add version info first (at the top, right after title)
115
117
  if version_info and version_info.get("current") != "unknown":
116
- version_line = f" 🗿 MoAI-ADK Ver: {version_info['current']}"
117
118
  if version_info.get("update_available"):
118
- version_line += f" {version_info['latest']} available ✨"
119
- lines.append(version_line)
120
-
121
- # Add upgrade recommendation if update is available
122
- if version_info.get("update_available") and version_info.get("upgrade_command"):
123
- lines.append(f" ⬆️ Upgrade: {version_info['upgrade_command']}")
119
+ # Check if this is a major version update
120
+ if version_info.get("is_major_update"):
121
+ # Major version warning
122
+ lines.append(f" ⚠️ Major version update available: {version_info['current']} {version_info['latest']}")
123
+ lines.append(" Breaking changes detected. Review release notes:")
124
+ if version_info.get("release_notes_url"):
125
+ lines.append(f" 📝 {version_info['release_notes_url']}")
126
+ else:
127
+ # Regular update
128
+ lines.append(f" 🗿 MoAI-ADK Ver: {version_info['current']} → {version_info['latest']} available ✨")
129
+ if version_info.get("release_notes_url"):
130
+ lines.append(f" 📝 Release Notes: {version_info['release_notes_url']}")
131
+
132
+ # Add upgrade recommendation
133
+ if version_info.get("upgrade_command"):
134
+ lines.append(f" ⬆️ Upgrade: {version_info['upgrade_command']}")
135
+ else:
136
+ # No update available - show current version only
137
+ lines.append(f" 🗿 MoAI-ADK Ver: {version_info['current']}")
124
138
 
125
139
  # Add language info
126
140
  lines.append(f" 🐍 Language: {language}")
@@ -0,0 +1,102 @@
1
+ #!/usr/bin/env python3
2
+ # @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
3
+ """Stop Hook: Handle Execution Interruption
4
+
5
+ Claude Code Event: Stop
6
+ Purpose: Handle graceful shutdown when execution is interrupted by user
7
+ Execution: Triggered when user stops Claude Code execution (Ctrl+C, stop button)
8
+
9
+ Output: Continue execution (currently a stub for future enhancements)
10
+ """
11
+
12
+ import json
13
+ import signal
14
+ import sys
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ # Setup import path for shared modules
19
+ HOOKS_DIR = Path(__file__).parent
20
+ SHARED_DIR = HOOKS_DIR / "shared"
21
+ if str(SHARED_DIR) not in sys.path:
22
+ sys.path.insert(0, str(SHARED_DIR))
23
+
24
+ from handlers import handle_stop
25
+
26
+
27
+ class HookTimeoutError(Exception):
28
+ """Hook execution timeout exception"""
29
+ pass
30
+
31
+
32
+ def _timeout_handler(signum, frame):
33
+ """Signal handler for 5-second timeout"""
34
+ raise HookTimeoutError("Hook execution exceeded 5-second timeout")
35
+
36
+
37
+ def main() -> None:
38
+ """Main entry point for Stop hook
39
+
40
+ Currently a stub for future functionality:
41
+ - Save partial work before interruption
42
+ - Create recovery checkpoint
43
+ - Log interruption reason and context
44
+ - Notify external systems of stop event
45
+
46
+ Exit Codes:
47
+ 0: Success
48
+ 1: Error (timeout, JSON parse failure, handler exception)
49
+ """
50
+ # Set 5-second timeout
51
+ signal.signal(signal.SIGALRM, _timeout_handler)
52
+ signal.alarm(5)
53
+
54
+ try:
55
+ # Read JSON payload from stdin
56
+ input_data = sys.stdin.read()
57
+ data = json.loads(input_data) if input_data.strip() else {}
58
+
59
+ # Call handler
60
+ result = handle_stop(data)
61
+
62
+ # Output result as JSON
63
+ print(json.dumps(result.to_dict()))
64
+ sys.exit(0)
65
+
66
+ except HookTimeoutError:
67
+ # Timeout - return minimal valid response
68
+ timeout_response: dict[str, Any] = {
69
+ "continue": True,
70
+ "systemMessage": "⚠️ Stop handler timeout"
71
+ }
72
+ print(json.dumps(timeout_response))
73
+ print("Stop hook timeout after 5 seconds", file=sys.stderr)
74
+ sys.exit(1)
75
+
76
+ except json.JSONDecodeError as e:
77
+ # JSON parse error
78
+ error_response: dict[str, Any] = {
79
+ "continue": True,
80
+ "hookSpecificOutput": {"error": f"JSON parse error: {e}"}
81
+ }
82
+ print(json.dumps(error_response))
83
+ print(f"Stop JSON parse error: {e}", file=sys.stderr)
84
+ sys.exit(1)
85
+
86
+ except Exception as e:
87
+ # Unexpected error
88
+ error_response: dict[str, Any] = {
89
+ "continue": True,
90
+ "hookSpecificOutput": {"error": f"Stop error: {e}"}
91
+ }
92
+ print(json.dumps(error_response))
93
+ print(f"Stop unexpected error: {e}", file=sys.stderr)
94
+ sys.exit(1)
95
+
96
+ finally:
97
+ # Always cancel alarm
98
+ signal.alarm(0)
99
+
100
+
101
+ if __name__ == "__main__":
102
+ main()
@@ -0,0 +1,102 @@
1
+ #!/usr/bin/env python3
2
+ # @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
3
+ """SubagentStop Hook: Handle Sub-agent Termination
4
+
5
+ Claude Code Event: SubagentStop
6
+ Purpose: Handle cleanup when a sub-agent execution completes or is terminated
7
+ Execution: Triggered when Task tool completes (sub-agent finishes)
8
+
9
+ Output: Continue execution (currently a stub for future enhancements)
10
+ """
11
+
12
+ import json
13
+ import signal
14
+ import sys
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ # Setup import path for shared modules
19
+ HOOKS_DIR = Path(__file__).parent
20
+ SHARED_DIR = HOOKS_DIR / "shared"
21
+ if str(SHARED_DIR) not in sys.path:
22
+ sys.path.insert(0, str(SHARED_DIR))
23
+
24
+ from handlers import handle_subagent_stop
25
+
26
+
27
+ class HookTimeoutError(Exception):
28
+ """Hook execution timeout exception"""
29
+ pass
30
+
31
+
32
+ def _timeout_handler(signum, frame):
33
+ """Signal handler for 5-second timeout"""
34
+ raise HookTimeoutError("Hook execution exceeded 5-second timeout")
35
+
36
+
37
+ def main() -> None:
38
+ """Main entry point for SubagentStop hook
39
+
40
+ Currently a stub for future functionality:
41
+ - Collect sub-agent execution metrics
42
+ - Log sub-agent results and errors
43
+ - Update workflow state based on sub-agent outcome
44
+ - Trigger follow-up actions based on results
45
+
46
+ Exit Codes:
47
+ 0: Success
48
+ 1: Error (timeout, JSON parse failure, handler exception)
49
+ """
50
+ # Set 5-second timeout
51
+ signal.signal(signal.SIGALRM, _timeout_handler)
52
+ signal.alarm(5)
53
+
54
+ try:
55
+ # Read JSON payload from stdin
56
+ input_data = sys.stdin.read()
57
+ data = json.loads(input_data) if input_data.strip() else {}
58
+
59
+ # Call handler
60
+ result = handle_subagent_stop(data)
61
+
62
+ # Output result as JSON
63
+ print(json.dumps(result.to_dict()))
64
+ sys.exit(0)
65
+
66
+ except HookTimeoutError:
67
+ # Timeout - return minimal valid response
68
+ timeout_response: dict[str, Any] = {
69
+ "continue": True,
70
+ "systemMessage": "⚠️ SubagentStop handler timeout"
71
+ }
72
+ print(json.dumps(timeout_response))
73
+ print("SubagentStop hook timeout after 5 seconds", file=sys.stderr)
74
+ sys.exit(1)
75
+
76
+ except json.JSONDecodeError as e:
77
+ # JSON parse error
78
+ error_response: dict[str, Any] = {
79
+ "continue": True,
80
+ "hookSpecificOutput": {"error": f"JSON parse error: {e}"}
81
+ }
82
+ print(json.dumps(error_response))
83
+ print(f"SubagentStop JSON parse error: {e}", file=sys.stderr)
84
+ sys.exit(1)
85
+
86
+ except Exception as e:
87
+ # Unexpected error
88
+ error_response: dict[str, Any] = {
89
+ "continue": True,
90
+ "hookSpecificOutput": {"error": f"SubagentStop error: {e}"}
91
+ }
92
+ print(json.dumps(error_response))
93
+ print(f"SubagentStop unexpected error: {e}", file=sys.stderr)
94
+ sys.exit(1)
95
+
96
+ finally:
97
+ # Always cancel alarm
98
+ signal.alarm(0)
99
+
100
+
101
+ if __name__ == "__main__":
102
+ main()
@@ -0,0 +1,120 @@
1
+ #!/usr/bin/env python3
2
+ # @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
3
+ """UserPromptSubmit Hook: Just-In-Time Document Loading
4
+
5
+ Claude Code Event: UserPromptSubmit
6
+ Purpose: Analyze user prompt and recommend relevant documents to load into context
7
+ Execution: Triggered when user submits a prompt
8
+
9
+ Output: additionalContext with document path suggestions
10
+ """
11
+
12
+ import json
13
+ import signal
14
+ import sys
15
+ from pathlib import Path
16
+ from typing import Any
17
+
18
+ # Setup import path for shared modules
19
+ HOOKS_DIR = Path(__file__).parent
20
+ SHARED_DIR = HOOKS_DIR / "shared"
21
+ if str(SHARED_DIR) not in sys.path:
22
+ sys.path.insert(0, str(SHARED_DIR))
23
+
24
+ from handlers import handle_user_prompt_submit
25
+
26
+
27
+ class HookTimeoutError(Exception):
28
+ """Hook execution timeout exception"""
29
+ pass
30
+
31
+
32
+ def _timeout_handler(signum, frame):
33
+ """Signal handler for 5-second timeout"""
34
+ raise HookTimeoutError("Hook execution exceeded 5-second timeout")
35
+
36
+
37
+ def main() -> None:
38
+ """Main entry point for UserPromptSubmit hook
39
+
40
+ Analyzes user prompt patterns and recommends relevant documents:
41
+ - /alfred:1-plan → spec-metadata.md
42
+ - /alfred:2-run → development-guide.md
43
+ - @TAG mentions → TAG documentation
44
+ - SPEC references → related SPEC files
45
+
46
+ Exit Codes:
47
+ 0: Success
48
+ 1: Error (timeout, JSON parse failure, handler exception)
49
+
50
+ Note: Uses special output schema for UserPromptSubmit:
51
+ {
52
+ "continue": true,
53
+ "hookSpecificOutput": {
54
+ "hookEventName": "UserPromptSubmit",
55
+ "additionalContext": "Document path suggestions..."
56
+ }
57
+ }
58
+ """
59
+ # Set 5-second timeout
60
+ signal.signal(signal.SIGALRM, _timeout_handler)
61
+ signal.alarm(5)
62
+
63
+ try:
64
+ # Read JSON payload from stdin
65
+ input_data = sys.stdin.read()
66
+ data = json.loads(input_data) if input_data.strip() else {}
67
+
68
+ # Call handler
69
+ result = handle_user_prompt_submit(data)
70
+
71
+ # Output result using UserPromptSubmit-specific schema
72
+ print(json.dumps(result.to_user_prompt_submit_dict()))
73
+ sys.exit(0)
74
+
75
+ except HookTimeoutError:
76
+ # Timeout - return minimal valid response
77
+ timeout_response: dict[str, Any] = {
78
+ "continue": True,
79
+ "hookSpecificOutput": {
80
+ "hookEventName": "UserPromptSubmit",
81
+ "additionalContext": "⚠️ JIT context timeout - continuing without suggestions"
82
+ }
83
+ }
84
+ print(json.dumps(timeout_response))
85
+ print("UserPromptSubmit hook timeout after 5 seconds", file=sys.stderr)
86
+ sys.exit(1)
87
+
88
+ except json.JSONDecodeError as e:
89
+ # JSON parse error
90
+ error_response: dict[str, Any] = {
91
+ "continue": True,
92
+ "hookSpecificOutput": {
93
+ "hookEventName": "UserPromptSubmit",
94
+ "error": f"JSON parse error: {e}"
95
+ }
96
+ }
97
+ print(json.dumps(error_response))
98
+ print(f"UserPromptSubmit JSON parse error: {e}", file=sys.stderr)
99
+ sys.exit(1)
100
+
101
+ except Exception as e:
102
+ # Unexpected error
103
+ error_response: dict[str, Any] = {
104
+ "continue": True,
105
+ "hookSpecificOutput": {
106
+ "hookEventName": "UserPromptSubmit",
107
+ "error": f"UserPromptSubmit error: {e}"
108
+ }
109
+ }
110
+ print(json.dumps(error_response))
111
+ print(f"UserPromptSubmit unexpected error: {e}", file=sys.stderr)
112
+ sys.exit(1)
113
+
114
+ finally:
115
+ # Always cancel alarm
116
+ signal.alarm(0)
117
+
118
+
119
+ if __name__ == "__main__":
120
+ main()
@@ -10,7 +10,7 @@
10
10
  {
11
11
  "hooks": [
12
12
  {
13
- "command": "uv run .claude/hooks/alfred/alfred_hooks.py SessionStart",
13
+ "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/session_start__show_project_info.py",
14
14
  "type": "command"
15
15
  }
16
16
  ]
@@ -20,7 +20,7 @@
20
20
  {
21
21
  "hooks": [
22
22
  {
23
- "command": "uv run .claude/hooks/alfred/alfred_hooks.py PreToolUse",
23
+ "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/pre_tool__auto_checkpoint.py",
24
24
  "type": "command"
25
25
  }
26
26
  ],
@@ -31,7 +31,7 @@
31
31
  {
32
32
  "hooks": [
33
33
  {
34
- "command": "uv run .claude/hooks/alfred/alfred_hooks.py UserPromptSubmit",
34
+ "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/user_prompt__jit_load_docs.py",
35
35
  "type": "command"
36
36
  }
37
37
  ]
@@ -41,7 +41,7 @@
41
41
  {
42
42
  "hooks": [
43
43
  {
44
- "command": "uv run .claude/hooks/alfred/alfred_hooks.py SessionEnd",
44
+ "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/session_end__cleanup.py",
45
45
  "type": "command"
46
46
  }
47
47
  ]
@@ -51,7 +51,7 @@
51
51
  {
52
52
  "hooks": [
53
53
  {
54
- "command": "uv run .claude/hooks/alfred/alfred_hooks.py PostToolUse",
54
+ "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/post_tool__log_changes.py",
55
55
  "type": "command"
56
56
  }
57
57
  ],
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: moai-foundation-ears
3
- version: 2.0.0
3
+ version: 2.1.0
4
4
  created: 2025-10-22
5
- updated: 2025-10-22
5
+ updated: 2025-10-29
6
6
  status: active
7
- description: EARS requirement authoring guide (Ubiquitous/Event/State/Optional/Constraints).
8
- keywords: ['ears', 'requirements', 'authoring', 'syntax']
7
+ description: EARS requirement authoring guide (Ubiquitous/Event-driven/State-driven/Optional/Unwanted Behaviors) with 5 official patterns.
8
+ keywords: ['ears', 'requirements', 'authoring', 'syntax', 'unwanted-behaviors']
9
9
  allowed-tools:
10
10
  - Read
11
11
  - Bash
@@ -27,13 +27,15 @@ allowed-tools:
27
27
 
28
28
  ## What It Does
29
29
 
30
- EARS requirement authoring guide (Ubiquitous/Event/State/Optional/Constraints).
30
+ Official EARS (Easy Approach to Requirements Syntax) requirement authoring guide with 5 patterns: Ubiquitous, Event-driven, State-driven, Optional, and Unwanted Behaviors.
31
31
 
32
32
  **Key capabilities**:
33
+ - ✅ Five official EARS patterns with real-world examples
33
34
  - ✅ Best practices enforcement for foundation domain
34
35
  - ✅ TRUST 5 principles integration
35
- - ✅ Latest tool versions (2025-10-22)
36
+ - ✅ Latest tool versions (2025-10-29)
36
37
  - ✅ TDD workflow support
38
+ - ✅ Unwanted Behaviors pattern for error handling & quality gates
37
39
 
38
40
  ---
39
41
 
@@ -85,6 +87,7 @@ _Documentation links updated 2025-10-22_
85
87
 
86
88
  ## Changelog
87
89
 
90
+ - **v2.1.0** (2025-10-29): Standardized Unwanted Behaviors as 5th official EARS pattern, replacing Constraints terminology
88
91
  - **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
89
92
  - **v1.0.0** (2025-03-29): Initial Skill release
90
93
 
@@ -1,74 +1,74 @@
1
1
  # moai-spec-authoring Skill
2
2
 
3
- **Version**: 1.1.0
4
- **Created**: 2025-10-23
5
- **Updated**: 2025-10-27
6
- **Status**: Active
3
+ **Version**: 1.2.0
4
+ **Created**: 2025-10-23
5
+ **Updated**: 2025-10-29
6
+ **Status**: Active
7
7
  **Tier**: Foundation
8
8
 
9
9
  ## Overview
10
10
 
11
- MoAI-ADK SPEC 문서 작성을 위한 종합 가이드입니다. YAML 메타데이터, EARS 문법, 검증 전략을 제공합니다.
11
+ Comprehensive guide for authoring SPEC documents in MoAI-ADK projects. Provides complete YAML metadata structure, EARS syntax patterns, version management strategies, and validation tools.
12
12
 
13
13
  ## Key Features
14
14
 
15
- - **7 Required + 9 Optional Metadata Fields**: 완전한 레퍼런스와 예제
16
- - **5 EARS Patterns**: Ubiquitous, Event-driven, State-driven, Optional, Constraints
17
- - **Version Lifecycle**: draft에서 production까지 시맨틱 버전 관리
18
- - **TAG Integration**: @SPEC, @TEST, @CODE, @DOC 체인 관리
19
- - **Validation Tools**: 제출 체크리스트와 자동화 스크립트
20
- - **Common Pitfalls**: 7가지 주요 이슈에 대한 예방 전략
15
+ - **7 Required + 9 Optional Metadata Fields**: Complete reference with lifecycle examples
16
+ - **5 Official EARS Patterns**: Ubiquitous, Event-driven, State-driven, Optional, Unwanted Behaviors
17
+ - **Version Lifecycle**: Semantic versioning from draft to production
18
+ - **TAG Integration**: @SPEC, @TEST, @CODE, @DOC chain management
19
+ - **Validation Tools**: Pre-submission checklist and automation scripts
20
+ - **Common Pitfalls**: Prevention strategies for 7 major issues
21
21
 
22
22
  ## File Structure (Progressive Disclosure)
23
23
 
24
24
  ```
25
25
  .claude/skills/moai-spec-authoring/
26
- ├── SKILL.md # 핵심 개요 + Quick Start (~500 words)
27
- ├── reference.md # 메타데이터 레퍼런스 + EARS 문법 상세
28
- ├── examples.md # 실전 예제 + 패턴 + 트러블슈팅
26
+ ├── SKILL.md # Core overview + Quick Start (~500 words)
27
+ ├── reference.md # Complete metadata reference + EARS syntax
28
+ ├── examples.md # Real-world examples + patterns + troubleshooting
29
29
  ├── examples/
30
- │ └── validate-spec.sh # SPEC 검증 스크립트
31
- └── README.md # 파일
30
+ │ └── validate-spec.sh # Automated SPEC validation script
31
+ └── README.md # This file
32
32
  ```
33
33
 
34
34
  ## Quick Links
35
35
 
36
36
  - **Quick Start**: [SKILL.md](./SKILL.md#quick-start-5-step-spec-creation)
37
- - **Metadata Reference**: [reference.md](./reference.md#메타데이터-완전-레퍼런스)
38
- - **EARS Syntax**: [reference.md](./reference.md#ears-요구사항-문법)
39
- - **Examples**: [examples.md](./examples.md#실전-ears-예제)
40
- - **Troubleshooting**: [examples.md](./examples.md#트러블슈팅)
37
+ - **Metadata Reference**: [reference.md](./reference.md#complete-metadata-field-reference)
38
+ - **EARS Syntax**: [reference.md](./reference.md#ears-requirement-syntax)
39
+ - **Examples**: [examples.md](./examples.md#real-world-ears-examples)
40
+ - **Troubleshooting**: [examples.md](./examples.md#troubleshooting)
41
41
 
42
42
  ## Usage
43
43
 
44
44
  ### Automatic Activation
45
45
 
46
- Skill 다음 경우 자동으로 로드됩니다:
47
- - `/alfred:1-plan` 명령어 실행
48
- - SPEC 문서 생성 요청
49
- - 요구사항 명확화 논의
46
+ This Skill automatically loads when:
47
+ - `/alfred:1-plan` command is executed
48
+ - SPEC document creation is requested
49
+ - Requirements clarification is discussed
50
50
 
51
51
  ### Manual Reference
52
52
 
53
- 다음 경우 상세 섹션 참조:
54
- - SPEC 작성 모범 사례 학습
55
- - 기존 SPEC 문서 검증
56
- - 메타데이터 이슈 트러블슈팅
57
- - EARS 문법 패턴 이해
53
+ Consult detailed sections for:
54
+ - SPEC authoring best practices
55
+ - Existing SPEC document validation
56
+ - Metadata issue troubleshooting
57
+ - EARS syntax pattern reference
58
58
 
59
59
  ## Validation Command
60
60
 
61
61
  ```bash
62
- # SPEC 메타데이터 검증
62
+ # Validate SPEC metadata
63
63
  rg "^(id|version|status|created|updated|author|priority):" .moai/specs/SPEC-AUTH-001/spec.md
64
64
 
65
- # 중복 ID 확인
65
+ # Check for duplicate IDs
66
66
  rg "@SPEC:AUTH-001" -n .moai/specs/
67
67
 
68
- # 전체 TAG 체인 스캔
68
+ # Scan entire TAG chain
69
69
  rg '@(SPEC|TEST|CODE|DOC):AUTH-001' -n
70
70
 
71
- # 자동화 스크립트 사용
71
+ # Use automated script
72
72
  ./examples/validate-spec.sh .moai/specs/SPEC-AUTH-001
73
73
  ```
74
74
 
@@ -79,8 +79,8 @@ rg '@(SPEC|TEST|CODE|DOC):AUTH-001' -n
79
79
  id: AUTH-001
80
80
  version: 0.0.1
81
81
  status: draft
82
- created: 2025-10-23
83
- updated: 2025-10-23
82
+ created: 2025-10-29
83
+ updated: 2025-10-29
84
84
  author: @YourHandle
85
85
  priority: high
86
86
  ---
@@ -88,50 +88,50 @@ priority: high
88
88
  # @SPEC:AUTH-001: JWT Authentication System
89
89
 
90
90
  ## HISTORY
91
- ### v0.0.1 (2025-10-23)
92
- - **INITIAL**: JWT 인증 SPEC 초안
91
+ ### v0.0.1 (2025-10-29)
92
+ - **INITIAL**: JWT authentication SPEC draft
93
93
 
94
94
  ## Environment
95
95
  **Runtime**: Node.js 20.x
96
96
 
97
97
  ## Assumptions
98
- 1. 사용자 저장소: PostgreSQL
99
- 2. 시크릿 관리: 환경변수
98
+ 1. User storage: PostgreSQL
99
+ 2. Secret management: Environment variables
100
100
 
101
101
  ## Requirements
102
102
 
103
103
  ### Ubiquitous Requirements
104
- **UR-001**: 시스템은 JWT 기반 인증을 제공해야 한다.
104
+ **UR-001**: The system shall provide JWT-based authentication.
105
105
 
106
106
  ### Event-driven Requirements
107
- **ER-001**: WHEN 사용자가 유효한 인증 정보를 제출하면, 시스템은 JWT 토큰을 발급해야 한다.
107
+ **ER-001**: WHEN the user submits valid credentials, the system shall issue a JWT token.
108
108
 
109
109
  ### State-driven Requirements
110
- **SR-001**: WHILE 사용자가 인증된 상태이면, 시스템은 보호된 리소스에 대한 접근을 허용해야 한다.
110
+ **SR-001**: WHILE the user is in an authenticated state, the system shall permit access to protected resources.
111
111
 
112
112
  ### Optional Features
113
- **OF-001**: WHERE 다중 인증이 활성화된 경우, 시스템은 OTP 검증을 요구할 있다.
113
+ **OF-001**: WHERE multi-factor authentication is enabled, the system can require OTP verification.
114
114
 
115
- ### Constraints
116
- **C-001**: IF 토큰이 만료되었다면, 시스템은 접근을 거부해야 한다.
115
+ ### Unwanted Behaviors
116
+ **UB-001**: IF a token has expired, THEN the system shall deny access and return HTTP 401.
117
117
  ```
118
118
 
119
119
  ## Integration
120
120
 
121
- 다음과 원활하게 작동:
122
- - `spec-builder` agent - SPEC 생성
123
- - `moai-foundation-ears` - EARS 문법 패턴
124
- - `moai-foundation-specs` - 메타데이터 검증
125
- - `moai-foundation-tags` - TAG 시스템 통합
121
+ Works seamlessly with:
122
+ - `spec-builder` agent - SPEC creation
123
+ - `moai-foundation-ears` - EARS syntax patterns
124
+ - `moai-foundation-specs` - Metadata validation
125
+ - `moai-foundation-tags` - TAG system integration
126
126
 
127
127
  ## Support
128
128
 
129
- 질문이나 이슈가 있을 경우:
130
- 1. 포괄적인 문서는 `SKILL.md`, `reference.md`, `examples.md` 참조
131
- 2. 가이드된 SPEC 생성을 위해 `/alfred:1-plan` 호출
132
- 3. 예제는 `.moai/specs/`의 기존 SPEC 참조
129
+ For questions or issues:
130
+ 1. Refer to comprehensive documentation: `SKILL.md`, `reference.md`, `examples.md`
131
+ 2. Use `/alfred:1-plan` for guided SPEC creation
132
+ 3. Review existing SPECs in `.moai/specs/` for examples
133
133
 
134
134
  ---
135
135
 
136
- **Maintained By**: MoAI-ADK Team
137
- **Last Updated**: 2025-10-27
136
+ **Maintained By**: MoAI-ADK Team
137
+ **Last Updated**: 2025-10-29