From 48a7d227f2dff702c8976f12554075cd1039ba24 Mon Sep 17 00:00:00 2001 From: Alexander Miroshnichenko Date: Thu, 12 Nov 2026 11:55:16 +0300 Subject: [PATCH] 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. --- AGENTS.md | 210 ++++-------------------------------------------------- 1 file changed, 13 insertions(+), 197 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 296aae3..889ff98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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// -├── 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-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 - - ---- - -## 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 # Full issue details with dependencies -br search "keyword" # Full-text search - -# Create and update -br create --title="..." --description="..." --type=task --priority=2 -br update --status=in_progress -br close --reason="Completed" -br close # 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 --status=in_progress` -3. **Work**: Implement the task -4. **Complete**: Use `br close ` -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 ` 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 .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 - -