moai-adk 0.8.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

moai_adk/templates/.moai/memory/spec-metadata.md

@@ -1,356 +0,0 @@
-# SPEC Metadata Structure Guide
-
-> **MoAI-ADK SPEC Metadata Standard**
->
-> Every SPEC document must follow this structure.
-
----
-
-## 📋 Metadata Overview
-
-SPEC metadata contains **7 required fields** and **9 optional fields**.
-
-### Full Example
-
-```yaml
----
-# Required Fields (7)
-id: AUTH-001                    # Unique SPEC ID
-version: 0.0.1                  # Semantic version (v0.0.1 = INITIAL, draft start)
-status: draft                   # draft|active|completed|deprecated
-created: 2025-09-15             # Creation date (YYYY-MM-DD)
-updated: 2025-09-15             # Last updated (YYYY-MM-DD; initially same as created)
-author: @Goos                   # Author (single GitHub handle)
-priority: high                  # low|medium|high|critical
-
-# Optional Fields – Classification/Meta
-category: security              # feature|bugfix|refactor|security|docs|perf
-labels:                         # Tags for search and grouping
-  - authentication
-  - jwt
-
-# Optional Fields – Relationships (Dependency Graph)
-depends_on:                     # SPECs this one depends on (optional)
-  - USER-001
-blocks:                         # SPECs blocked by this one (optional)
-  - AUTH-002
-related_specs:                  # Related SPECs (optional)
-  - TOKEN-002
-related_issue: "https://github.com/modu-ai/moai-adk/issues/123"
-
-# Optional Fields – Scope/Impact
-scope:
-  packages:                     # Impacted packages
-    - src/core/auth
-  files:                        # Key files (optional)
-    - auth-service.ts
-    - jwt-manager.ts
----
-```
-
----
-
-## Required Fields
-
-### 1. `id` – Unique SPEC Identifier
-- **Type**: string
-- **Format**: `<DOMAIN>-<NUMBER>`
-- **Examples**: `AUTH-001`, `INSTALLER-SEC-001`
-- **Rules**:
-  - Immutable once assigned
-  - Use three digits (001–999)
-  - Domain in uppercase; hyphens allowed
-  - Directory name: `.moai/specs/SPEC-{ID}/` (e.g., `.moai/specs/SPEC-AUTH-001/`)
-
-### 2. `version` – Semantic Version
-- **Type**: string (`MAJOR.MINOR.PATCH`)
-- **Default**: `0.0.1` (all SPECs start here, status: draft)
-- **Version Lifecycle**:
-  - **v0.0.1**: INITIAL – SPEC first draft (status: draft)
-  - **v0.0.x**: Draft refinements (increment PATCH when editing the SPEC)
-  - **v0.1.0**: TDD implementation complete (status: completed, updated via `/alfred:3-sync`)
-  - **v0.1.x**: Bug fixes or doc improvements (PATCH increment)
-  - **v0.x.0**: Feature additions or major enhancements (MINOR increment)
-  - **v1.0.0**: Stable release (production ready, explicit stakeholder approval required)
-
-### 3. `status` – Progress State
-- **Type**: enum
-- **Values**:
-  - `draft`: Authoring in progress
-  - `active`: Implementation underway
-  - `completed`: Implementation finished
-  - `deprecated`: Planned for retirement
-
-### 4. `created` – Creation Date
-- **Type**: date string
-- **Format**: `YYYY-MM-DD`
-- **Example**: `2025-10-06`
-
-### 5. `updated` – Last Modified Date
-- **Type**: date string
-- **Format**: `YYYY-MM-DD`
-- **Rule**: Update whenever the SPEC content changes.
-
-### 6. `author` – Primary Author
-- **Type**: string
-- **Format**: `@{GitHub ID}`
-- **Example**: `@Goos`
-- **Rules**:
-  - Single value only (no `authors` array)
-  - Prefix the GitHub handle with `@`
-  - Additional contributors belong in the HISTORY section
-
-### 7. `priority` – Work Priority
-- **Type**: enum
-- **Values**:
-  - `critical`: Immediate attention (security, severe defects)
-  - `high`: Major feature work
-  - `medium`: Enhancements
-  - `low`: Optimizations or documentation
-
----
-
-## Optional Fields
-
-### Classification / Meta
-
-#### 8. `category` – Change Type
-- **Type**: enum
-- **Values**:
-  - `feature`: New functionality
-  - `bugfix`: Defect resolution
-  - `refactor`: Structural improvements
-  - `security`: Security enhancements
-  - `docs`: Documentation updates
-  - `perf`: Performance optimizations
-
-#### 9. `labels` – Classification Tags
-- **Type**: array of strings
-- **Purpose**: Search, filtering, grouping
-- **Example**:
-  ```yaml
-  labels:
-    - installer
-    - template
-    - security
-  ```
-
-### Relationship Fields (Dependency Graph)
-
-#### 10. `depends_on` – Required SPECs
-- **Type**: array of strings
-- **Meaning**: SPECs that must be completed first
-- **Example**:
-  ```yaml
-  depends_on:
-    - USER-001
-    - AUTH-001
-  ```
-- **Use Case**: Determines execution order and parallelization.
-
-#### 11. `blocks` – Blocked SPECs
-- **Type**: array of strings
-- **Meaning**: SPECs that cannot proceed until this one is resolved
-- **Example**:
-  ```yaml
-  blocks:
-    - PAYMENT-003
-  ```
-
-#### 12. `related_specs` – Associated SPECs
-- **Type**: array of strings
-- **Meaning**: Related items without direct dependencies
-- **Example**:
-  ```yaml
-  related_specs:
-    - TOKEN-002
-    - SESSION-001
-  ```
-
-#### 13. `related_issue` – Linked GitHub Issue
-- **Type**: string (URL)
-- **Format**: Full GitHub issue URL
-- **Example**:
-  ```yaml
-  related_issue: "https://github.com/modu-ai/moai-adk/issues/123"
-  ```
-
-### Scope Fields (Impact Analysis)
-
-#### 14. `scope.packages` – Impacted Packages
-- **Type**: array of strings
-- **Meaning**: Packages or modules touched by the SPEC
-- **Example**:
-  ```yaml
-  scope:
-    packages:
-      - moai-adk-ts/src/core/installer
-      - moai-adk-ts/src/core/git
-  ```
-
-#### 15. `scope.files` – Key Files
-- **Type**: array of strings
-- **Meaning**: Primary files involved (for reference)
-- **Example**:
-  ```yaml
-  scope:
-    files:
-      - template-processor.ts
-      - template-security.ts
-  ```
-
----
-
-## Metadata Validation
-
-### Required Field Checks
-```bash
-# Verify that every SPEC includes the required fields
-rg "^(id|version|status|created|updated|author|priority):" .moai/specs/SPEC-*/spec.md
-
-# Identify SPECs missing the priority field
-rg -L "^priority:" .moai/specs/SPEC-*/spec.md
-```
-
-### Format Checks
-```bash
-# Ensure the author field uses @Handle format
-rg "^author: @[A-Z]" .moai/specs/SPEC-*/spec.md
-
-# Ensure the version field follows 0.x.y
-rg "^version: 0\.\d+\.\d+" .moai/specs/SPEC-*/spec.md
-```
-
----
-
-## Migration Guide
-
-### Updating Existing SPECs
-
-#### 1. Add the `priority` Field
-Add it if missing:
-```yaml
-priority: medium  # or low|high|critical
-```
-
-#### 2. Normalize the `author` Field
-- `authors: ["@goos"]` → `author: @Goos`
-- Convert lowercase handles to the canonical casing.
-
-#### 3. Add Optional Fields (Recommended)
-```yaml
-category: refactor
-labels:
-  - code-quality
-  - maintenance
-```
-
-### Updating config.json for Language Support (v0.4.2+)
-
-**Background**: MoAI-ADK v0.4.2 introduces conversation language selection in `/alfred:0-project`. Existing projects need to add language metadata to `.moai/config.json`.
-
-#### Migration Steps
-
-**For Existing Projects** (before v0.4.2):
-
-Current config.json structure:
-```json
-{
-  "project": {
-    "locale": "en",
-    "mode": "personal",
-    "language": "python"
-  }
-}
-```
-
-**Updated Structure** (v0.4.2+):
-```json
-{
-  "project": {
-    "locale": "en",
-    "mode": "personal",
-    "language": "python",
-    "conversation_language": "en",
-    "conversation_language_name": "English",
-    "codebase_languages": ["python"]
-  }
-}
-```
-
-#### New Fields
-
-| Field | Type | Required | Description | Example |
-|-------|------|----------|-------------|---------|
-| `conversation_language` | string (ISO 639-1 code) | ✅ Yes | Two-letter language code for Alfred dialogs | `"ko"`, `"en"`, `"ja"`, `"zh"` |
-| `conversation_language_name` | string | ✅ Yes | Display name of conversation language | `"Korean"`, `"English"` |
-| `codebase_languages` | array of strings | ✅ Yes | List of programming languages detected | `["python"]`, `["typescript", "python"]` |
-
-#### Manual Update Process
-
-1. Open `.moai/config.json`
-2. Add the three new fields under `project`:
-   ```json
-   "conversation_language": "en",
-   "conversation_language_name": "English",
-   "codebase_languages": ["python"]
-   ```
-3. Save and commit:
-   ```bash
-   git add .moai/config.json
-   git commit -m "chore: add language metadata to config.json for v0.4.2+"
-   ```
-
-#### Automated Update (via `/alfred:0-project`)
-
-Running `/alfred:0-project` on an existing project will:
-1. Detect current language settings
-2. Add new fields automatically
-3. Preserve existing values
-
-**No manual action required if running `/alfred:0-project` after upgrade.**
-
-#### Field Mapping (Legacy → New)
-
-| Old Field | New Field | Migration Rule |
-|-----------|-----------|-----------------|
-| `locale` | `conversation_language` | Keep as-is (or run `/alfred:0-project` to re-select) |
-| (none) | `conversation_language_name` | Auto-populate from locale mapping |
-| `language` | `codebase_languages` | Wrap in array: `"python"` → `["python"]` |
-
-#### Backward Compatibility
-
-- ✅ Projects without new fields will continue working
-- ⚠️ New language features (multilingual documentation) unavailable without migration
-- ✅ `/alfred:0-project` automatically migrates on next run
-- ✅ Auto-detection will prefer new fields if present
-
----
-
-## Design Principles
-
-### 1. DRY (Don't Repeat Yourself)
-- ❌ **Remove**: the `reference` field (every SPEC referenced the same master plan)
-- ✅ **Instead**: document project-level resources in README.md
-
-### 2. Context-Aware
-- Include only the necessary context.
-- Use optional fields only when they add value.
-
-### 3. Traceable
-- Use `depends_on`, `blocks`, and `related_specs` to map dependencies.
-- Automated tooling can detect cyclic references.
-
-### 4. Maintainable
-- Every field must be machine-verifiable.
-- Maintain consistent formatting for easy parsing.
-
-### 5. Simple First
-- Keep complexity low.
-- Limit to 7 required + 9 optional fields.
-- Expand gradually when justified.
-
----
-
-**Last Updated**: 2025-10-06  
-**Author**: @Alfred

moai_adk/templates/.moai/project/product.md

@@ -1,161 +0,0 @@
----
-id: PRODUCT-001
-version: 0.1.3
-status: active
-created: 2025-10-01
-updated: 2025-10-17
-author: @project-owner
-priority: high
----
-
-# {{PROJECT_NAME}} Product Definition
-
-## HISTORY
-
-### v0.1.3 (2025-10-17)
-- **UPDATED**: Template version synced (v0.3.8)
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Mission (finalized team of 12 agents: Alfred + 11 specialists)
-  - Added implementation-planner, tdd-implementer, quality-gate
-  - Split code-builder into implementation-planner + tdd-implementer + quality-gate
-
-### v0.1.2 (2025-10-17)
-- **UPDATED**: Agent count adjusted (9 → 11)
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Mission (updated Alfred SuperAgent roster)
-
-### v0.1.1 (2025-10-17)
-- **UPDATED**: Template defaults aligned with the real MoAI-ADK project
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Mission, User, Problem, Strategy, Success populated with project context
-
-### v0.1.0 (2025-10-01)
-- **INITIAL**: Authored the product definition document
-- **AUTHOR**: @project-owner
-- **SECTIONS**: Mission, User, Problem, Strategy, Success, Legacy
-
----
-
-## @DOC:MISSION-001 Core Mission
-
-> **"No SPEC, no CODE."**
-
-{{PROJECT_NAME}} combats Frankenstein code at the root by enforcing a **SPEC-first TDD methodology**.
-
-### Core Value Proposition
-
-#### Four Key Values
-
-1. **Consistency**: A three-step SPEC → TDD → Sync pipeline safeguards delivery quality.
-2. **Quality**: TRUST principles (Test First, Readable, Unified, Secured, Trackable) apply automatically.
-3. **Traceability**: The @TAG system (`@SPEC → @TEST → @CODE → @DOC`) preserves end-to-end lineage.
-4. **Universality**: Supports diverse programming languages and frameworks.
-
-#### Alfred SuperAgent
-
-**Alfred** coordinates a team of 12 AI agents (Alfred + 11 specialists):
-- **spec-builder** 🏗️: Authors SPECs (EARS pattern) – Sonnet
-- **implementation-planner** 📋: Analyzes SPECs and derives implementation plans – Sonnet
-- **tdd-implementer** 🔬: Executes RED–GREEN–REFACTOR cycles – Sonnet
-- **quality-gate** 🛡️: Enforces TRUST principles – Haiku
-- **doc-syncer** 📖: Maintains living documentation – Haiku
-- **tag-agent** 🏷️: Manages the TAG system – Haiku
-- **git-manager** 🚀: Automates Git workflows – Haiku
-- **debug-helper** 🔍: Diagnoses runtime issues – Sonnet
-- **trust-checker** ✅: Verifies TRUST compliance – Haiku
-- **cc-manager** 🛠️: Configures Claude Code – Sonnet
-- **project-manager** 📂: Bootstraps projects – Sonnet
-
-## @SPEC:USER-001 Primary Users
-
-### Primary Audience
-- **Who**: [Describe your main user segment]
-- **Core Needs**: [Explain the problems they want solved]
-- **Critical Scenarios**: [Outline their primary usage scenarios]
-
-### Secondary Audience (Optional)
-- **Who**: [Describe any secondary user group]
-- **Needs**: [Capture their requirements]
-
-## @SPEC:PROBLEM-001 Problems to Solve
-
-### High Priority
-1. [Top problem to resolve]
-2. [Second critical problem]
-3. [Third critical problem]
-
-### Medium Priority
-- [Problems with moderate urgency]
-
-### Current Failure Cases
-- [Limitations or failure patterns in existing solutions]
-
-## @DOC:STRATEGY-001 Differentiators & Strengths
-
-### Strengths Versus Alternatives
-1. [Primary differentiator]
-   - **When it matters**: [Scenario where the strength shines]
-
-2. [Second differentiator]
-   - **When it matters**: [Concrete usage example]
-
-## @SPEC:SUCCESS-001 Success Metrics
-
-### Immediately Measurable KPIs
-1. [Metric 1]
-   - **Baseline**: [Target value and measurement approach]
-
-2. [Metric 2]
-   - **Baseline**: [Target value and measurement approach]
-
-### Measurement Cadence
-- **Daily**: [Metrics tracked daily]
-- **Weekly**: [Metrics tracked weekly]
-- **Monthly**: [Metrics tracked monthly]
-
-## Legacy Context
-
-### Existing Assets
-- [Reusable assets or resources]
-- [Relevant past projects or experience]
-
-## TODO:SPEC-BACKLOG-001 Next SPEC Candidates
-
-1. **SPEC-001**: [First feature to implement]
-2. **SPEC-002**: [Second feature to implement]
-3. **SPEC-003**: [Third feature to implement]
-
-## EARS Requirement Authoring Guide
-
-### EARS (Easy Approach to Requirements Syntax)
-
-Use these EARS patterns to keep SPEC requirements structured:
-
-#### EARS Patterns
-1. **Ubiquitous Requirements**: The system shall provide [capability].
-2. **Event-driven Requirements**: WHEN [condition], the system shall [behaviour].
-3. **State-driven Requirements**: WHILE [state], the system shall [behaviour].
-4. **Optional Features**: WHERE [condition], the system may [behaviour].
-5. **Constraints**: IF [condition], the system shall enforce [constraint].
-
-#### Sample Application
-```markdown
-### Ubiquitous Requirements (Foundational)
-- The system shall provide user management capabilities.
-
-### Event-driven Requirements
-- WHEN a user signs up, the system shall send a welcome email.
-
-### State-driven Requirements
-- WHILE a user remains logged in, the system shall display a personalized dashboard.
-
-### Optional Features
-- WHERE an account is premium, the system may offer advanced features.
-
-### Constraints
-- IF an account is locked, the system shall reject login attempts.
-```
-
----
-
-_This document serves as the baseline when `/alfred:1-plan` runs._

moai_adk/templates/.moai/project/structure.md

@@ -1,156 +0,0 @@
----
-id: STRUCTURE-001
-version: 0.1.1
-status: active
-created: 2025-10-01
-updated: 2025-10-17
-author: @architect
-priority: medium
----
-
-# {{PROJECT_NAME}} Structure Design
-
-## HISTORY
-
-### v0.1.1 (2025-10-17)
-- **UPDATED**: Template version synced (v0.3.8)
-- **AUTHOR**: @Alfred
-- **SECTIONS**: Metadata standardization (single `author` field, added `priority`)
-
-### v0.1.0 (2025-10-01)
-- **INITIAL**: Authored the structure design document
-- **AUTHOR**: @architect
-- **SECTIONS**: Architecture, Modules, Integration, Traceability
-
----
-
-## @DOC:ARCHITECTURE-001 System Architecture
-
-### Architectural Strategy
-
-**[Describe the end-to-end architectural approach for the project]**
-
-```
-Project Architecture
-- [Layer 1]          # [Describe its responsibilities]
-- [Layer 2]          # [Describe its responsibilities]
-- [Layer 3]          # [Describe its responsibilities]
-- [Layer 4]          # [Describe its responsibilities]
-```
-
-**Rationale**: [Explain the trade-offs behind the chosen architecture]
-
-## @DOC:MODULES-001 Module Responsibilities
-
-### 1. [Primary Module 1]
-
-- **Responsibilities**: [Key duties of the module]
-- **Inputs**: [Data it consumes]
-- **Processing**: [Core processing steps]
-- **Outputs**: [Produced artifacts]
-
-| Component     | Role   | Key Capabilities |
-| ------------- | ------ | ---------------- |
-| [Component 1] | [Role] | [Feature list]   |
-| [Component 2] | [Role] | [Feature list]   |
-
-### 2. [Primary Module 2]
-
-- **Responsibilities**: [Key duties of the module]
-- **Inputs**: [Data it consumes]
-- **Processing**: [Core processing steps]
-- **Outputs**: [Produced artifacts]
-
-## @DOC:INTEGRATION-001 External Integrations
-
-### [External System 1] Integration
-
-- **Authentication**: [Method used]
-- **Data Exchange**: [Formats and protocols]
-- **Failure Handling**: [Fallback strategy]
-- **Risk Level**: [Risk profile and mitigation]
-
-### [External System 2] Integration
-
-- **Purpose**: [Why it is used]
-- **Dependency Level**: [Degree of reliance and alternatives]
-- **Performance Requirements**: [Latency, throughput, etc.]
-
-## @DOC:TRACEABILITY-001 Traceability Strategy
-
-### Applying the TAG Framework
-
-**Full TDD Alignment**: SPEC → Tests → Implementation → Documentation
-- `@SPEC:ID` (`.moai/specs/`) → `@TEST:ID` (`tests/`) → `@CODE:ID` (`src/`) → `@DOC:ID` (`docs/`)
-
-**Implementation Detail Levels**: Annotation within `@CODE:ID`
-- `@CODE:ID:API` – REST APIs, GraphQL endpoints
-- `@CODE:ID:UI` – Components, views, screens
-- `@CODE:ID:DATA` – Data models, schemas, types
-- `@CODE:ID:DOMAIN` – Business logic, domain rules
-- `@CODE:ID:INFRA` – Infrastructure, databases, integrations
-
-### Managing TAG Traceability (Code-Scan Approach)
-
-- **Verification**: Run `/alfred:3-sync`, which scans with `rg '@(SPEC|TEST|CODE|DOC):' -n`
-- **Coverage**: Full project source (`.moai/specs/`, `tests/`, `src/`, `docs/`)
-- **Cadence**: Validate whenever the code changes
-- **Code-First Principle**: TAG truth lives in the source itself
-
-## Legacy Context
-
-### Current System Snapshot
-
-**[Describe the existing system or assets]**
-
-```
-Current System/
-├── [Component 1]/     # [Current state]
-├── [Component 2]/     # [Current state]
-└── [Component 3]/     # [Current state]
-```
-
-### Migration Considerations
-
-1. **[Migration item 1]** – [Plan and priority]
-2. **[Migration item 2]** – [Plan and priority]
-3. **[Migration item 3]** – [Plan and priority]
-
-## TODO:STRUCTURE-001 Structural Improvements
-
-1. **Define module interfaces** – [Plan details]
-2. **Dependency management strategy** – [Plan details]
-3. **Scalability roadmap** – [Plan details]
-
-## EARS for Architectural Requirements
-
-### Applying EARS to Architecture
-
-Use EARS patterns to write clear architectural requirements:
-
-#### Architectural EARS Example
-```markdown
-### Ubiquitous Requirements (Baseline Architecture)
-- The system shall adopt a layered architecture.
-- The system shall maintain loose coupling across modules.
-
-### Event-driven Requirements
-- WHEN an external API call fails, the system shall execute fallback logic.
-- WHEN a data change event occurs, the system shall notify dependent modules.
-
-### State-driven Requirements
-- WHILE the system operates in scale-out mode, it shall load new modules dynamically.
-- WHILE in development mode, the system shall provide verbose debug information.
-
-### Optional Features
-- WHERE the deployment runs in the cloud, the system may use distributed caching.
-- WHERE high performance is required, the system may apply in-memory caching.
-
-### Constraints
-- IF the security level is elevated, the system shall encrypt all inter-module communication.
-- Each module shall keep cyclomatic complexity under 15.
-```
-
----
-
-_This structure informs the TDD implementation when `/alfred:2-run` runs._