Once you’re writing specs to hand off to an AI coding agent, plain Markdown files scattered in a folder stop being enough. You need to know which spec is current, what changed since the last edit, whether a requirement card is actually complete before you feed it to an agent, and how a big project’s dozens of requirement cards relate to an index. Google Docs and Notion don’t give you diffs against a previous version or structural validation; a bare folder of .md files gives you no filtering, no search, no enforced format. The same problem shows up at company scale the moment more than one person or one agent is writing specs against a shared requirements set: without a source of truth and a validation gate, spec drift and half-finished requirement cards get fed straight into implementation, and nobody catches it until the generated code is wrong.

I built ReqManager to close that gap for my own spec-writing workflow, but the underlying problem — keeping human- and agent-facing specs authoritative, versioned, and structurally sound — is exactly what a team doing spec-driven development with AI agents runs into.

ReqManager is a local Flask + HTMX web app (no JavaScript hand-written, everything server-rendered) that manages four kinds of item, all stored as Markdown on disk with SQLite holding only metadata (group, category, labels) — delete the database and you lose nothing, it rebuilds from the files. The four types: Complex Projects (a folder with an INDEX.md plus individual REQ-NNN.md requirement cards), Simple Projects, Specifications, and Contexts.

From the main screen you can create, edit, or delete any of the four types; filter the full list by name (with autocomplete), group, category, or multi-select labels; and run a full-text word search that highlights every item whose files contain the term, so you can jump straight to the matching file. Every file — INDEX.md, a requirement card, a spec, a context doc — carries one snapshot: the previous saved version. Open a diff view for side-by-side comparison, and a Restore button swaps the current content back in cleanly. For Complex Projects there’s a dedicated project view: it renders INDEX.md, lists every requirement card in the project, lets you add a new card (the app auto-assigns the next number in the right range from INDEX.md’s own numbering table — you never type a card number), edit a card with structural validation before it’s allowed to save, or delete a card, with INDEX.md’s totals and summary tables kept in sync automatically. There’s also an import flow for pulling in an existing folder of requirement files: it runs six coherence checks (every card in INDEX.md has a file, every file is listed, numbers match filenames, titles match headings, the total count is accurate, no duplicate numbers) and either blocks the import with a discrepancy list or regenerates INDEX.md from the files.

The validation is the part that matters most for the agent-handoff use case: a requirement card isn’t allowed to save unless it has a non-empty Who, Domain, a Priority from a fixed MoSCoW-style set, a Status, a What section, at least one Business Rule, and at least one complete Given/When/Then acceptance criterion. That format — Gherkin-style acceptance criteria baked into the schema — exists specifically so a spec is precise enough for an agent to build against without asking clarifying questions.

Writing this app was itself a spec-driven-development exercise — I wrote a full functional-requirements document (nine FRs, exact file-format grammars for both requirement cards and INDEX.md) before generating any code, then used the app I was building to manage other projects’ specs. That loop surfaced something I’m still chewing on: Gherkin/Given-When-Then acceptance criteria are the standard advice for writing specs precise enough for an agent to implement against, but a rigid structural format is also exactly the kind of thing an agent can learn to satisfy superficially — passing the shape of the requirement without necessarily building the right behavior. Structural validation catches malformed specs; it doesn’t catch specs that are technically well-formed but hollow. That’s a real open question I flagged for follow-up, not a solved problem — validation of format is not the same as validation of intent.

The natural extension is closing the loop between validated specs and the agent that consumes them — e.g. a card’s Given/When/Then criteria compiled directly into an agent’s acceptance-test harness, so passing the tests and satisfying the spec become the same check rather than two things that can silently diverge.

At team scale this stops being a personal spec editor and becomes the shared source of truth a group of engineers and agents write against: multiple people filing requirement cards into the same Complex Project, an import/coherence-check step that catches drift before it reaches an agent, and a validation gate that keeps every spec in a shared repo well-formed no matter who (or what) wrote it. That’s the same problem product and engineering orgs solve today with heavyweight tools like Jira or Confluence, except optimized for the actual bottleneck teams have now: specs precise enough for an AI agent to execute against directly, with versioning that survives someone or something overwriting a file at 2am.