agent-sop

Agent SOPs

Agent SOPs (Standard Operating Procedures) are markdown-based instruction sets that guide AI agents through sophisticated workflows using natural language, parameterized inputs, and constraint-based execution. They transform complex processes into reusable, shareable workflows that work across different AI systems and teams.

Lovingly nicknamed "Strands Operating Procedures" by the team.

What are Agent SOPs?

Agent SOPs use a standardized format to define:

• Clear objectives with detailed overviews
• Parameterized inputs for flexible reuse across different contexts
• Step-by-step instructions with RFC 2119 constraints (MUST, SHOULD, MAY)
• Examples and troubleshooting for reliable execution
• Multi-modal distribution (MCP tools, Anthropic Skills, Python modules)

Example SOP Structure

# Code Assist

## Overview
This SOP guides the implementation of code tasks using test-driven development 
principles, following a structured Explore, Plan, Code, Commit workflow.

## Parameters
- **task_description** (required): Description of the task to be implemented
- **mode** (optional, default: "interactive"): "interactive" or "fsc" (Full Self-Coding)

## Steps
### 1. Setup
Initialize the project environment and create necessary directory structures.

**Constraints:**
- You MUST validate and create the documentation directory structure
- You MUST discover existing instruction files using find commands
- You MUST NOT proceed if directory creation fails

### 2. Explore Phase
[Additional steps with specific constraints...]

Available SOPs

SOP	Purpose	Use Cases
codebase-summary	Comprehensive codebase analysis and documentation generation	Project onboarding, documentation creation, system understanding
pdd	Prompt-driven development methodology	Complex problem solving, architectural decisions, system design
code-task-generator	Intelligent task breakdown and planning from requirements	Project planning, sprint preparation, requirement analysis
code-assist	TDD-based code implementation with structured workflow	Feature development, bug fixes, refactoring
eval	Automated evaluation workflow for AI agents using Strands Evals SDK	Evaluation planning, test data generation, evaluation execution, and result analysis (usage guide)

Directory Structure

The Prompt-Driven Development (PDD) family of SOPs (codebase-summary, pdd, code-task-generator, code-assist) write their artifacts to a .agents/ directory with this default organizational structure:

.agents/
├── summary/               # codebase-summary output (always commit)
│   └── *.md
├── planning/              # pdd output (often worth committing)
│   └── {project_name}/
│       ├── rough-idea.md
│       ├── idea-honing.md
│       ├── research/
│       ├── design/
│       └── implementation/
├── tasks/                 # code-task-generator output (optionally commit)
│   └── {project_name}/
│       └── step01/
│           └── task-*.code-task.md
└── scratchpad/            # code-assist working files (add to .gitignore)
    └── {project_name}/
        └── {task_name}/

Why this structure?

The hierarchy is organized by what you're likely to want to commit: