diff --git a/custom-skills/90-reference-curator/USER-GUIDE.md b/custom-skills/90-reference-curator/USER-GUIDE.md new file mode 100644 index 0000000..33b937d --- /dev/null +++ b/custom-skills/90-reference-curator/USER-GUIDE.md @@ -0,0 +1,297 @@ +# Reference Curator - User Guide + +A modular skill suite for curating reference documentation with Claude Code. + +## Quick Start + +### One-Shot Full Pipeline (Recommended) + +```bash +# Research a topic and generate reference library +/reference-curator-pipeline "Claude Code best practices" --auto-approve + +# From specific URLs +/reference-curator-pipeline https://docs.anthropic.com/en/docs/agents + +# With options +/reference-curator-pipeline "MCP servers" --max-sources 10 --export-format fine_tuning +``` + +### Run as Background Agent + +Ask Claude Code: +> "Run reference-curator as a background agent for topic X" + +This launches autonomous processing while you continue other work. + +--- + +## Individual Skills + +Use these when you need granular control over each stage. + +### 1. Reference Discovery + +**Purpose:** Search and discover authoritative sources + +```bash +/reference-discovery "prompt engineering techniques" +``` + +**Output:** Discovery manifest (JSON) with scored URLs + +| Tier | Score | Sources | +|------|-------|---------| +| tier1_official | ≥0.60 | Official docs, vendor blogs | +| tier2_verified | 0.40-0.59 | Research papers, cookbooks | +| tier3_community | <0.40 | Tutorials, blog posts | + +--- + +### 2. Web Crawler + +**Purpose:** Crawl URLs and save raw content + +```bash +# From discovery manifest +/web-crawler /path/to/manifest.json + +# Single URL +/web-crawler https://docs.example.com/guide +``` + +**Output:** Markdown files in `~/Documents/05_AI Agent/10_Reference Library/raw/YYYY/MM/` + +**Crawler Selection:** +| Crawler | Best For | +|---------|----------| +| Firecrawl (default) | SPAs, JS-rendered sites | +| WebFetch | Simple documentation pages | +| Node.js | Small static sites (≤50 pages) | + +--- + +### 3. Content Repository + +**Purpose:** Store documents in MySQL with versioning + +```bash +# Store crawled content +/content-repository store --topic "my-topic" + +# Query existing documents +/content-repository query --topic "my-topic" +``` + +**Prerequisites:** MySQL database `reference_library` with schema applied. + +--- + +### 4. Content Distiller + +**Purpose:** Summarize and extract key concepts + +```bash +/content-distiller --topic "my-topic" +``` + +**Output per document:** +- Executive summary (2-3 sentences) +- Key concepts (JSON) +- Code snippets (JSON) +- Structured content (Markdown) +- ~15-20% compression ratio + +--- + +### 5. Quality Reviewer + +**Purpose:** Score and approve content + +```bash +/quality-reviewer --topic "my-topic" +``` + +**Scoring Criteria:** +| Criterion | Weight | +|-----------|--------| +| Accuracy | 25% | +| Completeness | 20% | +| Clarity | 20% | +| PE Quality | 25% | +| Usability | 10% | + +**Decisions:** +| Score | Decision | Action | +|-------|----------|--------| +| ≥0.85 | APPROVE | Ready for export | +| 0.60-0.84 | REFACTOR | Re-distill with feedback | +| 0.40-0.59 | DEEP_RESEARCH | Crawl more sources | +| <0.40 | REJECT | Archive | + +--- + +### 6. Markdown Exporter + +**Purpose:** Generate final export files + +```bash +# Project files (for Claude Projects) +/markdown-exporter --topic "my-topic" --format project_files + +# Fine-tuning dataset (JSONL) +/markdown-exporter --topic "my-topic" --format fine_tuning +``` + +**Output Structure:** +``` +~/Documents/05_AI Agent/10_Reference Library/exports/ +├── INDEX.md +└── my-topic/ + ├── _index.md + ├── 01-document-one.md + ├── 02-document-two.md + └── ... +``` + +--- + +## Common Workflows + +### Workflow 1: Quick Reference on a Topic + +``` +You: "Create a reference library on n8n self-hosting" +Claude: [Runs full pipeline automatically] +``` + +### Workflow 2: Curate Specific URLs + +``` +You: "Add these URLs to my reference library: + - https://docs.example.com/guide1 + - https://docs.example.com/guide2" +Claude: [Skips discovery, crawls URLs directly] +``` + +### Workflow 3: Update Existing Topic + +``` +You: "Update the MCP developer manual with latest SDK docs" +Claude: [Discovers new sources, crawls, merges with existing] +``` + +### Workflow 4: Export for Fine-Tuning + +``` +You: "Export all approved content as JSONL for fine-tuning" +Claude: /markdown-exporter --format fine_tuning +``` + +--- + +## Configuration + +### Storage Paths + +| Type | Location | +|------|----------| +| Raw content | `~/Documents/05_AI Agent/10_Reference Library/raw/` | +| Exports | `~/Documents/05_AI Agent/10_Reference Library/exports/` | +| Config | `~/.config/reference-curator/` | + +### MySQL Setup + +Database credentials via `~/.my.cnf`: +```ini +[client] +user = root +password = your_password +socket = /tmp/mysql.sock +``` + +### Config Files + +``` +~/.config/reference-curator/ +├── db_config.yaml # Database connection +├── crawl_config.yaml # Crawler settings +└── export_config.yaml # Export preferences +``` + +--- + +## Tips + +### For Best Results + +1. **Be specific with topics** - "Claude Code MCP integration" > "MCP" +2. **Use official sources first** - tier1 sources get higher quality scores +3. **Review before export** - Check quality scores, refine if needed +4. **Use background agents** - For large topics, run as background task + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| MySQL auth failed | Check `~/.my.cnf` permissions (chmod 600) | +| Missing table | Run schema.sql from `shared/schema.sql` | +| Low quality scores | Add more tier1 sources, re-distill | +| Crawl timeout | Try different crawler or reduce max_pages | +| Export empty | Check documents are approved in quality review | + +### Checking Pipeline Status + +```sql +-- View pending documents +SELECT title, review_status FROM distilled_content +JOIN documents USING (doc_id) WHERE review_status = 'pending'; + +-- View export history +SELECT export_name, total_documents, status FROM export_jobs; +``` + +--- + +## Example Session + +``` +You: Create a reference library on "Anthropic Claude API best practices" + +Claude: Starting reference-curator pipeline... + +[1/6] Reference Discovery +- Searching docs.anthropic.com, github.com/anthropics... +- Found 12 authoritative sources (8 tier1, 3 tier2, 1 tier3) + +[2/6] Web Crawling +- Crawling 12 URLs with WebFetch... +- Saved 12 markdown files + +[3/6] Content Repository +- Stored 12 documents in MySQL +- Created topic: claude-api-best-practices + +[4/6] Content Distillation +- Distilled 12 documents (~18% avg compression) +- Extracted 45 key concepts + +[5/6] Quality Review +- Scored all documents +- 11 APPROVED (≥0.85), 1 REFACTOR (0.78) +- Re-distilling 1 document... APPROVED (0.86) + +[6/6] Markdown Export +- Generated 14 files (12 docs + 2 indexes) +- Output: ~/Documents/.../exports/claude-api-best-practices/ + +Pipeline complete! Reference library ready. +``` + +--- + +## Need Help? + +- **Skill source code:** `custom-skills/90-reference-curator/` +- **MySQL schema:** `shared/schema.sql` +- **Config templates:** `shared/config/` diff --git a/custom-skills/90-reference-curator/shared/config/crawl_config.yaml b/custom-skills/90-reference-curator/shared/config/crawl_config.yaml index becfbcf..19b9e9d 100644 --- a/custom-skills/90-reference-curator/shared/config/crawl_config.yaml +++ b/custom-skills/90-reference-curator/shared/config/crawl_config.yaml @@ -100,8 +100,8 @@ processing: - markdown # Storage paths (configurable) - raw_content_dir: ${REFERENCE_LIBRARY_PATH:-~/reference-library}/raw/ - processed_dir: ${REFERENCE_LIBRARY_PATH:-~/reference-library}/processed/ + raw_content_dir: ${REFERENCE_LIBRARY_PATH:-~/Documents/05_AI Agent/10_Reference Library}/raw/ + processed_dir: ${REFERENCE_LIBRARY_PATH:-~/Documents/05_AI Agent/10_Reference Library}/processed/ # URL filtering url_filter: diff --git a/custom-skills/90-reference-curator/shared/config/export_config.yaml b/custom-skills/90-reference-curator/shared/config/export_config.yaml index 3cab480..9d5790d 100644 --- a/custom-skills/90-reference-curator/shared/config/export_config.yaml +++ b/custom-skills/90-reference-curator/shared/config/export_config.yaml @@ -4,7 +4,7 @@ # Copy this file to ~/.config/reference-curator/export_config.yaml output: - base_path: ~/reference-library/exports/ + base_path: ~/Documents/05_AI Agent/10_Reference Library/exports/ # Project files format (for Claude Projects) project_files: diff --git a/custom-skills/90-reference-curator/shared/config/pipeline_config.yaml b/custom-skills/90-reference-curator/shared/config/pipeline_config.yaml index 37b0911..12236ab 100644 --- a/custom-skills/90-reference-curator/shared/config/pipeline_config.yaml +++ b/custom-skills/90-reference-curator/shared/config/pipeline_config.yaml @@ -30,7 +30,7 @@ state: backend: ${STATE_BACKEND:-file} # File-based state directory (used when backend=file) - state_directory: ${REFERENCE_LIBRARY_PATH:-~/reference-library}/pipeline_state/ + state_directory: ${REFERENCE_LIBRARY_PATH:-~/Documents/05_AI Agent/10_Reference Library}/pipeline_state/ logging: # Log level: DEBUG, INFO, WARNING, ERROR diff --git a/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json b/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json new file mode 100644 index 0000000..f1f5dc9 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "multi-agent-guide", + "version": "1.0.0", + "description": "Multi-agent collaboration framework for complex projects. Sets up agent hierarchies, ownership rules, guardrails, handoff protocols, and CI/CD integration for Claude, Gemini, Codex, and Human agents working together.", + "author": { + "name": "OurDigital", + "email": "ourdigital@example.com" + }, + "keywords": [ + "multi-agent", + "collaboration", + "guardrails", + "ownership", + "ci-cd", + "project-management" + ], + "license": "MIT" +} diff --git a/custom-skills/91-multi-agent-guide/SKILL.md b/custom-skills/91-multi-agent-guide/SKILL.md new file mode 100644 index 0000000..690bbdf --- /dev/null +++ b/custom-skills/91-multi-agent-guide/SKILL.md @@ -0,0 +1,429 @@ +--- +name: multi-agent-guide +description: Use when user asks to "set up multi-agent collaboration", "initialize multi-agent project", "create agent guardrails", "set up team AI collaboration", "configure agent ownership rules", "create agent handoff protocols", mentions "multi-agent guide", "multi-agent setup", "agent coordination", "AI agent collaboration", or wants to configure a project for multiple AI agents (Claude, Gemini, Codex) working together with proper ownership rules, task management, and CI/CD integration. +version: 1.0.0 +allowed-tools: Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion +--- + +# Multi-Agent Collaboration Guide Skill + +This skill helps you set up a comprehensive multi-agent collaboration framework for complex software projects where multiple AI agents (Claude Code, Gemini, Codex, and Human) work together. + +## Overview + +The multi-agent setup creates: + +| Component | Purpose | +|-----------|---------| +| **Agent Hierarchy** | Defines lead agent and sub-agents with clear authority levels | +| **Ownership Matrix** | Specifies which agent owns which files/directories | +| **Guardrails System** | Prevents conflicts through locks and task claiming | +| **Handoff Protocols** | Standardizes communication between agents | +| **CI/CD Integration** | Automated ownership verification in pipelines | +| **Pre-commit Hooks** | Local verification before commits | + +## When to Use This Skill + +Activate when users: + +1. **Starting a complex project** requiring multiple AI agents +2. **Organizing existing project** for multi-agent collaboration +3. **Setting up guardrails** to prevent agent conflicts +4. **Implementing ownership rules** for files and directories +5. **Creating handoff protocols** between AI agents +6. **Configuring CI/CD** for multi-agent workflows + +## Setup Workflow + +### Phase 1: Assessment + +Before setup, gather the following information: + +``` +1. Project type (Python, Node.js, monorepo, etc.) +2. Agent hierarchy (which agents will participate) +3. Primary ownership domains for each agent +4. Shared file coordination needs +5. CI/CD platform (GitHub Actions, GitLab CI, etc.) +``` + +### Phase 2: File Structure Creation + +Create the following directory structure: + +``` +project-root/ +├── .agent-state/ # Agent coordination state +│ ├── tasks.yaml # Task registry +│ └── locks.yaml # File lock registry +├── tools/ # Ownership verification scripts +│ └── check-ownership.py # Multi-agent ownership checker +├── AGENTS.md # Shared collaboration rules +├── GUARDRAILS.md # Ownership and enforcement rules +├── CLAUDE.md # Lead agent (Claude) directive +├── GEMINI.md # Sub-agent (Gemini) directive (optional) +├── CODEX.md # Sub-agent (Codex) directive (optional) +└── .pre-commit-config.yaml # Pre-commit hooks (update existing) +``` + +### Phase 3: Configuration + +The setup configures: + +1. **Agent identity** via `SEO_AGENT_AUTHOR` environment variable +2. **Ownership matrix** in check-ownership.py +3. **Task and lock state** in .agent-state/ YAML files +4. **Commit message format** enforcement: `[Agent] type(scope): description` +5. **Pre-commit hooks** for local verification +6. **CI/CD workflows** for PR verification (optional) + +--- + +## File Templates + +### AGENTS.md Template + +The shared rules file should include: + +```markdown +# AGENTS.md - Common Ground Rules & Collaboration Protocols + +## Agent Hierarchy + +| Agent | Role | Authority | Context File | +|-------|------|-----------|--------------| +| **Claude Code** | Lead / Orchestrator | Architecture, core logic, final decisions | `CLAUDE.md` | +| **Gemini** | Sub-agent | Google APIs, documentation, research | `GEMINI.md` | +| **Codex** | Sub-agent | Tests, boilerplate, docstrings | `CODEX.md` | + +## Handoff Protocols + +### Claude → Gemini Handoff +- Google API implementation +- Documentation writing +- Research tasks + +### Claude → Codex Handoff +- Unit test generation +- Boilerplate models +- Docstring generation + +## Commit Convention + +[Agent] type(scope): description + +Types: feat, fix, docs, test, refactor, chore +Agent tags: [Claude], [Gemini], [Codex], [Human] +``` + +### GUARDRAILS.md Template + +The enforcement rules file should include: + +```markdown +# GUARDRAILS.md - Ownership & Enforcement Rules + +## Ownership Matrix + +### Claude Primary Ownership +- `src/*/cli.py` +- `src/*/core/` +- Architecture-related files + +### Gemini Primary Ownership +- `src/*/integrations/google/` +- `docs/` +- Research documentation + +### Codex Primary Ownership +- `tests/` +- `src/*/models.py` +- `src/*/utils/` + +### Shared Files (Claude Approves) +- `pyproject.toml` +- `config/*.yaml` +- `.github/workflows/` + +### Unrestricted Files +- `.agent-state/` +- `.gitignore` +- `README.md` + +## Lock System + +Lock types: +- **exclusive**: Only one agent can modify +- **shared**: Multiple agents can read, one can write +- **override**: Claude override for conflict resolution + +Lock file format (.agent-state/locks.yaml): +```yaml +version: "1.0" +locks: + - path: "src/module/" + agent: "claude" + lock_type: "exclusive" + task_id: "TASK-001" + expires_at: "2025-01-30T12:00:00Z" +``` + +## Task Claiming Protocol + +1. Check task status in .agent-state/tasks.yaml +2. Claim task by setting agent and status +3. Acquire necessary file locks +4. Complete work +5. Release locks and mark task complete +``` + +### check-ownership.py Template + +The ownership verification script should: + +1. Define `OWNERSHIP_MATRIX` with regex patterns +2. Define `SHARED_FILES` requiring Claude approval +3. Define `UNRESTRICTED_FILES` anyone can modify +4. Check file ownership before allowing modifications +5. Verify lock status in `.agent-state/locks.yaml` +6. Validate commit message format + +Key functions: +- `get_file_owner(filepath)` → Returns (owner, ownership_type) +- `is_file_locked(filepath, root)` → Returns (is_locked, lock_info) +- `verify_ownership(files, agent, root)` → Returns (violations, warnings) +- `check_commit_message(msg_file)` → Returns bool + +--- + +## Setup Commands + +### Quick Setup (Recommended) + +When user requests multi-agent setup, follow these steps: + +1. **Ask configuration questions**: + ``` + - What is your project name and type? + - Which agents will participate? (Claude, Gemini, Codex, custom) + - What are the main directories/domains for each agent? + - Do you want CI/CD integration? (GitHub Actions, GitLab CI) + ``` + +2. **Create directory structure**: + ```bash + mkdir -p .agent-state + mkdir -p tools + ``` + +3. **Generate configuration files** from templates: + - AGENTS.md (customize based on project) + - GUARDRAILS.md (customize ownership matrix) + - Agent-specific .md files (CLAUDE.md, etc.) + - .agent-state/tasks.yaml (initialize empty) + - .agent-state/locks.yaml (initialize empty) + - tools/check-ownership.py (customize OWNERSHIP_MATRIX) + +4. **Update pre-commit configuration**: + - Add check-ownership hook + - Add commit-message hook + +5. **Optional: Create CI workflow**: + - GitHub Actions ownership-check.yml + - Or equivalent for other CI systems + +### Environment Setup + +Instruct users to set agent identity: + +```bash +# Add to shell profile (.bashrc, .zshrc) +export SEO_AGENT_AUTHOR=claude # or gemini, codex, human + +# Or use direnv (.envrc) +export SEO_AGENT_AUTHOR=claude +``` + +--- + +## Customization Guide + +### Adding New Agents + +1. Create `AGENTNAME.md` at project root +2. Add to AGENTS.md hierarchy table +3. Update OWNERSHIP_MATRIX in check-ownership.py +4. Add to VALID_AGENTS set + +### Modifying Ownership Rules + +1. Edit OWNERSHIP_MATRIX in check-ownership.py +2. Update GUARDRAILS.md documentation +3. Communicate changes to all agents + +### Adjusting Lock Timeouts + +Default lock expiration: 4 hours + +To change, modify the task/lock creation logic to use different `expires_at` values. + +--- + +## Integration with CI/CD + +### GitHub Actions + +Create `.github/workflows/ownership-check.yml`: + +```yaml +name: Ownership Check + +on: + pull_request: + branches: [main, develop] + +jobs: + check-ownership: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: '3.11' + + - name: Install dependencies + run: pip install pyyaml + + - name: Get changed files + id: changed-files + uses: tj-actions/changed-files@v44 + + - name: Check ownership + env: + SEO_AGENT_AUTHOR: ci + run: | + python tools/check-ownership.py ${{ steps.changed-files.outputs.all_changed_files }} +``` + +### Pre-commit Integration + +Add to `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: local + hooks: + - id: check-ownership + name: Check Agent Ownership + entry: python tools/check-ownership.py + language: python + always_run: true + pass_filenames: true + additional_dependencies: [pyyaml] + + - id: check-commit-message + name: Check Commit Message Format + entry: python tools/check-ownership.py --check-commit-msg + language: python + stages: [commit-msg] + additional_dependencies: [pyyaml] +``` + +--- + +## Best Practices + +### Agent Coordination + +| Practice | Description | +|----------|-------------| +| **Claim before work** | Always claim tasks in .agent-state/tasks.yaml | +| **Lock during edits** | Acquire locks for files you're modifying | +| **Release promptly** | Don't hold locks longer than necessary | +| **Use handoff format** | Follow standard handoff protocol for delegation | +| **Attribution** | Always include agent tag in commit messages | + +### Conflict Resolution + +1. **Check locks first** - Don't modify locked files +2. **Escalate to Claude** - Claude can override locks +3. **Document conflicts** - Update GUARDRAILS.md if patterns emerge +4. **Communicate changes** - Notify other agents of ownership changes + +### Code Style + +Maintain consistent code style across agents: + +| Aspect | Standard | +|--------|----------| +| Formatter | Black (Python), Prettier (JS) | +| Line length | 100 characters | +| Docstrings | Google-style | +| Type hints | Required | + +--- + +## Reference Files + +Supporting files in this skill: + +| File | Purpose | +|------|---------| +| `templates/agents-md.md` | AGENTS.md template | +| `templates/guardrails-md.md` | GUARDRAILS.md template | +| `templates/claude-md.md` | CLAUDE.md template | +| `templates/gemini-md.md` | GEMINI.md template | +| `templates/codex-md.md` | CODEX.md template | +| `templates/tasks-yaml.yaml` | Tasks file template | +| `templates/locks-yaml.yaml` | Locks file template | +| `scripts/check-ownership.py` | Ownership verification script | +| `references/ownership-matrix.md` | Detailed ownership patterns | +| `examples/minimal-setup/` | Minimal 2-agent setup example | +| `examples/full-setup/` | Full 3-agent setup example | + +--- + +## Commands + +Available actions when this skill is active: + +| Command | Description | +|---------|-------------| +| "Set up multi-agent collaboration" | Initialize full framework | +| "Add new agent [name]" | Add a new agent to existing setup | +| "Update ownership matrix" | Modify file ownership rules | +| "Check agent setup" | Verify configuration is correct | +| "Create handoff for [agent]" | Generate handoff document | +| "Initialize task" | Create new task in tasks.yaml | + +--- + +## Troubleshooting + +### Common Issues + +**"Ownership violation" error**: +- Check `SEO_AGENT_AUTHOR` environment variable is set +- Verify file is in your agent's ownership domain +- Ask lead agent (Claude) for override if needed + +**"File locked" error**: +- Check `.agent-state/locks.yaml` for active locks +- Wait for lock to expire or ask owner to release +- Claude can override locks if urgent + +**Pre-commit hook fails**: +- Verify PyYAML is installed: `pip install pyyaml` +- Check `.agent-state/` directory exists +- Ensure commit message follows format + +**CI workflow fails**: +- Verify changed files list is correct +- Check that check-ownership.py is in tools/ +- Ensure Python and dependencies are available + +--- + +*This skill is designed for complex projects requiring coordinated multi-agent collaboration with clear ownership, accountability, and conflict prevention.* diff --git a/custom-skills/91-multi-agent-guide/examples/minimal-setup/README.md b/custom-skills/91-multi-agent-guide/examples/minimal-setup/README.md new file mode 100644 index 0000000..969b62f --- /dev/null +++ b/custom-skills/91-multi-agent-guide/examples/minimal-setup/README.md @@ -0,0 +1,67 @@ +# Minimal Multi-Agent Setup Example + +This example shows the minimum files needed for a 2-agent setup (Claude + Codex). + +## Directory Structure + +``` +project/ +├── .agent-state/ +│ ├── tasks.yaml +│ └── locks.yaml +├── tools/ +│ └── check-ownership.py +├── AGENTS.md +├── GUARDRAILS.md +└── CLAUDE.md +``` + +## Files Created + +1. **AGENTS.md** - Basic agent hierarchy (Claude lead, Codex sub-agent) +2. **GUARDRAILS.md** - Simplified ownership matrix +3. **CLAUDE.md** - Lead agent directive +4. **.agent-state/** - Task and lock management +5. **tools/check-ownership.py** - Verification script + +## Setup Steps + +1. Create directories: + ```bash + mkdir -p .agent-state tools + ``` + +2. Copy templates (customize as needed): + ```bash + # From skill templates + cp templates/agents-md.md AGENTS.md + cp templates/guardrails-md.md GUARDRAILS.md + cp templates/claude-md.md CLAUDE.md + cp templates/tasks-yaml.yaml .agent-state/tasks.yaml + cp templates/locks-yaml.yaml .agent-state/locks.yaml + cp scripts/check-ownership.py tools/check-ownership.py + ``` + +3. Set environment variable: + ```bash + export SEO_AGENT_AUTHOR=claude + ``` + +4. Verify setup: + ```bash + python tools/check-ownership.py --verify-setup + ``` + +## Ownership Matrix (Minimal) + +| Agent | Owns | +|-------|------| +| Claude | `src/`, `CLAUDE.md`, `AGENTS.md`, `GUARDRAILS.md` | +| Codex | `tests/`, `CODEX.md` | + +## Commit Format + +``` +[Claude] type(scope): description +[Codex] type(scope): description +``` diff --git a/custom-skills/91-multi-agent-guide/references/ownership-matrix.md b/custom-skills/91-multi-agent-guide/references/ownership-matrix.md new file mode 100644 index 0000000..4663dea --- /dev/null +++ b/custom-skills/91-multi-agent-guide/references/ownership-matrix.md @@ -0,0 +1,233 @@ +# Ownership Matrix Reference + +This document provides detailed patterns for configuring the ownership matrix in `check-ownership.py`. + +## Pattern Syntax + +The ownership matrix uses Python regular expressions (regex) to match file paths. + +### Common Patterns + +| Pattern | Matches | Example Files | +|---------|---------|---------------| +| `^src/cli\.py$` | Exact file | `src/cli.py` | +| `^src/.*/cli\.py$` | Any subdirectory | `src/app/cli.py`, `src/core/cli.py` | +| `^src/core/` | Directory prefix | `src/core/main.py`, `src/core/utils/helper.py` | +| `^tests/` | All tests | `tests/test_main.py`, `tests/unit/test_foo.py` | +| `^docs/.*\.md$` | Markdown in docs | `docs/api.md`, `docs/guides/setup.md` | +| `\.py$` | All Python files | Any `.py` file | + +### Regex Cheat Sheet + +| Symbol | Meaning | Example | +|--------|---------|---------| +| `^` | Start of string | `^src/` matches paths starting with `src/` | +| `$` | End of string | `\.py$` matches paths ending with `.py` | +| `.` | Any character | `a.c` matches `abc`, `a1c`, etc. | +| `\.` | Literal dot | `\.py` matches `.py` | +| `*` | Zero or more | `a*` matches ``, `a`, `aa`, `aaa` | +| `+` | One or more | `a+` matches `a`, `aa`, `aaa` | +| `.*` | Any characters | `src/.*` matches anything starting with `src/` | +| `[abc]` | Character class | `[abc]` matches `a`, `b`, or `c` | +| `\w` | Word character | `\w+` matches words | +| `\d` | Digit | `\d+` matches numbers | +| `(a\|b)` | Alternation | `(foo\|bar)` matches `foo` or `bar` | + +## Project-Specific Examples + +### Python Project + +```python +OWNERSHIP_MATRIX: Dict[str, str] = { + # Claude - Core application + r"^src/app/": "claude", + r"^src/core/": "claude", + r"^src/.*/cli\.py$": "claude", + r"^CLAUDE\.md$": "claude", + r"^AGENTS\.md$": "claude", + r"^GUARDRAILS\.md$": "claude", + + # Gemini - APIs and documentation + r"^src/.*/api/": "gemini", + r"^src/.*/integrations/": "gemini", + r"^docs/": "gemini", + r"^GEMINI\.md$": "gemini", + + # Codex - Testing and utilities + r"^tests/": "codex", + r"^src/.*/models\.py$": "codex", + r"^src/.*/utils/": "codex", + r"^CODEX\.md$": "codex", +} +``` + +### TypeScript Project + +```python +OWNERSHIP_MATRIX: Dict[str, str] = { + # Claude - Core application + r"^src/app/": "claude", + r"^src/core/": "claude", + r"^src/index\.ts$": "claude", + r"^CLAUDE\.md$": "claude", + + # Gemini - APIs and documentation + r"^src/api/": "gemini", + r"^src/services/": "gemini", + r"^docs/": "gemini", + r"^GEMINI\.md$": "gemini", + + # Codex - Testing and utilities + r"^tests/": "codex", + r"^__tests__/": "codex", + r"^src/.*/.*\.test\.ts$": "codex", + r"^src/types/": "codex", + r"^src/utils/": "codex", + r"^CODEX\.md$": "codex", +} +``` + +### Monorepo Project + +```python +OWNERSHIP_MATRIX: Dict[str, str] = { + # Claude - Core packages + r"^packages/core/": "claude", + r"^packages/cli/": "claude", + r"^CLAUDE\.md$": "claude", + + # Gemini - API packages + r"^packages/api/": "gemini", + r"^packages/sdk/": "gemini", + r"^docs/": "gemini", + r"^GEMINI\.md$": "gemini", + + # Codex - Testing and shared + r"^packages/testing/": "codex", + r"^packages/shared/": "codex", + r"^packages/.*/tests/": "codex", + r"^CODEX\.md$": "codex", +} +``` + +## Shared Files Configuration + +Files that require coordination between agents: + +```python +SHARED_FILES: Set[str] = { + # Package configuration + r"^pyproject\.toml$", + r"^package\.json$", + r"^Cargo\.toml$", + + # Build configuration + r"^Makefile$", + r"^Dockerfile$", + r"^docker-compose\.ya?ml$", + + # CI/CD + r"^\.github/workflows/", + r"^\.gitlab-ci\.yml$", + r"^\.circleci/", + + # Project planning + r"^PROJECT_PLAN\.md$", + r"^ROADMAP\.md$", + r"^CHANGELOG\.md$", +} +``` + +## Unrestricted Files Configuration + +Files any agent can modify: + +```python +UNRESTRICTED_FILES: Set[str] = { + # Agent state + r"^\.agent-state/", + + # Git configuration + r"^\.gitignore$", + r"^\.gitattributes$", + + # Editor configuration + r"^\.vscode/", + r"^\.idea/", + + # Documentation + r"^README\.md$", + r"^CONTRIBUTING\.md$", + r"^LICENSE$", + + # Pre-commit + r"^\.pre-commit-config\.yaml$", +} +``` + +## Custom Agent Example + +Adding a custom agent (e.g., "designer"): + +```python +# 1. Add to valid agents +VALID_AGENTS = {"claude", "gemini", "codex", "human", "designer"} + +# 2. Add ownership patterns +OWNERSHIP_MATRIX: Dict[str, str] = { + # ... existing patterns ... + + # Designer - UI and styles + r"^src/components/": "designer", + r"^src/styles/": "designer", + r"^src/.*/.*\.css$": "designer", + r"^src/.*/.*\.scss$": "designer", + r"^DESIGNER\.md$": "designer", +} + +# 3. Update commit message pattern in check_commit_message() +pattern = r"^\[(Claude|Gemini|Codex|Human|Designer|CI)\]\s+\w+(\([^)]+\))?:\s+.+" +``` + +## Testing Patterns + +Test your patterns using Python: + +```python +import re + +def test_pattern(pattern: str, test_paths: list) -> None: + """Test a regex pattern against multiple paths.""" + for path in test_paths: + match = re.match(pattern, path) + print(f"{path}: {'MATCH' if match else 'NO MATCH'}") + +# Example +test_pattern(r"^src/.*/cli\.py$", [ + "src/cli.py", # NO MATCH (no subdirectory) + "src/app/cli.py", # MATCH + "src/core/cli.py", # MATCH + "src/a/b/cli.py", # MATCH +]) +``` + +## Debugging Tips + +1. **Pattern not matching?** + - Check for literal dots (use `\.` not `.`) + - Verify start `^` and end `$` anchors + - Test with simple paths first + +2. **Pattern too broad?** + - Add more specific path components + - Use `$` to anchor end of pattern + - Add file extension matching + +3. **Multiple agents matching?** + - First match wins + - Order patterns from specific to general + - Use more specific patterns for exceptions + +--- + +*Customize the ownership matrix for your specific project structure.* diff --git a/custom-skills/91-multi-agent-guide/scripts/check-ownership.py b/custom-skills/91-multi-agent-guide/scripts/check-ownership.py new file mode 100644 index 0000000..8272beb --- /dev/null +++ b/custom-skills/91-multi-agent-guide/scripts/check-ownership.py @@ -0,0 +1,496 @@ +#!/usr/bin/env python3 +""" +Multi-Agent Ownership Verification Script + +This script enforces file ownership rules and lock verification for the +multi-agent workflow defined in GUARDRAILS.md. + +Usage: + # Verify files before commit + python tools/check-ownership.py path/to/file.py + + # Check commit message format + python tools/check-ownership.py --check-commit-msg + + # Verify setup + python tools/check-ownership.py --verify-setup + + # List expired locks/tasks + python tools/check-ownership.py --list-expired + + # Validate state files + python tools/check-ownership.py --validate-state + +Environment: + SEO_AGENT_AUTHOR: Agent identity (claude|gemini|codex|human) +""" + +import argparse +import os +import re +import sys +from datetime import datetime, timezone +from pathlib import Path +from typing import Dict, List, Optional, Set, Tuple + +try: + import yaml +except ImportError: + print("Warning: PyYAML not installed. Install with: pip install pyyaml") + yaml = None + +# ============================================================================= +# CUSTOMIZE: Ownership Matrix +# ============================================================================= +# Modify these patterns to match your project structure + +# Primary ownership rules: pattern -> owner +OWNERSHIP_MATRIX: Dict[str, str] = { + # Claude ownership (customize for your project) + r"^src/.*/cli\.py$": "claude", + r"^src/.*/core/": "claude", + r"^src/.*/main\.py$": "claude", + r"^CLAUDE\.md$": "claude", + r"^AGENTS\.md$": "claude", + r"^GUARDRAILS\.md$": "claude", + # Gemini ownership + r"^src/.*/integrations/google/": "gemini", + r"^src/.*/integrations/gsc\.py$": "gemini", + r"^src/.*/integrations/ga.*\.py$": "gemini", + r"^docs/.*\.md$": "gemini", + r"^GEMINI\.md$": "gemini", + # Codex ownership + r"^src/.*/models\.py$": "codex", + r"^src/.*/utils/": "codex", + r"^tests/": "codex", + r"^CODEX\.md$": "codex", +} + +# Shared files (require coordination, Claude approves) +SHARED_FILES: Set[str] = { + r"^pyproject\.toml$", + r"^package\.json$", + r"^config/.*\.yaml$", + r"^config/.*\.json$", + r"^\\.github/workflows/", + r"^PROJECT_PLAN\.md$", +} + +# Files that any agent can modify without ownership check +UNRESTRICTED_FILES: Set[str] = { + r"^\\.agent-state/", + r"^\\.pre-commit-config\\.yaml$", + r"^\\.gitignore$", + r"^README\\.md$", +} + +# Valid agents (add custom agents here) +VALID_AGENTS = {"claude", "gemini", "codex", "human"} + + +# ============================================================================= +# Helper Functions +# ============================================================================= + + +def get_project_root() -> Path: + """Find the project root directory.""" + current = Path(__file__).resolve().parent + while current != current.parent: + if (current / "pyproject.toml").exists(): + return current + if (current / "package.json").exists(): + return current + if (current / ".git").exists(): + return current + current = current.parent + return Path.cwd() + + +def get_agent_author() -> Optional[str]: + """Get the current agent from environment variable.""" + agent = os.environ.get("SEO_AGENT_AUTHOR", "").lower() + return agent if agent in VALID_AGENTS else None + + +def load_yaml_file(filepath: Path) -> Optional[dict]: + """Load a YAML file safely.""" + if yaml is None: + return None + if not filepath.exists(): + return None + try: + with open(filepath, "r") as f: + return yaml.safe_load(f) + except Exception as e: + print(f"Warning: Could not load {filepath}: {e}") + return None + + +def get_file_owner(filepath: str) -> Tuple[Optional[str], str]: + """ + Determine the owner of a file. + + Returns: + Tuple of (owner, ownership_type) where ownership_type is + 'primary', 'shared', 'unrestricted', or 'unknown' + """ + # Normalize path + filepath = filepath.replace("\\", "/").lstrip("./") + + # Check unrestricted first + for pattern in UNRESTRICTED_FILES: + if re.match(pattern, filepath): + return None, "unrestricted" + + # Check shared files + for pattern in SHARED_FILES: + if re.match(pattern, filepath): + return "shared", "shared" + + # Check primary ownership + for pattern, owner in OWNERSHIP_MATRIX.items(): + if re.match(pattern, filepath): + return owner, "primary" + + return None, "unknown" + + +def is_file_locked(filepath: str, root: Path) -> Tuple[bool, Optional[dict]]: + """ + Check if a file is locked by another agent. + + Returns: + Tuple of (is_locked, lock_info) + """ + locks_file = root / ".agent-state" / "locks.yaml" + locks_data = load_yaml_file(locks_file) + + if not locks_data or "locks" not in locks_data: + return False, None + + filepath = filepath.replace("\\", "/").lstrip("./") + current_time = datetime.now(timezone.utc) + + for lock in locks_data.get("locks", []): + if not lock: + continue + lock_path = lock.get("path", "").replace("\\", "/").lstrip("./") + + # Check if path matches (exact or prefix for directories) + if filepath == lock_path or filepath.startswith(lock_path + "/"): + # Check if lock is expired + expires_at = lock.get("expires_at") + if expires_at: + try: + expiry = datetime.fromisoformat(expires_at.replace("Z", "+00:00")) + if current_time > expiry: + continue # Lock expired + except ValueError: + pass + + return True, lock + + return False, None + + +def check_commit_message(msg_file: str) -> bool: + """ + Verify commit message follows the [Agent] type(scope): description format. + """ + try: + with open(msg_file, "r") as f: + first_line = f.readline().strip() + except Exception as e: + print(f"Error reading commit message: {e}") + return False + + # Skip merge commits and fixup commits + if first_line.startswith("Merge ") or first_line.startswith("fixup!"): + return True + + # Pattern: [Agent] type(scope): description + pattern = r"^\[(Claude|Gemini|Codex|Human|CI)\]\s+\w+(\([^)]+\))?:\s+.+" + if not re.match(pattern, first_line, re.IGNORECASE): + print("Error: Commit message must follow format: [Agent] type(scope): description") + print(f" Got: {first_line}") + print(" Example: [Claude] feat(core): add new feature") + print(" Valid agents: Claude, Gemini, Codex, Human, CI") + return False + + return True + + +def verify_ownership(files: List[str], agent: str, root: Path) -> Tuple[List[str], List[str]]: + """ + Verify ownership for a list of files. + + Returns: + Tuple of (violations, warnings) + """ + violations = [] + warnings = [] + + for filepath in files: + owner, ownership_type = get_file_owner(filepath) + + # Unrestricted files - anyone can modify + if ownership_type == "unrestricted": + continue + + # Unknown files - warn but don't block + if ownership_type == "unknown": + warnings.append(f"Unknown ownership for: {filepath}") + continue + + # Shared files - warn (Claude should approve) + if ownership_type == "shared": + if agent != "claude": + warnings.append(f"Shared file modified (requires Claude approval): {filepath}") + continue + + # Primary ownership check + if owner and owner != agent: + # Claude can override any ownership + if agent == "claude": + warnings.append(f"Claude overriding {owner}'s ownership: {filepath}") + else: + violations.append(f"Ownership violation: {filepath} is owned by {owner}") + + # Lock check + is_locked, lock_info = is_file_locked(filepath, root) + if is_locked and lock_info: + lock_agent = lock_info.get("agent", "unknown") + if lock_agent != agent: + # Claude can override locks + if agent == "claude" and lock_info.get("lock_type") != "override": + warnings.append(f"Claude overriding {lock_agent}'s lock: {filepath}") + else: + task_id = lock_info.get("task_id", "unknown") + violations.append(f"File locked by {lock_agent}: {filepath} (task: {task_id})") + + return violations, warnings + + +def verify_setup() -> bool: + """Verify that the agent environment is properly configured.""" + agent = get_agent_author() + root = get_project_root() + + print("=== Agent Environment Verification ===\n") + + # Check environment variable + if agent: + print(f"[OK] SEO_AGENT_AUTHOR is set to: {agent}") + else: + env_val = os.environ.get("SEO_AGENT_AUTHOR", "") + if env_val: + print(f"[ERROR] Invalid SEO_AGENT_AUTHOR value: {env_val}") + print(f" Valid values: {', '.join(sorted(VALID_AGENTS))}") + else: + print("[WARNING] SEO_AGENT_AUTHOR is not set") + print(" Set with: export SEO_AGENT_AUTHOR=") + + # Check state files + tasks_file = root / ".agent-state" / "tasks.yaml" + locks_file = root / ".agent-state" / "locks.yaml" + + if tasks_file.exists(): + print(f"[OK] Tasks file exists: {tasks_file}") + else: + print(f"[WARNING] Tasks file not found: {tasks_file}") + + if locks_file.exists(): + print(f"[OK] Locks file exists: {locks_file}") + else: + print(f"[WARNING] Locks file not found: {locks_file}") + + # Check GUARDRAILS.md + guardrails = root / "GUARDRAILS.md" + if guardrails.exists(): + print("[OK] GUARDRAILS.md exists") + else: + print("[ERROR] GUARDRAILS.md not found") + + print("\n=== Setup Complete ===") + return agent is not None + + +def list_expired(root: Path) -> None: + """List expired tasks and locks.""" + current_time = datetime.now(timezone.utc) + + # Check tasks + tasks_file = root / ".agent-state" / "tasks.yaml" + tasks_data = load_yaml_file(tasks_file) + + print("=== Expired Tasks ===\n") + if tasks_data and "tasks" in tasks_data: + found_expired = False + for task in tasks_data.get("tasks", []): + if not task or task.get("status") in ("completed", "abandoned"): + continue + expires_at = task.get("expires_at") + if expires_at: + try: + expiry = datetime.fromisoformat(expires_at.replace("Z", "+00:00")) + if current_time > expiry: + found_expired = True + print(f" - {task.get('id')}: {task.get('description')}") + print(f" Agent: {task.get('agent')}, Expired: {expires_at}") + except ValueError: + pass + if not found_expired: + print(" No expired tasks found.") + else: + print(" No tasks file or empty.") + + # Check locks + locks_file = root / ".agent-state" / "locks.yaml" + locks_data = load_yaml_file(locks_file) + + print("\n=== Expired Locks ===\n") + if locks_data and "locks" in locks_data: + found_expired = False + for lock in locks_data.get("locks", []): + if not lock: + continue + expires_at = lock.get("expires_at") + if expires_at: + try: + expiry = datetime.fromisoformat(expires_at.replace("Z", "+00:00")) + if current_time > expiry: + found_expired = True + print(f" - {lock.get('path')}") + print(f" Agent: {lock.get('agent')}, Task: {lock.get('task_id')}") + except ValueError: + pass + if not found_expired: + print(" No expired locks found.") + else: + print(" No locks file or empty.") + + +def validate_state(root: Path) -> bool: + """Validate the structure of state files.""" + valid = True + + # Validate tasks.yaml + tasks_file = root / ".agent-state" / "tasks.yaml" + tasks_data = load_yaml_file(tasks_file) + + print("=== Validating State Files ===\n") + + if tasks_data: + print("[OK] tasks.yaml is valid YAML") + if "version" not in tasks_data: + print("[WARNING] tasks.yaml missing 'version' field") + if "tasks" not in tasks_data: + print("[WARNING] tasks.yaml missing 'tasks' field") + else: + if tasks_file.exists(): + print("[ERROR] tasks.yaml is not valid YAML") + valid = False + else: + print("[WARNING] tasks.yaml does not exist") + + # Validate locks.yaml + locks_file = root / ".agent-state" / "locks.yaml" + locks_data = load_yaml_file(locks_file) + + if locks_data: + print("[OK] locks.yaml is valid YAML") + if "version" not in locks_data: + print("[WARNING] locks.yaml missing 'version' field") + if "locks" not in locks_data: + print("[WARNING] locks.yaml missing 'locks' field") + else: + if locks_file.exists(): + print("[ERROR] locks.yaml is not valid YAML") + valid = False + else: + print("[WARNING] locks.yaml does not exist") + + return valid + + +# ============================================================================= +# Main Entry Point +# ============================================================================= + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Multi-Agent Ownership Verification", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=__doc__, + ) + parser.add_argument("files", nargs="*", help="Files to check ownership for") + parser.add_argument( + "--check-commit-msg", + metavar="FILE", + nargs="?", + const=".git/COMMIT_EDITMSG", + help="Check commit message format", + ) + parser.add_argument("--verify-setup", action="store_true", help="Verify agent environment") + parser.add_argument("--list-expired", action="store_true", help="List expired tasks/locks") + parser.add_argument( + "--validate-state", action="store_true", help="Validate state file structure" + ) + parser.add_argument("--strict", action="store_true", help="Treat warnings as errors") + + args = parser.parse_args() + root = get_project_root() + + # Handle special commands + if args.verify_setup: + return 0 if verify_setup() else 1 + + if args.list_expired: + list_expired(root) + return 0 + + if args.validate_state: + return 0 if validate_state(root) else 1 + + if args.check_commit_msg: + return 0 if check_commit_message(args.check_commit_msg) else 1 + + # Default: check file ownership + if not args.files: + print("No files specified. Use --help for usage.") + return 0 + + agent = get_agent_author() + if not agent: + print("Warning: SEO_AGENT_AUTHOR not set or invalid.") + print(" Set with: export SEO_AGENT_AUTHOR=") + print(" Ownership check skipped.") + return 0 + + violations, warnings = verify_ownership(args.files, agent, root) + + # Print results + if warnings: + print("\n=== Warnings ===") + for warning in warnings: + print(f" [WARN] {warning}") + + if violations: + print("\n=== Ownership Violations ===") + for violation in violations: + print(f" [ERROR] {violation}") + print(f"\nAgent '{agent}' cannot modify these files.") + print("See GUARDRAILS.md for ownership rules.") + return 1 + + if args.strict and warnings: + print("\n[STRICT MODE] Treating warnings as errors.") + return 1 + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/custom-skills/91-multi-agent-guide/templates/agents-md.md b/custom-skills/91-multi-agent-guide/templates/agents-md.md new file mode 100644 index 0000000..295e680 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/agents-md.md @@ -0,0 +1,327 @@ +# AGENTS.md - Common Ground Rules & Collaboration Protocols + +This file defines the shared rules, handoff protocols, and guidelines for all AI agents working on this repository. + +> **Master Plan Reference**: For strategic decisions, roadmap, and feature priorities, consult [`PROJECT_PLAN.md`](./PROJECT_PLAN.md) if available. + +> **Enforcement Layer**: For ownership rules, task claiming, and conflict resolution, see [`GUARDRAILS.md`](./GUARDRAILS.md). + +## Agent Hierarchy + +| Agent | Role | Authority | Context File | +|-------|------|-----------|--------------| +| **Claude Code** | Lead / Orchestrator | Architecture, core logic, final decisions | `CLAUDE.md` | +| **Gemini** | Sub-agent | Google APIs, documentation, research | `GEMINI.md` | +| **Codex** | Sub-agent | Tests, boilerplate, docstrings | `CODEX.md` | +| **Human** | Supervisor | Final approval, business decisions | N/A | + +**All agents read this file (`AGENTS.md`) as the shared source of truth.** + +--- + +## 1. Project Status + + + +| Aspect | Status | Notes | +|--------|--------|-------| +| **Stage** | [Development/Beta/Production] | | +| **Primary Language** | [Python/TypeScript/etc.] | | +| **Test Coverage** | [X%] | Target: 80% | +| **Documentation** | [Status] | See `docs/` directory | + +--- + +## 2. Handoff Protocols + +### 2.1 Claude → Gemini Handoff + +**When to delegate:** +- Google API implementation (GSC, GA4, PageSpeed, etc.) +- Documentation writing (user guides, tutorials) +- Research on best practices or algorithm updates +- Content quality assessment logic + +**Handoff format:** +```markdown +## Task for Gemini + +**Type:** [Google API | Documentation | Research] +**Priority:** [High | Medium | Low] + +### Objective +[Clear description of what needs to be done] + +### Interface/Contract (if API) +```python +# Claude defines the interface +class SomeProtocol(Protocol): + async def method(...) -> SomeResponse: + ... +``` + +### Deliverables +- [ ] Implementation file(s) +- [ ] Unit tests (optional, Codex can assist) +- [ ] Documentation updates + +### Constraints +- Follow code style in AGENTS.md Section 4 +- Use existing patterns from the codebase +``` + +**Return protocol:** +Gemini returns completed code → Claude reviews → Claude integrates. + +--- + +### 2.2 Claude → Codex Handoff + +**When to delegate:** +- Unit test generation from existing code +- Boilerplate Pydantic/dataclass models +- Docstring generation +- Repetitive pattern implementation + +**Handoff format:** +```markdown +## Task for Codex + +**Type:** [Tests | Models | Docstrings | Boilerplate] + +### Pattern to Follow +```python +# Claude provides the first example +class ExampleClass(BaseClass): + def method(self, arg: str) -> Result: + ... +``` + +### Generate +- [ ] SimilarClass1 (same pattern) +- [ ] SimilarClass2 (same pattern) +- [ ] Tests for all classes +``` + +**Return protocol:** +Codex generates → Claude reviews for edge cases → Claude commits. + +--- + +### 2.3 Sub-agent → Claude Escalation + +**When to escalate back:** +- Complex error handling needed +- Multi-file integration required +- Architectural decisions needed +- Rate limiting / caching strategy + +**Escalation format:** +```markdown +## Escalation to Claude + +**Reason:** [Complexity | Architecture | Integration] + +### Completed Work +[What was finished] + +### Blocking Issue +[What requires Claude's decision] + +### Proposed Options +1. Option A: ... +2. Option B: ... +``` + +--- + +## 3. Development Workflow + +> **Task Claiming**: Before starting work, claim your task in `.agent-state/tasks.yaml`. +> See [`GUARDRAILS.md`](./GUARDRAILS.md) for the full claiming protocol. + +### Phase 1: Planning (Claude Lead) + +``` +User Request → Claude analyzes + ↓ + Claude creates task breakdown + ↓ + Claude assigns to agents + ↓ + Claude defines interfaces +``` + +### Phase 2: Implementation (Parallel) + +``` +┌─────────────┬─────────────┬─────────────┐ +│ Claude │ Gemini │ Codex │ +├─────────────┼─────────────┼─────────────┤ +│ Core logic │ Google APIs │ Tests │ +│ Complex │ Docs │ Models │ +│ Integration │ Research │ Docstrings │ +└─────────────┴─────────────┴─────────────┘ +``` + +**Before modifying files:** +1. Set `SEO_AGENT_AUTHOR` environment variable +2. Check `.agent-state/locks.yaml` for active locks +3. Claim task in `.agent-state/tasks.yaml` + +### Phase 3: Review & Merge (Claude Lead) + +``` +Sub-agent work → Claude reviews + ↓ + Claude integrates + ↓ + Claude runs full test suite + ↓ + Claude commits with attribution +``` + +--- + +## 4. Code Style Guidelines + +### 4.1 Python Conventions + +| Rule | Standard | +|------|----------| +| Line length | 100 characters | +| Formatter | Black | +| Import sorter | isort (Black profile) | +| Linter | flake8 | +| Type checker | mypy | +| Docstrings | Google-style | + +### 4.2 Import Organization + +```python +# Standard library +import asyncio +import logging +from typing import Dict, List, Optional + +# Third-party +import aiohttp +from pydantic import BaseModel + +# Local +from mypackage.models import MyModel +from mypackage.utils import helper_function +``` + +### 4.3 Error Handling Pattern + +```python +try: + result = await some_operation(arg) +except SpecificError as e: + logger.warning(f"Specific error: {e}") + return None +except GeneralError: + logger.exception("Unexpected error") + raise +``` + +--- + +## 5. Commit & PR Standards + +### 5.1 Commit Message Format + +``` +[Agent] type(scope): description + +Body explaining the change (optional) + +Co-Authored-By: Claude +``` + +**Types:** `feat`, `fix`, `docs`, `test`, `refactor`, `chore` + +**Agent tags:** `[Claude]`, `[Gemini]`, `[Codex]`, `[Human]`, `[CI]` + +### 5.2 Examples + +```bash +[Claude] feat(core): implement new feature +[Gemini] docs(api): add API documentation +[Codex] test(models): add unit tests for models +[Human] fix(config): update configuration +``` + +### 5.3 PR Checklist + +```markdown +## Pre-Merge Checklist + +- [ ] Tests pass +- [ ] Code quality passes (formatter, linter, type checker) +- [ ] No hardcoded secrets +- [ ] Error handling implemented +- [ ] Logging added for debugging +- [ ] Documentation updated +- [ ] Agent attribution in commit messages +``` + +--- + +## 6. Quality Assurance + +### 6.1 Review Matrix + +| Review Type | Reviewer | Focus | +|-------------|----------|-------| +| Architecture | Claude | Design patterns, scalability | +| Logic correctness | Claude | Edge cases, error handling | +| Google API usage | Gemini | Best practices, quotas | +| Code style | Linter | Consistency | +| Documentation | Gemini | Clarity, completeness | +| Test coverage | Claude + Codex | Coverage, edge cases | + +### 6.2 Testing Standards + +```bash +# Minimum requirements before merge +pytest --cov=src --cov-fail-under=70 + +# For critical modules +pytest --cov=src/critical_module --cov-fail-under=80 +``` + +--- + +## 7. Quick Reference Commands + +```bash +# Quality checks +black src tests && isort src tests && flake8 src tests && mypy src tests + +# Testing +pytest # All tests +pytest tests/test_file.py -v # Single file +pytest -k "pattern" -v # Pattern match +pytest --cov=src --cov-report=html # Coverage report +``` + +--- + +## 8. References + +### Internal Documents + +| Document | Purpose | +|----------|---------| +| [`GUARDRAILS.md`](./GUARDRAILS.md) | Ownership, locks, conflict resolution | +| [`CLAUDE.md`](./CLAUDE.md) | Lead agent directive | +| [`GEMINI.md`](./GEMINI.md) | Gemini sub-agent directive | +| [`CODEX.md`](./CODEX.md) | Codex sub-agent directive | + +--- + +*This document is the shared source of truth for all AI agents. Claude Code maintains and updates this file.* + +*Last updated: [DATE]* diff --git a/custom-skills/91-multi-agent-guide/templates/claude-md.md b/custom-skills/91-multi-agent-guide/templates/claude-md.md new file mode 100644 index 0000000..65a41d7 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/claude-md.md @@ -0,0 +1,141 @@ +# CLAUDE.md - Project Lead & Orchestrator + +This file defines Claude Code's role as the **Lead AI Agent** for this project. + +## Role: Project Manager & Architect + +Claude Code serves as the primary orchestrator for this repository, responsible for: + +| Domain | Responsibilities | +|--------|------------------| +| **Architecture** | System design, module structure, data flow decisions | +| **Orchestration** | Task delegation to sub-agents, workflow coordination | +| **Core Logic** | Complex algorithms, business logic, error handling | +| **Version Control** | Git management, branching strategy, PR reviews, commit standards | +| **Quality Gate** | Code review authority, merge decisions, release management | +| **Integration** | MCP server configuration, external API orchestration | + +## Sub-Agent Hierarchy + +``` + ┌─────────────────┐ + │ Claude Code │ + │ (Lead Agent) │ + └────────┬────────┘ + │ + ┌──────────────┼──────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │ Gemini │ │ Codex │ │ Human │ + │(Research)│ │ (Speed) │ │ (Review) │ + └──────────┘ └──────────┘ └──────────┘ +``` + +- **Gemini**: Google APIs, documentation, research tasks +- **Codex**: Boilerplate, tests, docstrings, repetitive patterns +- **Human**: Final approval, business decisions, priority setting + +## Project Overview + + + +| Aspect | Details | +|--------|---------| +| Status | [Development/Beta/Production] | +| Language | [Python/TypeScript/etc.] | +| CLI | [Your CLI command] | +| Source | [Main source directory] | + +## Quick Commands + +```bash +# Install +pip install -e ".[dev]" + +# Run +[your-cli] --help + +# Test & Quality +pytest --cov=src --cov-report=term-missing +black src tests && isort src tests && flake8 src tests +``` + +## Architecture Overview + +### Core Modules + + + +| Module | Purpose | Complexity | +|--------|---------|------------| +| `cli.py` | CLI entry point | High | +| `core.py` | Core business logic | High | +| `models.py` | Data models | Low | +| `utils.py` | Helper functions | Low | + +## Orchestration Patterns + +### When to Delegate + +| Task Type | Delegate To | Example | +|-----------|-------------|---------| +| Google API implementation | Gemini | OAuth, API clients | +| Documentation writing | Gemini | User guides, API docs | +| Unit test generation | Codex | pytest cases | +| Boilerplate models | Codex | Pydantic schemas | +| Complex refactoring | Keep (Claude) | Multi-file restructuring | +| Architecture decisions | Keep (Claude) | New module design | + +### Handoff Protocol + +See `AGENTS.md` for detailed handoff procedures between agents. + +## Git Management + +### Branching Strategy + +``` +main ─────────────────────────────────────────▶ + │ + └── feature/xxx ──── PR ──── merge ─────────▶ + │ + └── fix/xxx ──────── PR ──── merge ─────────▶ +``` + +### Commit Convention + +``` +[Agent] type(scope): description + +[Claude] feat(core): add new feature +[Gemini] docs(api): update API documentation +[Codex] test(models): add model tests +[Human] fix(config): correct configuration +``` + +### PR Requirements + +- [ ] Tests pass +- [ ] Code quality passes (formatter, linter, type checker) +- [ ] Documentation updated if needed +- [ ] Sub-agent contributions attributed in commit messages + +## Code Standards + +- **Line length:** 100 chars +- **Formatter:** Black + isort (Python) / Prettier (JS) +- **Type hints:** Required for all signatures +- **Docstrings:** Google-style + +## Related Documentation + +| File | Purpose | +|------|---------| +| `AGENTS.md` | Common ground rules, handoff protocols | +| `GUARDRAILS.md` | Ownership, locks, conflict resolution | +| `GEMINI.md` | Gemini sub-agent directive | +| `CODEX.md` | Codex sub-agent directive | + +--- + +*Claude Code is the authoritative source for architectural decisions in this repository.* diff --git a/custom-skills/91-multi-agent-guide/templates/codex-md.md b/custom-skills/91-multi-agent-guide/templates/codex-md.md new file mode 100644 index 0000000..296f780 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/codex-md.md @@ -0,0 +1,215 @@ +# CODEX.md - Testing & Boilerplate Sub-Agent + +This file defines Codex's role as a **Sub-Agent** specializing in testing, models, and repetitive patterns. + +## Role: Testing & Boilerplate Specialist + +Codex serves as a specialized agent for: + +| Domain | Responsibilities | +|--------|------------------| +| **Testing** | Unit tests, integration tests, test fixtures | +| **Models** | Pydantic models, dataclasses, type definitions | +| **Docstrings** | Google-style documentation for functions | +| **Boilerplate** | Repetitive patterns, similar class implementations | + +## Hierarchy Position + +``` + ┌─────────────────┐ + │ Claude Code │ ← Lead Agent + │ (Orchestrator) │ + └────────┬────────┘ + │ + ┌────────────┼────────────┐ + ▼ ▼ ▼ +┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Gemini │ │ Codex │ │ Human │ +│ │ │ (YOU) │ │ │ +└──────────┘ └──────────┘ └──────────┘ +``` + +## Primary Ownership + +| Pattern | Description | +|---------|-------------| +| `CODEX.md` | This directive file | +| `tests/` | All test files | +| `src/*/models.py` | Data models | +| `src/*/utils/` | Utility functions | + +## Workflow + +### Receiving Tasks from Claude + +Claude will delegate tasks using this format: + +```markdown +## Task for Codex + +**Type:** [Tests | Models | Docstrings | Boilerplate] + +### Pattern to Follow +```python +# Claude provides the first example +class ExampleClass(BaseClass): + def method(self, arg: str) -> Result: + ... +``` + +### Generate +- [ ] SimilarClass1 (same pattern) +- [ ] SimilarClass2 (same pattern) +- [ ] Tests for all classes +``` + +### Completing Tasks + +1. **Claim task** in `.agent-state/tasks.yaml` +2. **Acquire locks** for files you'll modify +3. **Generate** following Claude's pattern +4. **Test** your implementation +5. **Return to Claude** for review + +### Escalation to Claude + +Escalate back to Claude when: +- Logic beyond simple patterns +- Complex mocking or fixtures needed +- Unclear requirements + +```markdown +## Escalation to Claude + +**Reason:** [Complexity | Unclear | Dependencies] + +### Completed Work +[What you finished] + +### Question +[What you need clarification on] +``` + +## Code Standards + +Follow these standards: + +| Standard | Value | +|----------|-------| +| Line length | 100 characters | +| Formatter | Black (Python) | +| Test framework | pytest | +| Type hints | Required | + +### Example Test Style + +```python +import pytest +from mypackage.models import MyModel + + +class TestMyModel: + """Tests for MyModel class.""" + + @pytest.fixture + def sample_data(self) -> dict: + """Provide sample data for tests.""" + return { + "name": "test", + "value": 42, + } + + def test_creation(self, sample_data: dict) -> None: + """Test model creation with valid data.""" + model = MyModel(**sample_data) + assert model.name == "test" + assert model.value == 42 + + def test_validation_error(self) -> None: + """Test model raises error on invalid data.""" + with pytest.raises(ValueError): + MyModel(name="", value=-1) + + @pytest.mark.parametrize( + "value,expected", + [ + (0, True), + (100, True), + (-1, False), + ], + ) + def test_is_valid(self, value: int, expected: bool) -> None: + """Test is_valid method with various inputs.""" + model = MyModel(name="test", value=value) + assert model.is_valid() == expected +``` + +### Example Model Style + +```python +from typing import Optional +from pydantic import BaseModel, Field, validator + + +class MyModel(BaseModel): + """ + Represents a data entity. + + Attributes: + name: The entity name + value: The numeric value + description: Optional description + """ + + name: str = Field(..., min_length=1, description="Entity name") + value: int = Field(..., ge=0, description="Numeric value") + description: Optional[str] = Field(None, description="Optional description") + + @validator("name") + def validate_name(cls, v: str) -> str: + """Ensure name is properly formatted.""" + return v.strip() + + def is_valid(self) -> bool: + """Check if the model data is valid.""" + return self.value >= 0 +``` + +## Commit Format + +Always use this commit format: + +``` +[Codex] type(scope): description + +Examples: +[Codex] test(models): add unit tests for MyModel +[Codex] feat(models): add NewModel with validation +[Codex] refactor(utils): add type hints to helpers +``` + +## Before Starting Work + +1. Set environment variable: + ```bash + export SEO_AGENT_AUTHOR=codex + ``` + +2. Check for existing locks: + ```bash + python tools/check-ownership.py --list-expired + ``` + +3. Claim your task in `.agent-state/tasks.yaml` + +## References + +| Document | Purpose | +|----------|---------| +| `AGENTS.md` | Collaboration rules | +| `GUARDRAILS.md` | Ownership matrix | +| `CLAUDE.md` | Lead agent directive | + +--- + +*Codex operates under Claude Code's orchestration. Always follow the provided patterns exactly.* diff --git a/custom-skills/91-multi-agent-guide/templates/gemini-md.md b/custom-skills/91-multi-agent-guide/templates/gemini-md.md new file mode 100644 index 0000000..cf6b149 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/gemini-md.md @@ -0,0 +1,165 @@ +# GEMINI.md - Research & Documentation Sub-Agent + +This file defines Gemini's role as a **Sub-Agent** specializing in documentation, Google APIs, and research. + +## Role: Research & Documentation Specialist + +Gemini serves as a specialized agent for: + +| Domain | Responsibilities | +|--------|------------------| +| **Google APIs** | GSC, GA4, PageSpeed, OAuth implementation | +| **Documentation** | User guides, API docs, tutorials | +| **Research** | Best practices, algorithm updates, industry trends | +| **Content** | Technical writing, explanations | + +## Hierarchy Position + +``` + ┌─────────────────┐ + │ Claude Code │ ← Lead Agent + │ (Orchestrator) │ + └────────┬────────┘ + │ + ┌────────────┼────────────┐ + ▼ ▼ ▼ +┌──────────┐ ┌──────────┐ ┌──────────┐ +│ Gemini │ │ Codex │ │ Human │ +│ (YOU) │ │ │ │ │ +└──────────┘ └──────────┘ └──────────┘ +``` + +## Primary Ownership + +| Pattern | Description | +|---------|-------------| +| `GEMINI.md` | This directive file | +| `src/*/integrations/google/` | Google API integrations | +| `src/*/integrations/gsc.py` | Google Search Console | +| `src/*/integrations/ga*.py` | Google Analytics | +| `docs/*.md` | Documentation files | + +## Workflow + +### Receiving Tasks from Claude + +Claude will delegate tasks using this format: + +```markdown +## Task for Gemini + +**Type:** [Google API | Documentation | Research] +**Priority:** [High | Medium | Low] + +### Objective +[What needs to be done] + +### Deliverables +- [ ] Item 1 +- [ ] Item 2 +``` + +### Completing Tasks + +1. **Claim task** in `.agent-state/tasks.yaml` +2. **Acquire locks** for files you'll modify +3. **Implement** following Claude's specifications +4. **Test** your implementation +5. **Return to Claude** with completion report + +### Escalation to Claude + +Escalate back to Claude when: +- Complex error handling needed +- Multi-file integration required +- Architectural decisions needed + +```markdown +## Escalation to Claude + +**Reason:** [Complexity | Architecture | Integration] + +### Completed Work +[What you finished] + +### Blocking Issue +[What requires Claude's decision] +``` + +## Code Standards + +Follow these standards when writing code: + +| Standard | Value | +|----------|-------| +| Line length | 100 characters | +| Formatter | Black (Python) | +| Type hints | Required | +| Docstrings | Google-style | + +### Example Code Style + +```python +async def get_search_analytics( + self, + site_url: str, + start_date: str, + end_date: str, + dimensions: Optional[List[str]] = None, +) -> SearchAnalyticsResponse: + """ + Fetch search analytics data from Google Search Console. + + Args: + site_url: The site URL to query + start_date: Start date in YYYY-MM-DD format + end_date: End date in YYYY-MM-DD format + dimensions: Optional list of dimensions + + Returns: + SearchAnalyticsResponse containing the analytics data + + Raises: + GSCError: If the API request fails + """ + ... +``` + +## Commit Format + +Always use this commit format: + +``` +[Gemini] type(scope): description + +Examples: +[Gemini] feat(gsc): implement search analytics endpoint +[Gemini] docs(api): add GSC integration guide +[Gemini] fix(oauth): correct token refresh logic +``` + +## Before Starting Work + +1. Set environment variable: + ```bash + export SEO_AGENT_AUTHOR=gemini + ``` + +2. Check for existing locks: + ```bash + python tools/check-ownership.py --list-expired + ``` + +3. Claim your task in `.agent-state/tasks.yaml` + +## References + +| Document | Purpose | +|----------|---------| +| `AGENTS.md` | Collaboration rules | +| `GUARDRAILS.md` | Ownership matrix | +| `CLAUDE.md` | Lead agent directive | + +--- + +*Gemini operates under Claude Code's orchestration. Always coordinate major changes with Claude.* diff --git a/custom-skills/91-multi-agent-guide/templates/github-workflow.yaml b/custom-skills/91-multi-agent-guide/templates/github-workflow.yaml new file mode 100644 index 0000000..d23be3b --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/github-workflow.yaml @@ -0,0 +1,161 @@ +# GitHub Actions Workflow: Ownership Check +# Save as: .github/workflows/ownership-check.yml +# +# This workflow verifies file ownership rules on pull requests. + +name: Ownership Check + +on: + pull_request: + branches: [main, develop] + types: [opened, synchronize, reopened] + +jobs: + check-ownership: + name: Verify File Ownership + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 0 # Full history for accurate diff + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.11" + + - name: Install dependencies + run: pip install pyyaml + + - name: Get changed files + id: changed-files + uses: tj-actions/changed-files@v44 + + - name: Check ownership + id: ownership-check + env: + SEO_AGENT_AUTHOR: ci + run: | + echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}" + + # Run ownership check + python tools/check-ownership.py ${{ steps.changed-files.outputs.all_changed_files }} > ownership_result.txt 2>&1 || true + + # Capture exit code + python tools/check-ownership.py ${{ steps.changed-files.outputs.all_changed_files }} + echo "exit_code=$?" >> $GITHUB_OUTPUT + + # Show results + cat ownership_result.txt + + - name: Check commit messages + run: | + # Get commits in PR + commits=$(git log origin/${{ github.base_ref }}..HEAD --format="%H") + + for commit in $commits; do + msg=$(git log -1 --format="%s" $commit) + echo "Checking commit: $msg" + + # Check format: [Agent] type(scope): description + if ! echo "$msg" | grep -qE "^\[(Claude|Gemini|Codex|Human|CI)\] \w+(\([^)]+\))?: .+"; then + echo "::error::Invalid commit message format: $msg" + echo "Expected format: [Agent] type(scope): description" + exit 1 + fi + done + + echo "All commit messages are valid." + + - name: Comment on PR (violations) + if: failure() + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + let result = ''; + try { + result = fs.readFileSync('ownership_result.txt', 'utf8'); + } catch (e) { + result = 'Unable to read ownership check results.'; + } + + const body = `## Ownership Check Failed + + The following ownership violations were detected: + + \`\`\` + ${result} + \`\`\` + + Please ensure: + 1. You are modifying files in your agent's ownership domain + 2. Shared files have Claude's approval + 3. Commit messages follow the format: \`[Agent] type(scope): description\` + + See \`GUARDRAILS.md\` for ownership rules. + `; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: body + }); + + - name: Comment on PR (success) + if: success() + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: '✅ **Ownership Check Passed**\n\nAll file ownership rules and commit message formats are valid.' + }); + + validate-state-files: + name: Validate Agent State Files + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: "3.11" + + - name: Validate YAML files + run: | + python -c " + import yaml + import sys + + files = ['.agent-state/tasks.yaml', '.agent-state/locks.yaml'] + errors = [] + + for f in files: + try: + with open(f, 'r') as file: + data = yaml.safe_load(file) + if data is None: + errors.append(f'{f}: File is empty') + elif 'version' not in data: + print(f'Warning: {f} missing version field') + except FileNotFoundError: + print(f'Warning: {f} not found') + except yaml.YAMLError as e: + errors.append(f'{f}: Invalid YAML - {e}') + + if errors: + for e in errors: + print(f'Error: {e}') + sys.exit(1) + + print('All state files are valid.') + " diff --git a/custom-skills/91-multi-agent-guide/templates/guardrails-md.md b/custom-skills/91-multi-agent-guide/templates/guardrails-md.md new file mode 100644 index 0000000..d537cb6 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/guardrails-md.md @@ -0,0 +1,355 @@ +# GUARDRAILS.md - Ownership & Enforcement Rules + +This document defines the ownership matrix, lock system, and enforcement mechanisms for multi-agent collaboration in this repository. + +> **Collaboration Rules**: See [`AGENTS.md`](./AGENTS.md) for handoff protocols and code standards. + +--- + +## 1. Ownership Matrix + +### 1.1 Ownership Categories + +| Category | Description | Override | +|----------|-------------|----------| +| **Primary** | Agent has exclusive authority | Claude can override | +| **Shared** | Multiple agents can modify, requires coordination | Claude approves changes | +| **Unrestricted** | Any agent can modify | No restrictions | + +### 1.2 Claude Code - Primary Ownership + +Claude Code is the lead agent with primary ownership of: + +| Pattern | Description | +|---------|-------------| +| `CLAUDE.md` | Lead agent directive | +| `AGENTS.md` | Shared collaboration rules | +| `GUARDRAILS.md` | This file | +| `src/*/cli.py` | CLI entry points | +| `src/*/core/` | Core logic modules | +| `src/*/main.py` | Main entry points | + +### 1.3 Gemini - Primary Ownership + +Gemini has primary ownership of: + +| Pattern | Description | +|---------|-------------| +| `GEMINI.md` | Gemini directive | +| `src/*/integrations/google/` | Google API integrations | +| `src/*/integrations/gsc.py` | Google Search Console | +| `src/*/integrations/ga*.py` | Google Analytics | +| `docs/` | Documentation (markdown) | + +### 1.4 Codex - Primary Ownership + +Codex has primary ownership of: + +| Pattern | Description | +|---------|-------------| +| `CODEX.md` | Codex directive | +| `src/*/models.py` | Pydantic/data models | +| `src/*/utils/` | Utility functions | +| `tests/` | All test files | + +### 1.5 Shared Files + +These files require coordination (Claude approves): + +| Pattern | Coordination Rule | +|---------|-------------------| +| `pyproject.toml` | Dependency changes require discussion | +| `config/*.yaml` | Configuration changes affect all agents | +| `.github/workflows/` | CI/CD changes impact everyone | +| `PROJECT_PLAN.md` | Roadmap changes need consensus | + +### 1.6 Unrestricted Files + +Any agent can modify these files: + +| Pattern | Notes | +|---------|-------| +| `.agent-state/` | Task and lock management | +| `.gitignore` | Git configuration | +| `README.md` | Project readme | +| `.pre-commit-config.yaml` | Pre-commit hooks | + +--- + +## 2. Lock System + +### 2.1 Lock Types + +| Type | Description | Use Case | +|------|-------------|----------| +| `exclusive` | Single agent can modify | Long-running refactors | +| `shared` | Multiple can read, one writes | Concurrent development | +| `override` | Claude override for conflicts | Emergency fixes | + +### 2.2 Lock File Format + +Location: `.agent-state/locks.yaml` + +```yaml +version: "1.0" +updated_at: "2025-01-29T12:00:00Z" + +locks: + - path: "src/module/" + agent: "claude" + lock_type: "exclusive" + task_id: "TASK-001" + reason: "Refactoring core module" + created_at: "2025-01-29T10:00:00Z" + expires_at: "2025-01-29T14:00:00Z" + + - path: "docs/api/" + agent: "gemini" + lock_type: "shared" + task_id: "TASK-002" + reason: "Updating API documentation" + created_at: "2025-01-29T11:00:00Z" + expires_at: "2025-01-29T15:00:00Z" +``` + +### 2.3 Lock Operations + +**Acquire Lock:** +1. Check if path is already locked +2. If locked by another agent, wait or request release +3. Add lock entry to locks.yaml +4. Set expiration time (default: 4 hours) + +**Release Lock:** +1. Remove lock entry from locks.yaml +2. Update `updated_at` timestamp +3. Notify other agents if requested + +**Lock Expiration:** +- Locks automatically expire at `expires_at` time +- Expired locks can be claimed by any agent +- Run `python tools/check-ownership.py --list-expired` to see expired locks + +--- + +## 3. Task Claiming Protocol + +### 3.1 Task File Format + +Location: `.agent-state/tasks.yaml` + +```yaml +version: "1.0" +updated_at: "2025-01-29T12:00:00Z" + +tasks: + - id: "TASK-001" + description: "Implement new feature" + agent: "claude" + status: "in_progress" + priority: "high" + files: + - "src/feature.py" + - "tests/test_feature.py" + created_at: "2025-01-29T09:00:00Z" + claimed_at: "2025-01-29T09:30:00Z" + expires_at: "2025-01-29T13:30:00Z" + + - id: "TASK-002" + description: "Write API documentation" + agent: "gemini" + status: "pending" + priority: "medium" + files: + - "docs/api.md" + created_at: "2025-01-29T10:00:00Z" +``` + +### 3.2 Task Status Flow + +``` +pending → in_progress → completed + ↓ + abandoned (if expired) + ↓ + blocked (if dependency) +``` + +### 3.3 Claiming Process + +1. **Check availability**: Verify task is `pending` +2. **Set identity**: Ensure `SEO_AGENT_AUTHOR` is set +3. **Claim task**: Update tasks.yaml with your agent name +4. **Acquire locks**: Lock files you'll modify +5. **Begin work**: Start implementation +6. **Complete task**: Mark as `completed`, release locks + +### 3.4 Task Expiration + +- Default timeout: 4 hours from `claimed_at` +- Expired tasks revert to `pending` +- Other agents can reclaim expired tasks + +--- + +## 4. Environment Configuration + +### 4.1 Required Environment Variable + +```bash +# Set in shell profile or .envrc +export SEO_AGENT_AUTHOR= + +# Valid values: +# - claude +# - gemini +# - codex +# - human +``` + +### 4.2 Verification + +```bash +# Check current agent identity +echo $SEO_AGENT_AUTHOR + +# Verify setup +python tools/check-ownership.py --verify-setup +``` + +--- + +## 5. Conflict Resolution + +### 5.1 Resolution Hierarchy + +| Conflict Type | Resolution | +|---------------|------------| +| Ownership dispute | Claude decides | +| Lock conflict | First to lock wins; Claude can override | +| Task overlap | Split tasks or assign to single agent | +| Merge conflict | Claude resolves | + +### 5.2 Escalation Process + +1. **Identify conflict**: Agent detects violation +2. **Document issue**: Add to escalation log +3. **Notify Claude**: Include conflict details +4. **Claude decides**: Makes binding decision +5. **Update rules**: Modify GUARDRAILS.md if pattern emerges + +### 5.3 Claude Override + +Claude can override any lock or ownership rule: + +```yaml +# In locks.yaml +- path: "src/critical/" + agent: "claude" + lock_type: "override" + task_id: "EMERGENCY-001" + reason: "Critical bug fix" + override_agent: "gemini" # Agent whose lock was overridden +``` + +--- + +## 6. Verification Tools + +### 6.1 check-ownership.py Commands + +```bash +# Verify files before commit +python tools/check-ownership.py path/to/file.py + +# Check commit message format +python tools/check-ownership.py --check-commit-msg + +# Verify setup +python tools/check-ownership.py --verify-setup + +# List expired locks/tasks +python tools/check-ownership.py --list-expired + +# Validate state files +python tools/check-ownership.py --validate-state + +# Strict mode (warnings as errors) +python tools/check-ownership.py --strict path/to/file.py +``` + +### 6.2 Pre-commit Integration + +The following hooks run automatically: + +| Hook | Stage | Purpose | +|------|-------|---------| +| `check-ownership` | commit | Verify file ownership | +| `check-commit-message` | commit-msg | Validate message format | + +--- + +## 7. CI/CD Integration + +### 7.1 GitHub Actions + +Ownership checks run on PRs: + +```yaml +# .github/workflows/ownership-check.yml +- Check changed files against ownership matrix +- Post violations as PR comments +- Block merge on violations +``` + +### 7.2 PR Labels + +| Label | Meaning | +|-------|---------| +| `ownership-verified` | All files verified | +| `ownership-override` | Claude approved override | +| `ownership-violation` | Needs resolution | + +--- + +## 8. Quick Reference + +### Commands + +```bash +# Set identity +export SEO_AGENT_AUTHOR=claude + +# Check ownership +python tools/check-ownership.py src/file.py + +# List expired +python tools/check-ownership.py --list-expired + +# Validate state +python tools/check-ownership.py --validate-state +``` + +### Commit Format + +``` +[Agent] type(scope): description + +[Claude] feat(core): implement new feature +[Gemini] docs(api): update API documentation +[Codex] test(models): add model tests +``` + +### File Locations + +| File | Purpose | +|------|---------| +| `.agent-state/tasks.yaml` | Task registry | +| `.agent-state/locks.yaml` | Lock registry | +| `tools/check-ownership.py` | Verification script | + +--- + +*This document defines the enforcement rules for multi-agent collaboration. Claude Code is the authoritative source for conflict resolution.* + +*Last updated: [DATE]* diff --git a/custom-skills/91-multi-agent-guide/templates/locks-yaml.yaml b/custom-skills/91-multi-agent-guide/templates/locks-yaml.yaml new file mode 100644 index 0000000..7121a5c --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/locks-yaml.yaml @@ -0,0 +1,42 @@ +# Agent File Locks Registry +# Location: .agent-state/locks.yaml +# +# This file tracks file/directory locks held by agents. +# Agents must acquire locks before modifying files. + +version: "1.0" +updated_at: "2025-01-29T00:00:00Z" + +# Lock Types: +# - exclusive: Only one agent can modify (blocks all others) +# - shared: Multiple can read, one can write +# - override: Claude override for conflict resolution + +locks: [] + +# Example lock entry: +# +# locks: +# - path: "src/core/" +# agent: "claude" +# lock_type: "exclusive" +# task_id: "TASK-001" +# reason: "Refactoring core module" +# created_at: "2025-01-29T10:00:00Z" +# expires_at: "2025-01-29T14:00:00Z" +# +# - path: "docs/api/" +# agent: "gemini" +# lock_type: "shared" +# task_id: "TASK-002" +# reason: "Updating API documentation" +# created_at: "2025-01-29T11:00:00Z" +# expires_at: "2025-01-29T15:00:00Z" +# +# - path: "tests/" +# agent: "codex" +# lock_type: "exclusive" +# task_id: "TASK-003" +# reason: "Adding comprehensive tests" +# created_at: "2025-01-29T12:00:00Z" +# expires_at: "2025-01-29T16:00:00Z" diff --git a/custom-skills/91-multi-agent-guide/templates/pre-commit-config.yaml b/custom-skills/91-multi-agent-guide/templates/pre-commit-config.yaml new file mode 100644 index 0000000..40cd275 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/pre-commit-config.yaml @@ -0,0 +1,90 @@ +# Pre-commit Configuration for Multi-Agent Projects +# Save as: .pre-commit-config.yaml (update existing or create new) +# +# Install: pre-commit install +# Run all: pre-commit run --all-files + +repos: + # Standard pre-commit hooks + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + exclude: ^\.agent-state/ + - id: end-of-file-fixer + exclude: ^\.agent-state/ + - id: check-yaml + args: [--unsafe] # Allow custom tags in YAML + - id: check-json + - id: check-toml + - id: check-merge-conflict + - id: check-added-large-files + args: ['--maxkb=500'] + - id: detect-private-key + - id: no-commit-to-branch + args: ['--branch', 'main'] + + # Python code formatting (if using Python) + - repo: https://github.com/psf/black + rev: 24.1.1 + hooks: + - id: black + args: ['--line-length=100'] + language_version: python3 + + # Import sorting (if using Python) + - repo: https://github.com/pycqa/isort + rev: 5.13.2 + hooks: + - id: isort + args: ['--profile=black', '--line-length=100'] + + # Linting (if using Python) + - repo: https://github.com/pycqa/flake8 + rev: 7.0.0 + hooks: + - id: flake8 + args: ['--max-line-length=100', '--extend-ignore=E203,W503'] + + # Custom multi-agent hooks + - repo: local + hooks: + # Ownership verification hook + - id: check-ownership + name: Check Agent Ownership + description: Verify file ownership and locks for multi-agent workflow + entry: python tools/check-ownership.py + language: python + always_run: true + pass_filenames: true + additional_dependencies: + - pyyaml + # Only runs when SEO_AGENT_AUTHOR is set + # If not set, hook will warn but not block + + # Commit message format hook + - id: check-commit-message + name: Check Commit Message Format + description: Verify commit message follows [Agent] type(scope) format + entry: python tools/check-ownership.py --check-commit-msg + language: python + stages: [commit-msg] + additional_dependencies: + - pyyaml + +# CI Configuration +# These settings are used when running in CI environment +ci: + autofix_commit_msg: | + [CI] auto fixes from pre-commit hooks + + for more information, see https://pre-commit.ci + autofix_prs: true + autoupdate_branch: '' + autoupdate_commit_msg: '[CI] pre-commit autoupdate' + autoupdate_schedule: weekly + skip: [check-ownership, check-commit-message] # Skip custom hooks in CI + submodules: false + +# Default stages - hooks run at these stages unless otherwise specified +default_stages: [commit] diff --git a/custom-skills/91-multi-agent-guide/templates/tasks-yaml.yaml b/custom-skills/91-multi-agent-guide/templates/tasks-yaml.yaml new file mode 100644 index 0000000..1a71887 --- /dev/null +++ b/custom-skills/91-multi-agent-guide/templates/tasks-yaml.yaml @@ -0,0 +1,48 @@ +# Agent Tasks Registry +# Location: .agent-state/tasks.yaml +# +# This file tracks all tasks claimed by agents. +# Agents must claim tasks before modifying associated files. + +version: "1.0" +updated_at: "2025-01-29T00:00:00Z" + +# Task Status Values: +# - pending: Available for claiming +# - in_progress: Currently being worked on +# - completed: Work finished successfully +# - abandoned: Work stopped, task available for reclaiming +# - blocked: Waiting on dependencies + +tasks: [] + +# Example task entry: +# +# tasks: +# - id: "TASK-001" +# description: "Implement new feature" +# agent: "claude" +# status: "in_progress" +# priority: "high" +# files: +# - "src/feature.py" +# - "tests/test_feature.py" +# depends_on: [] +# created_at: "2025-01-29T09:00:00Z" +# claimed_at: "2025-01-29T09:30:00Z" +# expires_at: "2025-01-29T13:30:00Z" +# completed_at: null +# +# - id: "TASK-002" +# description: "Write API documentation" +# agent: null +# status: "pending" +# priority: "medium" +# files: +# - "docs/api.md" +# depends_on: +# - "TASK-001" +# created_at: "2025-01-29T10:00:00Z" +# claimed_at: null +# expires_at: null +# completed_at: null diff --git a/settings-audit-report.md b/settings-audit-report.md index 7925a07..dfd2cf0 100644 --- a/settings-audit-report.md +++ b/settings-audit-report.md @@ -1,112 +1,212 @@ # Claude Code Settings Audit Report - -**Generated:** 2026-01-20 17:49:51 +**Generated:** 2026-01-29 +**Project:** our-claude-skills --- ## Token Budget Summary -| Component | Tokens | % of 200K | Status | -|-----------|--------|-----------|--------| -| CLAUDE.md | 1,738 | 0.9% | 🟢 | -| MCP Servers | 61,500 | 30.8% | 🟡 | -| **Baseline Total** | **63,238** | **31.6%** | 🔴 | -| **Available for Work** | **136,762** | **68.4%** | — | +| Component | Lines | Est. Tokens | % of 200K | Status | +|-----------|-------|-------------|-----------|--------| +| Global CLAUDE.md | 118 | ~1,200 | 0.6% | ✅ OK | +| Project CLAUDE.md | 232 | ~2,500 | 1.3% | ⚠️ WARN | +| MCP Servers (11) | — | ~1,000 | 0.5% | ✅ OK | +| Commands (7) | 716 | ~1,800 | 0.9% | ✅ OK | +| Skills (1 loaded) | 480 | ~3,000 | 1.5% | ✅ OK | +| Agents (5) | 195 | ~500 | 0.3% | ✅ OK | +| **Baseline Total** | — | **~10,000** | **5%** | — | +| **Available for Work** | — | **~190,000** | **95%** | ✅ OK | -**Target:** Baseline under 30% (60,000 tokens), Available over 70% +**Assessment:** Excellent token efficiency. ~95% of context available for conversation. --- -## Overall Health: 🔴 Critical +## Overall Health: 🟢 Good -- Critical Issues: 1 -- Warnings: 13 -- Passing Checks: 56 +- Critical Issues: 0 +- Warnings: 2 +- Passing Checks: 24 --- ## MCP Server Analysis -**Servers:** 10 configured +### Server Configuration Summary +| Server | serverInstructions | Load Strategy | Status | +|--------|-------------------|---------------|--------| +| filesystem | ✅ Custom | always | ✅ OK | +| sqlite | ✅ Custom | always | ✅ OK | +| playwright | ✅ Custom | always | ✅ OK | +| firecrawl | ✅ Custom | always | ✅ OK | +| google-analytics | ⚠️ Generic | always | ⚠️ WARN | +| chrome-devtools | ✅ Custom | autoStart: false | ✅ OK | +| exa | ✅ Custom | always | ✅ OK | +| dtm-agent | ⚠️ Generic | always | ⚠️ WARN | +| slack | ✅ Custom | always | ✅ OK | +| n8n-instance | ✅ Custom | always | ✅ OK | -**Active:** 10 | **Disabled:** 0 +### Plugins Enabled (5) +- commit-commands@claude-plugins-official +- figma@claude-plugins-official +- frontend-design@claude-plugins-official +- Notion@claude-plugins-official +- playwright@claude-plugins-official -| Server | Tokens | Instructions | Status | -|--------|--------|--------------|--------| -| filesystem | ~4,000 | ✅ | always | -| sqlite | ~5,000 | ✅ | lazy | -| playwright | ~13,500 | ✅ | always | -| figma | ~5,000 | ✅ | lazy | -| osascript | ~5,000 | ✅ | lazy | -| firecrawl | ~6,000 | ✅ | lazy | -| google-analytics | ~5,000 | ✅ | lazy | -| chrome-devtools | ~8,000 | ✅ | always | -| exa | ~5,000 | ✅ | lazy | -| dtm-agent | ~5,000 | ✅ | lazy | +**Note:** Plugins use deferred tool loading via Tool Search, which is efficient. --- ## CLAUDE.md Analysis -- **/Users/ourdigital/.claude/CLAUDE.md**: 110 lines, ~800 tokens 🟢 -- **/Users/ourdigital/Project/claude-skills/CLAUDE.md**: 150 lines, ~938 tokens 🟢 +### Global CLAUDE.md (`~/.claude/CLAUDE.md`) +| Metric | Value | Target | Status | +|--------|-------|--------|--------| +| Lines | 118 | <200 | ✅ OK | +| Bytes | 4,652 | — | — | +| Est. Tokens | ~1,200 | <3,000 | ✅ OK | +| Structure | Good | — | ✅ OK | + +**Contents:** +- User profile & workspaces (3 Google accounts) +- n8n workflow automation config +- Pending setup notes (Gemini CLI) +- Notion database schema reference +- GTM debugging workflow directive + +### Project CLAUDE.md (`./CLAUDE.md`) +| Metric | Value | Target | Status | +|--------|-------|--------|--------| +| Lines | 232 | <200 | ⚠️ WARN | +| Bytes | 9,269 | — | — | +| Est. Tokens | ~2,500 | <3,000 | ✅ OK | +| Structure | Good | — | ✅ OK | + +**Contents:** +- Repository overview +- Custom skills summary (29 skills) +- Dual-platform skill structure +- Directory layout +- Creating new skills guide --- ## Extensions Analysis -- Commands: 18 -- Skills: 28 -- Agents: 5 +### Commands (7 files) +| Command | Lines | Frontmatter | Status | +|---------|-------|-------------|--------| +| settings-audit.md | 119 | ✅ Yes | ✅ OK | +| web-crawler.md | 79 | ✅ Yes | ✅ OK | +| reference-discovery.md | 72 | ✅ Yes | ✅ OK | +| content-repository.md | 94 | ✅ Yes | ✅ OK | +| content-distiller.md | 92 | ✅ Yes | ✅ OK | +| markdown-exporter.md | 138 | ✅ Yes | ✅ OK | +| quality-reviewer.md | 122 | ✅ Yes | ✅ OK | + +**All commands under 150 lines with proper YAML frontmatter.** + +### Skills (1 installed) +| Skill | SKILL.md Lines | Total Files Lines | Status | +|-------|----------------|-------------------|--------| +| jamie-brand-guardian | 480 | 4,141 | ✅ OK | + +**Note:** SKILL.md is 480 lines (under 500 limit). Total includes reference files (guides, templates, fact-sheets) which are only loaded on demand. + +### Agents (5 files) +| Agent | Lines | Tools Restricted | Status | +|-------|-------|------------------|--------| +| data-analyst.md | 39 | ✅ Yes | ✅ OK | +| seo-advisor.md | 28 | ✅ Yes | ✅ OK | +| python-coach.md | 36 | ✅ Yes | ✅ OK | +| gtm-manager.md | 53 | ✅ Yes | ✅ OK | +| data-engineer.md | 39 | ✅ Yes | ✅ OK | + +**All agents under 60 lines with appropriate tool restrictions.** --- ## ❌ Critical Issues -- Baseline uses 31.6% of context - target is under 30% +None found. --- ## ⚠️ Warnings -- Command 'settings-audit': Missing YAML frontmatter -- Command 'settings-audit': Too long: 120 lines (max 100) -- Skill 'jamie-youtube-manager': Too long: 526 lines (max 500) -- Agent 'data-analyst': Missing frontmatter -- Agent 'data-analyst': Tools not restricted (consider limiting) -- Agent 'seo-advisor': Missing frontmatter -- Agent 'seo-advisor': Tools not restricted (consider limiting) -- Agent 'python-coach': Missing frontmatter -- Agent 'python-coach': Tools not restricted (consider limiting) -- Agent 'gtm-manager': Missing frontmatter -- *...and 3 more* +### 1. Generic serverInstructions on 2 MCP servers +**Affected:** `google-analytics`, `dtm-agent` ---- +Both servers have placeholder instructions: +```json +"serverInstructions": "External tool: {server-name}. Use when this functionality is needed." +``` -## ✅ Passing +**Impact:** Tool Search may not route requests accurately to these servers. -- MCP 'filesystem': Has serverInstructions -- MCP 'sqlite': Has serverInstructions -- MCP 'playwright': Has serverInstructions -- MCP 'figma': Has serverInstructions -- MCP 'osascript': Has serverInstructions -- *...and 51 more* +### 2. Project CLAUDE.md exceeds 200 lines +**Current:** 232 lines | **Target:** <200 lines + +**Impact:** Minor token overhead (~500 extra tokens). --- ## Recommendations -1. **Fix:** Baseline uses 31.6% of context - target is under 30% +### Priority 1: Fix MCP serverInstructions + +**google-analytics:** +```json +"serverInstructions": "Google Analytics data retrieval. Use for: GA4 reports, traffic analysis, conversion data, audience insights. Keywords: analytics, GA4, traffic, sessions, users, conversions, pageviews" +``` + +**dtm-agent:** +```json +"serverInstructions": "GTM container management via API. Use for: tag configuration, trigger management, variable setup, container publishing. Keywords: GTM, tag, trigger, variable, container, workspace, version" +``` + +### Priority 2: Consider CLAUDE.md optimization +Move these sections to a separate `REFERENCE.md` or link: +- Detailed directory layout (lines 167-218) +- Full skill tables could link to the AUDIT_REPORT.md instead --- -## Next Steps +## Auto-Fix Available -1. Run `python3 scripts/auto_fix.py` to preview fixes -2. Run `python3 scripts/auto_fix.py --apply` to apply fixes -3. Re-run audit to verify improvements +Run `/settings-audit --fix` to apply: +1. ✅ Update `google-analytics` serverInstructions +2. ✅ Update `dtm-agent` serverInstructions --- -*Generated by Claude Code Settings Optimizer* +## Configuration Highlights + +### Environment Variables +```json +{ + "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000", + "MAX_THINKING_TOKENS": "31999" +} +``` + +### Settings +- `alwaysThinkingEnabled`: true ✅ + +--- + +## Summary + +| Category | Score | Notes | +|----------|-------|-------| +| Token Efficiency | 🟢 Excellent | 95% context available | +| MCP Configuration | 🟡 Good | 2 servers need better instructions | +| CLAUDE.md | 🟢 Good | Slightly over line target but well-structured | +| Extensions | 🟢 Excellent | All properly formatted | +| **Overall** | 🟢 **A-** | Minor improvements suggested | + +**Your Claude Code setup is well-optimized.** The 2 MCP server instruction warnings are minor and mainly affect Tool Search routing accuracy for those specific servers. + +--- + +*Generated by Claude Code Settings Audit Skill*