Reverse-Spec-Flow AWS released reverse-spec-flow version 2.2.1 under the MIT-0 license, a workflow that generates Markdown specifications for AI agents from source code that has no specifications, outdated ones, or has become a black box. The workflow requires every statement to cite a `path:line` location, has a verifier AI agent isolated from the author check each statement against the source, marks unconfirmable items as `UNKNOWN`, and only counts work complete when the gate script `gates.sh` returns exit 0. The generated specifications carry stable IDs such as `REQ-F-01` with forward and reverse indexes so an agent can look up only what it needs, and progress is written to files and committed to git so work survives context overflow. A workflow that turns existing source code into "AI-friendly specifications" for AI agents to use Version: 2.2.1 https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/release-notes.md / License: MIT-0 日本語版: README ja.md https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/README ja.md The documents under docs/ and the rules the AI agent follows are currently written in Japanese. reverse-spec-flow creates specifications for AI agents to read and use from the source code of an application that has no specifications, has outdated ones, or has become a black box. The output is Markdown that lets an agent look up only the parts it needs, through IDs and indexes. Typical uses of the generated specifications: - Reimagining the application — an AI agent reimagines the application on a new technology stack through spec-driven development, using the specifications as input - Maintaining and evolving the current system — an AI agent consults the specifications to explain how the current system behaves and what a change would affect, supporting maintenance feature additions, specification changes and the planning of refactoring or migration work It is intended for developers and architects who want to use AI agents to reimagine or maintain existing systems. People can read the specifications too, but the main readers are AI agents. The specifications are also written by AI agents. For that reason, reverse-spec-flow puts the highest priority on guaranteeing the following two things by mechanism, not by the agent's self-report. - Every statement cites its evidence — each statement carries the location in the code that supports it path:line . - Verified separately from the author — a verifier AI agent, isolated from the one that wrote the specification, checks each statement against the source code under analysis. It confirms not just that a location is cited, but that the cited lines actually support the statement. - Unknowns are written as unknown — anything that cannot be confirmed from the code is not filled in by guesswork; it is left as UNKNOWN . - Build the list to count against the denominator first — the first step builds a structural map the code graph that lists the modules, entry points and external connections, and how they are connected. - Not complete until the list is used up — the workflow counts whether every element of the code graph has been specified, and the work is not complete until nothing is left. It does not stop at "we looked at the main parts." - The correctness of the list is supported by a counting method suited to the target technology see "Playbooks" below , together with cross-checks against other sources such as configuration files to find anything missed. For both, whether the work is complete is decided not by the agent saying "done," but by whether the gate script gates.sh returns a pass exit 0 . - Easy for AI agents to look up — every specification file and requirement gets a unique, stable ID for example REQ-F-01 . Specifications refer to each other by ID, and the workflow also builds an index from ID to file and a reverse index from source file to specification, so an AI agent can look up only what it needs without reading everything. The rules that an AI agent using the specifications must follow specs/AGENTS.md are included. - Separate layer for reimagining — what depends on the current technology and what any reimagined application would need regardless of technology can be written separately. - Large code bases in parallel — the code is read one business area at a time, so the whole code base never has to be loaded at once. If the AI tool supports sub-agents AI agents that split the work and run in parallel , business areas can be processed in parallel. - Survives context overflow — progress and the next actions are written to files and committed to git. If the agent's context overflows or the session ends, opening a new session resumes from the record. - Lessons carry forward — lessons learned in a project are recorded, and general ones can be fed back into reverse-spec-flow itself see "Documentation" below . - The target is not modified — the rules tell the AI agent not to modify the source code, and gates.sh detects changes to it. Specifications are written to a separate git repository. Analyze a git clone or a copy of the source. Below, products such as Claude Code and Kiro are called AI tools , and the AI that works inside them is called an AI agent . - bash and git macOS / Linux. On Windows, WSL is recommended. Git Bash also works, but the checks take longer - An AI tool see "Supported AI tools" below - The source code you want to analyze No database or dedicated platform is needed. 1. Clone next to the folder you want to analyze for example legacy-order-system/ cd /path/to/workspace legacy-order-system/ is in here git clone https://github.com/aws-samples/sample-reverse-spec-flow.git 2. Create the repository for the specifications init.sh