docs(agents): trim stale guidance and forbid unrequested edits
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.
This commit is contained in:
@@ -1,7 +1,3 @@
|
|||||||
# AGENTS.md - Instructions for AI Agents
|
|
||||||
|
|
||||||
This file provides guidance to AI agents (such as Claude, GPT, Goose, etc.) when working with this Nix overlay repository.
|
|
||||||
|
|
||||||
## Project Overview
|
## 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.
|
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.
|
||||||
@@ -12,12 +8,14 @@ This is a **Nix flake overlay** repository that provides additional packages for
|
|||||||
|
|
||||||
1. Don't assume. Don't hide confusion. Surface tradeoffs.
|
1. Don't assume. Don't hide confusion. Surface tradeoffs.
|
||||||
2. Minimum code that solves the problem. Nothing speculative.
|
2. Minimum code that solves the problem. Nothing speculative.
|
||||||
3. Touch only what you must. Clean up only your own mess.
|
3. NEVER touch AGENTS.md without user request.
|
||||||
4. Define success criteria. Loop until verified.
|
4. Touch only what you must. Clean up only your own mess.
|
||||||
|
5. Define success criteria. Loop until verified.
|
||||||
|
|
||||||
|
|
||||||
## Before Starting Any Work
|
## Before Starting Any Work
|
||||||
|
|
||||||
**MANDATORY** — Before writing code, running builds, or making any changes:
|
**MANDATORY** — Before making code changes:
|
||||||
|
|
||||||
1. **Run `br robot-docs guide`** — Get full workflow context and available commands
|
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
|
2. **Check for existing issues** — Run `br ready` to find available work
|
||||||
@@ -33,18 +31,6 @@ Always use these skills when working with this repository:
|
|||||||
- **nix-flakes** - For reproducible builds, flake management, and devShell operations
|
- **nix-flakes** - For reproducible builds, flake management, and devShell operations
|
||||||
- **karpathy-guidelines** - For high-quality task execution best practices
|
- **karpathy-guidelines** - For high-quality task execution best practices
|
||||||
|
|
||||||
### Required MCP Server
|
|
||||||
|
|
||||||
- **sequentialthinking** — MUST be used for ANY planning, problem-solving, or decision-making.
|
|
||||||
Invoke `sequentialthinking` MCP before:
|
|
||||||
- Designing implementation approaches
|
|
||||||
- Debugging non-obvious issues
|
|
||||||
- Evaluating trade-offs between approaches
|
|
||||||
- Breaking down complex tasks
|
|
||||||
- When you're uncertain about the best path forward
|
|
||||||
|
|
||||||
Do NOT skip deliberative thinking. Surface reasoning through sequentialthinking before acting.
|
|
||||||
|
|
||||||
### Blueprint Framework
|
### Blueprint Framework
|
||||||
|
|
||||||
This project uses `numtide/blueprint` which:
|
This project uses `numtide/blueprint` which:
|
||||||
@@ -53,7 +39,7 @@ This project uses `numtide/blueprint` which:
|
|||||||
- Handles formatting, checking, and devShell generation
|
- Handles formatting, checking, and devShell generation
|
||||||
- Exposes `mkPackagesFor` function to build packages against any nixpkgs instance
|
- Exposes `mkPackagesFor` function to build packages against any nixpkgs instance
|
||||||
|
|
||||||
**Important**: Blueprint's package discovery reads from the git index, not the working directory. New package directories must be staged with `git add` before they appear in flake outputs. Unstaged files are invisible to `nix build`, `nix flake show`, and `nix run`.
|
Unstaged files are invisible to `nix build`, `nix flake show`, and `nix run`.
|
||||||
|
|
||||||
### Two Overlay Strategies
|
### Two Overlay Strategies
|
||||||
|
|
||||||
@@ -87,90 +73,6 @@ nix-overlay/
|
|||||||
└── flake.lock
|
└── flake.lock
|
||||||
```
|
```
|
||||||
|
|
||||||
## Package Definition Pattern
|
|
||||||
|
|
||||||
### Standard Package Structure
|
|
||||||
|
|
||||||
Each package should follow this structure:
|
|
||||||
|
|
||||||
```
|
|
||||||
packages/<package-name>/
|
|
||||||
├── default.nix # Wrapper that receives blueprint args (pkgs, perSystem, etc.)
|
|
||||||
└── package.nix # Actual package definition using pkgs.callPackage pattern
|
|
||||||
```
|
|
||||||
|
|
||||||
### `default.nix` Pattern
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
pkgs,
|
|
||||||
perSystem,
|
|
||||||
...
|
|
||||||
}:
|
|
||||||
pkgs.callPackage ./package.nix {
|
|
||||||
# Pass any extra arguments here
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### `package.nix` Pattern
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
lib,
|
|
||||||
stdenv,
|
|
||||||
# ... package-specific dependencies
|
|
||||||
}:
|
|
||||||
|
|
||||||
stdenv.mkDerivation rec {
|
|
||||||
pname = "my-package";
|
|
||||||
version = "1.0.0";
|
|
||||||
|
|
||||||
src = fetchFromGitHub {
|
|
||||||
owner = "user";
|
|
||||||
repo = "repo";
|
|
||||||
rev = "v${version}";
|
|
||||||
hash = "sha256-...";
|
|
||||||
};
|
|
||||||
|
|
||||||
# ... build instructions
|
|
||||||
|
|
||||||
meta = with lib; {
|
|
||||||
description = "Brief description";
|
|
||||||
homepage = "https://...";
|
|
||||||
license = licenses.mit;
|
|
||||||
maintainers = with maintainers; [ ];
|
|
||||||
platforms = platforms.all;
|
|
||||||
mainProgram = "program-name";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Rust Packages
|
|
||||||
|
|
||||||
For Rust packages, use `rustPlatform.buildRustPackage`:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
lib,
|
|
||||||
rustPlatform,
|
|
||||||
fetchFromGitHub,
|
|
||||||
...
|
|
||||||
}:
|
|
||||||
|
|
||||||
rustPlatform.buildRustPackage rec {
|
|
||||||
pname = "my-rust-app";
|
|
||||||
version = "1.0.0";
|
|
||||||
|
|
||||||
src = fetchFromGitHub { ... };
|
|
||||||
|
|
||||||
cargoHash = "sha256-...";
|
|
||||||
|
|
||||||
# ... build instructions
|
|
||||||
|
|
||||||
meta = { ... };
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Adding a New Package
|
## Adding a New Package
|
||||||
|
|
||||||
When adding a new package:
|
When adding a new package:
|
||||||
@@ -302,12 +204,6 @@ After updating, always test the build:
|
|||||||
nix build .#<package-name>
|
nix build .#<package-name>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Package-Specific Notes
|
|
||||||
|
|
||||||
- **magg**: Python/hatchling package built with `python3Packages.buildPythonApplication`; tagged releases mean plain `nix-update --flake .#magg` works, but upstream also publishes alias/junk tags (`v1.3`, `latest-publish`, `root`) so verify the picked tag on bump; `checkPhase` runs pytest with `-m "not integration"` because the integration-marked tests need a live server
|
|
||||||
- **mcp-gateway**: Standard Rust package, `nix-update` handles version + cargoHash
|
|
||||||
- **skillsmcp**: Pinned to a commit hash; use `--version=branch=main` or specify the target commit with `--commit`
|
|
||||||
|
|
||||||
## Git Workflow
|
## Git Workflow
|
||||||
|
|
||||||
### Committing Completed Work
|
### Committing Completed Work
|
||||||
@@ -376,7 +272,7 @@ git commit -m "sync beads"
|
|||||||
|
|
||||||
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`.
|
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 `git add .beads/ && git commit`.
|
**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
|
### Triage labels
|
||||||
|
|
||||||
@@ -388,98 +284,18 @@ Single-context layout: `CONTEXT.md` plus `docs/adr/` at the repo root. See `docs
|
|||||||
|
|
||||||
## Session Completion
|
## Session Completion
|
||||||
|
|
||||||
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
|
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until git commit succeeds.
|
||||||
|
|
||||||
**MANDATORY WORKFLOW:**
|
**MANDATORY WORKFLOW:**
|
||||||
|
|
||||||
1. **File issues for remaining work** - Create issues for anything that needs follow-up
|
1. **File issues for remaining work** - Create issues for anything that needs follow-up
|
||||||
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
||||||
3. **Update issue status** - Close finished work, update in-progress items
|
3. **Update issue status** - Close finished work, update in-progress items
|
||||||
4. **Export and commit issue state** - `br` never runs git commands:
|
4. **Export and commit issue state** - `br` never runs git commands
|
||||||
```bash
|
5. **Clean up** - Clear stashes, prune branches
|
||||||
br sync --flush-only
|
6. **Verify** - All changes committed
|
||||||
git add .beads/
|
7. **Hand off** - Provide context for next session
|
||||||
git commit -m "sync beads"
|
|
||||||
```
|
|
||||||
5. **PUSH TO REMOTE** - This is MANDATORY:
|
|
||||||
```bash
|
|
||||||
git pull --rebase
|
|
||||||
git push
|
|
||||||
git status # MUST show "up to date with origin"
|
|
||||||
```
|
|
||||||
6. **Clean up** - Clear stashes, prune remote branches
|
|
||||||
7. **Verify** - All changes committed AND pushed
|
|
||||||
8. **Hand off** - Provide context for next session
|
|
||||||
|
|
||||||
**CRITICAL RULES:**
|
**CRITICAL RULES:**
|
||||||
- Work is NOT complete until `git push` succeeds
|
- Work is NOT complete until git commit and merge into main succeeds
|
||||||
- NEVER stop before pushing - that leaves work stranded locally
|
|
||||||
- NEVER say "ready to push when you are" - YOU must push
|
|
||||||
- If push fails, resolve and retry until it succeeds
|
|
||||||
|
|
||||||
<!-- br-agent-instructions-v1 -->
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Beads Workflow Integration
|
|
||||||
|
|
||||||
This project uses [beads_rust](https://github.com/Dicklesworthstone/beads_rust) (`br`) for issue tracking. Issues are stored in `.beads/` and tracked in git.
|
|
||||||
|
|
||||||
### Essential Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# View ready issues (open, unblocked, not deferred)
|
|
||||||
br ready # Unblocked, non-deferred work
|
|
||||||
|
|
||||||
# List and search
|
|
||||||
br list --status=open # All open issues
|
|
||||||
br show <id> # Full issue details with dependencies
|
|
||||||
br search "keyword" # Full-text search
|
|
||||||
|
|
||||||
# Create and update
|
|
||||||
br create --title="..." --description="..." --type=task --priority=2
|
|
||||||
br update <id> --status=in_progress
|
|
||||||
br close <id> --reason="Completed"
|
|
||||||
br close <id1> <id2> # Close multiple issues at once
|
|
||||||
|
|
||||||
# Sync with git
|
|
||||||
br sync --flush-only # Export DB to JSONL
|
|
||||||
br sync --status # Check sync status
|
|
||||||
```
|
|
||||||
|
|
||||||
### Workflow Pattern
|
|
||||||
|
|
||||||
1. **Start**: Run `br ready` to find actionable work
|
|
||||||
2. **Claim**: Use `br update <id> --status=in_progress`
|
|
||||||
3. **Work**: Implement the task
|
|
||||||
4. **Complete**: Use `br close <id>`
|
|
||||||
5. **Sync**: Always run `br sync --flush-only` at session end
|
|
||||||
|
|
||||||
### Key Concepts
|
|
||||||
|
|
||||||
- **Dependencies**: Issues can block other issues. `br ready` shows only open, unblocked work.
|
|
||||||
- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
|
|
||||||
- **Types**: task, bug, feature, epic, chore, docs, question
|
|
||||||
- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
|
|
||||||
|
|
||||||
### Session Protocol
|
|
||||||
|
|
||||||
**Before ending any session, run this checklist:**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git status # Check what changed
|
|
||||||
br sync --flush-only # Export beads changes to JSONL
|
|
||||||
git add <files> .beads/ # Stage code changes and exported issue state
|
|
||||||
git commit -m "..." # Commit everything
|
|
||||||
git push # Push to remote
|
|
||||||
```
|
|
||||||
|
|
||||||
### Best Practices
|
|
||||||
|
|
||||||
- Check `br ready` at session start to find available work
|
|
||||||
- Update status as you work (in_progress → closed)
|
|
||||||
- Create new issues with `br create` when you discover tasks
|
|
||||||
- Use descriptive titles and set appropriate priority/type
|
|
||||||
- Always sync before ending session
|
|
||||||
|
|
||||||
<!-- end-br-agent-instructions -->
|
|
||||||
|
|||||||
Reference in New Issue
Block a user