Skip to content

AGENTS.md

Latest commit

 

History

History
57 lines (42 loc) · 6.13 KB

AGENTS.md

File metadata and controls

57 lines (42 loc) · 6.13 KB
Raw

FlowValue AI — repository instructions for Codex and other development agents

Source-of-truth reading order

  1. Engineering onboarding, architecture memory and collaborator brief: read this first when joining the project or handing work to another engineer/Codex. It records founder intent, tested versus planned functions, data-flow boundaries, recent architecture diagnostic and agreed task ownership. It supplements, but does not override, the canonical product specification or current code.
  2. Canonical founder product specification: full unchanged product vision, scope and acceptance requirements.
  3. Complete A–I build roadmap: phases, dependencies, test gates and status. Read the R39 cross-phase roadmap before implementing natural-language opportunities.
  4. For relevant implementation work: AI/research, calculation basis, process/engineering integration, unit analyst, and future release gate.
  5. Under frontend/, also follow Next.js instructions.

These are product requirements and proposed acceptance criteria, not proof of implemented functionality. Respect the founder's existing broad end-to-end platform scope; do not silently narrow, expand or discard it. Historical phase acceptance docs report past checks and must not be rewritten as newly delivered claims.

Engineer 2 GitHub checkpoint

For Engineer 2 tasks in this repository, use the long-lived engineer-2/development branch with upstream origin/engineer-2/development. Inspect branch, upstream and working-tree status before editing. Fetch and inspect any remote divergence before reconciliation. Preserve existing history and local work. Stage only the verified files for the task, commit with its phase and backlog ID, push normally to that upstream and verify the remote commit. Obtain approval before publishing an incomplete checkpoint.

Keep generated files, credentials and unrelated work out of commits. Keep main and Engineer 1's branch untouched unless expressly authorized. Do not force-push, rewrite published history or merge automatically. Get Engineer 1 review before changing shared engineering or financial semantics. Report local and remote commit status separately.

R39 — planned natural-language commercial opportunity workflow

Founder example: “We get revenue from food. Could we sell our wastes?”

  • Interpret the idea into a reviewable draft additional revenue scenario linked to the actual waste/by-product stream where known. Capture material quality, saleable quantity, volume sold, location, price/units/basis, extra logistics/processing cost and evidence. Missing information remains explicit; never invent a mass balance, market price, or signed contract.
  • If the user supplies a price, record it as a user assumption and calculate a preview. If price is missing, ask permission before any external research. Return possible comparable prices with dated citations, and prospective buyers and buyer requirements where verifiable.
  • Evaluate the likelihood of winning a buyer/contract, but give a numeric probability only with an explicit defensible calibrated basis; otherwise mark numerical probability not estimable. Public listings are neither commitments nor signed contracts.
  • Hand user-reviewed assumptions to validated deterministic engineering/economics engines. Recompute separate revenue, incremental costs, cash flow, NPV/IRR and other affected metrics. Refresh Revenue, Scenario, Main dashboard charts and applicable 2D/3D stream annotations; preserve baseline-versus-preview comparison and the original project/version history.
  • Build and test across A structured proposals → B real stream mapping → C multi-revenue economics → D opted-in sourced research → E visual/report reconciliation. The acceptance cases in the spec and roadmap (price given, price missing, refusal, insufficient market/stream data, unsupported contract probability, scenario editing and baseline restoration) are mandatory gates.

General safeguards

Do not replace engineering analysis with AI-generated arithmetic or unsupported confidence scores. Do not silently modify an approved baseline, create physical connections from an economic idea, or contact buyers/suppliers without separate authorisation. Reconcile financial outputs and exports from the same saved scenario; test source lineage, user permissions, invalid units, incomplete data, versioning, and end-to-end UI behaviour before declaring any feature complete.

Canonical Entry-file parser scaffolds (17 methods; deliberately empty)

Before implementing or changing ingestion, read the input parser directory index and the UI source frontend/src/lib/import-methods.ts. Exactly one headed but otherwise empty Python module now exists for each dropdown selection at backend/app/parsers/inputs/. These are future adapter stubs, not working parsers, registered routes or a promise of support. Implement them one at a time with the founder, keeping source provenance and the canonical stream/balance models intact. Preserve the current working Excel, CSV, JSON, DWSIM and trusted BioSTEAM paths until independent tests and a reviewed migration justify replacement. Do not execute uploaded simulator scripts or claim PDF/Word/image/OCR capabilities from the existence of a stub.

Source and dependency licence hygiene

Before incorporating any third-party code, check its actual licence for the resolved version, compatibility with our proprietary source, and required notices. Read LICENSE and THIRD_PARTY_NOTICES.md. Do not assume a public GitHub repository is open source, and do not copy code lacking a licence without permission from its rights holder. Keep original FlowValue code distinct from separately licensed dependencies and preserve upstream notices. Changing the licence of original FlowValue code requires the owner's explicit approval.