{{PROJECT_NAME}} — Agent Instructions

Cross-AI-tool guidance. Works with Claude Code, Cursor, Copilot, or any AI coding assistant. Generated by SOVA (sova setup)

Project Overview

{{PROJECT_DESCRIPTION}}

Tech Stack

{{TECH_STACK}}

Architecture

{{ARCHITECTURE_NOTES}}

Key Paths

Domain Guidelines Index

Remove rows for domains that don't apply. Add custom domains as needed.

Context Index

Knowledge System

This project uses a four-tier knowledge management system. See KNOWLEDGE.md for full architecture.

Promotion flow: Tier 2 (confirmed in 2+ tasks) → Tier 1 (confirmed in 2+ projects) → Tier 0.

Rules Files

Each file < 150 lines. Confirmed, stable patterns only. Add more as the project grows.

Project Tracker

{{#TASK_SOURCE_GITHUB}} This project uses GitHub Issues for task tracking.

• Issue commands: gh issue list, gh issue view <NUMBER> {{/TASK_SOURCE_GITHUB}} {{#TASK_SOURCE_JIRA}} This project uses JIRA for task tracking. {{/TASK_SOURCE_JIRA}} {{#TASK_SOURCE_LINEAR}} This project uses Linear for task tracking. {{/TASK_SOURCE_LINEAR}} {{#TASK_SOURCE_MANUAL}} This project uses manual task input. {{/TASK_SOURCE_MANUAL}}

Conventions

Branches

• Format: {{BRANCH_FORMAT}} (e.g., feat/42-add-user-auth)
• Base branch: {{BASE_BRANCH}}

Commits

{{#CONVENTIONAL_COMMITS}}

• Use conventional commits: type(scope): description
• Types: feat, fix, refactor, test, docs, chore, style, perf, ci {{/CONVENTIONAL_COMMITS}} {{#FREEFORM_COMMITS}}
• Descriptive commit messages, imperative mood {{/FREEFORM_COMMITS}} {{#NO_AI_COAUTHOR}}
• Do NOT add "Co-Authored-By" lines for AI {{/NO_AI_COAUTHOR}} {{#AI_COAUTHOR}}
• Add "Co-Authored-By: Claude noreply@anthropic.com" to commits {{/AI_COAUTHOR}}

PRs

• Title: {{PR_TITLE_FORMAT}} {{#PR_AUTO_LINK}}
• Include "Closes #N" in PR body to auto-link issues {{/PR_AUTO_LINK}}
• Include a test plan section

Code Quality

{{#TYPE_HINTS}}

• Type hints required on all new functions {{/TYPE_HINTS}} {{#NO_EMOJIS}}
• No emoji characters in code or documentation {{/NO_EMOJIS}}
• Follow existing code style and patterns
• Keep functions focused and small
• Make minimal, focused changes — don't refactor unrelated code
• Don't add features beyond what the issue asks for

Testing

• Always run tests before pushing
• Write tests for new features (TDD preferred) {{#COVERAGE_THRESHOLD}}
• Coverage threshold: {{COVERAGE_THRESHOLD}}% {{/COVERAGE_THRESHOLD}}

What NOT to Do

• Don't modify code unrelated to the current task
• Don't add dependencies without discussing first
• Don't skip tests or lower coverage
• Don't push without running the full test suite

Important Patterns

{{PATTERNS}}

Invariants

These constraints are checked automatically before push: {{INVARIANT_LIST}}

Persona

{{PERSONA_GUIDANCE}}

Agentic Workflow Commands

This repo has Claude Code commands in .claude/commands/:

Core Development

• /develop — implement a feature or fix (TDD approach)
• /develop-full — full workflow: develop + test + review + PR
• /develop-explain — explain approaches without implementing
• /test — run and fix tests iteratively
• /review — pre-push code review with auto-fix
• /debug — systematic debugging workflow

Pull Requests

• /pr — create PR with standard template
• /address-pr — address PR review comments (human and bot)
• /review-pr — review a teammate's PR

Project Management

• /standup — daily context summary
• /find-task — browse issue backlog and prioritize sprint work
• /issue — fetch and analyze a GitHub Issue
• /new-feature — set up a new feature branch
• /status — project health check

Post-Work

• /after-merge — post-merge cleanup
• /rearrange-commits — reorganize branch commits
• /ingest-review — learn from PR feedback
• /extract-knowledge — capture reusable patterns

Meta

• /agent-readiness — assess and improve AI readiness