Atomizer/docs/protocols/extensions/EXT_03_CREATE_PROTOCOL.md

# EXT_03: Create New Protocol

<!--
PROTOCOL: Create New Protocol Document
LAYER: Extensions
VERSION: 1.0
STATUS: Active
LAST_UPDATED: 2025-12-05
PRIVILEGE: admin
LOAD_WITH: []
-->

## Overview

This protocol guides you through creating new protocol documents for the Atomizer Protocol Operating System (POS). Use this when adding significant new system capabilities.

**Privilege Required**: admin

---

## When to Use

| Trigger | Action |
|---------|--------|
| Adding major new system capability | Follow this protocol |
| "create protocol", "new protocol" | Follow this protocol |
| Need to document architectural pattern | Follow this protocol |

---

## Protocol Types

| Layer | Prefix | Purpose | Example |
|-------|--------|---------|---------|
| Operations | OP_ | How-to guides | OP_01_CREATE_STUDY |
| System | SYS_ | Core specifications | SYS_10_IMSO |
| Extensions | EXT_ | Extensibility guides | EXT_01_CREATE_EXTRACTOR |

---

## Step-by-Step Guide

### Step 1: Determine Protocol Type

- **Operations (OP_)**: User-facing procedures
- **System (SYS_)**: Technical specifications
- **Extensions (EXT_)**: Developer guides

### Step 2: Assign Protocol Number

**Operations**: Sequential (OP_01, OP_02, ...)
**System**: By feature area (SYS_10=optimization, SYS_11=multi-obj, etc.)
**Extensions**: Sequential (EXT_01, EXT_02, ...)

Check existing protocols to avoid conflicts.

### Step 3: Create Protocol File

Use the template from `templates/protocol_template.md`:

```markdown
# {LAYER}_{NUMBER}_{NAME}.md

<!--
PROTOCOL: {Full Name}
LAYER: {Operations|System|Extensions}
VERSION: 1.0
STATUS: Active
LAST_UPDATED: {YYYY-MM-DD}
PRIVILEGE: {user|power_user|admin}
LOAD_WITH: [{dependencies}]
-->

## Overview

{1-3 sentence description of what this protocol does}

---

## When to Use

| Trigger | Action |
|---------|--------|
| {keyword or condition} | Follow this protocol |

---

## Quick Reference

{Tables with key parameters, commands, or mappings}

---

## Detailed Specification

### Section 1: {Topic}

{Content}

### Section 2: {Topic}

{Content}

---

## Examples

### Example 1: {Scenario}

{Complete working example}

---

## Troubleshooting

| Symptom | Cause | Solution |
|---------|-------|----------|
| {error} | {why} | {fix} |

---

## Cross-References

- **Depends On**: [{protocol}]({path})
- **Used By**: [{protocol}]({path})
- **See Also**: [{related}]({path})

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | {DATE} | Initial release |
```

### Step 4: Write Content

**Required Sections**:
1. Overview - What does this protocol do?
2. When to Use - Trigger conditions
3. Quick Reference - Fast lookup
4. Detailed Specification - Full content
5. Examples - Working examples
6. Troubleshooting - Common issues
7. Cross-References - Related protocols
8. Version History - Changes over time

**Writing Guidelines**:
- Front-load important information
- Use tables for structured data
- Include complete code examples
- Provide troubleshooting for common issues

### Step 5: Update Navigation

**docs/protocols/README.md**:
```markdown
| {NUM} | {Name} | [{Layer}]({layer}/{filename}) |
```

**.claude/skills/01_CHEATSHEET.md**:
```markdown
| {task} | {LAYER}_{NUM} | {key info} |
```

**.claude/skills/02_CONTEXT_LOADER.md**:
Add loading rules if needed.

### Step 6: Update Cross-References

Add references in related protocols:
- "Depends On" in new protocol
- "Used By" or "See Also" in existing protocols

### Step 7: Validate

```bash
# Check markdown syntax
# Verify all links work
# Test code examples
# Ensure consistent formatting
```

---

## Protocol Metadata

### Header Comment Block

```markdown
<!--
PROTOCOL: Full Protocol Name
LAYER: Operations|System|Extensions
VERSION: Major.Minor
STATUS: Active|Draft|Deprecated
LAST_UPDATED: YYYY-MM-DD
PRIVILEGE: user|power_user|admin
LOAD_WITH: [SYS_10, SYS_11]
-->
```

### Status Values

| Status | Meaning |
|--------|---------|
| Draft | In development, not ready for use |
| Active | Production ready |
| Deprecated | Being phased out |

### Privilege Levels

| Level | Who Can Use |
|-------|-------------|
| user | All users |
| power_user | Developers who can extend |
| admin | Full system access |

---

## Versioning

### Semantic Versioning

- **Major (X.0)**: Breaking changes
- **Minor (1.X)**: New features, backward compatible
- **Patch (1.0.X)**: Bug fixes (usually omit for docs)

### Version History Format

```markdown
| Version | Date | Changes |
|---------|------|---------|
| 2.0 | 2025-12-15 | Redesigned architecture |
| 1.1 | 2025-12-05 | Added neural support |
| 1.0 | 2025-11-20 | Initial release |
```

---

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| Protocol not found | Wrong path | Check location and README |
| LLM not loading | Missing from context loader | Update 02_CONTEXT_LOADER.md |
| Broken links | Path changed | Update cross-references |

---

## Cross-References

- **Template**: `templates/protocol_template.md`
- **Navigation**: `docs/protocols/README.md`
- **Context Loading**: `.claude/skills/02_CONTEXT_LOADER.md`

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-12-05 | Initial release |