Getting Started with Supernal Coding

This guide will walk you through setting up Supernal Coding and creating your first compliant project.

Prerequisites

Node.js 18+ and npm
Git for version control
Modern terminal (bash, zsh, or PowerShell)
Code editor (VS Code recommended for best integration)

Installation

1. Install the Global CLI

npm install -g supernal-coding

Verify installation:

sc --version
sc --help

2. Verify System Requirements

sc doctor  # Check system compatibility

Quick Start (5 Minutes)

1. Create a New Project

mkdir my-compliant-app
cd my-compliant-app
git init

2. Equip with Supernal Coding

sc init --standard

This will:

Install Supernal Coding configuration
Set up git hooks for validation
Create requirement tracking system
Configure testing framework
Initialize dashboard components

3. Launch the Dashboard

sc dashboard

Opens at http://localhost:3001 showing:

Project overview
Requirements by phase
Compliance status
Testing results

4. Create Your First Requirement

sc planning req new "User authentication system" --priority=high --epic=auth

5. Start Development

sc planning req start-work REQ-001  # Creates feature branch
# Implement your feature
sc test                    # Run validation
sc git smart merge         # Safe merge to main

Project Initialization Options

Standard Setup (Recommended)

sc init --standard

Complete feature set
All compliance frameworks
Full testing suite
Dashboard integration

Minimal Setup

sc init --minimal

Basic requirement tracking
Essential git hooks
Lightweight configuration

Development Setup

sc init --development

All features plus development tools
Enhanced debugging
Contributor documentation

Interactive Setup

sc init --interactive

Guided configuration
Custom compliance selection
Tailored to your needs

Understanding the File Structure

After initialization, your project will have:

my-compliant-app/
├── .supernal-coding/           # Supernal Coding configuration
│   ├── config.json            # Main configuration
│   ├── requirements/          # Requirement files
│   ├── compliance/            # Compliance mappings
│   └── state/                 # Project state tracking
├── .cursor/                   # AI agent rules (if using Cursor)
│   └── rules/                 # Development guidelines
├── tests/                     # Test suites
│   ├── unit/                  # Unit tests
│   ├── integration/           # Integration tests
│   └── e2e/                   # End-to-end tests
├── docs/                      # Generated documentation
├── scripts/                   # Automation scripts
├── .gitignore                 # Enhanced git ignore
├── package.json               # Project dependencies
└── supernal-code.config.toml  # Supernal configuration

Core Concepts

Requirements Lifecycle

Creation: sc planning req new "Feature description"
Planning: sc planning req expand REQ-001 (break into subtasks)
Development: sc planning req start-work REQ-001
Testing: sc test validate REQ-001
Completion: sc planning req update REQ-001 --status=done

Development Phases

Your project progresses through phases:

Discovery: Problem definition and planning
Foundation: Infrastructure and setup
Implementation: Feature development
Validation: Testing and quality assurance
Compliance: Regulatory validation

Git Workflow Integration

Supernal Coding enhances your git workflow:

# Create feature branch
sc git smart branch --req=REQ-001

# Safe merge with validation
sc git smart merge --push --delete-local

# Automated compliance checks
git commit -m "REQ-001: Implement user auth"

First Development Cycle

Let's create a complete feature from start to finish:

1. Define the Requirement

sc planning req new "User login with email and password" \
  --priority=high \
  --epic=authentication \
  --compliance="iso-13485"

2. Plan the Implementation

sc planning req show REQ-001           # View requirement details
sc planning req expand REQ-001         # Break into subtasks
sc planning req generate-tests REQ-001 # Create test framework

3. Start Development

sc planning req start-work REQ-001     # Creates feature/req-001-user-login

4. Implement the Feature

Create your login component, API endpoints, etc.

5. Validate Implementation

sc test run unit              # Run unit tests
sc test run e2e               # Run end-to-end tests
sc planning req validate REQ-001       # Validate requirement completion

6. Complete the Requirement

sc planning req update REQ-001 --status=done
sc git smart merge --push --delete-local

7. Monitor Progress

sc dashboard                  # View progress
sc compliance report         # Check compliance status

Common Commands

Requirement Management

sc planning req list                   # List all requirements
sc planning req show REQ-001          # Show requirement details
sc planning req new "Description"     # Create new requirement
sc planning req update REQ-001 --status=done

Testing

sc test guide               # Show testing guidance
sc test run unit            # Run unit tests
sc test validate REQ-001    # Validate specific requirement

Git Operations

sc git smart branch         # Create feature branch
sc git smart merge          # Safe merge with validation
sc git-hooks install        # Install git hooks

Dashboard & Monitoring

sc dashboard               # Launch dashboard
sc compliance report      # Generate compliance report
sc docs generate          # Update documentation

Troubleshooting

Command not found: sc

npm install -g supernal-coding
# or
npx supernal-coding --version

Git hooks not working

sc git-hooks install
sc git-hooks status

Dashboard not loading

sc dashboard --port=3002  # Try different port

Tests failing

sc test doctor           # Diagnose test issues
sc test setup           # Reconfigure testing

Next Steps

Now that you have Supernal Coding set up:

Explore the Dashboard - Familiarize yourself with the visual interface
Create More Requirements - Build out your project requirements
Set Up Compliance - Configure your specific compliance frameworks
Customize Workflows - Adapt the system to your team's needs
Integrate with CI/CD - Set up automated validation

Ready to dive deeper? Check out the Guides for detailed how-to information, or explore the Tools Reference for complete CLI documentation.