Graph-first, automatically orchestrated AI development workflow.
One prompt starts the entire lifecycle — from blank repo to production.
v4 highlights: native Windows PowerShell support (no Git Bash needed), single Python core for board/install/hook logic, tri-OS CI matrix, and 23-test pytest suite. See CHANGELOG.md for the full migration notes.
Python 3.8+ and Git are required. Check if you have them:
py -3 --version # need 3.8 or higher
git --version # any recent version is fineInstall Graphify — the knowledge graph engine GraphStack is built on. The version range is pinned in requirements.txt:
pip install -r requirements.txt
# or, equivalently, install Graphify directly with the same pin:
pip install "graphifyy>=0.7,<0.9"After installation, register the Cursor slash command (one-time):
graphify cursor installVerify it worked:
pip show graphifyyIf graphify is not found after install, try:
pip install --user "graphifyy>=0.7,<0.9"
# then add ~/.local/bin to your PATH, or use:
python3 -m graphify --versionGraphify runs entirely locally — no API calls, no data sent anywhere. It uses tree-sitter to parse your code and builds the graph on your machine.
GraphStack now works natively on Windows, macOS, and Linux. The installer runs through Python (which you already have for Graphify), so no shell-specific tooling is required.
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-interactivegit 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-interactiveThis 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. Just go to Step 4.
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] reads graph (not raw files) → scopes change → writes BRIEF.md
↓ auto
[BUILDER] reads brief → queries graph for deps → 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 |
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.
your-project/
├── .cursor/rules/graphstack.mdc ← always-active rules (Cursor auto-loads)
├── .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 ← session state for resuming
│ ├── 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
│ └── tests/ ← pytest suite
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 logpython -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 logEvery 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.