Supernal Commands: Why We Built the Backend Before the Interface

There's a concept I keep coming back to: Every company is a function.

Input → Processing → Output. That's it. Whether you're running a hospital, building software, or operating a supply chain—you're taking inputs (data, requirements, resources), applying transformations (processes, workflows, intelligence), and producing outputs (features, reports, value).

The question isn't whether your organization is a function. It's how well-defined that function is.

And when you're building software—especially AI-woven applications—the most powerful decision you can make is this:

Build the backend first. Make it executable through commands. Add the interface later.

This is why Supernal Coding started with sc—a command-line interface that orchestrates our entire development workflow. Not because we hate UIs. Because we needed the function to exist before we could visualize it.

The Traditional Approach (and Why It Fails for AI)

Most software development follows this pattern:

Design the UI - Mockups, user flows, pretty screens
Build the backend - APIs that power those screens
Maybe add a CLI - If developers ask for it
Hope AI agents can use it - Spoiler: they struggle

This works fine for human-centric applications. But when you're building AI-woven systems—where AI agents are co-workers, where automation is essential, where workflows must compose—this approach creates friction.

Why?

UIs are opaque to agents - AI can't easily automate clicking buttons
APIs require integration - Every tool needs custom code
Workflows are rigid - UI-first design locks you into specific paths
Testing is complex - Hard to verify business logic through UI

The Hybrid Approach: CLI Orchestration + File Editing

Here's what makes Supernal different: we're not trying to replace file editing with commands.

Instead:

CLI creates structure - Files in the right place, correct format
You edit files - Requirements, code, docs (with AI pair programming)
CLI enforces safety - Validates structure, runs tests, prevents mistakes
Dashboard visualizes - Shows what's in those files

It's orchestration and guardrails, not CRUD operations.

# CLI creates the structure
$ sc requirement new "User Authentication" --epic=security --priority=high
Created: requirements/req-042-user-authentication.md

# You edit the file in your editor (with AI help)
$ cursor requirements/req-042-user-authentication.md
# Write Gherkin scenarios, acceptance criteria...

# CLI validates what you wrote
$ sc requirement validate 042
✓ Frontmatter complete
✓ Gherkin scenarios well-formed
✓ Acceptance criteria defined

# CLI generates test structure
$ sc requirement generate-tests 042
Created: tests/requirements/req-042/

# You write implementation (with AI pair programming)
# Code, tests, everything happens in your editor

# CLI runs tests and logs evidence
$ sc test run
Running tests...
✓ All tests passing
Evidence logged for compliance

# CLI commits with automatic traceability
$ sc git smart commit
Detected: REQ-042 from file context
Commit: "feat: REQ-042 - Implement user authentication"
✓ Linked to requirement automatically

The pattern: CLI creates → You edit → CLI validates → CLI orchestrates

Why This Enables AI-Woven Development

1. Commands Are AI-Native

AI agents execute commands naturally:

# Agent workflow (smooth)
$ sc requirement list --status=pending --format=json
$ sc test run
$ sc git smart commit
$ sc audit export

# Every operation is scriptable, chainable, testable

Compare to UI automation:

Navigate pages
Find elements
Click buttons
Hope DOM hasn't changed
Fragile, slow, painful

Commands >>> UI clicks for automation.

2. Files Are Portable

Your requirements are markdown. Your code is code. No database to export.

$ git clone <repo>
$ sc requirement validate 042
$ sc test run

Everything just works. The files ARE the database.

3. Context Emerges From Files

The CLI doesn't maintain a separate state database. It reads your files to understand context:

$ sc git smart check-context

Analyzing working directory...
- Modified: src/auth/login.ts, tests/auth/login.test.ts
- File paths mention: req-042, authentication
- Git branch: feature/req-042-user-auth
- Requirement exists: requirements/req-042-user-authentication.md
- Tests exist: tests/requirements/req-042/

Inferred context: Working on REQ-042

$ sc git smart commit
# Auto-links to REQ-042 based on file analysis

Files are the source of truth. CLI just reads them intelligently.

4. Human AND AI Readable

Feature: User Authentication
  Scenario: Successful login
    Given a registered user
    When they enter correct credentials
    Then they are logged in

Both humans and AI agents can read, write, and understand this naturally. No special API needed.

5. Version Control is Native

Every change is in git history:

$ git log requirements/req-042-user-authentication.md

commit abc123 REQ-042: Add edge case for locked accounts
commit def456 REQ-042: Initial authentication requirement

Your audit trail IS your git history. No separate compliance database.

Real Workflow: How It Actually Works

Week 1: Core Commands

# Requirements management
$ sc requirement new "Feature Title" --epic=core
$ sc requirement validate 042
$ sc requirement generate-tests 042

# No UI. Just commands that work.
# AI agents can use them immediately.
# Business logic is testable.

Week 2: Git Integration

# Safe git operations with context awareness
$ sc git smart commit      # Links to requirements automatically
$ sc git smart check-branch # Validates before merge
$ sc git smart merge --push # Safe merge with validation

# Commands coordinate with requirement system
# Traceability is automatic
# Still no UI needed

Week 3: Testing System

# Test execution with evidence logging
$ sc test run
$ sc test evidence --requirement=042
$ sc test-map show

# Tests run, evidence logs, requirements validated
# Everything works through CLI

Week 8: Dashboard (Finally)

// The dashboard just calls commands and displays results
function RequirementsList() {
  // Read markdown files, display them
  const requirements = useRequirementsFromFiles();
  return <RequirementGrid data={requirements} />;
}

function RequirementActions({ reqId }) {
  // Buttons execute CLI commands
  const validate = () => exec(`sc requirement validate ${reqId}`);
  const runTests = () => exec(`sc test run --requirement=${reqId}`);
  
  return (
    <>
      <Button onClick={validate}>Validate</Button>
      <Button onClick={runTests}>Run Tests</Button>
    </>
  );
}

The dashboard added zero business logic. It just visualized what the CLI already did.

The Result

8 weeks to functional system (via CLI)
2 additional weeks to add dashboard (just UI)
AI agents used it from day 1 (through CLI)
Every feature testable immediately (no UI dependencies)
Files are portable (no vendor lock-in)

The Company as a Function

Let's go deeper.

Every organization performs transformations:

Inputs:
  - Customer requirements
  - Market signals
  - Resources

Processing:
  - Business logic
  - Workflows
  - Decision making

Outputs:
  - Shipped features
  - Reports
  - Customer value

Traditional Companies: Black Box

Input → [mysterious processes] → Output
         [manual work]
         [email chains]
         [meetings]
         [hope]

Can't debug, can't optimize, can't automate what you can't see.

AI-Woven Companies: Explicit Functions

# The function is visible and executable
$ sc requirement new "Feature X" --epic=core --priority=high
  ↓
$ sc requirement validate REQ-042
  ↓
$ sc test run --requirement=REQ-042
  ↓
$ sc git smart commit
  ↓
$ sc git smart merge --push
  ↓
$ sc audit export --requirement=REQ-042

Every step is a command. Every command is testable. Every test ensures the function works.

Now you can:

Debug: See exactly where processes fail
Optimize: Measure and improve each step
Automate: AI agents execute the workflow
Scale: Commands run anywhere

Composability: Bash is Your Workflow Engine

Because these are just commands, standard bash works:

# Complete validation workflow
sc requirement validate 042 && \
  sc test run && \
  sc git smart commit && \
  sc git smart merge --push

# Or in a script
function complete_requirement() {
  local req_id=$1
  
  echo "Validating requirement..."
  sc requirement validate "$req_id" || return 1
  
  echo "Running tests..."
  sc test run || return 1
  
  echo "Committing with traceability..."
  sc git smart commit || return 1
  
  echo "Exporting audit evidence..."
  sc audit export --requirement="$req_id"
  
  echo "✓ Requirement $req_id complete"
}

complete_requirement 042

No special workflow DSL. Just bash.

The Pattern: Backend → CLI → Dashboard

This is the architecture for AI-woven applications:

1. Define Domain Functions

What are your business operations?

Requirements management
Testing & validation
Git operations & traceability
Compliance reporting
Documentation generation

2. Implement as Commands

# Requirements
sc requirement new
sc requirement validate
sc requirement generate-tests

# Testing
sc test run
sc test evidence
sc test-map show

# Git
sc git smart commit
sc git smart merge
sc git smart check-branch

# Compliance
sc audit export
sc traceability matrix

3. Store State in Files

requirements/
  req-042-user-authentication.md    # Gherkin scenarios
tests/
  requirements/req-042/              # Test files
.supernal/
  evidence/                          # Test evidence logs

No database. Files are the storage.

4. Commands Read Files for Context

$ sc git smart commit
# Reads: modified files, git branch, requirement files
# Infers: REQ-042 context
# Auto-links: commit to requirement

5. Dashboard Reads Same Files

function Dashboard() {
  // Read markdown files
  const requirements = readRequirementFiles();
  const tests = readTestResults();
  const commits = readGitLog();
  
  // Display them
  return <UI requirements={requirements} tests={tests} commits={commits} />;
}

Same data source. Different interface.

Extending the Pattern

Imagine applying this to any domain:

# Healthcare system (conceptual example)
$ health patient admit --id=12345 --condition="chest-pain"
$ health tests order --patient=12345 --tests=ekg,bloodwork
$ health alerts subscribe --patient=12345

# Supply chain (conceptual example)
$ logistics order place --product=widget --quantity=1000
$ logistics shipment track --order=98765
$ logistics inventory check --warehouse=west

# Finance (conceptual example)
$ finance invoice create --customer=acme --amount=5000
$ finance payment process --invoice=inv-123
$ finance report generate --period=q4-2025

Any organization's operations can become executable, composable, automatable.

Lessons Learned

✅ What Worked

1. Rapid Prototyping

Test business logic immediately
No UI dependencies
Iterate on functionality independently

2. Clear Contracts

Command signatures are API contracts
Input/output is explicit
Breaking changes are obvious

3. AI Integration for Free

Agents use CLI from day 1
No special "AI API" needed
Automation is natural

4. File-Based Storage

Portable (just git clone)
Versionable (git history)
Human-readable (markdown, code)
No vendor lock-in

5. Dashboard Was Easy

Just read and display files
No new business logic
Took 2 weeks, not 2 months

⚠️ What Was Challenging

1. Designing Command Structure

Getting command grouping right
Balancing granularity vs convenience
Managing flags and options

2. Context Inference

Reading files to determine context
Handling ambiguous situations
Providing helpful suggestions

3. Error Messages

Making validation errors actionable
Suggesting next steps
Debugging command chains

But these challenges are far easier than building UI-first and then trying to add CLI/automation later.

Why This Matters for AI-Woven Applications

When you build AI-woven applications—where AI is a co-worker—CLI-first architecture is essential:

AI Agents Operate Through Commands

# Agent workflow
Agent: "What requirements are pending?"
System: $ sc requirement list --status=pending --format=json

Agent: "Run tests for REQ-042"
System: $ sc test run --requirement=042

Agent: "Commit the changes"
System: $ sc git smart commit

Agent: "Generate compliance report"
System: $ sc audit export --requirement=042

No UI scraping. No fragile automation. Just commands.

Humans Use the Same System

# Developer workflow (via terminal or dashboard)
$ sc requirement validate 042
$ sc test run
$ sc git smart commit

# Or via dashboard:
# Click "Validate" → Executes: sc requirement validate 042
# Click "Run Tests" → Executes: sc test run

Same backend. Different interface. Consistent behavior.

Automation is Native

#!/bin/bash
# CI/CD pipeline - just bash

# Validate all in-progress requirements
sc requirement list --status=in-progress --format=json | \
  jq -r '.[].id' | \
  while read req_id; do
    sc test run --requirement="$req_id" || notify_team "Tests failed: $req_id"
  done

# Generate nightly compliance report
sc audit export --format=html > audit-$(date +%Y-%m-%d).html

No special automation framework. Just bash scripts calling commands.

Conclusion: Build the Function First

If you're building software—especially AI-woven applications—start with the backend:

Define your business functions - What are the core operations?
Implement as CLI commands - Make functions executable
Store state in files - Portable, versionable, human-readable
Commands read files - Context emerges from filesystem
Test business logic directly - No UI dependencies
Add dashboard as visualization - Just display what's in files

Your company is a function. Make that function executable.

When you build CLI-first:

✅ AI agents can use your system immediately
✅ Humans get powerful automation
✅ Dashboard is just a view over files
✅ Testing is straightforward
✅ Files are portable (no lock-in)
✅ Version control is native (git history)

We built Supernal this way. The CLI came first. The dashboard came later. And now we have a system that AI agents and humans use equally well—because they're using the same backend, through different interfaces.

Start with sc. Build the commands. The interface will follow.

Want to explore the CLI-first approach? Check out Supernal Coding on GitHub or dive into the CLI commands reference to see this philosophy in action.

Further Reading