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…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- code-reviewSkill
- continuous-improvementSkill
- dev-workflowSkill
- git-workflowSkill
- openapi-workflowSkill
- ralph-invokeSkill
- security-scanSkill
- systematic-debuggingSkill
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
- Very specific: line 7
Search existing work: openspec list, openspec spec list
- Very specific: line 11
Write deltas: use ## ADDED|MODIFIED|REMOVED Requirements
- Distinctive: line 19
Create proposal when you need to:
- Distinctive: line 20
Add features or functionality
- Very specific: line 46
Confirm completion: - Ensure every item in tasks.md is finished
- Distinctive: line 48
Approval gate: - Do not start implementation until approved
- Very specific: line 54
Update specs/ if capabilities changed
- Distinctive: line 126
Default to <100 lines of new code
- Distinctive: line 128
Avoid frameworks without clear justification
- Very specific: line 131
Use file.ts:42 format for code locations
- Very specific: line 135
Use verb-noun: user-auth, api-endpoints
≈ “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.
Files
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
- Review
openspec/project.mdandopenspec listto understand current context - Choose a unique verb-led
change-idand scaffold files underopenspec/changes/<id>/ - Draft spec deltas using
## ADDED|MODIFIED|REMOVED Requirements - Validate and resolve issues before sharing
Stage 2: Implementing Changes
Track these steps as TODOs and complete them one by one:
- Read proposal.md - Understand what's being built
- Read design.md (if exists) - Review technical decisions
- Read tasks.md - Get implementation checklist
- Implement tasks sequentially - Complete in order
- Confirm completion - Ensure every item in
tasks.mdis finished - Update checklist - Set every task to
- [x] - 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 changesCreating Change Proposals
Proposal Structure
- Create directory:
changes/[change-id]/ - 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]- Create tasks.md:
## 1. Implementation
- [ ] 1.1 Task description
- [ ] 1.2 Task description- 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 resultDelta 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:42format 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 completeStage Indicators
changes/- Proposed, not yet builtspecs/- Built and deployedarchive/- Completed changes
Remember: Specs are truth. Changes are proposals. Keep them in sync.
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
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.

