{"id":50771966,"url":"https://github.com/mertcapkin/graphstack","last_synced_at":"2026-06-11T20:00:18.730Z","repository":{"id":356145814,"uuid":"1231260815","full_name":"MertCapkin/GraphStack","owner":"MertCapkin","description":"Graph-first, automatically orchestrated AI development workflow. One prompt starts the entire lifecycle — from blank repo to production.","archived":false,"fork":false,"pushed_at":"2026-06-11T17:25:59.000Z","size":625,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-11T18:16:48.294Z","etag":null,"topics":["ai-development","claude","claude-ai","claude-code","craft","cursor","cursor-ai","cursor-ide","cursor-rules","god-node","graph","graph-first","graph-node","graphify","graphstack","node","orchestrator","stack","vibe-coding","workflow"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MertCapkin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T19:43:35.000Z","updated_at":"2026-06-11T17:17:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MertCapkin/GraphStack","commit_stats":null,"previous_names":["mertcapkin/graphstack"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/MertCapkin/GraphStack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MertCapkin%2FGraphStack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MertCapkin%2FGraphStack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MertCapkin%2FGraphStack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MertCapkin%2FGraphStack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MertCapkin","download_url":"https://codeload.github.com/MertCapkin/GraphStack/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MertCapkin%2FGraphStack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34215254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-development","claude","claude-ai","claude-code","craft","cursor","cursor-ai","cursor-ide","cursor-rules","god-node","graph","graph-first","graph-node","graphify","graphstack","node","orchestrator","stack","vibe-coding","workflow"],"created_at":"2026-06-11T20:00:16.785Z","updated_at":"2026-06-11T20:00:18.550Z","avatar_url":"https://github.com/MertCapkin.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# GraphStack 🧠⚡\n\n**Graph-first, automatically orchestrated AI development workflow.**  \nOne prompt starts the entire lifecycle — from blank repo to production.\n\n[![CI](https://github.com/MertCapkin/graphstack/actions/workflows/ci.yml/badge.svg)](https://github.com/MertCapkin/graphstack/actions)\n[![PyPI](https://img.shields.io/pypi/v/MertCapkin_GraphStack)](https://pypi.org/project/MertCapkin_GraphStack/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-success)](#compatibility)\n[![Works with Cursor](https://img.shields.io/badge/Works%20with-Cursor-blue)](https://cursor.sh)\n[![Works with Claude Code](https://img.shields.io/badge/Works%20with-Claude%20Code-orange)](https://claude.ai/code)\n\n\u003c/div\u003e\n\n\u003e **v4.5 highlights:** Published on [PyPI](https://pypi.org/project/MertCapkin_GraphStack/) as **`MertCapkin_GraphStack`**, one-command bootstrap, `board reopen` / `list-done`. Plus v4.4 `graph query` + `init`, v4.3 gate. See [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## One command (Cursor terminal)\n\nOpen your **project folder** in Cursor, open the integrated terminal, and run:\n\n**Windows (PowerShell) — recommended:**\n```powershell\nirm https://raw.githubusercontent.com/MertCapkin/GraphStack/master/scripts/bootstrap.ps1 | iex\n```\n\n**macOS / Linux:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MertCapkin/GraphStack/master/scripts/bootstrap.sh | bash\n```\n\n**Or install from PyPI directly:**\n\n\u003e Package: **`MertCapkin_GraphStack`** on [PyPI](https://pypi.org/project/MertCapkin_GraphStack/) (`graphstack` name was taken). CLI command: **`graphstack`**.\n\n```bash\npip install \"MertCapkin_GraphStack[graphify]\"\ngraphstack init . -y --install-deps\n```\n\nThis 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.\n\n---\n\n## Quick Start\n\n### Step 1 — Install GraphStack (PyPI)\n\n**Python 3.8+** and **Git** are required.\n\n```bash\npy -3 --version\ngit --version\n```\n\nInstall GraphStack + Graphify from PyPI, then initialize **your project** (run inside your project folder):\n\n```bash\npip install \"MertCapkin_GraphStack[graphify]\"\ngraphstack init . -y --install-deps\n```\n\nOr use the [one-command bootstrap](#one-command-cursor-terminal) above (same result; installs from PyPI, falls back to GitHub if needed).\n\nVerify:\n\n```bash\ngraphstack --version\ngraphstack doctor\npip show graphifyy\n```\n\n\u003e **PyPI:** [pypi.org/project/MertCapkin_GraphStack](https://pypi.org/project/MertCapkin_GraphStack/)  \n\u003e **CLI name:** `graphstack` (unchanged — only the pip package name differs)\n\nGraphify runs **entirely locally** — tree-sitter AST, no API calls for code graphs.\n\n---\n\n### Step 1 (alternative) — Manual Graphify only\n\nIf you prefer to install Graphify separately first:\n\n```bash\npip install \"graphifyy\u003e=0.7,\u003c0.9\"\ngraphify cursor install\npip install \"MertCapkin_GraphStack[graphify]\"\ngraphstack init . -y --install-deps\n```\n\n---\n\n### Step 2 — Install from source (contributors / offline)\n\nFor hacking on GraphStack itself or air-gapped installs, clone the repo instead of PyPI:\n\n```bash\ngit clone https://github.com/MertCapkin/graphstack /tmp/graphstack\ncd /path/to/your-project\nbash /tmp/graphstack/install.sh\n# or, equivalently:\n# python3 -m graphstack install . --no-interactive\n```\n\n#### Windows (PowerShell — native, no Git Bash needed)\n\n```powershell\ngit clone https://github.com/MertCapkin/graphstack $env:TEMP\\graphstack\ncd C:\\path\\to\\your-project\n\u0026 $env:TEMP\\graphstack\\install.ps1 .\n```\n\nIf `python.exe` on Windows redirects you to the Microsoft Store, the installer detects that and falls back to the official `py -3` launcher automatically.\n\n#### Any platform (Python, no shell preference)\n\n```bash\ngit clone https://github.com/MertCapkin/graphstack /path/to/graphstack\ncd /path/to/your-project\npython -m graphstack install . --non-interactive\n```\n\nThis copies all GraphStack files into your project:\n- `.cursor/rules/graphstack.mdc` — Cursor loads this automatically on every session\n- `orchestrator/`, `.cursor/skills/`, `handoff/`, `scripts/` — the full workflow system\n- `scripts/graphstack/` — the Python helper package (used by both the bash and PowerShell shims)\n\nThe install script is non-destructive: it won't overwrite existing `handoff/BRIEF.md`, `handoff/REVIEW.md`, or `handoff/BOOTSTRAP.md` if they already exist.\n\n---\n\n### Step 3 — Build the knowledge graph\n\nOpen your project in Cursor. In the chat, type:\n\n```\n/graphify .\n```\n\nWhat happens:\n- Graphify scans all source files (25 languages supported)\n- Builds a dependency graph using tree-sitter (local, no API)\n- Creates three files in `graphify-out/`:\n  - `GRAPH_REPORT.md` — human-readable architecture summary\n  - `graph.json` — machine-queryable full graph\n  - `graph.html` — visual explorer, open in browser\n\n**How long does it take?**\n\n| Codebase size | Time |\n|---|---|\n| \u003c 50 files | ~5 seconds |\n| 50–200 files | ~15–30 seconds |\n| 200–500 files | ~1–2 minutes |\n| 500+ files | ~3–5 minutes |\n\nRun this once. After that, use `/graphify --update` — it only re-scans changed files and takes a few seconds.\n\n**New project with no code yet?** Skip this step — GraphStack's Bootstrap Mode handles it.\n\n**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.\n\n---\n\n### Step 4 — Start working\n\nThe repo ships two ways to bootstrap the orchestrator — pick whichever feels natural.\n\n#### A) Easiest — new chat only (recommended)\n\nBecause `.cursor/rules/graphstack.mdc` is **`alwaysApply: true`**, every new Composer / Agent\nsession already carries GraphStack’s binding rules. Simply open chat and describe your goal in\nnatural language (`Add …`, `Fix …`). The assistant’s first turn must still **execute**\n`orchestrator/ORCHESTRATOR.md → Activation** (parallel `TOKEN_OPTIMIZER` + `GRAPH_REPORT`),\nbut **you don’t paste** `Read orchestrator/...` anymore.\n\n#### B) Slash command `/graphstack` (explicit nudge)\n\nIn Cursor Chat/Composer press `/` → choose **`graphstack`**. That injects the Bootstrap command\nstored in `.cursor/commands/graphstack.md` (helps when you want deterministic orchestrator wording\nor onboarding teammates).\n\n*If `/graphstack` doesn't appear immediately, restart Cursor once so it rescans `.cursor/commands/`.*\n\n#### C) Classic explicit prompt (fallback / other tools)\n\n**Existing codebase:**\n\n```\nRead orchestrator/ORCHESTRATOR.md and follow it exactly.\n[Describe what you want to build or fix]\n```\n\n**New project from scratch:**\n\n```\nRead orchestrator/ORCHESTRATOR.md and follow it exactly.\nThis is a new project with no existing codebase.\nI want to build [describe your idea].\nTech stack: [language, framework, database].\n```\n\nGraphStack handles everything from here — planning, building, reviewing, testing, shipping.\n\n---\n\n## What Is GraphStack?\n\nGraphStack combines two ideas into one installable system:\n\n**[Graphify](https://github.com/safishamsi/graphify)** builds a queryable knowledge graph of your codebase. Every AI query navigates that compact map instead of re-reading raw files from scratch.\n\n**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.\n\n\u003e You write one prompt. GraphStack runs the full cycle.\n\n---\n\n## The Problem\n\nWithout GraphStack, every AI coding session looks like this:\n\n```\nYou:  \"Add rate limiting to login.\"\nAI:   reads login.ts... reads session.ts... reads crypto.ts... reads types.ts...\n      (4 files, ~3 000 tokens — before writing a single line)\n\nYou:  \"Now add tests.\"\nAI:   reads login.ts again... reads session.ts again...\n      (same files, same cost, zero memory)\n```\n\nProblems:\n- **Token waste** — AI re-reads your codebase on every query\n- **No structure** — planning, coding, reviewing blur together\n- **No memory** — closing Cursor means starting from zero\n- **No audit trail** — impossible to know what was decided and why\n\n---\n\n## The Solution\n\n```\nStep 1 — once:\n  /graphify .  →  graphify-out/GRAPH_REPORT.md + graph.json\n\nStep 2 — every session (minimal typing):\n  Open Composer + describe the task (rules already activate GraphStack automatically),\n  optionally type `/graphstack` once for an explicit orchestrator preamble,\n  or paste the legacy `Read orchestrator/ORCHESTRATOR.md …` snippet if working outside Cursor.\n\nExample natural-language kickoff:\n  \"Add rate limiting to login.\"\n\n  [ARCHITECT]   reads graph (not raw files) → scopes change → writes BRIEF.md\n       ↓ auto\n  [BUILDER]     reads brief → queries graph for deps → builds exactly the brief\n       ↓ auto\n  [REVIEWER]    checks criteria → inspects graph neighbors for side effects\n       ↓ auto   (loops to Builder if rejected, max 3×)\n  [QA]          traces call path through graph → verifies behavior\n       ↓ auto\n  [SHIP]        checklist → graph update → commit message → closes board task\n```\n\n**Zero manual role switching. Zero repeated file reads. Full git audit trail.**\n\n---\n\n## Bootstrap Mode — Start from Zero\n\nNo code yet? GraphStack handles that too.\n\n```\nComposer (Cursor):\n  Describe the product + tech stack naturally (alwaysApply rules bootstrap GraphStack),\n  optionally `/graphstack` beforehand to inject the scripted opener.\n\nBootstrap example:\n\"/graphstack then: New project REST API for task mgmt — TS, Express, PostgreSQL.\"\n\n  [BOOTSTRAPPER]  analyzes idea → decomposes into modules → orders by dependency\n                  → writes BOOTSTRAP.md (the memory across all cycles)\n                  → writes Cycle 1 brief\n       ↓ auto\n  [BUILDER → REVIEWER → QA → SHIP]   Cycle 1 (auth module)\n       ↓\n  run /graphify .                    ← first graph from real code\n       ↓\n  [BOOTSTRAPPER]  reads new graph → writes Cycle 2 brief with real knowledge\n       ↓ auto\n  [BUILDER → REVIEWER → QA → SHIP]   Cycle 2 (data models)\n       ↓\n  run /graphify --update  →  next cycle  →  ...\n```\n\nEach brief is written with knowledge of what was **actually built** — not just planned. The graph grows with the project.\n\n---\n\n## Token Savings\n\nGraphStack's savings come from three mechanisms:\n\n| Mechanism | How | Savings |\n|-----------|-----|---------|\n| Graph-first reads | GRAPH_REPORT.md replaces browsing 10+ files | ~85% on architecture queries |\n| Role discipline | Each role reads only what its job requires | ~60% vs unstructured sessions |\n| File-based state | STATE.md replaces chat history on resume | ~60% per new session |\n| Parallel reads | Multiple files in one tool call | ~50% on multi-file ops |\n| Shell compaction | `graphstack run` shrinks git/test output before it hits context | ~60–80% on verbose shell ops |\n\n**Net savings by codebase size:**\n\n| Codebase | Tokens/day without | Tokens/day with | Saving |\n|----------|--------------------|-----------------|--------|\n| Small (10–20 files) | ~40k | ~28k | **~30%** |\n| Medium (50–100 files) | ~180k | ~54k | **~70%** |\n| Large (200+ files) | ~600k | ~90k | **~85%** |\n| Very large (500+ files) | ~1.5M | ~180k | **~88%** |\n\n*Estimates based on Graphify benchmarks and TOKEN_OPTIMIZER rules. Real savings depend on query patterns. See [docs/case-studies/graphstack-self.md](docs/case-studies/graphstack-self.md) for an honest self-analysis — measured community benchmarks are welcome via PR.*\n\n---\n\n## Limitations (read before adopting)\n\nGraphStack is a **workflow protocol** (markdown + handoff files), not a runtime that enforces AI behavior.\n\n| Topic | Reality |\n|-------|---------|\n| Role automation | Prompts alone cannot guarantee discipline. v4.3+ **`graphstack gate`** + v4.4 Cursor **`preToolUse`**. Hooks block commits and (on Cursor/Claude) code writes without a claimed task; `afterFileEdit` on Cursor remains advisory-only backup. |\n| Token savings | The table above is **estimated**, not guaranteed. Small repos or undisciplined sessions may use **more** tokens than unstructured chat. |\n| 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). |\n| Setup | Graphify + `pip install MertCapkin_GraphStack` + `graphstack init` — or one bootstrap command. See [PyPI](https://pypi.org/project/MertCapkin_GraphStack/). |\n\n**v4.1 helpers:** `graphstack doctor` (health report) and `graphstack validate` (exit code for CI). Use `--strict` before Builder handoff; use `--fail-stale-graph` in CI after code changes.\n\n```bash\ngraphstack doctor\ngraphstack validate\ngraphstack validate --strict --fail-stale-graph\n```\n\n---\n\n## Shell Output Compaction (`graphstack run`)\n\nGraph-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.\n\n**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.\n\n```bash\npython -m graphstack run -- git status\npython -m graphstack run -- git diff\npython -m graphstack run -- git log -n 20\npython -m graphstack run -- pytest -q\n```\n\n**Quality safeguards (not “blind compression”):**\n\n- File paths, branch names, diff hunks (`@@`), and `+`/`-` lines are preserved\n- Test failures, tracebacks, and stderr are kept (stderr is never compacted)\n- If compaction would drop too much signal, output **falls back to raw** automatically\n- Full output when debugging: `python -m graphstack run --raw -- git diff`\n\nIndependent Python implementation (MIT) — inspired by common agent-tooling patterns, no RTK dependency or vendored code.\n\n`graphstack doctor` reports whether the compact module is installed in your project.\n\n---\n\n## Graph Queries (`graphstack graph`)\n\nGraph-first rules mean **query the graph before opening raw files**. v4.4 wraps Graphify's CLI so agents use one consistent command:\n\n```bash\npython -m graphstack graph query \"who calls login\"\npython -m graphstack graph query \"blast radius of crypto.ts\" --budget 1500\npython -m graphstack graph path src/auth/login.ts src/utils/crypto.ts\npython -m graphstack graph explain \"login()\"\npython -m graphstack graph update .     # AST-only refresh after code changes\n```\n\nRequires `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.\n\n---\n\n## Process Gate (`graphstack gate`)\n\nv4.3+ adds **mechanical enforcement** so Architect → Builder → Reviewer steps are harder to skip silently. v4.4 extends Cursor with `preToolUse` blocking.\n\n| Rule | What it blocks | Cursor | Claude Code |\n|------|----------------|--------|-------------|\n| R1 | `git commit` touching code while `doing/` is empty | deny (`beforeShellExecution` + `preToolUse` Shell) | deny (`PreToolUse` Bash) |\n| R2 | Edit/Write on code paths while `doing/` is empty | deny (`preToolUse` Write/Edit) | deny (`PreToolUse` Edit/Write) |\n| R3 | Commit while `BRIEF.md` is still the template | deny | deny |\n| R4 | `STATE.json` not updated this cycle | advisory (`stop`) | advisory (`Stop`) |\n| — | Edit already applied (legacy hook) | advisory only (`afterFileEdit`) | — |\n\n```bash\npython -m graphstack gate check          # CI / manual — exit 1 on violation\npython -m graphstack state set --role builder --task my-feature\nGRAPHSTACK_GATE=off                      # emergency bypass (one session)\nGRAPHSTACK_GATE=strict                   # fail-closed on hook internal errors\n```\n\n**Install** writes `.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.\n\n\u003e **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](CONTRIBUTING.md).\n\n---\n\n## What Gets Installed\n\n```\nyour-project/\n├── .cursor/rules/graphstack.mdc          ← always-active rules (Cursor auto-loads)\n├── .cursor/commands/graphstack.md        ← `/graphstack` Cursor slash-command bootstrapper\n├── orchestrator/\n│   ├── ORCHESTRATOR.md                   ← state machine: all transitions\n│   └── TOKEN_OPTIMIZER.md                ← token budget rules for all roles\n├── .cursor/skills/\n│   ├── bootstrapper/BOOTSTRAPPER.md      ← new project → module plan → cycles\n│   ├── architect/ARCHITECT.md            ← scopes features, writes briefs\n│   ├── builder/BUILDER.md                ← implements exactly the brief\n│   ├── reviewer/REVIEWER.md              ← checks criteria + graph side effects\n│   ├── qa/QA.md                          ← traces call paths, verifies behavior\n│   └── ship/SHIP.md                      ← checklist + graph update + commit msg\n├── handoff/\n│   ├── BRIEF.md                          ← Architect → Builder\n│   ├── REVIEW.md                         ← Reviewer + QA findings (append-only)\n│   ├── STATE.md                          ← session state for resuming\n│   ├── BOOTSTRAP.md                      ← cross-cycle project memory\n│   └── board/\n│       ├── todo/                         ← tasks waiting to be claimed\n│       ├── doing/                        ← tasks in progress\n│       └── done/                         ← completed tasks (audit trail)\n├── graphify-out/                         ← generated by graphify (commit this)\n│   ├── GRAPH_REPORT.md\n│   ├── graph.json\n│   └── graph.html\n├── scripts/\n│   ├── board.sh                          ← GNAP board shim (bash)\n│   ├── board.ps1                         ← GNAP board shim (PowerShell)\n│   ├── post-commit                       ← smart graph-update hook (bash)\n│   ├── post-commit.ps1                   ← smart graph-update hook (PowerShell)\n│   └── graphstack/                       ← Python core (single source of truth)\n│       ├── board.py                      ← GNAP board logic\n│       ├── installer.py                  ← project installer logic\n│       ├── hook.py                       ← post-commit graph-update logic\n│       ├── platform_utils.py             ← OS detection, Python finder, encoding-safe echo\n│       ├── cli.py                        ← entry point dispatcher\n│       ├── validate.py                   ← layout / brief / graph checks\n│       ├── run.py                        ← shell runner with compaction\n│       ├── compact/                      ← git / pytest / generic compactors\n│       └── tests/                        ← pytest suite\n├── pyproject.toml                        ← pip install -e . (v4.1+)\n├── .graphifyignore                       ← code-focused graph for this repo\n```\n\n---\n\n## The GNAP Board\n\nGraphStack uses Git-Native Agent Protocol for task tracking — no server, no database, just files and git commits.\n\nAll three forms below are equivalent. Pick whichever fits your shell.\n\n#### macOS / Linux (bash)\n\n```bash\nbash scripts/board.sh status\nbash scripts/board.sh new add-oauth Add OAuth login with GitHub\nbash scripts/board.sh claim add-oauth builder\nbash scripts/board.sh complete add-oauth\nbash scripts/board.sh log\n```\n\n#### Windows (PowerShell)\n\n```powershell\n.\\scripts\\board.ps1 status\n.\\scripts\\board.ps1 new add-oauth Add OAuth login with GitHub\n.\\scripts\\board.ps1 claim add-oauth builder\n.\\scripts\\board.ps1 complete add-oauth\n.\\scripts\\board.ps1 log\n```\n\n#### Cross-platform (any shell with Python)\n\n```bash\npython -m graphstack board status\npython -m graphstack board new add-oauth Add OAuth login with GitHub\npython -m graphstack board claim add-oauth builder\npython -m graphstack board complete add-oauth\npython -m graphstack board log\npython -m graphstack run -- git status\npython -m graphstack doctor\npython -m graphstack validate --fail-stale-graph\n```\n\nEvery board operation is a git commit. `git log handoff/board/` shows who did what, when.\n\n---\n\n## Graph Update Strategy\n\nGraphStack's Ship role manages graph updates automatically at the end of every cycle:\n\n| Condition | Action |\n|-----------|--------|\n| Files were **added or deleted** this cycle | Always update |\n| Bootstrap cycle completed | Always update (next brief needs fresh graph) |\n| Content-only edits (bug fixes, refactors) | Skip — graph topology unchanged |\n\nThe post-commit hook enforces the same rules automatically. You never need to think about when to update.\n\n---\n\n## Project Suitability\n\n| Project type | Suitability | Notes |\n|---|---|---|\n| REST / GraphQL API | ⭐⭐⭐⭐⭐ | Best fit — clear module boundaries |\n| Monolithic web app | ⭐⭐⭐⭐⭐ | God node protection is critical here |\n| Data pipeline / ETL | ⭐⭐⭐⭐⭐ | Graph mirrors pipeline topology |\n| Library / SDK | ⭐⭐⭐⭐⭐ | Breaking change detection is precise |\n| Microservice (single) | ⭐⭐⭐⭐⭐ | Integration edges clearly visible |\n| CLI tool | ⭐⭐⭐⭐ | Good for medium+ complexity |\n| Serverless / Lambda | ⭐⭐⭐⭐ | Shared util blast radius visible |\n| Admin panel | ⭐⭐⭐⭐ | State + API integration coverage |\n| Game server (backend) | ⭐⭐⭐⭐ | State machine edges map well |\n| DevOps / automation | ⭐⭐⭐⭐ | Script dependency tracking |\n| React / Vue SPA | ⭐⭐⭐ | Good, but UI churn increases update frequency |\n| TypeScript monorepo | ⭐⭐⭐ | Cross-package deps very valuable |\n| Mobile app (React Native) | ⭐⭐⭐ | JS/TS layer fully covered |\n| Unity game (C#) | ⭐⭐⭐ | God node protection excellent |\n| E-commerce backend | ⭐⭐⭐ | Checkout flow blast radius useful |\n| AI / embedding pipeline | ⭐⭐⭐ | Static structure good; runtime behavior not |\n| Flutter app | ⭐⭐ | Dart supported; widget tree less useful |\n| Rapid prototype | ⭐⭐ | Brief discipline adds friction at this stage |\n| Static site | ⭐ | Minimal dependencies — low graph value |\n| Single-file script | ⭐ | No graph structure to analyze |\n\n**Rule of thumb:** GraphStack pays off when your codebase exceeds ~20 files and queries regularly cross module boundaries.\n\n---\n\n## Comparison\n\n| | GraphStack | gstack | loki-mode | code-review-graph |\n|---|---|---|---|---|\n| Knowledge graph | ✅ Graphify | ❌ | ❌ | ✅ |\n| Auto role transitions | ✅ | ❌ manual | ✅ complex | ❌ |\n| Bootstrap (0→project) | ✅ | ❌ | ❌ | ❌ |\n| Git-native task board | ✅ GNAP | ❌ | ❌ | ❌ |\n| Session resumability | ✅ STATE.md | ❌ | ❌ | ❌ |\n| Token optimization rules | ✅ explicit | ❌ | ❌ | ✅ partial |\n| Cursor `/graphstack` slash bootstrap | ✅ | ❌ | ❌ | ❌ |\n| Setup complexity | Low | Low | High | Low |\n\n---\n\n## Resuming a Session\n\nDefault (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.\n\nClassic explicit prompt:\n\n```\nRead orchestrator/ORCHESTRATOR.md and follow it exactly.\nResume from last session.\n```\n\nOrchestrator reads `handoff/STATE.md` and `handoff/board/doing/` and picks up exactly where it left off.\n\n---\n\n## All Prompts\n\n**Quick path:** describe work directly (rules + optional `/graphstack`). Legacy blocks remain for deterministic copy/paste workflows or non‑Cursor tooling.\n\n### Standard session *(legacy explicit)*\n```\nRead orchestrator/ORCHESTRATOR.md and follow it exactly.\n[What you want to build or fix — any language]\n```\n\n### New project from scratch *(legacy explicit)*\n```\nRead orchestrator/ORCHESTRATOR.md and follow it exactly.\nThis is a new project with no existing codebase.\nI want to build [describe your idea].\nTech stack: [language, framework, database].\n```\n\n### Resume a previous session *(legacy explicit)*\n```\nRead orchestrator/ORCHESTRATOR.md and follow it exactly.\nResume from last session.\n```\n\n### Manual role activation (advanced)\n\nUse these when you want a single role without the full lifecycle:\n\n**Architect** — plan and scope only, no building\n```\nRead .cursor/skills/architect/ARCHITECT.md and follow it exactly.\nRead orchestrator/TOKEN_OPTIMIZER.md for token rules.\n[What you want to plan]\n```\n\n**Builder** — build directly from an existing brief\n```\nRead .cursor/skills/builder/BUILDER.md and follow it exactly.\nRead orchestrator/TOKEN_OPTIMIZER.md for token rules.\nBrief is in handoff/BRIEF.md. Start building.\n```\n\n**Reviewer** — review existing code or a diff\n```\nRead .cursor/skills/reviewer/REVIEWER.md and follow it exactly.\nRead orchestrator/TOKEN_OPTIMIZER.md for token rules.\nReview the changes in [filename or \"the last git diff\"].\n```\n\n**QA** — trace and verify a specific feature\n```\nRead .cursor/skills/qa/QA.md and follow it exactly.\nRead orchestrator/TOKEN_OPTIMIZER.md for token rules.\nTrace and verify [feature name].\n```\n\n**Ship** — run pre-deploy checklist\n```\nRead .cursor/skills/ship/SHIP.md and follow it exactly.\nRun the pre-ship checklist for task [task-id].\n```\n\n**Bootstrapper** — decompose an idea into a module plan only\n```\nRead .cursor/skills/bootstrapper/BOOTSTRAPPER.md and follow it exactly.\nRead orchestrator/TOKEN_OPTIMIZER.md for token rules.\n[Describe your project idea]\n```\n\n\u003e **Note:** `.cursor/rules/graphstack.mdc` is loaded automatically by Cursor on every session. You never need to reference it manually.\n\n---\n\n## Compatibility\n\n| Tool | Orchestrator | Manual roles |\n|------|-------------|-------------|\n| Cursor | ✅ Full (.mdc auto-loads) | ✅ |\n| Claude Code | ✅ Full | ✅ |\n| VS Code Copilot Chat | ✅ Full | ✅ |\n| GitHub Copilot CLI | ⚠️ Paste per session | ✅ |\n| Aider | ⚠️ Paste per session | ✅ |\n\n---\n\n## Demo\n\n[`demo/DEMO_WALKTHROUGH.md`](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.\n\n---\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). GraphStack is just markdown and bash — the barrier is intentionally low.\n\n---\n\n## License\n\nMIT — free forever. No telemetry. No accounts. No phoning home.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmertcapkin%2Fgraphstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmertcapkin%2Fgraphstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmertcapkin%2Fgraphstack/lists"}