GraphCraft is what you install and run in your mobile project. GraphStack is a dependency (cycle, gate, code graph). GraphCraft adds the design intelligence layer without forking GraphStack.

Graphify     → code graph         (graphify-out/)
GraphStack   → orchestration      (cycle, gate, roles)
GraphCraft   → design layer       (graphcraft-out/, design-system/, research/)

Install

Requirements: Python 3.8+, Git, Cursor

pip install "MertCapkin_GraphCraft[graphstack,visual]"

Pin a release:

pip install "MertCapkin_GraphCraft[graphstack] @ git+https://github.com/MertCapkin/GraphCraft.git@v2.4.0"

Quick start (your app repo)

cd C:\path\to\your-mobile-app
graphcraft init . -y --install-deps
graphcraft doctor .
graphcraft design update .

graphcraft init runs GraphStack init then GraphCraft install. You get clean handoff templates, empty graphcraft-out/, and example design files — no cycle history or generated reports.

Typical UI task workflow

1. Architect     → handoff/BRIEF.md
2. Design Strategist → AESTHETIC_BRIEF.md + research pipeline (below)
3. Designer        → design/, design-system/, DESIGN_BRIEF Ready for Builder
4. Design audit    → graphcraft cycle enter-design-audit <task>
5. Builder         → packages/ui-core/ (gated)
6. Visual review   → graphcraft visual review
7. Reviewer → QA → Ship (GraphStack)

Mechanical design commands:

graphcraft cycle start my-feature "Login flow"
graphcraft cycle enter-design-strategist my-feature
# … strategist work …
graphcraft cycle enter-design-audit my-feature
graphcraft cycle enter-builder my-feature

Aesthetic & originality (anti-slop)

# 1. Fill handoff/AESTHETIC_BRIEF.md (identity + signature element)
# 2. Automated research
graphcraft aesthetic research doctor .
graphcraft aesthetic research run . --force
graphcraft aesthetic research distill .

# 3. Evaluate (includes originality score)
graphcraft design evaluate .

Config floors in graphcraft.config.yaml:

aesthetic:
  hard_floors:
    originality_min: 0.45
    originality_warn: 0.65

Google Stitch integration

Three paths — pick one:

A. One-command pull (API — recommended for scripts)

$env:STITCH_API_KEY = "your-key"
# graphcraft.config.yaml → stitch.project_id: "<numeric-project-id>"

graphcraft stitch doctor .
graphcraft stitch pull . --force

Uses official @google/stitch-sdk via npx. Downloads screens → .stitch/ → design graph.

B. MCP (Cursor agent in chat)

graphcraft stitch mcp install
graphcraft stitch mcp doctor
# Authenticate: gcloud auth application-default login
# Use Stitch MCP tools in Cursor, then:
graphcraft stitch import .

C. Manual export

graphcraft stitch fetch --export-dir C:\path\to\stitch-export
graphcraft stitch import .
graphcraft stitch report .

Set design_source: stitch|hybrid in graphcraft.config.yaml.

Design graph

graphcraft design update .              # build graph
graphcraft design query "screens"       # keyword query
graphcraft design bridge                # design ↔ code map
graphcraft design unified "login flow"  # design + bridge
graphcraft design validate
graphcraft design harmony

Output: graphcraft-out/design-graph.json, DESIGN_REPORT.md

UI library (four stacks)

graphcraft ui tokens emit rn
graphcraft ui validate all

Commands reference

Full GraphStack commands: python -m graphstack --help

Configuration

profile: mobile-app              # mobile-app | mobile-game
design_source: native            # native | stitch | hybrid
active_stack: react-native

design:
  style: style:minimal-dark
  touch_target_min: 44

aesthetic:
  priority: balanced             # marketing | usability | balanced
  research_enabled: true
  max_research_queries: 5
  hard_floors:
    contrast_min: 4.5
    originality_min: 0.45

stitch:
  enabled: false
  project_id: ""                 # Stitch numeric project id

Project layout (after graphcraft init)

your-project/
├── graphcraft.config.yaml
├── design-system/              # tokens, components
├── design/screens/             # screen YAML specs
├── research/
│   └── INSPIRATION.template.md # run research to generate INSPIRATION.md
├── graphcraft-out/             # generated (gitignore in your app)
├── handoff/
│   ├── BRIEF.md                # templates — fill per task
│   ├── AESTHETIC_BRIEF.md
│   ├── DESIGN_BRIEF.md
│   ├── REVIEW.md
│   ├── STATE.json
│   ├── DESIGN_STATE.json
│   └── board/                  # todo / doing / done (empty)
├── .stitch/                    # Stitch reference (optional)
└── packages/ui-core/           # per-stack UI implementations

Do not commit: graphcraft-out/*, research/INSPIRATION.md, handoff/board/*/*.json (cycle tasks) — regenerate via CLI.

Mobile stacks

See packs/mobile-app/STACKS.md and packs/mobile-game/STACKS.md.

Documentation

Contributors (this repo)

git clone https://github.com/MertCapkin/GraphCraft.git
cd GraphCraft
pip install -e ".[full]"
py -3 -m pytest scripts/graphcraft/tests -q
python scripts/sync_graphcraft_assets.py

License

MIT — see LICENSE. GraphStack is a separate MIT dependency.