Wayfinder: Finance Guru becomes a Claude Code + Codex plugin

[AojdevStudio]

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)

1. 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.
2. 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.
3. 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.
4. 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-plugin manifest 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.

[linear-code]

AOJ-1194

[AojdevStudio]

P2 plan (2026-09-01)

One PR per unit. Each passes the layer-7 and history push gates on its own.

PR	Change	State
P2-A	Untrack the strategies script, the .memory note, and .dev/meeting-notes. Ignore rules added.	#132 merged (8d441f8)
P2-B	One InstancePaths model in src/config/instance_paths.py owns every private path, resolved from FIN_GURU_DATA_ROOT with 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_URL stays optional and defaults to family_office.db under the root. .env loads from the root. pyproject.toml gains a build system so src imports from any cwd via uv run --project.	#133 merged (c70d05b)
P2-C	Prose sweep. Skills, agents, tasks, workflows, and the fin-core session hook point at the instance layout and invoke tools as python -m src... so they run with the instance as cwd. Done with a codemod; its mapping table is in the PR body.	#134 closed by GitHub when its base was deleted; continued as #136, merged (d0515b1). 17 review threads triaged; pre-existing doc bugs tracked in #137
P2-D	src/cli/instance_init.py scaffolds a local-only instance (layout, git init, .gitignore, .env template, CLAUDE.md) idempotently, plus a runbook for moving the owner's existing data.	#135 open against main, rebased; now also makes the instance a uv project depending on the engine, so uv run python -m src.<tool> works from the instance with no flags

Instance layout (decided)

Flat. The instance root holds .env, user-profile.yaml, config.yaml, system-context.md, family_office.db, dividend-schedules.yaml, and the directories imports/ (broker CSV drops, was notebooks/updates), analysis/, tickets/, strategies/, hedging/, reports/, auto-tickets/, notes/. The fin-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

• The history gate scans added lines only, so untracking passes without a rewrite. Old blobs stay in history; that decision belongs with chore(privacy): clear remaining layer-7 standing findings on main #130.
• src is not importable from outside the checkout today. A hatchling build section fixes it, verified from a scratch cwd on 2026-09-01.
• The engine currently searches three different profile paths and the session hook reads a fourth. None of the private ones exist on disk. P2-B collapses them to one.
• The scanner on this machine warns that scripts/qa/pii-replacements.txt is 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 main only, 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.