supernal-coding

Supernal Coding (sc) - Development Workflow CLI

Comprehensive development workflow system with kanban task management, requirements validation, git safety hooks, intelligent priority management, and live interactive documentation.

📖 Complete Documentation • 🚀 Quick Start Guide • 💻 CLI Reference

🔗 Quick Links

Resource	Description	Link
📖 Documentation	Complete interactive documentation	code.supernal.ai
🚀 Getting Started	Installation and setup guide	Quick Start
💻 CLI Commands	Complete command reference	CLI Reference
📦 NPM Package	Install via npm	supernal-code
🐙 GitHub	Source code and issues	Repository
🤝 Contributing	Contribution guidelines	Contributing Guide

🚀 Quick Start

📖 View Documentation (Recommended First Step)

🌐 Visit code.supernal.ai for the complete interactive documentation with:

• 📋 Live CLI Command Reference - All commands with examples
• 📊 Real-time Project Metrics - Requirements status and progress
• 🎯 Getting Started Guide - Step-by-step setup instructions
• 💡 Usage Examples - Real-world workflow demonstrations

For Local Documentation:

# Start the local documentation server
cd documentation && npm start
open http://localhost:3000

Installation Methods

1. Local Development (Recommended for Contributors)

# Clone and set up for local development
git clone <repository-url>
cd supernal-coding

# Install dependencies
npm install

# Link for global-like access during development
npm link

# Now 'sc' command is available globally
sc --version
sc --help

2. Global NPM Install (For End Users)

# Install globally from npm
npm install -g supernal-code

# Verify installation
sc --version
sc --help

# Get started with your first project
sc init

📖 Detailed installation guide available on our documentation site.

3. Local Project Usage (Without Global Install)

# Use via npm scripts
npm run sc -- --help
npm run sc -- priority show
npm run sc -- validate --all

# Or direct node execution
sc --help
sc priority show

📋 Available Commands

Core Commands

# Initialize in any repository
sc init [directory]

# Validate installation and configuration
sc validate-installation --all

# Agent workflow management
sc agent <action> [options]

# Priority management
sc priority [action] [options]

# Git workflow utilities
sc git-smart <action> [options]
sc git-assess [options]

# Kanban task management
sc kanban [action] [options]

# Documentation management
sc docs <action> [options]

# Development tools
sc dev <action> [options]

# Testing
sc test [options] [type] [target]

📖 See code.supernal.ai/docs/cli-commands for the complete interactive command reference with examples.

📚 Documentation

🌐 Online Documentation (Recommended)

• code.supernal.ai - Complete interactive documentation
• Getting Started - Installation and first steps
• CLI Reference - All commands with examples
• Configuration Guide - Setup and customization
• Workflow Guide - Best practices and workflows

📖 Local Documentation Files

• CLI Usage Guide - Complete command reference with examples
• Configuration System Guide - Multi-repository compatibility and configuration
• Tests as Documentation - How to use tests as executable examples
• Implementation Plan - Development roadmap and progress

🧪 Using Tests as Documentation

Our test suite serves as comprehensive, executable documentation:

# Run tests to see examples in action
npm test -- tests/requirements/req-003/multi-repo-init.test.js

# View configuration examples
npm test -- tests/requirements/req-011/req-011.unit.test.js

# See git workflow examples
npm test -- tests/requirements/req-011/req-011.e2e.test.js

📖 See docs/TESTS_AS_DOCUMENTATION.md for how to use tests as documentation.

🔧 Configuration

The system uses supernal-code.config.toml for all settings:

[project]
name = "your-project"
type = "standard"

[paths]
requirements = "supernal-coding/requirements"
kanban = "supernal-coding/kanban"

[compatibility]
multi_repo_support = true
dynamic_path_resolution = true

📖 See docs/CONFIGURATION_SYSTEM_GUIDE.md for complete configuration guide. sc git-smart status sc git-smart branch-cleanup sc git-smart commit-assist

### **Project Setup**
```bash
# Initialize supernal-coding in new project
sc init [directory]

# Install system in target repository
sc install <path>

Agent Workflow

# Agent coordination
sc agent handoff
sc agent status
sc agent assign <task>

Documentation

# Documentation management
sc docs generate
sc docs validate
sc docs serve

📚 Interactive Documentation (New!)

# Start the live documentation server
cd documentation && npm start

# Or using the CLI command (future)
sc docs serve

🌐 View Documentation: Open http://localhost:3000 in your browser

✨ Features:

• Live CLI Command Reference: All 17+ commands auto-documented from command-mapping.json
• Real-time Project Metrics: Current requirements status (31 tracked)
• Interactive Examples: Live usage examples for each command
• Dashboard Integration: Connected to existing dashboard infrastructure
• Programmatic Generation: Always up-to-date with actual CLI implementation

🛠️ Development Workflow

For Package Contributors:

• Set up local development:

git clone <repository-url>
cd supernal-coding
npm install
npm link  # Makes 'sc' available globally

• Test your changes:

sc --version          # Test global command
npm run sc -- --help  # Test via npm script
npm test              # Run test suite

• Priority system testing:

# Test the intelligent priority system
sc priority update    # Recalculate all priorities
sc priority show      # View distribution

For End Users:

• Install the package:

npm install -g supernal-coding

• Initialize in your project:

cd your-project
sc init

• Use the workflow:

sc validate --all           # Validate project
sc priority show            # Check priorities
sc kanban list              # View tasks

🎯 Priority Management System

The intelligent priority system automatically calculates requirement priorities based on:

• 🏗️ Foundational Systems: Auto-promote to Critical
• 🚧 Blocking Dependencies: Higher priority if blocking other tasks
• 🏥 Medical Compliance: Special handling for regulatory requirements
• System Architecture: Prioritize system-level requirements

Current Distribution:

• 17 Critical requirements (foundational systems)
• 11 High priority requirements
• 1 Medium priority requirement

📦 Package Structure

supernal-coding/
├── cli/                    # CLI entry point and commands
│   ├── index.js           # Main CLI script (#!/usr/bin/env node)
│   └── commands/          # Command modules
├── documentation/          # 🆕 Interactive documentation system (Docusaurus)
│   ├── docs/              # Generated CLI documentation
│   ├── plugins/           # Custom CLI docs generator plugin
│   └── src/               # Documentation components
├── scripts/               # Core functionality scripts
├── templates/             # Project templates
├── package.json           # NPM configuration with 'bin' setup
└── README.md             # This file

🔧 Troubleshooting

📖 For comprehensive troubleshooting guides, visit code.supernal.ai/docs/troubleshooting

Command Not Found: 'sc'

# Check if npm link worked
which sc

# If not found, try:
npm unlink supernal-coding
npm link

# Or use npm scripts instead:
npm run sc -- --help

Permission Issues

# For global install permission issues:
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Or use npm link for development
npm link

Priority System Issues

# If priorities seem outdated:
sc priority update          # Recalculate all priorities
sc priority validate        # Check for issues

# Debug with direct script:
sc priority update

Documentation Server Issues

# Start the documentation server:
cd documentation && npm start

# If port 3000 is busy:
cd documentation && npm start -- --port 3001

# Check if server is running:
lsof -i :3000

# Rebuild documentation:
cd documentation && npm run build

Documentation Features:

• Auto-generated CLI docs from cli/command-mapping.json
• Live project metrics (currently 31 requirements tracked)
• Real-time updates as CLI commands change
• Dashboard integration with existing infrastructure

📚 Additional Resources

• Configuration: Edit supernal-code.config.toml for project settings
• Requirements: Located in supernal-coding/requirements/
• Kanban: Task files in supernal-coding/kanban/
• Templates: Project templates in templates/

🚨 Development Notes

• CLI Entry Point: supernal-code-package/lib/cli/index.js (packaged CLI) and cli/index.js (development wrapper)
• Package Bin: Configured in package.json for both sc and supernal-coding commands
• Local Testing: Use npm link for development, npm run sc for testing
• Global Distribution: Ready for npm publish when needed

📄 License

This project uses a Dual License system - see the LICENSE file for details.

🏢 Supernal Intelligence (Commercial Rights)

• ✅ Unlimited commercial use in products and services
• ✅ Proprietary modifications and derivatives
• ✅ Revenue generation and customer licensing
• ✅ Private use without disclosure requirements

🌍 Everyone Else (CC BY-NC-SA 4.0)

• ✅ Academic research and education
• ✅ Personal learning and development
• ✅ Open source projects and contributions
• ✅ Non-profit organizational use
• ❌ Commercial use requires separate license

📧 Commercial Licensing for Third Parties

Organizations wishing to use this software commercially must obtain a commercial license.

Contact: [e-mail]

🎯 Why Dual License?

• Protects intellectual property while enabling open source community
• Allows company commercial use of their own code
• Prevents unauthorized commercial exploitation by others
• Encourages academic and open source contributions

Full License: LICENSE

🤝 Contributing

• Fork the project
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

Development Standards

• Follow existing code style and patterns
• Add appropriate comments and documentation
• Test your changes thoroughly
• Update README.md if needed
• Ensure all contributions comply with CC BY-NC-SA 4.0 license

🌐 Supernal.ai Integration Plan

Production Deployment: code.supernal.ai

This project is designed for deployment to code.supernal.ai as part of the Supernal Intelligence ecosystem. Here's the integration strategy:

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                 code.supernal.ai                        │
│              (GitHub Pages - Static)                   │
│  • Documentation (Docusaurus)  • Blog Posts            │
│  • CLI Reference               • Static Assets         │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────┼───────────────────────────────────┐
│              api.code.supernal.ai                       │
│               (Vercel - APIs)                           │
│  • Dashboard API (Serverless)  • Requirements API      │
│  • Premium Features            • Analytics & Insights  │
└─────────────────────┼───────────────────────────────────┘
                      │
┌─────────────────────┼───────────────────────────────────┐
│          Local Development (All Users)                 │
│  • CLI Tools               • Local Dashboard           │
│  • Requirements Tracking   • Kanban Management         │
│  • Git Integration         • Basic Export              │
└─────────────────────┴───────────────────────────────────┘

Key Integration Files

• supernal-ai-integration.config.js - Complete integration configuration
• docs/SUPERNAL_AI_DEPLOYMENT_GUIDE.md - Step-by-step deployment guide
• dashboard/src/services/supernal-integration.js - Premium feature service
• dashboard/routes/premium-api.js - Premium API endpoints

Revenue Strategy

• Open Source Core: Full local functionality to demonstrate value
• Premium Features: Advanced analytics, team collaboration, AI insights
• Freemium Model: Gradual upgrade prompts at natural conversion points
• Enterprise: Custom integrations, SLA support, unlimited projects

🔐 Authentication Flow

The system uses centralized authentication to serve multiple Supernal products:

┌─────────────────────────────────────────────────────┐
│ 1. User visits code.supernal.ai                    │
│    → Logs in via auth.supernal.ai                  │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│ 2. auth.supernal.ai returns JWT bearer token       │
│    → Token contains user profile + subscription    │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│ 3. Frontend sends requests to api.code.supernal.ai │
│    → Header: "Authorization: Bearer <token>"       │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│ 4. api.code.supernal.ai validates token           │
│    → Calls auth.supernal.ai/validate               │
│    → Returns user features based on subscription   │
└─────────────────────────────────────────────────────┘

Benefits:

• Single sign-on across all Supernal products
• auth.supernal.ai serves multiple domains (main site, code tools, other products)
• api.code.supernal.ai is specific to this project's needs
• Clean separation of concerns

Deployment Checklist

• DNS Configuration:
  • code.supernal.ai → supernalintelligence.github.io (CNAME)
  • api.code.supernal.ai → Vercel deployment (CNAME)
  • auth.supernal.ai → Centralized auth service (managed separately)
• GitHub Pages Setup: Enable Pages in repository settings (✅ Ready)
• GitHub Actions: Deploy workflow configured (✅ Done)
• Vercel API Setup: Deploy dashboard APIs to Vercel (✅ Ready)
• Documentation Build: Fixed component imports and build process (✅ Done)
• Premium Integration: Configured supernal.ai authentication flow (✅ Done)
• SSL Certificates: Automatic with GitHub Pages and Vercel
• Analytics & Conversion Tracking: Configure in production

For detailed deployment instructions, see docs/SUPERNAL_AI_DEPLOYMENT_GUIDE.md.

Next Steps:

• Test local installation: npm link && sc --version
• Validate functionality: sc priority show
• Initialize in project: sc init
• Run priority update: sc priority update # Test pre-push hook

Test metadata loop fix