mcp-server-for-ynab 0.1.0__tar.gz

mcp_server_for_ynab-0.1.0/.agents/.skill-lock.json

@@ -0,0 +1,42 @@
+{
+  "version": 3,
+  "skills": {
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "sourceUrl": "https://github.com/vercel-labs/skills.git",
+      "skillPath": "skills/find-skills/SKILL.md",
+      "skillFolderHash": "3013fdeb8a11b10b1eb795ec3ae8bfca38f7c26d",
+      "installedAt": "2026-04-06T01:04:58.085Z",
+      "updatedAt": "2026-04-06T01:04:58.085Z"
+    },
+    "writing-clearly-and-concisely": {
+      "source": "softaworks/agent-toolkit",
+      "sourceType": "github",
+      "sourceUrl": "https://github.com/softaworks/agent-toolkit.git",
+      "skillPath": "skills/writing-clearly-and-concisely/SKILL.md",
+      "skillFolderHash": "4bb2d919b567277219f7a18358bd05e0a1679a77",
+      "installedAt": "2026-04-06T01:05:44.917Z",
+      "updatedAt": "2026-04-06T01:05:44.917Z"
+    },
+    "requesting-code-review": {
+      "source": "obra/superpowers",
+      "sourceType": "github",
+      "sourceUrl": "https://github.com/obra/superpowers.git",
+      "skillPath": "skills/requesting-code-review/SKILL.md",
+      "skillFolderHash": "ed265b1a03114cc400d5524afc5c961a4aa9ea8b",
+      "installedAt": "2026-04-06T01:06:17.201Z",
+      "updatedAt": "2026-04-06T01:06:17.201Z"
+    },
+    "karpathy-guidelines": {
+      "source": "forrestchang/andrej-karpathy-skills",
+      "sourceType": "github",
+      "sourceUrl": "https://github.com/forrestchang/andrej-karpathy-skills.git",
+      "skillPath": "skills/karpathy-guidelines/SKILL.md",
+      "skillFolderHash": "e119339197d600aa39a24fd7a95c946800c9c949",
+      "installedAt": "2026-04-06T03:02:13.858Z",
+      "updatedAt": "2026-04-06T03:02:13.858Z"
+    }
+  },
+  "dismissed": {}
+}

mcp_server_for_ynab-0.1.0/.agents/README.md

@@ -0,0 +1,34 @@
+# Agent skills (mcp-server-for-ynab)
+
+This repository is **Python**. Skills under `skills/` assume:
+
+- **`pyproject.toml`** for dependencies, scripts, and tool config (`ruff`, `pytest`, `mypy`, etc.)
+- **MCP** as the primary agent surface (thin tools, logic in services/domain modules)
+- **`pytest`** for tests; optional HTTP/Postman only if documented in the repo
+
+| Skill | When to use |
+|-------|-------------|
+| `architecture-boundaries` | Layering MCP tools, services, clients, persistence |
+| `agent-runtime-guardrails` | MCP tools, prompts, observability, bounded behavior |
+| `python-api-docs` | Docstrings, type hints, public API and tool descriptions |
+| `contract-sync` | Pydantic models, OpenAPI, schemas, generated artifacts |
+| `live-api-verification` | Response models, new routes, transport changes, "does it work" claims |
+| `ynab-platform-compliance` | Naming, branding, disclaimers, privacy policy, OAuth, rate limits |
+| `data-access-discipline` | DB schema, queries, transactions (if used) |
+| `docs-honesty` | README and docs match implementation |
+| `local-workflow-reproducibility` | Local dev, env, seeds, repeatable commands |
+| `hardening-review` | Pre-merge / signoff review |
+| `postman-standards` | Only if repo maintains HTTP Postman collections |
+| `karpathy-guidelines` | General coding discipline |
+| `find-skills` | Discover installable skills from the ecosystem |
+| `requesting-code-review` | Structured review before merge |
+| `writing-clearly-and-concisely` | Human-facing prose |
+
+## Third-party skills
+
+Skills installed from other repositories are recorded in `.skill-lock.json` but
+their content is **not** committed here — they carry their own upstream licenses,
+and vendoring them would redistribute someone else's work from an Apache-2.0
+repo. Reinstall them from the lock file if you want them locally.
+
+The skills tracked in this repository are its own.

mcp_server_for_ynab-0.1.0/.agents/skills/agent-runtime-guardrails/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agent-runtime-guardrails
+description: Keep autonomous runtime behavior observable, bounded, and separate from durable business logic.
+---
+
+# Agent Runtime Guardrails
+
+Use this skill when working on MCP servers, tool execution, planning loops, memory, checkpoints, approvals, or other agent-facing runtime behavior in this **Python** repository.
+
+## Use When
+
+- Adding or editing MCP tools, resources, or prompts
+- Changing tool-calling or error-mapping behavior
+- Adding memory or checkpoint systems
+- Adding human-in-the-loop approval boundaries
+- Reviewing runtime safety and observability
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md`
+- MCP SDK usage in this repo (server setup, lifespan, tool registration)
+- Any runtime or workflow docs (for example `docs/agent-design.md`, `docs/current-state.md`)
+
+## Core Rules
+
+1. Prompts and tool descriptions do not replace durable business rules or validation in code.
+2. Ephemeral conversation or session state does not replace persistent storage when durability is required.
+3. Runtime orchestration should be observable (structured logging, clear error types, traceable tool results).
+4. Human approvals or intervention boundaries should be explicit where relevant.
+5. Tools must not silently bypass application invariants (budget scope, auth, rate limits).
+6. Long-running or multi-step behavior should use explicit checkpoints or idempotent steps—not implicit “continue from chat” assumptions.
+7. Tool and server capabilities advertised to clients must match what is implemented.
+8. **MCP boundary:** Each tool should have a narrow, documented contract (Pydantic models or typed parameters). Prefer structured errors (`isError`, clear messages) over opaque stack traces in tool results.
+
+## Workflow
+
+1. Identify what belongs in MCP wiring versus service/domain logic.
+2. Make durable state transitions explicit in code, not only in prompts.
+3. Ensure important steps are observable through logs or persisted records.
+4. Check auth, env vars, and secrets handling (`YNAB_*`, tokens via env—not hardcoded).
+5. Update docs if tool behavior or required env changed.
+6. Verify unhappy paths: API failures, partial data, timeouts, invalid user input.
+
+## Common Failure Modes
+
+- critical logic only in tool docstrings or system prompts
+- session memory used as system-of-record
+- unhandled exceptions surfaced as generic tool failures
+- no clear boundary between “call YNAB API” and “orchestrate workflow”
+- tools that do too much in one invocation
+- overstated autonomy in README vs actual tool set
+
+## Completion Standard
+
+Runtime behavior is bounded, observable, documented honestly, and does not hide durable business logic behind MCP or prompt layers.

mcp_server_for_ynab-0.1.0/.agents/skills/architecture-boundaries/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: architecture-boundaries
+description: Preserve clean system layering and prevent logic from smearing across handlers, services, persistence, integrations, and agent runtime.
+---
+
+# Architecture Boundaries
+
+Use this skill when adding or changing core logic, MCP tools, HTTP APIs, jobs, integrations, or runtime orchestration in this **Python** repository.
+
+## Use When
+
+- Adding MCP tools, resources, or prompts
+- Adding HTTP routes (if any)
+- Adding orchestration or business logic
+- Adding database access patterns
+- Adding jobs, workers, or scheduled tasks
+- Adding third-party integrations (for example YNAB API clients)
+- Reviewing whether a change belongs in the right layer
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md`
+- `pyproject.toml` (package layout, entry points)
+- Any repo-specific architecture docs (for example `docs/architecture.md`, `docs/current-state.md`)
+
+## Core Rules
+
+1. **Transport / protocol layer** (MCP server setup, FastAPI routers, CLI entrypoints) owns wiring, validation at the boundary, and mapping to/from wire types—not core business rules.
+2. **Services or domain modules** own workflows, state transitions, and business rules.
+3. **Data access** owns persistence and queries, not business policy.
+4. **Integration clients** (YNAB SDK, HTTP clients) own provider-specific IO and normalization, not app-wide orchestration.
+5. **MCP tool handlers** should stay thin: parse inputs, call services, map errors to structured tool results. Do not hide durable invariants only in tool docstrings or prompts.
+6. Do not invent a parallel architecture when the repo already has one; follow existing package layout (`src/` layout, module naming).
+7. Keep boundaries obvious enough that future agents can place code correctly.
+8. **Multi-step workflows:** Reusable step logic belongs in domain or service modules, not duplicated in each tool or route.
+9. **Persistence:** Prefer normalized storage and explicit fields as source of truth. Use **`data-access-discipline`** for schema and transactions.
+
+## Typical Python layout (adapt to this repo)
+
+| Layer | Examples |
+|-------|----------|
+| Entry | `__main__.py`, `server.py`, Typer/Click CLI, FastAPI `APIRouter` |
+| MCP surface | Tool/resource registration; argument validation via Pydantic |
+| Services | `services/`, `domain/`, use-case functions |
+| Integrations | `clients/ynab.py`, thin wrappers around external APIs |
+| Persistence | `db/`, repositories, SQLAlchemy models (if used) |
+
+## Workflow
+
+1. Identify the type of change: protocol surface, orchestration, persistence, integration.
+2. Find the existing repo pattern for that kind of work.
+3. Place new logic in the narrowest correct layer.
+4. Check whether cross-layer documentation needs to be updated.
+5. Verify the change did not create new ambiguity about responsibility.
+
+## Common Failure Modes
+
+- business logic in MCP tool functions or route handlers
+- raw DB or file access scattered through tools
+- integration clients owning multi-step workflows
+- prompts replacing durable validation rules
+- multiple competing patterns for the same concern
+
+## Completion Standard
+
+The change fits the existing architecture cleanly, layer responsibilities remain legible, and no new ambiguity was introduced.

mcp_server_for_ynab-0.1.0/.agents/skills/contract-sync/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: contract-sync
+description: Keep source-of-truth contracts, generated artifacts, and tests aligned whenever interfaces change.
+---
+
+# Contract Sync
+
+Use this skill when the repo has any source-of-truth contract and derived artifacts such as OpenAPI, JSON Schema, generated clients, MCP tool schemas, or prompt/task contracts.
+
+## Use When
+
+- Changing HTTP routes or MCP tool inputs/outputs
+- Changing request or response shapes (Pydantic models, dataclasses, TypedDicts)
+- Changing schema-driven generated artifacts
+- Updating public interface docs
+- Updating codegen outputs
+- Reviewing drift between source and generated files
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md` and `pyproject.toml` (`[project.scripts]`, `[tool.*]`, optional dependency groups)
+- `CONTRIBUTING.md` if present and maintained
+- Contract-related docs in this repo (for example `docs/api-strategy.md`, `docs/contract-discipline.md`)
+- `postman/` or OpenAPI under `docs/api/`, only if this repo maintains them
+- Generation scripts under `scripts/` or `tools/`
+
+## Core Rules
+
+1. Identify the source of truth before editing anything.
+   - Common patterns in Python repos: **Pydantic** (or similar) models; FastAPI/Starlette route signatures; hand-authored OpenAPI; JSON Schema; MCP tool parameter schemas derived from types or explicit definitions.
+   - Derived artifacts (OpenAPI YAML, JSON Schema exports, generated clients, Postman collections) must be regenerated from that source unless the repo documents otherwise.
+2. Do not hand-edit generated artifacts unless the repo explicitly says to.
+3. Regenerate derived artifacts when the source changes, using commands in `pyproject.toml`, `Makefile`, `uv run`, `poetry run`, or documented in `README.md` / `AGENTS.md`.
+4. Commit source changes and generated changes together.
+5. Update docs that describe the public or shared contract surface.
+6. Ensure tests validate the actual interface (`pytest`, contract tests, schema snapshots)—not only internal mocks.
+
+## Workflow
+
+1. Determine whether the change affects a contract.
+2. Identify the hand-authored source and the generated outputs (`pyproject.toml`, CI config, repo docs).
+3. Update the source of truth (models, tool definitions, route handlers).
+4. Run the appropriate generation or export step.
+5. Update any relevant docs or examples.
+6. Run the relevant tests or checks.
+
+## Common Failure Modes
+
+- generated artifacts not regenerated
+- public docs still describing old request or response shapes
+- manually patched generated files
+- tests passing while contract artifacts drift
+- MCP tool schema out of sync with implementation
+- temporary undocumented contract changes
+
+## Completion Standard
+
+The source-of-truth contract, generated artifacts, tests, and docs all describe the same interface.

mcp_server_for_ynab-0.1.0/.agents/skills/data-access-discipline/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: data-access-discipline
+description: Keep persistence logic explicit, consistent, and separate from transport concerns and business rules.
+---
+
+# Data Access Discipline
+
+Use this skill when adding tables, queries, migrations, persistence helpers, cross-entity writes, or scope or tenant enforcement.
+
+## Use When
+
+- Adding or changing schema
+- Writing new queries
+- Adding persistence helpers or repository modules
+- Adding cross-table workflows
+- Reviewing DB access placement
+- Tightening scope or tenant rules
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md`
+- Architecture and data docs in this repo (for example `docs/architecture.md`, `docs/data-access-patterns.md`, `docs/data-model.md`, `docs/environment.md`)
+- Migration tooling config (for example `alembic.ini`, SQLAlchemy models under `src/`, Django migrations—whatever this repo uses)
+
+## Core Rules
+
+1. Persistence code should be consistent and discoverable.
+2. Business rules should not be buried in route or MCP tool handlers.
+3. Persistence helpers should not quietly own domain policy.
+4. Cross-entity workflows should have a clear orchestration layer (service/module), not ad hoc scripts.
+5. Scope or tenant boundaries should be enforced explicitly.
+6. Schema changes, migrations, and related docs should move together.
+7. Domain-facing shapes should be intentional, not accidental spillover from ORM rows or raw dicts.
+8. **Single source of truth:** Prefer normalized tables and explicit columns for durable state. In-memory aggregates assembled for reads must not be duplicated as parallel persisted blobs unless documented and intentional.
+9. **Multi-write consistency:** When several SQL statements must succeed or fail together, use one outer transaction (`session.begin()`, `async with session.begin()`, or equivalent). Pass the same session/connection into helpers; avoid nested transaction calls that commit independently. Keep slow network or external API calls outside the transaction; persist only after durable inputs are ready.
+
+## Workflow
+
+1. Identify whether the task is schema, query, migration, or workflow related.
+2. Place query or persistence logic in the repo’s established pattern.
+3. Keep cross-entity business logic out of thin repository functions.
+4. Review whether scope and ownership enforcement are explicit.
+5. Update migrations, docs, and tests as needed.
+
+## Common Failure Modes
+
+- raw SQL or ORM calls scattered unpredictably
+- MCP handlers or FastAPI routes directly owning DB logic
+- hidden cross-tenant reads or writes
+- business rules implemented implicitly in query code
+- schema changes without migration or documentation updates
+- leaking ORM instances or untyped dicts into higher layers without intent
+- multiple commits for one logical unit of work
+
+## Completion Standard
+
+The data-access change follows the repo’s pattern, respects scope boundaries, keeps business logic in the right place, and remains easy to reason about.

mcp_server_for_ynab-0.1.0/.agents/skills/docs-honesty/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: docs-honesty
+description: Keep repo documentation aligned with implementation reality and prevent overclaiming.
+---
+
+# Docs Honesty
+
+Use this skill when changing documentation or when code changes affect documented behavior.
+
+## Use When
+
+- Updating README
+- Updating architecture docs
+- Updating current-state docs
+- Adding or modifying workflows
+- Changing behavior that docs describe
+- Reviewing whether docs still match implementation
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md`
+- Relevant architecture docs in this repo (for example `docs/architecture.md`, `docs/system-design.md`, `docs/current-state.md`)
+- `CONTRIBUTING.md` (if maintained)
+
+## Core Rules
+
+1. Distinguish implemented vs deferred vs conceptual.
+2. Do not present future-state thinking as current-state reality.
+3. If behavior changed materially, update the matching docs in the same task.
+4. If a documented flow or relationship changed materially, update the matching diagram (for example Mermaid) in the same task when the repo uses diagrams for that flow.
+5. Prefer blunt accuracy over polished ambiguity.
+6. If something is partial, say it is partial.
+7. If something is unknown, mark it as unknown.
+
+## Workflow
+
+1. Inspect the code or behavior being changed.
+2. Identify which docs claim or imply behavior in that area.
+3. Update the docs so they match actual implementation.
+4. Check whether a diagram should be added or updated.
+5. Re-read for overstatement, stale claims, and future-state leakage.
+
+## Common Failure Modes
+
+- README implies the system is more complete than it is
+- architecture docs describe intended design instead of implemented behavior
+- current-state doc is stale
+- diagrams describe old flows
+- partial systems are described as complete
+
+## Completion Standard
+
+The relevant docs accurately describe the current implementation and clearly label deferred or conceptual work.

mcp_server_for_ynab-0.1.0/.agents/skills/hardening-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: hardening-review
+description: Review completed work for edge cases, drift, missing tests, overstated claims, and signoff readiness.
+---
+
+# Hardening Review
+
+Use this skill when reviewing a completed feature, workflow, or integration for quality and signoff readiness in this **Python** repository.
+
+## Use When
+
+- Reviewing another agent’s work
+- Preparing for merge
+- Auditing a feature or phase
+- Checking whether implementation is truly complete
+- Looking for edge cases and drift
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md` and `pyproject.toml`
+- Relevant architecture docs and tests under `tests/`
+- Contract or MCP tool schema docs, if present
+
+## Core Rules
+
+1. “Works on the happy path” is not enough.
+2. Docs honesty is part of completion.
+3. Missing or weak tests (`pytest`) are a real issue, not a footnote.
+4. Scope, auth, or boundary mistakes are high severity (wrong budget, leaked tokens in logs).
+5. Generated artifact drift (OpenAPI, schemas) matters when the repo uses codegen.
+6. Overclaiming implementation is a bug.
+7. Review should prioritize bugs, regressions, and risks before summaries.
+8. Run or verify `pytest`, `ruff`, `mypy`/`pyright`—whatever this repo’s CI uses—when judging signoff.
+
+## Workflow
+
+1. Identify the implemented scope.
+2. Check the actual code path, not just the claimed behavior.
+3. Review unhappy paths and partial-data behavior (API errors, empty lists, invalid ids).
+4. Check docs and contract alignment (README, tool descriptions, Pydantic models).
+5. Check tests for real proof, not only heavy mocking of the code under test.
+6. Report findings ordered by severity.
+7. State clearly whether the work is signoff-ready.
+
+## Common Failure Modes
+
+- unit tests exist but MCP tools or integrations are untested
+- docs still describe old or aspirational behavior
+- env vars or secrets handling is unclear or unsafe
+- generated artifacts drift from Pydantic/OpenAPI source
+- incomplete feature presented as complete
+- type hints lie about optional vs required fields
+
+## Completion Standard
+
+The work has been checked for implementation reality, unhappy paths, docs honesty, contract alignment, and verification depth, and is clearly judged ready or not ready for signoff.

mcp_server_for_ynab-0.1.0/.agents/skills/live-api-verification/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: live-api-verification
+description: Verify response models and MCP transports against the real YNAB API before claiming a tool works.
+---
+
+# Live API Verification
+
+Use this skill whenever a change touches how a YNAB response is parsed, or how
+an agent connects to the server. The test suite cannot catch drift between a
+response model and the real API, because every payload in it was written by
+hand: the model and the fixture are the same guess.
+
+## Use When
+
+- Adding or editing a model under `src/mcp_server_for_ynab/models/ynab/`
+- Adding a raw tool or a `ynab_client` wrapper for a new route
+- Upgrading the `mcp` SDK, or changing transport/CLI startup
+- Reviewing a claim that a tool "works" when only unit tests were run
+- Investigating a tool that fails in a client but passes in CI
+
+## The Failures This Prevents
+
+The money movement models were written by analogy with transactions. They
+required `date` on a movement and `name`/`amount` on a group. The real API
+sends none of those — it sends `month`, `moved_at`, and category endpoints.
+All four money movement tools failed at validation on every call, while the
+suite passed, because no test used a real payload and no test touched the
+family at all.
+
+Two properties made this invisible:
+
+1. Hand-written fixtures agree with the model by construction.
+2. The tool boundary returns failures as a structured error payload with
+   `isError: False`, so a caller that only checks the MCP result looks fine.
+
+The write tools failed four more ways, each invisible to the same suite:
+
+- `category-groups` in the path where the API wants `category_groups`, so YNAB
+  answered "Invalid URI" for create and update alike
+- `categories_create` could not send `category_group_id`, which the API
+  requires, so no category could ever be created
+- the bulk update model expected `data.bulk`, a shape this route does not
+  return, so the write succeeded and the response failed to parse
+- the group create and update routes return a group without its `categories`,
+  which the response model required
+
+None of these are visible from the request side. Three of the four failed
+*after* YNAB had already accepted the write.
+
+## Rules
+
+1. Never infer a response shape from a sibling resource. Fetch the endpoint and
+   read what it actually returns.
+2. Record fixtures from a live response and replace the identifiers. Do not
+   write fixture payloads from the model definition.
+3. Profile every record in the response before setting a field required, not
+   just the first one. A field that is non-null in record 1 and null in record
+   40 makes a required field a guaranteed failure.
+4. A tool is not verified until it has been invoked against the live API. Green
+   unit tests are not evidence that a tool works.
+5. When parsing fails, check whether the error is reported as a tool error or
+   hidden in a success envelope, and say which in the report.
+6. Accepted is not applied. YNAB takes `budgeted` on the category update route
+   and ignores it, returning 200 and a `budgeted` of 0. After any write sweep,
+   read the plan back and confirm the values actually changed.
+7. Check both directions of a route pair. A resource's create response is
+   frequently a different shape from its list response — usually thinner, as
+   with a category group returned without its categories.
+
+## Workflow
+
+```bash
+# 1. See what the endpoint really returns, across all records.
+curl -s -H "Authorization: Bearer $YNAB_API_KEY" \
+  "https://api.ynab.com/v1/budgets/$YNAB_PLAN_ID/<resource>" | python3 -c "
+import json, sys, collections
+data = json.load(sys.stdin)['data']
+key = [k for k in data if isinstance(data[k], list)][0]
+records = data[key]
+types = collections.defaultdict(collections.Counter)
+for record in records:
+    for field, value in record.items():
+        types[field][type(value).__name__] += 1
+print(f'{len(records)} records')
+for field, counts in types.items():
+    print(f'  {field:28} {dict(counts)}')
+"
+
+# 2. Make the change, then verify.
+make test
+make verify-live                   # every read-only tool against the live API
+make verify-write PLAN_ID=<uuid>   # every write tool, against a disposable plan
+make verify-mcp-http               # the MCP handshake an agent performs
+
+# 3. For writes, read the plan back and confirm the values changed.
+```
+
+A field whose type counter shows `NoneType` for any record is optional.
+
+Never point `verify-write` at a real budget. It takes an explicit plan id, never
+falls back to `YNAB_PLAN_ID`, and refuses plans whose name does not look
+disposable. Keep those guards if you extend it.
+
+## Reporting
+
+State what was actually run. "39 read tools invoked live, 0 failures" is a
+verification claim; "tests pass" is not. If a tool was skipped because the plan
+has no such record, say so rather than counting it as passing.
+
+## Related Skills
+
+- `contract-sync` — keeping generated artifacts aligned with the source of truth
+- `docs-honesty` — keeping claims in docs matched to implementation

mcp_server_for_ynab-0.1.0/.agents/skills/local-workflow-reproducibility/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: local-workflow-reproducibility
+description: Turn repeated local setup, seed, and manual-test workflows into safe, documented, repeatable scripts.
+---
+
+# Local Workflow Reproducibility
+
+Use this skill when local development or manual testing depends on repeated setup, seed, reset, fixture, or scenario-loading steps.
+
+## Use When
+
+- local setup is repetitive or error-prone
+- realistic test state requires many manual steps
+- developers are copying IDs, tokens, or env values between tools
+- manual testing depends on exact ordering
+- seed or reset flows need guardrails
+
+## Read First
+
+- `AGENTS.md` (if present)
+- `README.md` and `pyproject.toml` (scripts, optional groups, entry points)
+- `Makefile` or `scripts/` if present
+- Environment docs (for example `docs/environment.md`, `.env.example`)
+- Existing fixtures under `tests/`, `scripts/`, or `tools/`
+
+## Core Rules
+
+1. Repeated workflows should become scripts or documented commands, not tribal knowledge.
+2. Destructive reset flows should be explicit and guarded (confirm DB name, env file, or `--dry-run` where appropriate).
+3. Scenario data should be intentional and named.
+4. Local workflows should prefer exercising real app code paths where practical (run the MCP server, call tools via inspector/CLI).
+5. Docs should explain how to reset, seed, and test locally—including required env vars (for example YNAB API tokens) without committing secrets.
+6. Use a virtual environment (`uv`, `venv`, `poetry`) consistently; document the canonical install and run commands.
+
+## Workflow
+
+1. Identify repeated manual setup pain.
+2. Decide whether it needs reset, load, list, or verify commands.
+3. Script the workflow with safety checks (Python CLI, `make` targets, or shell wrappers that call `python -m ...`).
+4. Document the command surface and expected state.
+5. Add or update `pytest` fixtures or seed data as the model evolves.
+
+## Common Failure Modes
+
+- manual setup requires many fragile steps
+- resets can accidentally target the wrong environment
+- scenarios drift from current schema or tool contracts
+- docs list workflows that no longer work
+- secrets committed or assumed in docs
+- “works on my machine” without pinned deps in `pyproject.toml` / lockfile
+
+## Completion Standard
+
+The repeated local workflow is safe, repeatable, discoverable, and documented well enough that future humans and agents can use it without tribal knowledge.

mcp_server_for_ynab-0.1.0/.agents/skills/postman-standards/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: postman-standards
+description: Keep Postman collections complete and aligned with API contracts when this repo documents HTTP testing with Postman or Newman.
+---
+
+# Postman standards
+
+**Scope:** Use this skill only if this repo maintains Postman/Newman collections or an HTTP API. Many MCP-only Python repos do not—skip this skill if there is no `postman/` or documented HTTP operator workflow.
+
+Use when editing Postman surfaces or HTTP routes and you need collections to stay a high-quality operator and integration-testing surface.
+
+## Use when
+
+- This repo exposes HTTP endpoints (FastAPI, etc.) with Postman collections
+- Changing request or response shapes or route behavior
+- Updating Postman examples, naming, variables, or tests
+- Adding or updating OpenAPI- or script-generated Postman artifacts
+
+## Read first
+
+- `AGENTS.md` (if present)
+- `README.md` and `pyproject.toml` (generation scripts, if any)
+- `.agents/skills/contract-sync/SKILL.md`
+- OpenAPI or contract docs in this repo
+
+## Core rules
+
+1. **Source of truth**: contracts live in hand-authored Python (Pydantic models, route handlers, tests). OpenAPI and generated Postman collections are derived unless the repo documents otherwise.
+   - Do not hand-edit generated OpenAPI or collection JSON; regenerate using commands in `pyproject.toml`, `Makefile`, or repo docs.
+2. **Variable contract (inputs equal outputs)**:
+   - Path params must use the OpenAPI parameter name as the Postman variable name.
+   - Post-scripts that capture ids must write to the same canonical keys the collection documents.
+3. **Every request needs a description** with: `Purpose:`, `Auth:`, `Reads:`, `Writes:`, `Assumptions:`, `Side Effects:`, `Downstream:`, `Notes:`.
+4. **Variables**: `{{baseUrl}}` in environment; collection variables for workflow ids; never hardcode tokens or production ids.
+5. **Body examples**: happy path, minimal payload, and a common edge case where applicable.
+6. **Post-script tests**: assert status and stable fields; avoid brittle full-body string matches on dynamic content.
+
+## Postman runtime note
+
+Postman and Newman run **JavaScript** in the sandbox, not Python from this repo. Shared logic belongs in repo templates injected at generation time—not imported Python modules.
+
+Use `postmanDebug=true` on the collection or environment to gate verbose script logs.
+
+## Completion standard
+
+An operator can run the collection end to end for the implemented subset with minimal guessing: clear descriptions, runnable examples, and tests that capture ids for chained requests.