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.