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

moai_adk/templates/.github/ISSUE_TEMPLATE/spec.yml

@@ -1,176 +0,0 @@
-name: 📋 SPEC Document
-description: Create a new SPEC document for feature planning
-title: "[SPEC-] "
-labels: ["spec", "planning"]
-assignees: []
-
-body:
-  - type: markdown
-    attributes:
-      value: |
-        ## 📋 SPEC Metadata
-
-        Fill out the SPEC details below. This will be synchronized with the SPEC document and GitHub Issue.
-
-  - type: input
-    id: spec-id
-    attributes:
-      label: SPEC ID
-      description: "Format: DOMAIN-###. Example: AUTH-001, API-DESIGN-001"
-      placeholder: "AUTH-001"
-    validations:
-      required: true
-
-  - type: input
-    id: spec-title
-    attributes:
-      label: SPEC Title
-      description: "Brief description of the specification"
-      placeholder: "JWT-based authentication system"
-    validations:
-      required: true
-
-  - type: dropdown
-    id: priority
-    attributes:
-      label: Priority
-      description: "Feature priority level"
-      options:
-        - "critical"
-        - "high"
-        - "medium"
-        - "low"
-    validations:
-      required: true
-
-  - type: dropdown
-    id: category
-    attributes:
-      label: Category
-      description: "SPEC category"
-      options:
-        - "API"
-        - "Backend"
-        - "Frontend"
-        - "Infrastructure"
-        - "Security"
-        - "Testing"
-        - "DevOps"
-        - "Documentation"
-        - "Performance"
-        - "Other"
-    validations:
-      required: true
-
-  - type: textarea
-    id: ubiquitous-requirements
-    attributes:
-      label: "Ubiquitous Requirements"
-      description: "Statements that apply universally to the system"
-      placeholder: |
-        - The system must provide JWT-based authentication
-        - The system must support token expiration
-      value: "### Ubiquitous\n"
-    validations:
-      required: true
-
-  - type: textarea
-    id: event-requirements
-    attributes:
-      label: "Event-driven Requirements (WHEN)"
-      description: "Event-triggered requirements in EARS format"
-      placeholder: |
-        - WHEN the user submits login credentials, the system must validate them against the database
-        - WHEN credentials are valid, the system must issue a JWT token with expiration
-      value: "### Event-driven (WHEN)\n"
-    validations:
-      required: false
-
-  - type: textarea
-    id: state-requirements
-    attributes:
-      label: "State-driven Requirements (WHILE)"
-      description: "State-based requirements in EARS format"
-      placeholder: |
-        - WHILE the token is unexpired, the system must allow access to protected resources
-        - WHILE the user is logged in, the system must track the session
-      value: "### State-driven (WHILE)\n"
-    validations:
-      required: false
-
-  - type: textarea
-    id: optional-requirements
-    attributes:
-      label: "Optional Requirements (WHERE)"
-      description: "Optional features and capabilities"
-      placeholder: |
-        - WHERE the user requests token refresh, the system can issue a new token
-        - WHERE OAuth2 is available, the system can support social login
-      value: "### Optional (WHERE)\n"
-    validations:
-      required: false
-
-  - type: textarea
-    id: constraints
-    attributes:
-      label: "Constraints (IF)"
-      description: "System constraints and conditions"
-      placeholder: |
-        - IF the token has expired, the system must return 401 Unauthorized
-        - IF the password is incorrect, the system must reject the login attempt
-      value: "### Constraints (IF)\n"
-    validations:
-      required: false
-
-  - type: textarea
-    id: acceptance-criteria
-    attributes:
-      label: "Acceptance Criteria (Given-When-Then)"
-      description: "At least 2-3 test scenarios"
-      placeholder: |
-        **Scenario 1: Successful Login**
-        - Given a user with valid credentials exists
-        - When the user submits their credentials
-        - Then the system returns a valid JWT token
-
-        **Scenario 2: Token Expiration**
-        - Given a user with an expired token
-        - When the user tries to access a protected resource
-        - Then the system returns a 401 Unauthorized response
-      value: "## Acceptance Criteria\n\n"
-    validations:
-      required: true
-
-  - type: textarea
-    id: dependencies
-    attributes:
-      label: "Dependencies"
-      description: "Related SPECs, tasks, or blockers"
-      placeholder: |
-        - Related: SPEC-SECURITY-001
-        - Blocks: SPEC-API-DESIGN-001
-        - Depends on: SPEC-DATABASE-001
-    validations:
-      required: false
-
-  - type: textarea
-    id: notes
-    attributes:
-      label: "Additional Notes"
-      description: "Technical notes, assumptions, or context"
-      placeholder: |
-        - Consider token refresh token rotation
-        - JWT payload should be minimal for performance
-        - Consider rate limiting on login attempts
-    validations:
-      required: false
-
-  - type: markdown
-    attributes:
-      value: |
-        ## 📚 Reference
-
-        - **SPEC Metadata Guide**: See `.moai/memory/spec-metadata.md`
-        - **EARS Syntax Guide**: See `.moai/memory/development-guide.md`
-        - **Acceptance Criteria**: Use Given-When-Then (Gherkin) format
-        - **@TAG System**: @SPEC, @TEST, @CODE, @DOC traceability

moai_adk/templates/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,69 +0,0 @@
-# MoAI-ADK GitFlow PR
-
-> 🗿 Full GitFlow Transparency — the agent auto-fills information
-
-## 📝 SPEC Info
-
-- Related SPEC: `SPEC-AUTH-001` (e.g., JWT authentication system)
-- Directory: `.moai/specs/SPEC-AUTH-001/`
-- @TAG Links: @SPEC:AUTH-001 @CODE:AUTH-001 (auto-tagging)
-
-## ✅ SPEC Quality Checks
-
-- [ ] YAML Front Matter: 7 required fields (id, version, status, created, updated, author, priority)
-- [ ] HISTORY Section: Record versioned change log (include v0.0.1 INITIAL)
-- [ ] EARS Requirements: Ubiquitous, Event-driven, State-driven, Optional, Constraints
-- [ ] @SPEC:ID TAG: Include TAG in doc and check duplicates (`rg "@SPEC:<ID>" -n`)
-
-## 🤖 Automated Validation Status
-
-<!-- The checklist below is auto-updated by the agent -->
-<!-- /alfred:1-plan → create feature branch → Draft PR -->
-<!-- /alfred:2-run → implement via TDD → auto-check checkboxes -->
-<!-- /alfred:3-sync → synchronize documents → Ready for Review -->
-
-- [ ] spec-builder: Complete EARS spec and create feature branch
-- [ ] code-builder: Finish TDD RED-GREEN-REFACTOR
-- [ ] doc-syncer: Sync Living Documents and mark PR Ready
-
-## 📊 Quality Metrics (auto-calculated)
-
-- TRUST 5 Principles: ✅ Compliant
-- Test Coverage: XX% (target ≥ 85%)
-- @TAG Traceability: 100%
-
-## 🌍 Locale Settings
-
-- Project Language: <!-- ko/en/ja/zh -->
-- Commit Messages: <!-- generated automatically according to locale -->
-
-## 🎯 Changes
-
-<!-- code-builder auto-fills TDD results -->
-
-### 🔴 RED (Test Authoring)
-- Test File: `tests/auth/service.test.ts`
-- Test Description: [describe the failing test]
-
-### 🟢 GREEN (Implementation)
-- Implementation File: `src/auth/service.ts`
-- Implementation Done: [describe functionality]
-
-### ♻️ REFACTOR (Improvements)
-- Refactoring Details: [code quality improvements]
-
-## 📚 Documentation Sync
-
-<!-- auto-filled by doc-syncer -->
-
-- [ ] Update README
-- [ ] Sync API docs
-- [ ] Update TAG index
-- [ ] Update HISTORY section (SPEC docs)
-
----
-
-🚀 MoAI-ADK: Professional development without Git commands via a 3-stage pipeline!
-
-Reviewers: Check TRUST 5 compliance and SPEC metadata completeness only.
-

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.