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

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

@@ -0,0 +1,296 @@
+---
+name: "Managing Claude Code Session Memory & Context"
+description: "Understand session context limits, use just-in-time retrieval, cache insights, manage memory files. Use when optimizing context usage, handling large projects, or implementing efficient workflows."
+allowed-tools: "Read, Write, Glob, Bash"
+---
+
+# Managing Claude Code Session Memory & Context
+
+Claude Code operates within context windows (~100K-200K tokens). Effective memory management ensures productive sessions without hitting limits.
+
+## Context Budget Overview
+
+```
+Total Context Budget
+├── System Prompt (~2K)
+├── Tools & Instructions (~5K)
+├── Session History (~30K)
+├── Project Context (~40K)
+└── Available for Response (~23K)
+```
+
+## Just-in-Time (JIT) Retrieval Strategy
+
+### High-Freedom: Core Principles
+
+**Principle 1: Pull Only What You Need**
+- Don't load entire codebase upfront
+- Load files relevant to immediate task
+- Use Glob/Grep for targeted searches
+- Cache results for reuse
+
+**Principle 2: Prefer Explore Over Manual Hunting**
+```bash
+# ❌ Manual approach: Search many files, load all
+rg "authenticate" src/ | head -20
+
+# ✅ JIT approach: Use Explore agent
+@agent-Explore "Find authentication implementation, analyze"
+```
+
+**Principle 3: Layered Context Summaries**
+```
+1. High-level brief (purpose, success criteria)
+   ↓
+2. Technical core (entry points, domain models)
+   ↓
+3. Edge cases (known bugs, constraints)
+```
+
+### Example: Feature Implementation
+
+```
+Task: "Add email verification to signup"
+
+JIT Retrieval:
+├── Read: User model (src/domain/user.ts)
+├── Read: Signup endpoint (src/api/auth.ts)
+├── Grep: "email" in tests (understand patterns)
+├── Glob: Find email service (src/infra/email.*)
+└── Cache: Signup flow diagram in memory
+```
+
+## Medium-Freedom: Memory File Patterns
+
+### Pattern 1: Session Summary Cache
+
+**File**: `.moai/memory/session-summary.md`
+
+```markdown
+# Session Summary
+
+## Current Task
+- Feature: User email verification
+- SPEC: AUTH-015
+- Status: In RED phase (writing tests)
+
+## Key Files
+- Test: tests/auth/email_verify.test.ts
+- Impl: src/domain/email_service.ts
+- Config: src/config/email.ts
+
+## Important Context
+- Email service uses SendGrid API
+- Verification tokens expire in 24h
+- Already have similar flow for password reset (AUTH-012)
+
+## Assumptions Made
+- Assuming transactional emails only
+- Async email sending OK
+- No SMS verification needed
+```
+
+### Pattern 2: Architecture Reference
+
+**File**: `.moai/memory/architecture.md`
+
+```markdown
+# Architecture Reference
+
+## Data Flow for Email Verification
+
+```
+User(Browser)
+    ↓ [POST /auth/signup]
+Server
+    ↓ [Create user + token]
+DB
+    ↓ [sendEmail async]
+Queue
+    ↓ [Process job]
+Email Service (SendGrid)
+    ↓
+User receives email with link
+User clicks link
+    ↓ [GET /auth/verify?token=...]
+Server validates token
+    ↓ [Mark user verified]
+DB
+    ↓
+User logged in
+```
+
+## Module Boundaries
+- `domain/`: Business logic (no framework)
+- `api/`: HTTP endpoints only
+- `infra/`: External services (SendGrid, DB)
+```
+
+### Pattern 3: Known Gotchas Cache
+
+**File**: `.moai/memory/gotchas.md`
+
+```markdown
+# Common Pitfalls in This Project
+
+## Email Service
+- SendGrid has rate limit: 100 emails/sec per account
+- Test mode uses fake email (won't actually send)
+- Async job failures don't alert (check logs)
+
+## Database
+- Migrations must be reviewed before prod deploy
+- Test DB is reset after each suite
+- Foreign key constraints enforced (plan deletions)
+
+## Authentication
+- JWT tokens stored in httpOnly cookies (XSRF protected)
+- Refresh token rotation required (not automatic)
+- Session timeout: 7 days (hardcoded, not configurable yet)
+```
+
+## Low-Freedom: Memory Management Practices
+
+### Practice 1: Caching Key Insights
+
+```
+After reading code:
+1. Note file locations (~5 min read)
+2. Summarize key logic (~2 min)
+3. Write to memory file (~1 min)
+4. Reference in next session
+```
+
+**Example memory entry**:
+```
+# USER-002: Email verification flow
+
+## Key Code Locations
+- Token generation: src/domain/user.ts:generateVerificationToken()
+- Email sending: src/infra/email_service.ts:sendVerificationEmail()
+- Token validation: src/api/auth.ts:POST /verify
+
+## Logic Summary
+1. User submits email → server generates token (16 chars, base64)
+2. Token stored in DB with 24h expiry
+3. Email sent async via SendGrid
+4. User clicks link → token validated → user marked verified
+5. Token deleted after use (can't reuse)
+
+## Related TESTs
+- tests/auth/email_verify.test.ts (GREEN phase - needs implementation)
+- Similar flow: password reset (PASSWORD-001)
+```
+
+### Practice 2: Session Boundary Management
+
+**Before switching between tasks**:
+```markdown
+# Session Handoff Note
+
+## Completed
+✓ RED phase: 3 test cases for email verification
+✓ GREEN phase: Minimal implementation passing tests
+✓ REFACTOR: Added input validation
+
+## Status
+- Current: Ready for /alfred:3-sync
+- Next action: Run full test suite, then sync docs
+
+## Context for Next Session
+- SPEC: .moai/specs/SPEC-AUTH-015/spec.md
+- Tests: tests/auth/email_verify.test.ts (all passing)
+- Code: src/domain/email_service.py
+- Database migration: pending (see migrations/ directory)
+
+## Assumptions
+- SendGrid API key set in .env
+- Test mode uses mock email service
+- Database schema includes email_verified_at column
+```
+
+### Practice 3: Cleanup Before Session End
+
+```bash
+# Remove unnecessary cached files
+rm .moai/memory/temp-*.md
+
+# Archive completed memory files
+mv .moai/memory/feature-x-* .moai/memory/archive/
+
+# Keep only active session memory
+ls -la .moai/memory/
+# session-summary.md (current)
+# architecture.md (reference)
+# gotchas.md (patterns)
+```
+
+## Memory File Organization
+
+```
+.moai/
+├── memory/
+│   ├── session-summary.md      # Current session state
+│   ├── architecture.md         # System design reference
+│   ├── gotchas.md             # Common pitfalls
+│   ├── spec-index.md          # List of all SPECs + status
+│   ├── api-reference.md       # API endpoints quick lookup
+│   └── archive/               # Completed session notes
+│       ├── feature-auth-*
+│       └── feature-api-*
+└── specs/                      # Requirement specifications
+    ├── SPEC-AUTH-001/
+    ├── SPEC-USER-002/
+    └── SPEC-API-003/
+```
+
+## Context Optimization Checklist
+
+- [ ] Memory files describe architecture (not code)
+- [ ] Session summary updated before handoff
+- [ ] Key file locations cached (don't re-search)
+- [ ] Assumptions explicitly documented
+- [ ] No duplicate information between memory files
+- [ ] Archive files moved after session completion
+- [ ] All cached insights reference file paths
+- [ ] Memory files are Markdown (human-readable)
+
+## Best Practices
+
+✅ **DO**:
+- Use Explore for large searches
+- Cache results in memory files
+- Keep memory files < 500 lines each
+- Update session-summary.md before switching tasks
+- Reference memory files in handoff notes
+
+❌ **DON'T**:
+- Load entire src/ or docs/ directory upfront
+- Duplicate context between memory files
+- Store memory files outside `.moai/memory/`
+- Leave stale session notes (archive or delete)
+- Cache raw code (summarize logic instead)
+
+## Commands for Memory Management
+
+```bash
+# View current session memory
+cat .moai/memory/session-summary.md
+
+# List all memory files
+ls -la .moai/memory/
+
+# Archive completed work
+mv .moai/memory/feature-old-* .moai/memory/archive/
+
+# Search memory files
+grep -r "email verification" .moai/memory/
+
+# Count context usage estimate
+wc -w .moai/memory/*.md  # Total words
+```
+
+---
+
+**Reference**: Claude Code Context Management
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-memory/templates/session-summary-template.md

@@ -0,0 +1,18 @@
+# Session Summary
+
+## Current Task
+- Feature: [description]
+- SPEC: [ID]
+- Status: [phase]
+
+## Key Files
+- Test: [path]
+- Impl: [path]
+- Config: [path]
+
+## Important Context
+- [Key insights]
+- [Related features]
+
+## Assumptions Made
+- [List assumptions]

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

@@ -0,0 +1,243 @@
+---
+name: "Configuring Claude Code settings.json & Security"
+description: "Set up permissions (allow/deny), permission modes, environment variables, tool restrictions. Use when securing Claude Code, restricting tool access, or optimizing session settings."
+allowed-tools: "Read, Write, Edit, Bash"
+---
+
+# Configuring Claude Code settings.json
+
+`settings.json` centralizes all Claude Code configuration: permissions, tool access, environment variables, and session behavior.
+
+**Location**: `.claude/settings.json`
+
+## Complete Configuration Template
+
+```json
+{
+  "permissions": {
+    "allowedTools": [
+      "Read(**/*.{js,ts,json,md})",
+      "Edit(**/*.{js,ts})",
+      "Glob(**/*)",
+      "Grep(**/*)",
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(npm run:*)",
+      "Bash(pytest:*)",
+      "Bash(python:*)"
+    ],
+    "deniedTools": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Bash(curl:*)"
+    ]
+  },
+  "permissionMode": "ask",
+  "spinnerTipsEnabled": true,
+  "disableAllHooks": false,
+  "env": {
+    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
+    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
+    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/pre-bash-check.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/post-edit-format.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/session-init.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "enabled": true,
+    "type": "command",
+    "command": "~/.claude/statusline.sh"
+  },
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-github"],
+      "oauth": {
+        "clientId": "${GITHUB_CLIENT_ID}",
+        "clientSecret": "${GITHUB_CLIENT_SECRET}",
+        "scopes": ["repo", "issues"]
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${CLAUDE_PROJECT_DIR}/.moai", "${CLAUDE_PROJECT_DIR}/src"]
+    }
+  },
+  "extraKnownMarketplaces": [
+    {
+      "name": "company-plugins",
+      "url": "https://github.com/your-org/claude-plugins"
+    }
+  ]
+}
+```
+
+## Permission Modes
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| **allow** | Execute all allowed tools without asking | Trusted environments |
+| **ask** | Ask before executing each tool | Development (safer) |
+| **deny** | Deny all tools except whitelisted | Restrictive (default) |
+
+```json
+{
+  "permissionMode": "ask"
+}
+```
+
+## Tool Permission Patterns
+
+### Restrictive (Recommended for teams)
+```json
+{
+  "allowedTools": [
+    "Read(src/**)",
+    "Edit(src/**/*.ts)",
+    "Bash(npm run test:*)",
+    "Glob(src/**)"
+  ],
+  "deniedTools": [
+    "Bash(rm:*)",
+    "Bash(sudo:*)",
+    "Read(.env)"
+  ]
+}
+```
+
+### Permissive (Local development only)
+```json
+{
+  "allowedTools": [
+    "Read",
+    "Write",
+    "Edit",
+    "Bash(git:*)",
+    "Bash(npm:*)",
+    "Bash(python:*)",
+    "Glob",
+    "Grep"
+  ]
+}
+```
+
+## Environment Variables Pattern
+
+```json
+{
+  "env": {
+    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
+    "GITHUB_TOKEN": "${GITHUB_TOKEN}",
+    "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}",
+    "NODE_ENV": "development"
+  }
+}
+```
+
+**Security rule**: Never hardcode secrets; always use `${VAR_NAME}` syntax.
+
+## Dangerous Tools to Deny
+
+```json
+{
+  "deniedTools": [
+    "Bash(rm -rf:*)",           // Recursive delete
+    "Bash(sudo:*)",             // Privilege escalation
+    "Bash(curl.*|.*bash)",      // Code injection
+    "Read(.env)",               // Secrets
+    "Read(.ssh/**)",            // SSH keys
+    "Read(/etc/shadow)",        // System secrets
+    "Edit(/etc/**)",            // System files
+  ]
+}
+```
+
+## Permission Validation
+
+```bash
+# Check current permissions
+cat .claude/settings.json | jq '.permissions'
+
+# Validate JSON syntax
+jq . .claude/settings.json
+
+# List allowed tools
+jq '.permissions.allowedTools[]' .claude/settings.json
+```
+
+## Spinner Tips Configuration
+
+```json
+{
+  "spinnerTipsEnabled": true
+}
+```
+
+Custom tips can be added for better UX during long operations.
+
+## Best Practices
+
+✅ **DO**:
+- Use `ask` mode for teams
+- Explicitly whitelist paths
+- Environment variables for all secrets
+- Review permissions regularly
+- Document why each denial exists
+
+❌ **DON'T**:
+- Hardcode credentials in settings.json
+- Use `allow` mode for untrusted contexts
+- Grant `Bash(*)` without restrictions
+- Include secrets in version control
+- Mix personal and project settings
+
+## Permission Checklist
+
+- [ ] All secrets use `${VAR_NAME}` syntax
+- [ ] Dangerous patterns are denied
+- [ ] File paths are explicit (not wildcards)
+- [ ] Permission mode matches use case (ask/allow/deny)
+- [ ] Hooks are not left in commented state
+- [ ] MCP servers have proper OAuth configuration
+- [ ] No `.env` file is readable
+- [ ] Sudo commands are denied
+
+---
+
+**Reference**: Claude Code settings.json documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-settings/templates/settings-complete-template.json

@@ -0,0 +1,30 @@
+{
+  "permissions": {
+    "allowedTools": [
+      "Read(**/*.{js,ts,json,md})",
+      "Edit(**/*.{js,ts})",
+      "Glob(**/*)",
+      "Grep(**/*)",
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(npm run:*)",
+      "Bash(pytest:*)",
+      "Bash(python:*)"
+    ],
+    "deniedTools": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Bash(curl:*)"
+    ]
+  },
+  "permissionMode": "ask",
+  "spinnerTipsEnabled": true,
+  "disableAllHooks": false,
+  "env": {
+    "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
+    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+  }
+}