# Workflow Documentation Index

> Navigation hub for all workflow documentation.

---

## Overview

This directory contains operational workflow documentation for AI agents. These documents define **how** to perform common operations safely and consistently.

**Before using these workflows:** Always read [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md) first.

---

## Quick Reference Table

| Document | Purpose | When to Use |
|----------|---------|-------------|
| [AGENT_EXECUTION.md](./AGENT_EXECUTION.md) | Standard execution protocol and rollback | During task execution |
| [AGENT_ESCALATION.md](./AGENT_ESCALATION.md) | Audit requirements and escalation | When uncertain or errors occur |
| [TESTING_VALIDATION.md](./TESTING_VALIDATION.md) | Validation and verification protocols | Before committing changes |
| [COMMIT_WORKFLOW.md](./COMMIT_WORKFLOW.md) | Commit timing and message format | After completing to-dos |
| [GIT_PUSH_PROCEDURES.md](./GIT_PUSH_PROCEDURES.md) | Push safety and verification | Before pushing to remote |
| [BRANCH_STRATEGY.md](./BRANCH_STRATEGY.md) | Branch naming and workflows | When creating branches |
| [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md) | Undo and recovery operations | When errors occur |
| [CODE_REVIEW.md](./CODE_REVIEW.md) | Review process and escalation | After code changes |
| [MCP_CHECKPOINTING.md](./MCP_CHECKPOINTING.md) | MCP checkpoint integration | Before/after critical tasks |
| [DOCUMENTATION_UPDATES.md](./DOCUMENTATION_UPDATES.md) | Post-sprint doc updates | After completing sprints |

---

## Document Summaries

### AGENT_EXECUTION.md
Defines the standard execution protocol for AI agents, including task flow, decision matrices, rollback procedures, commit message formats, and error handling protocols.

**Key sections:**
- Standard task flow (5 phases)
- Decision matrix
- Rollback procedures (immediate, post-commit, post-push)
- Commit message format
- Error handling protocols
- Verification checklists

### AGENT_ESCALATION.md
Defines audit requirements, escalation procedures, and platform-specific guidelines for AI agents operating on this codebase.

**Key sections:**
- Audit log requirements (what to log)
- Log format standards
- When to escalate to human
- How to escalate (templates and scenarios)
- Agent-specific guidelines (by category)
- Compliance and violation reporting

### TESTING_VALIDATION.md
Defines validation functions and git diff verification patterns. Use this to understand how to double-check all work before committing.

**Key sections:**
- Pre-edit validation patterns
- Post-edit validation
- Git diff verification protocol
- Language-specific validation

### COMMIT_WORKFLOW.md
Guidelines for when and how to commit changes, especially the rule for committing between to-do items.

**Key sections:**
- Commit decision matrix
- "Commit after each to-do" rule
- Commit message format
- Pre-commit checklist

### GIT_PUSH_PROCEDURES.md
Safety procedures for pushing to remote repositories, including pre-push checklists and error handling.

**Key sections:**
- Pre-push checklist
- Push decision matrix
- Branch-specific procedures
- Push safety rules

### BRANCH_STRATEGY.md
Git branching conventions including naming, workflows, and merge strategies.

**Key sections:**
- Branch naming conventions
- Feature branch workflow
- Hotfix emergency procedures
- Merge vs rebase guidance

### ROLLBACK_PROCEDURES.md
Comprehensive recovery and undo operations for all scenarios.

**Key sections:**
- Immediate rollback (uncommitted)
- Post-commit rollback
- Post-push rollback
- Disaster recovery checklist

### CODE_REVIEW.md
Code review process for agents including self-review and human escalation.

**Key sections:**
- Agent self-review checklist
- When to request human review
- Review focus areas
- Escalation procedures

### MCP_CHECKPOINTING.md
Integration with MCP servers for automatic checkpointing before and after tasks.

**Key sections:**
- Checkpoint concepts
- MCP server integration
- Checkpoint-aware sprints
- Recovery from checkpoints

### DOCUMENTATION_UPDATES.md
Procedures for updating documentation after sprints and code changes.

**Key sections:**
- Post-sprint updates
- Documentation review checklist
- Cross-reference maintenance

---

## Integration with Guardrails

All workflows in this directory **support** the safety protocols defined in [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md). They provide detailed implementation guidance for:

- **Execution** → AGENT_EXECUTION.md
- **Audit & escalation** → AGENT_ESCALATION.md
- **Verification** → TESTING_VALIDATION.md
- **Commits** → COMMIT_WORKFLOW.md
- **Rollback** → ROLLBACK_PROCEDURES.md
- **Error handling** → Referenced throughout

---

## Related Documents

- [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md) - Mandatory safety protocols
- [../standards/INDEX.md](../standards/INDEX.md) - Documentation standards
- [../sprints/INDEX.md](../sprints/INDEX.md) - Sprint task framework

---

**Last Updated:** 2026-01-16
**Document Count:** 10