Xero

Build me a freelancer bookkeeping app covering the personal slice of Xero:
invoices, expenses, and quarterly reports. Requirements:

- A local web app: Node + Express + better-sqlite3; income and expense entries
  with date, amount, category, client, and an attached receipt file.
- CSV import from my bank's export, plus a rules table (description pattern to
  category) so repeat transactions auto-categorize.
- Invoices numbered sequentially, rendered to PDF with pdfkit, one paid/unpaid
  flag. Nothing more.
- Reports: quarterly income, expenses by category, and a one-page cash P&L I
  can print for my accountant.
- Binds to localhost only, no accounts, no telemetry; write a nightly copy of
  the SQLite file to a dated backup.
- Out of scope: bank feeds, reconciliation, payroll, tax filing, and audit
  history. Do not build any of them; if I need real accounting, Odoo or
  Invoice Ninja is the honest route.
- README: state that this is a ledger for staying organized between real tools,
  not accounting. Xero's product is bank feeds, reconciliation, and books an
  accountant will accept, and no one should sign off these numbers unchecked.

# AGENTS.md — Build guide for Xero

## Project scope
Build simple bookkeeping with invoices, expenses, CSV imports, chart of accounts, and reports for personal/internal use.

Catalogue verdict: no. Invoices and reports are buildable, but Xero's real product is bank feeds, accounting workflows, accountant collaboration, compliance expectations, integrations, and trust.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- accounting model
- bank import/API
- secure hosted database
- backups
- accountant/tax review
- payment integrations

## Stack and architecture
- A local web app: Node + Express + better-sqlite3; income and expense entries with date, amount, category, client, and an attached receipt file.
- Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
- Interface for this small-business accounting workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- If bank import/API is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: bank reconciliation.

## Agent implementation rules
- Project rule, data: Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
- Project rule, behavior: Reports: quarterly income, expenses by category, and a one-page cash P&L I can print for my accountant.
- Project rule, recovery: If bank import/API is unavailable, keep the source record and show a recoverable error instead of a fabricated result.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this small-business accounting operation with sample or user-owned data: Reports: quarterly income, expenses by category, and a one-page cash P&L I can print for my accountant.
- Show a concrete result or export: CSV import from my bank's export, plus a rules table (description pattern to category) so repeat transactions auto-categorize.
- State the practical limit: bank reconciliation.

## Engineering roadmap
1. Phase 1, architecture and data: A local web app: Node + Express + better-sqlite3; income and expense entries with date, amount, category, client, and an attached receipt file. Model accounts, source transactions, ledger entries, reconciliations, and reports; keep stable source IDs and timestamps.
2. Phase 2, implement: Reports: quarterly income, expenses by category, and a one-page cash P&L I can print for my accountant.
3. Phase 3, implement: Build simple bookkeeping with invoices, expenses, CSV imports, chart of accounts, and reports for personal/internal use.
4. Phase 4, review and output: Cloud accounting, invoicing, bank reconciliation, payroll add-ons, and reporting. CSV import from my bank's export, plus a rules table (description pattern to category) so repeat transactions auto-categorize.
5. Phase 5, recovery and acceptance: If bank import/API is unavailable, keep the source record and show a recoverable error instead of a fabricated result. Verify this invariant with a saved fixture: The sum of debits and credits must balance for posted entries; an import retry cannot change the closing balance. State the practical limit: bank reconciliation.

## Paid-product capabilities outside this build
- bank reconciliation
- accountant workflows
- payroll/tax integrations
- app marketplace
- audit history
- compliance support

## Implementation prompt
Build me a freelancer bookkeeping app covering the personal slice of Xero:
invoices, expenses, and quarterly reports. Requirements:

- A local web app: Node + Express + better-sqlite3; income and expense entries
  with date, amount, category, client, and an attached receipt file.
- CSV import from my bank's export, plus a rules table (description pattern to
  category) so repeat transactions auto-categorize.
- Invoices numbered sequentially, rendered to PDF with pdfkit, one paid/unpaid
  flag. Nothing more.
- Reports: quarterly income, expenses by category, and a one-page cash P&L I
  can print for my accountant.
- Binds to localhost only, no accounts, no telemetry; write a nightly copy of
  the SQLite file to a dated backup.
- Out of scope: bank feeds, reconciliation, payroll, tax filing, and audit
  history. Do not build any of them; if I need real accounting, Odoo or
  Invoice Ninja is the honest route.
- README: state that this is a ledger for staying organized between real tools,
  not accounting. Xero's product is bank feeds, reconciliation, and books an
  accountant will accept, and no one should sign off these numbers unchecked.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.