agentleFS
muyenmuyen/vibe-to-prod/openspec/AGENTS.md

vibe-to-prod / openspec

AGENTS.md34 starsChanged 11 months agoMITView on GitHub

Instructions for AI coding assistants using OpenSpec for spec-driven development. Create proposal when you need to: - Add features or functionality - Make breaking changes (API, schema) - Change architecture or patterns - Optimize performance (changes behavior) - Update security patterns Skip proposal for: - Bug fixes (restore intended behavior) - Typos, formatting, comments - Dependency updates (non-breaking) - Configuration changes - Tests for existing behavior Workflow 1. Review openspec/project.md and openspec list to understand current context 2. Choose a…

The file

We split this AGENTS.md into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Search existing work: openspec list, openspec spec list

    line 7
  2. Very specific:

    Write deltas: use ## ADDED|MODIFIED|REMOVED Requirements

    line 11
  3. Distinctive:

    Create proposal when you need to:

    line 19
  4. Distinctive:

    Add features or functionality

    line 20
  5. Very specific:

    Confirm completion: - Ensure every item in tasks.md is finished

    line 46
  6. Distinctive:

    Approval gate: - Do not start implementation until approved

    line 48
  7. Very specific:

    Update specs/ if capabilities changed

    line 54
  8. Distinctive:

    Default to <100 lines of new code

    line 126
  9. Distinctive:

    Avoid frameworks without clear justification

    line 128
  10. Very specific:

    Use file.ts:42 format for code locations

    line 131
  11. Very specific:

    Use verb-noun: user-auth, api-endpoints

    line 135

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

OpenSpec Instructions

Instructions for AI coding assistants using OpenSpec for spec-driven development.

TL;DR Quick Checklist

  • Search existing work: openspec list, openspec spec list
  • Decide scope: new capability vs modify existing capability
  • Pick a unique change-id: kebab-case, verb-led (add-, update-, remove-, refactor-)
  • Scaffold: proposal.md, tasks.md, design.md (only if needed), and delta specs
  • Write deltas: use ## ADDED|MODIFIED|REMOVED Requirements
  • Validate before requesting approval
  • Request approval: Do not start implementation until proposal is approved

Three-Stage Workflow

Stage 1: Creating Changes

Create proposal when you need to:

  • Add features or functionality
  • Make breaking changes (API, schema)
  • Change architecture or patterns
  • Optimize performance (changes behavior)
  • Update security patterns

Skip proposal for:

  • Bug fixes (restore intended behavior)
  • Typos, formatting, comments
  • Dependency updates (non-breaking)
  • Configuration changes
  • Tests for existing behavior

Workflow

  1. Review openspec/project.md and openspec list to understand current context
  2. Choose a unique verb-led change-id and scaffold files under openspec/changes/<id>/
  3. Draft spec deltas using ## ADDED|MODIFIED|REMOVED Requirements
  4. Validate and resolve issues before sharing

Stage 2: Implementing Changes

Track these steps as TODOs and complete them one by one:

  1. Read proposal.md - Understand what's being built
  2. Read design.md (if exists) - Review technical decisions
  3. Read tasks.md - Get implementation checklist
  4. Implement tasks sequentially - Complete in order
  5. Confirm completion - Ensure every item in tasks.md is finished
  6. Update checklist - Set every task to - [x]
  7. Approval gate - Do not start implementation until approved

Stage 3: Archiving Changes

After deployment:

  • Move changes/[name]/ → changes/archive/YYYY-MM-DD-[name]/
  • Update specs/ if capabilities changed

Directory Structure

openspec/
├── project.md              # Project conventions
├── AGENTS.md               # This file - AI instructions
├── specs/                  # Current truth - what IS built
│   └── [capability]/
│       └── spec.md         # Requirements and scenarios
├── changes/                # Proposals - what SHOULD change
│   ├── [change-name]/
│   │   ├── proposal.md     # Why, what, impact
│   │   ├── tasks.md        # Implementation checklist
│   │   └── specs/          # Delta changes
│   └── archive/            # Completed changes

Creating Change Proposals

Proposal Structure

  1. Create directory: changes/[change-id]/
  2. Write proposal.md:
# Change: [Brief description]

## Why
[1-2 sentences on problem/opportunity]

## What Changes
- [Bullet list of changes]
- [Mark breaking changes with **BREAKING**]

## Impact
- Affected specs: [list capabilities]
- Affected code: [key files/systems]
  1. Create tasks.md:
## 1. Implementation
- [ ] 1.1 Task description
- [ ] 1.2 Task description
  1. Create design.md when needed (cross-cutting changes, new dependencies, security/performance concerns)

Spec File Format

Requirements with Scenarios

### Requirement: Feature Name
The system SHALL provide...

#### Scenario: Success case
- **WHEN** user performs action
- **THEN** expected result

Delta Operations

  • ## ADDED Requirements - New capabilities
  • ## MODIFIED Requirements - Changed behavior
  • ## REMOVED Requirements - Deprecated features

Best Practices

Simplicity First

  • Default to <100 lines of new code
  • Single-file implementations until proven insufficient
  • Avoid frameworks without clear justification

Clear References

  • Use file.ts:42 format for code locations
  • Reference specs as specs/[capability]/spec.md

Capability Naming

  • Use verb-noun: user-auth, api-endpoints
  • Single purpose per capability
  • Split if description needs "AND"

Quick Reference

CLI Commands (if available)

openspec list              # What's in progress?
openspec show [item]       # View details
openspec validate          # Is it correct?
openspec archive [id]      # Mark complete

Stage Indicators

  • changes/ - Proposed, not yet built
  • specs/ - Built and deployed
  • archive/ - Completed changes

Remember: Specs are truth. Changes are proposals. Keep them in sync.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.