biz-in-a-box Skill

Agent-native operating system for any business entity. An append-only, hash-chained journal (journal.ndjson) + a chart of accounts (accounts.yaml) + entity metadata (entity.yaml). Agents can derive any financial report from it in one context window.

• Protocol spec: See references/spec.md
• Chart of accounts: See references/accounts.md
• Vertical examples: See references/verticals.md

Quickstart

1. Fork or clone the repo

GitHub: https://github.com/taylorhou/biz-in-a-box Website: https://biz-in-a-box.org

git clone https://github.com/taylorhou/biz-in-a-box my-entity
cd my-entity

Edit entity.yaml with the entity's id, name, and type. Edit accounts.yaml to match the entity's chart of accounts.

2. Record a transaction

Append a JSON line to journal.ndjson. Every entry needs id (ULID recommended) and time (ISO-8601 UTC). Financial entries also need balanced debits/credits.

Example — record a $1,200 rent payment:

{"id":"01HXYZ...","time":"2026-02-26T14:00:00Z","labels":["financial"],"description":"February rent","debits":[{"account":"5200-rent","amount":1200}],"credits":[{"account":"1010-bank-checking","amount":1200}]}

3. Validate

node validate.js

Checks: required fields, double-entry balance, hash chain continuity, correction has supersedes, transfer has from/to.

4. Query / report

Read journal.ndjson line by line. Filter by labels, time range, or accounts to derive:

• P&L: sum revenue (4xxx) vs expenses (5xxx) over a period
• Balance sheet: sum assets (1xxx), liabilities (2xxx), equity (3xxx) at a point in time
• Cash flow: filter 1010-bank-checking debits and credits
• Burn rate: sum expenses (5xxx) over trailing 30/90 days

Key Rules

• sum(debits.amount) must equal sum(credits.amount) for financial entries
• Use correction label + supersedes: <id> to amend entries — never edit in place
• Genesis prev_hash: 64 zeros; subsequent entries chain via SHA-256
• Entries > 7 days backdated require historical or imported label

File Set

| File | Purpose | |------|---------| | journal.ndjson | Append-only event log (one JSON per line) | | entity.yaml | Entity metadata (id, name, type, jurisdiction, etc.) | | accounts.yaml | Chart of accounts (assets/liabilities/equity/revenue/expenses) | | labels.yaml | Label definitions | | access.yaml | Access control | | validate.js | Validation script | | snapshots/ | Optional periodic balance snapshots | | verticals/ | Vertical-specific extensions |