DOCSEARCHbyAlgolia
Submit Docs

Agent SOPs

repository·main·Indexed 22 days ago

https://github.com/strands-agents/agent-sop

A standardized, markdown-based framework for defining complex, multi-step workflows for AI agents. It provides built-in SOPs for codebase analysis, prompt-driven development (PDD), and TDD-based coding. The library includes a Model Context Protocol (MCP) server, a Python SDK for integration with Strands Agents, and tools to convert SOPs into Cursor Commands and Agent Skills for Claude.

Tokens
27.4K
Snippets
57
Records
107
Agent score
69%

What's inside strands-agents-sops

  1. What is EvalKit?

    main
    EvalKit is a conversational evaluation framework designed for AI agents. It uses the Strands Evals SDK to guide users through a structured lifecycle of creating robust evaluations. The framework allows you to plan evaluations, generate test data, execute evaluations, and analyze results through natural language conversation.

  2. What is an Agent SOP?

    main

    An Agent SOP (Standard Operating Procedure) is a standardized markdown file with the .sop.md extension. It is designed to guide AI agents through complex, multi-step workflows using natural language, parameterized inputs, and RFC 2119 constraints.

    Key components include:

    • Clear objectives: Detailed overviews of the workflow.
    • Parameterized inputs: Flexible inputs for customization.
    • Step-by-step instructions: Sequential tasks using RFC 2119 keywords (MUST, SHOULD, MAY) for precise control.
    • Resumability: Documentation of progress to allow agents to resume interrupted tasks.
    • Multi-modal distribution: Can be used via MCP tools, Agent Skills, or Python modules.

  3. What are Agent SOPs?

    main

    Agent SOPs are standardized markdown workflows designed for AI agents. They feature:

    • Structured steps with RFC 2119 constraints: Uses keywords like MUST, SHOULD, and MAY for precise behavior control.
    • Parameterized inputs: Uses parameters instead of hardcoded values to allow flexible application across different projects.
    • AI-assisted authoring: Designed to be easily read and generated by coding agents.
    • Progress tracking: Includes instructions for agents to document progress, enabling resumability and debugging.

  4. Use the Code Assist SOP for TDD-based implementation

    main

    The Code Assist SOP is a workflow designed for implementing code tasks using Test-Driven Development (TDD) principles. It follows a structured four-phase lifecycle: Explore, Plan, Code, and Commit.

    In this workflow, the agent acts as a 'Technical Implementation Partner' and 'TDD Coach', providing guidance, generating test cases, and producing idiomatic code that adheres to existing repository patterns.

    Workflow Phases

    1. Explore Phase: Understanding requirements and context.
    2. Plan Phase: Creating documentation and architectural decisions.
    3. Code Phase: Writing tests and implementation code.
    4. Commit Phase: Finalizing the task.

  5. Understand the .agents directory structure

    main

    The Prompt-Driven Development (PDD) family of SOPs (codebase-summary, pdd, code-task-generator, code-assist) organizes artifacts in a .agents/ directory. This structure helps distinguish between permanent documentation and transient working files.

    • .agents/summary/: Output from codebase-summary. Always commit.
    • .agents/planning/: Design docs from pdd. Often worth committing.
    • .agents/tasks/: Task breakdowns from code-task-generator. Optionally commit.
    • .agents/scratchpad/: Working files from code-assist. Add to .gitignore.

  6. Generate tasks in PDD mode

    main

    When processing a PDD plan, the generator follows a specific organizational pattern:

    1. Folder Structure: It creates a folder named step{NN} where NN is zero-padded (e.g., step01, step02).
    2. File Naming: Inside the step folder, it creates sequential files named task-01-{title}.code-task.md, task-02-{title}.code-task.md, etc.
    3. Content Logic:
      • It breaks steps into functional implementation phases (not separate testing tasks).
      • It includes a Reference Documentation section pointing to design/detailed-design.md.
      • It includes unit test requirements directly within the Acceptance Criteria of the implementation tasks rather than creating separate test tasks.
    4. Workflow: After generation, the user is advised to run code-assist on each generated task in the specified sequence.

  7. Understand the EvalKit workflow and phases

    main

    EvalKit follows a structured, four-phase lifecycle to evaluate an agent. Each phase depends on the successful completion of the previous one. The workflow is designed to keep evaluation artifacts separate from your agent's core code by placing them in an eval/ directory sibling to your agent folder.

    Phase Dependencies:

    1. Planning Phase: Defines metrics and scenarios. No prerequisites.
    2. Data Generation Phase: Creates test cases. Requires an evaluation plan (eval/eval-plan.md).
    3. Evaluation Execution Phase: Runs the actual tests. Requires test cases (eval/test-cases.jsonl).
    4. Reporting Phase: Analyzes results. Requires evaluation outputs (eval/results/).
    Phase 1: Planning (eval-plan.md)
Phase 2: Data Generation (test-cases.jsonl)
Phase 3: Evaluation Execution (run_evaluation.py)
Phase 4: Analysis (eval-report.md)

  8. Understand the Codebase Summary Output Structure

    main

    When running the Codebase Summary SOP, the output is organized into a root consolidated file and a detailed directory of documentation artifacts.

    Consolidated File:

    • AGENTS.md (or the file specified in consolidate_targets) located in the root directory.

    Artifact Directory (.agents/summary/):

    • index.md: Knowledge base index.
    • codebase_info.md: High-level codebase information.
    • architecture.md: Architectural overview (often includes Mermaid diagrams).
    • components.md: Component details.
    • interfaces.md: Key interfaces.
    • data_models.md: Data structures and models.
    • workflows.md: System workflows.
    • dependencies.md: Project dependencies.
    • review_notes.md: Notes on consistency and completeness checks.
    AGENTS.md (consolidated file in root directory)
.agents/summary/
├── index.md (knowledge base index)
├── codebase_info.md
├── architecture.md
├── components.md
├── interfaces.md
├── data_models.md
├── workflows.md
├── dependencies.md
└── review_notes.md

  9. Understand the Codebase Summary workflow

    main

    The Codebase Summary SOP follows a structured multi-step process to transform raw code into a documentation ecosystem:

    1. Setup: Validates the codebase_path and initializes the output_dir with necessary subdirectories.
    2. Analyze: Identifies packages, modules, architectural patterns, technology stacks, and dependencies. It creates a hierarchical map using Mermaid diagrams and documents basic info in {output_dir}/codebase_info.md.
    3. Generate: Creates a detailed knowledge base in the output_dir, including:
      • index.md: The primary entry point for AI assistants, containing instructions, metadata, and a table of contents.
      • architecture.md: System design and patterns.
      • components.md: Major components and responsibilities.
      • interfaces.md: APIs and integration points.
      • data_models.md: Data structures.
      • workflows.md: Key processes.
      • dependencies.md: External dependencies.
    4. Review: Checks for inconsistencies and completeness, documenting gaps in {output_dir}/review_notes.md.
    5. Consolidate: If enabled, merges documentation into root-level files like AGENTS.md, README.md, or CONTRIBUTING.md.
    6. Summary: Provides a report of accomplishments and instructions for using the documentation with AI assistants.

  10. Configure and load external SOPs

    main

    You can extend the library with your own Standard Operating Procedures.

    Requirements

    • File Extension: Files must have the .sop.md postfix to be recognized.
    • Format: Standard Markdown structure (e.g., using # Overview and ## Steps headers).

    Path Configuration

    When using --sop-paths in MCP or Skills commands, you can provide multiple paths using colon-separated values. The system supports ~ for home directory expansion and relative paths.

    Precedence

    External SOPs follow a first-wins rule: if an external SOP has the same name as a built-in SOP, the external one is used.

    # Example: Creating a custom SOP file
mkdir ~/my-sops
cat > ~/my-sops/custom-workflow.sop.md << 'EOF'
# Custom Workflow
## Overview
My custom workflow for specific tasks.
## Steps
### 1. Custom Step
Do something custom.
EOF

  11. Choose between Interactive and Auto modes

    main

    The mode parameter determines how the agent interacts with you during the implementation process.

    Interactive Mode (mode: "interactive")

    Best for collaborative tasks where you want control over the implementation details. The agent will:

    • Present proposed actions and ask for confirmation.
    • Explain pros/cons when multiple approaches exist.
    • Review artifacts and solicit feedback before moving forward.
    • Pause at key decision points to explain reasoning.
    • Provide educational context for new patterns.

    Auto Mode (mode: "auto")

    Best for autonomous execution of well-defined tasks. The agent will:

    • Execute all actions without user confirmation.
    • Document all decisions, assumptions, and reasoning in progress.md.
    • Select the most appropriate approach when multiple exist and document the rationale.
    • Provide a comprehensive summary upon completion.

    Warning: If you select auto mode, the agent will warn you that no further interaction will be required after the initial setup.

  12. Refine requirements using the Idea Honing process

    main

    The Requirements Clarification phase uses an interactive process to build a specification in {project_dir}/idea-honing.md.

    How it works:

    • The agent asks exactly one question at a time.
    • It waits for your response before proceeding.
    • It records both the question and your final answer in idea-honing.md.
    • It may suggest possible answers or options if you are unsure.
    • The process continues until you explicitly confirm that the requirements are complete.

    Tip: You can request to pause requirements clarification to conduct research if a question arises that requires more technical information.