moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

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

@@ -0,0 +1,269 @@
+---
+name: moai-cc-agents
+description: "Creating and Managing Sub-agents in Claude Code. Design agent personas, define proactive triggers, set tool permissions, structure agent files. Use when building specialized agents for code review, debugging, architecture, or domain-specific tasks."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
+---
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Ops |
+| Auto-load | When creating or managing sub-agents |
+
+## What It Does
+
+Sub-agent 생성 및 관리를 위한 전체 가이드를 제공합니다. Agent persona 설계, proactive trigger 정의, tool 권한 설정, agent 파일 구조화 방법을 다룹니다.
+
+## When to Use
+
+- Sub-agent를 새로 생성할 때
+- 기존 agent의 권한이나 trigger 조건을 수정할 때
+- Agent 간 협업 패턴을 설계할 때
+- Tool access 최소화 원칙을 적용할 때
+
+
+# Creating and Managing Sub-agents
+
+Sub-agents are specialized Claude instances with independent context, custom prompts, and restricted tool access. They handle deep analysis, parallel work, and autonomous tasks.
+
+## Agent File Structure
+
+**Location**: `.claude/agents/`
+
+```yaml
+---
+name: agent-name
+description: Use PROACTIVELY for [specific trigger conditions]
+tools: Read, Write, Edit, Glob, Grep, Bash(git:*)
+model: sonnet
+---
+
+# Agent Name — Specialist Role
+
+Brief description of agent expertise.
+
+## Core Mission
+
+- Primary responsibility
+- Scope boundaries
+- Success criteria
+
+## Proactive Triggers
+
+- When to activate automatically
+- Specific conditions for invocation
+- Integration with workflow
+
+## Workflow Steps
+
+1. Input validation
+2. Task execution
+3. Output verification
+4. Handoff to next agent (if applicable)
+
+## Constraints
+
+- What NOT to do
+- Delegation rules
+- Quality gates
+```
+
+## Agent Persona Design Pattern
+
+```markdown
+---
+name: code-reviewer
+description: Use PROACTIVELY for code review requests, PR analysis, or quality checks
+tools: Read, Glob, Grep, Bash(git:*)
+model: sonnet
+---
+
+# Code Reviewer — Quality Expert
+
+Specialized in identifying code quality issues, security risks, and architecture concerns.
+
+## Core Mission
+
+- Review code for SOLID principles
+- Identify code smells and anti-patterns
+- Verify security best practices
+- Suggest improvements with rationale
+
+## Proactive Triggers
+
+- When user mentions "review", "quality", "audit"
+- After significant code changes
+- Before PR merge
+
+## Workflow Steps
+
+1. **Analyze**: Read changed files, understand context
+2. **Evaluate**: Check against TRUST 5 principles
+3. **Report**: List findings with severity & fix suggestions
+4. **Recommend**: Suggest refactoring or architectural improvements
+
+## Constraints
+
+- No direct edits (only suggestions)
+- Focus on maintainability, not style
+- Respect existing architecture decisions
+```
+
+## High-Freedom: Agent Principles
+
+### Autonomy & Expertise
+- Each agent owns 1 specialization (not 3+)
+- Define clear "when to activate" triggers
+- Agents should make decisions independently
+
+### Tool Access Minimization
+- Grant only necessary tools per role
+- Restrict Bash to specific commands: `Bash(git:*)`, `Bash(python:*)`
+- Never grant `Bash(*)`; always specify pattern
+
+### Handoff & Collaboration
+- Agent A completes → hands off to Agent B
+- Use clear "next agent" instructions
+- No circular dependencies
+
+## Medium-Freedom: Common Agent Patterns
+
+### Pattern 1: Debugger Agent
+```yaml
+name: debugger
+description: Use PROACTIVELY for error diagnosis, test failures, exception analysis
+tools: Read, Grep, Glob, Bash(pytest:*), Bash(git:*)
+model: sonnet
+```
+
+**Mission**: Diagnose errors, provide fix-forward guidance
+**Triggers**: `error`, `failed`, `exception`, `debug`
+**Output**: Root cause + suggested fixes
+
+### Pattern 2: Architect Agent
+```yaml
+name: architect
+description: Use PROACTIVELY for system design, refactoring, scalability concerns
+tools: Read, Glob, Grep, Bash(ls:*), Bash(find:*)
+model: sonnet
+```
+
+**Mission**: Design systems, propose architectures
+**Triggers**: `architecture`, `refactor`, `design`, `scalability`
+**Output**: Design document + implementation roadmap
+
+### Pattern 3: Security Agent
+```yaml
+name: security-auditor
+description: Use PROACTIVELY for vulnerability assessment, OWASP checks, secrets detection
+tools: Read, Glob, Grep
+model: sonnet
+```
+
+**Mission**: Find security issues, verify OWASP compliance
+**Triggers**: `security`, `audit`, `vulnerability`, `secrets`
+**Output**: Risk assessment + remediation steps
+
+## Low-Freedom: Tool Permission Patterns
+
+### Principle of Least Privilege
+
+```yaml
+# ❌ Too permissive
+tools: Read, Write, Edit, Bash(*)
+
+# ✅ Appropriate
+tools: Read, Glob, Grep  # Read-only analysis
+
+# ✅ Appropriate
+tools: Read, Edit, Bash(black:*), Bash(pytest:*)  # Formatter + tests only
+```
+
+### Bash Command Restrictions
+
+```yaml
+# Allowed patterns:
+Bash(git:*)           # All git commands
+Bash(npm run:*)       # Only npm run scripts
+Bash(python:*)        # Python interpreter
+Bash(pytest:*)        # Pytest runner
+
+# Denied patterns:
+Bash(rm:*)            # Dangerous deletion
+Bash(sudo:*)          # Privilege escalation
+Bash(curl:*)          # Arbitrary downloads
+```
+
+## Agent Execution Modes
+
+### Mode 1: Inline (main context)
+```bash
+/role security
+"Check this project for vulnerabilities"
+# Runs in main session context
+```
+
+### Mode 2: Sub-agent (isolated context)
+```bash
+/role security --agent
+"Perform comprehensive security audit"
+# Runs in independent context, can work in parallel
+```
+
+### Mode 3: Parallel Multi-role
+```bash
+/multi-role security,performance,qa --agent
+"Analyze security, performance, and quality"
+# All roles run in parallel, results merged
+```
+
+## Agent Registration & Discovery
+
+```bash
+# List available agents
+/agents
+
+# Create new agent interactively
+/agents create
+
+# View specific agent
+/agents view security-auditor
+
+# Edit agent
+/agents edit security-auditor
+
+# Delete agent
+/agents delete security-auditor
+```
+
+## Agent Validation Checklist
+
+- [ ] `name` is kebab-case (e.g., `code-reviewer`)
+- [ ] `description` includes "Use PROACTIVELY for"
+- [ ] `tools` list only necessary tools
+- [ ] No `Bash(*)` wildcard; specific patterns only
+- [ ] `model` is `haiku` or `sonnet`
+- [ ] `Proactive Triggers` section clearly defined
+- [ ] No overlapping responsibilities with other agents
+- [ ] YAML frontmatter is valid
+
+## Best Practices
+
+✅ **DO**:
+- Design agents around specific expertise
+- Use `--agent` flag for large analyses
+- Combine multiple agents for complex tasks
+- Name agents descriptively
+
+❌ **DON'T**:
+- Create overpowered agents with all tools
+- Allow direct file modifications without approval
+- Overlap agent responsibilities
+- Use `Bash(*)` without specific patterns
+
+---
+
+**Reference**: Claude Code Sub-agents documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-agents/templates/agent-template.md

@@ -0,0 +1,32 @@
+---
+name: agent-name
+description: Use PROACTIVELY for [specific trigger conditions]
+tools: Read, Glob, Grep, Bash(git:*)
+model: sonnet
+---
+
+# Agent Name — Specialist Role
+
+Brief description of agent expertise.
+
+## Core Mission
+
+- Primary responsibility
+- Scope boundaries
+- Success criteria
+
+## Proactive Triggers
+
+- When to activate automatically
+- Specific conditions for invocation
+
+## Workflow Steps
+
+1. Input validation
+2. Task execution
+3. Output verification
+
+## Constraints
+
+- What NOT to do
+- Delegation rules

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

@@ -0,0 +1,298 @@
+---
+name: moai-cc-claude-md
+description: "Authoring CLAUDE.md Project Instructions. 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"
+---
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| Version | 1.0.0 |
+| Tier | Ops |
+| Auto-load | When authoring CLAUDE.md files |
+
+## What It Does
+
+프로젝트별 CLAUDE.md 파일 작성을 위한 표준 구조와 패턴을 제공합니다. AI 협업 가이드라인, 워크플로우 문서화, 아키텍처 패턴 정의 방법을 다룹니다.
+
+## When to Use
+
+- 새 프로젝트의 CLAUDE.md 파일을 생성할 때
+- 기존 CLAUDE.md를 업데이트하거나 개선할 때
+- 팀 표준 및 개발 워크플로우를 문서화할 때
+- AI 협업 패턴을 정의할 때
+
+
+# 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