feat: Add installation tool, Claude.ai export, and skill standardization (#1)
## Summary - Add portable installation tool (`install.sh`) for cross-machine setup - Add Claude.ai export files with proper YAML frontmatter - Add multi-agent-guide v2.0 with consolidated framework template - Rename `00-claude-code-setting` → `00-our-settings-audit` (avoid reserved word) - Add YAML frontmatter to 25+ SKILL.md files for Claude Desktop compatibility ## Commits Included - `93f604a` feat: Add portable installation tool for cross-machine setup - `9b84104` feat: Add Claude.ai export for portable skill installation - `f7ab973` fix: Add YAML frontmatter to Claude.ai export files - `3fed49a` feat(multi-agent-guide): Add v2.0 with consolidated framework - `3be26ef` refactor: Rename settings-audit skill and add YAML frontmatter Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Yim
@@ -0,0 +1,256 @@
|
||||
# Multi-Agent Development Framework
|
||||
|
||||
**Version:** 1.0
|
||||
**Applies to:** {{PROJECT_NAME}}
|
||||
**Last Updated:** {{DATE}}
|
||||
|
||||
---
|
||||
|
||||
## 1. Agent Hierarchy
|
||||
|
||||
```
|
||||
Human (Final Authority)
|
||||
│
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ Claude Code │ ← Lead Agent
|
||||
│ Orchestrator│
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌─────────────────┼─────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Gemini │ │ Codex │ │ Human │
|
||||
│Research │ │ Speed │ │ Approve │
|
||||
└─────────┘ └─────────┘ └─────────┘
|
||||
```
|
||||
|
||||
| Agent | Role | Scope |
|
||||
|-------|------|-------|
|
||||
| **Claude** | Lead / Orchestrator | Architecture, core logic, integration, git, final review |
|
||||
| **Gemini** | Sub-agent | Google APIs, documentation, research, visualization |
|
||||
| **Codex** | Sub-agent | Tests, boilerplate, models, docstrings, utilities |
|
||||
| **Human** | Authority | Business decisions, priorities, release approval |
|
||||
|
||||
---
|
||||
|
||||
## 2. File Ownership
|
||||
|
||||
### 2.1 Standard Ownership Matrix
|
||||
|
||||
| Pattern | Owner | Examples |
|
||||
|---------|-------|----------|
|
||||
| `src/*/core/`, `src/*/services/` | Claude | Business logic, orchestration |
|
||||
| `src/*/api/`, `src/*/mcp/` | Claude | API clients, MCP servers |
|
||||
| `src/*/connectors/` | Claude | Data source integrations |
|
||||
| `src/*/visualization/`, `src/*/app/` | Gemini | Dashboards, charts |
|
||||
| `docs/*.md` | Gemini | User documentation |
|
||||
| `tests/` | Codex | All test files |
|
||||
| `src/*/utils/`, `src/*/models.py` | Codex | Utilities, Pydantic models |
|
||||
|
||||
### 2.2 Shared Files (Require Claude Approval)
|
||||
|
||||
| Files | Rule |
|
||||
|-------|------|
|
||||
| `pyproject.toml`, `requirements*.txt` | Claude approves dependency changes |
|
||||
| `.github/workflows/` | Claude approves CI/CD changes |
|
||||
| `CLAUDE.md`, `AGENTS.md`, `GUARDRAILS.md` | Claude only |
|
||||
| `PROJECT_PLAN.md` | Human approves roadmap changes |
|
||||
|
||||
### 2.3 Unrestricted Files
|
||||
|
||||
Any agent can modify: `.agent-state/*`, `.gitignore`, `README.md`
|
||||
|
||||
---
|
||||
|
||||
## 3. State Management
|
||||
|
||||
All state tracked in `.agent-state/` directory:
|
||||
|
||||
```
|
||||
.agent-state/
|
||||
├── tasks.yaml # Task registry
|
||||
└── locks.yaml # File locks
|
||||
```
|
||||
|
||||
### 3.1 Task Entry
|
||||
|
||||
```yaml
|
||||
tasks:
|
||||
- id: "TASK-001"
|
||||
agent: "codex"
|
||||
status: "in_progress" # pending | in_progress | completed | abandoned | blocked
|
||||
description: "Add unit tests for crawler"
|
||||
files: ["tests/test_crawler.py"]
|
||||
claimed_at: "{{DATE}}T10:00:00Z"
|
||||
expires_at: "{{DATE}}T22:00:00Z"
|
||||
```
|
||||
|
||||
### 3.2 Lock Entry
|
||||
|
||||
```yaml
|
||||
locks:
|
||||
- path: "src/crawler.py"
|
||||
agent: "claude"
|
||||
task_id: "TASK-001"
|
||||
lock_type: "exclusive" # exclusive | shared | override
|
||||
expires_at: "{{DATE}}T22:00:00Z"
|
||||
```
|
||||
|
||||
### 3.3 Expiration Rules
|
||||
|
||||
| Scenario | Duration |
|
||||
|----------|----------|
|
||||
| Standard task | 12 hours |
|
||||
| Complex refactoring | 24 hours |
|
||||
| Emergency fix | 4 hours |
|
||||
| Override (Claude) | 4 hours |
|
||||
|
||||
---
|
||||
|
||||
## 4. Workflow
|
||||
|
||||
### 4.1 Task Claiming
|
||||
|
||||
```bash
|
||||
# 1. Set identity
|
||||
export AGENT_AUTHOR=codex
|
||||
|
||||
# 2. Check state
|
||||
cat .agent-state/tasks.yaml
|
||||
cat .agent-state/locks.yaml
|
||||
|
||||
# 3. Claim task (add to tasks.yaml)
|
||||
git commit -m "[Codex] chore: claim TASK-001"
|
||||
|
||||
# 4. Do work, then commit
|
||||
git commit -m "[Codex] test(crawler): add unit tests"
|
||||
|
||||
# 5. Complete (update status, remove locks)
|
||||
git commit -m "[Codex] chore: complete TASK-001"
|
||||
```
|
||||
|
||||
### 4.2 Conflict Resolution
|
||||
|
||||
```
|
||||
1. Ownership Matrix → Owner has priority
|
||||
↓
|
||||
2. Active Locks → Lock holder has priority
|
||||
↓
|
||||
3. Task Assignment → Assigned agent has priority
|
||||
↓
|
||||
4. Escalate to Claude → Final decision
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Handoff Protocols
|
||||
|
||||
### 5.1 Claude → Sub-agent
|
||||
|
||||
```markdown
|
||||
## Task for [Gemini/Codex]
|
||||
|
||||
**Type:** [API | Docs | Tests | Models]
|
||||
**Priority:** [High | Medium | Low]
|
||||
|
||||
### Objective
|
||||
[What needs to be done]
|
||||
|
||||
### Deliverables
|
||||
- [ ] Implementation
|
||||
- [ ] Tests (if applicable)
|
||||
- [ ] Documentation update
|
||||
```
|
||||
|
||||
### 5.2 Sub-agent → Claude (Escalation)
|
||||
|
||||
```markdown
|
||||
## Escalation to Claude
|
||||
|
||||
**Reason:** [Architecture | Integration | Security | Complexity]
|
||||
|
||||
### Completed
|
||||
[What was finished]
|
||||
|
||||
### Blocking Issue
|
||||
[What needs Claude's decision]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Commit Standards
|
||||
|
||||
### 6.1 Format
|
||||
|
||||
```
|
||||
[Agent] type(scope): description
|
||||
|
||||
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### 6.2 Types & Tags
|
||||
|
||||
| Type | Purpose | Agent Tags |
|
||||
|------|---------|------------|
|
||||
| `feat` | New feature | `[Claude]` |
|
||||
| `fix` | Bug fix | `[Gemini]` |
|
||||
| `docs` | Documentation | `[Codex]` |
|
||||
| `test` | Tests | `[Human]` |
|
||||
| `refactor` | Refactoring | `[CI]` |
|
||||
| `chore` | Maintenance | |
|
||||
|
||||
---
|
||||
|
||||
## 7. Quality Gates
|
||||
|
||||
### 7.1 Pre-merge Checklist
|
||||
|
||||
- [ ] Tests pass (`pytest`)
|
||||
- [ ] Code quality passes (`black`, `isort`, `flake8`, `mypy`)
|
||||
- [ ] Ownership check passes
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] Documentation updated
|
||||
- [ ] Agent attribution in commits
|
||||
|
||||
### 7.2 Coverage Targets
|
||||
|
||||
| Scope | Minimum | Target |
|
||||
|-------|---------|--------|
|
||||
| Overall | 70% | 80% |
|
||||
| Core modules | 80% | 90% |
|
||||
| New code | 80% | 100% |
|
||||
|
||||
---
|
||||
|
||||
## 8. Quick Reference
|
||||
|
||||
### Environment Setup
|
||||
|
||||
```bash
|
||||
export AGENT_AUTHOR=claude # claude | gemini | codex | human
|
||||
pip install -e ".[dev]"
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
### Ownership Lookup
|
||||
|
||||
```
|
||||
Core logic, APIs, services → Claude
|
||||
Visualization, dashboards → Gemini
|
||||
Documentation → Gemini
|
||||
Tests, fixtures → Codex
|
||||
Utilities, models → Codex
|
||||
Dependencies, CI/CD → Shared (Claude approves)
|
||||
```
|
||||
|
||||
### Escalation Triggers
|
||||
|
||||
- Architectural decisions needed
|
||||
- Multi-file integration required
|
||||
- Security concerns
|
||||
- Performance optimization
|
||||
|
||||
---
|
||||
|
||||
*Generated by Multi-Agent Guide Skill v2.0*
|
||||
Reference in New Issue
Block a user