48a7d227f2
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.
302 lines
10 KiB
Markdown
302 lines
10 KiB
Markdown
## Project Overview
|
|
|
|
This is a **Nix flake overlay** repository that provides additional packages for Nix/NixOS users. It uses [numtide/blueprint](https://github.com/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
|
|
|
|
1. Don't assume. Don't hide confusion. Surface tradeoffs.
|
|
2. Minimum code that solves the problem. Nothing speculative.
|
|
3. NEVER touch AGENTS.md without user request.
|
|
4. Touch only what you must. Clean up only your own mess.
|
|
5. Define success criteria. Loop until verified.
|
|
|
|
|
|
## Before Starting Any Work
|
|
|
|
**MANDATORY** — Before making code changes:
|
|
|
|
1. **Run `br robot-docs guide`** — Get full workflow context and available commands
|
|
2. **Check for existing issues** — Run `br ready` to find available work
|
|
3. **Claim the task** — Use `br update <id> --claim` before starting
|
|
4. **Track via `br` ONLY** — NEVER use TodoWrite, TaskCreate, or markdown TODO lists. All task tracking goes through `br`.
|
|
|
|
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 `perSystem` outputs for multi-system builds
|
|
- Handles formatting, checking, and devShell generation
|
|
- Exposes `mkPackagesFor` function to build packages against any nixpkgs instance
|
|
|
|
Unstaged files are invisible to `nix build`, `nix flake show`, and `nix run`.
|
|
|
|
### Two Overlay Strategies
|
|
|
|
1. **`overlays.default`** - Binary-cache-friendly
|
|
- Uses packages built against this flake's nixpkgs revision
|
|
- Better for binary cache hits when using the same nixpkgs
|
|
|
|
2. **`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
|
|
|
|
## 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:
|
|
|
|
1. **Create the directory**: `mkdir -p packages/<package-name>`
|
|
|
|
2. **Create `package.nix`** with the actual derivation
|
|
|
|
3. **Create `default.nix`** as a wrapper:
|
|
```nix
|
|
{ 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.
|
|
|
|
4. **Test the package**:
|
|
```bash
|
|
nix build .#<package-name>
|
|
nix run .#<package-name>
|
|
```
|
|
|
|
5. **Update README.md** to document the new package in the Available Packages table
|
|
|
|
6. **Set appropriate metadata**:
|
|
- `meta.description` - Required, shown in package listings
|
|
- `meta.mainProgram` - Set for packages providing a CLI executable
|
|
- `meta.passthru.category` - Optional, used for organization (e.g., "AI Coding Agents")
|
|
- `meta.passthru.hideFromDocs` - Set to `true` to exclude from documentation
|
|
|
|
## Common Tasks
|
|
|
|
### Updating a Package Version
|
|
|
|
1. Update `version` in `package.nix`
|
|
2. Update `src.hash` (use `nix-prefetch-github` or let Nix tell you the correct hash)
|
|
3. Update `cargoHash` for Rust packages (build will fail and tell you the correct hash)
|
|
4. Test: `nix build .#<package-name>`
|
|
5. Update README if needed
|
|
|
|
### Testing Changes
|
|
|
|
```bash
|
|
# 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`**: Receives `packages` from blueprint outputs, maps them to `final.stdenv.hostPlatform.system`
|
|
- **`overlays/shared-nixpkgs.nix`**: Receives `mkPackagesFor`, uses it to build against consumer's `final`
|
|
|
|
## Important Notes
|
|
|
|
### Do's
|
|
|
|
- ✅ Use `pkgs.callPackage` pattern for package definitions
|
|
- ✅ Set proper `meta` attributes (description, license, homepage)
|
|
- ✅ Test packages with `nix build` before committing
|
|
- ✅ Use `passthru.category` for organizational grouping
|
|
- ✅ Follow Nixpkgs conventions for package naming and structure
|
|
|
|
### Don'ts
|
|
|
|
- ❌ Don't modify `flake.lock` manually - use `nix flake update`
|
|
- ❌ Don't hardcode system-specific paths or assumptions
|
|
- ❌ Don't forget to set `meta.mainProgram` for 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
|
|
|
|
1. Check the error message carefully
|
|
2. Verify all dependencies are listed
|
|
3. Check if the source hash is correct
|
|
4. For Rust packages, verify `cargoHash` matches
|
|
|
|
### Overlay Not Working
|
|
|
|
1. Verify the overlay is correctly imported
|
|
2. Check if the package exists in `packages` output
|
|
3. For `shared-nixpkgs`, ensure `mkPackagesFor` is available
|
|
|
|
### Binary Cache Issues
|
|
|
|
- The `default` overlay is more likely to get cache hits
|
|
- The `shared-nixpkgs` overlay builds from source unless nixpkgs revisions match
|
|
|
|
## Resources
|
|
|
|
- [Nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/)
|
|
- [Blueprint Documentation](https://github.com/numtide/blueprint)
|
|
- [Nix Flake Patterns](https://github.com/NixOS/flake-patterns)
|
|
- [Rust in Nixpkgs](https://nixos.org/manual/nixpkgs/stable/#rust)
|
|
|
|
## Updating Packages
|
|
|
|
Use [nix-update](https://github.com/Mic92/nix-update) to bump versions and update hashes:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
1. **File issues for remaining work** - Create issues for anything that needs follow-up
|
|
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
|
3. **Update issue status** - Close finished work, update in-progress items
|
|
4. **Export and commit issue state** - `br` never runs git commands
|
|
5. **Clean up** - Clear stashes, prune branches
|
|
6. **Verify** - All changes committed
|
|
7. **Hand off** - Provide context for next session
|
|
|
|
**CRITICAL RULES:**
|
|
- Work is NOT complete until git commit and merge into main succeeds
|
|
|