Graph-first, automatically orchestrated AI development workflow.
One prompt starts the entire lifecycle — from blank repo to production.
v4.7 highlights: Full-cycle
cycle enter-reviewer|enter-qa|enter-ship, gate v4 (ship + QA before commit/close), protocol hardening in v4.7.1 (resume matrix, handoff conventions, token budgets). See CHANGELOG.md.
Open your project folder in Cursor, open the integrated terminal, and run:
Windows (PowerShell) — recommended:
irm https://raw.githubusercontent.com/MertCapkin/GraphStack/master/scripts/bootstrap.ps1 | iex
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/MertCapkin/GraphStack/master/scripts/bootstrap.sh | bashOr install from PyPI directly:
Package:
MertCapkin_GraphStackon PyPI (graphstackname was taken). CLI command:graphstack.
pip install "MertCapkin_GraphStack[graphify]" graphstack init . -y --install-deps
This installs GraphStack + Graphify, copies workflow files into the current project, refreshes the code graph, and runs doctor. Then describe your task in Cursor chat — rules load automatically.
Python 3.8+ and Git are required.
py -3 --version git --version
Install GraphStack + Graphify from PyPI, then initialize your project (run inside your project folder):
pip install "MertCapkin_GraphStack[graphify]" graphstack init . -y --install-deps
Or use the one-command bootstrap above (same result; installs from PyPI, falls back to GitHub if needed).
Verify:
graphstack --version graphstack doctor pip show graphifyy
PyPI: pypi.org/project/MertCapkin_GraphStack
CLI name:graphstack(unchanged — only the pip package name differs)
Graphify runs entirely locally — tree-sitter AST, no API calls for code graphs.
If you prefer to install Graphify separately first:
pip install "graphifyy>=0.7,<0.9" graphify cursor install pip install "MertCapkin_GraphStack[graphify]" graphstack init . -y --install-deps
For hacking on GraphStack itself or air-gapped installs, clone the repo instead of PyPI:
git clone https://github.com/MertCapkin/graphstack /tmp/graphstack cd /path/to/your-project bash /tmp/graphstack/install.sh # or, equivalently: # python3 -m graphstack install . --no-interactive
git clone https://github.com/MertCapkin/graphstack $env:TEMP\graphstack cd C:\path\to\your-project & $env:TEMP\graphstack\install.ps1 .
If python.exe on Windows redirects you to the Microsoft Store, the installer detects that and falls back to the official py -3 launcher automatically.
git clone https://github.com/MertCapkin/graphstack /path/to/graphstack cd /path/to/your-project python -m graphstack install . --non-interactive
This copies all GraphStack files into your project:
.cursor/rules/graphstack.mdc— Cursor loads this automatically on every sessionorchestrator/,.cursor/skills/,handoff/,scripts/— the full workflow systemscripts/graphstack/— the Python helper package (used by both the bash and PowerShell shims)
The install script is non-destructive: it won't overwrite existing handoff/BRIEF.md, handoff/REVIEW.md, or handoff/BOOTSTRAP.md if they already exist.
Open your project in Cursor. In the chat, type:
/graphify .
What happens:
- Graphify scans all source files (25 languages supported)
- Builds a dependency graph using tree-sitter (local, no API)
- Creates three files in
graphify-out/:GRAPH_REPORT.md— human-readable architecture summarygraph.json— machine-queryable full graphgraph.html— visual explorer, open in browser
How long does it take?
| Codebase size | Time |
|---|---|
| < 50 files | ~5 seconds |
| 50–200 files | ~15–30 seconds |
| 200–500 files | ~1–2 minutes |
| 500+ files | ~3–5 minutes |
Run this once. After that, use /graphify --update — it only re-scans changed files and takes a few seconds.
New project with no code yet? Skip this step — GraphStack's Bootstrap Mode handles it.
Already ran graphstack init --install-deps? You have a code-only graph in graphify-out/; run /graphify . in Cursor for the full semantic graph when ready.
The repo ships two ways to bootstrap the orchestrator — pick whichever feels natural.
Because .cursor/rules/graphstack.mdc is alwaysApply: true, every new Composer / Agent
session already carries GraphStack’s binding rules. Simply open chat and describe your goal in
natural language (Add …, Fix …). The assistant’s first turn must still execute
orchestrator/ORCHESTRATOR.md → Activation** (parallel TOKEN_OPTIMIZER+GRAPH_REPORT), but **you don’t paste** Read orchestrator/...` anymore.
In Cursor Chat/Composer press / → choose graphstack. That injects the Bootstrap command
stored in .cursor/commands/graphstack.md (helps when you want deterministic orchestrator wording
or onboarding teammates).
If /graphstack doesn't appear immediately, restart Cursor once so it rescans .cursor/commands/.
Existing codebase:
Read orchestrator/ORCHESTRATOR.md and follow it exactly.
[Describe what you want to build or fix]
New project from scratch:
Read orchestrator/ORCHESTRATOR.md and follow it exactly.
This is a new project with no existing codebase.
I want to build [describe your idea].
Tech stack: [language, framework, database].
GraphStack handles everything from here — planning, building, reviewing, testing, shipping.
GraphStack combines two ideas into one installable system:
Graphify builds a queryable knowledge graph of your codebase. Every AI query navigates that compact map instead of re-reading raw files from scratch.
Role-based orchestration drives a structured lifecycle: Bootstrapper → Architect → Builder → Reviewer → QA → Ship. A central Orchestrator manages all transitions automatically. You never switch roles manually.
You write one prompt. GraphStack runs the full cycle.
Without GraphStack, every AI coding session looks like this:
You: "Add rate limiting to login."
AI: reads login.ts... reads session.ts... reads crypto.ts... reads types.ts...
(4 files, ~3 000 tokens — before writing a single line)
You: "Now add tests."
AI: reads login.ts again... reads session.ts again...
(same files, same cost, zero memory)
Problems:
- Token waste — AI re-reads your codebase on every query
- No structure — planning, coding, reviewing blur together
- No memory — closing Cursor means starting from zero
- No audit trail — impossible to know what was decided and why
Step 1 — once:
/graphify . → graphify-out/GRAPH_REPORT.md + graph.json
Step 2 — every session (minimal typing):
Open Composer + describe the task (rules already activate GraphStack automatically),
optionally type `/graphstack` once for an explicit orchestrator preamble,
or paste the legacy `Read orchestrator/ORCHESTRATOR.md …` snippet if working outside Cursor.
Example natural-language kickoff:
"Add rate limiting to login."
[ARCHITECT] cycle start → reads graph → scopes change → writes BRIEF.md
↓ auto
[BUILDER] cycle enter-builder → reads brief → builds exactly the brief
↓ auto
[REVIEWER] checks criteria → inspects graph neighbors for side effects
↓ auto (loops to Builder if rejected, max 3×)
[QA] traces call path through graph → verifies behavior
↓ auto
[SHIP] checklist → graph update → commit message → closes board task
Zero manual role switching. Zero repeated file reads. Full git audit trail.
No code yet? GraphStack handles that too.
Composer (Cursor):
Describe the product + tech stack naturally (alwaysApply rules bootstrap GraphStack),
optionally `/graphstack` beforehand to inject the scripted opener.
Bootstrap example:
"/graphstack then: New project REST API for task mgmt — TS, Express, PostgreSQL."
[BOOTSTRAPPER] analyzes idea → decomposes into modules → orders by dependency
→ writes BOOTSTRAP.md (the memory across all cycles)
→ writes Cycle 1 brief
↓ auto
[BUILDER → REVIEWER → QA → SHIP] Cycle 1 (auth module)
↓
run /graphify . ← first graph from real code
↓
[BOOTSTRAPPER] reads new graph → writes Cycle 2 brief with real knowledge
↓ auto
[BUILDER → REVIEWER → QA → SHIP] Cycle 2 (data models)
↓
run /graphify --update → next cycle → ...
Each brief is written with knowledge of what was actually built — not just planned. The graph grows with the project.
GraphStack's savings come from three mechanisms:
| Mechanism | How | Savings |
|---|---|---|
| Graph-first reads | GRAPH_REPORT.md replaces browsing 10+ files | ~85% on architecture queries |
| Role discipline | Each role reads only what its job requires | ~60% vs unstructured sessions |
| File-based state | STATE.md replaces chat history on resume | ~60% per new session |
| Parallel reads | Multiple files in one tool call | ~50% on multi-file ops |
| Shell compaction | graphstack run shrinks git/test output before it hits context |
~60–80% on verbose shell ops |
Net savings by codebase size:
| Codebase | Tokens/day without | Tokens/day with | Saving |
|---|---|---|---|
| Small (10–20 files) | ~40k | ~28k | ~30% |
| Medium (50–100 files) | ~180k | ~54k | ~70% |
| Large (200+ files) | ~600k | ~90k | ~85% |
| Very large (500+ files) | ~1.5M | ~180k | ~88% |
Estimates based on Graphify benchmarks and TOKEN_OPTIMIZER rules. Real savings depend on query patterns. See docs/case-studies/graphstack-self.md for an honest self-analysis — measured community benchmarks are welcome via PR.
GraphStack is a workflow protocol (markdown + handoff files), not a runtime that enforces AI behavior.
| Topic | Reality |
|---|---|
| Role automation | Prompts + gate v4 (v4.7): code edits require STATE.json role=builder and a task in doing/; commits/close require Reviewer + QA + Ship. graphstack cycle binds board + state + phase handoffs. Strict mode (GRAPHSTACK_GATE=strict) fail-closes on hook errors. afterFileEdit on Cursor remains advisory-only backup. |
| Token savings | The table above is estimated, not guaranteed. Small repos or undisciplined sessions may use more tokens than unstructured chat. |
| Knowledge graph | Value appears on 20+ file codebases with module boundaries. Meta-repos full of markdown produce noisy graphs — use .graphifyignore (included in this repo). |
| Setup | Graphify + pip install MertCapkin_GraphStack + graphstack init — or one bootstrap command. See PyPI. |
Health checks: graphstack doctor and graphstack validate (exit code for CI). v4.7 adds framework handoff checks (framework_* warnings). Use --strict before Builder handoff; use --fail-stale-graph in CI after code changes.
graphstack doctor graphstack validate graphstack validate --strict --fail-stale-graph
Graph-first rules reduce file reads. Shell compaction reduces terminal output (git status, diffs, test runners) before it enters the AI context — without installing third-party proxies.
Who uses it: Cursor/Claude agents follow TOKEN_OPTIMIZER.md and .cursor/rules/graphstack.mdc — they call graphstack run, not raw git/pytest. You do not need to remember a separate workflow.
python -m graphstack run -- git status python -m graphstack run -- git diff python -m graphstack run -- git log -n 20 python -m graphstack run -- pytest -q
Quality safeguards (not “blind compression”):
- File paths, branch names, diff hunks (
@@), and+/-lines are preserved - Test failures, tracebacks, and stderr are kept (stderr is never compacted)
- If compaction would drop too much signal, output falls back to raw automatically
- Full output when debugging:
python -m graphstack run --raw -- git diff
Independent Python implementation (MIT) — inspired by common agent-tooling patterns, no RTK dependency or vendored code.
graphstack doctor reports whether the compact module is installed in your project.
Graph-first rules mean query the graph before opening raw files. v4.4 wraps Graphify's CLI so agents use one consistent command:
python -m graphstack graph query "who calls login" python -m graphstack graph query "blast radius of crypto.ts" --budget 1500 python -m graphstack graph path src/auth/login.ts src/utils/crypto.ts python -m graphstack graph explain "login()" python -m graphstack graph update . # AST-only refresh after code changes
Requires graphify on PATH (pip install -r requirements.txt). Agents should prefer graph query over reading full GRAPH_REPORT.md or grepping source for structural questions.
Gate v4 (v4.7) adds role-aware enforcement and full-cycle prerequisites before code commits and cycle close. Cursor preToolUse blocks edits before they land; use graphstack cycle enter-* for mechanical phase handoffs.
| Rule | What it blocks | Cursor | Claude Code |
|---|---|---|---|
| R1 | git commit touching code while doing/ is empty |
deny | deny |
| R2 | Edit/Write on code paths while doing/ is empty |
deny | deny |
| R3 | Template BRIEF.md while task in doing/ |
deny | deny |
| R2b | Code edit while STATE.json role ≠ builder |
deny | deny |
| R3b | Code edit while BRIEF.md status is Draft |
deny | deny |
| R4 | Stale STATE.json vs board claim |
advisory (stop; deny in strict) |
same |
| R5 | Code commit while role ≠ ship |
deny (gate on) | deny (gate on) |
| R6 | Code commit without Verdict: Approved in REVIEW.md |
deny (gate on) | deny (gate on) |
| R7 | Code commit without shippable QA Report | deny (gate on) | deny (gate on) |
| R8 | board complete / cycle close without ship prerequisites |
deny (gate on) | deny (gate on) |
| — | Edit already applied (legacy hook) | advisory (afterFileEdit) |
— |
python -m graphstack cycle start my-feature "Add email verification" python -m graphstack cycle enter-builder my-feature # after Architect writes BRIEF python -m graphstack cycle enter-reviewer my-feature # after Builder finishes python -m graphstack cycle enter-qa my-feature # after Reviewer approves python -m graphstack cycle enter-ship my-feature # after QA PASS/PARTIAL python -m graphstack cycle close my-feature # after Ship checklist (or --force) python -m graphstack gate check # CI / manual — exit 1 on violation python -m graphstack state set --role builder --task my-feature GRAPHSTACK_GATE=off # emergency bypass (one session) GRAPHSTACK_GATE=strict # R4 fail-closed + hook errors deny
Install writes or merges .cursor/hooks.json and .claude/settings.json with OS-specific shim commands (scripts/gate-hook.ps1 on Windows, scripts/gate-hook.sh on macOS/Linux). By default hooks fail open if Python is missing — use GRAPHSTACK_GATE=strict for teams that prefer blocking over availability.
Framework repo note: This GitHub repo ships
handoff/as templates (empty brief, nodone/tasks). Your installed project fills those files during real work. Before contributing here, reset handoff — see CONTRIBUTING.md.
your-project/
├── .cursor/rules/graphstack.mdc ← always-active rules v4.7.1 (Cursor auto-loads)
├── .cursor/hooks.json ← process gate (merged on reinstall)
├── .cursor/commands/graphstack.md ← `/graphstack` Cursor slash-command bootstrapper
├── orchestrator/
│ ├── ORCHESTRATOR.md ← state machine: all transitions
│ └── TOKEN_OPTIMIZER.md ← token budget rules for all roles
├── .cursor/skills/
│ ├── bootstrapper/BOOTSTRAPPER.md ← new project → module plan → cycles
│ ├── architect/ARCHITECT.md ← scopes features, writes briefs
│ ├── builder/BUILDER.md ← implements exactly the brief
│ ├── reviewer/REVIEWER.md ← checks criteria + graph side effects
│ ├── qa/QA.md ← traces call paths, verifies behavior
│ └── ship/SHIP.md ← checklist + graph update + commit msg
├── handoff/
│ ├── BRIEF.md ← Architect → Builder
│ ├── REVIEW.md ← Reviewer + QA findings (append-only)
│ ├── STATE.md ← human session log (append-only)
│ ├── STATE.json ← machine state for gate hooks
│ ├── BOOTSTRAP.md ← cross-cycle project memory
│ └── board/
│ ├── todo/ ← tasks waiting to be claimed
│ ├── doing/ ← tasks in progress
│ └── done/ ← completed tasks (audit trail)
├── graphify-out/ ← generated by graphify (commit this)
│ ├── GRAPH_REPORT.md
│ ├── graph.json
│ └── graph.html
├── scripts/
│ ├── board.sh ← GNAP board shim (bash)
│ ├── board.ps1 ← GNAP board shim (PowerShell)
│ ├── post-commit ← smart graph-update hook (bash)
│ ├── post-commit.ps1 ← smart graph-update hook (PowerShell)
│ └── graphstack/ ← Python core (single source of truth)
│ ├── board.py ← GNAP board logic
│ ├── installer.py ← project installer logic
│ ├── hook.py ← post-commit graph-update logic
│ ├── platform_utils.py ← OS detection, Python finder, encoding-safe echo
│ ├── cli.py ← entry point dispatcher
│ ├── validate.py ← layout / brief / graph / hooks checks
│ ├── gate.py ← process gate (R1–R6)
│ ├── state.py ← handoff/STATE.json
│ ├── cycle.py ← cycle start / enter-builder
│ ├── brief_utils.py ← shared BRIEF/REVIEW helpers
│ ├── graph.py ← graphify query wrappers
│ ├── run.py ← shell runner with compaction
│ ├── compact/ ← git / pytest / generic compactors
│ └── tests/ ← pytest suite
├── pyproject.toml ← pip install -e . (v4.1+)
├── .graphifyignore ← code-focused graph for this repo
GraphStack uses Git-Native Agent Protocol for task tracking — no server, no database, just files and git commits.
All three forms below are equivalent. Pick whichever fits your shell.
bash scripts/board.sh status
bash scripts/board.sh new add-oauth Add OAuth login with GitHub
bash scripts/board.sh claim add-oauth builder
bash scripts/board.sh complete add-oauth
bash scripts/board.sh log.\scripts\board.ps1 status .\scripts\board.ps1 new add-oauth Add OAuth login with GitHub .\scripts\board.ps1 claim add-oauth builder .\scripts\board.ps1 complete add-oauth .\scripts\board.ps1 log
Preferred — full cycle handoff (v4.7):
python -m graphstack cycle start add-oauth "Add OAuth login with GitHub" # Architect writes handoff/BRIEF.md → Status: Ready for Builder python -m graphstack cycle enter-builder add-oauth # … implement → enter-reviewer → enter-qa → enter-ship → cycle close
Low-level board (still supported):
python -m graphstack board status
python -m graphstack board new add-oauth Add OAuth login with GitHub
python -m graphstack board claim add-oauth builder
python -m graphstack board complete add-oauth
python -m graphstack board log
python -m graphstack run -- git status
python -m graphstack doctor
python -m graphstack validate --strict --fail-stale-graphEvery board operation is a git commit. git log handoff/board/ shows who did what, when.
GraphStack's Ship role manages graph updates automatically at the end of every cycle:
| Condition | Action |
|---|---|
| Files were added or deleted this cycle | Always update |
| Bootstrap cycle completed | Always update (next brief needs fresh graph) |
| Content-only edits (bug fixes, refactors) | Skip — graph topology unchanged |
The post-commit hook enforces the same rules automatically. You never need to think about when to update.
| Project type | Suitability | Notes |
|---|---|---|
| REST / GraphQL API | ⭐⭐⭐⭐⭐ | Best fit — clear module boundaries |
| Monolithic web app | ⭐⭐⭐⭐⭐ | God node protection is critical here |
| Data pipeline / ETL | ⭐⭐⭐⭐⭐ | Graph mirrors pipeline topology |
| Library / SDK | ⭐⭐⭐⭐⭐ | Breaking change detection is precise |
| Microservice (single) | ⭐⭐⭐⭐⭐ | Integration edges clearly visible |
| CLI tool | ⭐⭐⭐⭐ | Good for medium+ complexity |
| Serverless / Lambda | ⭐⭐⭐⭐ | Shared util blast radius visible |
| Admin panel | ⭐⭐⭐⭐ | State + API integration coverage |
| Game server (backend) | ⭐⭐⭐⭐ | State machine edges map well |
| DevOps / automation | ⭐⭐⭐⭐ | Script dependency tracking |
| React / Vue SPA | ⭐⭐⭐ | Good, but UI churn increases update frequency |
| TypeScript monorepo | ⭐⭐⭐ | Cross-package deps very valuable |
| Mobile app (React Native) | ⭐⭐⭐ | JS/TS layer fully covered |
| Unity game (C#) | ⭐⭐⭐ | God node protection excellent |
| E-commerce backend | ⭐⭐⭐ | Checkout flow blast radius useful |
| AI / embedding pipeline | ⭐⭐⭐ | Static structure good; runtime behavior not |
| Flutter app | ⭐⭐ | Dart supported; widget tree less useful |
| Rapid prototype | ⭐⭐ | Brief discipline adds friction at this stage |
| Static site | ⭐ | Minimal dependencies — low graph value |
| Single-file script | ⭐ | No graph structure to analyze |
Rule of thumb: GraphStack pays off when your codebase exceeds ~20 files and queries regularly cross module boundaries.
| GraphStack | gstack | loki-mode | code-review-graph | |
|---|---|---|---|---|
| Knowledge graph | ✅ Graphify | ❌ | ❌ | ✅ |
| Auto role transitions | ✅ | ❌ manual | ✅ complex | ❌ |
| Bootstrap (0→project) | ✅ | ❌ | ❌ | ❌ |
| Git-native task board | ✅ GNAP | ❌ | ❌ | ❌ |
| Session resumability | ✅ STATE.md | ❌ | ❌ | ❌ |
| Token optimization rules | ✅ explicit | ❌ | ❌ | ✅ partial |
Cursor /graphstack slash bootstrap |
✅ | ❌ | ❌ | ❌ |
| Setup complexity | Low | Low | High | Low |
Default (Cursor Composer with GraphStack repo open): reopen chat and paste a short cue such as "Resume GraphStack STATE.md" or select /graphstack followed by "Resume" — Activation still runs tokens + graph loaders automatically.
Classic explicit prompt:
Read orchestrator/ORCHESTRATOR.md and follow it exactly.
Resume from last session.
Orchestrator reads handoff/STATE.md and handoff/board/doing/ and picks up exactly where it left off.
Quick path: describe work directly (rules + optional /graphstack). Legacy blocks remain for deterministic copy/paste workflows or non‑Cursor tooling.
Read orchestrator/ORCHESTRATOR.md and follow it exactly.
[What you want to build or fix — any language]
Read orchestrator/ORCHESTRATOR.md and follow it exactly.
This is a new project with no existing codebase.
I want to build [describe your idea].
Tech stack: [language, framework, database].
Read orchestrator/ORCHESTRATOR.md and follow it exactly.
Resume from last session.
Use these when you want a single role without the full lifecycle:
Architect — plan and scope only, no building
Read .cursor/skills/architect/ARCHITECT.md and follow it exactly.
Read orchestrator/TOKEN_OPTIMIZER.md for token rules.
[What you want to plan]
Builder — build directly from an existing brief
Read .cursor/skills/builder/BUILDER.md and follow it exactly.
Read orchestrator/TOKEN_OPTIMIZER.md for token rules.
Brief is in handoff/BRIEF.md. Start building.
Reviewer — review existing code or a diff
Read .cursor/skills/reviewer/REVIEWER.md and follow it exactly.
Read orchestrator/TOKEN_OPTIMIZER.md for token rules.
Review the changes in [filename or "the last git diff"].
QA — trace and verify a specific feature
Read .cursor/skills/qa/QA.md and follow it exactly.
Read orchestrator/TOKEN_OPTIMIZER.md for token rules.
Trace and verify [feature name].
Ship — run pre-deploy checklist
Read .cursor/skills/ship/SHIP.md and follow it exactly.
Run the pre-ship checklist for task [task-id].
Bootstrapper — decompose an idea into a module plan only
Read .cursor/skills/bootstrapper/BOOTSTRAPPER.md and follow it exactly.
Read orchestrator/TOKEN_OPTIMIZER.md for token rules.
[Describe your project idea]
Note:
.cursor/rules/graphstack.mdcis loaded automatically by Cursor on every session. You never need to reference it manually.
| Tool | Orchestrator | Manual roles |
|---|---|---|
| Cursor | ✅ Full (.mdc auto-loads) | ✅ |
| Claude Code | ✅ Full | ✅ |
| VS Code Copilot Chat | ✅ Full | ✅ |
| GitHub Copilot CLI | ✅ | |
| Aider | ✅ |
demo/DEMO_WALKTHROUGH.md — full end-to-end walkthrough: adding rate limiting to a Node.js auth service, showing every automatic transition, graph query, and board update.
See CONTRIBUTING.md. GraphStack is just markdown and bash — the barrier is intentionally low.
MIT — free forever. No telemetry. No accounts. No phoning home.