# Template Implementation Notes

## Proof of Concept Results

### Test Case: Logs Agent

**Before (original)**:
- File: `agents/logs.md`
- Lines: 211
- Duplicated sections: 24 lines (Important Context + Time Formats + Permission Model)

**After (with templates)**:
- File: `agents/_templates/EXAMPLE_logs_refactored.md`
- Lines: 190
- Template references: 3 comments

**Savings**:
- Direct reduction: 21 lines (10%)
- Maintenance reduction: 24 lines of content → centralized in templates
- Net benefit: Template changes propagate to all agents automatically

### Extrapolation to Full Agent Set

**Current state** (46 agents):
- Total agent lines: ~33,897
- Average per agent: ~737 lines
- Estimated duplicated content: ~15,000 lines (templates used ~35 times each)

**With templates** (projected):
- Template overhead: ~50 lines (5 templates × 10 lines each)
- Template references: ~140 lines (46 agents × 3 references)
- Unique content: ~18,900 lines
- **Total**: ~19,090 lines

**Projected savings**:
- **14,807 lines removed** (43.7% reduction)
- **Maintenance**: Update 5 files instead of 46 for common changes
- **Consistency**: Guaranteed identical wording across agents

## Rollout Strategy

### Phase 3A: Template Infrastructure ✅ COMPLETE
- [x] Create `agents/_templates/` directory
- [x] Extract common sections to 5 template files
- [x] Document template usage in README.md
- [x] Create proof-of-concept refactored agent

### Phase 3B: Validation (Current)
- [ ] Test template approach with 2-3 more agents
- [ ] Verify template completeness
- [ ] Adjust templates based on edge cases
- [ ] Get feedback on approach

### Phase 3C: Rollout (Future)
- [ ] Refactor all 46 agents to use templates
- [ ] Update AGENTS.md to reference template system
- [ ] Add validation script to ensure template consistency
- [ ] Document for contributors

## Implementation Approach

Two options for implementing templates in agents:

### Option 1: Template Comments (Current)
Use HTML comments to mark where template content should be inserted:

```markdown
<!-- TEMPLATE: pup-context.md -->
```

**Pros**:
- Simple to implement
- Clear intent
- Doesn't require build process
- Templates stay as documentation

**Cons**:
- Content not actually inserted
- Relies on Claude understanding the pattern
- Manual updates still needed

### Option 2: Build-Time Injection
Use a build script to inject template content:

```bash
#!/bin/bash
# build-agents.sh
for agent in agents/*.md; do
  sed '/<!-- TEMPLATE: pup-context.md -->/r agents/_templates/pup-context.md' "$agent"
done
```

**Pros**:
- Actual content insertion
- No runtime dependencies
- Standard markdown files

**Cons**:
- Requires build process
- Harder to maintain source files
- Need to track source vs built files

### Recommendation: Option 1 (Template Comments)

For this Claude plugin, **Option 1** is preferred because:
1. Claude can understand template references
2. No build toolchain needed
3. Source files remain clean and maintainable
4. Templates serve as documentation
5. Easy for contributors to understand

## Template Usage Examples

### Read-Only Agent (logs, metrics, traces, etc.)
```markdown
---
description: Agent description
---

# Agent Name

Agent introduction and role.

## Your Capabilities
- List of capabilities

<!-- TEMPLATE: pup-context.md -->

## Available Commands
[Domain-specific commands]

<!-- TEMPLATE: time-formats.md -->

<!-- TEMPLATE: permission-model-read.md -->

## Response Formatting
[Domain-specific formatting]

## Common User Requests
[Domain-specific examples]
```

### Write Agent (monitors, dashboards, etc.)
```markdown
---
description: Agent description
---

# Agent Name

Agent introduction and role.

## Your Capabilities
- List of capabilities

<!-- TEMPLATE: pup-context.md -->

## Available Commands
[Domain-specific commands]

<!-- TEMPLATE: permission-model-write.md -->

## Response Formatting
[Domain-specific formatting]
```

### Mixed Agent (monitoring-alerting, log-configuration, etc.)
```markdown
<!-- TEMPLATE: pup-context.md -->
<!-- TEMPLATE: permission-model-mixed.md -->
```

## Metrics and Success Criteria

### Success Metrics
- [x] Templates created and documented
- [x] Proof-of-concept shows measurable reduction
- [ ] All 46 agents refactored
- [ ] Documentation updated
- [ ] Contributor guide includes template info

### Quality Metrics
- Template content accuracy: 100%
- Template coverage: 100% of agents use appropriate templates
- Consistency: No agent-specific variations of template content
- Maintainability: Single source of truth for common sections

## Future Enhancements

1. **Additional Templates**
   - Common response formatting patterns
   - Error handling boilerplate
   - Integration notes patterns

2. **Validation Tooling**
   - Script to verify template usage
   - Lint rules for template compliance
   - CI check for template consistency

3. **Documentation Templates**
   - README sections for new agents
   - CHANGELOG entry templates
   - PR description templates

## Lessons Learned

1. **Template Granularity**: 5 templates is the right balance - not too many, not too few
2. **Comment Syntax**: HTML comments work well in markdown and are clear
3. **Documentation Critical**: README.md in templates dir is essential
4. **Proof of Concept**: Testing with one agent before rollout was valuable