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
|
||||
|
||||
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.
|
||||
2. Minimum code that solves the problem. Nothing speculative.
|
||||
3. Touch only what you must. Clean up only your own mess.
|
||||
4. Define success criteria. Loop until verified.
|
||||
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 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
|
||||
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
|
||||
- **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
|
||||
|
||||
This project uses `numtide/blueprint` which:
|
||||
@@ -53,7 +39,7 @@ This project uses `numtide/blueprint` which:
|
||||
- Handles formatting, checking, and devShell generation
|
||||
- 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
|
||||
|
||||
@@ -87,90 +73,6 @@ nix-overlay/
|
||||
└── 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
|
||||
|
||||
When adding a new package:
|
||||
@@ -302,12 +204,6 @@ After updating, always test the build:
|
||||
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
|
||||
|
||||
### 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`.
|
||||
|
||||
**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
|
||||
|
||||
@@ -388,98 +284,18 @@ Single-context layout: `CONTEXT.md` plus `docs/adr/` at the repo root. See `docs
|
||||
|
||||
## 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:**
|
||||
|
||||
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:
|
||||
```bash
|
||||
br sync --flush-only
|
||||
git add .beads/
|
||||
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
|
||||
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 push` 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
|
||||
- Work is NOT complete until git commit and merge into main 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