@graph8/devex

g8-devex

Canonical Cursor governance + spec-driven development rules for graph8 repos.

What This Repo Is

A template payload + CLI consumed by npx @graph8/devex init to bootstrap:

• .cursor/rules/* — Cursor enforcement rules
• Governance files — manifesto.md, standards.md, playbook.md, AGENTS.md
• specs/ — Spec-driven development scaffolding

Quick Start

In any target repo:

npx @graph8/devex init

Then commit the created files. Done.

Commands

npx @graph8/devex init

Bootstrap governance + Cursor rules into current repo.

Safe mode (default):

• Creates missing files only
• Never overwrites existing files
• Leaves custom rules untouched

npx @graph8/devex init

Force mode:

• Overwrites existing standard files with latest templates

npx @graph8/devex init --force

npx @graph8/devex doctor

Check repo DevEx health and report issues.

npx @graph8/devex doctor        # Check health
npx @graph8/devex doctor --fix  # Auto-fix issues

Reports:

• Missing governance files and Cursor rules
• Placeholder detection in AGENTS.md
• Backlog sync with spec directories
• Custom rules missing globs patterns
• Governance Level (0–5)

Smart Init

Init automatically detects your repo structure and fills in AGENTS.md:

• Monorepo detection: Scans apps/, packages/, services/, src/
• Multi-stack: Detects Python + Node in same repo
• Path-aware commands: Generates cd apps/backend && pip install

Example output for a monorepo:

Install: `cd apps/backend && pip install` && `cd apps/frontend && npm install`
Test: `cd apps/backend && pytest` && `cd apps/frontend && npm test`

What Gets Installed

Cursor Rules (.cursor/rules/)

File	Purpose
00-principles.mdc	Core engineering philosophy
10-governance.mdc	Rule severity levels, dependency rules
20-spec-protocol.mdc	When/how to create specs before coding
90-emergency.mdc	Hard stops, escalation triggers

Governance Files

File	Purpose
manifesto.md	Engineering philosophy
standards.md	Technical standards and constraints
playbook.md	Team process and SLOs
AGENTS.md	Quick commands for AI agents

Specs Directory

File	Purpose
specs/backlog.md	Tracks active and completed specs
specs/plan.template.md	Template for new specs

Cursor Skills (.cursor/rules/skills/)

File	Purpose
spec-author.mdc	Compress intent into structured specs
scoped-implementer.mdc	Implement exactly what spec defines
proof-gate.mdc	Require verification evidence
agents-updater.mdc	Generate comprehensive AGENTS.md

AI-Powered AGENTS.md

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

• Project Overview
• Tech Stack (auto-detected)
• Architecture
• File Structure
• Environment Variables
• Development Patterns
• API Routes / Database Schema

The agent analyzes your repo and imports from existing CLAUDE.md if present.

Documentation

• Migration Guide — migrate from .cursorrules to .cursor/rules/
• Spec Example — real example of a well-structured spec
• Changelog — version history

Versioning

This repo is versioned via git tags (e.g. v1.0.0). The CLI defaults to the version it was published with.

Development

# Install dependencies
npm install

# Build
npm run build

# Test locally
node dist/index.js init

Safety Guarantees

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

Overwrite requires explicit --force.