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

moai_adk/templates/.moai/memory/DEVELOPMENT-GUIDE.md

@@ -1,344 +0,0 @@
-# {{PROJECT_NAME}} Development Guide
-
-> "No spec, no code. No tests, no implementation."
-
-This unified guardrail applies to every agent and developer who uses the MoAI-ADK universal development toolkit. The Python-based toolkit supports all major programming languages and enforces a SPEC-first TDD methodology with @TAG traceability. English is the default working language.
-
----
-
-## SPEC-First TDD Workflow
-
-### Core Development Loop (3 Steps)
-
-1. **Write the SPEC** (`/alfred:1-plan`) → no code without a spec
-2. **Implement with TDD** (`/alfred:2-run`) → no implementation without tests
-3. **Sync Documentation** (`/alfred:3-sync`) → no completion without traceability
-
-### On-Demand Support
-
-- **Debugging**: summon `@agent-debug-helper` when failures occur
-- **CLI Commands**: init, doctor, status, update, restore, help, version
-- **System Diagnostics**: auto-detect language tooling and verify prerequisites
-
-Every change must comply with the @TAG system, SPEC-derived requirements, and language-specific TDD practices.
-
-### EARS Requirement Authoring
-
-**EARS (Easy Approach to Requirements Syntax)** provides a disciplined method for writing requirements.
-
-#### Five 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].
-
-#### Practical Example
-```markdown
-### Ubiquitous Requirements (Baseline)
-- The system shall provide user authentication.
-
-### Event-driven Requirements
-- WHEN a user logs in with valid credentials, the system shall issue a JWT token.
-- WHEN a token expires, the system shall return a 401 error.
-
-### State-driven Requirements
-- WHILE the user remains authenticated, the system shall allow access to protected resources.
-
-### Optional Features
-- WHERE a refresh token is present, the system may issue a new access token.
-
-### Constraints
-- IF an invalid token is supplied, the system shall deny access.
-- Access tokens shall not exceed a 15-minute lifetime.
-```
-
----
-
-## Context Engineering
-
-MoAI-ADK follows Anthropic's principles from “Effective Context Engineering for AI Agents” to keep context lean and relevant.
-
-### 1. JIT (Just-in-Time) Retrieval
-
-**Principle**: Load documents only when needed to minimize initial context load.
-
-**Alfred’s JIT Strategy**:
-
-| Command          | Required Load    | Optional Load                    | Timing                             |
-| ---------------- | ---------------- | -------------------------------- | ---------------------------------- |
-| `/alfred:1-plan` | product.md       | structure.md, tech.md            | While discovering SPEC candidates  |
-| `/alfred:2-run`  | SPEC-XXX/spec.md | development-guide.md             | At the start of TDD implementation |
-| `/alfred:3-sync` | sync-report.md   | TAG chain validation (`rg` scan) | During documentation sync          |
-
-**Implementation Notes**:
-- Alfred uses the `Read` tool to load only the necessary documents at command time.
-- Agents request only the documents relevant to their current task.
-- The five documents listed in CLAUDE.md “Memory Strategy” are always loaded.
-
-### Context Engineering Checklist
-
-**When designing commands**:
-- [ ] JIT: Do we load only the required documents?
-- [ ] Optional Load: Do we load documents conditionally?
-
-**When designing agents**:
-- [ ] Minimum tools: Does the YAML frontmatter declare only the needed tools?
-- [ ] Clear roles: Does each agent maintain a single responsibility?
-
----
-
-## TRUST Principles (5 Pillars)
-
-### T – Test-Driven Development (SPEC-Aligned)
-
-**SPEC → Test → Code Cycle**:
-
-- **SPEC**: Author detailed specifications first with `@SPEC:ID` tags (EARS format).
-- **RED**: `@TEST:ID` – write failing tests tied to SPEC requirements and confirm failure.
-- **GREEN**: `@CODE:ID` – implement the minimal code that passes the tests and satisfies the SPEC.
-- **REFACTOR**: `@CODE:ID` – improve the code while preserving SPEC compliance, then document with `@DOC:ID`.
-
-**Language-Specific TDD Tooling**:
-
-- **Python**: pytest + SPEC-based test cases (with mypy type hints)
-- **TypeScript**: Vitest + SPEC-driven suites (strict typing)
-- **Java**: JUnit + SPEC annotations (behaviour-driven tests)
-- **Go**: go test + SPEC table-driven tests (interface adherence)
-- **Rust**: cargo test + SPEC doc tests (trait validation)
-- **Ruby**: RSpec + SPEC-based BDD scenarios
-
-Each test links SPEC requirements to implementations via `@TEST:ID → @CODE:ID`.
-
-### R – Requirement-Driven Readability
-
-**SPEC-Aligned Clean Code**:
-
-- Functions implement SPEC requirements directly (≤ 50 LOC per function).
-- Names mirror SPEC terminology and domain language.
-- Code structure reflects SPEC design decisions.
-- Comments are limited to SPEC clarifications and @TAG references.
-
-**Language-Specific SPEC Implementation**:
-
-- **Python**: Type hints mirroring SPEC interfaces + mypy validation
-- **TypeScript**: Strict interfaces that match SPEC contracts
-- **Java**: Classes implementing SPEC components with strong typing
-- **Go**: Interfaces that satisfy SPEC requirements + gofmt
-- **Rust**: Types enforcing SPEC safety requirements + rustfmt
-- **Ruby**: Behaviour reflecting SPEC narratives + RuboCop validation
-
-Every code element must remain traceable back to the SPEC via @TAG comments.
-
-### U – Unified SPEC Architecture
-
-- **SPEC-Driven Complexity**: Each SPEC defines its complexity threshold. Exceeding it requires a new SPEC or a documented exception.
-- **SPEC vs. Implementation**: Keep authoring and implementation separate; never edit the SPEC mid-TDD cycle.
-- **Language Boundaries**: SPECs define boundaries across languages (Python modules, TypeScript interfaces, Java packages, Go packages, Rust crates, etc.).
-- **SPEC-Guided Architecture**: Domain boundaries follow the SPEC, not language conventions, with the @TAG system ensuring cross-language traceability.
-
-### S – SPEC-Compliant Security
-
-- **Security Requirements**: Every SPEC explicitly defines security needs, data sensitivity, and access control.
-- **Security by Design**: Implement security controls during the TDD cycle, not after completion.
-- **Language-Agnostic Security Patterns**:
-  - Input validation based on SPEC interface definitions
-  - Audit logging for SPEC-defined critical operations
-  - Access controls aligned with the SPEC permission model
-  - Secret management tailored to SPEC environment requirements
-
-### T – SPEC Traceability
-
-- **Spec-to-Code Traceability**: Every code change references SPEC IDs and requirements through the @TAG system.
-- **Three-Stage Workflow Trace**:
-  - `/alfred:1-plan`: Write SPECs with `@SPEC:ID` tags (`.moai/specs/`)
-  - `/alfred:2-run`: Implement via TDD with `@TEST:ID` (tests/) → `@CODE:ID` (src/)
-  - `/alfred:3-sync`: Sync documentation using `@DOC:ID` (docs/) and validate TAG coverage
-- **Code Scan Verification**: Guarantee TAG traceability by scanning the codebase directly with `rg '@(SPEC|TEST|CODE|DOC):' -n`, without intermediate caches.
-
----
-
-## SPEC-First Mindset
-
-1. **SPEC-Led Decisions**: Reference an existing SPEC or author a new one before making any technical decision. Never implement without clear requirements.
-2. **SPEC Context Review**: Read the relevant SPEC documents before changing code, understand the @TAG relationships, and confirm compliance.
-3. **SPEC Communication**: Default to English for collaboration. SPEC documents should use precise technical terminology and plain, unambiguous explanations.
-
-## SPEC-TDD Workflow
-
-1. **Start with the SPEC**: Author or reference a SPEC before writing code. Use `/alfred:1-plan` to clarify requirements, design, and tasks.
-2. **Implement with TDD**: Follow the Red–Green–Refactor loop rigorously using `/alfred:2-run` with language-appropriate testing frameworks.
-3. **Maintain Traceability**: Run `/alfred:3-sync` to update documentation and preserve @TAG relationships between SPECs and code.
-
-## @TAG System
-
-### Core Chain
-
-```text
-@SPEC:ID → @TEST:ID → @CODE:ID → @DOC:ID
-```
-
-**Perfect TDD Alignment**:
-- `@SPEC:ID` (Preparation) – requirements authored with the EARS pattern
-- `@TEST:ID` (RED) – failing tests derived from the SPEC
-- `@CODE:ID` (GREEN + REFACTOR) – implementation and refactoring
-- `@DOC:ID` (Documentation) – live documents that capture the outcome
-
-### TAG Block Template
-
-> **📋 SPEC Metadata Standard (SSOT)**: see `SPEC-METADATA.md`
-
-**Every SPEC document must include YAML front matter and a HISTORY section**:
-- **Required Fields (7)**: id, version, status, created, updated, author, priority
-- **Optional Fields (9)**: category, labels, depends_on, blocks, related_specs, related_issue, scope
-- **HISTORY Section**: log every version change (mandatory)
-
-Find the complete template, field descriptions, and validation commands in `SPEC-METADATA.md`.
-
-**Quick Reference Example**:
-```yaml
----
-id: AUTH-001
-version: 0.0.1
-status: draft
-created: 2025-09-15
-updated: 2025-09-15
-author: @Goos
-priority: high
----
-
-# @SPEC:AUTH-001: JWT Authentication System
-
-## HISTORY
-### v0.0.1 (2025-09-15)
-- **INITIAL**: Authored the JWT authentication system SPEC
-...
-```
-
-**Source Code (`src/`)**:
-```text
-# @CODE:AUTH-001 | SPEC: SPEC-AUTH-001.md | TEST: tests/auth/service.test.ts
-```
-
-**Test Code (`tests/`)**:
-```text
-# @TEST:AUTH-001 | SPEC: SPEC-AUTH-001.md
-```
-
-### @CODE Subcategories (Comment Level)
-
-Document implementation details inside `@CODE:ID` blocks:
-- `@CODE:ID:API` – REST APIs, GraphQL endpoints
-- `@CODE:ID:UI` – UI components, views, screens
-- `@CODE:ID:DATA` – data models, schemas, types
-- `@CODE:ID:DOMAIN` – business logic, domain rules
-- `@CODE:ID:INFRA` – infrastructure, databases, integrations
-
-### TAG Usage Rules
-
-- **TAG ID Format**: `<DOMAIN>-<3 digits>` (e.g., `AUTH-003`) – immutable once created.
-- **Directory Naming**: `.moai/specs/SPEC-{ID}/` (required)
-  - ✅ Valid: `SPEC-AUTH-001/`, `SPEC-REFACTOR-001/`, `SPEC-UPDATE-REFACTOR-001/`
-  - ❌ Invalid: `AUTH-001/`, `SPEC-001-auth/`, `SPEC-AUTH-001-jwt/`
-  - **Composite Domains**: hyphenated combinations allowed (e.g., `UPDATE-REFACTOR-001`)
-  - **Guideline**: Prefer fewer than three hyphen segments for clarity
-- **TAG Contents**: May evolve freely; always record the rationale in HISTORY.
-- **Versioning**: Semantic Versioning (v0.0.1 → v0.1.0 → v1.0.0)
-  - See `SPEC-METADATA.md#versioning` for details.
-- **Duplicate Check**: Run `rg "@SPEC:{ID}" -n .moai/specs/` before creating a new TAG.
-- **TAG Validation**: `rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/`
-- **Version Alignment**: `rg "SPEC-{ID}.md v" -n`
-- **Code-First Principle**: The source of truth for TAGs lives in the codebase.
-
-### HISTORY Authoring Guide
-
-**Change Type Tags**:
-- `INITIAL`: First release (v1.0.0)
-- `ADDED`: New requirement or capability → increment MINOR
-- `CHANGED`: Adjusted behaviour → increment PATCH
-- `FIXED`: Bug or defect fix → increment PATCH
-- `REMOVED`: Removed capability → increment MAJOR
-- `BREAKING`: Backward-incompatible change → increment MAJOR
-- `DEPRECATED`: Marked for future removal
-
-**Required Metadata**:
-- `AUTHOR`: Contributor (GitHub ID)
-- `REVIEW`: Reviewer and approval status
-- `REASON`: Why the change was made (optional but recommended for significant updates)
-- `RELATED`: Linked issues/PRs (optional)
-
-**HISTORY Search Examples**:
-```bash
-# View the full change log for a TAG
-rg -A 20 "# @SPEC:AUTH-001" .moai/specs/SPEC-AUTH-001.md
-
-# Extract only the HISTORY section
-rg -A 50 "## HISTORY" .moai/specs/SPEC-AUTH-001.md
-
-# Check the latest entries
-rg "### v[0-9]" .moai/specs/SPEC-AUTH-001.md | head -3
-```
-
----
-
-## Development Principles
-
-### Code Constraints
-
-- ≤ 300 LOC per file
-- ≤ 50 LOC per function
-- ≤ 5 parameters per function
-- Cyclomatic complexity ≤ 10
-
-### Quality Benchmarks
-
-- ≥ 85% test coverage
-- Use intention-revealing names
-- Prefer guard clauses
-- Leverage language-standard tooling
-
-### Refactoring Rules
-
-- **Rule of Three**: Plan refactoring when the same pattern appears a third time.
-- **Preparatory Refactoring**: Shape the code for easy change before applying the change.
-- **Tidy as You Go**: Fix small issues immediately; when scope expands, split into a dedicated effort.
-
-## Exception Handling
-
-When deviating from recommendations, document a waiver and attach it to the relevant PR, issue, or ADR.
-
-**Waiver Checklist**:
-
-- Justification and evaluated alternatives
-- Risks and mitigation plan
-- Temporary vs. permanent status
-- Expiry conditions and approver
-
-## Language Tooling Map
-
-- **Python**: pytest (tests), mypy (type checks), black (formatting)
-- **TypeScript**: Vitest (tests), Biome (lint + format)
-- **Java**: JUnit (tests), Maven/Gradle (build)
-- **Go**: go test (tests), gofmt (format)
-- **Rust**: cargo test (tests), rustfmt (format)
-- **Ruby**: RSpec (tests), RuboCop (lint + format), Bundler (packages)
-
-## Variable Role Reference
-
-| Role               | Description                        | Example                              |
-| ------------------ | ---------------------------------- | ------------------------------------ |
-| Fixed Value        | Constant after initialization      | `const MAX_SIZE = 100`               |
-| Stepper            | Changes sequentially               | `for (let i = 0; i < n; i++)`        |
-| Flag               | Boolean state indicator            | `let isValid = true`                 |
-| Walker             | Traverses a data structure         | `while (node) { node = node.next; }` |
-| Most Recent Holder | Holds the most recent value        | `let lastError`                      |
-| Most Wanted Holder | Holds optimal/maximum value        | `let bestScore = -Infinity`          |
-| Gatherer           | Accumulator                        | `sum += value`                       |
-| Container          | Stores multiple values             | `const list = []`                    |
-| Follower           | Previous value of another variable | `prev = curr; curr = next;`          |
-| Organizer          | Reorganizes data                   | `const sorted = array.sort()`        |
-| Temporary          | Temporary storage                  | `const temp = a; a = b; b = temp;`   |
-
----
-
-This guide defines the standards for executing the three-stage MoAI-ADK pipeline.

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