You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**Pytest** — 5 new tests in `test_validate.py` (28 total in suite).
17
+
18
+
### Changed
19
+
-**CI** — `pip install -e .` before tests; `graphstack validate --fail-stale-graph` step; `pyproject.toml` and `validate.py` in required-files manifest.
20
+
-**Installer** — copies `validate.py` into target projects with the Python package.
21
+
22
+
### Fixed
23
+
- N/A (quality-of-life / transparency release).
24
+
25
+
---
26
+
7
27
## [v4.0.0] — 2026-05-16
8
28
9
29
GraphStack v4 is the **cross-platform release**. Windows runs natively in PowerShell (no Git Bash needed), macOS runs without `coreutils`, and the entire workflow logic lives in a single Python package. The `skills/` directory was unified with the post-install `.cursor/skills/` layout so the source repo and an installed project look identical.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,7 +47,7 @@ The `demo/` folder shows GraphStack in action on a Node.js auth service. More de
47
47
### 5. Write a case study
48
48
49
49
Used GraphStack on a real project? Measured token savings? Wrote about it?
50
-
Open a PR adding a `docs/case-studies/` entry or link to your post in the README.
50
+
Open a PR adding a `docs/case-studies/<name>.md` entry (see `docs/case-studies/graphstack-self.md` for the template style) or link to your post in the README.
[](https://cursor.sh)
13
13
[](https://claude.ai/code)
14
14
15
15
</div>
16
16
17
-
> **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](CHANGELOG.md) for the full migration notes.
17
+
> **v4.1 highlights:**`pip install -e .` packaging, `graphstack validate` / `graphstack doctor`, CI graph-staleness checks, code-focused `.graphifyignore`, and an honest limitations + case-study section. See [CHANGELOG.md](CHANGELOG.md).
18
18
19
19
---
20
20
@@ -35,6 +35,11 @@ git --version # any recent version is fine
35
35
pip install -r requirements.txt
36
36
# or, equivalently, install Graphify directly with the same pin:
37
37
pip install "graphifyy>=0.7,<0.9"
38
+
39
+
# Optional: install GraphStack CLI from a clone (board / validate / doctor)
40
+
pip install -e /path/to/graphstack
41
+
# or with Graphify in one step:
42
+
pip install -e "/path/to/graphstack[graphify]"
38
43
```
39
44
40
45
After installation, register the Cursor slash command (one-time):
@@ -290,7 +295,28 @@ GraphStack's savings come from three mechanisms:
290
295
| Large (200+ files) |~600k |~90k |**~85%**|
291
296
| Very large (500+ files) |~1.5M |~180k |**~88%**|
292
297
293
-
*Estimates based on Graphify benchmarks and TOKEN_OPTIMIZER rules. Real savings depend on query patterns.*
298
+
*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.*
299
+
300
+
---
301
+
302
+
## Limitations (read before adopting)
303
+
304
+
GraphStack is a **workflow protocol** (markdown + handoff files), not a runtime that enforces AI behavior.
305
+
306
+
| Topic | Reality |
307
+
|-------|---------|
308
+
| Role automation | The Orchestrator state machine lives in `ORCHESTRATOR.md`. Models can skip Activation or transitions unless you use discipline + `graphstack validate`. |
309
+
| Token savings | The table above is **estimated**, not guaranteed. Small repos or undisciplined sessions may use **more** tokens than unstructured chat. |
310
+
| 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). |
311
+
| Setup | Graphify + GraphStack install + `/graphify` + Cursor — four steps, not zero-config. |
312
+
313
+
**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.
314
+
315
+
```bash
316
+
graphstack doctor
317
+
graphstack validate
318
+
graphstack validate --strict --fail-stale-graph
319
+
```
294
320
295
321
---
296
322
@@ -334,7 +360,10 @@ your-project/
334
360
│ ├── hook.py ← post-commit graph-update logic
335
361
│ ├── platform_utils.py ← OS detection, Python finder, encoding-safe echo
336
362
│ ├── cli.py ← entry point dispatcher
363
+
│ ├── validate.py ← layout / brief / graph checks
337
364
│ └── tests/ ← pytest suite
365
+
├── pyproject.toml ← pip install -e . (v4.1+)
366
+
├── .graphifyignore ← code-focused graph for this repo
338
367
```
339
368
340
369
---
@@ -373,6 +402,8 @@ python -m graphstack board new add-oauth Add OAuth login with GitHub
GraphStack's own repository is mostly **instruction markdown** (~34 tracked source files in the first graph run). That makes it a poor benchmark for token savings on a typical app — but a good honesty check for graph quality.
12
+
13
+
---
14
+
15
+
## Graph quality (before `.graphifyignore`)
16
+
17
+
From `graphify-out/GRAPH_REPORT.md` (full-repo scan):
18
+
19
+
| Metric | Value | Interpretation |
20
+
|--------|-------|----------------|
21
+
| Nodes | 420 | Many are README / prompt code blocks |
| Community cohesion | 0.07–0.12 | Clusters are narrative, not architecture |
24
+
| God nodes |`GraphStack 🧠⚡`, `echo()`, `ORCHESTRATOR`| Meta concepts, not code hubs |
25
+
26
+
**Takeaway:** Running `/graphify .` on the GraphStack repo without ignores produces a **documentation graph**, not a code topology map. Use `.graphifyignore` (shipped in v4.1) or scan only `scripts/graphstack/**/*.py` and `demo/src/**` for actionable structure.
27
+
28
+
---
29
+
30
+
## Token savings — what we can claim today
31
+
32
+
The README percentage table (30%–88%) is an **estimate** based on Graphify benchmarks and TOKEN_OPTIMIZER rules. This repo does not yet ship automated session token logging.
33
+
34
+
| Scenario | Expected effect | Confidence |
35
+
|----------|-----------------|------------|
36
+
| Architecture question on 50+ file API | High savings if agent reads GRAPH_REPORT first | Medium (depends on model compliance) |
37
+
| Single-file bugfix | Low or negative (handoff overhead) | High |
38
+
| Undisciplined session (skips graph, re-reads files) | Negative vs baseline | High |
39
+
| GraphStack meta-repo (mostly .md) | Low graph value | High |
40
+
41
+
**Planned:** Community case studies with real `tokens/day` logs from Cursor or Claude Code exports.
42
+
43
+
---
44
+
45
+
## v4.1 validation workflow (measurable)
46
+
47
+
These checks do not require an LLM:
48
+
49
+
```bash
50
+
pip install -e .
51
+
graphstack doctor # human-readable health report
52
+
graphstack validate # exit 1 on layout errors
53
+
graphstack validate --fail-stale-graph # CI: graph must match HEAD
54
+
```
55
+
56
+
On a fresh clone with template `handoff/BRIEF.md`, `validate` reports **warnings** (template brief). With `--strict`, template brief is an **error** — useful before Builder handoff.
57
+
58
+
---
59
+
60
+
## Recommendations for adopters
61
+
62
+
1.**Commit**`graphify-out/GRAPH_REPORT.md` and `graph.json`; **ignore**`graphify-out/cache/`.
63
+
2. Run `graphstack validate --fail-stale-graph` in CI after code changes.
64
+
3. Use GraphStack on codebases with **20+ files** and clear module boundaries (see README suitability table).
65
+
4. Do not expect the orchestrator state machine to enforce itself — use `validate` + role discipline.
66
+
67
+
---
68
+
69
+
*This case study is part of GraphStack v4.1.0 transparency work. Replace estimates with measured data as contributors submit real projects.*
0 commit comments