{"slug": "reverse-spec-flow", "title": "Reverse-Spec-Flow", "summary": "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.", "body_md": "**A workflow that turns existing source code into \"AI-friendly specifications\" for AI agents to use**\n\nVersion: [2.2.1](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/release-notes.md) / License: MIT-0\n\n日本語版: [README_ja.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/README_ja.md)\n\nThe documents under `docs/` and the rules the AI agent follows are currently written in Japanese.\n\nreverse-spec-flow creates **specifications for AI agents to read and use** from the source code of an application\nthat has no specifications, has outdated ones, or has become a black box. The output is Markdown that lets an agent\nlook up only the parts it needs, through IDs and indexes. Typical uses of the generated specifications:\n\n- **Reimagining the application** — an AI agent reimagines the application on a new technology stack through spec-driven development, using the specifications as input\n- **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\n\nIt 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.\n\n- **Every statement cites its evidence** — each statement carries the location in the code that supports it (`path:line` ).\n- **Verified separately from the author** — a verifier AI agent, isolated from the one that wrote the specification,\nchecks 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.\n- **Unknowns are written as unknown** — anything that cannot be confirmed from the code is not filled in by guesswork; it is left as`UNKNOWN` .\n\n- **Build the list to count against (the denominator) first** — the first step builds a structural map (the code graph)\nthat lists the modules, entry points and external connections, and how they are connected.\n- **Not complete until the list is used up** — the workflow counts whether every element of the code graph has been specified,\nand the work is not complete until nothing is left. It does not stop at \"we looked at the main parts.\"\n- 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.\n\nFor both, whether the work is complete is decided not by the agent saying \"done,\" but by whether the gate script `gates.sh`\nreturns a pass (exit 0).\n\n- **Easy for AI agents to look up** — every specification file and requirement gets a unique, stable ID (for example`REQ-F-01` ).\nSpecifications 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,\nso an AI agent can look up only what it needs without reading everything.\nThe rules that an AI agent using the specifications must follow (`specs/AGENTS.md` ) are included.\n- **Separate layer for reimagining** — what depends on the current technology and what any reimagined application would need regardless of technology can be written separately.\n- **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.\nIf the AI tool supports sub-agents (AI agents that split the work and run in parallel), business areas can be processed in parallel.\n- **Survives context overflow** — progress and the next actions are written to files and committed to git.\nIf the agent's context overflows or the session ends, opening a new session resumes from the record.\n- **Lessons carry forward** — lessons learned in a project are recorded, and general ones can be fed back into reverse-spec-flow itself\n(see \"Documentation\" below).\n- **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.\n\nBelow, products such as Claude Code and Kiro are called **AI tools**, and the AI that works inside them is called an **AI agent**.\n\n- **bash and git** (macOS / Linux. On Windows, WSL is recommended. Git Bash also works, but the checks take longer)\n- **An AI tool** (see \"Supported AI tools\" below)\n- **The source code you want to analyze**\n\nNo database or dedicated platform is needed.\n\n```\n# 1. Clone next to the folder you want to analyze (for example legacy-order-system/)\ncd /path/to/workspace        # legacy-order-system/ is in here\ngit clone https://github.com/aws-samples/sample-reverse-spec-flow.git\n\n# 2. Create the repository for the specifications\n#    init.sh <target> <name (letters, digits, . _ -)> [purpose (asked interactively if omitted)]\n./sample-reverse-spec-flow/init.sh ./legacy-order-system order-system rebuild\n\n#    If there is a Playbook (a set of counting rules; see \"Playbooks\" below) for the target technology, you can specify it (optional; it works without one)\n./sample-reverse-spec-flow/init.sh ./legacy-order-system order-system rebuild --playbook java-jaxrs-jpa\n```\n\nThis creates `legacy-order-system-spec/` (the repository for the specifications) next to the target.\n**Do all further work in a new session opened on `legacy-order-system-spec/`.**\nDo not start the analysis in the `sample-reverse-spec-flow/` session where you ran `init.sh`.\nIf you use Kiro IDE, read `legacy-order-system-spec/HOST-SETUP.md` before opening the repository in Kiro IDE.\n\n```\n3. Open legacy-order-system-spec/ in your AI tool and give an instruction such as:\n\n   Read spec-extraction/AGENTS.md.\n   The source to analyze is in /path/to/workspace/legacy-order-system/ (read-only; do not modify it).\n   Fill in the <PLACEHOLDER> values in spec-extraction/AGENTS.md, then start from Phase 0.\n```\n\nThe same instruction is also shown at the end of the `init.sh` output.\n\nMain `init.sh` options:\n\n| Argument | Meaning | \n|---|---|\n| `purpose` (3rd argument, optional) | What the specifications are for. `maintenance` (maintaining and evolving the current system) /`evaluation` (assessing and estimating a reimagine effort) /`rebuild` (deep enough for an AI agent to implement the reimagined application). It changes what is produced and how strict the checks are. If omitted, you choose interactively (default`rebuild` ) | \n| `--playbook <name>` | Optional. Counting rules for the target technology (see \"Playbooks\" below). Can be given more than once | \n| `--host <name>` | The AI tool to use ( `claude-code` (default) /`kiro-ide` /`kiro-cli` ) | \n| `--list-playbooks` /`--list-hosts` | List the available Playbooks / AI tools | \n\n```\nPhase 0  Ingestion      Pin the commit of the target and decide the scope\nPhase 1  Code graph     List the modules, entry points, external connections and how they connect (the coverage denominator)\nPhase 2  Analysis       Analyze from each viewpoint (architecture, requirements, API, data, behavior, non-functional), with evidence\nPhase 3  Specification  Write specifications that AI agents can look up, structured after ISO/IEC/IEEE 29148 (the international standard for requirements specifications)\nPhase 4  Audit          Check coverage, citations and the separation of fact from guesswork, independently of the authoring\n```\n\nAt the boundaries between phases, the AI agent asks a person to confirm (for example, the scope or how to count).\nWhat is checked, and when the AI agent stops to ask a person, is described in [docs/how-it-works.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/how-it-works.md) (Japanese).\n\n```\nlegacy-order-system-spec/            ← independent git repository created by init.sh\n├── AGENTS.md                        ← entry point\n├── specs/                           ← output (specifications handed to AI agents)\n│   ├── AGENTS.md                    ←   rules for the agent that uses the specifications\n│   ├── overview.md                  ←   overview of the whole system\n│   ├── source-index.md              ←   reverse index from source to specifications (used for impact analysis)\n│   ├── modules/ api/ data/ behavior/\n│   └── rebuild/                     ←   technology-independent specifications for reimagining (when purpose is rebuild / evaluation)\n└── spec-extraction/                 ← working records (procedures, intermediate artifacts, check results)\n    ├── AGENTS.md                    ←   rules for the agent that writes the specifications\n    └── 03-audit/gates.sh            ←   gate script that decides completion\n```\n\nThe rules the AI agent follows are split into an entry point and two sets of rules.\n\n| Location | Role | \n|---|---|\n| `AGENTS.md` (root) | Entry point. Points to one of the two below depending on the task | \n| `specs/AGENTS.md` | Rules for the side that uses the specifications (the agent that reimagines the application or investigates it) | \n| `spec-extraction/AGENTS.md` | Rules for the side that writes the specifications | \n\nWhich files an AI tool loads automatically differs by tool and version. So the workflow does not depend on automatic loading: the agent reads the rules it needs, starting from the entry point.\n\nWhen you hand the specifications to an AI agent, give it `specs/` as is and have it read `specs/AGENTS.md` first.\nIf you also give it the source code under analysis, the agent can check statements against the source code.\nIf you do not, the agent says so and answers only what the specifications themselves support.\n\nAI tools that can be used to write the specifications:\n\n| AI tool | Status | Option | \n|---|---|---|\n| Claude Code | Verified (run end to end) | `--host claude-code` (default).`CLAUDE.md` (root) is also placed as a pointer to the entry point | \n| Kiro IDE | Verified (run end to end on a small target; scope in [hosts/README.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/hosts/README.md) ) | `--host kiro-ide` (read the generated`HOST-SETUP.md` before opening) | \n| Kiro CLI | Not verified (only some functions checked; not run end to end) | `--host kiro-cli` | \n\nFor writing the specifications, AI tools not in this table are not supported. (The generated specifications can be handed to any AI agent.)\nSupport status and measurement records are in [hosts/README.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/hosts/README.md) (Japanese).\n\n**reverse-spec-flow works with any language or technology stack. It works as is, even when there is no Playbook for your technology.**\n\nA Playbook is a shortcut: it records in advance, for a specific technology, what to count so that the whole system is covered (for example, how to count screens, APIs and tables). If you do not specify a Playbook, at the start of Phase 1 the AI agent examines the target code and decides how to count, based on its knowledge of the technology stack. The procedure is the same and the same checks run (if the agent moves on without deciding how to count, the checks stop it).\n\nPlaybooks currently available:\n\n| Playbook | Target | \n|---|---|\n| `java-jaxrs-jpa` | Java (JAX-RS / Spring MVC + JPA annotations) | \n| `java-struts-ormxml` | Java (Struts 2 + JPA XML mapping) | \n| `java-struts1-ejb2` | Java (Struts 1 / EJB 2.x) | \n| `aspnet-webforms` | ASP.NET Web Forms (C# / VB.NET) | \n| `csharp-winforms-adonet` | C# Windows Forms + ADO.NET | \n| `vbnet-winforms-adonet` | VB.NET Windows Forms + ADO.NET | \n| `vb6` | Visual Basic 6.0 | \n| `php-procedural-mysql` | Procedural PHP + MySQL and similar | \n| `cobol-cics-batch` | COBOL (CICS / JCL batch / DB2 and VSAM) | \n| `oracle-plsql` | Oracle PL/SQL (used together with the Playbook for the application side) | \n\nIf you work with a technology often, you can write and add a Playbook ([docs/authoring-playbook.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/authoring-playbook.md), Japanese).\n\n- **The specifications may still contain errors.** The checks reduce errors, but cannot eliminate them completely.\nIf you reimagine an application from the specifications, separately confirm through UAT, regression testing and similar means that it behaves like the current system.\nThe quality measured in verification runs is in[docs/release-notes.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/release-notes.md) (Japanese).\n- **The AI tool reads the source code under analysis.** If the code is confidential,\nfollow the terms of the AI tool you use and the rules of your organization.\n- **Instructions and secrets inside the analyzed code.** The rules tell AI agents to treat comments, strings and documents in the source code as data, not as instructions,\nand not to copy secret values (passwords, keys, tokens, personal data) into the specifications; only where they are and what kind they are is recorded.\nEven so, check the specifications for secrets before sharing them.\n- **Analyze untrusted code in an isolated environment.** The AI agent runs shell commands with your permissions, and the rules above are instructions to the AI, not enforcement.\nFor code you do not trust, use an isolated environment without production credentials (a VM, a container or a disposable machine), and do not use auto-approval\n(Always allow,`kiro-ide-allow.sh` ). Use Playbooks and`hosts/` files only from sources you trust.\n- **Handle the spec repository like the source code.** It contains excerpts of the analyzed code and local absolute paths. Do not push it to a public remote,\nand check it with a secret scanner (for example git-secrets or gitleaks) before sharing it. If you receive a spec repository from someone else,\nreview`.claude/` and`.kiro/` before you trust the workspace in your AI tool.\n- **No dynamic checks such as starting the application or operating its screens.** Anything that cannot be confirmed from the code is left as`UNKNOWN` .\n- This repository is a sample. Before using it for production work, verify it thoroughly at your own responsibility.\n\nThe documents below are in Japanese.\n\n| What you want to know | Document | \n|---|---|\n| **How to use it and how it works** (what happens, what is checked, what to do when it stops) | [docs/how-it-works.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/how-it-works.md) | \n| Explanation for non-engineers | [docs/overview-for-business.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/overview-for-business.md) | \n| Design ideas, the problems it addresses, examples of output | [docs/overview-for-engineers.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/overview-for-engineers.md) | \n| Changes by version | [docs/release-notes.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/release-notes.md) | \n| How to write a new Playbook | [docs/authoring-playbook.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/authoring-playbook.md) | \n| Design document (verifier isolation) | [docs/designs/verifier-isolation.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/docs/designs/verifier-isolation.md) | \n| How AI tool support works | [hosts/README.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/hosts/README.md) | \n| Generation rules and quality rules (documents the AI agent refers to; people do not need to read them) | [pipeline.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/pipeline.md) /[playbook.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/playbook.md) | \n\n- How to make changes and run the selftest: [CONTRIBUTING.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/CONTRIBUTING.md)\n- Pitfalls when modifying the framework: [dev/developing-the-framework.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/dev/developing-the-framework.md)\n- How to feed lessons from a project back into reverse-spec-flow: [dev/backport-procedure.md](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/dev/backport-procedure.md)\n- `dev/` also contains records of tests run during development (you do not need to read them just to use the workflow).\n\nSee [CONTRIBUTING](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/CONTRIBUTING.md#security-issue-notifications) for more information.\n\nThis library is licensed under the MIT-0 License. See the [LICENSE](https://github.com/aws-samples/sample-reverse-spec-flow/blob/main/LICENSE) file.", "url": "https://wpnews.pro/news/reverse-spec-flow", "canonical_source": "https://github.com/aws-samples/sample-reverse-spec-flow", "published_at": "2026-11-22 11:27:06+00:00", "updated_at": "2026-11-22 11:41:48.305681+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-research"], "entities": ["AWS", "reverse-spec-flow", "MIT-0"], "also_reported_by": [], "takeaway": "reverse-spec-flow 2.2.1 generates agent-readable Markdown specs from existing code, requiring each statement to cite a `path:line` location, an isolated verifier agent to confirm the cited lines support it, `UNKNOWN` for unconfirmable items, and a `gates.sh` exit-0 pass before work counts as complet", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/reverse-spec-flow", "markdown": "https://wpnews.pro/news/reverse-spec-flow.md", "text": "https://wpnews.pro/news/reverse-spec-flow.txt", "jsonld": "https://wpnews.pro/news/reverse-spec-flow.jsonld"}}