moai-adk 0.15.1__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-claude/reference/claude-code-skills-official.md

@@ -0,0 +1,113 @@
+# Claude Code Skills - Official Documentation Reference
+
+Source: https://code.claude.com/docs/en/skills
+
+## Key Concepts
+
+### What are Claude Code Skills?
+
+Skills are reusable pieces of functionality that extend Claude Code's capabilities. They can be automatically loaded based on context or manually invoked by users.
+
+### Skill Types
+
+1. Automatic Skills: Load automatically based on conversation context
+2. Manual Skills: User must explicitly invoke using `/skill <skill-name>`
+3. Plugin Skills: Bundled with installed packages
+
+### Storage Locations (Priority Order)
+
+1. Personal Skills: `~/.claude/skills/` (highest priority)
+2. Project Skills: `.claude/skills/` (team-shared)
+3. Plugin Skills: Bundled with installed packages (lowest priority)
+
+### Required Frontmatter Fields
+
+```yaml
+---
+name: my-skill # Required: kebab-case, max 64 chars
+description: Brief description of what the skill does and when to trigger it
+allowed-tools: Read, Write, Bash # Required: comma-separated tool list
+---
+```
+
+### Optional Frontmatter Fields
+
+```yaml
+---
+name: my-skill
+description: What the skill does and when to trigger it
+version: 1.0.0 # Semantic versioning
+modularized: false # Whether skill can be split into modules
+tags: [tag1, tag2] # For categorization
+updated: 2025-11-25 # Last update date
+status: active # active, deprecated, experimental
+---
+```
+
+### Skill Discovery and Loading
+
+- Automatic Loading: Skills load when Claude detects relevant context
+- Progressive Loading: Supporting files load on-demand
+- Tool Restrictions: Skills only have access to declared tools
+
+### Best Practices
+
+1. Single Responsibility: Each skill should have one clear purpose
+2. Specific Descriptions: Include trigger scenarios in description
+3. Minimal Tools: Declare only necessary tools using least privilege
+4. Progressive Disclosure: Keep main SKILL.md concise; expand with supporting files
+5. Working Examples: Include practical, tested examples
+
+### File Structure Standards
+
+```
+skill-name/
+ SKILL.md # Always create (main file, ≤ 500 lines)
+ reference.md # Optional: Extended documentation
+ examples.md # Optional: Code examples
+ scripts/ # Optional: Utility scripts
+ helper.sh
+ templates/ # Optional: File templates
+ template.md
+```
+
+### Skill Naming Conventions
+
+- Format: kebab-case (lowercase with hyphens)
+- Length: Maximum 64 characters
+- Uniqueness: Must be unique across all storage locations
+- Descriptive: Name should indicate skill purpose
+
+### Tool Permissions
+
+Skills only have access to tools declared in `allowed-tools`. Common tool categories:
+
+- Information: `Read`, `Grep`, `Glob` (no user approval needed)
+- Modification: `Write`, `Edit`, `Bash` (user approval required)
+- External: `WebFetch`, `WebSearch` (user approval required)
+
+### Integration Patterns
+
+Skill Dependencies:
+```yaml
+skills: moai-foundation-claude, other-skill-name
+```
+
+MCP Server Integration:
+```yaml
+mcpServers:
+ - context7
+ - figma-dev-mode-mcp-server
+```
+
+### Validation and Debugging
+
+Common Issues:
+- Skill not loading: Check YAML syntax and file path
+- Tool prompts unexpected: Review `allowed-tools` declaration
+- Duplicate triggers: Rename skill or tighten description
+
+Debug Commands:
+- `claude --debug`: Check skill loading and configuration
+- Validate YAML: Use online YAML validators or local tools
+- Test skills: Create test cases for skill functionality

moai_adk/templates/.claude/skills/moai-foundation-claude/reference/claude-code-sub-agents-official.md

@@ -0,0 +1,238 @@
+# Claude Code Sub-agents - Official Documentation Reference
+
+Source: https://code.claude.com/docs/en/sub-agents
+
+## Key Concepts
+
+### What are Claude Code Sub-agents?
+
+Sub-agents are specialized AI assistants that can be invoked to handle specific tasks or domains. They extend Claude Code's capabilities through delegation patterns.
+
+### Sub-agent Limitations
+
+Critical Constraint: Sub-agents cannot spawn other sub-agents. This is a fundamental limitation to prevent infinite recursion.
+
+Required Pattern: All sub-agent delegation must use the `Task()` function:
+```python
+# CORRECT - Required delegation pattern
+Task(subagent_type="specialized-agent", prompt="Handle specific task")
+```
+
+### Sub-agent Configuration
+
+Required Fields:
+```yaml
+---
+name: agent-name
+description: Clear description of agent's purpose and domain
+tools: Read, Write, Bash, Grep # Required: Available tools
+model: sonnet # Model choice: sonnet, opus, haiku, inherit
+permissionMode: default # Permission handling strategy
+skills: skill1, skill2 # Available skills for agent
+---
+```
+
+### Model Selection
+
+- sonnet: Balanced performance and quality (default)
+- opus: Highest quality, higher cost
+- haiku: Fastest, most cost-effective
+- inherit: Use same model as calling agent
+
+### Permission Modes
+
+Official Claude Code permissionMode values (verified from official documentation):
+
+- default: Standard permission prompts. Each tool usage requires user approval on first use in the session. This is the default value if permissionMode is omitted. Recommended for most agents requiring user oversight.
+
+- acceptEdits: Automatically accepts file edit operations (Write, Edit, MultiEdit) without prompting. Other tool operations (like Bash) still require approval. Use for trusted development environments where file modifications are expected and safe.
+
+- dontAsk: Suppresses all permission dialog prompts for this agent. All tool operations proceed without user confirmation. Use with caution - recommended ONLY for automated environments, CI/CD pipelines, or fully sandboxed contexts.
+
+Important Notes:
+- If `permissionMode` is omitted, the default value is `default`
+- The values `bypassPermissions`, `plan`, and `ignore` are NOT official permissionMode values
+- For maximum security, use `default` and explicitly approve each operation
+- For automation workflows in safe environments, `acceptEdits` or `dontAsk` may be appropriate
+
+### Tool Permissions
+
+Security Principle: Apply least privilege - only grant tools necessary for agent's domain.
+
+Common Tool Categories:
+- Read Tools: `Read`, `Grep`, `Glob` (file system access)
+- Write Tools: `Write`, `Edit`, `MultiEdit` (file modification)
+- System Tools: `Bash` (command execution)
+- Communication Tools: `AskUserQuestion`, `WebFetch` (interaction)
+
+### Sub-agent Creation Patterns
+
+Domain-Specific Specialization:
+```yaml
+---
+name: security-expert
+description: OWASP security analysis and vulnerability assessment
+tools: Read, Grep, Bash, WebFetch
+model: sonnet
+skills: moai-quality-security
+---
+```
+
+Task-Oriented Specialization:
+```yaml
+---
+name: spec-builder
+description: Generate EARS format specifications from requirements
+tools: Read, Write, Bash
+model: sonnet
+skills: moai-foundation-specs
+---
+```
+
+### Best Practices
+
+1. Clear Scope Definition: Single domain or responsibility
+2. Specific System Prompts: Clear instructions about agent boundaries
+3. Security Boundaries: Explicit limitations on agent behavior
+4. Error Handling: Robust error recovery and fallback strategies
+5. Performance Considerations: Appropriate model selection and context management
+
+### Integration Patterns
+
+Sequential Delegation:
+```python
+# Phase 1: Analysis
+analysis = Task(
+ subagent_type="spec-builder",
+ prompt="Analyze requirements for user authentication"
+)
+
+# Phase 2: Implementation (passes analysis results)
+implementation = Task(
+ subagent_type="backend-expert",
+ prompt="Implement authentication API based on analysis",
+ context={"analysis": analysis}
+)
+```
+
+Parallel Delegation:
+```python
+# Independent execution
+results = await Promise.all([
+ Task(subagent_type="backend-expert", prompt="Backend implementation"),
+ Task(subagent_type="frontend-expert", prompt="Frontend implementation"),
+ Task(subagent_type="test-engineer", prompt="Test strategy")
+])
+```
+
+Conditional Delegation:
+```python
+# Route based on analysis results
+if analysis.has_database_issues:
+ result = Task(subagent_type="database-expert", prompt="Optimize database")
+elif analysis.has_api_issues:
+ result = Task(subagent_type="backend-expert", prompt="Fix API issues")
+```
+
+### Context Management
+
+Efficient Data Passing:
+- Pass only essential information between agents
+- Use structured data formats for complex information
+- Minimize context size for performance optimization
+- Include validation metadata when appropriate
+
+Context Size Limits:
+- Each Task() creates independent context window
+- Recommended context size: 20K-50K tokens maximum
+- Large datasets should be referenced rather than embedded
+
+### File Storage Standards
+
+Agent Definition Location:
+```
+.claude/agents/
+ domain/
+ agent-name.md # Agent definition
+ examples.md # Usage examples
+ integration.md # Integration patterns
+ validation.md # Quality checks
+ agent-factory.md # Agent creation utilities
+```
+
+### Naming Conventions
+
+- Format: lowercase with hyphens (domain-function)
+- Length: Maximum 64 characters
+- Descriptive: Name should clearly indicate agent's domain
+- Unique: Must be unique across all agents
+
+### Testing and Validation
+
+Test Categories:
+1. Functionality Testing: Agent performs expected tasks correctly
+2. Integration Testing: Agent works properly with other agents
+3. Security Testing: Agent respects security boundaries
+4. Performance Testing: Agent operates efficiently within token limits
+
+Validation Steps:
+1. Test agent behavior with various inputs
+2. Verify tool usage respects permissions
+3. Validate error handling and recovery
+4. Check integration with other agents or skills
+
+### Error Handling
+
+Common Error Types:
+- Agent Not Found: Incorrect agent name or file not found
+- Permission Denied: Insufficient tool permissions
+- Context Overflow: Too much context passed between agents
+- Infinite Recursion: Agent tries to spawn another sub-agent
+
+Recovery Strategies:
+- Fallback to basic functionality
+- User notification with clear error messages
+- Graceful degradation of complex features
+- Context optimization for retry attempts
+
+### Performance Optimization
+
+Model Selection Guidelines:
+- Simple Tasks: Use `haiku` for speed and cost efficiency
+- Complex Analysis: Use `sonnet` for quality and reliability
+- Creative Tasks: Use `opus` for highest quality output
+- Cost-Sensitive: Use `haiku` with careful prompt optimization
+
+Context Optimization:
+- Minimize passed context between agents
+- Use efficient data structures
+- Cache reusable results
+- Avoid circular references
+
+### Security Considerations
+
+Access Control:
+- Apply principle of least privilege
+- Validate all external inputs
+- Restrict file system access where appropriate
+- Audit tool usage regularly
+
+Data Protection:
+- Never pass sensitive credentials
+- Sanitize inputs before processing
+- Use secure communication channels
+- Log agent activities appropriately
+
+### Monitoring and Observability
+
+Activity Logging:
+- Track all agent invocations
+- Monitor token usage and performance
+- Log error conditions and recovery attempts
+- Record integration patterns and dependencies
+
+Quality Metrics:
+- Agent success rates and error frequencies
+- Average response times per task type
+- Token efficiency and optimization opportunities
+- User satisfaction and feedback collection

moai_adk/templates/.claude/skills/moai-foundation-claude/reference/complete-configuration-guide.md

@@ -0,0 +1,175 @@
+# Claude Code Complete Configuration Guide
+
+## IAM & Permission Rules
+
+### Tool-Specific Permission Rules
+
+Tiered Permission System:
+1. Read-only: No approval required
+2. Bash Commands: User approval required
+3. File Modification: User approval required
+
+Permission Rule Format:
+```json
+{
+ "allowedTools": [
+ "Read", // Read-only access
+ "Bash", // Commands with approval
+ "Write", // File modification with approval
+ "WebFetch(domain:*.example.com)" // Domain-specific web access
+ ]
+}
+```
+
+### Enterprise Policy Overrides
+
+Enterprise IAM Structure:
+```json
+{
+ "enterprise": {
+ "policies": {
+ "tools": {
+ "Bash": "never", // Enterprise-wide restriction
+ "WebFetch": ["domain:*.company.com"] // Approved domains only
+ },
+ "mcpServers": {
+ "allowed": ["context7", "figma"], // Approved MCP servers
+ "blocked": ["custom-mcp"] // Blocked servers
+ }
+ }
+ }
+}
+```
+
+### Permission Configuration Examples
+
+Development Environment:
+```json
+{
+ "allowedTools": [
+ "Read",
+ "Write",
+ "Edit",
+ "Bash",
+ "WebFetch",
+ "Grep",
+ "Glob"
+ ],
+ "toolRestrictions": {
+ "Bash": {
+ "allowedCommands": ["npm", "python", "git", "make"],
+ "blockedCommands": ["rm -rf", "sudo", "chmod 777"]
+ },
+ "WebFetch": {
+ "allowedDomains": ["*.github.com", "*.npmjs.com", "docs.python.org"],
+ "blockedDomains": ["*.malicious-site.com"]
+ }
+ }
+}
+```
+
+Production Environment:
+```json
+{
+ "allowedTools": [
+ "Read",
+ "Grep",
+ "Glob"
+ ],
+ "toolRestrictions": {
+ "Write": "never",
+ "Edit": "never",
+ "Bash": "never"
+ }
+}
+```
+
+### MCP Permission Management
+
+MCP servers do not support wildcards - specific server names required:
+
+```json
+{
+ "allowedMcpServers": [
+ "context7",
+ "figma-dev-mode-mcp-server",
+ "playwright"
+ ],
+ "blockedMcpServers": [
+ "custom-unverified-mcp"
+ ]
+}
+```
+
+## Claude Code Settings
+
+### Settings Hierarchy
+
+Configuration Priority (highest to lowest):
+1. Enterprise Settings: Organization-wide policies
+2. User Settings: `~/.claude/settings.json` (personal)
+3. Project Settings: `.claude/settings.json` (shared)
+4. Local Settings: `.claude/settings.local.json` (local overrides)
+
+### Core Settings Structure
+
+```json
+{
+ "model": "claude-3-5-sonnet-20241022",
+ "permissionMode": "default",
+ "maxFileSize": 10000000,
+ "maxTokens": 200000,
+ "environment": {},
+ "hooks": {},
+ "plugins": {},
+ "subagents": {},
+ "mcpServers": {}
+}
+```
+
+### Key Configuration Options
+
+Model Settings:
+```json
+{
+ "model": "claude-3-5-sonnet-20241022", // or haiku, opus
+ "maxTokens": 200000, // Context window limit
+ "temperature": 1.0 // Creativity level (0.0-1.0)
+}
+```
+
+Permission Management:
+```json
+{
+ "permissionMode": "default", // default, acceptEdits, dontAsk
+ "tools": {
+ "Bash": "prompt", // always, prompt, never
+ "Write": "prompt",
+ "Edit": "prompt"
+ }
+}
+```
+
+Environment Variables:
+```json
+{
+ "environment": {
+ "NODE_ENV": "development",
+ "API_KEY": "$ENV_VAR", // Environment variable reference
+ "PROJECT_ROOT": "." // Static value
+ }
+}
+```
+
+MCP Server Configuration:
+```json
+{
+ "mcpServers": {
+ "context7": {
+ "command": "npx",
+ "args": ["@upstash/context7-mcp"],
+ "env": {"CONTEXT7_API_KEY": "$CONTEXT7_KEY"}
+ }
+ }
+}
+```