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.
- golang-patternsSkill
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
- Distinctive: line 8
Think Big Picture: Before suggesting a fix, consider how it affects the entire system architecture.
- Distinctive: line 10
Enforce Best Practices: Follow the project's existing patterns — do NOT suggest DI, decorators, or patterns that don't exist in the …
- Very specific: line 11
Zero-Tolerance for Bad Types: If you see any, you must provide a specific type or interface suggestion.
- Distinctive: line 12
Security Mindset: ALWAYS prioritize security.
- Distinctive: line 15
Philosophy: Create small components with a single responsibility.
- Distinctive: line 16
Logic: Prefer composition over complex configurations.
- Distinctive: line 20
When you find an issue, don't just say it's wrong.
- Very specific: line 30
Concurreny & SQLite: Always assume high concurrency from the upstream LLM (Hermes).
- Distinctive: line 33
Bubble Tea TUI Architecture: Follow the strict Model-View-Update (MVU) pattern.
- Very specific: line 59
Only *domain.SemanticError messages reach the client/LLM.
- Distinctive: line 66
Before staging, committing, or pushing any code to the repository, you MUST execute and pass the following verification pipeline.
- Very specific: line 69
Every pull request into main must pass the pr-gate required status check (.github/workflows/pr-gate.yml, enforced by the main-ci-gate …
- Very specific: line 73
Owner approval: every linked issue must carry the status:approved label (owner-granted, protected label — never self-assigned by agents).
- Very specific: line 84
Draft (agent): Before any code work, the agent proposes the title, body (problem, invariants/evidence, scope, risk) and the exact label …
- Very specific: line 90
Formatting & Linting: Run go fmt ./... and go vet ./...
- Distinctive: line 91
Compilation: Verify the project builds flawlessly:
- Distinctive: line 95
Tests: Run the full test suite with race detector:
- Very specific: line 112
NOT use --no-verify without ask to the user (rule unchanged, now moot while no review hook blocks the commit).
- Distinctive: line 117
After verification passes, ALWAYS ask user:
- Distinctive: line 121
Wait for user confirmation before proceeding.
- Distinctive: line 125
When the orchestrator delegates an apply/implement work unit to a subagent (worker), the worker is pre-authorized to commit that unit …
- Distinctive: line 138
NEVER run git commit --no-verify (nor any bypass).
- Distinctive: line 142
NEVER use git push, create PRs, branches off-policy, or any destructive git command.
- Distinctive: line 144
Only when this worker is the sole writer of the worktree at that moment (parallel writers require isolated worktrees).
- Very specific: line 169
Create a feature branch (e.g., feat/feat-auth-propose, feat/feat-auth-specs).
- Very specific: line 170
Commit the .md file(s) on that branch.
- Distinctive: line 174
Delete the local feature branch (git branch -d).
- Very specific: line 177
Create a feature branch (e.g., feat/feat-auth-apply).
- Distinctive: line 178
Commit and push to the remote branch.
- Distinctive: line 223
Create feature branch from main
- Distinctive: line 224
Commit following Conventional Commits
- Distinctive: line 232
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 …
- Very specific: line 236
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>) …
- Very specific: line 263
Keep the backup: it is the only path back to the strict configuration.
- Very specific: line 270
Add a bypass for your own user.
- Distinctive: line 309
Defense in Depth: Never rely on a single layer of security.
- Distinctive: line 311
Zero Trust: Never trust input, user, or network.
- Distinctive: line 312
Fail Secure: When something fails, fail safely.
- Distinctive: line 397
Before every commit, verify:
- Distinctive: line 468
All checks must pass before merge
- Distinctive: line 471
Add or update tests for any modified logic
≈ “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.
Files
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) orpkg/(public libraries). Binaries go incmd/<name>/. Configuration, scripts, and templates at the repo root or undersetup//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=5000and journal mode set toWAL. - 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:
| Layer | Location | Holds |
| Domain (center) | internal/domain/entity, /repository, /service, errors.go | Entities + invariants (Validate), repository/service ports (interfaces), SemanticError + error codes. No wire tags, no SQL |
| Application | internal/application/usecase, /dto | Orchestration, RBAC re-assert (auth.RequireRole), partial-merge semantics, semantic error strings (Spanish), DTO carriers (cross-layer doc comments) |
| Transport adapters | internal/mcp | MCP tool handlers, typed input/DTO structs with JSON tags, wire schemas, error sanitization boundary (internal/mcp/errors.go) |
| Persistence adapters | internal/repository (+ internal/db) | SQLite adapters implementing domain ports; prepared statements only; canonical DDL + pragmas in internal/db |
| UI adapter | internal/tui (+ internal/admin) | Bubble Tea admin TUI / console flows |
| Shared edges | internal/auth, internal/validation, internal/config | RBAC helpers (RequireCaller/RequireRole), input validation, app setup |
| Composition root | cmd/mcp-server | Wiring/DI, RBAC tool map, CLI entrypoints (mcp-server, admin tui, hermes chat). No business rules |
Boundary contracts (documented exceptions live inline with their rule):
- 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; specsopenspec/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-emptyX-Caller-Idheader, 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;
accountscollision 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_clientof 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.
- Sole documented exception — anonymous registration seam
- Only
*domain.SemanticErrormessages reach the client/LLM; every other error collapses to a generic-32603— never leak internals throughinternal/mcp/errors.go. - SQL only in
internal/repositoryadapters; prepared statements (?); schema changes only viainternal/db/schema.gocanonical DDL. - Wire shapes (JSON tags,
omitempty) stay ininternal/mcpstructs; 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):
- 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). - Owner approval: every linked issue must carry the
status:approvedlabel (owner-granted, protected label — never self-assigned by agents). - 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:
- 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:exceptiononly with a documented owner reason. - 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. - Create (agent). Verify the owner's host capability first (target-host
viewerPermissionMAINTAIN 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 exactlyconfirmed | no_write | unknown;unknownstops every later mutation. - Creation is pre-validation only. Labels stamped at birth avoid the late-relabel case (which does not re-trigger the
pr-gatecheck). Gate linkage, CI, native review and owner merge remain unaffected.
Pre-Commit Checklist:
- Formatting & Linting: Run
go fmt ./...andgo vet ./...andgolangci-lint run ./...— ensure no linting issues exist. - Compilation: Verify the project builds flawlessly:
go build -o /dev/null ./... - 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
.ggaproject config is intentionally KEPT: re-enabling = re-adding thegga run || exit 1block to.git/hooks/pre-commit(hook lives in the local clone;.ggawas never deleted). - Manual
gga runstays available any time a unit wants an extra pre-commit pass; the upstream vigilance item (B6) stays open. - NOT use
--no-verifywithout 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:
- Worker pipeline per unit: full Pre-Commit Checklist (fmt/vet/lint/build/test -race)
→
git commit→ fix pipeline findings → re-run pipeline → commit again. - 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.
- 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.
- NEVER run
- 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
| Type | Examples | Branch | Push Direct to main | PR Required |
| Documentation | docs/**, 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.yml | Feature branch | ❌ No | ✅ Yes |
Workflow for docs (docs/**, README.md, and tracking docs):
- Create a feature branch (e.g.,
feat/feat-auth-propose,feat/feat-auth-specs). - Commit the
.mdfile(s) on that branch. - Push the branch and open a PR against
mainthat closes an issue carryingstatus:approvedand carries exactly onetype:*label. - CI checks + reviewer approval required.
- Confirm the
pr-gatecheck is green, then squash and merge after approval. - Delete the local feature branch (
git branch -d).
Workflow for code (.go, go.mod, etc.):
- Create a feature branch (e.g.,
feat/feat-auth-apply). - Commit and push to the remote branch.
- Open a PR against
main(or against the change tracker iffeature-branch-chainis in use). - CI checks + reviewer approval required.
- Squash and merge after approval.
Commit Format (Conventional Commits)
<type>(<scope>): <description>| Type | Use Case |
feat | New features |
fix | Bug fixes |
docs | Documentation |
chore | Maintenance tasks |
refactor | Code refactoring |
test | Tests |
Process
- Create feature branch:
git checkout -b feat/<feature-name> - 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) - Create PR:
gh pr create - Wait for merge users notification
- Continue with next task
Pull Request Requirements
- Create feature branch from
main - Commit following Conventional Commits
- Push and create PR via
gh - CI checks must pass
- Code review approval required
- 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.ymluses concurrency with cancel-in-progress: consecutive pushes tomaincancel 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:
- 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. - The gate blocks the fix to the gate itself.
- 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.jsonKeep 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.json3. 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_actorsis[]current_user_can_bypassisneverrulescontains bothpull_requestandrequired_status_checksallowed_merge_methodsis["squash"]andrequired_approving_review_countis0— 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
anyfor 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:3001for 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 (
expclaim required) - ❌ NEVER use algorithm
nonein 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
.envfiles - add to.gitignore - ✅ Use
.env.exampleas 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/ratetoken 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
deferfor cleanup (close*sql.Rows,*sql.Stmt, transactions) - ✅ Propagate
context.Contextthrough 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 type | Gate | Notes |
| Default (sensible + funcional medio: auth/RBAC, transport/network HTTP/SSE, DB/schema, new dependencies go.mod, >400 lines, PII, business logic) | Según assess | reviewDue decide; detalle abajo |
| Trivial / docs | Structural readback | single-file mechanical fixes, documentation |
| Escalada a pedido | JD (2 blind judges) | solo si owner pide explícitamente "judgment day" / "hagamos juicio" — no corre junto al review nativo por default |
assessdecide 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 bygentle-ai; consultar conreview mode status/review status.- Riesgo ≠ autoridad — no confundirlas.
assessresponde "¿hace falta por riesgo?". Un recordatorio de autoridad RDD (candidato sin receipt) responde otra pregunta y prevalece sobrereviewDue: si el harness lo dispara, correspondeinspect→startaunqueassesshaya dichoreviewDue: 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)
- User says "judgment day" or "hagamos juicio"
- Launch two independent blind judge agents
- Synthesize findings from both judges
- Apply fixes for identified issues
- 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
| Level | Meaning | Action |
| CRITICAL | Must fix before proceeding | Fix immediately |
| WARNING | Should fix if easy | Fix or document reason not to |
| SUGGESTION | Consider fixing | Optional |
Testing & Quality
- go test -v -race ./...
CI Awareness
- Refer to
.github/workflowsfor 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
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
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.

