Remove content that no longer matches the workflow: package templates already covered by the "Adding a New Package" steps, per-package notes, the duplicated beads command reference, and the mandatory git push steps. Drop the sequentialthinking MCP requirement and add a rule that AGENTS.md changes need an explicit user request.
10 KiB
Project Overview
This is a Nix flake overlay repository that provides additional packages for Nix/NixOS users. It uses numtide/blueprint as its foundation, which simplifies flake development by providing sensible defaults and automatic package discovery.
Repository URL: git+https://git.millerson.name/alex/millerson-overlay.nix.git
Key Concepts
- Don't assume. Don't hide confusion. Surface tradeoffs.
- Minimum code that solves the problem. Nothing speculative.
- NEVER touch AGENTS.md without user request.
- Touch only what you must. Clean up only your own mess.
- Define success criteria. Loop until verified.
Before Starting Any Work
MANDATORY — Before making code changes:
- Run
br robot-docs guide— Get full workflow context and available commands - Check for existing issues — Run
br readyto find available work - Claim the task — Use
br update <id> --claimbefore starting - Track via
brONLY — NEVER use TodoWrite, TaskCreate, or markdown TODO lists. All task tracking goes throughbr.
Violating this rule means the agent is working outside the project's workflow. Stop and re-claim via br first.
Required Skills
Always use these skills when working with this repository:
- nix - For nixpkgs package lookups, option searches, and NixOS/Home Manager queries
- nix-flakes - For reproducible builds, flake management, and devShell operations
- karpathy-guidelines - For high-quality task execution best practices
Blueprint Framework
This project uses numtide/blueprint which:
- Automatically discovers packages in the
packages/directory - Provides
perSystemoutputs for multi-system builds - Handles formatting, checking, and devShell generation
- Exposes
mkPackagesForfunction to build packages against any nixpkgs instance
Unstaged files are invisible to nix build, nix flake show, and nix run.
Two Overlay Strategies
-
overlays.default- Binary-cache-friendly- Uses packages built against this flake's nixpkgs revision
- Better for binary cache hits when using the same nixpkgs
-
overlays.shared-nixpkgs- Dependency-sharing- Builds packages against the consumer's nixpkgs (
final) - Shares dependencies with the rest of the system
- No second nixpkgs evaluation
- Trade-off: binary cache only hits when consumer's nixpkgs matches ours
- Builds packages against the consumer's nixpkgs (
Repository Structure
nix-overlay/
├── flake.nix # Main flake definition with inputs and outputs
├── overlays/
│ ├── default.nix # Overlay using pre-built packages (binary cache friendly)
│ └── shared-nixpkgs.nix # Overlay building against consumer's nixpkgs
├── packages/
│ ├── default/ # Meta-package listing all visible packages
│ │ ├── default.nix
│ │ └── package.nix
│ └── flake-inputs/ # Utility to cache all flake inputs
│ └── default.nix
├── README.md # User-facing documentation
├── AGENTS.md # This file - AI agent instructions
├── LICENSE
└── flake.lock
Adding a New Package
When adding a new package:
-
Create the directory:
mkdir -p packages/<package-name> -
Create
package.nixwith the actual derivation -
Create
default.nixas a wrapper:{ pkgs, ... }: pkgs.callPackage ./package.nix { }
3.5. Stage the package: git add packages/<package-name>/
Blueprint discovers packages from the git index, not the working directory.
Without this step, the package won't appear in flake outputs.
-
Test the package:
nix build .#<package-name> nix run .#<package-name> -
Update README.md to document the new package in the Available Packages table
-
Set appropriate metadata:
meta.description- Required, shown in package listingsmeta.mainProgram- Set for packages providing a CLI executablemeta.passthru.category- Optional, used for organization (e.g., "AI Coding Agents")meta.passthru.hideFromDocs- Set totrueto exclude from documentation
Common Tasks
Updating a Package Version
- Update
versioninpackage.nix - Update
src.hash(usenix-prefetch-githubor let Nix tell you the correct hash) - Update
cargoHashfor Rust packages (build will fail and tell you the correct hash) - Test:
nix build .#<package-name> - Update README if needed
Testing Changes
# Build specific package
nix build .#mcp-gateway
# Build all packages for current system
nix build .#packages
# Enter dev shell
nix develop
# Check formatting
nix flake check
Working with Overlays
When modifying overlay behavior:
overlays/default.nix: Receivespackagesfrom blueprint outputs, maps them tofinal.stdenv.hostPlatform.systemoverlays/shared-nixpkgs.nix: ReceivesmkPackagesFor, uses it to build against consumer'sfinal
Important Notes
Do's
- ✅ Use
pkgs.callPackagepattern for package definitions - ✅ Set proper
metaattributes (description, license, homepage) - ✅ Test packages with
nix buildbefore committing - ✅ Use
passthru.categoryfor organizational grouping - ✅ Follow Nixpkgs conventions for package naming and structure
Don'ts
- ❌ Don't modify
flake.lockmanually - usenix flake update - ❌ Don't hardcode system-specific paths or assumptions
- ❌ Don't forget to set
meta.mainProgramfor CLI tools - ❌ Don't use
with pkgs;at top level (can cause scope issues) - ❌ Don't commit packages that don't build
Debugging Tips
Package Doesn't Build
- Check the error message carefully
- Verify all dependencies are listed
- Check if the source hash is correct
- For Rust packages, verify
cargoHashmatches
Overlay Not Working
- Verify the overlay is correctly imported
- Check if the package exists in
packagesoutput - For
shared-nixpkgs, ensuremkPackagesForis available
Binary Cache Issues
- The
defaultoverlay is more likely to get cache hits - The
shared-nixpkgsoverlay builds from source unless nixpkgs revisions match
Resources
Updating Packages
Use nix-update to bump versions and update hashes:
# Update a package to the latest version
nix-update <package-name>
# Update to a specific version
nix-update <package-name> --version <version>
# Update a package pinned to a commit hash (e.g. skillsmcp)
nix-update <package-name> --version=branch=main
After updating, always test the build:
nix build .#<package-name>
Git Workflow
Committing Completed Work
Every completed job or feature must be committed to the git repository.
When preparing git commits, always following conventional commit conventions and keep it concise.
This ensures:
- Clean git history with proper commit message formatting
- No work is left uncommitted
- Consistent commit message style across the project
Advanced Git Operations
For advanced Git workflows (rebasing, cherry-picking, bisect, worktrees, reflog, history recovery), use the git-advanced-workflows skill.
This skill provides:
- Master advanced Git workflows including rebasing, cherry-picking, bisect, worktrees, and reflog
- Maintain clean history and recover from any situation
- Manage complex Git histories, collaborate on feature branches, or troubleshoot repository issues
Example Workflow: Adding a New Package
# 0. Claim the task via beads (MANDATORY before any work)
br ready # Find available work
br show <id> # Review task details
br update <id> --claim # Claim the task
# 1. Create package directory
mkdir -p packages/my-tool
# 2. Create package.nix (use appropriate template above)
# 3. Create default.nix wrapper
cat > packages/my-tool/default.nix << 'EOF'
{ pkgs, ... }:
pkgs.callPackage ./package.nix { }
EOF
# 3.5. Stage for Blueprint discovery
git add packages/my-tool/
# 4. Test build
nix build .#my-tool
# 5. If build fails, fix issues, then retry
# 6. Update README.md with new package info
# 7. Commit changes using conventional-commit skill
git add packages/my-tool README.md
# Then invoke: skill: "conventional-commit"
# 8. Close the task via beads
br close <id> # Mark task as complete
br sync --flush-only # Export issue state to .beads/issues.jsonl
git add .beads/ # Stage the exported state
git commit -m "sync beads"
Agent skills
Issue tracker
Issues live in the beads database (.beads/, driven by the br CLI), synced through git push. The Gitea remote is not the issue tracker. See docs/agents/issue-tracker.md.
Note: br is non-invasive and never executes git commands. After br sync --flush-only, you must manually run add .beads/ to git index and commit.
Triage labels
The five canonical triage roles keep their default names, applied as br labels. See docs/agents/triage-labels.md.
Domain docs
Single-context layout: CONTEXT.md plus docs/adr/ at the repo root. See docs/agents/domain.md.
Session Completion
When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git commit succeeds.
MANDATORY WORKFLOW:
- File issues for remaining work - Create issues for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- Export and commit issue state -
brnever runs git commands - Clean up - Clear stashes, prune branches
- Verify - All changes committed
- Hand off - Provide context for next session
CRITICAL RULES:
- Work is NOT complete until git commit and merge into main succeeds