flowgraph-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 404FoundingFather
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# FlowGraph
+
+Machine-verifiable maintenance contracts for codebases. Capture what breaks when code changes.
+
+## What is FlowGraph?
+
+FlowGraph is a lightweight contract system that answers one question: **"If I change X, what else breaks?"**
+
+It captures the invisible maintenance relationships in your codebase — the ones where changing a database table silently breaks a repository method, or adding an enum value requires updating three switch statements in different files. These are the bugs that compilers don't catch and code review misses.
+
+FlowGraph is designed for AI coding agents and human developers alike. It's not documentation, not a dependency graph, and not a type system. It's a maintenance contract.
+
+### What goes in a FlowGraph:
+
+- **co_change edges** — "if you change X, you must also update Y" (highest value)
+- **validates edges** — runtime schema validation boundaries (Zod, Joi, etc.)
+- **Invariants** — cross-cutting rules that span multiple files
+- **Complex flows** — multi-file execution paths with non-trivial branching
+
+### What does NOT go in a FlowGraph:
+
+- Function call trees (read the code)
+- Request/response shapes (that's documentation)
+- Anything the type checker already enforces
+- Simple linear flows with no branching
+
+## Quick Start
+
+```bash
+# Verify your flowgraph against source code
+npx flowgraph-ai verify
+
+# See what breaks if you change a specific node
+npx flowgraph-ai verify --impact table:users
+
+# Render as Mermaid diagrams (outputs markdown)
+npx flowgraph-ai render
+
+# Create a starter flowgraph for your project
+npx flowgraph-ai init
+```
+
+## Example
+
+Here's a minimal flowgraph for a todo API ([full example](./example/)):
+
+```json
+{
+  "$flowgraph": "2.1",
+  "meta": { "name": "todo-api", "root": "src/" },
+  "nodes": {
+    "type:TaskStatus": {
+      "kind": "type",
+      "loc": "types.ts:5",
+      "values": ["pending", "in_progress", "done", "cancelled"]
+    },
+    "table:tasks": {
+      "kind": "table",
+      "loc": "../schema.sql:1"
+    },
+    "method:TaskRepository.create": {
+      "kind": "method",
+      "loc": "repository.ts:11"
+    }
+  },
+  "edges": [
+    {
+      "from": "table:tasks",
+      "to": "method:TaskRepository.create",
+      "rel": "co_change",
+      "note": "column changes require INSERT query update"
+    }
+  ],
+  "flows": {},
+  "invariants": []
+}
+```
+
+This single `co_change` edge says: if you add a column to the `tasks` table, you must also update `TaskRepository.create` — because it has a raw INSERT query that lists columns explicitly. The verifier confirms both sides of this contract exist in your source code.
+
+## CLI Commands
+
+### `flowgraph verify [file]`
+
+Runs four verification phases against your source code:
+
+1. **Structural** — every node's `loc` points to a real file and the expected artifact exists (type definition, method signature, CREATE TABLE, route handler, etc.)
+2. **Relational** — edges are valid (validates edges check for schema.parse() calls, co_change edges check both nodes exist)
+3. **Sequential** — flow steps reference existing nodes and branch targets are reachable
+4. **Invariant** — scoped nodes and files exist (custom invariant logic requires a project-specific checker)
+
+Output: `PASS`, `FAIL`, or `WARN` for each check.
+
+If no file is specified, auto-discovers `*.flowgraph.json` in the current directory.
+
+### `flowgraph verify --impact <node:id>`
+
+Shows everything affected by changing a node:
+- Outgoing/incoming edges (with `co_change` edges highlighted)
+- Flows containing the node
+- Invariants scoping the node
+
+### `flowgraph-ai render [file]`
+
+Generates a markdown file with Mermaid diagrams:
+- **Dependency graph** — nodes grouped by kind, edges styled by type (dashed for co_change, solid for others)
+- **Flow diagrams** — one per flow, with decision diamonds for branching and terminal nodes for DONE/FAIL
+- **Invariants table** — all invariants with their enforcement notes
+
+Output is written next to the input file (e.g., `my-project.flowgraph.json` -> `my-project.flowgraph.md`). View it on GitHub (native Mermaid support), in VS Code with a Mermaid extension, or paste diagrams into [mermaid.live](https://mermaid.live).
+
+### `flowgraph-ai init`
+
+Creates a starter `<project-name>.flowgraph.json` in the current directory.
+
+## Specification
+
+See [flowgraph-spec-v2.1.md](./flowgraph-spec-v2.1.md) for the full FlowGraph specification, including:
+- All node kinds and their fields
+- Edge types and when to use each
+- Flow syntax and branching
+- Invariant structure
+- Extensibility with custom node kinds
+
+## Integrating with Claude Code
+
+FlowGraph is designed to be read by AI coding agents. To hook it up to [Claude Code](https://docs.anthropic.com/en/docs/claude-code):
+
+1. **Copy the spec into your project** so the agent can read it locally:
+   ```bash
+   # from your project root
+   cp node_modules/flowgraph-ai/flowgraph-spec-v2.1.md flowgraph/
+   # or if you haven't installed it:
+   curl -sL https://raw.githubusercontent.com/404FoundingFather/flowgraph/main/flowgraph-spec-v2.1.md -o flowgraph/flowgraph-spec-v2.1.md
+   ```
+
+2. **Add a FlowGraph section** to your `.claude/CLAUDE.md` — here's a ready-to-paste template (replace the paths to match your project):
+
+````markdown
+## FlowGraph
+
+This project uses [FlowGraph](https://github.com/404FoundingFather/flowgraph) for machine-verifiable maintenance contracts.
+
+- **`flowgraph/your-project.flowgraph.json`** — The contract: nodes, co_change edges, invariants, and flows. Read this first for structural understanding of how components connect.
+- **`flowgraph/flowgraph-spec-v2.1.md`** — The FlowGraph specification (how to read and write flowgraph files). Reference this when creating or updating flowgraph entries.
+
+### The three elements:
+
+1. **co_change edges** (primary) — "if you change X, you must also update Y." Every table and key type should have co_change edges to the methods/endpoints that would break if the schema changed.
+2. **Invariants** — Cross-cutting rules that must hold regardless of what changes. Each has an `enforce` field explaining where/how it's enforced.
+3. **Complex flows** — Multi-file execution paths with non-trivial branching (3+ cases). Only flows where the branching logic spans multiple files and isn't obvious from reading one call site.
+
+### Before modifying code:
+
+- **Impact check** — Run `npx flowgraph-ai verify --impact <node:id>` to see co_change requirements, containing flows, and scoped invariants.
+
+### After modifying code:
+
+1. **Verify** — Run `npx flowgraph-ai verify` to check the flowgraph still matches source.
+2. **Update** — If verification fails:
+   - Changed a table schema? Update co_change target methods/endpoints.
+   - New table? Add `table:` node with loc, fk, indexes + co_change edges to its repository methods.
+   - New cross-cutting rule? Add an `invariants` entry with `enforce`.
+   - Changed a complex multi-file flow with branching? Update the relevant `flows` entry.
+3. **Re-verify** — Run `npx flowgraph-ai verify` again to confirm 0 FAIL.
+
+### What does NOT belong:
+
+- **calls/reads/writes edges** — Visible by reading the call site. co_change captures what matters.
+- **Method pre/post conditions** — Restates what the method name and types already say.
+- **Endpoint request/response shapes** — Documentation, not contract.
+- **Simple linear flows** — If a flow is just "endpoint -> service -> repo -> done" with no branching, don't add it.
+- **Nodes not referenced** by any co_change edge, invariant, or complex flow.
+````
+
+The template points the agent at two files: the flowgraph JSON (the contract itself) and the spec (how to read/write it). This gives it enough context to check impact before changing, verify after changing, update the flowgraph when verification fails, and know what does and doesn't belong.
+
+### Other AI agents
+
+The same instructions work for any AI coding agent that reads project configuration. The key points to convey:
+
+1. Read the flowgraph JSON for structural understanding of the codebase
+2. Run `--impact` before modifying code to see what else needs to change
+3. Run `verify` after modifying code to confirm contracts still hold
+4. Keep the flowgraph lean — only high-value maintenance contracts
+
+## Getting Started from Scratch
+
+1. **Start small.** Run `npx flowgraph-ai init` and replace the example with 5-10 `co_change` edges from your project. Focus on database table -> repository method pairs and enum -> switch statement pairs.
+
+2. **Add invariants.** Write down 2-3 cross-cutting rules that a new contributor would violate without being told.
+
+3. **Add validates edges** where runtime validation (Zod, Joi, etc.) marks a trust boundary.
+
+4. **Only add flows** for complex multi-file paths with 3+ branching cases. Most projects have 2-5 of these.
+
+See the [Getting Started section of the spec](./flowgraph-spec-v2.1.md#getting-started) for detailed guidance.
+
+## Philosophy
+
+FlowGraph follows a "less is more" approach:
+
+- Every element must prevent a real bug when code changes
+- If it would drift silently without causing bugs, it doesn't belong
+- Nodes exist because they're referenced by edges, flows, or invariants — not to document the codebase
+- The maintenance cost of each element must be justified by the bugs it prevents
+
+## License
+
+MIT