Supernal Coding Principles: Building Quality Software with AI Agents
At Supernal Intelligence, we've built Supernal Coding on a foundation of seven core principles that ensure AI agents and human developers deliver high-quality, maintainable code. These aren't just guidelines—they're the backbone of our entire development workflow system.
The Seven Principles
1. 📋 Planning is Documentation
Why it matters: When AI agents work on your codebase, they need clear context. Your planning documents become living documentation that guides both humans and AI.
How Supernal Coding helps:
- Requirement tracking with Gherkin syntax
- Automated traceability matrices
- Git integration that links commits to requirements
Learn more about requirement management →
2. 👥 User's Needs are Primary
Why it matters: Features exist to serve users, not the other way around. Every line of code should trace back to a real user need.
How Supernal Coding helps:
- User story validation
- Acceptance criteria enforcement
- Direct mapping from requirements to implementation
3. ✅ If It Isn't Tested, It Isn't Done
Why it matters: AI agents can generate code fast—but only tests prove it works. Testing is not optional; it's the definition of "done."
How Supernal Coding helps:
- Test generation from requirements
- Coverage tracking and reporting
- Pre-push hooks that enforce test quality
4. 📝 Document It Appropriately
Why it matters: Over-documentation wastes time. Under-documentation wastes even more time later. Document what matters, when it matters.
How Supernal Coding helps:
- Auto-generated CLI documentation
- Requirement-based documentation system
- Code comments linked to requirements
View documentation standards →
5. 🏗️ Keep Needed Information Close to the Code
Why it matters: Context switching kills productivity. Build instructions, configuration, and documentation should live right next to the code that needs them.
How Supernal Coding helps:
BUILDME.shandTESTME.shtemplates- In-repo requirement tracking
- Configuration colocation
Learn about our file structure →
6. 🔗 Feature and Testing Mapping to Requirements
Why it matters: Compliance, auditability, and clarity all depend on knowing exactly which code implements which requirements.
How Supernal Coding helps:
- Automated traceability matrices
- Git branch naming conventions
- Requirement IDs in commit messages
Explore traceability features →
7. 🧹 Keep It Clean
Why it matters: Technical debt compounds. Legacy code spreads. Clean code is easier for AI agents to understand and modify safely.
How Supernal Coding helps:
- Linting and formatting enforcement
- Pre-commit quality checks
- Automated code review suggestions
Putting It All Together
These principles aren't isolated—they work together to create a development environment where AI agents and humans collaborate effectively:
- Plan with clear requirements
- Prioritize user needs in every requirement
- Test everything before marking it done
- Document the right things at the right time
- Colocate context near code
- Trace features back to requirements
- Clean up as you go
Getting Started
Ready to build better software with these principles?
# Install Supernal Coding
npm install -g supernal-code
# Initialize in your project
sc init
# Create your first requirement
sc req new "User login with OAuth"
About Supernal Intelligence: We build AI-powered development tools that help teams deliver higher quality code faster. Supernal Coding is our flagship workflow system designed specifically for AI agent collaboration.