moai-adk 0.4.7__py3-none-any.whl → 0.4.8__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-cc-claude-md/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: "Authoring CLAUDE.md Project Instructions"
+description: "Design project-specific AI guidance, document workflows, define architecture patterns. Use when creating CLAUDE.md files for projects, documenting team standards, or establishing AI collaboration guidelines."
+allowed-tools: "Read, Write, Edit, Glob"
+---
+
+# Authoring CLAUDE.md Project Instructions
+
+CLAUDE.md is a Markdown file that provides Claude with project-specific context, workflows, standards, and guidance. It acts as a living document for AI collaboration patterns.
+
+## CLAUDE.md File Location & Purpose
+
+**Location**: `./{PROJECT_ROOT}/CLAUDE.md` or `/~/.claude/CLAUDE.md` (personal)
+
+**Purpose**: Tell Claude about your project before every session starts.
+
+## Core Sections
+
+### Section 1: Project Overview
+
+```markdown
+# Project Name
+
+**Description**: What does this project do?
+
+**Repository**: GitHub URL
+**Tech Stack**: Technologies, languages, frameworks
+**Team**: Size, roles
+**Status**: Active, archived, experimental
+```
+
+### Section 2: Core Workflow
+
+```markdown
+## Development Workflow
+
+### Phase 1: Planning
+- Use `/alfred:1-plan` for SPEC creation
+- EARS syntax: Ubiquitous, Event-driven, State-driven, Optional, Constraints
+- Store in `.moai/specs/`
+
+### Phase 2: Implementation (TDD)
+- RED: Write failing tests
+- GREEN: Minimal implementation
+- REFACTOR: Improve quality
+- Tools: pytest, TypeScript, mypy, ruff
+
+### Phase 3: Sync & Documentation
+- Run `/alfred:3-sync` to validate
+- Update Living Documents
+- Verify @TAG chains
+- Prepare PR
+```
+
+### Section 3: Code Standards
+
+```markdown
+## Code Standards (TRUST 5 Principles)
+
+### T - Test First
+- Target coverage: ≥ 85%
+- Framework: pytest for Python, Jest for TypeScript
+- Pattern: TDD (RED → GREEN → REFACTOR)
+
+### R - Readable
+- Max file: 300 LOC
+- Max function: 50 LOC
+- Max params: 5
+- Use linters: ruff (Python), ESLint (TypeScript)
+
+### U - Unified
+- Type safety: mypy for Python, TypeScript strict mode
+- Consistent patterns across domain
+- Shared utilities in `src/core/`
+
+### S - Secured
+- Input validation everywhere
+- No hardcoded secrets
+- Use environment variables
+- Run: bandit (Python), npm audit
+
+### T - Trackable
+- @TAG system: @SPEC:ID, @TEST:ID, @CODE:ID, @DOC:ID
+- Document all changes in HISTORY section
+- Link code to SPEC requirements
+```
+
+### Section 4: Project Architecture
+
+```markdown
+## Architecture
+
+### Directory Structure
+```
+src/
+├── core/          # Shared utilities, domain models
+├── domain/        # Business logic, DOMAIN-specific
+├── interfaces/    # API endpoints, CLI commands
+├── middleware/    # Cross-cutting concerns
+└── infra/         # Database, external services
+
+tests/
+├── unit/          # Unit tests for core/ and domain/
+├── integration/   # API, database tests
+└── e2e/          # End-to-end workflows
+```
+
+### Key Design Decisions
+- Monolithic backend (for now)
+- Database: PostgreSQL with migrations
+- Authentication: JWT tokens
+- API: REST with OpenAPI docs
+```
+
+### Section 5: AI Collaboration Patterns
+
+```markdown
+## Working with Claude Code
+
+### When to Use Sub-agents
+- `debug-helper`: Errors, test failures, exceptions
+- `security-auditor`: Vulnerability assessment, OWASP checks
+- `architect`: Refactoring, system design, scalability
+- `code-reviewer`: Quality analysis, SOLID violations
+
+### Commands Available
+- `/alfred:1-plan "feature description"` — Create SPEC
+- `/alfred:2-run SPEC-ID` — Implement (TDD)
+- `/alfred:3-sync` — Sync docs and validate
+- `/review-code src/**/*.ts` — Code review
+- `/deploy [env]` — Deploy pipeline
+
+### Context Engineering Tips
+- Always mention relevant SPEC ID
+- Provide file paths relative to project root
+- Link to similar existing features
+- Mention constraints or non-negotiables upfront
+```
+
+### Section 6: Known Gotchas & Decisions
+
+```markdown
+## Important Notes
+
+### Why We Use SPEC-First
+- Clarifies requirements upfront
+- Prevents scope creep
+- Enables parallel work (different SPECs)
+- Makes code changes traceable
+
+### Common Mistakes to Avoid
+- ❌ Implementing without SPEC
+- ❌ Skipping tests for "quick" fixes
+- ❌ Mixing multiple features in one PR
+- ❌ Ignoring @TAG system
+
+### Team Decisions
+- Use pytest fixtures for mocking (not monkeypatch)
+- All API responses must include status codes
+- Database migrations are CI/CD blocking
+- Security audit runs on every PR
+```
+
+## CLAUDE.md Examples by Domain
+
+### Example 1: Web API Project
+```markdown
+# Transaction API
+
+**Tech Stack**: Python (FastAPI), PostgreSQL, pytest
+
+## Phase Workflow
+
+1. **SPEC**: Requirements in EARS syntax
+   - Example: `The API must validate transaction amounts > 0`
+   - Stored in: `.moai/specs/SPEC-TRANS-{###}/spec.md`
+
+2. **TDD**: Implement with test-first approach
+   - Tests: `tests/integration/test_transactions.py`
+   - Code: `src/domain/transaction.py`
+
+3. **Sync**: Verify completeness
+   - Run: `/alfred:3-sync`
+   - Check: TAG chain integrity
+```
+
+### Example 2: React Frontend Project
+```markdown
+# Competition Dashboard
+
+**Tech Stack**: TypeScript, React 19, Vitest, Tailwind
+
+## Development Standards
+
+- Framework: Next.js 15 (App Router)
+- Testing: Vitest + React Testing Library
+- Styling: Tailwind CSS with shadcn/ui
+- State: Zustand for client state, Server Components for data
+
+## Key Patterns
+- Server Components for data fetching
+- Suspense boundaries for loading states
+- Error boundaries for graceful failures
+```
+
+## High-Freedom: Architectural Decisions
+
+```markdown
+## Why This Architecture?
+
+### Monolith vs Microservices
+- **Chosen**: Monolithic backend
+- **Reason**: Team < 10, throughput manageable
+- **When to reconsider**: >10M requests/month or 3+ teams
+
+### Database: PostgreSQL
+- **Reason**: Strong ACID guarantees, mature ecosystem
+- **Alternatives considered**: MongoDB (rejected: unclear schema)
+```
+
+## Medium-Freedom: Workflow Definition
+
+```markdown
+## Code Review Checklist
+
+Before merging, reviewer must verify:
+1. [ ] SPEC ID linked in PR description
+2. [ ] All tests passing (>85% coverage)
+3. [ ] No security issues (bandit clean)
+4. [ ] Code follows TRUST 5 principles
+5. [ ] @TAG chain complete (@SPEC → @TEST → @CODE → @DOC)
+6. [ ] CHANGELOG updated
+```
+
+## Low-Freedom: Explicit Rules
+
+```markdown
+## Non-negotiable Rules
+
+- ❌ No commits without @TAG references
+- ❌ No merging PRs without passing tests
+- ❌ No pushing secrets to repo
+- ❌ No force-pushing to main/master
+- ✅ All features must have SPEC document
+- ✅ All code changes must have corresponding tests
+- ✅ All SPECs must use EARS syntax
+```
+
+## Validation Checklist
+
+- [ ] Project name and description clear
+- [ ] Tech stack documented
+- [ ] Development workflow defined (Plan → Run → Sync)
+- [ ] TRUST 5 principles explained
+- [ ] Architecture diagram or structure described
+- [ ] AI collaboration patterns defined
+- [ ] Known gotchas documented
+- [ ] Examples provided for key workflows
+
+## Best Practices
+
+✅ **DO**:
+- Keep CLAUDE.md up-to-date as standards evolve
+- Include real examples (links to actual files/PRs)
+- Document why (not just what)
+- Link to external docs (architecture decisions, security policy)
+- Review with team before finalizing
+
+❌ **DON'T**:
+- Explain general programming concepts (Claude already knows)
+- List every possible workflow (focus on your specific patterns)
+- Write as instruction to humans (write as guidance to Claude)
+- Update CLAUDE.md only at project start (evolve as needed)
+
+---
+
+**Reference**: Claude Code CLAUDE.md documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-claude-md/templates/CLAUDE-template.md

@@ -0,0 +1,26 @@
+# Project Name
+
+**Description**: What does this project do?
+
+## Development Workflow
+
+### Phase 1: Planning
+- Use `/alfred:1-plan` for SPEC creation
+- Use EARS syntax
+
+### Phase 2: Implementation (TDD)
+- RED: Write failing tests
+- GREEN: Minimal implementation
+- REFACTOR: Improve quality
+
+### Phase 3: Sync & Documentation
+- Run `/alfred:3-sync`
+- Update Living Documents
+
+## Code Standards (TRUST 5)
+
+- **T**est First: ≥85% coverage
+- **R**eadable: Max 300 LOC per file
+- **U**nified: Type safety
+- **S**ecured: Input validation
+- **T**rackable: @TAG system

moai_adk/templates/.claude/skills/moai-cc-commands/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: "Designing Slash Commands for Claude Code"
+description: "Create and optimize slash commands with proper argument parsing, tool permissions, and agent orchestration. Use when building workflow entry points, automation commands, or user-facing shortcuts."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
+---
+
+# Designing Slash Commands
+
+Slash commands are user-facing entry points that orchestrate sub-agents, manage approvals, and coordinate multi-step workflows. They follow the Plan → Execute → Sync cadence.
+
+## Command File Structure
+
+**Location**: `.claude/commands/`
+
+```yaml
+---
+name: command-name
+description: Brief description of what the command does
+argument-hint: "[param1] [param2] [optional-param]"
+tools: Read, Write, Task, Bash(git:*)
+model: sonnet
+---
+
+# Command Title
+
+Brief description of functionality.
+
+## Usage
+
+- `/command-name param1 param2` — Basic usage
+- Parameter descriptions
+- Expected behavior
+
+## Agent Orchestration
+
+1. Call specific agent for task
+2. Handle results
+3. Provide user feedback
+```
+
+## Command Design Patterns
+
+### Pattern 1: Planning Command
+```yaml
+---
+name: /alfred:1-plan
+description: Write SPEC requirements in EARS syntax
+argument-hint: "[title]"
+tools: Read, Write, Task
+model: sonnet
+---
+
+# SPEC Planning Command
+
+Initiates SPEC authoring via spec-builder sub-agent.
+
+## Usage
+
+`/alfred:1-plan "User authentication system"`
+
+## Agent Orchestration
+
+1. Invoke spec-builder agent
+2. Gather requirements via EARS patterns
+3. Create SPEC file in `.moai/specs/`
+4. Suggest next step: `/alfred:2-run`
+```
+
+### Pattern 2: Code Review Command
+```yaml
+---
+name: /review-code
+description: Trigger automated code review with quality analysis
+argument-hint: "[file-pattern] [--strict]"
+tools: Read, Glob, Grep, Task
+model: sonnet
+---
+
+# Code Review Command
+
+Analyzes code quality against TRUST 5 principles.
+
+## Usage
+
+- `/review-code src/**/*.ts` — Review TypeScript files
+- `/review-code . --strict` — Strict mode (fail on warnings)
+
+## Agent Orchestration
+
+1. Scan files matching pattern
+2. Invoke code-reviewer agent
+3. Generate report with findings
+4. Suggest fixes with severity levels
+```
+
+### Pattern 3: Deployment Command
+```yaml
+---
+name: /deploy
+description: Deploy application with safety gates
+argument-hint: "[env] [--force]"
+tools: Read, Write, Task, Bash(git:*)
+model: haiku
+---
+
+# Deployment Command
+
+Orchestrates multi-step deployment with approval gates.
+
+## Usage
+
+- `/deploy staging` — Deploy to staging
+- `/deploy production --force` — Force production deploy
+
+## Agent Orchestration
+
+1. Validate deployment readiness
+2. Run pre-deployment checks
+3. Ask for user approval
+4. Execute deployment
+5. Monitor post-deployment
+```
+
+## Argument Parsing Pattern
+
+```bash
+# Inside command execution
+$ARGUMENTS              # Entire argument string
+$1, $2, $3            # Individual arguments
+$@                    # All arguments as array
+
+# Example: /my-command arg1 arg2 --flag
+# $ARGUMENTS = "arg1 arg2 --flag"
+# $1 = "arg1"
+# $2 = "arg2"
+# $3 = "--flag"
+```
+
+## High-Freedom: Orchestration Strategies
+
+### Sequential Execution
+```
+Command: /plan-and-implement
+├─ Phase 1: spec-builder (SPEC creation)
+└─ Phase 2: code-builder (TDD implementation)
+```
+
+### Parallel Execution
+```
+Command: /analyze-project
+├─ Agent 1: security-auditor (vulnerability scan)
+├─ Agent 2: performance-analyzer (bottleneck detection)
+└─ Agent 3: architecture-reviewer (design review)
+```
+
+### Conditional Branching
+```
+Command: /fix-errors
+├─ Check: Are tests failing?
+│  ├─ YES → debug-helper agent
+│  └─ NO → suggest next steps
+```
+
+## Medium-Freedom: Command Templates
+
+### Status Check Command
+```yaml
+name: /status
+description: Show project status summary
+argument-hint: "[--verbose]"
+tools: Read, Bash(git:*)
+model: haiku
+---
+
+# Status Check
+
+Displays project health: SPEC status, test results, Git state.
+
+## Checks
+
+1. SPEC completeness
+2. Test coverage
+3. Git branch status
+4. Recent commits
+5. TODO items
+```
+
+### Bulk Operation Command
+```yaml
+name: /migrate
+description: Run migration across multiple files
+argument-hint: "[from] [to] [--preview]"
+tools: Read, Glob, Bash
+model: sonnet
+---
+
+# Migration Command
+
+Migrates code patterns across project.
+
+## Usage
+
+- `/migrate v1-api v2-api --preview` — Show changes without applying
+- `/migrate v1-api v2-api` — Apply migration
+```
+
+## Low-Freedom: Safety & Approval Patterns
+
+### Approval Gate Pattern
+```bash
+# Inside command execution
+
+echo "🔴 This action is destructive. Review carefully:"
+echo "  • Will delete 10 files"
+echo "  • Cannot be undone"
+echo ""
+read -p "Type 'yes' to confirm: " confirm
+
+if [[ "$confirm" != "yes" ]]; then
+  echo "❌ Cancelled"
+  exit 1
+fi
+
+# Execute dangerous operation
+```
+
+### Dry-Run Pattern
+```bash
+if [[ "${3:-}" == "--preview" ]]; then
+  echo "🔍 Preview mode (no changes)"
+  # Show what would happen
+  exit 0
+fi
+
+# Execute actual changes
+```
+
+## Command Registry
+
+```bash
+# List all commands
+/commands
+
+# View command details
+/commands view /deploy
+
+# Create new command
+/commands create
+
+# Edit command
+/commands edit /deploy
+
+# Delete command
+/commands delete /deploy
+```
+
+## Command Validation Checklist
+
+- [ ] `name` is kebab-case (e.g., `/review-code`)
+- [ ] `description` clearly explains purpose
+- [ ] `argument-hint` shows expected parameters
+- [ ] `tools` list is minimal and justified
+- [ ] `model` is `haiku` or `sonnet`
+- [ ] Agent orchestration is clearly defined
+- [ ] Arguments are properly parsed
+- [ ] Safety gates are in place for dangerous operations
+- [ ] Feedback to user is clear and actionable
+
+## Best Practices
+
+✅ **DO**:
+- Design commands around workflows, not tools
+- Use agents for complex logic
+- Include preview/dry-run modes for risky operations
+- Provide clear feedback at each step
+- Link to next command in suggestions
+
+❌ **DON'T**:
+- Make commands do too much (limit to 1 coherent workflow)
+- Require multiple parameters without defaults
+- Skip approval gates for destructive operations
+- Leave users guessing what happened
+
+---
+
+**Reference**: Claude Code Slash Commands documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-commands/templates/command-template.md

@@ -0,0 +1,21 @@
+---
+name: command-name
+description: Brief description of what the command does
+argument-hint: "[param1] [param2]"
+tools: Read, Write, Task
+model: sonnet
+---
+
+# Command Title
+
+Brief description of functionality.
+
+## Usage
+
+`/command-name param1 param2` — Basic usage
+
+## Agent Orchestration
+
+1. Call specific agent for task
+2. Handle results
+3. Provide user feedback