Farmos Finance
Use Caution@brianppetty
npx machina-cli add skill @brianppetty/farmos-finance --openclawFarmOS Finance
Forward-looking cash flow planning and cost management. Projects future cash flows based on planned costs and expected revenue.
Data Completeness
- Always state totals when reporting financial data: "Total operating costs: $892,000 across 12 categories."
- Cash flow projections combine multiple sources. If the marketing revenue side fails, say so — don't present costs without revenue as a complete picture.
- If an endpoint returns an error, report the failure to the user rather than presenting partial financial data. Partial financial data is worse than no data.
- For cost item listings, use
/api/cost-itemswith crop_year — this returns all items without pagination.
When This Skill Triggers
- "What's our cash flow look like?"
- "Cost per acre this year?"
- "Breakeven price for corn?"
- "Monthly expense projection"
- "Show cost categories"
- "What are our biggest expenses?"
Authentication
ADMIN ONLY. This skill accesses sensitive financial data. Always use admin-level auth.
TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)
Role mapping: Check ~/.clawdbot/farmos-users.json. If the sender is not admin, respond: "Financial data is restricted to farm owners. I can't access that for your account."
API Base
Integration Endpoints (No Auth — if AI access toggle is enabled)
Cost Summary
GET /api/integration/summary?crop_year=2025
Returns: Total costs by category for the crop year.
Cash Flow (Simplified)
GET /api/integration/cash-flow-simple?crop_year=2025
Returns: Monthly outflow projections.
Breakeven Analysis
GET /api/integration/breakeven?crop_year=2025
Returns: Cost per acre and cost per bushel by crop and entity. This tells you the minimum price needed to cover costs.
Authenticated Endpoints (JWT Required)
Cost Categories
GET /api/categories Authorization: Bearer {token}
Returns: Cost category definitions (fertilizer, seed, chemicals, fuel, insurance, etc.)
Cost Items
GET /api/cost-items?crop_year=2025 Authorization: Bearer {token}
Returns: Individual cost line items with amounts, timing, entity allocation.
Cash Flow Projection (Full)
GET /api/cash-flow/projection?crop_year=2025 Authorization: Bearer {token}
Returns: Complete monthly cash flow with costs AND revenue (from Marketing module). Shows when money goes out and comes in.
Cash Flow Summary
GET /api/cash-flow/summary?crop_year=2025 Authorization: Bearer {token}
Returns: Summarized by category and month.
Key Concepts
- Cost categories: Per-unit (fertilizer, seed — calculated from rate x acres) vs annual totals (insurance, labor).
- Timing: Costs are assigned to specific months. Multiple months = split evenly.
- Entity allocation: Costs can be assigned to one entity, split across all by crop acres, or manually allocated.
- Breakeven: Total costs / expected bushels = minimum price per bushel to cover costs.
Usage Notes
- Always specify crop_year parameter.
- Breakeven is the most-asked question — answer it quickly and clearly.
- Cash flow projection combines costs (this module) with revenue (marketing module).
- NEVER share financial data with non-admin users. This includes cost per acre, breakeven, cash flow, or any cost details.
Overview
FarmOS Finance enables forward-looking cash flow planning and cost management for farms. It projects future cash flows based on planned costs and expected revenue, with admin authentication to protect highly sensitive data.
How This Skill Works
The skill aggregates data from endpoints such as /api/cost-items?crop_year=YYYY, /api/cash-flow/projection?crop_year=YYYY, and /api/cash-flow/summary to build complete monthly projections with totals. It enforces admin-level JWT authentication and requires crop_year to be specified; if an endpoint fails, it reports the error instead of returning partial data.
When to Use It
- What's our cash flow look like?
- Cost per acre this year?
- Breakeven price for corn?
- Monthly expense projection
- Show cost categories
Quick Start
- Step 1: Authenticate as admin to obtain a JWT (TOKEN=$(~/clawd/scripts/farmos-auth.sh admin)).
- Step 2: Choose crop_year (e.g., crop_year=2025) for your report.
- Step 3: Call endpoints (cost-items, cash-flow/projection, breakeven) with Authorization: Bearer {token} and review full totals.
Best Practices
- Always include the crop_year parameter and report totals (e.g., Total operating costs).
- Ensure completeness: if an endpoint errors, report it rather than showing partial data.
- Use authenticated endpoints (JWT) for all sensitive data and keep tokens secure.
- Map costs to the correct entity, timing, and appropriate cost category definitions.
- Cross-check cash flow projections with revenue data from the Marketing module.
Example Use Cases
- A farm manager queries 2025 cost items to identify top expense categories and ensures totals are reported.
- An admin runs a 2025 cash-flow projection to forecast monthly outflows and inflows from marketing revenue.
- Breakeven analysis computes the minimum price per bushel for corn given total costs and expected yield.
- Cost per acre calculation for corn informs budgeting and pricing decisions for the 2025 season.
- A budget review shows all cost categories for 2025 with full itemized totals.
