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

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

@@ -2,200 +2,243 @@
 name: moai-foundation-claude
 aliases: [moai-foundation-claude]
 category: foundation
-description: Canonical Claude Code skill authoring kit covering agent Skills, sub-agent templates, custom slash commands, orchestration patterns, hooks, memory, settings, and IAM permission rules aligned with official documentation.
-version: 2.0.0
+description: Canonical Claude Code authoring kit covering Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns. Use when creating Claude Code extensions or configuring Claude Code features.
+version: 5.0.0
 modularized: false
-tags:
- - foundation
- - claude-code
- - skills
- - sub-agents
- - slash-commands
- - orchestration
- - hooks
- - memory
- - settings
- - iam
- - best-practices
+user-invocable: false
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+tags: ['foundation', 'claude-code', 'skills', 'sub-agents', 'plugins', 'slash-commands', 'hooks', 'memory', 'settings', 'sandboxing', 'headless', 'agent-patterns']
+---
+
 # Claude Code Authoring Kit
 
-Comprehensive reference for Claude Code Skills, sub-agents, custom slash commands, hooks, memory, settings, and IAM permissions with official standards compliance.
+Comprehensive reference for Claude Code Skills, sub-agents, plugins, slash commands, hooks, memory, settings, sandboxing, headless mode, and advanced agent patterns.
 
-Official Documentation References:
+## Documentation Index
 
+Core Features:
 - [Skills Guide](reference/claude-code-skills-official.md) - Agent Skills creation and management
 - [Sub-agents Guide](reference/claude-code-sub-agents-official.md) - Sub-agent development and delegation
-- [Custom Slash Commands](reference/claude-code-custom-slash-commands-official.md) - Command creation and orchestration
-- [Hooks System](reference/claude-code-hooks-official.md) - Event-driven automation
-- [Memory Management](reference/claude-code-memory-official.md) - Context and knowledge persistence
-- [Settings Configuration](reference/claude-code-settings-official.md) - Configuration hierarchy and management
+- [Plugins Guide](reference/claude-code-plugins-official.md) - Plugin architecture and distribution
+- [Slash Commands](reference/claude-code-custom-slash-commands-official.md) - Command creation and orchestration
+
+Configuration:
+- [Settings](reference/claude-code-settings-official.md) - Configuration hierarchy and management
+- [Memory](reference/claude-code-memory-official.md) - Context and knowledge persistence
+- [Hooks](reference/claude-code-hooks-official.md) - Event-driven automation
 - [IAM & Permissions](reference/claude-code-iam-official.md) - Access control and security
-- [Complete Configuration](reference/complete-configuration-guide.md) - Comprehensive setup guide
+
+Advanced Features:
+- [Sandboxing](reference/claude-code-sandboxing-official.md) - Security isolation
+- [Headless Mode](reference/claude-code-headless-official.md) - Programmatic and CI/CD usage
+- [Dev Containers](reference/claude-code-devcontainers-official.md) - Containerized environments
+- [CLI Reference](reference/claude-code-cli-reference-official.md) - Command-line interface
+- [Statusline](reference/claude-code-statusline-official.md) - Custom status display
+- [Advanced Patterns](reference/advanced-agent-patterns.md) - Engineering best practices
 
 ## Quick Reference (30 seconds)
 
-Skills: `~/.claude/skills/` (personal) or `.claude/skills/` (project), ≤500 lines, progressive disclosure
-Sub-agents: `Task(subagent_type="...")` delegation only, no nested spawning
-Commands: `$ARGUMENTS`/`$1`/`$2` parameters, `@file` references, stored in `.claude/commands/`
-Hooks: Event-driven automation in `settings.json`, PreToolUse/PostToolUse events
-Memory: Enterprise → Project → User hierarchy, `@import.md` syntax
-Settings: 4-tier hierarchy (Enterprise → User → Project → Local)
-IAM: Tiered permissions (Read→Bash→Write→Admin), tool-specific rules
+Skills: Model-invoked extensions in ~/.claude/skills/ (personal) or .claude/skills/ (project). Three-level progressive disclosure. Max 500 lines.
+
+Sub-agents: Specialized assistants via Task(subagent_type="..."). Own 200K context. Cannot spawn sub-agents. Use /agents command.
+
+Plugins: Reusable bundles in .claude-plugin/plugin.json. Include commands, agents, skills, hooks, MCP servers.
+
+Commands: User-invoked via /command. Parameters: $ARGUMENTS, $1, $2. File refs: @file.
+
+Hooks: Events in settings.json. PreToolUse, PostToolUse, SessionStart, SessionEnd, PreCompact, Notification.
 
-## Implementation Guide (5 minutes)
+Memory: CLAUDE.md files + .claude/rules/*.md. Enterprise to Project to User hierarchy. @import syntax.
 
-### Features
+Settings: 6-level hierarchy. Managed to file-managed to CLI to local to shared to user.
 
-- Comprehensive Claude Code authoring reference
-- Skills, sub-agents, commands, hooks, and settings
-- IAM permissions and security best practices
-- Progressive disclosure documentation architecture
-- MCP integration patterns and examples
+Sandboxing: OS-level isolation. Filesystem and network restrictions. Auto-allow safe operations.
 
-### When to Use
+Headless: -p flag for non-interactive. --allowedTools, --json-schema, --agents for automation.
 
-- Creating new Claude Code skills following official standards
-- Developing custom sub-agents with proper delegation patterns
-- Implementing custom slash commands with parameter handling
-- Setting up hooks for event-driven automation
-- Configuring IAM permissions and access control
+## Skill Creation (3 minutes)
 
-### Core Patterns
+### Progressive Disclosure Architecture
+
+Level 1 (Metadata): Name and description loaded at startup, approximately 100 tokens per Skill
+
+Level 2 (Instructions): SKILL.md body loaded when triggered, under 5K tokens recommended
+
+Level 3 (Resources): Additional files loaded on demand, effectively unlimited
+
+### Required Format
 
-Pattern 1: Skill Creation (≤500 lines)
 ```yaml
 ---
 name: skill-name
-description: One-line description (max 200 chars)
-version: 1.0.0
-updated: 2025-11-26
-status: active
+description: What it does AND when to use it. Third person. Max 1024 chars.
 ---
 
-## Quick Reference (30 seconds)
-## Implementation Guide (5 minutes)
-## Advanced Implementation (10+ minutes)
-```
+# Skill Name
 
-Pattern 2: Sub-agent Delegation
-```python
-# Sequential delegation
-result1 = Task(subagent_type="workflow-spec", prompt="Analyze")
-result2 = Task(subagent_type="code-backend", prompt="Implement", context=result1)
-
-# Parallel delegation
-results = await Promise.all([
- Task(subagent_type="code-backend", prompt="Backend"),
- Task(subagent_type="code-frontend", prompt="Frontend")
-])
-```
+## Quick start
+Brief instructions here.
 
-Pattern 3: Custom Command with Hooks
-```json
-{
- "hooks": {
- "PreToolUse": [{
- "matcher": "Write",
- "hooks": [{"type": "command", "command": "validate-write"}]
- }]
- }
-}
+## Details
+See [REFERENCE.md](REFERENCE.md) for more.
 ```
 
-## MoAI-ADK Skills & Sub-agents Directory
-
-### Quick Access Patterns
-
-Core Skills: `Skill("moai-foundation-claude")` - This comprehensive authoring kit
-Agent Creation: `Task(subagent_type="agent-factory")` - Create standardized sub-agents
-Skill Creation: `Task(subagent_type="skill-factory")` - Create compliant skills
-Quality Gates: `Task(subagent_type="quality-gate")` - TRUST 5 validation
-Documentation: `Task(subagent_type="docs-manager")` - Generate technical docs
-
-Key Specialized Skills:
-- `moai-lang-python` - Python 3.13+ with FastAPI, async patterns
-- `moai-lang-typescript` - TypeScript 5.9+ with React 19, Next.js 16
-- `moai-domain-backend` - Modern backend architecture patterns
-- `moai-domain-frontend` - React 19, Next.js 15, Vue 3.5 frameworks
-- `moai-quality-security` - OWASP Top 10, threat modeling
-- `moai-essentials-debug` - AI-powered debugging with Context7
-
-Essential Sub-agents:
-- `spec-builder` - EARS format specification generation
-- `tdd-implementer` - RED-GREEN-REFACTOR TDD execution
-- `security-expert` - Security analysis and validation
-- `backend-expert` - Backend architecture and API development
-- `frontend-expert` - Frontend UI implementation
-- `performance-engineer` - Performance optimization and analysis
-
-## Essential Implementation Patterns
-
-### Command→Agent→Skill Orchestration
-
-Sequential Workflow:
-```python
-# Phase 1: Analysis → spec-builder → analysis
-analysis = Task(subagent_type="spec-builder", prompt="Analyze: $ARGUMENTS")
-# Phase 2: Implementation → tdd-implementer → code + tests
-implementation = Task(subagent_type="tdd-implementer", prompt="Implement: $analysis.spec_id")
-# Phase 3: Validation → quality-gate → approval
-validation = Task(subagent_type="quality-gate", prompt="Validate: $implementation")
-```
+### Best Practices
 
-Parallel Development:
-```python
-# Execute independent tasks simultaneously
-results = await Promise.all([
- Task(subagent_type="backend-expert", prompt="Backend: $1"),
- Task(subagent_type="frontend-expert", prompt="Frontend: $1"),
- Task(subagent_type="docs-manager", prompt="Docs: $1")
-])
-# Integrate all results
-Task(subagent_type="quality-gate", prompt="Integrate", context={"results": results})
-```
+- Third person descriptions (does not I do)
+- Include trigger terms users mention
+- Keep under 500 lines
+- One level deep references
+- Test with Haiku, Sonnet, Opus
+
+## Sub-agent Creation (3 minutes)
+
+### Using /agents Command
+
+1. Type /agents
+2. Select Create New Agent
+3. Define purpose and tools
+4. Press e to edit prompt
+
+### File Format
 
-### Token Session Management
+```yaml
+---
+name: agent-name
+description: When to invoke. Use PROACTIVELY for auto-delegation.
+tools: Read, Write, Bash
+model: sonnet
+---
 
-Independent 200K Sessions: Each `Task()` creates a new 200K token context
-```python
-Task(subagent_type="backend-expert", prompt="Complex task") # 200K session
-Task(subagent_type="frontend-expert", prompt="UI task") # New 200K session
+System prompt here.
 ```
 
-### File Reference Patterns
+### Critical Rules
+
+- Cannot spawn other sub-agents
+- Cannot use AskUserQuestion effectively
+- All user interaction before delegation
+- Each gets own 200K context
 
-Parameter Handling:
-- Positional: `$1`, `$2`, `$3`
-- All arguments: `$ARGUMENTS`
-- File references: `@config.yaml`, `@path/to/file.md`
+## Plugin Creation (3 minutes)
+
+### Directory Structure
+
+```
+my-plugin/
+- .claude-plugin/plugin.json
+- commands/
+- agents/
+- skills/
+- hooks/hooks.json
+- .mcp.json
+```
 
-### Hook Integration
+### Manifest (plugin.json)
 
-Pre/Post Tool Execution (see [Hooks Guide](reference/claude-code-hooks-official.md)):
 ```json
 {
- "hooks": {
- "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "validate-command"}]}],
- "PostToolUse": [{"matcher": "Write", "hooks": [{"type": "command", "command": "backup-file"}]}]
- }
+  "name": "my-plugin",
+  "description": "Plugin purpose",
+  "version": "1.0.0",
+  "author": {"name": "Author"}
 }
 ```
 
-## Key Reference Guides
+### Commands
+
+/plugin install owner/repo
+/plugin validate .
+/plugin enable plugin-name
+
+## Advanced Agent Patterns
+
+### Two-Agent Pattern for Long Tasks
+
+Initializer agent: Sets up environment, feature registry, progress docs
+
+Executor agent: Works single features, updates registry, maintains progress
+
+See [Advanced Patterns](reference/advanced-agent-patterns.md) for details.
+
+### Orchestrator-Worker Architecture
+
+Lead agent: Decomposes tasks, spawns workers, synthesizes results
+
+Worker agents: Execute focused tasks, return condensed summaries
+
+### Context Engineering Principles
+
+- Smallest set of high-signal tokens
+- Just-in-time retrieval over upfront loading
+- Context compaction for long sessions
+- External memory files persist outside window
+
+### Tool Design Best Practices
+
+- Consolidate related functions into single tools
+- Return high-signal context-aware responses
+- Clear parameter names (user_id not user)
+- Instructive error messages with examples
+
+## Workflow: Explore-Plan-Code-Commit
+
+Phase 1 Explore: Read files, understand structure, map dependencies
+
+Phase 2 Plan: Use think prompts, outline approach, define criteria
+
+Phase 3 Code: Implement iteratively, verify each step, handle edges
+
+Phase 4 Commit: Descriptive messages, logical groupings, clean history
+
+## MoAI-ADK Integration
+
+### Core Skills
+
+- moai-foundation-claude: This authoring kit
+- moai-foundation-core: SPEC system and workflows
+- moai-foundation-philosopher: Strategic thinking
+
+### Essential Sub-agents
+
+- spec-builder: EARS specifications
+- manager-tdd: TDD execution
+- expert-security: Security analysis
+- expert-backend: API development
+- expert-frontend: UI implementation
+
+## Security Features
+
+### Sandboxing
+
+- Filesystem: Write restricted to cwd
+- Network: Domain allowlists via proxy
+- OS-level: bubblewrap (Linux), Seatbelt (macOS)
+
+### Dev Containers
+
+- Security-hardened with firewall
+- Whitelisted outbound only
+- --dangerously-skip-permissions for trusted only
+
+### Headless Safety
+
+- Always use --allowedTools in CI/CD
+- Validate inputs before passing to Claude
+- Handle errors with exit codes
+
+## Version History
+
+v4.0.0 (2026-01-06): Added plugins, sandboxing, headless, statusline, dev containers, CLI reference, advanced patterns from engineering blogs
 
-Comprehensive Documentation:
-- [Commands Guide](reference/claude-code-custom-slash-commands-official.md) - Complete command creation
-- [Hooks System](reference/claude-code-hooks-official.md) - Event-driven automation
-- [Memory Management](reference/claude-code-memory-official.md) - Context persistence
-- [Settings Config](reference/claude-code-settings-official.md) - Configuration hierarchy
-- [IAM Permissions](reference/claude-code-iam-official.md) - Access control
-- [Complete Setup](reference/complete-configuration-guide.md) - Full configuration
+v3.0.0 (2025-12-06): Added progressive disclosure, sub-agent details, integration patterns
 
-## Works Well With
+v2.0.0 (2025-11-26): Initial comprehensive release
 
-- moai-core-agent-factory - For creating new sub-agents with proper standards
-- moai-cc-commands - For creating custom slash commands
-- moai-cc-hooks - For implementing Claude Code hooks
-- moai-cc-configuration - For managing Claude Code settings
-- moai-quality-gate - For validating code quality standards
-- moai-essentials-debug - For debugging skill loading issues