Repository navigation
Wayfinder: Finance Guru becomes a Claude Code + Codex plugin #131
Description
Planning artifact for converting this repo, in place, into an installable agent plugin. The repo keeps its traction; the owner's private instance data leaves it entirely.
Decisions (locked 2026-08-31)
- Open-core line: everything open. All skills, agents, and the Python engine ship free under the existing AGPL-3.0. The commercial layer is convenience, never withheld features. AGPL already prevents proprietary forks.
- Keepfolio relationship: the plugin is the funnel. Finance Guru is the free, self-hosted, CLI-native experience; Keepfolio is the polished product for people who will not run a terminal. The README says so explicitly.
- Connectivity: CSV-first. v1 works on day one with broker CSV exports. SnapTrade/SimpleFIN live sync stays in the plugin as documented bring-your-own-credentials for power users. No paid-API wall in the first hour.
- First user: technical operators already running Claude Code or Codex. Onboarding may assume CLI comfort, uv, and API-key literacy.
Phases
- P1 — Privacy foundation. DONE. Layer-7 financial-figure scanner, history-scope push gate, fail-closed baseline, DataClassification policy, tree scrub (fix(simplefin): correct sync direction, payroll and retirement categorization, and close the privacy gate that missed them #128, chore(privacy): rewrite standing financial figures as ratios per DataClassification #129). Remaining standing findings tracked in chore(privacy): clear remaining layer-7 standing findings on main #130.
- P2 — Instance exfiltration. Untrack the remaining instance artifacts (the tracked
fin-guru-private/strategies/script,.memory/note,.dev/meeting-notes/), introduce a configurable data root (env override, CWD default) so the engine reads profile/DB/strategies from outside the repo, and scaffold the owner's local-only instance directory (local git, no remote). Owner sessions move to the instance; this repo stops being anyone's working residence. - P3 — Plugin packaging.
.claude-pluginmanifest plus the Codex surface using the proven shared-tree + platform-dispatch pattern (as in pstack). Capability probes for the six skills and six agent definitions that currently hard-require personal paid MCPs (exa, bright-data, perplexity, financial-datasets): degrade to WebSearch or state what is missing, never fail silently. Onboarding skill scaffolds a user instance (profile template, DB init, CSV import walkthrough). Marketplace entry. - P4 — Repositioning. README rewritten for installers rather than the owner (including the Keepfolio funnel line), BYO-credentials guide for live sync, contributor guide pointing at DataClassification, close out chore(privacy): clear remaining layer-7 standing findings on main #130.
Each phase lands as its own reviewed PR train through the layer-7/history push gates. No commit in any phase may contain household data; the gates enforce it.
Initiative memory: kp-b71f778eef854cbbac9eb2f981c870e1.
Activity
linear-code commentedon Sep 1, 2026
AOJ-1194
AojdevStudio commentedon Sep 1, 2026
P2 plan (2026-09-01)
One PR per unit. Each passes the layer-7 and history push gates on its own.
.memorynote, and.dev/meeting-notes. Ignore rules added.InstancePathsmodel insrc/config/instance_paths.pyowns every private path, resolved fromFIN_GURU_DATA_ROOTwith cwd as the default. Legacy per-file env overrides (FIN_GURU_PRIVATE_DIR,FIN_GURU_HEDGING_DIR,FIN_GURU_DIVIDEND_SCHEDULES,FIN_GURU_PORTFOLIO_DIR) are deleted with their callers migrated.DATABASE_URLstays optional and defaults tofamily_office.dbunder the root..envloads from the root.pyproject.tomlgains a build system sosrcimports from any cwd viauv run --project.python -m src...so they run with the instance as cwd. Done with a codemod; its mapping table is in the PR body.src/cli/instance_init.pyscaffolds a local-only instance (layout,git init,.gitignore,.envtemplate,CLAUDE.md) idempotently, plus a runbook for moving the owner's existing data.uv run python -m src.<tool>works from the instance with no flagsInstance layout (decided)
Flat. The instance root holds
.env,user-profile.yaml,config.yaml,system-context.md,family_office.db,dividend-schedules.yaml, and the directoriesimports/(broker CSV drops, wasnotebooks/updates),analysis/,tickets/,strategies/,hedging/,reports/,auto-tickets/,notes/. Thefin-guru-private/fin-guru/...nesting and the three competing profile locations go away. The repo-relative layout only ever existed because the data lived inside the checkout.Findings while grounding
srcis not importable from outside the checkout today. A hatchling build section fixes it, verified from a scratch cwd on 2026-09-01.scripts/qa/pii-replacements.txtis missing and falls back to the template, so repo-specific literals are not detected locally. Worth restoring from BWS before P2-C's large sweep.Scope note
"Owner sessions move to the instance" needs the skills to invoke the engine with the instance as cwd. P2-C gives them that form. The onboarding wizard still writes its private files under the repo; P2-D's scaffold replaces that path for the owner, and the wizard's rewrite belongs to P3's onboarding skill.
Proposed owner instance path:
~/Documents/Irondi-Household/family-office-data, local git, no remote.Merge order: #132, #133, #134, #135. The Python CI workflows trigger against
mainonly, so #134 and #135 get their lint-and-test run when each retargets after its parent merges; the full suite passed locally on both heads. The owner's data migration (runbook in #135) runs only after #135 merges.feat(config): read the SnapTrade routing file from the instance root
feat(instance): scaffold a local-only instance directory
fix(config): harden InstancePaths after review
feat(config): resolve every private path from one instance data root (#…
docs(skills): point every skill, agent, and task at the instance layout
feat(instance): scaffold a local-only instance directory
chore(privacy): untrack the last three instance artifacts (#132)
docs(skills): fix the sweep's leftovers from review
docs(engine): module-form help text, instance-relative task paths
feat(instance): make the instance a uv project that depends on the en…
docs(skills): point every skill, agent, and task at the instance layo…
feat(instance): scaffold a local-only instance directory
feat(instance): make the instance a uv project that depends on the en…
3 remaining items
fix(deps): cap the SnapTrade SDK below 12
docs(wiki): ledger rows for the instance data root claims
AojdevStudio commentedon Sep 2, 2026
P3 and P4 in review (2026-09-02)
Run as a multi-model program from one coordinator. Landed since the P2 comment: #138 (progress-persistence flake, Opus lane) and #140 (instance_init git-environment fix, codex lane). The owner's data migration ran; the checkout holds no private files and the dashboard agent serves from the instance.
Open, all against main:
Owner gates: push the Wiki, enable Pages after #147, restore
scripts/qa/pii-replacements.txt. Follow-ups filed: #139 (atomic persistence writes).docs: reposition the README and setup guides for installers (#146)
feat(plugin): package Finance Guru as a Claude Code plugin with a Cod…
fix(deps): cap the SnapTrade SDK below 12 (#142)
docs(site): add the Diátaxis documentation site on the AOJ Starlight …
fix(instance): refuse a root with a git remote and normalize empty en…
fix(instance): scrub placeholder env values and run chart tools as mo…
docs(wiki): ledger rows for the instance data root claims (#143)
AojdevStudio commentedon Sep 2, 2026
P3 and P4 landed (2026-09-02)
All program units merged, in order: #138, #140, #144, #145, #146, #141, #142, #147, #149, #143. Issues #130 and #137 closed by their PRs. Main is at f512ee4.
What is on main now beyond P2: the plugin and marketplace manifests (
finance-guru2.3.0), the shared paid-MCP capability probe wired into six skills and six agents, theinstance-onboardingskill, the Codex surface through the instance's.agentslink, the README and setup guides for installers, the credentials and contributor guides, the Diátaxis site underdocs-site/with its Pages workflow, the SnapTrade SDK pin, the initializer hardened against inherited git environments and roots with remotes, chart tools running as modules from an instance, and the closed scanner findings.Owner gates, parked in the program store:
~/finance-guru-wikiwith no push made.docs-site/on the.github/workflows/docs.ymlworkflow.fg-*agents and theinstance-onboardingskill;plugin detailscounts zero agents headlessly because they live under.claude/agents.scripts/qa/pii-replacements.txton the MacBook.Open follow-ups: #139 (atomic persistence writes), #148 (Dependabot on the docs site's npm dependencies). The remaining phase-P4 item, closing this Wayfinder, waits on the gates above.
AojdevStudio commentedon Sep 2, 2026
Reopened. GitHub auto-closed this when the v2.3.0 release commit (#164) landed, because its changelog carried the 'closes #131' reference from #145. The plugin packaging shipped in 2.3.0, but this wayfinder tracks the plugin becoming the primary install path, which the README roadmap still lists as open. Keeping it on the roadmap label.