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

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

@@ -1,94 +1,121 @@
 ---
-
 name: moai-claude-code
-description: Scaffolds and audits Claude Code agents, commands, skills, plugins, and settings with production templates. Use when configuring or reviewing Claude Code automation inside MoAI workflows.
+version: 2.0.0
+created: 2025-10-22
+updated: 2025-10-22
+status: active
+description: Scaffolds and audits Claude Code agents, commands, skills, plugins, and settings with production templates.
+keywords: ['claude-code', 'agents', 'skills', 'automation']
 allowed-tools:
   - Read
-  - Write
-  - Edit
+  - Bash
 ---
 
-# MoAI Claude Code Manager
+# Claude Code Skill
 
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file) |
-| Auto-load | SessionStart (Claude Code bootstrap) |
-| Trigger cues | Agent/command/skill/plugin/settings authoring, Claude Code environment setup. |
-
-Create and manage Claude Code's five core components according to official standards.
-
-## Components covered
+| **Skill Name** | moai-claude-code |
+| **Version** | 2.0.0 (2025-10-22) |
+| **Allowed tools** | Read (read_file), Bash (terminal) |
+| **Auto-load** | On demand when keywords detected |
+| **Tier** | Ops |
 
-- **Agents** `.claude/agents/` — Persona, tools, and workflow definition
-- **Commands** `.claude/commands/` — Slash command entry points
-- **Skills** `.claude/skills/` — Reusable instruction capsules
-- **Plugins** `settings.json › mcpServers` — MCP integrations
-- **Settings** `.claude/settings.json` — Tool permissions, hooks, session defaults
+---
 
-## Reference files
+## What It Does
 
-- `reference.md` — Writing guide and checklist
-- `examples.md` — Sample completed artifacts
-- `templates/` — Markdown/JSON skeleton for five components
-- `scripts/` — settings validation and template integrity check scripts
+Scaffolds and audits Claude Code agents, commands, skills, plugins, and settings with production templates.
 
-## Workflow
+**Key capabilities**:
+- ✅ Best practices enforcement for ops domain
+- ✅ TRUST 5 principles integration
+- ✅ Latest tool versions (2025-10-22)
+- ✅ TDD workflow support
 
-1. Analyze user requests to determine required components (Agent/Command/Skill/Plugin/Settings).
-2. Copy the stub from `templates/` and replace the placeholders to suit your project context.
-3. If necessary, run the `scripts/` verifier to check required fields, permissions, and follow-up links.
+---
 
-## Guardrails
+## When to Use
 
-- Maintain minimum privileges and progressive disclosure in line with Anthropic official guidelines.
-- Rather than modifying the template directly, only update the hook/field guided by reference.md.
-- The created files and settings.json are included in Git version management and a change history is left.
+**Automatic triggers**:
+- Related code discussions and file patterns
+- SPEC implementation (`/alfred:2-run`)
+- Code review requests
 
-**Official documentation**: https://docs.claude.com/en/docs/claude-code/skills  
-**Version**: 1.0.0
+**Manual invocation**:
+- Review code for TRUST 5 compliance
+- Design new features
+- Troubleshoot issues
 
-## Examples
-```markdown
-- Create a spec-builder agent and the /alfred command set in a new project.
-- Review existing settings.json to update allowable tools and hook configurations.
-```
+---
 
-## Best Practices
-- The output template is designed to be idempotent so that it is safe even when reapplied.
-- Detailed procedures are separated into reference.md (writing guide) and examples.md (sample artifacts) and loaded only when necessary.
+## Tool Version Matrix (2025-10-22)
 
-## When to use
-- Activates when someone asks to scaffold or audit Claude Code components.
-- When bootstrapping a Claude Code configuration to a new project.
-- When reexamining existing agents/commands/skills/plug-ins to meet standards.
-- When verification of settings is required in initialization workflows such as `/alfred:0-project`.
+| Tool | Version | Purpose | Status |
+|------|---------|---------|--------|
+| **Claude Code** | 0.6.0 | Primary | ✅ Current |
 
-## What it does
-- Create and update the five core components as official templates.
-- Verify accepted tools, model selection, and progressive disclosure links.
-- Provides reusable stubs and verification procedures through templates/·scripts/ resources.
+---
 
 ## Inputs
-- User configuration requests (e.g. “add new command”, “review settings.json”) and current `.claude/` directory state.
-- Project-specific template requirements or security/permissions policies.
+
+- Language-specific source directories
+- Configuration files
+- Test suites and sample data
 
 ## Outputs
-- Official Markdown definition file under `.claude/agents|commands|skills/`.
-- A summary of `.claude/settings.json` that reflects the latest settings and allowed tools and follow-up TODOs.
+
+- Test/lint execution plan
+- TRUST 5 review checkpoints
+- Migration guidance
 
 ## Failure Modes
-- If the template path or placeholder is different from the latest version, the result may be damaged.
-- The settings.json permission policy may conflict with project rules or may block verification script execution.
+
+- When required tools are not installed
+- When dependencies are missing
+- When test coverage falls below 85%
 
 ## Dependencies
-- When used with cc-manager, doc-syncer, and moai-foundation-git, the creation → verification → distribution flow is completed.
-- You must have versioned resources in the templates/ and scripts/ directories for automation to work properly.
 
-## References
-- Anthropic. "Claude Code Style Guide." https://docs.claude.com/ (accessed 2025-03-29).
-- Prettier. "Opinionated Code Formatter." https://prettier.io/docs/en/ (accessed 2025-03-29).
+- Access to project files via Read/Bash tools
+- Integration with `moai-foundation-langs` for language detection
+- Integration with `moai-foundation-trust` for quality gates
+
+---
+
+## References (Latest Documentation)
+
+_Documentation links updated 2025-10-22_
+
+---
 
 ## Changelog
-- 2025-03-29: Added best practice structure to Claude code formatting skill.
+
+- **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
+- **v1.0.0** (2025-03-29): Initial Skill release
+
+---
+
+## Works Well With
+
+- `moai-foundation-trust` (quality gates)
+- `moai-alfred-code-reviewer` (code review)
+- `moai-essentials-debug` (debugging support)
+
+---
+
+## Best Practices
+
+✅ **DO**:
+- Follow ops best practices
+- Use latest stable tool versions
+- Maintain test coverage ≥85%
+- Document all public APIs
+
+❌ **DON'T**:
+- Skip quality gates
+- Use deprecated tools
+- Ignore security warnings
+- Mix testing frameworks

moai_adk/templates/.claude/skills/moai-claude-code/examples.md

@@ -1,513 +1,29 @@
-# Claude Code collection of practical examples
+# moai-claude-code - Working Examples
 
-> **Actual working example code**
->
-> Proven examples that can be copied and used immediately
+_Last updated: 2025-10-22_
 
----
-
-## 📋 Table of Contents
-
-1. [Agent example](#1-agent-example)
-2. [Command example](#2-command-example)
-3. [Skill example](#3-skill-example)
-4. [Plugin example](#4-plugin-example)
-5. [Settings example](#5-settings-example)
-
----
-
-## 1. Agent example
-
-### Example 1: spec-builder (MoAI-ADK)
-
-**File**: `.claude/agents/alfred/spec-builder.md`
-
-```markdown
----
-name: spec-builder
-description: "Use when: When writing SPEC, EARS specification, and requirements analysis are necessary."
-tools: Read, Write, Edit, MultiEdit, Grep, Glob, Bash, TodoWrite
-model: sonnet
----
-
-# SPEC Builder 🏗️ - System Architect
-
-**MoAI-ADK SPEC writing expert**
-
-## 🎭 Agent Persona
-
-**Icon**: 🏗️
-**Job**: System Architect
-**Area of ​​Expertise**: SPEC writing, EARS specification, requirements analysis
-**Role**: Convert business requirements into structured SPECs
-**Goal**: Create clear and testable SPEC documents.
-
-## 🎯 Key Role
-
-### 1. Create SPEC document
-- Apply EARS 5 syntax
-- YAML Front Matter 7 required fields
-- HISTORY section management
-
-### 2. Auto-execution conditions
-- When executing the `/alfred:1-plan` command
-- When a new function requirement occurs
-- When requesting improvement of the existing SPEC
-
-## 📐 Workflow
-
-### STEP 1: Project document analysis
-\`\`\`bash
-# read product.md
-Read .moai/project/product.md
-
-# Check existing SPEC
-ls .moai/specs/SPEC-*/spec.md
-\`\`\`
-
-### STEP 2: Draft SPEC
-\`\`\`bash
-Write .moai/specs/SPEC-{ID}/spec.md
-\`\`\`
-
-## 💡 User Guide
-\`\`\`bash
-@agent-spec-builder "Create a user authentication function SPEC"
-\`\`\`
-```
-
-### Example 2: code-analyzer (simple analysis agent)
-
-**File**: `.claude/agents/code-analyzer.md`
-
-```markdown
----
-name: code-analyzer
-description: Use when: code quality analysis is needed
-tools: Read, Grep, Bash(rg:*)
-model: haiku
----
-
-# Code Analyzer 🔍 - Quality Manager
-
-Analyze code quality metrics and provide improvement suggestions.
-
-## 🎭 Agent Persona
-
-**Icon**: 🔍
-**Job**: Quality Manager
-**Area of ​​Expertise**: Code quality analysis, linting, test coverage
-**Role**: Measure code quality metrics and suggest improvements
-**Goal**: Maintain high code quality
-
-## 🎯 Key Role
-
-### 1. Collect quality indicators
-- Check test coverage
-- Detect linting errors
-- Complexity analysis
-
-### 2. Conditions for automatic execution
-- When quality verification is requested before commit
-- Automatic verification before creating PR
-
-## 📐 Workflow
-
-### STEP 1: Scan code
-\`\`\`bash
-rg "@TEST:" -n tests/
-pytest --cov
-\`\`\`
-
-### STEP 2: Generate report
-- Coverage: {percentage}%
-- Linting errors: {count}
-
-## 💡 User Guide
-\`\`\`bash
-@agent-code-analyzer "Analyze current project quality"
-\`\`\`
-```
-
----
-
-## 2. Command example
-
-### Example 1: /alfred:1-plan (MoAI-ADK)
-
-**File**: `.claude/commands/alfred/1-spec.md`
-
-```markdown
----
-name: alfred:1-spec
-description: Project document analysis and SPEC creation (EARS method)
-argument-hint: [feature-description]
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Task
-  - Grep
-  - Glob
-  - TodoWrite
-  - Bash(git:*)
----
-
-# 📋 MoAI-ADK Step 1: Write SPEC
-
-## 🎯 Command Purpose
-
-Analyze project documents, create SPEC documents using the EARS method, and create Git branches.
-
-## 💡 Example of use
-\`\`\`bash
-/alfred:1-plan "User authentication function"
-\`\`\`
-
-## 📋 Execution flow
-
-1. **Phase 1**: Analyze project document
- - Read product.md
- - Check existing SPEC
-
-2. **Phase 2**: SPEC creation
- - EARS method specification
- - Git branch creation
-
-## 🔗 Associated Agent
-
-- **Primary**: spec-builder (🏗️ System Architect)
-- **Secondary**: git-manager (🚀 Release Engineer)
-
-## ⚠️ Precautions
-
-- SPEC ID duplication check required
-- Compliance with EARS 5 phrases
-
-## 📋 Next steps
-
-- `/alfred:2-run SPEC-{ID}` - Start TDD implementation
-```
-
-### Example 2: /deploy-api (deploy command)
-
-**File**: `.claude/commands/deploy-api.md`
-
-```markdown
----
-name: deploy-api
-description: Deploy API server to production environment
-argument-hint: [environment]
-allowed-tools:
-  - Read
-  - Bash(git:*)
-  - Bash(npm:*)
----
-
-# 🚀 API deployment command
-
-Deploys the API server to the specified environment.
-
-## 🎯 Command Purpose
-
-Automate Git tag creation and deployment by environment
-
-## 💡 Example of use
-\`\`\`bash
-/deploy-api production
-/deploy-api staging
-\`\`\`
-
-## 📋 Execution flow
-
-1. **Phase 1**: Check Git status
- - Check current branch (main required)
- - Create version tag
-
-2. **Phase 2**: Deployment execution
-   - npm run build
-- Execute deployment script for each environment
-
-## ⚠️ Precautions
-
-- Can only be run from the main branch
-- Must pass all tests
-```
-
----
-
-## 3. Skill example
-
-### Example 1: moai-alfred-tag-scanning
-
-**File**: `.claude/skills/moai-alfred-tag-scanning/SKILL.md`
-
-```markdown
----
-name: moai-alfred-tag-scanning
-description: Directly scan TAG markers and create inventory (CODE-FIRST principle)
-model: haiku
-allowed-tools:
-  - Grep
-  - Read
----
-
-# TAG scanner
-
-> CODE-FIRST principle: scan code directly without intermediate cache
-
-## 🎯 Purpose
-
-Scan `@SPEC`, `@TEST`, `@CODE`, and `@DOC` TAGs directly from your code.
-
-## 💡 How to use
-
-“Check AUTH domain TAG list”
-
-## 📋 How to scan
-
-\`\`\`bash
-rg '@(SPEC|TEST|CODE|DOC):' -n .moai/specs/ tests/ src/ docs/
-\`\`\`
-
-## ✅ Verification
-
-- Does every `@CODE` TAG have a corresponding `@SPEC`?
-- No orphan TAGs
-```
-
-### Example 2: moai-alfred-feature-selector
-
-**File**: `.claude/skills/moai-alfred-feature-selector/SKILL.md`
-
-```markdown
----
-name: moai-alfred-feature-selector
-description: Select optimal functions for each project type (37 skills → automatically filter 3 to 5)
-model: haiku
-allowed-tools:
-  - Read
----
-
-# MoAI Alfred Feature Selector
-
-> Automatic selection of MoAI-ADK functions suitable for project characteristics
-
-## 🎯 Purpose
-
-Analyze your project type and select only the features you need.
-
-## 📋 Project classification
-
-### By language
-- **Python**: pytest, mypy, ruff
-- **TypeScript**: Vitest, Biome
-
-### Domain-specific
-- **CLI Tool**: Argument parsing, POSIX compliance
-- **Web API**: REST/GraphQL, authentication
-
-## 💡 How to use
-
-"Automatically called when running /alfred:0-project"
-```
-
----
-
-## 4. Plugin example
-
-### Example 1: GitHub + Filesystem (default)
-
-**FILE**: `.claude/settings.json` (mcpServers section)
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
-      }
-    },
-    "filesystem": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "${CLAUDE_PROJECT_DIR}/src",
-        "${CLAUDE_PROJECT_DIR}/tests"
-      ]
-    }
-  }
-}
-```
-
-### Example 2: Fully configured MoAI-ADK
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
-      }
-    },
-    "moai-filesystem": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "${CLAUDE_PROJECT_DIR}/.moai",
-        "${CLAUDE_PROJECT_DIR}/src",
-        "${CLAUDE_PROJECT_DIR}/tests",
-        "${CLAUDE_PROJECT_DIR}/docs"
-      ]
-    },
-    "brave-search": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
-      "env": {
-        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
-      }
-    }
-  }
-}
-```
-
----
-
-## 5. Settings example
-
-### Example 1: Python project
-
-**File**: `.claude/settings.json`
+## Example 1: Basic Setup
 
-```json
-{
-  "permissions": {
-    "defaultMode": "default",
-    "allow": [
-      "Read",
-      "Write",
-      "Edit",
-      "Grep",
-      "Glob",
-      "Bash(git:*)",
-      "Bash(python:*)",
-      "Bash(pytest:*)",
-      "Bash(mypy:*)",
-      "Bash(ruff:*)"
-    ],
-    "ask": [
-      "Bash(pip install:*)",
-      "Bash(git push:*)"
-    ],
-    "deny": [
-      "Read(./.env)",
-      "Bash(sudo:*)",
-      "Bash(rm -rf:*)"
-    ]
-  }
-}
+```bash
+# Setup commands
+# ...
 ```
 
-### Example 2: TypeScript project
+## Example 2: TDD Workflow
 
-```json
-{
-  "permissions": {
-    "defaultMode": "default",
-    "allow": [
-      "Read",
-      "Write",
-      "Edit",
-      "Grep",
-      "Glob",
-      "Bash(git:*)",
-      "Bash(node:*)",
-      "Bash(npm:*)",
-      "Bash(pnpm:*)"
-    ],
-    "ask": [
-      "Bash(npm install:*)",
-      "Bash(pnpm install:*)",
-      "Bash(git push:*)"
-    ],
-    "deny": [
-      "Read(./.env)",
-      "Read(./secrets/**)",
-      "Bash(sudo:*)",
-      "Bash(rm -rf:*)"
-    ]
-  }
-}
+```bash
+# RED: Write failing test
+# GREEN: Implement feature
+# REFACTOR: Improve code
 ```
 
-### Example 3: MoAI-ADK project (with hooks)
+## Example 3: Quality Gate
 
-```json
-{
-  "permissions": {
-    "defaultMode": "default",
-    "allow": [
-      "Task",
-      "Read",
-      "Write",
-      "Edit",
-      "MultiEdit",
-      "Grep",
-      "Glob",
-      "TodoWrite",
-      "Bash(git:*)",
-      "Bash(python:*)",
-      "Bash(pytest:*)",
-      "Bash(mypy:*)",
-      "Bash(ruff:*)",
-      "Bash(moai-adk:*)",
-      "Bash(alfred:*)"
-    ],
-    "ask": [
-      "Bash(git push:*)",
-      "Bash(pip install:*)"
-    ],
-    "deny": [
-      "Read(./.env)",
-      "Read(./secrets/**)",
-      "Bash(sudo:*)",
-      "Bash(rm -rf:*)"
-    ]
-  },
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [
-          {
-            "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/alfred/session-notice.cjs",
-            "type": "command"
-          }
-        ],
-        "matcher": "*"
-      }
-    ],
-    "PreToolUse": [
-      {
-        "hooks": [
-          {
-            "command": "node $CLAUDE_PROJECT_DIR/.claude/hooks/alfred/pre-write-guard.cjs",
-            "type": "command"
-          }
-        ],
-        "matcher": "Edit|Write|MultiEdit"
-      }
-    ]
-  }
-}
+```bash
+# Run quality checks
+# Verify coverage ≥85%
 ```
 
 ---
 
-**Last update**: 2025-10-19
-**Author**: @Alfred
+_For more examples, see SKILL.md reference section_