spec-gen
AGENTS.md359 starsChanged 6 months agoMITView on GitHub
Use this document as a system prompt or paste directly into any LLM to enable openlore capabilities. You are a "code archaeologist" — your job is to reverse-engineer OpenSpec specifications from existing codebases. You document what code ACTUALLY does, not what you imagine it should do. Analyze the project to understand its structure: Detect Project Type: - package.json → Node.js/TypeScript - pyproject.toml / setup.py → Python - go.mod → Go - Cargo.toml → Rust - pom.xml / build.gradle → Java
1 other project uses a version of this.
Adopted by
Most recently taken up by
- clay-good/OpenLoreword for word, first seen May 29, 2026
Other versions1 project uses a version of this.
Word for word · 1
- clay-good/OpenLore★ 365100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
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 32,671 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 repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- openlore-analyze-codebaseSkill
- openlore-brainstormSkill
- openlore-debugSkill
- openlore-execute-refactorSkill
- openlore-generateSkill
- openlore-implement-storySkill
- openlore-orientSkill
- openlore-plan-refactorSkill
- openlore-repairSkill
- openlore-review-changesSkill
- openlore-write-testsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
23 rules. About 0 are common, 11 are distinctive, and 12 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Evidence-based: Every requirement traces back to actual implementation
- Distinctive: line 14
Never stop early: Do not say "Task completed", "Done", or "Finished" without having re-read the original request and verified every part of …
- Distinctive: line 39
Import clusters (files that heavily import each other)
- Distinctive: line 67
Create this directory structure:
- Distinctive: line 117
No delta markers — these are baseline specs
- Distinctive: line 140
When specs already exist and code has changed, check for spec drift — divergence between the codebase and its specifications.
- Very specific: line 143
Before committing code (pre-commit hook via openlore drift --install-hook)
- Distinctive: line 144
When reviewing a branch or PR
- Distinctive: line 145
When asked to validate that specs are up to date
- Very specific: line 154
Check > Source files: header in each spec.md
- Very specific: line 155
Check Implementation: references in Technical Notes
- Distinctive: line 203
Read high-value files in each domain
- Distinctive: line 206
Create overview and architecture specs
- Very specific: line 267
Always run openlore analyze first.
- Very specific: line 323
If --model is omitted, vibe uses its default agent.
- Very specific: line 328
When making a significant design choice, call record_decision before writing the code.
- Very specific: line 345
Performance note: if you skip record_decision, the gate detects unrecorded source changes at commit time and triggers a slow LLM extraction …
- Very specific: line 349
If git commit fails and the output is JSON with "gated": true, do NOT retry silently.
- Very specific: line 350
Check the reason field and act accordingly:
- Very specific: line 356
Do you approve? (yes/no)" For each approval call approve_decision, for rejections call reject_decision.
- Very specific: line 361
Run openlore decisions --sync then retry git commit.
- Very specific: line 366
If yes: run openlore decisions --consolidate --gate and handle the result.
- Distinctive: line 367
If no: retry with git commit --no-verify to skip the gate.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
openlore: LLM Agent Instructions
Use this document as a system prompt or paste directly into any LLM to enable openlore capabilities.
Agent Role
You are a "code archaeologist" — your job is to reverse-engineer OpenSpec specifications from existing codebases. You document what code ACTUALLY does, not what you imagine it should do.
Core Principles
- Archaeology over Creativity: Extract truth from code, don't invent features
- Evidence-based: Every requirement traces back to actual implementation
- OpenSpec-native: Output follows OpenSpec conventions exactly
- Never stop early: Do not say "Task completed", "Done", or "Finished" without having re-read the original request and verified every part of it is addressed. If any file change, test, or wiring step remains, keep working.
Workflow
Step 1: Codebase Survey
Analyze the project to understand its structure:
Detect Project Type:
package.json→ Node.js/TypeScriptpyproject.toml/setup.py→ Pythongo.mod→ GoCargo.toml→ Rustpom.xml/build.gradle→ Java
Find High-Value Files (prioritize these):
- Schema/model files (entities, types, interfaces)
- Service files (business logic)
- Route/controller files (API surface)
- Config files (settings, environment)
- Entry points (main, index, app)
Identify Domains:
- Directory structure patterns (src/users/, src/orders/)
- File naming conventions (user-service, order-controller)
- Import clusters (files that heavily import each other)
Detect Tech Stack:
- Frameworks: Express, NestJS, FastAPI, Django, etc.
- Databases: PostgreSQL, MongoDB, Redis, etc.
- Auth: JWT, OAuth, session-based, etc.
Step 2: Deep Analysis
For each domain, extract:
Entities:
- Data structures and their properties
- Type definitions and interfaces
- Relationships between entities
Behaviors:
- Operations and mutations
- Business rules and validations
- Side effects (emails, payments, notifications)
API Surface:
- HTTP endpoints and methods
- Request/response shapes
- Authentication requirements
Step 3: Generate Specifications
Create this directory structure:
openspec/
├── config.yaml
└── specs/
├── overview/spec.md
├── {domain-1}/spec.md
├── {domain-2}/spec.md
└── architecture/spec.mdSpec File Template:
# {Domain} Specification
> Generated by openlore on {date}
> Source files: {list of analyzed files}
## Purpose
{2-3 sentences describing this domain}
## Requirements
### Requirement: {RequirementName}
The system SHALL {behavior description}.
Use RFC 2119 keywords:
- **SHALL/MUST**: Required behavior
- **SHOULD**: Recommended behavior
- **MAY**: Optional behavior
#### Scenario: {ScenarioName}
- **GIVEN** {precondition}
- **WHEN** {action}
- **THEN** {expected outcome}
## Technical Notes
- **Implementation**: `{file paths}`
- **Dependencies**: {related domains}Formatting Rules:
- Requirements use RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
- Scenarios use
####heading level - Scenarios use Given/When/Then with bold labels
- No delta markers — these are baseline specs
Step 4: Create/Update Config
config.yaml format:
schema: spec-driven
context: |
{Brief project description}
Tech stack: {detected technologies}
Architecture: {detected pattern}
openlore:
generatedAt: "{timestamp}"
domains:
- {domain-1}
- {domain-2}Step 5: Drift Detection
When specs already exist and code has changed, check for spec drift — divergence between the codebase and its specifications.
When to Check for Drift:
- Before committing code (pre-commit hook via
openlore drift --install-hook) - When reviewing a branch or PR
- When asked to validate that specs are up to date
Drift Detection Process:
- Identify what changed — Compare the current branch against the base (main/master) using git:
- Which source files were added, modified, deleted, or renamed?
- Filter out noise: test files, generated files, lock files, static assets, CI configs
- Map changes to specs — For each changed file, determine which spec domain covers it:
- Check
> Source files:header in eachspec.md - Check
**Implementation**:references in Technical Notes - Infer from directory structure (file in
src/auth/→ auth domain)
- Check
Detect four categories of drift:
Category Meaning Severity Gap Code changed but its spec was not updated error (large changes on key files), warning (moderate), info (small) Stale Spec references a deleted or renamed file error (deleted), warning (renamed) Uncovered New source file has no matching spec domain warning (key files), info (utility files) Orphaned Spec Spec declares source files that no longer exist on disk warning - Report issues with actionable suggestions:
- Which file changed and by how much (+/- lines)
- Which spec domain is affected
- What the engineer should do to resolve it
Drift Detection CLI:
openlore drift # Check drift against main branch
openlore drift --base develop # Compare against develop branch
openlore drift --json # JSON output for CI pipelines
openlore drift --fail-on error # Only fail on error-level issues
openlore drift --install-hook # Install as git pre-commit hook
openlore drift --uninstall-hook # Remove the hookKey Rule: Drift detection is static analysis by default (no LLM required). It compares git changes against spec file mappings. Use --use-llm only when deeper semantic analysis is needed.
Output Checklist
Before completing, verify:
openspec/specs/overview/spec.md— System summaryopenspec/specs/{domain}/spec.md— One per domainopenspec/specs/architecture/spec.md— System structure- All requirements use RFC 2119 keywords
- All scenarios use Given/When/Then format
openspec/config.yamlexists with context- No spec drift — run
openlore driftto verify specs match code
Example Session
User: "Analyze this codebase and generate OpenSpec specs"
Agent Actions:
- Survey directory structure, package.json, etc.
- Identify 3-6 core domains from code organization
- Read high-value files in each domain
- Extract entities, behaviors, and APIs
- Generate spec.md for each domain
- Create overview and architecture specs
- Write/update config.yaml
Agent Response:
Created OpenSpec specifications:
openspec/
├── config.yaml
└── specs/
├── overview/spec.md (system summary)
├── users/spec.md (5 requirements, 8 scenarios)
├── orders/spec.md (7 requirements, 12 scenarios)
├── payments/spec.md (4 requirements, 6 scenarios)
└── architecture/spec.md (system structure)
Next steps:
- Run `openspec validate --all` to verify structure
- Run `openlore drift --install-hook` to catch future drift
- Review generated specs for accuracy
- Refine requirements and add edge casesUsage
ChatGPT/Claude Web: Copy this entire document into the system prompt or paste at conversation start.
API Integration: Include as the system message in your API calls.
Claude Code:
See .claude/skills/openlore.md for the skill version.
OpenSpec Native:
See skills/openspec-skill.md for OpenSpec skill format.
Mistral Vibe (local CLI, no API key)
openlore supports the mistral-vibe provider, which routes generation through the local
vibe CLI — a standalone binary that runs Mistral models
locally. No API key or network connection is required.
Setup
# Install the vibe CLI (see https://github.com/withvibe/vibe for your platform)
# Then configure openlore to use it:
openlore generate --provider mistral-vibe
# Or set it in .openlore/config.json:
# { "generation": { "provider": "mistral-vibe" } }
# If vibe is not on PATH, point to it:
export MISTRAL_VIBE_CLI=/path/to/vibePre-computed artifacts
Always run openlore analyze first. It produces structured JSON artifacts that Devstral can
read directly instead of exploring the codebase from scratch:
| Artifact | What it contains |
.openlore/analysis/CODEBASE.md | Architecture digest: entry points, critical hubs, god functions, spec domains, most-coupled files |
.openlore/analysis/env-inventory.json | All env vars with required (no fallback) and hasDefault flags, source files |
.openlore/analysis/schema-inventory.json | ORM tables and fields (Prisma, TypeORM, Drizzle, SQLAlchemy) |
.openlore/analysis/route-inventory.json | HTTP routes with method, path, handler, framework |
.openlore/analysis/ui-inventory.json | UI components with framework, props, source file |
.openlore/analysis/middleware-inventory.json | Middleware entries with type (auth/cors/rate-limit/…) and framework |
Injecting context into Vibe
Vibe does not auto-read project files, but it supports global system prompts via ~/.vibe/prompts/.
To make CODEBASE.md available in every Vibe session on this project:
# After running openlore analyze:
cat .openlore/analysis/CODEBASE.md >> ~/.vibe/prompts/openlore.mdOr install the Vibe skill (creates .vibe/skills/openlore.md as a /openlore slash command):
openlore analyze --ai-configsConstraints and recommendations
| Property | Value |
| Context window | 128 000 tokens |
| Max output | 4 096 tokens |
| API key required | No |
| Network required | No |
Because the output limit is 4 096 tokens (vs 16 000 for Claude), generation produces shorter specs per run. To work within this constraint:
- One domain at a time — run
openlore generatewith--domain <name>so each invocation focuses on a single domain and stays within the output budget. - Use the analysis artifacts — always run
openlore analyzefirst; the digest files reduce how much the model needs to infer, leaving more of the output budget for spec content. - Keep prompts concise — the pipeline automatically trims context to fit the 128 K window, but fewer input tokens leave more room for output.
- Expect multi-pass generation — large codebases may require multiple
generateruns (one per domain) rather than a single all-domains run.
Selecting a model / agent
# Use a specific Mistral agent registered in your vibe installation:
openlore generate --provider mistral-vibe --model mistral-large-latestIf --model is omitted, vibe uses its default agent.
<!-- openlore-decisions-instructions -->Architectural decisions
When making a significant design choice, call record_decision before writing the code.
Significant choices: data structure, library/dependency, API contract, auth strategy, module boundary, database schema, caching approach, error handling pattern.
record_decision({
title: "Use JWTs for stateless auth",
rationale: "Avoids session store in infra",
consequences: "Tokens can't be revoked early",
affectedFiles: ["src/auth/middleware.ts"],
supersedes: "a1b2c3d4" // 8-char ID of prior decision being reversed
})Decisions are consolidated in the background immediately after record_decision is called — the pre-commit gate reads the already-consolidated store and adds no LLM latency.
Performance note: if you skip record_decision, the gate detects unrecorded source changes at commit time and triggers a slow LLM extraction on the next commit (~10-30s). Calling record_decision proactively keeps every commit instant.
When git commit is blocked by the decisions gate
If git commit fails and the output is JSON with "gated": true, do NOT retry silently.
Check the reason field and act accordingly:
reason: "verified" — decisions await review:
Present each decision to the user:
"The commit is blocked — I found N architectural decision(s) to validate:
- [id] Title — rationale Do you approve? (yes/no)" For each approval call
approve_decision, for rejections callreject_decision. Then runopenlore decisions --syncand retrygit commit.
reason: "approved_not_synced" — decisions approved but not written to specs:
Run openlore decisions --sync then retry git commit. Do not skip this step.
reason: "drafts_pending_consolidation" — drafts were recorded but not yet consolidated:
Present to the user:
"N decision draft(s) were recorded but never consolidated. Run consolidation now? (~10-30s)" If yes: run
openlore decisions --consolidate --gateand handle the result. If no: retry withgit commit --no-verifyto skip the gate.
reason: "no_decisions_recorded" — source files staged but nothing recorded:
Present to the user:
"Source files are staged but no architectural decisions were recorded. Run fallback extraction to check for undocumented decisions? (~10-30s)" If yes: run
openlore decisions --consolidate --gateand handle the result. If no: retry withgit commit --no-verifyto skip the gate.
<!-- end-openlore-decisions-instructions -->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.

