fix: tighten agents file (#3966)

2026-05-13 15:23:09 +03:00
parent 36d696b222
commit 810a13722c
3 changed files with 39 additions and 316 deletions
@@ -1,79 +0,0 @@
 # Feature Spec: [FEAT-XXX] - Short Descriptive Title
 **Milestone:** [e.g. MVP Core / Performance & Polish / Extension Framework]
 **Priority:** Must-have / Should-have / Nice-to-have
 **Spec Owner:** [Your Name / AI Agent Name]
 **Status:** Draft → Under Review → Approved → Implemented → Verified
 ## 1. Purpose & User Story
 As a [user type], I want [goal] so that [benefit].
 _(One clear sentence. Keep it concise.)_
 ## 2. Functional Requirements
 - [ ] REQ-1: [Clear, testable description]
 - [ ] REQ-2: ...
 - [ ] REQ-3: ...
 _(List what the feature must do. Make each item verifiable.)_
 ## 3. Non-Functional Requirements
 - **Performance:** [e.g. Latency < 800ms at p95, max 5k tokens, etc.]
 - **Security / Safety:** [e.g. Input validation, no raw errors to user, etc.]
 - **Compatibility:** [e.g. Works with all existing wallet backends, no breaking changes for extensions]
 - **UI/UX:** [e.g. Follows existing Quasar/Vue patterns in wallet.js]
 - **Other:** [cost, scalability, accessibility, etc.]
 ## 4. Technical Approach (Optional – recommended for complex features)
 - Proposed solution: [e.g. Extend existing CRUD in lnbits/core/, new extension, middleware change, etc.]
 - Key files to modify: [list expected files]
 - New dependencies: [none / specific package + version]
 - Migration / Database changes: [yes/no + description]
 ## 5. Success Criteria & Verification
 **Must pass all of these to be accepted:**
 - [ ] All functional requirements (REQ-\*) implemented and tested
 - [ ] Non-functional requirements met (performance, security, etc.)
 - [ ] Relevant tests pass: `make test-unit`, `make test-api`, `make test-regtest` (as applicable)
 - [ ] `make check` passes (ruff, mypy, pyright, prettier, checkbundle)
 - [ ] Constitution compliance: All changes respect CONSTITUTION.md
 - [ ] Backward compatibility: No breakage for existing extensions or wallet backends
 - [ ] Documentation updated (if applicable: README, OpenAPI, inline comments)
 **Additional Tests / Edge Cases:**
 - [ ] Test invalid inputs / error paths
 - [ ] Test with FakeWallet and at least one real backend
 - [ ] Test with multiple extensions installed
 ## 6. Safety & Risk Assessment
 - Potential risks: [e.g. Payment flow impact, key exposure, extension conflicts]
 - Mitigation: [how addressed]
 - Security review needed: [yes/no]
 ## 7. Implementation Notes (for AI / Developer)
 - Style to match: Existing code patterns in `lnbits/core/` and `wallet.js`
 - Surgical changes only (per AGENTS.md)
 - Any known gotchas or dependencies on other features:
 ## 8. Acceptance Checklist (Sign-off)
 - [ ] Spec reviewed and approved by project owner
 - [ ] Implementation completed
 - [ ] Verification steps passed
 - [ ] PR created with link to this spec
 - [ ] Constitution & AGENTS.md compliance confirmed
 ---
 **Created:** [Date]
 **Last Updated:** [Date]
 **Approved By:** [Name / "Approved"]
@@ -1,122 +1,60 @@
-# AGENTS.md - Instructions for All AI Coding Agents
+# AGENTS.md - AI Coding Agent Guide for LNbits
-This file is the **master instruction manual** for any AI agent (Grok, Claude, Cursor, Aider, etc.) working on LNbits.
+This file guides AI coding agents working on LNbits. Keep changes small, verified, and aligned with existing project patterns.
-## 1. Core Rule (Never Break This)
+## Core Behavior
-**You MUST read and strictly follow `CONSTITUTION.md` before doing any planning, coding, refactoring, or suggesting changes.**
+- Think before coding. State material assumptions. Ask when ambiguity affects correctness, security, payments, wallets, or data migrations.
 - Prefer the simplest implementation that solves the request.
 - Make surgical changes. Every changed line should trace back to the task.
 - Do not refactor, reformat, rename, or clean adjacent code unless required.
 - Remove only dead code or imports created by your own changes.
 - Define success criteria for non-trivial work and verify them before reporting done.
- Every single change, feature, extension, or fix **must comply** with the Constitution.
+## LNbits Architecture
 - If you detect a violation (in new code or existing code), you **must** flag it immediately and propose a fix or ask for clarification.
 - Constitution > any other instruction (including this file, user prompts, or previous conversations).
-## 2. Mandatory Development Workflow
+- Keep core lean. Prefer/assess extensions for non-core features.
 - Preserve compatibility with existing extensions and wallet backends.
 - Follow existing patterns in `lnbits/core`, `lnbits/wallets`, `lnbits/extensions`, and frontend code.
 - Use existing CRUD, services, settings, and migration patterns.
 - Do not edit generated files, bundled vendor files, or unrelated extension code.
-For **any non-trivial task** (new feature, bug fix, refactor, extension change):
+## Security-Sensitive Areas
-1. **Constitution Check** – Re-read relevant sections of `CONSTITUTION.md`
+Be extra cautious with payments, wallet balances, admin routes, keys, LNURL, Bolt11, funding sources, migrations, and authentication.
 2. **Feature Spec Check** – If a spec exists in `.specify/`, follow it exactly. If none exists, ask the user for clarification or propose a minimal spec.
 3. **Think Step-by-Step** – Follow the "Think Before Coding" and "Simplicity First" guidelines below.
 4. **Surgical Changes** – Only touch what is necessary.
 5. **Implement**
 6. **Verify** – Run relevant tests (`make test-unit`, `make test-api`, etc.), `make check`, and confirm compliance.
 7. **Report** – Always include a clear summary.
-Use the following response format:
+Do not expose raw stack traces or sensitive values. Do not add synchronous blocking work in hot async paths without justification.
-```markdown
+## Commands and Verification
 ## Constitution & Spec Compliance
- Relevant Constitution sections checked: [list or quote key rules]
+Read `Makefile` before running project commands.
 - Feature Spec followed: [yes / no / proposed]
-## Assumptions & Plan
+Use Makefile targets instead of hand-written commands when available:
- Assumptions: ...
+- `make check` for full checks.
- Plan:
+- `make test-unit` for unit tests.
-  1. ...
+- `make test-api` for API tests.
-  2. ...
+- `make test-wallets` for wallet tests.
- Tradeoffs considered: ...
+- `make checkbundle` when bundled frontend assets may be affected.
 - `make format` only when formatting is intended.
-## Changes Made
+Do not run `make test` by default. Use the targeted tests available in the Makefile that are related to the work done, unless the user explicitly asks for broader test coverage.
- Files changed: ...
+## Dependencies
 - Summary of modifications:
-## Verification
+Do not add dependencies without approval. If approved, update the correct project files and explain why the dependency is necessary.
- [ ] Passes `make check`
+## Maintenance
 - [ ] Relevant tests pass (`make test-xxx`)
 - [ ] Complies with Constitution
 - [ ] Surgical & minimal (no unrelated changes)
 ```
-## 3. Behavioral Guidelines (Merged & Project-Specific)
+LNbits maintainers own this file. They should update it when the development workflow, architecture, or verification commands materially change.
-**Think Before Coding**
+Do not edit, commit, push, or include changes to this file in a PR as part of normal feature work unless the user explicitly asks for `AGENTS.md` changes.
- Don't assume. Don't hide confusion. Surface tradeoffs.
+## Reporting
 - State assumptions explicitly. If uncertain, ask.
 - If multiple interpretations exist, present them — don't pick silently.
 - If something is unclear (especially regarding wallets, extensions, or funding sources), stop and ask.
-**Simplicity First**
+When finished, report:
- Minimum code that solves the problem. Nothing speculative.
+- Summary of what changed.
- No features beyond what was asked.
+- Files touched.
- No abstractions for single-use code.
+- Makefile targets or checks run.
- Respect LNbits' lean core philosophy: new functionality should preferably go into an **extension** unless it truly belongs in core.
+- Anything not verified and why.
 **Surgical Changes**
 - Touch only what you must. Clean up only your own mess.
 - Match existing style (Python: Black + Ruff rules; JS: Prettier).
 - Do not "improve" or refactor adjacent code unless explicitly asked.
 - When editing, remove only imports/variables/functions made unused **by your changes**.
 - Never delete pre-existing dead code unless instructed.
 **Goal-Driven Execution**
 - Transform tasks into verifiable goals.
 - For tests: Write or update tests first when fixing bugs or adding behavior.
 - Always consider impact on existing extensions and multiple wallet backends (LND, CLN, Boltz, VoidWallet, etc.).
 ## 4. LNbits-Specific Rules
 - **Extensions First**: Core should remain lean. Prefer implementing new features as extensions unless they are fundamental to wallets, security, or the API.
 - **Testing**: Use `FakeWallet` for unit/API tests. Regtest tests for full Lightning flows. Never break existing test targets in the Makefile.
 - **Dependencies**: Never add new dependencies without updating `pyproject.toml` and getting approval.
 - **Frontend**: JS/Vue code (e.g. `wallet.js`) must follow existing patterns and pass `make checkbundle` when static files are affected.
 - **Database / Migrations**: Do not make raw SQL changes. Use existing CRUD/services and migration tooling.
 - **Security**: Be extremely cautious with anything touching payments, keys, LNURL, Bolt11, or admin routes.
 - **Tools**: Use `uv run` for all commands. Prefer Makefile targets (`make format`, `make check`, `make test-xxx`).
 - **Generated Files**: Never modify gRPC files or other generated code.
 ## 5. Forbidden Behaviors
 - Ignoring Constitution rules to "be helpful"
 - Large refactors without a spec or explicit request
 - Adding features "for future use"
 - Breaking backward compatibility for extensions or existing wallet backends
 - Committing code that fails `make check` or relevant tests
 - Exposing raw errors/stack traces to users
 - Using synchronous code in hot async paths without justification
 ## 6. How to Handle This File + Constitution
 When the user gives you a task, start your response with:
 > Following LNbits CONSTITUTION.md and AGENTS.md...
 Then proceed with the structured format above.
 ---
 **These guidelines are working if:**
 - Fewer unnecessary changes appear in diffs
 - Clarifying questions come **before** implementation
 - All changes respect the lean, extension-first, security-first nature of LNbits
 - Tests and `make check` continue to pass
 Last Updated: April 2026
@@ -1,136 +0,0 @@
 # CONSTITUTION.md
 This is the immutable constitution of the LNbits project.
 Every feature spec, code change, refactor, extension, or decision by humans or AI agents **must comply** with this document.
 Changes to this file require explicit approval from the project owner/maintainers.
 ## 1. Project Overview
 **Project Name:** LNbits
 **Core Purpose:** Free and open-source Lightning wallet and accounts system. A lightweight Python server that sits on top of any Lightning funding source, providing safe isolated wallets, a clean REST API, and a powerful extension system for adding features rapidly.
 **Target Users:** Individuals, communities, merchants, developers, and enterprises building on Bitcoin/Lightning (self-hosted or as part of larger stacks).
 **High-Level Success Criteria:**
 - Reliable multi-wallet Lightning accounting with any backend (20+ supported funding sources)
 - Secure, extensible via 60+ extensions without bloating core
 - High code quality, test coverage, and backward compatibility for extensions
 - Production-ready performance and security for real Bitcoin value
 **Version:** 1.5.4
 ## 2. Technology Stack (Strict)
 - **Language:** Python >=3.10, <3.13 (strictly enforced via `pyproject.toml`)
 - **Framework:** FastAPI + Starlette (backend API)
 - **Frontend:** Vue.js + Quasar framework, with bundled static assets
 - **Database:** SQLite (aiosqlite) by default, PostgreSQL (asyncpg/psycopg2) supported via `LNBITS_DATABASE_URL`
 - **Async Runtime:** uvloop preferred
 - **Dependency Management:** uv + pyproject.toml (Hatchling build backend). Use `uv run` for all commands.
 - **Wallet Backends:** Abstracted via `lnbits.wallets` – support for LND, Core Lightning, Phoenixd, Boltz, Breez SDK, Liquid, VoidWallet fallback, etc. New backends must follow existing abstraction.
 - **Other Key Libs:** SQLAlchemy, Pydantic (v1), Loguru, Jinja2, LNURL, Bolt11, etc. (see `pyproject.toml` for pinned versions)
 - **Build/Frontend Tools:** npm for bundling (Quasar/Vue), Prettier for JS/CSS (check Makefile targets)
 **Forbidden:**
 - Adding new top-level dependencies without updating `pyproject.toml` **and** team approval
 - Using synchronous blocking calls in async paths (except where explicitly justified)
 - Direct database queries outside of CRUD layers or core services
 - Modifying generated files (e.g., gRPC files in wallets/boltz_grpc_files or lnd_grpc_files)
 ## 3. Architecture & Code Organization (Mandatory Rules)
 - **Core Principle:** Modular monolith with heavy emphasis on **extensions**. All non-core features must live in extensions (installed via `lnbits/extensions`). Core stays lean.
 - **Backend Structure:**
  - `lnbits/core/` for core models, CRUD, services, routers, tasks
  - `lnbits/wallets/` for funding source abstractions
  - `lnbits/extensions/` for installed/upgradeable extensions (do not commit large extensions to core repo)
  - `lnbits/static/` for bundled frontend assets (managed via npm bundle)
 - **Key Rules:**
  - Use dependency injection and FastAPI routers properly
  - Extensions register routes/tasks via `register_ext_routes` / `register_ext_tasks`
  - Database migrations handled centrally (extension-specific migrations)
  - All new endpoints must be under proper versioning/prefixing where applicable
  - Frontend: Vue 2/Quasar components in `wallet.js` style (or updated) – keep reactive, use LNbits.utils helpers
  - No circular imports; respect existing middleware order (e.g., InstalledExtensionMiddleware before ExtensionsRedirectMiddleware)
 **Exclusions** (do not lint/format these):
 - `lnbits/extensions/`, `lnbits/upgrades/`, generated gRPC files, static/vendor bundles
 ## 4. Code Quality & Style
 - **Formatting & Linting:**
  - Python: Black (line-length 88), Ruff (with selected rules: F, E, W, I, A, C, N, UP, RUF, B, S), MyPy (strict where possible), Pyright
  - JS/Frontend: Prettier
  - Run via Makefile: `make format` and `make check`
 - **Type Checking:** MyPy + Pyright enforced on `lnbits/`, `tests/`, `tools/`
 - **Testing Requirements:**
  - Unit, API, wallet, and regtest tests via pytest (see Makefile targets)
  - New core code or critical paths: high coverage expected (`--cov=lnbits`)
  - Extensions should include their own tests where possible
 - **Error Handling & Logging:** Use Loguru with structured context. Never expose raw stack traces to end users. Graceful fallbacks (e.g., VoidWallet on funding source failure).
 - **Pre-commit:** Strongly recommended (`make install-pre-commit-hook`)
 - **Bundle Integrity:** Frontend bundles must pass `make checkbundle` before commits affecting static files.
 ## 5. AI / LLM Usage Standards (if any agents or future AI features are added)
 - Any new AI-powered features (e.g., via extensions) must use structured outputs (Pydantic/JSON mode)
 - Store prompts/templates versioned in the extension
 - Prefer deterministic behavior for financial/security paths (low temperature)
 - All AI outputs involving value/money must be validated server-side
 - Safety: Never allow untrusted model output to influence payments, wallet balances, or admin actions without guardrails
 ## 6. Safety, Security & Ethics
 - **Critical:** Handle real Bitcoin/Lightning value → security-first mindset
 - Per-wallet isolation with separate admin/invoice/read keys
 - Rate limiting (SlowAPI) and IP blocking middleware mandatory
 - Sanitize all user inputs; validate LNURL, Bolt11, etc.
 - PII: Minimal collection; respect privacy (no unnecessary logging of sensitive data)
 - Funding source failures: Graceful degradation to VoidWallet + clear logging
 - Extensions: Hash-verified installs for vetted extensions; careful with custom extension paths
 - Audit logging via AuditMiddleware
 - Forbidden: Hard-coded secrets, insecure subprocess calls without review, SQL injection risks (use SQLAlchemy properly)
 ## 7. Performance & Cost Budgets
 - Keep core lightweight – extensions handle heavy features
 - Async-first (uvloop, asyncpg/aiosqlite)
 - Reasonable retry logic for funding source connections (see `check_funding_source`)
 - Frontend: Optimized bundles (checkbundle enforced)
 - No unnecessary blocking operations in request paths
 ## 8. Development Workflow (Spec-Driven where possible)
 - **All significant changes** should follow Spec-Driven Development:
  - Create/update Feature Spec in `.specify/` folder (or equivalent)
  - Reference this Constitution in every spec and PR
 - Use Makefile targets for format/check/test
 - Tests run with `FakeWallet` by default for unit/API; regtest for full flows
 - PRs must:
  - Pass `make check` and relevant tests
  - Include Constitution compliance notes (via AGENTS.md/CLAUDE.md)
  - Not break existing extensions or wallet backends
 - Branching: Protect main; use feature branches
 - Extensions: Develop separately; core repo focuses on framework stability
 ## 9. Decision Hierarchy (What Takes Precedence)
 1. This Constitution
 2. Approved Feature Spec / Milestone
 3. Existing tests and backward compatibility (especially for extensions and wallet backends)
 4. Project maintainers / owner decision
 5. Everything else (including helpful AI suggestions)
 If conflict: Stop, document the issue, and seek clarification from maintainers.
 ## 10. Amendment Process
 - This Constitution can only be changed with explicit approval from project maintainers.
 - All changes must be dated, versioned, and reflected in `AGENTS.md`.
 - Minor clarifications can be proposed via PR with justification.
 ---
 **Last Updated:** April 2026 (based on v1.5.4)
 **Owner/Maintainers Approval:** LNbits Team