# Specification for Creating Agent Task Templates

**Version:** 1.0.0
**Purpose:** Define requirements for creating new pluggable agent task templates

---

## Overview

This specification guides the creation of agent task templates that work with the infinite-templated system. Templates are parameterized blueprints that define exactly how agents should perform specific types of tasks.

## Template File Structure

### Location
All templates must be stored in: `.claude/templates/{{template_name}}.md`

### File Format
Templates are Markdown files with specific sections and parameter placeholders using `{{PARAMETER}}` syntax.

## Required Sections

Every template must include these sections in order:

### 1. Metadata Header

```markdown
# {{Template Title}}

**Template Name:** `{{template-name}}`
**Template Version:** `X.Y.Z`
**Template Category:** `{{category}}`
```

**Requirements:**
- Template name in kebab-case
- Semantic version number
- Category from: generation, analysis, quality-assurance, research, testing, documentation

### 2. Template Overview

```markdown
## Template Overview

**Purpose:** {{single sentence describing what this template does}}

**Use Cases:**
{{bulleted list of 3-5 use cases}}

**Prerequisites:**
{{what's needed before using this template}}
```

**Requirements:**
- Clear, concise purpose statement
- Concrete use case examples
- List any tool, file, or knowledge prerequisites

### 3. Agent Role Definition

```markdown
## Agent Role Definition

You are a **{{Role Title}}** with the following characteristics:

**Primary Responsibilities:**
{{numbered list of 3-5 responsibilities}}

**Expertise Areas:**
{{bulleted list of relevant expertise}}

**Working Style:**
{{description of how agent should work}}
```

**Requirements:**
- Define agent as a role with expertise (e.g., "Code Quality Analyst")
- Be specific about responsibilities
- Set expectations for working style
- Follow "treat as new employee" principle

### 4. Task Context

```markdown
## Task Context

**Project Context:**
{{PROJECT_NAME}} - {{PROJECT_DESCRIPTION}}

**Workflow Position:**
{{where this task fits in larger workflow}}

**Success Criteria:**
{{numbered list of what defines success}}

**Constraints:**
{{what the agent must not do or limitations}}
```

**Requirements:**
- Include parameterized project context
- Explain where task fits in workflow
- Define measurable success criteria
- State explicit constraints

### 5. Execution Instructions

```markdown
## Execution Instructions

Follow these steps precisely and in order:

### Step 1: {{Step Name}}
**Instructions:**
{{detailed, explicit instructions}}

**Expected Output:**
{{what this step should produce}}

### Step 2: {{Step Name}}
[Same format]

[Continue for 3-7 steps]
```

**Requirements:**
- Minimum 3 steps, maximum 7 steps
- Steps must be sequential and numbered
- Each step has clear name
- Instructions are explicit and unambiguous
- Expected output clearly defined
- Use sub-steps if needed (numbered lists within step)

### 6. Output Specifications

```markdown
## Output Specifications

**Output Format:**
{{description of output format}}

**Required Elements:**
{{numbered list of required elements in output}}

**Quality Standards:**
{{what makes output high quality}}

**Deliverables:**
{{specific files or artifacts to produce}}
```

**Requirements:**
- Specify exact format (file type, structure)
- List all required elements
- Define quality criteria
- Name specific deliverables

### 7. Template Parameters Reference

```markdown
## Template Parameters Reference

| Parameter | Type | Required | Description | Example |
|-----------|------|----------|-------------|---------|
| PARAM_1 | type | Yes/No | Description | Example value |
[... all parameters ...]
```

**Requirements:**
- Document EVERY parameter used in template
- Specify type (string, number, path, url, list, object)
- Mark as required or optional
- Provide clear description
- Show example value

### 8. Example Usage

```markdown
## Example Usage

\`\`\`markdown
# Agent Assignment

You are being assigned a {{task type}} task.

**Template:** {{template_name}}
**Parameters:**
- PARAMETER_1: "value"
- PARAMETER_2: 123
[... all parameters ...]

Execute the {{template_name}} template with these parameters.
\`\`\`
```

**Requirements:**
- Show concrete, realistic example
- Include all required parameters
- Demonstrate parameter substitution
- Make it copy-paste usable

### 9. Validation Checklist

```markdown
## Validation Checklist

Before completing the task, verify:

- [ ] {{validation item 1}}
- [ ] {{validation item 2}}
[... 5-10 items ...]
```

**Requirements:**
- Provide 5-10 validation items
- Items should be checkable/verifiable
- Cover all critical requirements
- Match success criteria from Task Context

### 10. Notes and Best Practices

```markdown
## Notes and Best Practices

{{Tips, common pitfalls, efficiency suggestions, etc.}}
```

**Requirements:**
- Provide practical tips
- Note common pitfalls
- Suggest best practices
- Include any important caveats

### 11. Footer

```markdown
---

**Template Source:** Based on Anthropic's "Be Clear and Direct" prompt engineering principles
**Design Philosophy:** {{brief statement of design approach}}
**Last Updated:** {{date}}
```

## Parameter Design Requirements

### Naming Conventions

1. **Use UPPER_SNAKE_CASE:**
   - Correct: `WEB_URL`, `OUTPUT_DIR`, `MIN_TECHNIQUES`
   - Incorrect: `webUrl`, `output-dir`, `minTechniques`

2. **Be Descriptive:**
   - Correct: `VALIDATION_SPEC`, `LEARNING_FOCUS`
   - Incorrect: `SPEC`, `FOCUS`

3. **Be Specific:**
   - Correct: `WEB_URL` (not just `URL`)
   - Correct: `OUTPUT_DIR` (not just `DIR`)

### Parameter Types

- **string**: Text value (e.g., "example")
- **number**: Numeric value (e.g., 42)
- **path**: File system path (e.g., "/project/file.txt")
- **url**: Web URL (e.g., "https://example.com")
- **list**: Array of values (e.g., ["item1", "item2"])
- **object**: JSON object (e.g., {"key": "value"})
- **glob**: Glob pattern (e.g., "*.html")

### Required vs. Optional

- **Required**: Must be provided, no default available
- **Optional**: Has sensible default or can be omitted

Document defaults for optional parameters in the reference table.

### Substitution Syntax

Use `{{PARAMETER}}` syntax:
- Correct: `{{OUTPUT_DIR}}/{{FILE_NAME}}`
- Incorrect: `$OUTPUT_DIR/$FILE_NAME`
- Incorrect: `{OUTPUT_DIR}/{FILE_NAME}`

## Instruction Writing Guidelines

Based on Anthropic's "Be Clear and Direct" principles:

### 1. Be Explicit

**Bad:**
```
Analyze the code.
```

**Good:**
```
1. Read all files in {{TARGET_DIR}}
2. For each file:
   - Count lines of code
   - Identify functions and classes
   - Check for TODO comments
3. Document findings in a table
```

### 2. Provide Context

**Bad:**
```
Generate a report.
```

**Good:**
```
Generate a compliance report that will be reviewed by the quality assurance team before release. The report must clearly show pass/fail status for each requirement so non-technical stakeholders can understand results at a glance.
```

### 3. Define Success

**Bad:**
```
Make it good.
```

**Good:**
```
Success criteria:
1. All 15 validation rules checked
2. Each failure has specific evidence quoted from code
3. Remediation steps provided for each failure
4. Report is formatted as markdown with tables
5. Executive summary fits in one paragraph
```

### 4. Specify Output Format

**Bad:**
```
Create documentation.
```

**Good:**
```
Create a markdown file with:
1. Header: # Analysis Results
2. Table with columns: File, LOC, Complexity, Issues
3. Bulleted list of top 3 issues
4. Code snippet examples for each issue
5. Recommendations section with numbered action items
```

### 5. Show Examples

Include concrete examples in instructions:
```
Name the file following this pattern: `viz_{{theme}}_{{number}}.html`
For example: viz_network_007.html or viz_timeline_012.html
```

## Quality Standards

A template is considered high quality when:

### Completeness
- All required sections present
- All parameters documented
- Example usage provided
- Validation checklist complete

### Clarity
- Instructions are unambiguous
- No steps require guessing
- Examples clarify instructions
- Success criteria measurable

### Reusability
- Template works for multiple scenarios
- Parameters enable flexibility
- No hardcoded values that should be parameters
- Template composition possible (reference other templates)

### Effectiveness
- Agents can execute without questions
- Output consistently meets requirements
- Template follows "be clear and direct" principles
- Instructions treat agent as capable but uninformed

## Testing Checklist

Before finalizing a template:

- [ ] All sections present and complete
- [ ] 3-7 execution steps defined
- [ ] All parameters documented in reference table
- [ ] Example usage is concrete and complete
- [ ] No ambiguous instructions
- [ ] Success criteria are measurable
- [ ] Validation checklist matches success criteria
- [ ] File saved to `.claude/templates/{{name}}.md`
- [ ] No unsubstituted placeholders (unless intentional parameters)
- [ ] Follows "be clear and direct" principles

## Template Categories

**generation**: Create new artifacts (code, docs, data)
**analysis**: Analyze existing artifacts, extract insights
**quality-assurance**: Validate, verify, test artifacts
**research**: Gather information, learn from sources
**testing**: Execute tests, verify functionality
**documentation**: Create or update documentation

Choose the most specific category.

---

## Example Template Scaffolding

Use this as starting point for new templates:

```markdown
# {{Your Template Name}}

**Template Name:** `your-template-name`
**Template Version:** `1.0.0`
**Template Category:** `{{category}}`

---

## Template Overview

**Purpose:** [One sentence]

**Use Cases:**
- [Use case 1]
- [Use case 2]
- [Use case 3]

**Prerequisites:**
- [Prerequisite 1]
- [Prerequisite 2]

---

## Agent Role Definition

You are a **{{Role Name}}** with the following characteristics:

**Primary Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]
3. [Responsibility 3]

**Expertise Areas:**
- [Expertise 1]
- [Expertise 2]

**Working Style:**
[Description]

---

[Continue with remaining sections...]
```

---

**This specification follows its own requirements** - it provides clear, explicit guidance for creating templates that provide clear, explicit guidance for agents.