SpecOps Agents File

This repository provides a sample agents instruction file for projects that follow the SpecOps methodology. The goal is to make AI agents operate in a specification-driven workflow where the specification is the source of truth and all code changes trace back to documented, verified requirements.

Overview

• Purpose: Equip AI agents with clear, enforceable instructions that prioritize specifications over code.
• Core principle: The specification is the source of truth; code implements the spec.
• Audience: Teams modernizing systems with AI assistance while maintaining rigorous governance and traceability.

SpecOps Methodology (Essentials)

• Specification First: Agents read and defer to specs in specifications/ before making or reviewing code changes.
• No Undocumented Behavior: If behavior isn’t covered by a spec, draft a spec update and request human verification.
• Human Verification: Domain experts review specs (plain language), not implementation details.
• Flag Ambiguity: Agents stop and request clarification when requirements are unclear, contradictory, or incomplete.
• Preserve Knowledge: Extract implicit business rules found in legacy code into specs for human review.

Using AGENTS.md

The file AGENTS.md encodes operating instructions for AI agents:

• Workflow: Read specs first, propose spec changes before code changes, and implement only documented behavior.
• Review Protocol: Specs must be verified by domain experts; agents flag gaps and contradictions.
• Specification Format: Includes Purpose, Requirements with Acceptance Criteria, Edge Cases, and References.
• Legacy Extraction: Guidance for converting business logic from existing code into verifiable specifications.
• Project Integration: Notes on CI/CD hooks (e.g., GitHub Action) to enforce spec-first changes.

Recommended Workflow for Agents

• Locate Spec: Identify the governing spec for any change under specifications/.
• Validate Coverage: Ensure the spec defines the required behavior and acceptance criteria.
• Draft Spec Changes: If missing, write a spec update draft and label it for human review.
• Implement Precisely: Map implementation to spec requirements, terminology, and acceptance criteria.
• Verify: Confirm behavior matches all acceptance criteria; document any decisions or spec gaps.

CI/CD Integration

Use automation to enforce spec-first development. For example, with the SpecOps GitHub action.

name: Create Issues for Spec Changes

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read
  issues: write

jobs:
  spec-change-issues:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Need history for diff
      
      - uses: spec-ops-method/spec-ops-action@v1

This creates issues when specification files change, ensuring spec updates generate trackable work items and implementation proceeds from documented requirements.

References

• SpecOps Methodology site: https://spec-ops.ai
• Agents guidance: https://spec-ops.ai/llms.txt
• SpecOps Repository: https://github.com/mheadd/spec-ops
• GitHub spec-kit: https://github.com/github/spec-kit
• Contributing Guide: CONTRIBUTING.md
• License: LICENSE (MIT)
• PR Template: .github/pull_request_template.md

Getting Started

• Add your specifications under specifications/ following the format in AGENTS.md.
• Configure CI to track spec changes and enforce spec references in implementation PRs.
• Instruct AI agents to follow AGENTS.md and stop when specs are unclear, asking for human review.
• See example spec: specifications/sample-feature.md.