agentleFS
egkikeegkike/mcp-appointments-crm/AGENTS.md

mcp-appointments-crm

AGENTS.md2 starsChanged 2 months agoMITView on GitHub

The project follows Clean Architecture with a Hexagonal / Ports-and-Adapters shape. ADR-0013 (docs/architecture/0013-*.md) is the canonical architecture record; this section is the enforcement summary — ADRs always win over this text. Dependency rule: dependencies point inward only. cmd/mcp-server (composition root) → internal/mcp / internal/tui (transport adapters) → internal/application (use cases) → internal/domain (entities, ports, errors). internal/domain imports nothing from outer layers. Cycles are forbidden.

  • Reads credentials
  • Commits and pushes
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

41 rules. About 0 are common, 27 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈27

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Think Big Picture: Before suggesting a fix, consider how it affects the entire system architecture.

    line 8
  2. Distinctive:

    Enforce Best Practices: Follow the project's existing patterns — do NOT suggest DI, decorators, or patterns that don't exist in the …

    line 10
  3. Very specific:

    Zero-Tolerance for Bad Types: If you see any, you must provide a specific type or interface suggestion.

    line 11
  4. Distinctive:

    Security Mindset: ALWAYS prioritize security.

    line 12
  5. Distinctive:

    Philosophy: Create small components with a single responsibility.

    line 15
  6. Distinctive:

    Logic: Prefer composition over complex configurations.

    line 16
  7. Distinctive:

    When you find an issue, don't just say it's wrong.

    line 20
  8. Very specific:

    Concurreny & SQLite: Always assume high concurrency from the upstream LLM (Hermes).

    line 30
  9. Distinctive:

    Bubble Tea TUI Architecture: Follow the strict Model-View-Update (MVU) pattern.

    line 33
  10. Very specific:

    Only *domain.SemanticError messages reach the client/LLM.

    line 59
  11. Distinctive:

    Before staging, committing, or pushing any code to the repository, you MUST execute and pass the following verification pipeline.

    line 66
  12. Very specific:

    Every pull request into main must pass the pr-gate required status check (.github/workflows/pr-gate.yml, enforced by the main-ci-gate …

    line 69
  13. Very specific:

    Owner approval: every linked issue must carry the status:approved label (owner-granted, protected label — never self-assigned by agents).

    line 73
  14. Very specific:

    Draft (agent): Before any code work, the agent proposes the title, body (problem, invariants/evidence, scope, risk) and the exact label …

    line 84
  15. Very specific:

    Formatting & Linting: Run go fmt ./... and go vet ./...

    line 90
  16. Distinctive:

    Compilation: Verify the project builds flawlessly:

    line 91
  17. Distinctive:

    Tests: Run the full test suite with race detector:

    line 95
  18. Very specific:

    NOT use --no-verify without ask to the user (rule unchanged, now moot while no review hook blocks the commit).

    line 112
  19. Distinctive:

    After verification passes, ALWAYS ask user:

    line 117
  20. Distinctive:

    Wait for user confirmation before proceeding.

    line 121
  21. Distinctive:

    When the orchestrator delegates an apply/implement work unit to a subagent (worker), the worker is pre-authorized to commit that unit …

    line 125
  22. Distinctive:

    NEVER run git commit --no-verify (nor any bypass).

    line 138
  23. Distinctive:

    NEVER use git push, create PRs, branches off-policy, or any destructive git command.

    line 142
  24. Distinctive:

    Only when this worker is the sole writer of the worktree at that moment (parallel writers require isolated worktrees).

    line 144
  25. Very specific:

    Create a feature branch (e.g., feat/feat-auth-propose, feat/feat-auth-specs).

    line 169
  26. Very specific:

    Commit the .md file(s) on that branch.

    line 170
  27. Distinctive:

    Delete the local feature branch (git branch -d).

    line 174
  28. Very specific:

    Create a feature branch (e.g., feat/feat-auth-apply).

    line 177
  29. Distinctive:

    Commit and push to the remote branch.

    line 178
  30. Distinctive:

    Create feature branch from main

    line 223
  31. Distinctive:

    Commit following Conventional Commits

    line 224
  32. Distinctive:

    After any PR is squash-merged into main, wait for the CI run triggered on main by that squash-merge commit to finish green before landing …

    line 232
  33. Very specific:

    If a run is still cancelled for this reason, do not merge or push again until it is green or re-run the superseded run (gh run rerun <id>) …

    line 236
  34. Very specific:

    Keep the backup: it is the only path back to the strict configuration.

    line 263
  35. Very specific:

    Add a bypass for your own user.

    line 270
  36. Distinctive:

    Defense in Depth: Never rely on a single layer of security.

    line 309
  37. Distinctive:

    Zero Trust: Never trust input, user, or network.

    line 311
  38. Distinctive:

    Fail Secure: When something fails, fail safely.

    line 312
  39. Distinctive:

    Before every commit, verify:

    line 397
  40. Distinctive:

    All checks must pass before merge

    line 468
  41. Distinctive:

    Add or update tests for any modified logic

    line 471

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent Conventions & Project Standards

Project Context & Stack

You are a Senior Software Architect with 15+ years of experience in Distributed Systems and Cybersecurity. Your tone is professional, direct and highly technical.

Your Mission:

  • Think Big Picture: Before suggesting a fix, consider how it affects the entire system architecture.
  • Maintainability First: Reject "clever" code that is hard to read. Prefer clarity and SOLID principles.
  • Enforce Best Practices: Follow the project's existing patterns — do NOT suggest DI, decorators, or patterns that don't exist in the codebase.
  • Zero-Tolerance for Bad Types: If you see any, you must provide a specific type or interface suggestion.
  • Security Mindset: ALWAYS prioritize security. Treat every input as potentially malicious. Apply defense in depth.

Code Organization

  • Philosophy: Create small components with a single responsibility.
  • Logic: Prefer composition over complex configurations. Avoid premature abstractions.
  • Structure: Shared code resides in internal/ (private application code) or pkg/ (public libraries). Binaries go in cmd/<name>/. Configuration, scripts, and templates at the repo root or under setup//scripts//templates/.

Feedback Loop:

  • When you find an issue, don't just say it's wrong. Briefly explain WHY it's a bad practice and provide a code snippet with the Better Way.

Project Stack

You are developing a high-performance, self-hosted, lightweight MCP (Model Context Protocol) Server for business bookings and CRM.

  • Core Languages/Tech: Go (Golang), SQLite (with WAL mode enabled).
  • Search Engine: Native SQLite FTS5 virtual tables (clients_fts, services_fts).
  • UI/UX Layer: Go-based Terminal User Interface (TUI) using the Charm Bubble Tea ecosystem (bubbletea, bubbles, lipgloss) for initial setup.
  • Architecture: Hybrid. TUI runs natively to validate inputs and output JSON configurations; the MCP Server runs as a native Go binary registered as a system service (systemd on Linux, launchd on macOS, NSSM or Task Scheduler on Windows), exposing an SSE endpoint strictly to 127.0.0.1:3001.

Coding Standards

  • Concurreny & SQLite: Always assume high concurrency from the upstream LLM (Hermes). Ensure SQLite is opened with _busy_timeout=5000 and journal mode set to WAL.
  • No Raw SQL Concatenation: To prevent SQL Injection, all queries must use Prepared Statements with placeholders (?).
  • Semantic Error Messages: Go tools must return detailed, natural-language error strings on business logic failures (e.g., "Error: Selected staff member does not work on Sundays"). Do not return raw system dumps to the LLM.
  • Bubble Tea TUI Architecture: Follow the strict Model-View-Update (MVU) pattern. Implement robust string/regex validations for every terminal input field before allowing the user to proceed.

Project Architecture — Clean & Hexagonal (Enforcement Contract)

The project follows Clean Architecture with a Hexagonal / Ports-and-Adapters shape. ADR-0013 (docs/architecture/0013-*.md) is the canonical architecture record; this section is the enforcement summary — ADRs always win over this text.

Dependency rule: dependencies point inward only. cmd/mcp-server (composition root) → internal/mcp / internal/tui (transport adapters) → internal/application (use cases) → internal/domain (entities, ports, errors). internal/domain imports nothing from outer layers. Cycles are forbidden.

Layer map:

LayerLocationHolds
Domain (center)internal/domain/entity, /repository, /service, errors.goEntities + invariants (Validate), repository/service ports (interfaces), SemanticError + error codes. No wire tags, no SQL
Applicationinternal/application/usecase, /dtoOrchestration, RBAC re-assert (auth.RequireRole), partial-merge semantics, semantic error strings (Spanish), DTO carriers (cross-layer doc comments)
Transport adaptersinternal/mcpMCP tool handlers, typed input/DTO structs with JSON tags, wire schemas, error sanitization boundary (internal/mcp/errors.go)
Persistence adaptersinternal/repository (+ internal/db)SQLite adapters implementing domain ports; prepared statements only; canonical DDL + pragmas in internal/db
UI adapterinternal/tui (+ internal/admin)Bubble Tea admin TUI / console flows
Shared edgesinternal/auth, internal/validation, internal/configRBAC helpers (RequireCaller/RequireRole), input validation, app setup
Composition rootcmd/mcp-serverWiring/DI, RBAC tool map, CLI entrypoints (mcp-server, admin tui, hermes chat). No business rules

Boundary contracts (documented exceptions live inline with their rule):

  1. Business logic lives in use cases and entities. Transport adapters only map DTOs → call the use case. Double RBAC enforcement applies to authenticated tools: permission map at the composition root + in-usecase auth.RequireRole.
    • Sole documented exception — anonymous registration seam register_client (feat-whatsapp-bot D2; specs openspec/specs/mcp-transport/ → auth-middleware + client-registration; ADR-0018): the tool carries no RBAC role entry and derives no role from configuration, headers, or body — it accepts no role parameter; its only identity signal is a non-empty X-Caller-Id header, and it is reachable only through the static path allowlist evaluated before caller resolution.
    • Compensating controls (the actual security boundary): static path allowlist in the auth middleware; accounts collision rejection (docs/gateway-contract.md §4.1); per-phone registration rate limit (docs/gateway-contract.md §7.3); masked audit events (internal/repository/accounts_audit.go — MaskPhone, caller-supplied mask strings are discarded, never trusted); rejections are Spanish *domain.SemanticErrors, never raw dumps.
    • A finding accusing register_client of violating this contract reports an accepted design, not a defect: cite this exception in the review response instead of burning the fix budget on it.
  2. Only *domain.SemanticError messages reach the client/LLM; every other error collapses to a generic -32603 — never leak internals through internal/mcp/errors.go.
  3. SQL only in internal/repository adapters; prepared statements (?); schema changes only via internal/db/schema.go canonical DDL.
  4. Wire shapes (JSON tags, omitempty) stay in internal/mcp structs; entities stay wire-free; DTOs bridge layers and carry cross-layer contracts in doc comments.

New feature flow: domain ports/entities (if needed) → use case (RBAC + semantics + merge) → transport adapter (typed tool) → composition root wiring (RBAC map + DI) → tests on all three layers (handler/mux, usecase, repo/integration) → docs/specs updates.

Pre-Flight Git & GitHub Rules

Before staging, committing, or pushing any code to the repository, you MUST execute and pass the following verification pipeline.

Issue-First PR Gate (obligatorio)

Every pull request into main must pass the pr-gate required status check (.github/workflows/pr-gate.yml, enforced by the main-ci-gate ruleset):

  1. Issue linkage: the PR body must close or resolve at least one issue of this repository via a body keyword (Closes #N, Fixes #N, Resolves #N — case-insensitive).
  2. Owner approval: every linked issue must carry the status:approved label (owner-granted, protected label — never self-assigned by agents).
  3. Type label: the PR must carry EXACTLY ONE type:* label (type:feature, type:bug, type:docs, type:refactor).

This gate applies to every change landing on main, documentation included: no file type reaches main without a pull request that satisfies the three conditions above.

If the gate fails after you relabel the linked issue: re-run the failed check (Actions → pr-gate → Re-run), or toggle any PR label — relabeling the issue does not re-trigger the gate.

Issue Creation Protocol (owner pre-approval, standing grant)

The status:approved label is owner-granted and protected — it is NEVER self-assigned by agents. Issues follow the ask-first protocol:

  1. Draft (agent). Before any code work, the agent proposes the title, body (problem, invariants/evidence, scope, risk) and the exact label list: exactly ONE type:* label; size:exception only with a documented owner reason.
  2. Authorization (owner). Reviewing the draft IS the approval act. The standing grant (established 2026-10-25; issue #149 is the working model) authorizes creating the issue already carrying status:approved — it only pre-labels a scope the owner already green-lit in conversation; it NEVER self-authorizes. A grant for one cycle never extends to another: without a current owner instruction for that issue, it opens unlabeled and waits for owner approval.
  3. Create (agent). Verify the owner's host capability first (target-host viewerPermission MAINTAIN or ADMIN; TRIAGE never suffices), make ONE create attempt with the authorized labels (no blind retry), and require the host read-back (identity, title, body, labels, state) as evidence before reporting. Classify the result exactly confirmed | no_write | unknown; unknown stops every later mutation.
  4. Creation is pre-validation only. Labels stamped at birth avoid the late-relabel case (which does not re-trigger the pr-gate check). Gate linkage, CI, native review and owner merge remain unaffected.

Pre-Commit Checklist:

  1. Formatting & Linting: Run go fmt ./... and go vet ./... and golangci-lint run ./... — ensure no linting issues exist.
  2. Compilation: Verify the project builds flawlessly:
    go build -o /dev/null ./...
  3. Tests: Run the full test suite with race detector:
    go test -v -race ./...

GGA Rule (DISABLED on this repo — owner decision 2026-11-03)

  • GGA is DISABLED for this project: the pre-commit hook no longer runs gga run; commits are gated only by the Pre-Commit Checklist + the native review RDD gate.
  • The single IA gate for this repo is the Verification & Review Protocol (el gate lo decide assess, readback for trivial/docs, JD only on explicit owner request).
  • The .gga project config is intentionally KEPT: re-enabling = re-adding the gga run || exit 1 block to .git/hooks/pre-commit (hook lives in the local clone; .gga was never deleted).
  • Manual gga run stays available any time a unit wants an extra pre-commit pass; the upstream vigilance item (B6) stays open.
  • NOT use --no-verify without ask to the user (rule unchanged, now moot while no review hook blocks the commit).

Always Ask Before Commit

After verification passes, ALWAYS ask user:

  • "¿Corremos el gate de verificación (review nativo o readback estructural según el routing del Verification & Review Protocol)?"
  • "¿Hacemos commit?"

Wait for user confirmation before proceeding.

Delegated Worker Commits (standing authorization, 2026-10-17)

When the orchestrator delegates an apply/implement work unit to a subagent (worker), the worker is pre-authorized to commit that unit itself after the Pre-Commit Checklist passes (2026-11-03: GGA is disabled on this repo — the worker pipeline no longer invokes GGA; the native reviewRDD is the sole IA gate, invoked by the orchestrator after the commit lands, never inside the worker). Contract:

  1. Worker pipeline per unit: full Pre-Commit Checklist (fmt/vet/lint/build/test -race) → git commit → fix pipeline findings → re-run pipeline → commit again.
  2. Bounded fix loop: fix only pipeline findings the worker can determine real; if a verification tool trips ambiguously (provider timeouts, noisy parser), run the cache-clear command of that tool once and retry once, then stop. There is no GGA round cap — that machinery left with GGA.
  3. Worker authority boundaries (hard rules):
    • NEVER run git commit --no-verify (nor any bypass). A red pipeline finding the worker cannot determine real: abort — leave changes staged, commit NOTHING, and hand back to the orchestrator with the check output as evidence. Only the owner decides --no-verify.
    • NEVER use git push, create PRs, branches off-policy, or any destructive git command.
    • One commit per work unit (≤ ~400 authored changed lines); never the whole feature.
    • Only when this worker is the sole writer of the worktree at that moment (parallel writers require isolated worktrees).
    • Record the pipeline result (commands + verdict) in the feature doc's Log; the native review lineage belongs to the orchestrator's gate step.
  4. What still asks the user (unchanged): --no-verify, push, PR creation, merge, recovery/correction beyond one bounded pass, and any off-touched-scope change.

Rationale: the GGA round-trip loop across sessions burned orchestrator context (24+ rounds of minted findings in PR #135). The worker that authored the code resolves findings with the diff context already loaded; the orchestrator receives one result per unit. (2026-11-03: the same rationale eventually severed GGA entirely from this repo — minted/pre-existing findings outweighed its pre-commit timing; RDD review + the deterministic pipeline took over that role.)

Branch & Commit Strategy

Branch Rules

TypeExamplesBranchPush Direct to mainPR Required
Documentationdocs/**, README.md, and repository tracking docs (odd/, openspec/changes/archive/)Feature branch❌ No✅ Yes
Code Changes*.go, go.mod, go.sum, scripts/, internal/, cmd/Feature branch❌ No✅ Yes
Config / CI.github/** (workflows, issue templates, ruleset-adjacent config; a change to .github/workflows/** also governs delivery, so it never ships without a PR), setup/, templates/, .golangci.ymlFeature branch❌ No✅ Yes

Workflow for docs (docs/**, README.md, and tracking docs):

  1. Create a feature branch (e.g., feat/feat-auth-propose, feat/feat-auth-specs).
  2. Commit the .md file(s) on that branch.
  3. Push the branch and open a PR against main that closes an issue carrying status:approved and carries exactly one type:* label.
  4. CI checks + reviewer approval required.
  5. Confirm the pr-gate check is green, then squash and merge after approval.
  6. Delete the local feature branch (git branch -d).

Workflow for code (.go, go.mod, etc.):

  1. Create a feature branch (e.g., feat/feat-auth-apply).
  2. Commit and push to the remote branch.
  3. Open a PR against main (or against the change tracker if feature-branch-chain is in use).
  4. CI checks + reviewer approval required.
  5. Squash and merge after approval.

Commit Format (Conventional Commits)

<type>(<scope>): <description>
TypeUse Case
featNew features
fixBug fixes
docsDocumentation
choreMaintenance tasks
refactorCode refactoring
testTests

Process

  1. Create feature branch: git checkout -b feat/<feature-name>
  2. For each task:
    □ Delegar implementación (worker async)
    □ Revisar resultado
    □ Verificar el resultado (pipeline + checks funcionales)
    □ Correr el gate según routing (Verification & Review Protocol):
        default (sensible + funcional medio) → según `assess`:
            `reviewDue: true`  → review nativo
            `reviewDue: false` → sin review; gate = pipeline + checks funcionales
            recordatorio de AUTORIDAD RDD → prevalece: inspect/start
        trivial/docs → readback estructural
        escalada a pedido → JD (2 rondas, solo si owner pide "judgment day")
    □ Si hay issues → Fix → correr el gate de nuevo (sin loop infinito)
    □ Si pasa → Commit + Push
    □ Si PR > budget lines → hacer chained PR (ver abajo)
  3. Create PR: gh pr create
  4. Wait for merge users notification
  5. Continue with next task

Pull Request Requirements

  1. Create feature branch from main
  2. Commit following Conventional Commits
  3. Push and create PR via gh
  4. CI checks must pass
  5. Code review approval required
  6. Squash and merge after approval

Post-Merge CI Sequencing

After any PR is squash-merged into main, wait for the CI run triggered on main by that squash-merge commit to finish green before landing the next change on main (including the docs/tracking follow-up commit).

  • ci.yml uses concurrency with cancel-in-progress: consecutive pushes to main cancel the older run, leaving a red/cancelled badge on the squash-merge commit.
  • A squash-merge commit whose CI was cancelled provides no CI evidence for that exact SHA — and it is a potential release baseline (DoD: "CI pasa en cada release").
  • If a run is still cancelled for this reason, do not merge or push again until it is green or re-run the superseded run (gh run rerun <id>) and observe it to completion.

Main Branch Gate — recovery procedure

The main-ci-gate ruleset (id 20610142) is the enforcement, and it has no bypass: bypass_actors is empty and current_user_can_bypass reads never. When the pull-request path itself is unavailable, nothing reaches main until the ruleset is edited. The ruleset lives outside the repository, so git revert cannot restore it — capture it before you touch it.

Relax the gate only for these three cases:

  1. A required check is permanently absent for a valid commit. A run that dies at startup emits no check runs at all, and an absent check blocks where a skipped one does not. Try gh run rerun <id> first: startup failures are often transient, and rerunning the same SHA is the cheapest fix.
  2. The gate blocks the fix to the gate itself.
  3. An emergency revert of a commit that broke main.

1. Capture the rollback artifact and a PUT-valid payload

gh api repos/egkike/mcp-appointments-crm/rulesets/20610142 > /tmp/main-ci-gate.backup.json
jq '{name, target, enforcement, conditions, rules, bypass_actors}' \
  /tmp/main-ci-gate.backup.json > /tmp/main-ci-gate.payload.json

Keep the backup: it is the only path back to the strict configuration. Keep the payload too — a PUT that sends the whole GET response fails, because the response carries read-only fields (id, node_id, created_at, current_user_can_bypass, _links).

2. Relax the minimum

Add a bypass for your own user. Do not remove the required checks or the pull_request rule: that leaves main ungated until someone remembers to put them back, and the storage for that memory is a human under incident pressure.

ACTOR_ID=$(gh api user --jq .id)
jq --argjson id "$ACTOR_ID" \
  '.bypass_actors = [{actor_id: $id, actor_type: "User", bypass_mode: "always"}]' \
  /tmp/main-ci-gate.payload.json > /tmp/main-ci-gate.relaxed.json
gh api -X PUT repos/egkike/mcp-appointments-crm/rulesets/20610142 \
  --input /tmp/main-ci-gate.relaxed.json

3. Restore, then prove the restore

gh api -X PUT repos/egkike/mcp-appointments-crm/rulesets/20610142 \
  --input /tmp/main-ci-gate.payload.json
gh api repos/egkike/mcp-appointments-crm/rulesets/20610142 \
  --jq '{bypass: .bypass_actors, can_bypass: .current_user_can_bypass, rules: [.rules[].type]}'

The procedure is not complete until all four hold:

  • bypass_actors is []
  • current_user_can_bypass is never
  • rules contains both pull_request and required_status_checks
  • allowed_merge_methods is ["squash"] and required_approving_review_count is 0 — a positive count is unsatisfiable, because GitHub forbids self-approval.

Report the incident and the verified restore in the issue that covers the change. A relaxation that is not followed by a proved restore is an open security defect, not a forgotten step.


Cybersecurity Standards (Extended)

Core Principles

  • Defense in Depth: Never rely on a single layer of security. Multiple controls = multiple barriers.
  • Least Privilege: Grant minimum permissions necessary. No root/admin access unless absolutely required.
  • Zero Trust: Never trust input, user, or network. Always verify, always validate.
  • Fail Secure: When something fails, fail safely. Don't expose data on errors.

Input Validation & Sanitization

  • ❌ NEVER trust user input - always validate and sanitize
  • ❌ NEVER use any for input types - use specific types/interfaces (concrete structs)
  • ✅ Validate: type, length, format, range, allowed characters
  • ✅ Use Go validation patterns: struct tags with go-playground/validator, regex matching, or explicit manual checks
  • ✅ Sanitize TUI inputs with regex/string validation before persistence (see Bubble Tea TUI Architecture)
  • ✅ Parameterize ALL database queries - NEVER concatenate strings

SQL Injection Prevention

  • ❌ NEVER concatenate strings in SQL queries - use parameterized queries
  • ❌ NEVER use string replacement for schema/table names - use allowlists
  • ✅ Use ? placeholders: db.QueryRow("SELECT id, name FROM clients WHERE id = ?", clientID)
  • ✅ Validate table/column names against a strict allowlist if dynamic

Authentication & Authorization

N/A for this project: This MCP server runs locally on 127.0.0.1:3001 for a single trusted client (Hermes LLM). No web auth, no public users, no password storage. Re-evaluate this section if a future API-key or remote-deployment auth layer is added.

Reference patterns if/when auth is introduced:

  • ❌ NEVER implement auth from scratch - use proven libraries (e.g., golang-jwt/jwt, casbin, oauth2)
  • ❌ NEVER store passwords in plaintext - use bcrypt/argon2 with proper cost
  • ❌ NEVER trust the LLM client for authorization - always verify in the MCP handler
  • ✅ Implement RBAC at the tool/service layer, not the transport layer
  • ✅ Gate every MCP tool with explicit permission checks
  • ✅ Keep any secrets in env vars, never in source code

JWT Security

N/A for this project: No JWT layer in the current design. The MCP server trusts the loopback client. Re-evaluate this section only if token-based auth is introduced.

Reference patterns if/when JWT is introduced:

  • ❌ NEVER use JWT without expiration (exp claim required)
  • ❌ NEVER use algorithm none in JWT
  • ❌ NEVER store sensitive data in JWT payload - only IDs, roles, permissions
  • ✅ Use strong signing algorithms (RS256, HS256 with strong keys)
  • ✅ Implement refresh token rotation if/when refresh tokens exist

Secrets Management

  • ❌ NEVER hardcode credentials - use environment variables
  • ❌ NEVER expose API keys in code or logs
  • ❌ NEVER commit .env files - add to .gitignore
  • ✅ Use .env.example as template with placeholder values
  • ✅ Use secrets management tools in production (AWS Secrets Manager, HashiCorp Vault)
  • ✅ Rotate secrets regularly

Secure Headers & HTTPS

N/A for this project: The MCP server is loopback-only (127.0.0.1:3001). No browser, no static assets, no public TLS termination. Re-evaluate this section only if the server is exposed beyond loopback or fronted by a public reverse proxy.

Reference patterns if/when the server is exposed:

  • ✅ Terminate TLS at a reverse proxy (Caddy, nginx, traefik) - never in-app
  • ✅ Set HSTS, CSP, X-Frame-Options, X-Content-Type-Options at the proxy
  • ✅ Enable CORS with explicit allow-list of origins (not *)
  • ✅ Never serve static assets over plain HTTP in production

Error Handling & Logging

  • ❌ NEVER expose stack traces in production
  • ❌ NEVER expose internal file paths in error messages
  • ❌ NEVER log sensitive data (passwords, tokens, PII)
  • ✅ Use generic error messages: "An error occurred" + detailed logging server-side
  • ✅ Implement centralized error handling middleware
  • ✅ Log security events: failed auth attempts, rate limit hits, suspicious patterns

Rate Limiting

N/A for this project: Single loopback client, no public endpoints. Concurrency control happens at the SQLite layer via busy_timeout=5000 + WAL mode (see Coding Standards). Re-evaluate this section only if the server is exposed to multiple clients.

Reference patterns if/when rate limiting is needed:

  • ✅ Apply per-tool rate limits (e.g., golang.org/x/time/rate token bucket)
  • ✅ Return clear error messages when limits are hit; do not silently drop
  • ✅ For multi-instance deployments, use a shared store (Redis) for limits

Dependency Security

  • ✅ Audit dependencies regularly: go mod tidy, go list -m -u all, govulncheck ./...
  • ✅ Update dependencies frequently (especially security patches)
  • ❌ NEVER use packages with known vulnerabilities
  • ❌ NEVER use abandoned or unmaintained packages

Secure Coding Patterns

  • ✅ Wrap errors with fmt.Errorf("...: %w", err) for context propagation
  • ✅ Use defer for cleanup (close *sql.Rows, *sql.Stmt, transactions)
  • ✅ Propagate context.Context through all layers for cancellation and timeouts
  • ✅ Return concrete types from public APIs; never any / interface{}
  • ✅ Validate JSON input (MCP tool args) with structs and explicit field tags

Security Checklist (Pre-Commit)

Before every commit, verify:

□ No hardcoded passwords, API keys, or secrets
□ All user inputs are validated and sanitized
□ All database queries use parameterized statements (`?` placeholders)
□ MCP tool handlers validate all input args (types, length, format, range)
□ Error messages don't expose internal details (paths, stack traces, raw SQL)
□ Environment variables documented in .env.example (when introduced)
□ SQLite pragmas active: WAL, busy_timeout=5000, foreign_keys=ON
□ Dependencies have no known vulnerabilities (`govulncheck ./...`)
□ `go fmt ./...` clean
□ `go vet ./...` clean
□ `golangci-lint run ./...` clean
□ `go build -o /dev/null ./...` passes
□ `go test -v -race ./...` passes
□ No layering violations: business logic in use cases/entities only; SQL only in repository adapters; wire JSON tags only in transport adapters; dependencies point inward (`internal/domain` imports nothing outer)

Verification & Review Protocol

Verification routing is exclusive: one path per change, never both by default.

Routing

Change typeGateNotes
Default (sensible + funcional medio: auth/RBAC, transport/network HTTP/SSE, DB/schema, new dependencies go.mod, >400 lines, PII, business logic)Según assessreviewDue decide; detalle abajo
Trivial / docsStructural readbacksingle-file mechanical fixes, documentation
Escalada a pedidoJD (2 blind judges)solo si owner pide explícitamente "judgment day" / "hagamos juicio" — no corre junto al review nativo por default
  • assess decide el gate, no el tipo de cambio. reviewDue: true → native review. reviewDue: false (p. ej. under_budget) → no se corre review: la verificación es el pipeline completo + los checks funcionales aplicables, porque correr un review igual es gastar rondas de modelo sin mandato. Mecánica owned by gentle-ai; consultar con review mode status / review status.
  • Riesgo ≠ autoridad — no confundirlas. assess responde "¿hace falta por riesgo?". Un recordatorio de autoridad RDD (candidato sin receipt) responde otra pregunta y prevalece sobre reviewDue: si el harness lo dispara, corresponde inspect → start aunque assess haya dicho reviewDue: false. El único camino limpio para no invocarlo es una disposición explícita del humano sobre ese candidato exacto ("este target no se revisa"); el anuncio del agente no cuenta como disposición.
  • JD is a second-opinion escalation, never run together with native review unless explicitly requested.
  • Delivery closes under ordinary repository policy (Pre-Commit Checklist, CI green, PR review approval; the IA gate is the Verification & Review Protocol — GGA disabled 2026-11-03).
  • Verification always precedes the gate: full pipeline + applicable functional checks.
  • Precedente (2026-11-13, issue #219 / PR #220): risk medium, reviewDue: false (under_budget), review nativo omitido por decisión del owner; gate = pipeline completo verde (fmt/vet/lint/build/test -race).

Judgment Day Process (escalada — solo a pedido)

  1. User says "judgment day" or "hagamos juicio"
  2. Launch two independent blind judge agents
  3. Synthesize findings from both judges
  4. Apply fixes for identified issues
  5. Re-judge until both pass OR escalate to user (max 2 rounds)

What Gets Judged

  • Code quality and architecture
  • Security posture
  • Performance considerations
  • Adherence to project standards
  • Test coverage

Judgment Criteria

LevelMeaningAction
CRITICALMust fix before proceedingFix immediately
WARNINGShould fix if easyFix or document reason not to
SUGGESTIONConsider fixingOptional

Testing & Quality

  • go test -v -race ./...

CI Awareness

  • Refer to .github/workflows for source of truth on CI checks
  • All checks must pass before merge

Proactivity

  • Add or update tests for any modified logic
  • Tests are mandatory for new features

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.