@graph8/devex

g8-devex

Intent-driven development governance + Cursor rules for Graph8 repos.

Philosophy

Speed + Solidity. Ship fast, ship solid. Friction is proportional to risk.

• Trivial changes (docs, css): Just do it
• Low-risk changes (tests): State intent, proceed
• Standard changes (features): Show plan, wait for 👍
• Critical changes (auth, security): Full plan, block until approved

Quick Start

npx @graph8/devex init

Then commit the created files. Open Cursor — rules are now active.

Commands

g8 init

Bootstrap governance + Cursor rules into current repo.

npx @graph8/devex init           # Safe mode (won't overwrite)
npx @graph8/devex init --force   # Overwrite with latest templates
npx @graph8/devex init --hook    # Also install pre-commit hook

g8 doctor

Check repo health and report issues.

npx @graph8/devex doctor         # Check health
npx @graph8/devex doctor --fix   # Auto-fix issues
npx @graph8/devex doctor --ci    # CI-friendly JSON output

g8 check

Pre-commit quality gate (tests, lint, secrets scan, risk analysis).

npx @graph8/devex check          # Check all changed files
npx @graph8/devex check --staged # Check only staged files

What Gets Installed

Cursor Rules (.cursor/rules/)

File	Purpose
00-principles.mdc	Core engineering philosophy
10-governance.mdc	Rule severity levels (A/B/C), dependency rules
15-risk-classification.mdc	Auto-attached rules for critical paths
20-spec-protocol.mdc	Risk-based intent protocol
90-emergency.mdc	Hard stops, escalation triggers

Cursor Skills (.cursor/rules/skills/)

File	Purpose
planner.mdc	Generate intent docs from user requests
implementer.mdc	Execute approved plans, stay in scope
verifier.mdc	Collect evidence before commit
researcher.mdc	Read-only exploration mode
agents-updater.mdc	Generate comprehensive AGENTS.md

Context Files

File	Purpose
AGENTS.md	Quick commands + risk classification for AI

Specs Directory

File	Purpose
specs/plan.template.md	Intent format templates

Risk Classification

Files are automatically classified by risk level:

Risk	File Patterns	Friction
Critical	auth/**, security/**, migrations/**, .env*	Full plan, block until approved
Standard	src/**, app/**, lib/**	Show plan, wait for 👍
Low	tests/**, *.test.*	State intent, proceed
Trivial	*.md, *.css, docs/**	Just do it

Intent Formats

Standard (3 sections)

# Intent: Add rate limiting to API

## Plan
- Create rateLimit middleware
- Apply to /api/* routes
- Add tests

## Verify
- npm test passes
- 101 rapid requests → 429

Critical (6 sections)

# Intent: Update password hashing

## Why
Security audit requires updated bcrypt cost.

## Plan
- Update bcrypt cost from 10 to 12
- Add lazy rehash on login

## Constraints
- Existing passwords must validate
- No user-facing changes

## Verify
- All auth tests pass
- Manual: old passwords work

## Rollback
- Revert cost factor

Pre-Commit Hook

Install the pre-commit hook to run quality checks automatically:

npx @graph8/devex init --hook

This installs a git pre-commit hook that runs g8 check --staged before each commit.

AI-Powered AGENTS.md

After g8 init, say "update AGENTS.md" in Cursor to generate comprehensive documentation:

• Project Overview
• Tech Stack (auto-detected)
• Risk Classification
• YOLO Configuration
• Architecture
• Environment Variables

Documentation

• Migration Guide — migrate from .cursorrules or v1.x
• Intent Example — real example of intent formats
• Changelog — version history

Development

npm install      # Install dependencies
npm run build    # Build CLI
node dist/index.js init   # Test locally

Safety Guarantees

Scenario	Behavior
Standard file missing	Create
Standard file exists	Skip
Custom rule file	Leave untouched
.cursorrules present	Warn; do not delete

Overwrite requires explicit --force.