docs(claude): refactor CLAUDE.md into modular documentation structure
- Refactor main CLAUDE.md from 491 to 164 lines (66% reduction) - Create 9 domain-specific CLAUDE.md files for focused guidance: * agents/CLAUDE.md (347 lines) - Agent development guide * marketing-skill/CLAUDE.md (253 lines) - Marketing tools * product-team/CLAUDE.md (268 lines) - Product management tools * engineering-team/CLAUDE.md (291 lines) - Engineering tools * standards/CLAUDE.md (176 lines) - Standards usage * c-level-advisor/CLAUDE.md (143 lines) - Strategic advisory * project-management/CLAUDE.md (139 lines) - Atlassian integration * ra-qm-team/CLAUDE.md (153 lines) - RA/QM compliance * templates/CLAUDE.md (77 lines) - Template system - Add navigation map in main CLAUDE.md for easy domain access - Create PROGRESS.md for real-time sprint tracking - Implement auto-documentation system for sprint progress Benefits: - Main CLAUDE.md now concise and navigable - Domain-specific guidance easier to find - No duplicate content across files - Better organization for 42 skills across 6 domains Total: 2,011 lines across 10 organized files vs 491 lines in 1 monolithic file Sprint: sprint-11-05-2025 Issue: Part of documentation refactoring milestone
This commit is contained in:
Reza Rezvani
347
agents/CLAUDE.md
Normal file
347
agents/CLAUDE.md
Normal file
@@ -0,0 +1,347 @@
|
||||
# Agent Development Guide
|
||||
|
||||
This guide provides comprehensive instructions for creating **cs-* prefixed agents** that seamlessly integrate with the 42 production skills in this repository.
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
### What are cs-* Agents?
|
||||
|
||||
**cs-* agents** are specialized Claude Code agents that orchestrate the 42 existing skills. Each agent:
|
||||
- References skills via relative paths (`../../marketing-skill/`)
|
||||
- Executes Python automation tools from skill packages
|
||||
- Follows established workflows and templates
|
||||
- Maintains skill portability and independence
|
||||
|
||||
**Key Principle**: Agents ORCHESTRATE skills, they don't replace them. Skills remain self-contained and portable.
|
||||
|
||||
### Agent vs Skill
|
||||
|
||||
| Aspect | Agent (cs-*) | Skill |
|
||||
|--------|-------------|-------|
|
||||
| **Purpose** | Orchestrate and execute workflows | Provide tools, knowledge, templates |
|
||||
| **Location** | `agents/domain/` | `domain-skill/skill-name/` |
|
||||
| **Structure** | Single .md file with YAML frontmatter | SKILL.md + scripts/ + references/ + assets/ |
|
||||
| **Integration** | References skills via `../../` | Self-contained, no dependencies |
|
||||
| **Naming** | cs-content-creator, cs-ceo-advisor | content-creator, ceo-advisor |
|
||||
|
||||
## Agent File Structure
|
||||
|
||||
### Required YAML Frontmatter
|
||||
|
||||
Every agent file must start with valid YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: cs-agent-name
|
||||
description: One-line description of what this agent does
|
||||
skills: skill-folder-name
|
||||
domain: domain-name
|
||||
model: sonnet
|
||||
tools: [Read, Write, Bash, Grep, Glob]
|
||||
---
|
||||
```
|
||||
|
||||
**Field Definitions:**
|
||||
- **name**: Agent identifier with `cs-` prefix (e.g., `cs-content-creator`)
|
||||
- **description**: Single sentence describing agent's purpose
|
||||
- **skills**: Skill folder this agent references (e.g., `marketing-skill/content-creator`)
|
||||
- **domain**: Domain category (marketing, product, engineering, c-level, pm, ra-qm)
|
||||
- **model**: Claude model to use (sonnet, opus, haiku)
|
||||
- **tools**: Array of Claude Code tools agent can use
|
||||
|
||||
### Required Markdown Sections
|
||||
|
||||
After YAML frontmatter, include these sections:
|
||||
|
||||
1. **Purpose** (2-3 paragraphs)
|
||||
2. **Skill Integration** (with subsections)
|
||||
- Skill Location
|
||||
- Python Tools
|
||||
- Knowledge Bases
|
||||
- Templates
|
||||
3. **Workflows** (minimum 3 workflows)
|
||||
4. **Integration Examples** (concrete code/command examples)
|
||||
5. **Success Metrics** (how to measure effectiveness)
|
||||
6. **Related Agents** (cross-references)
|
||||
7. **References** (links to documentation)
|
||||
|
||||
## Relative Path Resolution
|
||||
|
||||
### Path Pattern
|
||||
|
||||
All skill references use the `../../` pattern:
|
||||
|
||||
```markdown
|
||||
**Skill Location:** `../../marketing-skill/content-creator/`
|
||||
|
||||
### Python Tools
|
||||
|
||||
1. **Brand Voice Analyzer**
|
||||
- **Path:** `../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py`
|
||||
- **Usage:** `python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py content.txt`
|
||||
|
||||
2. **SEO Optimizer**
|
||||
- **Path:** `../../marketing-skill/content-creator/scripts/seo_optimizer.py`
|
||||
- **Usage:** `python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "keyword"`
|
||||
```
|
||||
|
||||
### Why `../../`?
|
||||
|
||||
From agent location: `agents/marketing/cs-content-creator.md`
|
||||
To skill location: `marketing-skill/content-creator/`
|
||||
|
||||
Navigation: `agents/marketing/` → `../../` (up to root) → `marketing-skill/content-creator/`
|
||||
|
||||
**Always test paths resolve correctly!**
|
||||
|
||||
## Python Tool Integration
|
||||
|
||||
### Execution Pattern
|
||||
|
||||
Agents execute Python tools from skill packages:
|
||||
|
||||
```bash
|
||||
# From agent context
|
||||
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt
|
||||
|
||||
# With JSON output
|
||||
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py input.txt json
|
||||
|
||||
# With arguments
|
||||
python ../../product-team/product-manager-toolkit/scripts/rice_prioritizer.py features.csv --capacity 20
|
||||
```
|
||||
|
||||
### Tool Requirements
|
||||
|
||||
All Python tools must:
|
||||
- Use standard library only (or minimal dependencies documented in SKILL.md)
|
||||
- Support both JSON and human-readable output
|
||||
- Provide `--help` flag with usage information
|
||||
- Return appropriate exit codes (0 = success, 1 = error)
|
||||
- Handle missing arguments gracefully
|
||||
|
||||
### Error Handling
|
||||
|
||||
When Python tools fail:
|
||||
1. Check file path resolution
|
||||
2. Verify input file exists
|
||||
3. Check Python version compatibility (3.8+)
|
||||
4. Review tool's `--help` output
|
||||
5. Inspect error messages in stderr
|
||||
|
||||
## Workflow Documentation
|
||||
|
||||
### Workflow Structure
|
||||
|
||||
Each workflow must include:
|
||||
|
||||
```markdown
|
||||
### Workflow 1: [Clear Descriptive Name]
|
||||
|
||||
**Goal:** One-sentence description
|
||||
|
||||
**Steps:**
|
||||
1. **[Action]** - Description with specific commands/tools
|
||||
2. **[Action]** - Description with specific commands/tools
|
||||
3. **[Action]** - Description with specific commands/tools
|
||||
|
||||
**Expected Output:** What success looks like
|
||||
|
||||
**Time Estimate:** How long this workflow takes
|
||||
|
||||
**Example:**
|
||||
\`\`\`bash
|
||||
# Concrete example command
|
||||
python ../../marketing-skill/content-creator/scripts/seo_optimizer.py article.md "primary keyword"
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Minimum Requirements
|
||||
|
||||
Each agent must document **at least 3 workflows** covering:
|
||||
1. Primary use case (most common scenario)
|
||||
2. Advanced use case (complex scenario)
|
||||
3. Integration use case (combining multiple tools)
|
||||
|
||||
## Agent Template
|
||||
|
||||
Use this template when creating new agents:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: cs-agent-name
|
||||
description: One-line description
|
||||
skills: skill-folder-name
|
||||
domain: domain-name
|
||||
model: sonnet
|
||||
tools: [Read, Write, Bash, Grep, Glob]
|
||||
---
|
||||
|
||||
# Agent Name
|
||||
|
||||
## Purpose
|
||||
|
||||
[2-3 paragraphs describing what this agent does, why it exists, and who it serves]
|
||||
|
||||
## Skill Integration
|
||||
|
||||
**Skill Location:** \`../../domain-skill/skill-name/\`
|
||||
|
||||
### Python Tools
|
||||
|
||||
1. **Tool Name**
|
||||
- **Purpose:** What it does
|
||||
- **Path:** \`../../domain-skill/skill-name/scripts/tool.py\`
|
||||
- **Usage:** \`python ../../domain-skill/skill-name/scripts/tool.py [args]\`
|
||||
|
||||
### Knowledge Bases
|
||||
|
||||
1. **Reference Name**
|
||||
- **Location:** \`../../domain-skill/skill-name/references/file.md\`
|
||||
- **Content:** What's inside
|
||||
|
||||
### Templates
|
||||
|
||||
1. **Template Name**
|
||||
- **Location:** \`../../domain-skill/skill-name/assets/template.md\`
|
||||
- **Use Case:** When to use
|
||||
|
||||
## Workflows
|
||||
|
||||
### Workflow 1: [Name]
|
||||
|
||||
**Goal:** Description
|
||||
|
||||
**Steps:**
|
||||
1. Step 1
|
||||
2. Step 2
|
||||
3. Step 3
|
||||
|
||||
**Expected Output:** Success criteria
|
||||
|
||||
**Example:**
|
||||
\`\`\`bash
|
||||
python ../../domain-skill/skill-name/scripts/tool.py input.txt
|
||||
\`\`\`
|
||||
|
||||
### Workflow 2: [Name]
|
||||
[Same structure]
|
||||
|
||||
### Workflow 3: [Name]
|
||||
[Same structure]
|
||||
|
||||
## Integration Examples
|
||||
|
||||
[Concrete examples with actual commands and expected outputs]
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- Metric 1: How to measure
|
||||
- Metric 2: How to measure
|
||||
- Metric 3: How to measure
|
||||
|
||||
## Related Agents
|
||||
|
||||
- [cs-related-agent](../domain/cs-related-agent.md) - How they relate
|
||||
|
||||
## References
|
||||
|
||||
- [Skill Documentation](../../domain-skill/skill-name/SKILL.md)
|
||||
- [Domain Roadmap](../../domain-skill/roadmap.md)
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Agent Quality Checklist
|
||||
|
||||
Before committing an agent:
|
||||
|
||||
- [ ] YAML frontmatter valid (no parsing errors)
|
||||
- [ ] All required fields present (name, description, skills, domain, model, tools)
|
||||
- [ ] cs-* prefix used for agent naming
|
||||
- [ ] Relative paths resolve correctly (../../ pattern)
|
||||
- [ ] Skill location documented and accessible
|
||||
- [ ] Python tools referenced with correct paths
|
||||
- [ ] At least 3 workflows documented
|
||||
- [ ] Integration examples provided and tested
|
||||
- [ ] Success metrics defined
|
||||
- [ ] Related agents cross-referenced
|
||||
|
||||
### Testing Agent Integration
|
||||
|
||||
Test these aspects:
|
||||
|
||||
**1. Path Resolution**
|
||||
```bash
|
||||
# From agent directory
|
||||
cd agents/marketing/
|
||||
ls ../../marketing-skill/content-creator/ # Should list contents
|
||||
```
|
||||
|
||||
**2. Python Tool Execution**
|
||||
```bash
|
||||
# Create test input
|
||||
echo "Test content" > test-input.txt
|
||||
|
||||
# Execute tool
|
||||
python ../../marketing-skill/content-creator/scripts/brand_voice_analyzer.py test-input.txt
|
||||
|
||||
# Verify output
|
||||
```
|
||||
|
||||
**3. Knowledge Base Access**
|
||||
```bash
|
||||
# Verify reference files exist
|
||||
cat ../../marketing-skill/content-creator/references/brand_guidelines.md
|
||||
```
|
||||
|
||||
## Domain-Specific Guidelines
|
||||
|
||||
### Marketing Agents (agents/marketing/)
|
||||
- Focus on content creation, SEO, demand generation
|
||||
- Reference: `../../marketing-skill/`
|
||||
- Tools: brand_voice_analyzer.py, seo_optimizer.py
|
||||
|
||||
### Product Agents (agents/product/)
|
||||
- Focus on prioritization, user research, agile workflows
|
||||
- Reference: `../../product-team/`
|
||||
- Tools: rice_prioritizer.py, user_story_generator.py, okr_cascade_generator.py
|
||||
|
||||
### C-Level Agents (agents/c-level/)
|
||||
- Focus on strategic decision-making
|
||||
- Reference: `../../c-level-advisor/`
|
||||
- Tools: Strategic analysis and planning tools
|
||||
|
||||
### Engineering Agents (agents/engineering/)
|
||||
- Focus on scaffolding, code quality, fullstack development
|
||||
- Reference: `../../engineering-team/`
|
||||
- Tools: project_scaffolder.py, code_quality_analyzer.py
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
**Avoid these mistakes:**
|
||||
|
||||
❌ Hardcoding absolute paths
|
||||
❌ Skipping YAML frontmatter validation
|
||||
❌ Forgetting to test relative paths
|
||||
❌ Documenting workflows without examples
|
||||
❌ Creating agent dependencies (keep them independent)
|
||||
❌ Duplicating skill content in agent files
|
||||
❌ Using LLM calls instead of referencing Python tools
|
||||
|
||||
## Next Steps
|
||||
|
||||
After creating an agent:
|
||||
|
||||
1. Test all relative paths resolve
|
||||
2. Execute all Python tools from agent context
|
||||
3. Verify all workflows with concrete examples
|
||||
4. Update agent catalog in main README.md
|
||||
5. Create GitHub issue for agent testing
|
||||
6. Commit with conventional commit message: `feat(agents): implement cs-agent-name`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** November 5, 2025
|
||||
**Current Sprint:** sprint-11-05-2025 (Skill-Agent Integration Phase 1-2)
|
||||
**Related:** See [main CLAUDE.md](../CLAUDE.md) for repository overview
|
||||
Reference in New Issue
Block a user