flowstate-finance-core Package Skill

Package: @epicdm/flowstate-finance-core Repository: epic-flowstate-community Path: packages/flowstate-finance-core Version: 0.1.7

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Finance Core Maintenance

Purpose

Use this skill when changing the finance-core package boundary or keeping documentation, package-local skills, feature matrix records, and Dojo artifacts aligned with source code.

Read First

• packages/flowstate-finance-core/src/index.ts
• packages/flowstate-finance-core/README.md
• packages/flowstate-finance-core/CHANGELOG.md
• packages/flowstate-finance-core/.flowstate/feature-matrix/
• packages/flowstate-finance-core/.flowstate/dojo/
• packages/flowstate-finance-core/.flowstate/skills/
• packages/flowstate-mcp/src/tools/FinanceTools.ts

Maintenance Checklist

When changing public behavior:

1. Update source and tests first.
2. Export new public functions/types from src/index.ts.
3. Check downstream MCP wrappers in flowstate-mcp.
4. Update README and CHANGELOG if the workflow or public surface changed.
5. Update package-local .flowstate/skills if an agent workflow changed.
6. Rebuild package-local Dojo content from reviewed skills before publishing.
7. Update feature inventory/status artifacts if feature coverage changed.

Known Drift

• README still frames posting, mapping, schema seeding, and batch orchestration as future work. Current source implements and tests those workflows.
• Existing .flowstate/dojo artifacts are generated prototypes. They incorrectly state that no query-like public methods and no test behavior names were detected.
• Generated Dojo artifacts over-list one-function skilllets instead of teaching workflows.
• Publisher metadata differs across Dojo artifacts.

Do not publish these generated Dojo artifacts as-is. Rebuild from reviewed local skills and course material.

Export Hygiene

For any new public function or type:

• Add it to src/index.ts.
• Confirm package build emits declarations.
• Check whether flowstate-mcp should expose it as a tool.
• Add tests at the package layer before adding downstream tool tests.

For internal helpers:

• Keep helpers unexported unless downstream packages need them.
• Prefer testing through public workflows when possible.

Verification

Run package gates:

yarn workspace @epicdm/flowstate-finance-core test
yarn workspace @epicdm/flowstate-finance-core typecheck
yarn workspace @epicdm/flowstate-finance-core build
yarn workspace @epicdm/flowstate-finance-core lint
yarn nx build @epicdm/flowstate-finance-core

Run downstream checks when exports or MCP behavior changed:

yarn workspace @epicdm/flowstate-mcp typecheck
yarn nx test @epicdm/flowstate-mcp --passWithNoTests

Record known warnings separately from failures. Existing lint warnings are not a reason to weaken the skill content.

Package Skill Inventory

@epicdm/flowstate-finance-core Skill Inventory

Skill Set

Design Notes

This package needs workflow skills rather than one skill per exported function. Most defects would come from breaking accounting invariants across modules: posting, mapping, schema setup, and reports depend on the same collection names, source ids, org/workspace scoping, and journal-entry contracts.

Each skill names the source files to read first, concrete commands to run, and the verification evidence agents should capture before changing downstream Dojo content.

Not Included

• Test fixtures are not taught as runtime APIs.
• Generated .flowstate/dojo skilllets are not reused directly because they contain stale and misleading statements.
• The skills avoid publishing instructions until package-local review passes and the Dojo content is rebuilt from these reviewed skills.

Review Gate

@epicdm/flowstate-finance-core Skills Review

Verdict

Pass with tracked follow-ups.

The authored skills are source-backed and workflow-oriented. They teach agents how the finance package is used in practice instead of listing individual features.

Coverage

• Posting engine: covered from post-batch.ts, posting helpers, idempotency, source hash, transfer-pair logic, subtransaction expansion, and journal write shape.
• Mapping and schemas: covered from schema definitions, schema seeding, mapping seeding, resolver, Suspense lifecycle, and YNAB type derivation.
• Reports: covered from report types, aggregate wrapper, filter/date helpers, mode checks, and report builders.
• Queries/actions: covered from query builders, manual journal-entry actions, voiding, reconciliation, close period, and explicit mapping updates.
• Maintenance: covered for public export hygiene, downstream flowstate-mcp wrapper checks, README/Dojo drift, and verification commands.

Follow-Ups

• Rebuild package-local .flowstate/dojo course and skill manifests from the reviewed skills before publishing.
• Update README.md to stop describing implemented posting/mapping/schema/report phases as future work.
• Keep flowstate-mcp finance tool wrappers synchronized when adding, renaming, or changing exported finance-core functions.
• Track existing lint warnings separately from skill quality.

Verification Results

LC_ALL=C rg -n "[^\\x00-\\x7F]" packages/flowstate-finance-core/.flowstate/skills
rg -n "^name:|^description:" packages/flowstate-finance-core/.flowstate/skills
yarn workspace @epicdm/flowstate-finance-core test
yarn workspace @epicdm/flowstate-finance-core typecheck
yarn workspace @epicdm/flowstate-finance-core build
yarn workspace @epicdm/flowstate-finance-core lint
yarn nx build @epicdm/flowstate-finance-core

Results:

• ASCII scan passed with no non-ASCII matches.
• Frontmatter scan found name and description on all six skills.
• typecheck passed.
• build passed and emitted CJS, ESM, and DTS outputs.
• test passed: 40 passed suites, 2 skipped suites, 334 passed tests, 29 skipped tests, 363 total tests.
• lint passed with 84 existing @typescript-eslint/no-non-null-assertion warnings.
• yarn nx build @epicdm/flowstate-finance-core passed. Nx Cloud reported the existing unconnected-workspace 401 warning.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/flowstate-finance-core/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.