Skip to content

chore: automate agent instruction mirroring #332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Coldaine wants to merge 3 commits into
base: main
Choose a base branch
from
Open

chore: automate agent instruction mirroring #332

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92a5e1a
chore: automate agent instruction mirroring
Dec 25, 2025
814af07
docs: clarify solo-dev trust model
Dec 25, 2025
2ed660c
docs: keep agent instruction mirrors in sync
Dec 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .githooks/post-checkout
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
#!/usr/bin/env bash
set -euo pipefail

repo_root="$({
cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd
})"

"$repo_root/scripts/ensure_agent_hardlinks.sh" >/dev/null
Copy link

Copilot AI Dec 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The git hook redirects all output to /dev/null, which will hide error messages if the hardlink script fails. Users won't know why their hooks are failing. Consider redirecting only stdout (1>/dev/null) or capturing and logging errors to allow debugging while keeping the output quiet.

Copilot uses AI. Check for mistakes.
8 changes: 8 additions & 0 deletions .githooks/post-merge
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
#!/usr/bin/env bash
set -euo pipefail

repo_root="$({
cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd
})"

"$repo_root/scripts/ensure_agent_hardlinks.sh" >/dev/null
Copy link

Copilot AI Dec 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The git hook redirects all output to /dev/null, which will hide error messages if the hardlink script fails. Users won't know why their hooks are failing. Consider redirecting only stdout (1>/dev/null) or capturing and logging errors to allow debugging while keeping the output quiet.

Suggested change
"$repo_root/scripts/ensure_agent_hardlinks.sh" >/dev/null
"$repo_root/scripts/ensure_agent_hardlinks.sh" 1>/dev/null

Copilot uses AI. Check for mistakes.
1 change: 0 additions & 1 deletion .github/copilot-instructions.md
View file
Open in desktop

This file was deleted.

216 changes: 216 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,216 @@
# AGENTS.md

> Canonical AI agent instructions for ColdVox. All tools (Claude Code, Copilot, Cursor, Kilo Code, etc.) should read this file.

> **⚠️ CRITICAL**: Some documented features are broken or removed. See [`docs/plans/critical-action-plan.md`](docs/plans/critical-action-plan.md) before following STT instructions.

> **Solo-dev trust model**: This repo is effectively single-developer. We optimize for local productivity/automation over “untrusted contributor” safety. If a tool/setup step enables automation (e.g., repo-managed git hooks), that’s intentional.

## Key Docs

- [`README.md`](README.md) - Project overview and quick start
- [`CLAUDE.md`](CLAUDE.md) - Deep-dive guide (Claude-specific + imports AGENTS)
- [`docs/plans/critical-action-plan.md`](docs/plans/critical-action-plan.md) - What’s currently broken/misleading
- [`docs/dev/CI/architecture.md`](docs/dev/CI/architecture.md) - CI runner split and rationale
- [`docs/standards.md`](docs/standards.md) - Documentation + changelog standards
- [`docs/MasterDocumentationPlaybook.md`](docs/MasterDocumentationPlaybook.md) - Documentation structure and rules

## Project Overview

ColdVox is a Rust-based voice AI pipeline: audio capture → VAD → STT → text injection. Multi-crate Cargo workspace under `crates/`.

**Key crates**: `coldvox-app` (main), `coldvox-audio`, `coldvox-vad`, `coldvox-vad-silero`, `coldvox-stt`, `coldvox-text-injection`, `coldvox-telemetry`, `coldvox-foundation`, `coldvox-gui`

## Worktrees

Use git worktrees for parallel agent work. This allows multiple agents to work on independent tasks simultaneously.

```bash
# Create worktree for a new task
git worktree add ../.trees/coldvox-{task} -b {task}
cd ../.trees/coldvox-{task}

# List all worktrees
git worktree list

# Remove when done (after merge)
git worktree remove ../.trees/coldvox-{task}
```

**Convention**: Worktrees live in `../.trees/coldvox-{branch-name}` to keep them adjacent but separate.

## Commands

### File-Scoped (Preferred)

Always prefer file/crate-scoped commands over full workspace commands for faster feedback:

```bash
# Type check single crate
cargo check -p coldvox-stt

# Clippy single crate
cargo clippy -p coldvox-audio
# Test single crate
cargo test -p coldvox-text-injection

# Format check (always full, it's fast)
cargo fmt --all -- --check
```

### Full Workspace (When Needed)

```bash
just lint # fmt + clippy + check (pre-push)
just test # cargo test --workspace --locked
just build # cargo build --workspace --locked
just ci # Full CI mirror via ./scripts/local_ci.sh
```

### Running

```bash
just run # Main app
just tui # TUI dashboard
cargo run --features text-injection # Text injection enabled
```

## Do

- Use `just lint` before every push
- Prefer crate-scoped commands for faster iteration
- Use feature flags: `whisper`, `parakeet`, `text-injection`, `silero`
- Follow Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`
- Run `cargo fmt --all` before committing
- Add tests for new functionality
- Update `CHANGELOG.md` for user-visible changes (see `docs/standards.md`)

## Don't

- Don't run full workspace builds when crate-scoped works
- Don't commit secrets or `.env` files
- Don't edit generated code under `target/`
- Don't add heavy dependencies without discussion
- Don't skip `just lint` before pushing
- Don't create `docs/agents.md` - agent config lives at repo root

## Project Structure

```
crates/
app/ # Main application, binaries, integration
coldvox-audio/ # Audio capture, ring buffer, resampling
coldvox-vad/ # VAD traits and config
coldvox-vad-silero/ # Silero V5 ONNX VAD implementation
coldvox-stt/ # STT abstractions and plugins (Whisper, Parakeet)
coldvox-text-injection/ # Platform-specific text injection backends
coldvox-telemetry/ # Pipeline metrics
coldvox-foundation/ # Core types, error handling, shutdown
coldvox-gui/ # GUI components

config/ # Runtime configuration
docs/ # Documentation (see MasterDocumentationPlaybook.md)
scripts/ # Automation scripts
```

## Feature Flags

Default: `silero`, `text-injection`

- `whisper` - Faster-Whisper STT (Python-based, CPU/GPU)
- `parakeet` - NVIDIA Parakeet STT (GPU-only, pure Rust)
- `text-injection` - Platform-aware text injection
- `silero` - Silero V5 ONNX VAD (default)
- `examples` - Example binaries
- `live-hardware-tests` - Hardware test suites

## Safety & Permissions

**Allowed without prompt:**
- Read files, list files, search code
- Crate-scoped: check, clippy, test, fmt
- Git status, diff, log

**Ask first:**
- Package/dependency changes
- Git push, force operations
- Deleting files
- Full workspace builds (prefer crate-scoped)
- Database migrations
- Running with hardware features

## When Stuck

- Ask a clarifying question
- Propose a short plan before large changes
- Open a draft PR with notes
- Don't push large speculative changes without confirmation

## Key Files

- **Main entry**: `crates/app/src/main.rs`
- **Audio pipeline**: `crates/coldvox-audio/src/capture.rs`
- **VAD engine**: `crates/coldvox-vad-silero/src/silero_wrapper.rs`
- **STT plugins**: `crates/coldvox-stt/src/plugins/`
- **Text injection**: `crates/coldvox-text-injection/src/manager.rs`
- **Build detection**: `crates/app/build.rs` (platform detection)

## Documentation

- `docs/MasterDocumentationPlaybook.md` - Documentation standards
- `docs/standards.md` - Changelog rubric, metadata requirements
- `docs/architecture.md` - System design and future vision
- `docs/domains/` - Domain-specific technical docs

## CI Environment

> **Principle**: The self hosted runner on the laptop is used for hardware tests, CI for everything else.

See [CI Architecture](docs/dev/CI/architecture.md) for full details.

### Self-Hosted Runner (Fedora/Nobara)

| Fact | Implication |
|------|-------------|
| **Live KDE Plasma session** | NO Xvfb needed. Use real `$DISPLAY`. |
| **Fedora-based** | `apt-get` does NOT exist. Use `dnf`. |
| **Always available** | Auto-login, survives reboots. |
| **Warm sccache** | Incremental builds ~2-3 min. |

### CI Split

| Task | Runner | Why |
|------|--------|-----|
| `cargo fmt`, `cargo clippy` | GitHub-hosted | Fast, parallel, free |
| `cargo audit`, `cargo deny` | GitHub-hosted | Security checks, no build needed |
| `cargo build` | **Self-hosted** | Warm cache, THE build |
| Hardware tests | **Self-hosted** | Requires display/audio/clipboard |

### DON'T (Common AI Mistakes)

```yaml
# WRONG - runner has live display, also uses apt-get internally
- uses: GabrielBB/xvfb-action@v1

# WRONG - this is Fedora, not Ubuntu
- run: sudo apt-get install -y xdotool

# WRONG - real display is :0
env:
DISPLAY: ":99"

# WRONG - delays self-hosted by 5-10 min
hardware:
needs: [lint, build]

# WRONG - wasted work, can't share artifacts with Fedora
- run: cargo build # On ubuntu-latest
```

## PR Checklist

- [ ] `just lint` passes
- [ ] `just test` passes (or crate-scoped tests)
- [ ] Changelog updated if user-visible
- [ ] Commit messages follow Conventional Commits
- [ ] No secrets or sensitive data
5 changes: 5 additions & 0 deletions .github/workflows/docs-ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,11 @@ jobs:
run: |
uv run scripts/validate_docs.py "${{ github.event.pull_request.base.sha }}" "${{ github.sha }}"

- name: Validate agent instruction mirrors
run: |
diff -u AGENTS.md .github/copilot-instructions.md
diff -u AGENTS.md .kilocode/rules/agents.md
Comment on lines +42 to +45
Copy link

Copilot AI Dec 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The CI check validates that mirror files match AGENTS.md using diff, but this happens after checkout. If someone forgets to run the hardlink script locally, the CI will catch it. However, the error message from diff won't be very helpful to developers who don't understand the hardlink system. Consider adding a comment or documentation in the workflow explaining what this check does and how to fix failures (run just link-agents or ./scripts/ensure_agent_hardlinks.sh).

Copilot uses AI. Check for mistakes.

Comment on lines +44 to +46
Copy link

Copilot AI Dec 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The diff commands will fail and cause the CI job to fail if the files differ. However, diff exits with status 1 when files differ (which is the expected case when someone forgets to sync mirrors). Consider either adding || true to allow the step to complete and show the difference, or adding a more descriptive error message. Alternatively, use diff -q first to check, then show detailed diff only if they differ.

Suggested change
diff -u AGENTS.md .github/copilot-instructions.md
diff -u AGENTS.md .kilocode/rules/agents.md
set +e
DIFF_FAILED=0
diff -u AGENTS.md .github/copilot-instructions.md || DIFF_FAILED=1
diff -u AGENTS.md .kilocode/rules/agents.md || DIFF_FAILED=1
if [ "$DIFF_FAILED" -ne 0 ]; then
echo "::error::Agent instruction mirrors are out of sync. Please update .github/copilot-instructions.md and .kilocode/rules/agents.md to match AGENTS.md."
exit 1
fi

Copilot uses AI. Check for mistakes.
- name: Append revision log entries
run: |
uv run scripts/docs_revision_logger.py "${{ github.event.pull_request.base.sha }}" "${{ github.sha }}" "${{ github.actor }}"
Expand Down
1 change: 0 additions & 1 deletion .kilocode/rules/agents.md
View file
Open in desktop

This file was deleted.

Loading
Loading