agentleFS
joaoguimaraesprojoaoguimaraespro/personal-finance/AGENTS.md

personal-finance

AGENTS.md1 starsChanged todayMITView on GitHub

Instructions for AI coding agents (Claude Code, Codex, Cursor) working in this repository. Humans: see CONTRIBUTING.md. The binding rules are in .specify/memory/constitution.md. The short version: Project rules that add to or override the generic stack rules below live in .claude/rules/project/ (Cursor: .cursor/rules/project-*.mdc): backend.md, web.md, testing.md, security.md. Where they differ from a pack rule, the project rule wins. Features live in specs/<NNN-feature>/ (spec.md, plan.md, tasks.md). Implement tasks with task-loop specs/<NNN-feature>/tasks.md: one fresh agent session per task, and a task counts as…

  • Reads credentials

The file

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

10 rules. About 1 is common, 6 are distinctive, and 3 are very specific to this project.

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read-only brokers: Never write code that places orders, moves money or withdraws.

    line 10
  2. Distinctive:

    Test-first: Every behaviour change starts with a failing test.

    line 12
  3. Very specific:

    Follow the repo's application structure: feature slices with minimal APIs, CQRS handlers behind a mediator (<Verb><Entity>Command/Query), …

    line 73
  4. Distinctive:

    Test-first by user-visible behaviour, with the repo's runner (Vitest and Testing Library by default).

    line 96
  5. Very specific:

    No secrets or tokens in the browser: public env prefixes (NEXT_PUBLIC_, VITE_) are public.

    line 98
  6. Distinctive:

    Check the installed Angular version first.

    line 114
  7. Distinctive:

    Every UI string goes into every language file in the same change.

    line 118
  8. Common:

    Never paste secrets, tokens, real user data or client data into a prompt or a finding.

    line 148
  9. Distinctive:

    Review a screen: Run the app and look at it before judging it: light and dark, 375 px and 1440 px, keyboard only.

    line 171
  10. Very specific:

    Keep it consistent: Use tokens, never hard-coded values.

    line 174

≈ “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

AGENTS.md

Instructions for AI coding agents (Claude Code, Codex, Cursor) working in this repository. Humans: see CONTRIBUTING.md.

Rules

The binding rules are in .specify/memory/constitution.md. The short version:

  • Read-only brokers. Never write code that places orders, moves money or withdraws.
  • Money is decimal; the backend calculates, the UI only displays.
  • Test-first. Every behaviour change starts with a failing test.
  • No personal data anywhere: synthetic data and the demo broker only.
  • Architecture, security or data decisions get a new ADR in docs/adr/; merged ADRs are never edited.

Project rules that add to or override the generic stack rules below live in .claude/rules/project/ (Cursor: .cursor/rules/project-*.mdc): backend.md, web.md, testing.md, security.md. Where they differ from a pack rule, the project rule wins.

Workflow

SizeProcess
Bug fix, small changeA task with acceptance criteria → test-first → pull request
Feature/speckit-specify → /speckit-plan → /speckit-tasks → human review of spec and tasks → implement

Features live in specs/<NNN-feature>/ (spec.md, plan.md, tasks.md). Implement tasks with task-loop specs/<NNN-feature>/tasks.md: one fresh agent session per task, and a task counts as done only when the verification gate in .agent-loop.env passes.

Commands

cd backend && dotnet build                                   # .NET 10 (see backend/global.json)
cd backend && dotnet format --verify-no-changes --include <files>   # C# format check on the files you touch
cd backend && dotnet test --project tests/Finance.Tests      # one test project (Microsoft.Testing.Platform)
cd web && npm run build                                      # Angular build and type check
cd web && npm test && npm run lint:format                    # Vitest + Prettier

Integration.Tests need Docker; CI runs them on every pull request. The whole backend is not dotnet format clean yet, so check only the files you change.

Subagents (Claude Code)

One version of each generic agent, from Armature; the project context they need is in the rules above, not in copies of the agents.

  • Armature core plugin (user level): tdd-guide (implements one task test-first), security-reviewer (report only), build-error-resolver (minimal fixes to a broken build).
  • Written into .claude/agents/ by the Armature packs (managed: armature sync, never edited here): csharp-reviewer, typescript-reviewer (report only), dotnet-developer, angular-developer, design-system-guard.

Never

Merge pull requests, push to main, edit merged ADRs, weaken or skip tests, or commit secrets.

<!-- armature:stack-dotnet:start -->

.NET (stack-dotnet)

Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or AGENTS.md outside the Armature sections) differ, the repo wins.

Rules: .claude/rules/csharp/ (coding style, patterns, data access, security, testing), also rendered to .cursor/rules/csharp-*.mdc. They load for *.cs, *.csproj and appsettings*.json. The repo's .editorconfig, architecture doc and ADRs decide style and structure; the rules describe the defaults when the repo says nothing.

  • Style follows the repo's .editorconfig (var, namespaces, braces); nullable on. Without one, Armature's template (plugins/stack-dotnet/templates/.editorconfig) is a starting point.
  • Expected failures as results (Result/Error: validation, not found, conflict, forbidden) rather than exceptions, in whatever shape the repo already uses.
  • Follow the repo's application structure: feature slices with minimal APIs, CQRS handlers behind a mediator (<Verb><Entity>Command/Query), or controllers. Do not introduce a different one in a single change.
  • A module owns its data: no reaching into another module's DbContext; migrations come from the EF tool.

Skills: dotnet-create-module, dotnet-create-entity, dotnet-create-command-query (for repos that use CQRS), dotnet-ef-migration. Official .NET skills come from the dotnet/skills marketplace (enabled in .claude/settings.json, not copied here).

Agents: [@dotnet-developer] implements one .NET task test-first; csharp-reviewer reviews C# changes (report only). Typical gate: dotnet build, dotnet format --verify-no-changes, dotnet test (the repo's VERIFY_CMD wins).

<!-- armature:stack-dotnet:end --><!-- armature:stack-typescript:start -->

TypeScript

Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or AGENTS.md outside the Armature sections) differ, the repo wins.

Rules: .claude/rules/typescript/ (Cursor: .cursor/rules/typescript-*.mdc), applied to *.ts, *.tsx, *.js and test files.

  • Strict TypeScript: no any, no hiding casts, no ! without a guard; schemas (e.g. Zod) at every trust boundary.
  • One formatter and linter, run by the gate: what the repo already uses (Biome when it has none).
  • Test-first by user-visible behaviour, with the repo's runner (Vitest and Testing Library by default); Playwright for critical flows.
  • No secrets or tokens in the browser: public env prefixes (NEXT_PUBLIC_, VITE_) are public.
AgentUse it
typescript-reviewerAfter TypeScript changes, before a pull request. Reports findings with a verdict; never edits
<!-- armature:stack-typescript:end --><!-- armature:stack-angular:start -->

Angular

Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or AGENTS.md outside the Armature sections) differ, the repo wins.

Rules: .claude/rules/angular/ (Cursor: .cursor/rules/angular-*.mdc), plus the TypeScript rules. Skill: angular-guide (the official angular/skills angular-developer skill, renamed so it does not clash with the agent).

  • Check the installed Angular version first; follow the CLI conventions the repo already uses.
  • Defaults for new code: standalone components, OnPush, inject(), signal inputs/outputs, resource/rxResource for data, block control flow with track.
  • HTTP through the repo's API service and HttpClient, so the interceptors (session expiry, timeouts, XSRF) apply.
  • Every UI string goes into every language file in the same change; money and dates through the shared pipes.
  • The backend computes figures; the UI only displays them.
AgentUse it
angular-developerTasks tagged [@angular-developer]: one task, test-first
typescript-reviewerAfter web changes, before a pull request. Reports only
<!-- armature:stack-angular:end --><!-- armature:security:start -->

Security review tools

Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or AGENTS.md outside the Armature sections) differ, the repo wins.

Nothing from this pack is copied into the repo. The security plugins are installed from upstream, at user scope, on demand (when a change touches auth, input handling, secrets, dependencies or integrations), and never vendored: Trail of Bits' skills are CC-BY-SA-4.0, which must not be mixed into the repo.

claude plugin marketplace add trailofbits/skills
claude plugin install insecure-defaults@trailofbits      # hard-coded credentials, fail-open defaults
claude plugin install sharp-edges@trailofbits            # error-prone APIs and dangerous configuration
claude plugin install differential-review@trailofbits    # security review of a diff with git history
claude plugin install supply-chain-risk-auditor@trailofbits
claude plugin install security-guidance@claude-plugins-official   # warnings on risky edits
  • The security-reviewer agent (Armature core) stays the first pass before a pull request; the plugins above go deeper.
  • Static findings come from semgrep scan --json in PR Validation, not from a model.
  • Never paste secrets, tokens, real user data or client data into a prompt or a finding.
<!-- armature:security:end --><!-- armature:design:start -->

Design work

Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or AGENTS.md outside the Armature sections) differ, the repo wins.

Work like a senior product designer, not a code generator. Start from the user's task and the evidence on screen, reuse what the app already has before adding anything, and treat every state as a deliverable: empty, loading, partial, error, no permission and stale. The repo's own design rules (its design-system doc and DESIGN.md) outrank any skill. Accessibility means WCAG 2.2 AA: keyboard use, visible focus, contrast, no meaning carried by colour alone, labels.

Skill or agentUse it to
impeccableReview and improve an existing screen: critique (UX, hierarchy), audit (accessibility, performance, responsive), then polish, typeset, layout, clarify or harden. The default for "make this better"
frontend-designSet a new screen's direction before code: purpose, tone, hierarchy. Constrained by the repo's design rules
ui-ux-pro-maxLook up palettes, font pairings, UX guidelines and chart types: python3 .agents/skills/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain>. Do not use --persist
emil-design-eng + review-animationsMotion and interaction feel (easing, duration, hover and press states); review every animation before shipping; respect prefers-reduced-motion
break-uiStress a screen before calling it done: long text, empty and huge data, slow network, narrow widths
design-system-guard (agent)Check a UI diff against the design tokens and rules: no hard-coded colours or sizes, components reused

Review a screen. Run the app and look at it before judging it: light and dark, 375 px and 1440 px, keyboard only. Fix problems by severity and show before and after screenshots. A visual change is done only when a person has seen it.

Keep it consistent. Use tokens, never hard-coded values. Impeccable owns PRODUCT.md (users, purpose, tone; /impeccable init) and DESIGN.md (the visual system; /impeccable document, refreshed in the same PR as a visual change). Do not create a design-system/ folder. Keep telemetry off (DO_NOT_TRACK=1). Vendored skills are pinned in Armature's vendor.lock.json; do not edit them in the repo (armature sync reports it).

<!-- armature:design:end --><!-- armature:core:start -->

Armature (core)

Armature writes defaults into this repo: the sections between armature: markers in this file, the rules in .claude/rules/ and .cursor/rules/, skills and agents. They are defaults, not the repo's law. Where this repo's own rules differ (.claude/rules/project/, any other rule Armature does not manage, or AGENTS.md outside the Armature sections), the repo wins. To change an Armature section here, use .armature/overrides.json, not an edit between the markers (armature sync reports edits there as conflicts).

Task Loop. Implement a feature's tasks.md one task per fresh agent session, test-first; a task is done only when the gate (VERIFY_CMD in .agent-loop.env) passes:

task-loop specs/<NNN-feature>/tasks.md                            # on PATH while the core plugin is enabled
"$ARMATURE_HOME/plugins/core/bin/task-loop" specs/<NNN-feature>/tasks.md   # from a normal shell

--dry-run prints the plan; tasks_lint.py specs/<NNN-feature>/tasks.md checks the task lines first.

Agent (.claude/agents/)Use it
tdd-guideUntagged tasks: one task, failing test first, then the code
build-error-resolverThe build, type check or format gate fails: the smallest fix, no refactoring
security-reviewerBefore a pull request that touches auth, input, secrets, dependencies or integrations. Reports only
lead-engineer, software-architect, database-engineer, devops-engineerPlans, designs, schemas, pipelines
product-manager, ux-designer, researcherSpecs, flows, evidence

Commits are Conventional Commits with no co-author or AI attribution (the commit-msg hook checks; .armature/config.json sets the subject limit and a task-id prefix). Never commit .env files, secrets or client data (the pre-commit hook checks; .armature/allow-data lists data that may be committed).

<!-- armature:core:end -->

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.