Skip to content

Slash Commands Guide

Learn how to use the /novaai slash command in Claude Code for orchestrated workflows.

Overview

The /novaai command is Nova AI's primary interface for interactive development workflows. It provides:

  • Intelligent Planning - Orchestrator analyzes your request and creates a detailed plan
  • Agent Coordination - Delegates to specialist agents (implementer, code-reviewer, tester)
  • Quality Gates - Enforces code review and testing before completion
  • KB Search - Automatically finds relevant standards and patterns
  • User Approval - Shows plan before execution (press Enter to approve)

Basic Usage

Command Format

/novaai <your task description>

The task description should be clear and specific about what you want to accomplish.

Simple Example

/novaai implement a hello world function in Python

Complex Example

/novaai implement user authentication with JWT tokens, refresh tokens, password hashing with bcrypt, and email validation

Workflow Phases

Every /novaai command follows this 7-phase workflow:

Phase 0: Context Analysis

The orchestrator analyzes your request and determines:

  • STAY: Continue in current project
  • SWITCH: Move to different project
  • CREATE: Set up new project structure
graph LR
    A[User Request] --> B[Context Analysis]
    B --> C{Decision}
    C -->|STAY| D[Continue]
    C -->|SWITCH| E[Change Project]
    C -->|CREATE| F[New Project]

Phase 1: Planning (Interactive)

The orchestrator:

  1. Searches Knowledge Base - Finds relevant standards, patterns, examples
  2. Asks Clarifying Questions - If requirements are unclear
  3. Creates Detailed Plan - With agent assignments and success criteria
  4. Presents Plan - Waits for your approval (press Enter)

Planning Output:

PLANNING PHASE

Task: Implement user authentication

Questions for User:
1. Which authentication method? (Options: JWT, OAuth2, Sessions)
2. Password requirements? (Default: 12+ chars, uppercase, lowercase, number)

Knowledge Base Findings:
- [JWT Best Practices] - /kb/auth/jwt-patterns.md
- [Password Hashing] - /kb/security/password-hashing.md
- [API Security] - /kb/api/security-checklist.md

Proposed Plan:
1. Create User model with bcrypt password hashing
2. Implement JWT token generation (access + refresh)
3. Create registration endpoint with validation
4. Create login endpoint with rate limiting
5. Add comprehensive tests (unit + integration)
6. Code review by code-reviewer agent
7. Security audit checklist

Agent Assignments:
- implementer: Steps 1-5
- code-reviewer: Step 6-7

Success Criteria:
- All tests passing (>80% coverage)
- No security vulnerabilities
- Type hints complete
- Documentation complete

Press Enter to approve plan or type modifications...

Fast Planning

Planning phase is optimized to complete in ~30 seconds. It's faster to review the plan than to debug issues later.

Phase 2-5: Execution

The orchestrator delegates to specialist agents:

graph LR
    A[Orchestrator] --> B[Implementer]
    B --> C[Code-Reviewer]
    C --> D{Pass?}
    D -->|Yes| E[Tester]
    D -->|No| B
    E --> F{Pass?}
    F -->|Yes| G[Complete]
    F -->|No| B

Agent Responsibilities:

Agent Responsibility Quality Gates
implementer Write code, tests, docs Type hints, docstrings, >80% coverage
code-reviewer Security, correctness No vulnerabilities, best practices
tester Run test suite All tests passing, no regressions

Phase 6: Validation

Final quality checks:

  • ✅ All tests passing
  • ✅ Code coverage >80%
  • ✅ Type hints complete (mypy clean)
  • ✅ Linting clean (ruff clean)
  • ✅ Security review passed
  • ✅ Documentation complete

Phase 7: Summary

Returns structured summary:

IMPLEMENTATION COMPLETE

Files Modified: 3
- src/auth/routes.py: +87 lines (authentication endpoints)
- src/auth/models.py: +45 lines (User model)
- tests/auth/test_auth.py: +156 lines (comprehensive tests)

Tests: ✅ 18/18 passing
Coverage: 91% (target: >80%)

Validation:
- ✅ Type hints complete (mypy clean)
- ✅ Linting clean (ruff clean)
- ✅ Security review passed
- ✅ No hardcoded secrets

Ready for: Production deployment

Task Categories

Feature Implementation

Implement new functionality from scratch.

Examples:

/novaai implement user registration with email verification
/novaai create a REST API endpoint for blog posts
/novaai add OAuth2 authentication with GitHub

What happens:

  1. Searches KB for similar implementations
  2. Creates implementation following project patterns
  3. Writes comprehensive tests
  4. Documents with docstrings
  5. Code review for security and correctness

Bug Fixes

Fix existing issues with regression testing.

Examples:

/novaai fix the timeout error in the API client
/novaai resolve the authentication token expiration bug
/novaai fix the broken import in src/auth/service.py

What happens:

  1. Locates buggy code
  2. Writes test that reproduces bug
  3. Implements fix
  4. Ensures test passes
  5. Adds regression tests

Code Review

Analyze code for security, correctness, and best practices.

Examples:

/novaai review src/auth/ for security issues
/novaai review PR #123 and provide feedback
/novaai audit the payment module for vulnerabilities

What happens:

  1. Deep code analysis
  2. Security vulnerability scan
  3. Best practices compliance
  4. Performance optimization suggestions
  5. Detailed report with action items

Testing

Add or improve test coverage.

Examples:

/novaai add unit tests for the UserService class
/novaai create integration tests for authentication flow
/novaai improve test coverage for src/payment/

What happens:

  1. Analyzes existing tests
  2. Identifies gaps in coverage
  3. Writes comprehensive tests (unit + integration)
  4. Ensures >80% coverage
  5. Tests edge cases and error conditions

Refactoring

Improve code structure while maintaining functionality.

Examples:

/novaai refactor the payment module for better performance
/novaai simplify the authentication logic
/novaai extract common code into reusable utilities

What happens:

  1. Ensures existing tests exist
  2. Refactors incrementally
  3. Runs tests continuously
  4. Updates documentation
  5. Maintains backward compatibility

Documentation

Add or improve documentation.

Examples:

/novaai document the UserService class with docstrings
/novaai create API documentation for auth endpoints
/novaai add usage examples to the README

What happens:

  1. Analyzes existing code
  2. Writes Google-style docstrings
  3. Adds type hints
  4. Creates usage examples
  5. Updates relevant docs

Best Practices

Writing Effective Requests

Good Requests (Specific):

✅ /novaai implement user registration with email validation, password hashing using bcrypt, and JWT tokens
✅ /novaai fix the timeout error in src/api/client.py by adding retry logic with exponential backoff
✅ /novaai add unit tests for UserService.create_user() covering success, duplicate email, and weak password cases

Poor Requests (Vague):

❌ /novaai make the auth better
❌ /novaai fix the bug
❌ /novaai add tests

Provide Context

Include relevant details:

  • What: Specific feature or issue
  • Where: File paths or modules
  • How: Technical approach (if you have preferences)
  • Why: Business requirements or constraints

Example:

/novaai implement rate limiting for API endpoints using Redis,
limiting users to 100 requests per minute, with exponential backoff
for exceeded limits, and proper error messages

Iterative Refinement

Use follow-up commands to refine:

# First request
/novaai implement user authentication

# Review results, then refine
/novaai add refresh token rotation to the authentication system
/novaai improve error messages in the login endpoint

The orchestrator automatically searches the knowledge base, but you can guide it:

/novaai implement user authentication following the JWT best practices in the knowledge base

Advanced Usage

Session Continuation

Reuse sessions for related tasks (88-95% overhead reduction):

# First task creates session
/novaai implement user registration

# Follow-up task reuses session (faster)
/novaai add login endpoint

# Another related task
/novaai add password reset functionality

The orchestrator automatically manages sessions for related tasks.

Multi-Agent Coordination

For complex tasks, the orchestrator coordinates multiple agents:

/novaai design and implement a microservices architecture for the API
with user service, payment service, and notification service

Agent Flow:

  1. architect - Design architecture and trade-offs
  2. orchestrator - Break down into phases
  3. implementer - Implement each service
  4. code-reviewer - Review security and correctness
  5. tester - Integration testing
  6. orchestrator - Validate and summarize

Parallel Execution

The orchestrator can run independent tasks in parallel:

/novaai implement user service, payment service, and notification service in parallel

See Parallel Execution for details.

Troubleshooting

Command Not Recognized

Error: Unknown command '/novaai'

Solution: Ensure you're in Claude Code with the nova_ai project loaded.

Planning Phase Hangs

Solution: Check your API key and network connection:

export ANTHROPIC_API_KEY="your-key-here"

Agent Switch Fails

Error: Failed to delegate to implementer agent

Solution: Check agent configuration:

ls -la .claude/agents/

No KB Results Found

Solution: Verify knowledge base is set up:

ls -la kb_store/faiss_metadata/

Keyboard Shortcuts

  • Enter - Approve plan and execute
  • Ctrl+C - Cancel execution
  • Ctrl+K - Open search (in docs)

Tips for Success

  1. Be Specific - Clear requests get better results
  2. Review Plans - The 30-second planning saves hours of debugging
  3. Trust the Process - Quality gates catch issues early
  4. Iterate - Refine incrementally with follow-up commands
  5. Check Output - Review the summary for file changes and metrics

Next Steps