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 | bash

Or install from PyPI directly:

Package: MertCapkin_GraphStack on PyPI (graphstack name 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 session
• orchestrator/, .cursor/skills/, handoff/, scripts/ — the full workflow system
• scripts/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 summary
  • graph.json — machine-queryable full graph
  • graph.html — visual explorer, open in browser

How long does it take?

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:

Net savings by codebase size:

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.

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.

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, no done/ 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-graph

Every 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:

The post-commit hook enforces the same rules automatically. You never need to think about when to update.

Rule of thumb: GraphStack pays off when your codebase exceeds ~20 files and queries regularly cross module boundaries.

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.mdc is loaded automatically by Cursor on every session. You never need to reference it manually.

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.