sxtn

v4.4.0

Published

6 months ago

State-machine enforced AI development framework for Cursor IDE

0High
0Medium
0Low

sxtn

cursor ai development framework autonomous-agents mcp n8n bubble

SXTN Framework v4.2

Hierarchical state-machine enforced AI development for Cursor IDE
User story validation. Discovery tracking. Confidence gating. Context health monitoring. BMAD-style documentation wizard. Child project rules propagation.

What's New in v4.2

| Feature | Description | |---------|-------------| | Documentation Wizard | BMAD-style interactive wizard (/sxtn-wizard) for creating project docs | | Document Templates | Handlebars-style templates for Product Brief, PRD, Architecture, Roadmap | | Doc Validation | Init validates required documentation, triggers wizard if missing | | Child Project Rules | Symlink .cursor/ rules to parent for "zoom in" workflows | | Project Levels | Hobby/Startup/Enterprise levels with different doc requirements | | Scale-Adaptive | Documentation depth adapts to project complexity |

What's in v4.1

| Feature | Description | |---------|-------------| | Hierarchical States | XState-inspired compound states with nested transitions | | Testing State | Dedicated testing compound state for user story validation | | Discovery Tracking | Capture unplanned work automatically in DISCOVERY.md | | User Story Validation | Acceptance criteria testing linked to stories | | AI Confidence Gating | Block low-confidence transitions based on ceremony level | | Ceremony Profiles | trivial/standard/critical levels with different requirements | | Context Health | Token tracking and drift detection | | Multi-Plan Locks | Resource locking for concurrent plans (n8n, Supabase) | | Event Sourcing | Full audit trail in events.yaml | | Project Scanning | Auto-detect docs and tech stack on init |

Quick Start

1. Install

npm install -g sxtn

Or use npx:

npx sxtn init

2. Initialize Project

# In your project root (must have git)
cd your-project
sxtn init

This will:

Validate documentation (or launch /sxtn-wizard if missing)
Create .sxtn/ runtime directory
Set up .cursor/ rules (symlink to parent if child project)
Scan for existing docs and tech stack
Auto-migrate if older SXTN version detected

3. Create Documentation (New Projects)

If no documentation exists, the wizard guides you through creating:

/sxtn-wizard
    ↓
Step 1: Detect project level (hobby/startup/enterprise)
    ↓
Step 2: Product Brief (vision, problem, solution)
    ↓
Step 3: PRD (requirements, user stories)
    ↓
Step 4: Architecture (tech stack, data model)
    ↓
Step 5: Roadmap (phases, milestones) [enterprise only]
    ↓
Documentation complete → /sxtn-init continues

4. Initialize Global Learnings (first time)

sxtn global-init

Creates ~/.sxtn/ for cross-project learnings.

5. Start Working in Cursor

/sxtn-session-start     # Begin session, read state, announce

Workflow

/sxtn-brainstorm        # Design exploration (idle → brainstorming)
      ↓
/sxtn-plan-write        # Create plan (→ working.planning → working.approval)
      ↓
/sxtn-plan-verify       # Optional: validate plan
      ↓
APPROVED                # Start execution (→ working.executing.active)
      ↓
/sxtn-plan-execute      # Execute tasks one by one
      ↓
/sxtn-plan-complete     # Mark plan done (→ done)
      ↓
/sxtn-test              # Validate user stories (→ testing)
      ↓
APPROVED                # Tests pass
      ↓
/sxtn-session-end       # Commit & push

State Machine (v4.1)

                              ┌─────────────────────────────────────────────┐
idle ────────────────────────►│            WORKING (compound)               │
  │                           │  ┌─────────────────────────────────────┐    │
  │                           │  │ planning ──► approval ──► executing │    │
  │                           │  │                           │         │    │
  │                           │  │                      ┌────┴────┐    │    │
  │                           │  │                      │ active  │◄──►│paused│
  │                           │  │                      └─────────┘    │    │
  │                           │  └─────────────────────────────────────┘    │
  │                           │                                              │
  │                           └──────────────────────────────────────────────┘
  │                                              │
  └──────── brainstorming ◄─────────────────────┘
  │                                              │
  │                              ┌───────────────┘
  │                              │
  └──────────────► testing ◄────┘  (v4.1 NEW)
  │                   │
  │                   │            ┌──────────────────────┐
  │                   └───────────►│ setup → executing →  │
  │                                │ checkpoint → review  │
  │                                └──────────────────────┘
  │
  └──────────────────► done ◄──────────────────

ABORT from any working/testing state → idle

Every response reads .sxtn/state.yaml and enforces valid transitions.

Project Structure

project/
├── .sxtn/                      # Runtime state
│   ├── state.yaml              # Hierarchical state machine
│   ├── session.yaml            # Session context + AI state
│   ├── events.yaml             # Event sourcing audit trail
│   ├── context-health.yaml     # Token tracking & drift detection
│   ├── ceremony-profiles.yaml  # Ceremony level configuration
│   ├── retrospectives.yaml     # Retrospective data
│   ├── versions.yaml           # Version tracking
│   ├── project-index.yaml      # Scanned project structure
│   ├── PROGRESS.yaml           # Progress tracker
│   ├── DEBT.yaml               # Technical debt registry
│   ├── parent.yaml             # Parent SXTN reference (if child)
│   ├── templates/              # Document templates (v4.2)
│   │   ├── product-brief.md    # Vision template
│   │   ├── prd.md              # Requirements template
│   │   ├── architecture.md     # Architecture template
│   │   ├── roadmap.md          # Roadmap template
│   │   └── checklist.yaml      # Validation rules
│   ├── pending/                # Atomic operation staging
│   ├── plans/                  # Plan files
│   ├── references/             # HANDOFF.md, LEARNINGS.md, etc.
│   ├── verifications/          # Proof logs
│   ├── locks/                  # Resource locks
│   └── backups/                # Auto-backups
│
├── .cursor/
│   ├── rules/                  # Symlinked to parent if child project
│   │   ├── 000-sxtn-core.mdc           # Core enforcement
│   │   ├── 001-confidence-gates.mdc    # Confidence gating
│   │   ├── 002-explanation-requirements.mdc
│   │   ├── 003-discovery-capture.mdc   # Discovery pattern
│   │   ├── 010-multi-plan-locks.mdc    # Resource locking
│   │   └── 100-stack-*.mdc             # Stack contexts
│   └── commands/               # Symlinked to parent if child project
│       ├── sxtn-wizard.md      # Documentation wizard (v4.2)
│       └── sxtn-*.md           # All other commands
│
├── docs/                       # Source of truth (DOC agent only)
│   ├── PRODUCT-BRIEF.md        # Vision document (v4.2)
│   ├── PRD.md                  # Requirements
│   ├── ARCHITECTURE.md         # Technical design
│   └── ROADMAP.md              # Milestones (optional)
│
├── CLAUDE.md                   # AI quick reference (<2KB)
└── DISCOVERY.md                # Unplanned work tracking

Global Structure

~/.sxtn/                        # Cross-project
├── config.yaml                 # Global settings
├── learnings/
│   ├── stacks/
│   │   ├── mcp.yaml            # MCP learnings
│   │   ├── n8n.yaml            # n8n learnings
│   │   └── bubble.yaml         # Bubble learnings
│   └── patterns.yaml           # General patterns
└── backups/                    # Global backups

Commands

Setup Commands (v4.2)

| Command | Purpose | |---------|---------| | /sxtn-init | Initialize SXTN (validates docs, creates runtime) | | /sxtn-wizard | Interactive documentation wizard (Product Brief, PRD, Architecture, Roadmap) |

Workflow Commands

| Command | From State | Purpose | |---------|------------|---------| | /sxtn-session-start | any | Initialize session, read state, announce | | /sxtn-brainstorm | idle | Design exploration | | /sxtn-plan-write | idle, brainstorming | Create implementation plan | | /sxtn-plan-verify | working.approval | Validate plan before execution | | /sxtn-plan-execute | working.approval | Execute approved plan | | /sxtn-plan-complete | working.executing | Mark plan done | | /sxtn-test | done | Validate user stories | | /sxtn-session-end | done | Commit & push | | /sxtn-session-handoff | any | Prepare handoff document |

Utility Commands

| Command | Purpose | |---------|---------| | /sxtn-status | Show current state, confidence, ceremony | | /sxtn-health | Project health check | | /sxtn-recover | Fix corrupt state | | /sxtn-review | Read-only project review | | /sxtn-docs-update | Update documentation (DOC agent) | | /sxtn-build | Generate new rules/commands | | /sxtn-retrospective | Capture session learnings |

CLI Commands

sxtn init              # Initialize project (auto-migrates, scans project)
sxtn update            # Update to latest SXTN version
sxtn migrate           # Explicitly migrate from older version
sxtn status            # Show state, confidence, ceremony
sxtn doctor            # Diagnose issues
sxtn global-init       # Initialize ~/.sxtn/
sxtn global-update     # Update global SXTN
sxtn version           # Show version
sxtn help              # Show help

CLI Options

sxtn init --force      # Reinitialize (overwrites existing)
sxtn migrate --dry-run # Preview migration without changes
sxtn status --verbose  # Show detailed status

Agents

| Agent | Trigger | Can Write | Cannot Write | |-------|---------|-----------|--------------| | DEV | default | code, plans, refs, PROGRESS, DEBT, DISCOVERY | docs/, CLAUDE.md | | REVIEWER | /sxtn-review | PROGRESS (status), reports | code, docs/ | | DOC | /sxtn-docs-update | docs/, CLAUDE.md, DISCOVERY | code | | BUILDER | /sxtn-build | .cursor/rules, commands | docs/, code |

Key Concepts

Confidence Gating

Before state transitions, AI reports confidence (0.0-1.0) and checks against ceremony threshold:

| Ceremony | Threshold | On Low Confidence | |----------|-----------|-------------------| | trivial | 0.70 | Warn, proceed | | standard | 0.80 | Require confirmation | | critical | 0.95 | BLOCK until addressed |

Discovery Tracking

Unplanned work is captured automatically:

## ⚠️ Discovery

**Found:** Existing validation function could be reused
**Location:** src/utils/validate.ts

This is NOT in the plan.

**Options:**
1. ADD - Add task to integrate (requires re-approval)
2. DEFER - Log to DISCOVERY.md, continue planned task
3. IGNORE - Not relevant to current work

Multi-Plan Resource Locks

Multiple plans can exist but cannot overlap on:

n8n workflows
Supabase functions

Locks acquired on APPROVED, released on /sxtn-plan-complete.

Child Project Rules (v4.2)

When you "zoom in" to a child project (open Cursor directly at a subfolder), you need .cursor/rules/ there for rules to apply.

SXTN handles this automatically:

Parent: C:\Dev\                     ← Has .cursor/rules/
Child:  C:\Dev\my-project\          ← Symlinks to parent's .cursor/

On /sxtn-init in a child project:

Detects parent .cursor/ by walking up directories
Creates symlinks: .cursor/rules → ../parent/.cursor/rules
Records relationship in .sxtn/parent.yaml

Benefits:

Single source of truth for rules
Changes to parent automatically apply to children
Works when you open Cursor at any level

Project Levels (v4.2)

Documentation requirements adapt to project complexity:

| Level | Required Docs | Optional Docs | |-------|---------------|---------------| | Hobby | Product Brief | PRD, Architecture, Roadmap | | Startup | Product Brief, PRD | Architecture, Roadmap | | Enterprise | All | None |

The wizard detects your level based on:

Who is this for? (personal vs business vs corporate)
Scope complexity (simple vs medium vs complex)
Stakeholder count

Guards

Transitions are protected by guards:

| Guard | Purpose | |-------|---------| | confidenceAboveThreshold | AI confidence meets ceremony level | | hasVerificationProof | Task has verification log | | contextHealthOk | Context not in critical decay | | noOrphanedLocks | No locks from dead sessions | | debtAcknowledged | New debt recorded before session end | | hasCompletedPlan | Must have completed plan to test | | noUnacknowledgedDiscoveries | All discoveries addressed |

Installation

npm (recommended)

npm install -g sxtn

npx (no install)

npx sxtn init

Manual

git clone https://github.com/smartout/sxtn.git
cd sxtn
npm link

Requirements

Node.js >= 18
Git repository (for root SXTN)
Cursor IDE

Version History

| Version | Date | Changes | |---------|------|---------| | 4.2.0 | 2024-12-09 | BMAD-style wizard, document templates, child project symlinks, project levels | | 4.1.0 | 2024-12-09 | Testing state, discovery tracking, user story validation, project scanning | | 4.0.0 | 2024-11-29 | Hierarchical states, confidence gating, context health, ceremony profiles | | 3.1.0 | 2024-11-29 | Initial state machine enforcement |

License

MIT

State-machine enforced. Confidence gated. Discovery tracked. Wizard-guided. Child-aware.