biz-in-a-box

Agent-native double-entry business ledger for any entity type, supporting transaction recording, auditing, reporting, and data integrity validation.

Security Scan

The skill's declared purpose (an agent-native double-entry ledger) is coherent with its instructions, but it tells the agent to fetch and execute code from an external GitHub repo (node validate.js) without declaring runtime requirements or bundling that code — that creates a non-trivial risk and an incoherence that you should review before using it.

Purpose & Capability

The name/description (agent-native double-entry ledger, validation, reporting) matches the instruction-only content: files, validation rules, and reporting guidance all fit the stated purpose. However, the runtime instructions require running a validation script (node validate.js) even though the skill's metadata does not declare Node or any runtime binary as required and the skill bundle does not include validate.js — that's an omission/incoherence.

Instruction Scope

Instructions ask the agent to git clone a public repo and run a local script (node validate.js). That means the agent will download and execute third-party code not included in the skill bundle; SKILL.md does not instruct the agent to inspect or verify the script before executing it. While the file operations (editing entity.yaml, appending to journal.ndjson) are consistent with the ledger purpose, executing arbitrary code from the cloned repo expands the scope beyond a pure data-format/spec skill and introduces execution risk.

Install Mechanism

There is no install spec in the skill (lower baseline risk), but SKILL.md explicitly instructs a network fetch (git clone https://github.com/taylorhou/biz-in-a-box). Downloading and executing code from an external repo is effectively an install/runtime step; because the repo contents (including validate.js) are not bundled or pinned in the skill metadata, this is a higher-risk pattern.

Credentials

The skill declares no environment variables, no credentials, and requires no config paths. That is proportionate to a local ledger/validation tool. However, the lack of declared required binaries (Node) is an omission — the skill will silently fail or force arbitrary runtime behavior if Node is unavailable or different versions are used.

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and is user-invocable only. It does instruct writing/reading repository-local files (journal.ndjson, entity.yaml) which is expected for its purpose and does not request broader system or skill-wide privileges.

What to consider before installing

This skill appears to be a coherent design for a plain-text double-entry ledger, but it relies on fetching and running code from an external GitHub repository (validate.js) that is not included in the skill bundle. Before installing or invoking: (1) review the GitHub repo and inspect validate.js and any other scripts for malicious behavior (network calls, credential access, arbitrary exec); (2) pin the clone to a specific commit or vendor you trust rather than cloning HEAD; (3) run validation scripts in a sandbox or isolated environment (container) before using them on real data; (4) ensure you have Node.js and the expected versions, and update the skill metadata to declare required runtimes if you intend to use it regularly; (5) avoid running these scripts on systems with sensitive credentials or wide filesystem access until you’ve reviewed them. If you cannot or will not inspect the external code, treat this skill as risky.

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