OpenForge

Imported from wolney8/OpenForge (AGENTS.md). Install upstream with npx skills add wolney8/OpenForge. Copyright stays with the author.

Plum Duff Repository Agent Instructions

Last updated: 2026-08-16

Project purpose

Plum Duff is the user-facing platform developed in the OpenForge repository. It is a local-first reconstruction of the user's matched betting tracker workbook.

The workbook is the architectural blueprint. The first goal is to mirror and improve the current tracker workflow, calculations, documentation, and reporting without drifting into a generic betting app.

Product direction

• Build the Plum Duff Tracker first.
• Treat Oddsmatcher as a later, explicitly deferred module for odds matching or opportunity finding.
• Do not plan, design in detail, or implement Oddsmatcher unless a later task explicitly approves that scope.

Route priority

The intended first application shell is:

/login -> /profiles -> /profiles/:profileId/tracker

Required initial route model to preserve in planning:

• /login
• /profiles
• /profiles/new
• /profiles/:profileId
• /profiles/:profileId/tracker
• /profiles/:profileId/tracker/dashboard
• /profiles/:profileId/tracker/accounts
• /profiles/:profileId/tracker/sportsbook-bets
• /profiles/:profileId/tracker/free-bets
• /profiles/:profileId/tracker/casino-offers
• /profiles/:profileId/tracker/cash-adjustments
• /profiles/:profileId/tracker/reports
• /profiles/:profileId/tracker/profit-tracker

Local-first rule

• Assume local development first.
• Prefer local/demo authentication for MVP.
• Do not design hosted SaaS authentication, public sign-up, cloud sync, or production multi-tenant hosting unless explicitly approved.
• Each subscriber/profile must still be modelled as isolated data even in a single-user local MVP.

Spreadsheet-as-blueprint rule

• Treat the current tracker workbook and current tracker-only source pack as the source of truth.
• Current source-pack files in _input/, docs/planning/, and docs/templates/ override older archived references.
• Do not replace spreadsheet workflow with generic CRUD screens or generic matched-betting conventions.
• Preserve sheet intent, workflow order, user-entered fields, calculated fields, reporting logic, and audit concepts.

Profile-scoped tracker rule

• Plum Duff is a profile-based platform with a Fund Manager overview and isolated subscriber/profile trackers.
• The Fund Manager overview is an aggregate control screen, not a replacement for the detailed tracker.
• Every profile-owned tracker record must be isolated, usually by profile_id.
• No profile may see another profile's accounts, bets, balances, reports, notes, or derived metrics.

Authentication and authorization rule

• Authentication proves identity; it does not grant a role. Fund Manager access requires a server-validated session plus explicit owner authorization.
• Protect browser routes and API reads/mutations independently. Client-side hiding is never an authorization boundary, and search results must be filtered by the same server-side authority.

Cash-first tracker calculation rule

Plum Duff must preserve the workbook's cash-first principle:

What is this row worth to the bankroll right now?

Required implications:

• Keep projected/current value separate from settled/final value.
• Preserve conservative current-value behaviour, including MIN()-style scenario selection where the workbook uses it.
• Keep calculator/reference values separate from actual user-entered values.
• Keep manual overrides explicit, reasoned, and auditable.
• Do not flatten tracker logic into a standard equal-profit matched betting calculator.

Financial safety rules

• No calculation without a calculation contract.
• No deterministic money logic without deterministic fixtures.
• No user-visible financial value without tests.
• No hidden assumptions.
• No silent rounding.
• No silent commission defaults.
• No silent liability or exposure inference.
• No human-facing balance, P&L, bankroll, exposure, deduction, or earnings number without traceable source logic.

Read docs/codex/financial-safety-rules.md before planning or changing money logic.

Sensitive-data rules

• Treat the uploaded workbook and any extracted tracker data as sensitive.
• Never copy real personal or operational data into docs, fixtures, examples, tests, or commits.
• Use synthetic placeholders such as USER-001, demo@example.invalid, Bookmaker A, Exchange A, Demo Offer, and DEMO-CODE-001.
• Do not store full card numbers, bank login credentials, bookmaker passwords, exchange passwords, session cookies, or MFA secrets.
• Do not commit raw workbook exports, screenshots, or dumps unless explicitly approved.

Read docs/codex/data-safety-rules.md before handling workbook-derived data.

No-bet-automation rule

• Do not create autonomous bookmaker or exchange bet placement.
• Do not auto-confirm bets.
• Do not automate wager execution.
• Do not store the secrets that would enable bet automation.

No-live-scraping rule

• Do not implement live bookmaker scraping.
• Do not build unsafe browser automation against third-party betting platforms.
• Do not create session replay, cookie capture, or scraping workflows unless explicitly approved in a later scoped task.

Calculation contract rule

• Any new or changed financial calculation must have a contract first.
• Use docs/templates/calculation-contract.md.
• If a contract conflicts with the current workbook source pack, stop and surface the contradiction.
• When the user introduces a new feature idea, workflow, ledger, calculator, or operational rule, record it in the appropriate contract, fixture spec, planning note, and GitHub issue coverage before treating it as durable roadmap scope.

Fixture rule

• Every money-impacting workflow needs deterministic fixtures before implementation is considered complete.
• Fixtures must be synthetic or anonymised only.
• Include open/pending, settled, cancelled/void, and manual-override examples where relevant.

Testing rule

• User-visible financial values require automated tests.
• Profile isolation requires automated tests.
• Import mapping and reporting logic require fixtures and assertions.
• If exact tolerances or rounding are unknown, stop and document the gap instead of guessing.

Playwright rule

• UI-facing workflows must define a Playwright path before implementation is considered done.
• Playwright coverage is required for route flows such as login, profile selection, tracker navigation, and critical data-entry/reporting paths once those surfaces exist.
• Do not save Playwright videos, screenshots, or traces by default unless approval or troubleshooting requires them.

Mandatory UI and accessibility contract

Before implementing or modifying any UI, read and follow:

• docs/agent-contracts/plum-duff-ui-accessibility-contract.md
• docs/agent-contracts/plum-duff-ui-implementation-checklist.md
• docs/agent-contracts/plum-duff-known-ui-pitfalls.md
• docs/agent-contracts/plum-duff-ledger-modal-parity-contract.md
• .skills/plum-duff-ui-review/SKILL.md
• .skills/plum-duff-ui-consistency-enforcer/SKILL.md

Non-negotiable baseline:

• Material Design 3 principles using existing Plum Duff components, tokens and CSS primitives first
• WCAG 2.2 Level AA
• semantic HTML before ARIA
• light and dark mode verification
• context-specific accessible names and stable data-pd-id identifiers for important controls
• contained table/dialog overflow with no unintended page-level horizontal scroll
• process-correct enabled, disabled, loading, error and success states
• repository-wide equivalent-pattern search whenever a UI pattern is fixed
• ledger add/edit modal parity across Sportsbook, Free Bets, Casino Offers, Cash Adjustments and future ledgers
• shared action semantics: positive/create actions use the green positive action token, destructive actions use the red Material delete icon, close actions use the red Material close icon, and neighbouring icons/buttons must match size, padding and centre alignment

Complete the implementation checklist for every feature, bug fix, route, component, workflow or fixture-backed UI change. Larger existing issues belong in docs/agent-contracts/plum-duff-ui-audit-backlog.md; do not hide them or perform an unsafe visual rewrite.

The consistency-enforcer skill is a fail-closed handoff gate. An agent must compare changed UI against established Plum Duff equivalents and provide automated geometry, overflow, action/icon, theme and accessibility evidence before asking the user to smoke test it. Unverified UI work must be reported as incomplete, not handed to the user to discover basic consistency defects.

Reuse before creation is mandatory. For every changed panel, toolbar, modal, table, action, field, chip or icon, identify the nearest signed-off Plum Duff equivalent and reuse its component, class, tokens, geometry and behaviour. Do not introduce or rename a variant unless the existing semantics genuinely do not fit and the exception is recorded before implementation. The signed-off application is the visual source of truth when older documentation differs, unless the current request explicitly approves a redesign.

Task cadence

Use the workflow in docs/codex/task-cadence.md.

Lean working cadence: read only the instructions and source relevant to the active task; reuse accepted evidence for unchanged code; then reproduce, make the smallest correct fix, run focused regressions, and commit/push the isolated change. Expand investigation or testing only when a changed dependency or observed failure justifies it.

Short version:

1. Restate the objective.
2. Identify relevant files.
3. Identify risks and assumptions.
4. Propose a short plan.
5. Wait for approval when scope touches architecture, schema, calculations, imports, auth, reporting, or other money-sensitive areas.
6. Implement only approved scope.
7. Run relevant tests.
8. Report changed files and results.
9. Stop for review.

Delivery checkpoint rule

Unless the user explicitly says not to commit/push or not to run local services, every completed implementation tranche must finish with all of the following:

• Git checkpoint: review and isolate the intended diff; commit only intended changes; push to the correct branch; report the commit SHA and push state; explicitly leave unrelated user, private, generated, environment and secret files untouched.
• Local runtime: confirm the repository's required local web/API services are running, restart any stopped service using the canonical development commands, report the final URLs and verify the applicable local health endpoint.
• Hosted state: when a tranche affects Vercel, verify and report whether the new commit is deployed. Never describe hosted behavior as verified when only local tests have run; keep hosted smoke verification as an explicit gate when it still requires the user.

Response style

• Keep responses direct, concise, and forward-looking.
• Do not use a status table unless the user explicitly asks for one.
• In every substantive reply, explicitly note in short:
  • what we are working on now
  • what is on hold if we were sidetracked
  • what happens next
• When useful, include a short completion estimate and GitHub issue reference in prose.
• Avoid long recaps unless the user asks for them.
• Before asking the user to smoke test, provide a brief, concrete checklist with the routes, actions and expected outcomes for the changed workflow.
• When a repo change is made for active work, commit and push promptly so connected deployment workflows can pick it up, unless the user says not to.

Corrective change batches

• Treat every user-supplied list of UX defects, styling corrections, bugs, or adjustments as one tracked batch. Assign every item a stable PD-FIX-### or current register ID and record its area, requested behaviour, supplied selector/reference, signed-off equivalent and status before editing.
• Use NOT STARTED, IN PROGRESS, NEEDS CLARIFICATION, BLOCKED, NEEDS VERIFICATION, or COMPLETE for new batches. Existing historical registers may retain their original status labels. Never silently omit an item. Ask one precise question for NEEDS CLARIFICATION; state the concrete blocker for BLOCKED.
• Mark an item COMPLETE only after implementation, applicable automated checks, and focused nearby/shared-pattern verification. Reconcile every supplied ID in a concise final table.
• Use shared Plum Duff primitives and check all affected equivalents before adding a local CSS correction. Every distinct user-reported defect or request, including minor visual and operational-delivery defects, must have a local ID and verified GitHub issue or checklist link.

Retrospective UI consistency audit

• Maintain a bounded inventory of repeated panels, headings, actions, fields, chips, cards, tables, toolbars, filters, pagination, dialogs, tabs, themes and responsive treatments.
• Assign every mismatch an audit ID, identify its signed-off reference and classify blast radius as LOW, MEDIUM or HIGH. Fix only unambiguous LOW-risk drift in the active scope. Record MEDIUM/HIGH consolidation for review rather than mass-refactoring signed-off UI.
• When a repeated inconsistency is discovered, update the consistency enforcer, known-pitfalls register and focused regression coverage so the rule survives future sessions.

Durable feature parity

• A durable Plum Duff feature is not complete when only UI/code exists. Where applicable, its implementation, contracts/schemas, representative fixtures, tests, documentation and GitHub issue/milestone state must remain consistent.
• Apply this proportionately: a small visual adjustment does not require all artefacts, but a workflow, persisted-data, calculation, public-interface, or domain-rule change does.
• When live GitHub state matters, try an authenticated integration, browser access, securely available API credentials, then gh; only then use a clearly labelled local fallback. Missing gh is not missing GitHub. Never request or print credentials. Record a concise pending-sync note when live mutation is unavailable and reconcile it when access returns.

Durable request capture

• Capture every distinct user idea, defect, and requested outcome in the existing canonical request register before claiming it is tracked. Keep user requirements separate from assistant recommendations, and retain unclear requests provisionally instead of silently omitting them.
• Request capture is not implementation approval. Reuse existing IDs; new identifiers must be product-neutral.
• Do not delete, cancel, archive, supersede, consolidate away, narrow, or close a request without the user's explicit approval. Similar items may be linked, but their original requirements must remain visible.
• Partial delivery leaves remaining scope visible. A recurrence reopens verification without erasing earlier evidence. Report the IDs updated and their actual GitHub sync state in the final receipt.
• Future tasks should start from the project-status entry point and the relevant register items, not by rereading every planning document.

Corrective change cadence

• Treat every user-supplied bug, UX correction, or feature adjustment list as a tracked work batch. Assign a short PD-FIX-* or PD-PR-* identifier, record the affected surface, supplied selector where relevant, requested outcome, and status in an active register before editing.
• Reconcile every identifier before reporting a batch complete. An item is only done after its requested behaviour, relevant tests/checks, and nearby shared-pattern regression check pass. Use NEEDS-INFO or BLOCKED rather than silently skipping unclear or unsafe work.
• Link every distinct request to an open GitHub issue or explicit checklist item whose scope genuinely covers it. Do not hide an unresolved defect behind a closed historical issue or an unrelated umbrella issue.

Branch baseline rule

• Work only in /Users/will_work/Scripts/Homelab/OpenForge. Never edit, create, stage, commit, run formatting against, or otherwise modify files in /Users/will_work/Scripts/Homelab/OpenForge-oddsforge-m8/.
• Treat origin/main as the cumulative source of truth for all completed work.
• Before starting a new issue branch, first update from origin/main and branch from that exact tip.
• Every new branch must be a clean layer on top of the previously merged work.
• After a branch is approved, validate it, merge it back to main, and push main before starting the next issue branch.
• Do not start the next issue from an older feature branch baseline when the same work already exists in main.

Approval gates

Stop for explicit approval before:

• creating or changing application source code
• changing database schema design
• defining or altering financial calculations
• implementing import/export behaviour
• implementing authentication flows
• building UI screens beyond approved scope
• adding new dependencies that materially shape architecture
• committing changes

For bootstrap and planning tasks, stop after planning output unless explicitly approved to code.

Definition of done

Read docs/codex/definition-of-done.md.

At minimum:

• scope satisfied
• assumptions documented
• safety rules followed
• changed files reported
• tests run or explicitly not run with reason
• unresolved risks surfaced

File and folder conventions

• docs/codex/: durable Codex process rules and bootstrap prompts
• docs/planning/: planning, discovery, build sequencing, and risk research
• docs/reference/: safe reference summaries and approved non-raw extracts
• docs/templates/: reusable contracts and workflow templates
• docs/agent-contracts/: mandatory UI/accessibility contracts, checklists and audit registers
• .skills/: local project skills for recurring review/check tasks
• tests/fixtures/: synthetic or anonymised deterministic fixtures only
• data/: local-only data handling guidance, not committed sensitive raw data
• _input/: sensitive source-pack inputs; do not treat as safe-to-commit outputs

Expected commands

Current scaffold commands:

• Build: pnpm build:web
• Test: pnpm test
• Lint: pnpm lint
• Typecheck: pnpm typecheck
• Playwright: pnpm playwright

Python commands run through scripts/run-python.sh to avoid Apple Silicon / Rosetta architecture mismatches when pnpm is launched from an x64 Node runtime.

Bootstrap boundary

During bootstrap and planning phases:

• create docs, guardrails, templates, and skills only
• do not build frontend, backend, database, or import code
• do not modify the uploaded workbook
• do not start the build plan unless the task explicitly asks for it
• stop after planning output unless explicitly approved to code