vox-core 0.2.0__tar.gz

vox_core-0.2.0/.ai/COMMANDS/_shared/README.md

@@ -0,0 +1,13 @@
+# Shared Command Blocks
+
+This folder contains reusable guidance blocks referenced by runnable commands in `.ai/COMMANDS/`.
+
+These files are not primary entry commands. Use them as referenced from:
+- `commit.md`
+- `push.md`
+- `review.md`
+- `pr.md`
+
+Purpose:
+- avoid duplicating checklists and quality bars across commands
+- keep commit/PR/review expectations consistent

vox_core-0.2.0/.ai/COMMANDS/_shared/review-checklist.md

@@ -0,0 +1,23 @@
+# Self-Review Checklist (Reusable)
+
+Use this checklist before commit and PR.
+
+## Bugs / Correctness
+- Does behavior match plan/spec exactly?
+- Any obvious runtime errors, edge-case failures, or invalid assumptions?
+
+## Regressions
+- Could this break existing workflows, APIs, CLI contracts, or data contracts?
+- Were impacted areas re-tested?
+
+## Tests
+- Are new/changed behaviors covered by tests?
+- Are missing tests explicitly documented as risk?
+
+## Risks
+- Security, data loss, migration, compatibility, performance, operational risk noted?
+- Are rollback/remediation paths clear?
+
+## Evidence
+- Validation commands and outcomes are captured.
+- User-visible outputs are proven with direct verification commands.

vox_core-0.2.0/.ai/COMMANDS/_shared/story-writing.md

@@ -0,0 +1,20 @@
+# Story Writing For Commits and PRs
+
+High-signal history explains both implementation and intent.
+
+Use this structure:
+
+## Context
+- What problem or gap existed?
+
+## Changes
+- What was implemented? (major files/components only)
+
+## Why
+- Why this approach or tradeoff?
+
+## Validation
+- Which commands prove it works? Include outcomes.
+
+## Impact
+- What can users/developers do now that they could not do before?

vox_core-0.2.0/.ai/COMMANDS/check_tests.md

@@ -0,0 +1,190 @@
+---
+description: "Audit repository tests and produce evidence-backed quality + fix plan"
+---
+
+# Check Tests: Rigorous Test Audit Workflow
+
+You are a `test-auditor`. Your job is to systematically inspect the repository's tests and produce a rigorous, evidence-backed audit report plus a prioritized fix plan.
+
+## Non-Negotiable Rules
+
+- Do not skip steps. If you cannot perform a step, write `NOT CHECKED` and explain exactly why.
+- Every finding must cite evidence: file path + line range, or exact command output snippet.
+- Prefer truth over politeness. If tests are weak, say so plainly.
+- No vague claims like "looks fine" or "seems ok" without evidence.
+
+## Goals
+
+1. Evaluate test quality, maintainability, and bug-catching power.
+2. Detect common problems:
+   - brittleness
+   - over-mocking
+   - unclear intent
+   - poor coverage of edge cases
+   - integration tests disguised as unit tests
+   - dependence on real network/time/fs
+   - flaky behavior
+   - slow tests
+3. Produce a ranked list of concrete improvements with suggested code-level changes.
+
+## Workflow
+
+### Step 0 - Repo Recon
+
+- Identify language(s), test framework(s), and test layout conventions.
+- Enumerate all test files (glob patterns, directories).
+
+Required output:
+- `Test Inventory` table with:
+  - file
+  - framework
+  - approx # tests
+  - notes (mocks/fixtures/heavy setup)
+
+### Step 1 - Run Baseline
+
+- Run the full test suite.
+- Capture:
+  - pass/fail
+  - runtime
+  - top 5 slowest tests (if possible)
+  - failure summaries
+- Run a quick flake check:
+  - rerun tests 3x (or targeted suspicious ones) to detect flaky failures.
+
+Required output:
+- Commands executed + outputs summary.
+
+### Step 2 - Quality Rubric (Score Every Test File)
+
+For each test file, score `0-2` on each dimension (total `0-20`):
+
+- `A) Clarity/Intent`: test names + assertions make behavior obvious
+- `B) AAA Structure`: Arrange/Act/Assert separation is readable
+- `C) Independence`: no order dependence; minimal shared mutable state
+- `D) Determinism`: doesn't rely on wall clock, randomness (without seeding), network, external services
+- `E) Isolation`: unit tests don't touch DB/fs/network unless explicitly integration tests
+- `F) Assertions`: meaningful asserts; avoids "no assert" tests; checks outcomes not internals
+- `G) Setup Hygiene`: avoids huge fixtures; avoids brittle global fixtures; uses factories/builders
+- `H) Mocking Discipline`: mocks at boundaries; avoids mocking the system under test; avoids over-mocking
+- `I) Coverage of Edge Cases`: error paths, boundary values, weird inputs
+- `J) Maintainability`: low duplication; helper utilities used appropriately; failures are diagnosable
+
+For each file, include:
+
+- a score table row
+- `2-5` bullet findings with evidence (path + line range)
+- one `best next improvement` suggestion
+
+### Step 3 - Repo-Level Patterns
+
+Aggregate across all tests:
+
+- top 10 recurring issues
+- `Flake risks` list
+- `Slow risks` list
+- missing test layers: unit vs integration vs e2e; recommend a pyramid distribution appropriate to repo
+
+### Step 4 - Prioritized Fix Plan
+
+Create a plan ranked by ROI:
+
+- `P0`: fixes that reduce flakiness and increase determinism
+- `P1`: fixes that increase bug-catching power (assertions, edge cases)
+- `P2`: refactors that improve maintainability (fixtures, factories, helpers)
+
+Each item must include:
+
+- impact
+- effort (`S/M/L`)
+- files to touch
+- example change (pseudo-code or snippet)
+
+### Step 5 - Optional Patch Set
+
+Only if the human explicitly requests implementation after reviewing the audit, implement `1-3` `P0/P1` improvements as small, clean patches.
+
+Default behavior:
+
+- stop after reporting findings, scores, and prioritized recommendations
+- do not modify code/tests without explicit follow-up approval
+
+If implementation is explicitly requested:
+
+- keep each patch PR-sized
+- add/adjust tests without changing production behavior unless necessary
+- show diffs clearly
+
+## Calibration Examples
+
+Use these patterns when judging tests.
+
+### Example 1 - Clear Behavior vs Vague
+
+Bad:
+- `test_process(): assert process(x) != None`
+
+Good:
+- `test_process_returns_normalized_email_lowercases_and_strips_whitespace()`
+
+### Example 2 - Testing Implementation Details vs Outcomes
+
+Bad:
+- `assert service._cache["k"] == "v"` (pokes internals)
+
+Good:
+- `assert service.get("k") == "v"` (validates public behavior)
+
+### Example 3 - Brittle Time/Network vs Deterministic Seams
+
+Bad:
+- calls real `time.sleep()`, `datetime.now()`, real HTTP
+
+Good:
+- inject clock/http client; freeze time; use stub server or mock at boundary
+
+### Example 4 - Over-Mocking vs Boundary Mocking
+
+Bad:
+- mocks every collaborator; asserts call order and exact args everywhere
+
+Good:
+- mocks only external boundary (db/http/fs); asserts meaningful outcome + key interaction(s) only
+
+### Example 5 - AAA Structure
+
+Bad:
+- setup/assert interleaved; hard to see what changed
+
+Good:
+- Arrange: build inputs
+- Act: call function
+- Assert: check outputs/errors
+
+## Reference Context
+
+Follow principles from Google's "Software Engineering at Google" testing chapters:
+
+- prefer fast, reliable unit tests
+- value maintainability and clarity
+
+Constraint:
+- do not quote directly; translate principles into the rubric and findings
+
+## Final Output Format
+
+1. Test Inventory (table)
+2. Execution Summary (commands + results)
+3. File-by-file Rubric Scores (table + per-file notes)
+4. Repo Patterns
+5. Prioritized Fix Plan
+6. Optional Patches (diffs or described edits)
+
+Before finishing, output a `Checklist` with `✅/❌`:
+
+- [ ] Enumerated all test files
+- [ ] Ran full test suite
+- [ ] Ran flake check (rerun)
+- [ ] Scored every test file with rubric
+- [ ] Evidence provided for every claim
+- [ ] Prioritized fix plan with ROI ranking

vox_core-0.2.0/.ai/COMMANDS/commit.md

@@ -0,0 +1,113 @@
+---
+description: "Create a commit with Commitizen/Conventional Commit compliance and high-signal context"
+---
+
+# Commit: High-Signal, Commitizen-Compliant
+
+## Objective
+
+Create a single atomic commit for the intended changes with a Commitizen-compliant message that explains both **what changed** and **why it changed**.
+
+Reusable guidance:
+- `.ai/COMMANDS/_shared/story-writing.md`
+- `.ai/COMMANDS/_shared/review-checklist.md`
+
+## Process
+
+### 1. Review change scope
+
+Run `.ai/COMMANDS/review.md` first.
+
+Branch safety check (required):
+- `git branch --show-current`
+- If branch is `main`, stop and create/switch to a feature branch before committing.
+
+- Run:
+  - `git status`
+  - `git diff HEAD`
+  - `git status --porcelain`
+- Confirm the commit scope is coherent and atomic.
+- If unrelated changes are present, do not include them.
+
+### 2. Stage only intended files
+
+- Add modified and untracked files that belong to this commit.
+- Re-check staged scope:
+  - `git diff --cached --stat`
+  - `git diff --cached`
+
+### 3. Write Commitizen-compliant message
+
+Message must follow Conventional Commits / Commitizen:
+
+`<type>(<optional-scope>): <short imperative summary>`
+
+Allowed types:
+- `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+Optional breaking-change marker:
+- `type(scope)!: summary`
+- or `BREAKING CHANGE:` footer in body
+
+### 4. Tell the story in the body
+
+Commit body is required for non-trivial changes. Include:
+- Context/problem: what was missing or broken.
+- Key changes: what was implemented (major files/components).
+- Reasoning: why this approach was chosen.
+- Outcome: what is now possible/verified.
+
+Recommended body structure:
+
+```text
+Context:
+- ...
+
+Changes:
+- ...
+
+Why:
+- ...
+
+Validation:
+- <command/result>
+- <command/result>
+```
+
+### 5. Add footers when relevant
+
+- Reference plans/issues:
+  - `Refs: .ai/PLANS/<NNN>-<feature>.md`
+- Breaking changes:
+  - `BREAKING CHANGE: ...`
+
+## Quality Bar
+
+- Subject line is <= 72 chars, imperative, specific.
+- Type/scope accurately reflect the primary intent.
+- Body explains both implementation and motivation.
+- Future readers (human or AI) can understand the change without re-reading the full diff.
+- Message matches staged content exactly.
+
+## Example
+
+```text
+docs(reboot): align rules and command references with reboot baseline
+
+Context:
+- command guidance referenced removed targets and legacy architecture paths.
+
+Changes:
+- updated `.ai/RULES.md` architecture/boundary guidance for current repository layout
+- updated command/reference docs to use active `just` targets
+- removed stale examples that referenced legacy render subsystem paths
+
+Why:
+- keep workflow docs actionable so validation and execution commands match real repo state
+
+Validation:
+- just quality-check (pass)
+- just status (pass)
+
+Refs: .ai/PLANS/016-example-reboot-docs-alignment.md
+```

vox_core-0.2.0/.ai/COMMANDS/create-prd.md

@@ -0,0 +1,158 @@
+---
+description: Create a Product Requirements Document from conversation
+argument-hint: [plan-slug-or-output-path]
+---
+
+# Create PRD: Generate Product Requirements Document
+
+## Overview
+
+Generate a comprehensive Product Requirements Document (PRD) based on the current conversation context and requirements discussed. Use the structure and sections defined below to create a thorough, professional PRD.
+
+## Output File
+
+Write the PRD to: `$ARGUMENTS` (default: `.ai/SPECS/<NNN>-<feature>/PRD.md`)
+
+Default behavior:
+- If an active plan exists (`.ai/PLANS/<NNN>-<feature>.md`), write to `.ai/SPECS/<NNN>-<feature>/PRD.md`.
+- If `$ARGUMENTS` is a plan slug like `<NNN>-<feature>`, write to `.ai/SPECS/<NNN>-<feature>/PRD.md`.
+- If `$ARGUMENTS` is a path, write exactly there.
+- Never default to repo root.
+
+## PRD Structure
+
+Create a well-structured PRD with the following sections. Adapt depth and detail based on available information:
+
+### Required Sections
+
+**1. Executive Summary**
+- Concise product overview (2-3 paragraphs)
+- Core value proposition
+- MVP goal statement
+
+**2. Mission**
+- Product mission statement
+- Core principles (3-5 key principles)
+
+**3. Target Users**
+- Primary user personas
+- Technical comfort level
+- Key user needs and pain points
+
+**4. MVP Scope**
+- **In Scope:** Core functionality for MVP (use ✅ checkboxes)
+- **Out of Scope:** Features deferred to future phases (use ❌ checkboxes)
+- Group by categories (Core Functionality, Technical, Integration, Deployment)
+
+**5. User Stories**
+- Primary user stories (5-8 stories) in format: "As a [user], I want to [action], so that [benefit]"
+- Include concrete examples for each story
+- Add technical user stories if relevant
+
+**6. Core Architecture & Patterns**
+- High-level architecture approach
+- Directory structure (if applicable)
+- Key design patterns and principles
+- Technology-specific patterns
+
+**7. Tools/Features**
+- Detailed feature specifications
+- If building an agent: Tool designs with purpose, operations, and key features
+- If building an app: Core feature breakdown
+
+**8. Technology Stack**
+- Backend/Frontend technologies with versions
+- Dependencies and libraries
+- Optional dependencies
+- Third-party integrations
+
+**9. Security & Configuration**
+- Authentication/authorization approach
+- Configuration management (environment variables, settings)
+- Security scope (in-scope and out-of-scope)
+- Deployment considerations
+
+**10. API Specification** (if applicable)
+- Endpoint definitions
+- Request/response formats
+- Authentication requirements
+- Example payloads
+
+**11. Success Criteria**
+- MVP success definition
+- Functional requirements (use ✅ checkboxes)
+- Quality indicators
+- User experience goals
+
+**12. Implementation Phases**
+- Break down into 3-4 phases
+- Each phase includes: Goal, Deliverables (✅ checkboxes), Validation criteria
+- Realistic timeline estimates
+
+**13. Future Considerations**
+- Post-MVP enhancements
+- Integration opportunities
+- Advanced features for later phases
+
+**14. Risks & Mitigations**
+- 3-5 key risks with specific mitigation strategies
+
+**15. Appendix** (if applicable)
+- Related documents
+- Key dependencies with links
+- Repository/project structure
+
+## Instructions
+
+### 1. Extract Requirements
+- Review the entire conversation history
+- Identify explicit requirements and implicit needs
+- Note technical constraints and preferences
+- Capture user goals and success criteria
+
+### 2. Synthesize Information
+- Organize requirements into appropriate sections
+- Fill in reasonable assumptions where details are missing
+- Maintain consistency across sections
+- Ensure technical feasibility
+
+### 3. Write the PRD
+- Use clear, professional language
+- Include concrete examples and specifics
+- Use markdown formatting (headings, lists, code blocks, checkboxes)
+- Add code snippets for technical sections where helpful
+- Keep Executive Summary concise but comprehensive
+
+### 4. Quality Checks
+- ✅ All required sections present
+- ✅ User stories have clear benefits
+- ✅ MVP scope is realistic and well-defined
+- ✅ Technology choices are justified
+- ✅ Implementation phases are actionable
+- ✅ Success criteria are measurable
+- ✅ Consistent terminology throughout
+
+## Style Guidelines
+
+- **Tone:** Professional, clear, action-oriented
+- **Format:** Use markdown extensively (headings, lists, code blocks, tables)
+- **Checkboxes:** Use ✅ for in-scope items, ❌ for out-of-scope
+- **Specificity:** Prefer concrete examples over abstract descriptions
+- **Length:** Comprehensive but scannable (typically 30-60 sections worth of content)
+
+## Output Confirmation
+
+After creating the PRD:
+1. Confirm the file path where it was written
+2. Provide a brief summary of the PRD contents
+3. Highlight any assumptions made due to missing information
+4. Suggest next steps (e.g., review, refinement, planning)
+
+## Notes
+
+- If critical information is missing, ask clarifying questions before generating
+- If neither an active plan slug nor `$ARGUMENTS` is available, ask for a slug/path before writing
+- Adapt section depth based on available details
+- For highly technical products, emphasize architecture and technical stack
+- For user-facing products, emphasize user stories and experience
+- This command contains the complete PRD template structure - no external references needed

vox_core-0.2.0/.ai/COMMANDS/create-rules.md

@@ -0,0 +1,155 @@
+description: Create global rules (.ai/RULES.md) from codebase analysis
+---
+
+# Create Global Rules
+Generate or refresh `.ai/RULES.md` for Codex/Cursor by analyzing the codebase and extracting enforceable patterns.
+
+---
+
+## Objective
+
+Create project-specific global rules that give coding agents (Codex/Cursor) context about:
+- What this project is
+- Technologies used
+- How the code is organized
+- Patterns and conventions to follow
+- How to build, test, and validate
+
+---
+
+## Phase 1: DISCOVER
+
+### Identify Project Type
+
+First, determine what kind of project this is:
+
+| Type | Indicators |
+|------|------------|
+| Web App (Full-stack) | Separate client/server dirs, API routes |
+| Web App (Frontend) | React/Vue/Svelte, no server code |
+| API/Backend | Express/Fastify/etc, no frontend |
+| Library/Package | `main`/`exports` in package.json, publishable |
+| CLI Tool | `bin` in package.json, command-line interface |
+| Monorepo | Multiple packages, workspaces config |
+| Script/Automation | Standalone scripts, task-focused |
+
+### Analyze Configuration
+
+Look at root configuration files:
+
+```
+package.json       → dependencies, scripts, type
+tsconfig.json      → TypeScript settings
+vite.config.*      → Build tool
+*.config.js/ts     → Various tool configs
+```
+
+### Map Directory Structure
+
+Explore the codebase to understand organization:
+- Where does source code live?
+- Where are tests?
+- Any shared code?
+- Configuration locations?
+
+---
+
+## Phase 2: ANALYZE
+
+### Extract Tech Stack
+
+From package.json and config files, identify:
+- Runtime/Language (Node, Bun, Deno, browser)
+- Framework(s)
+- Database (if any)
+- Testing tools
+- Build tools
+- Linting/formatting
+
+### Identify Patterns
+
+Study existing code for:
+- **Naming**: How are files, functions, classes named?
+- **Structure**: How is code organized within files?
+- **Errors**: How are errors created and handled?
+- **Types**: How are types/interfaces defined?
+- **Tests**: How are tests structured?
+
+### Find Key Files
+
+Identify files that are important to understand:
+- Entry points
+- Configuration
+- Core business logic
+- Shared utilities
+- Type definitions
+
+---
+
+## Phase 3: GENERATE
+
+### Create/Refresh `.ai/RULES.md`
+
+Use the current `.ai/RULES.md` and `.ai/REF/README.md` as the starting baseline.
+
+**Output path**: `.ai/RULES.md`
+
+**Adapt to the project:**
+- Remove sections that don't apply
+- Add sections specific to this project type
+- Keep it concise - focus on what's useful and enforceable for coding agents
+
+**Key sections to include:**
+
+1. **Project Overview** - What is this and what does it do?
+2. **Tech Stack** - What technologies are used?
+3. **Commands** - How to dev, build, test, lint?
+4. **Structure** - How is the code organized?
+5. **Patterns** - What conventions should be followed?
+6. **Key Files** - What files are important to know?
+
+**Optional sections (add if relevant):**
+- Architecture (for complex apps)
+- API endpoints (for backends)
+- Component patterns (for frontends)
+- Database patterns (if using a DB)
+- On-demand context references
+- Project-type overlays (link to `.ai/REF/project-types/*` and instruct when to read each)
+
+---
+
+## Phase 4: OUTPUT
+
+```markdown
+## Global Rules Updated
+
+**File**: `.ai/RULES.md`
+
+### Project Type
+
+{Detected project type}
+
+### Tech Stack Summary
+
+{Key technologies detected}
+
+### Structure
+
+{Brief structure overview}
+
+### Next Steps
+
+1. Review the updated `.ai/RULES.md`
+2. Add any project-specific notes
+3. Ensure `.ai/REF/*` contains package-specific guidance linked from `.ai/RULES.md`
+4. Run PRIME/PLAN/EXECUTE workflows against the updated rules
+```
+
+---
+
+## Tips
+
+- Keep `.ai/RULES.md` focused and scannable
+- Don't duplicate information that's in other docs (link instead)
+- Focus on patterns and conventions, not exhaustive documentation
+- Update it as the project evolves