feat: Add OurDigital custom skills package (10 skills)
Complete implementation of OurDigital skills with dual-platform support (Claude Desktop + Claude Code) following standardized structure. Skills created: - 01-ourdigital-brand-guide: Brand reference & style guidelines - 02-ourdigital-blog: Korean blog drafts (blog.ourdigital.org) - 03-ourdigital-journal: English essays (journal.ourdigital.org) - 04-ourdigital-research: Research prompts & workflows - 05-ourdigital-document: Notion-to-presentation pipeline - 06-ourdigital-designer: Visual/image prompt generation - 07-ourdigital-ad-manager: Ad copywriting & keyword research - 08-ourdigital-trainer: Training materials & workshop planning - 09-ourdigital-backoffice: Quotes, proposals, cost analysis - 10-ourdigital-skill-creator: Meta skill for creating new skills Features: - YAML frontmatter with "ourdigital" or "our" prefix triggers - Standardized directory structure (code/, desktop/, shared/, docs/) - Shared environment setup (_ourdigital-shared/) - Comprehensive reference documentation - Cross-skill integration support Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
|
||||
<!-- Customize this section for your project -->
|
||||
|
||||
| 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 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
**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]*
|
||||
@@ -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
|
||||
|
||||
<!-- Customize this section for your project -->
|
||||
|
||||
| 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
|
||||
|
||||
<!-- Customize for your project structure -->
|
||||
|
||||
| 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.*
|
||||
@@ -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.*
|
||||
@@ -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.*
|
||||
@@ -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.')
|
||||
"
|
||||
@@ -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=<agent_name>
|
||||
|
||||
# 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]*
|
||||
@@ -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"
|
||||
@@ -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]
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user