Skip to content

Code Assist Tools

See also: Programmer's Guide · Coding Standards · Adding Plugins · Template Source Code

The milk project includes agent rules and workflows that guide AI coding assistants (Gemini, Copilot, etc.) to follow project conventions automatically. They live under:

.agents/
├── rules/        # Always-on guardrails
├── skills/       # Deep-dive instruction sets
└── workflows/    # On-demand task templates

Collaborators benefit even without using an AI assistant — the rule and workflow files document the conventions, checklists, and cross-references that every contributor should know.

Getting Started

New to adding capabilities? Start with these:

  1. Developer Tutorial — write your first module end-to-end.
  2. Adding Plugins — CMake setup, dual-mode headers, _compute variants.
  3. Template Source Code — which template file to copy for each use case.

Agent Rules

Rules fire automatically when a task touches relevant code. They enforce conventions without requiring you to remember every checklist.

Rule File What it enforces
Agent docs update agent-docs-update.md Update AGENTS.md and code_assist.md when agent files change.
Architecture principles architecture-principles.md Minimize cross-module deps; consult dependency_graph.md before adding new ones.
CMake conventions cmake-conventions.md Use PUBLIC/INTERFACE properties; each module owns its headers.
Code style code-style-guide.md 80-char lines, Kernel-Doc, Linux kernel style, explicit includes.
Compile after edit compile-after-edit.md Always run /compile-test after modifying C/CMake.
Concurrency practices concurrency-practices.md Semaphore protocol, FPS sync, process coordination.
Documentation site documentation-site.md MkDocs structure, page creation, tag categories.
Documentation standards documentation-standards.md Markdown formatting, shell prompts, link checking.
Error handling error-handling-practices.md Use milkDebugTools.h macros for errors.
fpsexec conventions fpsexec-conventions.md V2 template, 8-section layout, -h1 requirement.
Git workflow git-workflow.md PRs from feature branches into framework-dev; commit conventions.
Help consistency help-consistency.md Cross-check all sibling help sources when editing help content.
Programmer's Guide maintain-programmers-guide.md Update docs/programmers_guide.md on architectural changes.
Module dependencies module-deps-declaration.md MODULE_DEPS and INIT_MODULE_LIB_DEPS macros.
Performance practices performance-practices.md SIMD, BLAS, pointer alignment, type dispatch, memory allocation, CPU pinning.
README updates readme-update.md Update module README when source files are added/removed.
Running commands run-milk-commands.md Environment setup, SHM cleanup, tmux session management.
Script documentation script-docs.md Update docs/scripts.md and add --help when scripts change.
Shared memory safety shared-memory-safety.md SHM cleanup, stale detection, stream creation.
Testing practices testing-practices.md Run tests after changes; add regression tests.
Workspace layout files-directories.md cacao lives at plugins/cacao-src → ~/src/cacao.
What's New whatsnew-update.md Add entry to docs/whatsnew.md for significant features.

Skills

Skills live in .agents/skills/ and provide deep context for specialized tasks. Each skill folder contains a SKILL.md with detailed instructions.

Skill Folder What it provides
Feature planner feature-planner Structured planning and architectural decomposition for new features.
Batch Kernel-Doc batch-kernel-doc Systematic function documentation with scanning, templates, and batch processing.
CLI test writer cli-test-writer Writing test cases for the CLI robustness suite with coverage analysis.
CMake patterns cmake-patterns Module CMake setup, standalone builds, _compute variants.
Debug CLI behavior debug-cli-behavior Crash investigation, command registration tracing, display debugging.
Diagnose build failure diagnose-build-failure CMake/GCC error triage mapped to milk's build tiers.
FPS parameter guide fps-parameter-guide FPS parameter types, flags, X-macro patterns, common mistakes.
ImageStream internals imagestream-internals SHM stream layout, semaphore protocol, circular buffers.
Module loading internals module-loading-internals dlopen sequence, data.moduleindex race, constructor timing.
Milk script writer milk-script-writer Generate correct milk-cli scripts from natural language prompts.
Optimize compute function optimize-compute-function Systematic performance optimization methodology.
PR preparation pr-preparation End-to-end PR packaging with template body and AI authorship.
Refactor C source refactor-c-source Safe file splitting with dependency analysis and CMake updates.
Stream modifier guide stream-modifier-guide IMGID parsing pipeline, @S:/@L:/@F: modifiers, slice syntax.

Workflows

Workflows are invoked by typing the slash command as a chat message (e.g., /compile-test). They are step-by-step checklists for common tasks.

Command File What it does
/compile-test compile-test.md Incremental build, install, and test from _build/.
/create-fpsexec create-fpsexec.md Scaffold a new V2 fpsexec standalone executable.
/add-new-module add-new-module.md Scaffold a new plugin module (README, CMake, boilerplate).
/add-function add-function.md Add a function to an existing module (dispatches to sub-workflows).
/add-stream-processor add-stream-processor.md Scaffold a stream processing loop compute unit.
/add-cli-command add-cli-command.md Add a CLI command to an existing module.
/fix-bug fix-bug.md Investigate, fix, and verify a bug with regression test.
/migrate-to-v2 migrate-to-v2.md Convert V1 fpsexec code to V2 template layout.
/review-pr review-pr.md Review a PR for coding standards compliance.
/setup-dev-environment setup-dev-environment.md First-time development environment setup.
/update-programmers-guide update-programmers-guide.md Scan recent commits and refresh docs/programmers_guide.md.
/audit-help-consistency audit-help-consistency.md Cross-check all help sources for drift or contradictions.
/check-type-consistency check-type-consistency.md Audit switch blocks for incomplete type handling.
/cli-robustness-test cli-robustness-test.md Run the CLI robustness test suite.
/inspect-machine-code inspect-machine-code.md Assembly inspection for performance optimization.
/sync-worktree sync-worktree.md Sync worktree to latest framework-dev.
/update-docs-site update-docs-site.md Add or update MkDocs pages.
/update-scripts-docs update-scripts-docs.md Sync docs/scripts.md after script changes.

Adding New Rules or Workflows

Rules

Create a new .md file in .agents/rules/ with YAML frontmatter:

---
description: Short description of what this rule does
---

Then write the trigger conditions and required actions in markdown below the frontmatter.

Workflows

Create a new .md file in .agents/workflows/ with YAML frontmatter:

---
description: Short description of the workflow
---

Then write numbered steps below the frontmatter. Use // turbo-all at the top of the steps section if every command should auto-run without confirmation.

← Documentation Index