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

moai_adk/templates/.claude/skills/moai-alfred-context-budget/reference.md

@@ -1,405 +0,0 @@
-# Context Budget Management Guide
-
-## Overview
-
-- **Total context budget**: 200K tokens (Claude Sonnet 4.5)
-- **Session start overhead**: ~20K tokens (core files: CLAUDE.md, agents, commands, skills, memory)
-- **Available for work**: ~180K tokens
-- **Warning threshold**: 180K tokens (90% usage)
-- **Critical threshold**: 190K tokens (95% usage)
-
-## Progressive Loading Strategy
-
-### Load Priority Tiers
-
-#### Tier 1: CRITICAL (Always Load) — ~10K tokens
-
-**Must load at session start**:
-- `.moai/config.json` (project configuration)
-- `.moai/project/product.md` (business requirements)
-- `.moai/project/structure.md` (architecture design)
-- `.moai/project/tech.md` (technology stack)
-- `CLAUDE.md` (project directives)
-
-**Why**: These files define project scope, constraints, and workflow rules.
-
----
-
-#### Tier 2: HIGH (Load When Needed) — ~15K tokens
-
-**Load when working on specific SPEC**:
-- `.moai/specs/SPEC-{ID}/spec.md` (requirements)
-- `.moai/specs/SPEC-{ID}/plan.md` (implementation plan)
-- `.moai/specs/SPEC-{ID}/acceptance.md` (acceptance criteria)
-
-**Load when quality verification needed**:
-- `.moai/memory/development-guide.md` (TRUST principles)
-- `.moai/memory/spec-metadata.md` (SPEC standard)
-
-**Why**: Context-specific guidance needed only for active work.
-
----
-
-#### Tier 3: MEDIUM (Load On-Demand During Execution) — ~15K tokens
-
-**Load selectively during TDD implementation**:
-- Existing code references (src/ files related to current SPEC)
-- Test files (tests/ files related to current SPEC)
-- Related SPEC documents (dependencies, blockers)
-
-**Load during document sync**:
-- `.moai/reports/sync-report-latest.md` (previous sync state)
-- Documentation files (README, architecture docs)
-
-**Why**: Needed only when actively modifying or referencing.
-
----
-
-#### Tier 4: LOW (Load If Context Allows) — ~10K tokens
-
-**Optional context enhancements**:
-- Historical context (git log, SPEC history)
-- Examples and templates
-- Related Skills (moai-foundation-*, moai-alfred-*)
-- Agent instructions (spec-builder, tdd-implementer)
-
-**Why**: Helpful but not essential for task completion.
-
----
-
-## Agent-Specific Guidelines
-
-### spec-builder
-
-**Phase 1: Planning** (20-30K tokens)
-- **Tier 1**: Always load (product.md, structure.md, tech.md)
-- **Tier 2**: Load EARS standard, existing SPEC list
-- **Tier 3**: JIT load related SPEC examples
-
-**Phase 2: SPEC Creation** (30-40K tokens)
-- **Tier 1**: Maintain project documents
-- **Tier 2**: Load SPEC metadata standard
-- **Tier 3**: Load existing SPEC documents for reference
-
----
-
-### tdd-implementer
-
-**Phase 1: Analysis** (25-35K tokens)
-- **Tier 1**: Load SPEC documents (spec.md, plan.md, acceptance.md)
-- **Tier 2**: Load TDD workflow, development guide
-- **Tier 3**: JIT load existing test files
-
-**Phase 2: TDD Cycle** (40-60K tokens)
-- **Tier 1**: Maintain SPEC documents
-- **Tier 2**: Load implementation files (src/)
-- **Tier 3**: Load test files (tests/)
-- **Tier 4**: Load refactoring guidelines when needed
-
----
-
-### doc-syncer
-
-**Phase 1: Analysis** (30-40K tokens)
-- **Tier 1**: Load project documents
-- **Tier 2**: Load TAG scanning results
-- **Tier 3**: JIT load documentation files
-
-**Phase 2: Synchronization** (50-70K tokens)
-- **Tier 1**: Maintain project documents
-- **Tier 2**: Load SPEC documents
-- **Tier 3**: Load documentation files (README, architecture)
-- **Tier 4**: Load previous sync report for comparison
-
----
-
-### implementation-planner
-
-**Phase 1: SPEC Analysis** (20-30K tokens)
-- **Tier 1**: Load SPEC documents
-- **Tier 2**: Load project documents (architecture constraints)
-- **Tier 3**: JIT load existing code structure
-
-**Phase 2: Plan Creation** (30-40K tokens)
-- **Tier 1**: Maintain SPEC documents
-- **Tier 2**: Load development guide, TAG system
-- **Tier 3**: Load related implementation examples
-
----
-
-## Context Monitoring
-
-### Session Context Tracking
-
-**File**: `.moai/memory/session-context.json`
-
-```json
-{
-  "session_id": "2025-11-02-001",
-  "started_at": "2025-11-02T10:00:00Z",
-  "context_usage": {
-    "current_tokens": 45000,
-    "warning_threshold": 180000,
-    "critical_threshold": 190000,
-    "percent_used": 22.5
-  },
-  "loaded_files": [
-    ".moai/config.json",
-    ".moai/project/product.md",
-    ".moai/specs/SPEC-AUTH-001/spec.md",
-    "src/auth/service.py",
-    "tests/auth/test_service.py"
-  ],
-  "current_command": "alfred:2-run",
-  "current_spec": "SPEC-AUTH-001"
-}
-```
-
-### Warning Indicators
-
-**90% threshold (180K tokens)**:
-```
-⚠️ Context budget warning: 180K/200K tokens used (90%)
-Recommendation: Start new session with /clear for optimal performance
-```
-
-**95% threshold (190K tokens)**:
-```
-🚨 Context budget critical: 190K/200K tokens used (95%)
-Action required: Start new session immediately with /clear
-```
-
----
-
-## Optimization Tips
-
-### 1. Use Skill() for Large Content
-
-**Instead of loading entire files**:
-```python
-# ❌ BAD: Load entire 5K token file
-Read(".moai/memory/development-guide.md")
-
-# ✅ GOOD: Load specific Skill (~500 tokens)
-Skill("moai-foundation-trust")
-```
-
-**Benefits**:
-- Skill provides targeted guidance (~500 tokens)
-- Full file includes examples, history, unused sections (~5K tokens)
-- 10x efficiency improvement
-
----
-
-### 2. Read Files Selectively
-
-**Use grep/glob to get specific lines**:
-```python
-# ❌ BAD: Load entire codebase
-Glob("src/**/*.py")
-
-# ✅ GOOD: Load only related files
-Glob("src/auth/**/*.py")
-
-# ✅ BETTER: Search for specific patterns
-Grep("@CODE:AUTH-", path="src/")
-```
-
----
-
-### 3. Batch Related Operations
-
-**Parallelize to avoid multiple passes**:
-```python
-# ❌ BAD: Sequential reads (3 separate responses)
-Read(".moai/project/product.md")
-Read(".moai/project/structure.md")
-Read(".moai/project/tech.md")
-
-# ✅ GOOD: Parallel reads (1 response)
-# In a SINGLE response:
-Read(".moai/project/product.md")
-Read(".moai/project/structure.md")
-Read(".moai/project/tech.md")
-```
-
-**Performance impact**: 1.5-2x faster execution
-
----
-
-### 4. Clean Up Session Memory
-
-**Remove stale context between phases**:
-- After completing `/alfred:1-plan`, start new session with `/clear` before `/alfred:2-run`
-- After completing `/alfred:2-run`, start new session with `/clear` before `/alfred:3-sync`
-
-**Why**: Each phase has different context needs:
-- Planning phase: Product documents, SPEC examples
-- Implementation phase: SPEC documents, code files, tests
-- Sync phase: Documentation files, TAG chains
-
-Carrying over unused context wastes tokens.
-
----
-
-### 5. Use Context Pointers
-
-**Instead of loading full content, use pointers**:
-```markdown
-# ❌ BAD: Paste entire SPEC document (5K tokens)
-Full SPEC content here...
-
-# ✅ GOOD: Reference SPEC by ID (50 tokens)
-See SPEC-AUTH-001 for detailed requirements.
-Related TAGs: @SPEC:AUTH-001, @CODE:AUTH-001, @TEST:AUTH-001
-```
-
----
-
-## Command-Specific Context Budgets
-
-### /alfred:0-project (Project Initialization)
-
-**Expected usage**: 30-50K tokens
-- Phase 1: Analysis (20K)
-- Phase 2: Interview (30K)
-- Phase 3: Document creation (40K)
-
-**Strategy**: Load project documents progressively, avoid loading all Skills upfront.
-
----
-
-### /alfred:1-plan (SPEC Planning)
-
-**Expected usage**: 40-60K tokens
-- Phase 1: Project analysis (30K)
-- Phase 2: SPEC creation (50K)
-
-**Strategy**: Load product/structure/tech documents first, then SPEC standards JIT.
-
----
-
-### /alfred:2-run (TDD Implementation)
-
-**Expected usage**: 60-90K tokens
-- Phase 1: SPEC analysis (40K)
-- Phase 2: TDD cycle (70K)
-- Phase 3: Quality gate (80K)
-
-**Strategy**: Load SPEC documents first, then code/tests JIT during TDD cycle.
-
----
-
-### /alfred:3-sync (Document Synchronization)
-
-**Expected usage**: 70-100K tokens
-- Phase 1: TAG verification (50K)
-- Phase 2: Document sync (80K)
-
-**Strategy**: Load TAG inventory first, then documentation files JIT during sync.
-
----
-
-## Session Transition Best Practices
-
-### When to Start New Session
-
-**Recommended transition points**:
-1. ✅ After `/alfred:0-project` completion → `/clear` → `/alfred:1-plan`
-2. ✅ After `/alfred:1-plan` completion → `/clear` → `/alfred:2-run`
-3. ✅ After `/alfred:2-run` completion → `/clear` → `/alfred:3-sync`
-
-**Why**: Each command has different context needs. Starting fresh ensures optimal performance.
-
-### Session Handoff Pattern
-
-**Before starting new session**:
-1. Save session state to `.moai/memory/session-context.json`
-2. Note current SPEC ID, phase, and progress
-3. Run `/clear` to reset context
-4. Load only essential files for next phase
-
-**Example handoff**:
-```markdown
-✅ Implementation complete for SPEC-AUTH-001
-
-Session transition recommended:
-1. Run /clear to start fresh
-2. Load SPEC-AUTH-001 documents only
-3. Proceed with /alfred:3-sync for document sync
-
-Context saved to: .moai/memory/session-context.json
-```
-
----
-
-## Performance Metrics
-
-### Context Budget Impact on Response Time
-
-| Context Usage | Response Time | Recommendation                      |
-| ------------- | ------------- | ----------------------------------- |
-| 0-50K tokens  | Fast (1-2s)   | Optimal, continue                   |
-| 50-100K tokens| Normal (2-4s) | Good, monitor                       |
-| 100-150K tokens| Slower (4-6s) | Acceptable, plan transition         |
-| 150-180K tokens| Slow (6-8s)   | ⚠️ Warning, start new session soon |
-| 180-200K tokens| Very slow     | 🚨 Critical, start new session now |
-
----
-
-## Troubleshooting
-
-### Problem: Context budget exceeding 90%
-
-**Symptoms**:
-- Slow response times (>6s)
-- Warning messages about context usage
-- Difficulty loading new files
-
-**Solutions**:
-1. Start new session with `/clear`
-2. Load only Tier 1 files (CRITICAL)
-3. Use Skill() instead of Read() for large files
-4. Use Grep() instead of Glob() for file searches
-
----
-
-### Problem: Running out of context mid-task
-
-**Symptoms**:
-- Unable to load required files
-- "Context budget exceeded" errors
-- Incomplete responses
-
-**Solutions**:
-1. Save current progress to `.moai/memory/session-context.json`
-2. Start new session with `/clear`
-3. Load minimal context (current SPEC + implementation files only)
-4. Resume task from saved state
-
----
-
-## Summary
-
-**Golden Rules**:
-1. ✅ Load progressively: CRITICAL → HIGH → MEDIUM → LOW
-2. ✅ Use Skills over full files (10x efficiency)
-3. ✅ Parallelize independent reads (2x faster)
-4. ✅ Clean up between phases (start fresh with `/clear`)
-5. ✅ Monitor usage: 90% = warning, 95% = critical
-
-**Context Budget Formula**:
-```
-Available tokens = 200K total - 20K overhead = 180K
-Safe usage = 80% of available = 144K tokens
-```
-
-**When to transition**:
-- After each major command completion
-- When approaching 90% threshold (180K tokens)
-- When response times exceed 6 seconds
-
-**Performance targets**:
-- Context usage < 80% (144K tokens): Optimal
-- Context usage 80-90% (144-180K tokens): Acceptable, plan transition
-- Context usage > 90% (>180K tokens): Start new session immediately

moai_adk/templates/.claude/skills/moai-alfred-dev-guide/SKILL.md

@@ -1,51 +0,0 @@
----
-name: "Orchestrating SPEC-First TDD Development"
-description: "Guides agents through SPEC-First TDD workflow with context engineering, TRUST principles, and @TAG traceability. Essential for /alfred:1-plan, /alfred:2-run, /alfred:3-sync commands. Covers EARS requirements, JIT context loading, TDD RED-GREEN-REFACTOR cycle, and TAG chain validation."
-allowed-tools: "Read, Bash(rg:*), Bash(grep:*)"
----
-
-# Alfred Development Guide Skill
-
-## Core Workflow: SPEC → TEST → CODE → DOC
-
-**No spec, no code. No tests, no implementation.**
-
-### 1. SPEC Phase (`/alfred:1-plan`)
-- Author detailed specifications first with `@SPEC:ID` tags
-- Use EARS format (5 patterns: Ubiquitous, Event-driven, State-driven, Optional, Constraints)
-- Store in `.moai/specs/SPEC-{ID}/spec.md`
-
-### 2. TDD Phase (`/alfred:2-run`)
-- **RED**: Write failing tests with `@TEST:ID` tags
-- **GREEN**: Implement minimal code with `@CODE:ID` tags
-- **REFACTOR**: Improve code while maintaining SPEC compliance
-- Document with `@DOC:ID` tags
-
-### 3. SYNC Phase (`/alfred:3-sync`)
-- Verify @TAG chain integrity (SPEC→TEST→CODE→DOC)
-- Synchronize documentation with implementation
-- Generate sync report
-
-## Key Principles
-
-**Context Engineering**: Load only necessary documents at each phase
-- `/alfred:1-plan` → product.md, structure.md, tech.md
-- `/alfred:2-run` → SPEC-{ID}/spec.md, development-guide.md
-- `/alfred:3-sync` → sync-report.md, TAG validation
-
-**TRUST 5 Pillars**:
-1. **T** – Test-driven (RED→GREEN→REFACTOR)
-2. **R** – Readable (clear naming, documentation)
-3. **U** – Unified (consistent patterns, language)
-4. **S** – Secured (OWASP compliance, security reviews)
-5. **E** – Evaluated (metrics, coverage ≥85%)
-
-## Common Patterns
-
-| Scenario | Action |
-|----------|--------|
-| Write tests first | RED phase: failing tests with @TEST:ID |
-| Implement feature | GREEN phase: minimal code with @CODE:ID |
-| Refactor safely | REFACTOR phase: improve code structure |
-| Track changes | Always use @TAG system in code + docs |
-| Validate completion | `/alfred:3-sync` verifies all links |