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:
2026-11-12 11:55:16 +03:00
parent 78c46e970c
commit 48a7d227f2
+13 -197
View File
@@ -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 -->