oh-my-customcode 0.3.1 → 0.4.0

package/templates/.claude/rules/SHOULD-memory-integration.md

@@ -5,110 +5,128 @@
 
 ## Purpose
 
-Integrate claude-mem for session context persistence across compaction.
+Provide persistent memory for agents using Claude Code's native auto memory system.
 
-## Requirements
+## Architecture: Native First
 
-### 1. Save Before Compaction
-```yaml
-trigger: PreCompact hook
-action:
-  - Collect session context (tasks, decisions, key info)
-  - Format with project tag "baekgom-agents"
-  - Store in claude-mem with metadata
 ```
-
-### 2. Restore on Session Start
-```yaml
-trigger: SessionStart hook
-action:
-  - Build semantic query with project prefix
-  - Search claude-mem for relevant context
-  - Load and present context to agent
+Primary: Native Auto Memory (memory field in agent frontmatter)
+  - Agent-specific persistent knowledge
+  - Automatic system prompt injection (MEMORY.md)
+  - No external dependencies
+
+Supplementary: claude-mem MCP (optional)
+  - Session-level temporal observations
+  - Cross-agent semantic search
+  - Only if installed and configured
+
+RULE: If native auto memory can handle the task,
+      DO NOT use claude-mem.
 ```
 
-### 3. Project Isolation
-```yaml
-rule: Always include project name in queries
-reason: Prevent cross-contamination between projects
-```
+## Native Auto Memory
 
-## Storage Format
+### How It Works
 
-```yaml
-project: baekgom-agents
-session: {date}-{uuid}
-tags: [session, task, decision]
-content:
-  summary: Brief description of session context
-  tasks_completed: List of completed tasks
-  decisions: Key decisions made
-  open_items: Unfinished work
-```
+1. Agent frontmatter includes `memory` field:
+   ```yaml
+   memory: project  # or user, local
+   ```
 
-## Query Pattern
+2. System automatically:
+   - Creates memory directory for the agent
+   - Loads first 200 lines of MEMORY.md into system prompt
+   - Enables Read/Write/Edit tools for memory directory
+   - Agent learns and records patterns across conversations
 
-Always include project name in queries:
-- `"baekgom-agents session authentication"`
-- `"baekgom-agents 2025-01-24 bug fix"`
-- `"baekgom-agents agent creation workflow"`
+### Memory Scopes
 
-### Effective Queries
-```yaml
-good:
-  - "baekgom-agents implementing oauth" (semantic, project-scoped)
-  - "baekgom-agents 2025-01-24 memory system" (temporal)
-  - "baekgom-agents decision agent architecture" (topic-based)
-
-bad:
-  - "implementing oauth" (missing project scope)
-  - "session context" (too generic)
-```
+| Scope | Location | Use Case | Git Tracked |
+|-------|----------|----------|-------------|
+| `user` | `~/.claude/agent-memory/<name>/` | Cross-project patterns | No |
+| `project` | `.claude/agent-memory/<name>/` | Project-specific patterns | Yes |
+| `local` | `.claude/agent-memory-local/<name>/` | Local-only knowledge | No |
 
-## Commands
+### Current Agent Memory Map
 
-| Command | Description |
-|---------|-------------|
-| `sys-memory-keeper:save` | Save current context to claude-mem |
-| `sys-memory-keeper:recall` | Search and recall relevant memories |
+| Scope | Agents | Count |
+|-------|--------|-------|
+| `project` | lang-*, be-*, fe-*, arch-*, tool-*, qa-*, mgr-creator, mgr-updater, mgr-gitnerd, mgr-sauron, mgr-claude-code-bible, sys-memory-keeper | 28 |
+| `user` | infra-docker-expert, infra-aws-expert, db-supabase-expert | 3 |
+| `local` | mgr-supplier, mgr-sync-checker, sys-naggy | 3 |
 
-## Integration with Agents
+### Memory Best Practices
 
-### sys-memory-keeper Agent
-```
-Responsible for:
-- Executing save/recall operations
-- Managing session metadata
-- Handling PreCompact and SessionStart hooks
+```yaml
+do:
+  - Let agents consult memory before starting work
+  - Update memory after discovering patterns or conventions
+  - Keep MEMORY.md under 200 lines (auto-curate if exceeded)
+  - Use separate topic files for detailed notes
+
+dont:
+  - Store sensitive data (API keys, credentials)
+  - Duplicate information already in CLAUDE.md
+  - Use memory for temporary session state
 ```
 
-### Other Agents
-```
-When to trigger sys-memory-keeper:save:
-- Before complex task completion
-- When making significant decisions
-- Before expected context compaction
-```
+## Claude-mem (Optional Supplement)
+
+claude-mem MCP provides session-level observations and semantic search.
+It is NOT required for basic memory functionality.
 
-## Storage Provider
+### When to Use claude-mem
+
+| Scenario | Use Native Memory | Use claude-mem |
+|----------|------------------|---------------|
+| Agent learns project patterns | Yes | |
+| Record debugging insights | Yes | |
+| Search across multiple sessions | | Yes |
+| Temporal queries (date-based) | | Yes |
+| Cross-agent knowledge sharing | | Yes |
+| Basic context persistence | Yes | |
+
+### claude-mem Integration (if installed)
 
 ```yaml
 provider: claude-mem
 collection: claude_memories
-project_tag: baekgom-agents
-archive_path: ~/.claude-mem/archives/
+project_tag: my-project
+status: optional
+```
+
+## Context Compaction
+
+### Compaction Controls
+
+```yaml
+# Targeted compaction - preserve specific context
+/compact focus on {topic}
+
+# Examples
+/compact focus on agent routing decisions
+/compact focus on authentication implementation
+/compact focus on test failures and fixes
+```
+
+### Best Practices
+
+```
+do:
+  - Use /compact focus when nearing context limits
+  - Focus on the most relevant topic for current work
+  - Let auto-compaction handle routine cleanup
+
+dont:
+  - Manually compact when not near limits
+  - Lose important decision context by unfocused compaction
 ```
 
 ## Error Handling
 
 ```yaml
-on_save_failure:
+on_memory_write_failure:
   - Log error
   - Continue without blocking main task
-  - Notify user of memory save failure
-
-on_recall_failure:
-  - Log error
-  - Continue with available context
-  - Notify user that memory recall failed
+  - Memory is enhancement, not requirement
 ```

package/templates/.claude/rules/index.yaml

@@ -1,4 +1,4 @@
-# Baekgom Agents - Global Rules
+# Global Rules
 # Priority: MUST > SHOULD > MAY
 
 rules:
@@ -108,14 +108,6 @@ rules:
     priority: SHOULD
     scope: all
 
-  # Pipeline Mode - SHOULD
-  - id: R014
-    name: pipeline-mode
-    title: Pipeline Mode Rules
-    path: ./SHOULD-pipeline-mode.md
-    priority: SHOULD
-    scope: orchestrator
-
   # Intent Transparency - MUST
   - id: R015
     name: intent-transparency

package/templates/.claude/skills/aws-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: aws-best-practices
 description: AWS patterns from Well-Architected Framework
+user-invocable: false
 ---
 
 ## Purpose

package/templates/.claude/skills/claude-code-bible/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: claude-code-bible
+description: Fetch and verify Claude Code official documentation. Use when checking official spec compliance or updating local reference docs.
+disable-model-invocation: true
+---
+
+# Claude Code Bible
+
+Official documentation reference management for Claude Code.
+
+## Purpose
+
+Maintain up-to-date local copies of Claude Code official documentation and verify that agents/skills comply with the official specifications.
+
+## Commands
+
+### /claude-code-bible update
+
+Fetch the latest documentation from code.claude.com.
+
+**What it does:**
+- Fetches `https://code.claude.com/docs/llms.txt`
+- Extracts all documentation URLs from the llms.txt content
+- Downloads each documentation page and saves as markdown
+- Writes a timestamp file for cache tracking
+- Respects a 24-hour cache (skip if fresh, unless `--force` used)
+
+**Usage:**
+```bash
+# Fetch latest docs (skip if cached < 24h)
+node .claude/skills/claude-code-bible/scripts/fetch-docs.js
+
+# Force update even if cache is fresh
+node .claude/skills/claude-code-bible/scripts/fetch-docs.js --force
+
+# Custom output directory
+node .claude/skills/claude-code-bible/scripts/fetch-docs.js --output /path/to/output
+```
+
+**Default output location:**
+```
+~/.claude/references/claude-code/
+├── llms.txt              # Master index
+├── last-updated.txt      # ISO timestamp
+├── <doc-name>.md         # Individual doc pages
+└── ...
+```
+
+**Exit codes:**
+- `0`: Success (or cache is fresh)
+- `1`: Fatal error
+
+### /claude-code-bible verify
+
+Verify agents and skills against official Claude Code specifications.
+
+**What it checks:**
+- Agent structure compliance (frontmatter fields, file format)
+- Skill structure compliance (SKILL.md format, disable-model-invocation usage)
+- Tool usage patterns match official recommendations
+- Workflow patterns align with Claude Code best practices
+- Agent/skill naming conventions follow official guidelines
+
+**Usage:**
+```bash
+# Verify all agents and skills
+/claude-code-bible verify
+
+# Verify specific agent
+/claude-code-bible verify --agent mgr-creator
+
+# Verify specific skill
+/claude-code-bible verify --skill go-best-practices
+
+# Verbose output
+/claude-code-bible verify --verbose
+```
+
+**Verification rules:**
+1. **Agent frontmatter** must include:
+   - `name`: kebab-case identifier
+   - `description`: one-line summary
+   - `model`: sonnet | opus | haiku
+   - `tools`: array of allowed tools
+   - `skills`: array of skill names
+
+2. **Skill frontmatter** must include:
+   - `name`: kebab-case identifier
+   - `description`: when/why to use this skill
+   - `disable-model-invocation`: true (if skill is procedural/scripted)
+
+3. **Agent files** should NOT contain:
+   - Detailed skill instructions (belongs in .claude/skills/)
+   - Reference documentation (belongs in guides/)
+   - Implementation scripts (belongs in .claude/skills/{name}/scripts/)
+
+4. **Skill files** should contain:
+   - Clear purpose statement
+   - Usage examples
+   - Input/output specifications
+   - Integration points with agents
+
+## Implementation Notes
+
+### Fetch Script (fetch-docs.js)
+
+**Features:**
+- Uses only Node.js built-in modules (https, fs, path)
+- Handles HTTP redirects (3xx responses)
+- Respects server with 200ms delay between requests
+- 24-hour cache to avoid unnecessary fetches
+- Comprehensive error reporting
+
+**Cache behavior:**
+- Checks `last-updated.txt` timestamp
+- Skips fetch if < 24 hours old (unless --force)
+- Always updates timestamp on successful fetch
+
+**Error handling:**
+- Reports HTTP errors with status codes
+- Continues on individual page failures
+- Prints summary of successes and failures
+
+### Verify Command (future implementation)
+
+The verify command should:
+1. Read official specs from `~/.claude/references/claude-code/`
+2. Parse all agents in `.claude/agents/*.md`
+3. Parse all skills in `.claude/skills/*/SKILL.md`
+4. Check each against official requirements
+5. Report violations with suggestions for fixes
+
+## Integration with Other Skills
+
+### create-agent
+- Should verify new agents against official spec
+- Use `/claude-code-bible verify --agent <name>` after creation
+
+### update-docs
+- Should update local docs first: `/claude-code-bible update`
+- Then verify sync with: `/claude-code-bible verify`
+
+### dev-review
+- Can reference official docs for best practices
+- Verify code patterns against Claude Code recommendations
+
+## Benefits
+
+1. **Compliance**: Ensure agents/skills match official specifications
+2. **Up-to-date**: Always have latest documentation locally
+3. **Offline access**: Work with docs even without internet
+4. **Automation**: Verify compliance automatically before commits
+5. **Learning**: Reference official patterns when creating new components
+
+## Example Workflow
+
+```bash
+# 1. Update local docs
+node .claude/skills/claude-code-bible/scripts/fetch-docs.js
+
+# 2. Create a new agent
+/create-agent my-new-agent
+
+# 3. Verify it matches official spec
+/claude-code-bible verify --agent my-new-agent
+
+# 4. Fix any violations
+
+# 5. Verify again
+/claude-code-bible verify --agent my-new-agent
+
+# 6. Commit when all checks pass
+```
+
+## Notes
+
+- The verify command implementation is left for future work
+- The fetch script is production-ready and can be used immediately
+- Consider running `/claude-code-bible update` weekly to stay current
+- Add this as a pre-commit hook to enforce compliance automatically

package/templates/.claude/skills/claude-code-bible/scripts/fetch-docs.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+/**
+ * fetch-docs.js
+ *
+ * Fetches Claude Code official documentation from code.claude.com
+ * and saves it locally for reference.
+ *
+ * Usage:
+ *   node fetch-docs.js [--force] [--output <dir>]
+ *
+ * Options:
+ *   --force          Skip 24-hour cache check
+ *   --output <dir>   Output directory (default: ~/.claude/references/claude-code/)
+ */
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const { homedir } = require('os');
+
+// Configuration
+const LLMS_TXT_URL = 'https://code.claude.com/docs/llms.txt';
+const DEFAULT_OUTPUT_DIR = path.join(homedir(), '.claude', 'references', 'claude-code');
+const FETCH_DELAY_MS = 200;
+const CACHE_HOURS = 24;
+
+// Parse CLI arguments
+function parseArgs() {
+  const args = {
+    force: false,
+    outputDir: DEFAULT_OUTPUT_DIR,
+  };
+
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+    if (arg === '--force') {
+      args.force = true;
+    } else if (arg === '--output' && i + 1 < process.argv.length) {
+      args.outputDir = process.argv[++i];
+    }
+  }
+
+  return args;
+}
+
+// Check if cache is fresh
+function isCacheFresh(outputDir) {
+  const lastUpdatedPath = path.join(outputDir, 'last-updated.txt');
+
+  if (!fs.existsSync(lastUpdatedPath)) {
+    return false;
+  }
+
+  try {
+    const content = fs.readFileSync(lastUpdatedPath, 'utf-8').trim();
+    const lastUpdated = new Date(content);
+    const now = new Date();
+    const hoursSince = (now - lastUpdated) / (1000 * 60 * 60);
+
+    return hoursSince < CACHE_HOURS;
+  } catch (error) {
+    return false;
+  }
+}
+
+// Fetch URL with redirect support
+function fetchUrl(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      // Handle redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location).then(resolve).catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+      }
+
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => resolve(data));
+    }).on('error', reject);
+  });
+}
+
+// Extract documentation URLs from llms.txt
+function extractDocUrls(llmsTxtContent) {
+  const urls = [];
+
+  // Match URLs in markdown links: [title](url) and bare URLs
+  const markdownLinkRegex = /\(https?:\/\/code\.claude\.com\/docs\/[^)]+\)/g;
+  const bareLinkRegex = /^https?:\/\/code\.claude\.com\/docs\/\S+/gm;
+
+  let match;
+  while ((match = markdownLinkRegex.exec(llmsTxtContent)) !== null) {
+    // Remove surrounding parentheses
+    urls.push(match[0].slice(1, -1));
+  }
+  while ((match = bareLinkRegex.exec(llmsTxtContent)) !== null) {
+    urls.push(match[0]);
+  }
+
+  return [...new Set(urls)]; // Remove duplicates
+}
+
+// Convert URL to filename
+function urlToFilename(url) {
+  const urlObj = new URL(url);
+  let filename = urlObj.pathname.replace(/^\/docs\//, '').replace(/\/$/, '');
+
+  if (!filename) {
+    filename = 'index';
+  }
+
+  // Remove language prefix (e.g., "en/") to keep filenames clean
+  filename = filename.replace(/^en\//, '');
+
+  // Replace remaining slashes with dashes for nested paths
+  filename = filename.replace(/\//g, '-');
+
+  if (!filename.endsWith('.md')) {
+    filename += '.md';
+  }
+
+  return filename;
+}
+
+// Sleep utility
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// Ensure directory exists
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+// Main execution
+async function main() {
+  const args = parseArgs();
+  const { force, outputDir } = args;
+
+  console.log('Claude Code Documentation Fetcher');
+  console.log('==================================\n');
+
+  // Check cache freshness
+  if (!force && isCacheFresh(outputDir)) {
+    console.log('✓ Cache is fresh (less than 24 hours old)');
+    console.log('  Use --force to bypass cache check\n');
+    console.log(`Output directory: ${outputDir}`);
+    return;
+  }
+
+  // Ensure output directory exists
+  ensureDir(outputDir);
+
+  const stats = {
+    total: 0,
+    success: 0,
+    failed: 0,
+    failures: [],
+  };
+
+  try {
+    // Step 1: Fetch llms.txt
+    console.log('Fetching llms.txt...');
+    const llmsTxtContent = await fetchUrl(LLMS_TXT_URL);
+    console.log('✓ llms.txt fetched\n');
+
+    // Save llms.txt itself
+    const llmsTxtPath = path.join(outputDir, 'llms.txt');
+    fs.writeFileSync(llmsTxtPath, llmsTxtContent, 'utf-8');
+
+    // Step 2: Extract documentation URLs
+    const docUrls = extractDocUrls(llmsTxtContent);
+
+    if (docUrls.length === 0) {
+      console.log('⚠ No documentation URLs found in llms.txt');
+      return;
+    }
+
+    console.log(`Found ${docUrls.length} documentation URL(s)\n`);
+    stats.total = docUrls.length;
+
+    // Step 3: Fetch each documentation page
+    for (let i = 0; i < docUrls.length; i++) {
+      const url = docUrls[i];
+      const filename = urlToFilename(url);
+      const filepath = path.join(outputDir, filename);
+
+      try {
+        console.log(`[${i + 1}/${docUrls.length}] Fetching ${url}...`);
+        const content = await fetchUrl(url);
+        fs.writeFileSync(filepath, content, 'utf-8');
+        console.log(`  ✓ Saved to ${filename}`);
+        stats.success++;
+      } catch (error) {
+        console.log(`  ✗ Failed: ${error.message}`);
+        stats.failed++;
+        stats.failures.push({ url, error: error.message });
+      }
+
+      // Delay between requests
+      if (i < docUrls.length - 1) {
+        await sleep(FETCH_DELAY_MS);
+      }
+    }
+
+    // Step 4: Write last-updated timestamp
+    const timestamp = new Date().toISOString();
+    const lastUpdatedPath = path.join(outputDir, 'last-updated.txt');
+    fs.writeFileSync(lastUpdatedPath, timestamp, 'utf-8');
+
+    // Summary
+    console.log('\n==================================');
+    console.log('Summary:');
+    console.log(`  Total URLs:      ${stats.total}`);
+    console.log(`  Downloaded:      ${stats.success}`);
+    console.log(`  Failed:          ${stats.failed}`);
+    console.log(`  Save location:   ${outputDir}`);
+    console.log(`  Last updated:    ${timestamp}`);
+
+    if (stats.failures.length > 0) {
+      console.log('\nFailures:');
+      stats.failures.forEach(({ url, error }) => {
+        console.log(`  - ${url}`);
+        console.log(`    ${error}`);
+      });
+    }
+
+  } catch (error) {
+    console.error('\n✗ Fatal error:', error.message);
+    process.exit(1);
+  }
+}
+
+// Run
+main().catch(error => {
+  console.error('Unexpected error:', error);
+  process.exit(1);
+});

package/templates/.claude/skills/docker-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: docker-best-practices
 description: Docker patterns for optimized containerization
+user-invocable: false
 ---
 
 ## Purpose

package/templates/.claude/skills/fastapi-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: fastapi-best-practices
 description: FastAPI patterns for high-performance async APIs
+user-invocable: false
 ---
 
 ## Purpose

package/templates/.claude/skills/go-backend-best-practices/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: go-backend-best-practices
 description: Go backend patterns from Uber style and standard layout
+user-invocable: false
 ---
 
 ## Purpose

package/templates/.claude/skills/go-best-practices/CLAUDE.md

@@ -0,0 +1,9 @@
+<claude-mem-context>
+# Recent Activity
+
+### Feb 5, 2026
+
+| ID | Time | T | Title | Read |
+|----|------|---|-------|------|
+| #8 | 8:07 PM | 🔵 | Skill Definition Structure | ~626 |
+</claude-mem-context>