/company-finance

name: company-finance
description: Run finance for a PenguinHarness organization — set and adjust monthly budgets along the reporting line, audit spend daily with penguin org finance and penguin cost, explain budget alerts in the all-hands channel with savings proposals, and handle budget pauses.
version: 2026.10.10.1

Company Finance

Finance keeps the organization inside its money. Budgets are set per employee and compared on the cumulative line — the employee plus all subordinates — so the CEO's budget is the whole organization's. Spend is derived from every desk and ticket session's usage: finance does not count tokens, it sets the limits, reads the audit, explains what happened and proposes what to change. `company-employee` applies to you as to everyone; this skill is what the title adds.

Before you start

If the message only names this skill without a concrete request, ask what finance should do — an audit, a budget change, an alert to explain. An `[org_trigger]` run needs no question: read `<app_data_dir>/organizations/<org_id>/handbook/README.md`, then run the audit below.

How budgets work

• `budget` is a field of each employee's entry in `org_chart.yaml`, in USD per calendar month in the organization's timezone; no field means unbounded.
• It is compared on the **cumulative** line: the employee's own sessions plus every subordinate's, recursively. A subordinate's budget therefore has to fit inside its superior's, and the CEO's is the organization's total.
• Employee spend is its desk session plus every ticket session it contributed to (each with its subsessions, each session counted once). Ticket spend is its contributing sessions — split evenly when a session is attached to several tickets — rolled up along `parent`.
• At `budget_warn_ratio` (default 0.8) the server posts one system alert in the all-hands channel per employee per period; at `budget_pause_ratio` (default 1.0) the employee is **paused**: its calendar events and its subordinates' stop firing. Mentions and human conversations still reach a paused employee, so it can be told to wrap up. The pause lifts by itself when the ratio falls: a new month, or a raised budget (applied at the next reconcile, about 30 s).
• Prices come from the Project's model configuration; an unpriced model shows tokens only, starred, and is a finding of its own.

Setting budgets

penguin org chart --json                                 # the tree, with each entry's budget
penguin org employee set <org_id>_ceo --budget 500       # the organization's monthly total
penguin org employee set <org_id>_dev --budget 200       # inside the CEO's; the dev's subordinates share it

• Start from the total the board gave (ask the creator in the all-hands channel when nobody did), give the CEO that number, then split down the tree with a reserve at each level: a superior's budget minus its subordinates' budgets is what the superior itself can spend, so never allocate a level to 100%.
• Size a role by its work, not its title: a developer running several ticket sessions a day costs more than a reviewer woken weekly. Use the first week's `penguin org finance` to correct the guesses.
• The CLI writes the employee tree and validates at once; the new limit counts from the next reconcile.

The first run

The CEO hires finance at initialization, before there is a budget tree. On your first work run:

1. Read `org_config.toml` for `timezone` (the month boundary), `budget_warn_ratio` and `budget_pause_ratio`; ask the CEO in the all-hands channel before proposing a change to the ratios. 2. If the CEO's entry has no `budget`, ask the board for the monthly total — `penguin org channel send -m "@user:<creator> What is the organization's monthly budget in USD?"` (the all-hands channel is the default, and it is where the board reads) — and block on the answer rather than inventing one; `created_by` in `org_config.toml` names the creator. 3. Set the tree top-down (above), leaving each superior its reserve. 4. Open the month's finance ticket to carry the audit lines: `penguin org ticket create --title "Finance <yyyy-mm>" --goal "Keep the organization within budget this month" --criteria "Every alert explained in the all-hands channel; one audit line per day" --owner agent:<your_agent_id>`. 5. Check that your own calendar carries the daily audit (`penguin org calendar ls`); add it when the CEO has not (`penguin org calendar add finance-daily --prompt "Run the daily audit" --start-at now --period 1d`).

The daily audit

penguin org finance --json                      # this period: spend per employee (own and cumulative) and per ticket, budget usage, alerts and pauses
penguin org finance --period 2026-08 --json     # last month, for the trend
penguin cost --days 7 --by agent                # the Project view: spend by agent over the week
penguin cost --days 7 --by session --agent-id <org_id>_dev --json    # which sessions of one employee cost the most

Read, in order: anyone paused; anyone above the warn ratio; spend against days elapsed in the month (an employee at 60% on the 10th will pause by the 20th); the most expensive tickets and whether their `sessions` count explains them; sessions that cost much and moved no ticket (a runaway conversation, a sweep that finds nothing). Write the finding as one progress line on the month's finance ticket (create it at the first audit of the month) so the trend is on the board.

Explaining alerts and proposing savings

A budget alert is a system message: it triggers nobody, so finance reads it in the audit and answers it. Alerts are posted in the all-hands channel and the answer belongs there too — money is the whole company's business, and the board reads it. One message, @-mentioning the employee's superior (and the employee when it can act on the advice), with the number, the cause and a proposal:

penguin org channel send -m "@acme_ceo acme_dev is at 85% (170/200 USD) o