Skip to content

Commit f57edea

Browse files
mheaddmheadd
committed
Add llms.txt file
1 parent b1fac4f commit f57edea

File tree

1 file changed

+143
-0
lines changed

1 file changed

+143
-0
lines changed

‎docs/llms.txt‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# SpecOps: Specification-Driven Legacy System Modernization
2+
3+
> Project URL: https://spec-ops.ai
4+
> Repository: https://github.com/mheadd/spec-ops
5+
> License: MIT
6+
7+
## Overview
8+
9+
SpecOps is a methodology for using AI to modernize legacy government systems by focusing on knowledge preservation and verified specifications rather than direct code translation. It builds on specification-driven development and GitOps principles to create a sustainable approach to legacy modernization.
10+
11+
## Core Concept
12+
13+
Traditional AI-assisted modernization tries to transpile legacy code directly into modern languages. SpecOps uses AI to compile institutional knowledge into comprehensive, human-verified software specifications that become the authoritative source of truth for system behavior.
14+
15+
**Key Principle**: The specification is more valuable than the code. It captures institutional knowledge, enables domain expert verification, and outlasts any particular technical implementation.
16+
17+
## The Problem
18+
19+
Governments struggle to upgrade and maintain legacy systems. Typical modernization approaches focus on converting old code into new code, but that misses something fundamental. More important than updated software code is comprehensive, human-readable documentation on how a system is supposed to work.
20+
21+
## The SpecOps Solution
22+
23+
Use AI to develop comprehensive software specifications that become the authoritative source of truth for system behavior. Rather than just translating COBOL to Java, SpecOps captures and verifies institutional knowledge in plain language that domain experts can review and approve.
24+
25+
## Built on Two Key Principles
26+
27+
1. **Specification-Driven Development** – The specification precedes and governs all implementation. Once the legacy system's behavior is captured in a verified specification, AI coding agents use that specification to generate modern implementations—transforming documented knowledge into working code.
28+
29+
2. **GitOps Thinking** – Like GitOps treats Git repositories as the single source of truth for infrastructure, SpecOps treats version-controlled specifications as the authoritative source of truth for system behavior. All future changes start with the specification—update the spec first, then update the code.
30+
31+
## How It Works
32+
33+
1. AI analyzes legacy systems and generates specifications in plain language
34+
2. Domain experts—policy makers, program administrators, business stakeholders—verify these specifications before any modern code is written
35+
3. Once verified, the specification becomes the source of truth that guides implementation and future changes
36+
4. All changes flow through the specification first, ensuring proper review and approval
37+
38+
**Result**: Preserved institutional knowledge, reduced risk, and a foundation that outlasts any particular technology stack.
39+
40+
## Core Principles
41+
42+
1. **The Specification is the Source of Truth** - Like GitOps treats Git as authoritative for infrastructure, SpecOps treats specifications as authoritative for system behavior
43+
44+
2. **Knowledge Preservation Precedes Translation** - Capture and verify what the system does before building replacements
45+
46+
3. **Domain Experts Are the Arbiters** - Policy and business stakeholders verify specifications, not code
47+
48+
4. **AI Assists, Humans Verify** - AI excels at analysis and generation; humans excel at judgment and verification
49+
50+
5. **Changes Flow Through Specifications** - All modifications start with specification updates, reviewed and approved before implementation
51+
52+
6. **Specifications Should Be Accessible** - Readable by domain experts while detailed enough to guide implementation
53+
54+
## Key Benefits
55+
56+
### For Government Agencies
57+
- **Knowledge Preservation**: Capture institutional knowledge before experts retire
58+
- **Risk Reduction**: Domain experts verify behavior before code is written
59+
- **Better Outcomes**: Specifications ensure modern systems implement policy correctly
60+
- **Sustainable Modernization**: Incremental approach via Strangler Fig pattern
61+
62+
### For Technology Teams
63+
- **AI as Force Multiplier**: AI handles tedious legacy code analysis and generates code from specifications
64+
- **Clear Success Criteria**: Specifications define when implementations are "correct"
65+
- **Reusable Knowledge**: Instruction sets can be shared across projects
66+
67+
## Six Phase Methodology
68+
69+
1. **Discovery and Assessment** - Understand the legacy system and plan the modernization approach
70+
2. **Specification Generation** - Use AI agents to create initial specifications from legacy code
71+
3. **Specification Verification** - Domain experts review and validate specifications
72+
4. **Modern Implementation** - Generate new code from verified specifications
73+
5. **Testing and Validation** - Verify the implementation matches the specification
74+
6. **Deployment and Knowledge Transfer** - Move to production and preserve institutional knowledge
75+
76+
## When to Use SpecOps
77+
78+
**Particularly effective when:**
79+
- Legacy system is poorly documented
80+
- Institutional knowledge is at risk of being lost
81+
- Business logic is complex and critical to get right
82+
- Domain experts are available but can't verify code
83+
- Long-term knowledge preservation is valuable
84+
- Incremental modernization over years is expected
85+
- System behavior must be auditable and explainable
86+
87+
**May not be necessary when:**
88+
- Legacy system is well-understood and well-documented
89+
- Business logic is simple and stable
90+
- Speed is prioritized over accuracy
91+
- Comprehensive test coverage already exists
92+
93+
## Documentation
94+
95+
- **Manifesto**: Foundational principles and philosophy
96+
- **Comparison Framework**: SpecOps vs. direct translation across 11 dimensions
97+
- **Core Tools**: Technical infrastructure needed (repos, AI agents, verification tools)
98+
- **Methodology**: Step-by-step guide through all six phases
99+
- **Team Structure**: Roles, responsibilities, and staffing guidance (8-18 people)
100+
- **Instruction Sets**: Guide to creating and sharing AI agent instruction sets
101+
- **Reference Implementation**: (In Development) Complete working example
102+
103+
## Related Projects
104+
105+
- **GitHub spec-kit**: https://github.com/github/spec-kit - Foundational toolkit for specification-driven development with AI
106+
- **GitOps**: Infrastructure as code methodology that inspired SpecOps' approach to source of truth
107+
- **Strangler Fig Pattern**: Incremental modernization pattern integrated into SpecOps methodology
108+
109+
## Community
110+
111+
SpecOps is designed to enable collaboration across government agencies and the civic tech community. Instruction sets and patterns are highly portable across organizations. A COBOL comprehension skill works whether you're modernizing benefits in California or taxes in New York.
112+
113+
## Contributing
114+
115+
We welcome contributions of:
116+
- Instruction Sets: AI agent skills for legacy platforms, languages, or domains
117+
- Experience Reports: Lessons learned from applying SpecOps
118+
- Tool Integrations: How to use SpecOps with different AI coding tools
119+
- Templates and Examples: Reusable artifacts for specifications and processes
120+
- Documentation Improvements: Clarifications, corrections, and enhancements
121+
122+
See CONTRIBUTING.md for detailed guidelines.
123+
124+
## Key Terminology
125+
126+
- **Specification**: Comprehensive, human-readable documentation of system behavior that serves as the source of truth
127+
- **Specification-Driven Development**: Software development approach where specifications precede and govern implementation
128+
- **Transpilation**: Direct conversion of source code from one language to another (what SpecOps moves beyond)
129+
- **Compilation**: Bringing together authoritative information (how SpecOps uses AI to create specifications)
130+
- **Instruction Sets/Skills**: AI agent guidance for understanding legacy code and generating specifications
131+
- **Domain Experts**: Policy makers, program administrators, and business stakeholders who understand system requirements
132+
- **GitOps Thinking**: Using version-controlled repositories as single source of truth
133+
- **Strangler Fig Pattern**: Incremental replacement of legacy system components
134+
135+
## Contact
136+
137+
- GitHub Repository: https://github.com/mheadd/spec-ops
138+
- GitHub Discussions: https://github.com/mheadd/spec-ops/discussions
139+
- Website: https://spec-ops.ai
140+
141+
## Tagline
142+
143+
**SpecOps: Because the knowledge is what matters. Everything else is implementation details.**

0 commit comments

Comments
 (0)