docs: add Specture specs for all 6 planned features #2

Merged
addison merged 12 commits from exe-dev-bot/loam:feat/feature-specs into main 2026-02-18 04:46:28 -05:00
Contributor

What

Specture specs for all 6 planned Loam features, in priority order.

Targets feat/initial-scaffolding (PR #1). Should be merged after that PR lands.

Specs

# Spec Tasks Summary
1 budget-tracking.md 27 Monthly view, manual transactions, categories, FAB quick-add
2 customer-tracking.md 21 Markdown file directory, YAML frontmatter, search, editor
3 sales-pipeline.md 26 Kanban board + list view, opportunity management
4 found-import.md 22 CSV import from Found, category auto-mapping
5 invoice-generator.md 26 Invoice creation, client-side PDF, Web Share API
6 tax-planning.md 24 Quarterly estimates, deduction tracking, projections

All specs validated with specture validate (6/6 valid, 146 total tasks).

Cross-cutting constraints

  • Mobile-first UX (touch targets, swipe gestures, bottom sheets, FABs)
  • PWA offline-capable, all data local
  • sql.js (SQLite via WASM) shared data layer
  • Chromium-only
  • All dev commands via just recipes
## What Specture specs for all 6 planned Loam features, in priority order. Targets `feat/initial-scaffolding` (PR #1). Should be merged after that PR lands. ## Specs | # | Spec | Tasks | Summary | |---|------|-------|---------| | 1 | budget-tracking.md | 27 | Monthly view, manual transactions, categories, FAB quick-add | | 2 | customer-tracking.md | 21 | Markdown file directory, YAML frontmatter, search, editor | | 3 | sales-pipeline.md | 26 | Kanban board + list view, opportunity management | | 4 | found-import.md | 22 | CSV import from Found, category auto-mapping | | 5 | invoice-generator.md | 26 | Invoice creation, client-side PDF, Web Share API | | 6 | tax-planning.md | 24 | Quarterly estimates, deduction tracking, projections | All specs validated with `specture validate` (6/6 valid, 146 total tasks). ## Cross-cutting constraints - Mobile-first UX (touch targets, swipe gestures, bottom sheets, FABs) - PWA offline-capable, all data local - sql.js (SQLite via WASM) shared data layer - Chromium-only - All dev commands via `just` recipes
- package.json with vue 3.5, vite 7, @vitejs/plugin-vue
- vite.config.js with vue plugin
- index.html entry point
- src/main.js and src/App.vue (minimal)

Co-authored-by: Shelley <shelley@exe.dev>
- eslint.config.js (flat config) with eslint-plugin-vue and eslint-config-prettier
- .prettierrc with no-semi, single quotes, trailing commas

Co-authored-by: Shelley <shelley@exe.dev>
- justfile with dev, build, lint, format recipes
- .pre-commit-config.yaml with local eslint and prettier hooks

Co-authored-by: Shelley <shelley@exe.dev>
Co-authored-by: Shelley <shelley@exe.dev>
Co-authored-by: Shelley <shelley@exe.dev>
- Web manifest (name: Loam, earth-tone theme)
- Service worker with auto-update and asset caching
- SVG + PNG icons (192px, 512px)
- Meta tags for theme-color, description, icons

Co-authored-by: Shelley <shelley@exe.dev>
- Add 'just deps' recipe for dependency installation
- Replace 'npm install' with 'just deps' in README
- Add AGENTS.md with just-recipe-only rule and project conventions

Co-authored-by: Shelley <shelley@exe.dev>
Specs (all draft status):
1. Monthly budget tracking — manual transactions, categories, monthly view
2. Customer tracking — markdown file directory with editor
3. Sales pipeline — kanban board, opportunity management
4. Found import — CSV transaction import with category mapping
5. Invoice generator — client invoicing with PDF export
6. Tax planning — quarterly estimates, deduction tracking

All specs follow mobile-first PWA design, sql.js data layer,
and Chromium-only target constraints.

Co-authored-by: Shelley <shelley@exe.dev>
@ -0,0 +4,4 @@
creation_date: 2025-07-17
---
# Customer Tracking
Owner

Name file and spec "Client Tracking"

Name file and spec "Client Tracking"
addison marked this conversation as resolved
@ -0,0 +10,4 @@
Kwila Development needs lightweight customer tracking without a full CRM. Markdown files are portable, version-controllable, and human-readable. This feature provides a simple customer directory that other features (sales pipeline, invoicing) can reference.
Each customer is a `.md` file in a dedicated directory. YAML frontmatter holds structured fields (name, email, company, phone, website, address). The body contains freeform notes, meeting history, or any other context. A searchable, sortable list view shows all customers with cards displaying name, company, and key contact info. Search works across all fields including the body text.
Owner

Wrong. Each client has multiple .md files in different directories within their dedicated directory.

Example:

clients
├── client-template
│   ├── IDEAS.md
│   ├── projects
│   │   └── template-project
│   │       └── client-agreements
│   │           └── 2026
│   │               ├── hosting.md
│   │               └── software.md
│   └── README.md
├── summit-welding
│   ├── customer-agreements
│   │   ├── 2025.md
│   │   ├── 2025.pdf
│   │   ├── 2026.md
│   │   └── 2026.pdf
│   ├── README.md
│   └── worklog.md
├── README.md
├── scripts
│   └── md-to-pdf.sh
├── riverside-custom-barns
│   ├── IDEAS.md
│   ├── projects
│   └── README.md
├── golden-grove-orchard
│   ├── apps
│   │   └── cratelink
│   │       ├── 2024
│   │       │   ├── customer-agreement
│   │       │   │   └── customer-agreement.pdf
│   │       │   ├── interviews
│   │       │   │   └── post-usage.md
│   │       │   └── invoices
│   │       │       └── tentative.xlsx
│   │       └── 2025
│   │           └── customer-agreement
│   │               ├── customer-agreement.md
│   │               └── customer-agreement.pdf
│   ├── ideas.md
│   └── README.md
├── pinnacle-services
│   ├── IDEAS.md
│   ├── projects
│   │   └── fieldworks-integrations
│   │       └── client-agreements
│   │           └── 2026
│   │               ├── software.md
│   │               └── software.pdf
│   └── README.md
└── VendorLicense.pdf

Important feature that also needs included - quickly generating high-quality PDF for any given markdown file.

Wrong. Each client has multiple `.md` files in different directories within their dedicated directory. Example: ``` clients ├── client-template │ ├── IDEAS.md │ ├── projects │ │ └── template-project │ │ └── client-agreements │ │ └── 2026 │ │ ├── hosting.md │ │ └── software.md │ └── README.md ├── summit-welding │ ├── customer-agreements │ │ ├── 2025.md │ │ ├── 2025.pdf │ │ ├── 2026.md │ │ └── 2026.pdf │ ├── README.md │ └── worklog.md ├── README.md ├── scripts │ └── md-to-pdf.sh ├── riverside-custom-barns │ ├── IDEAS.md │ ├── projects │ └── README.md ├── golden-grove-orchard │ ├── apps │ │ └── cratelink │ │ ├── 2024 │ │ │ ├── customer-agreement │ │ │ │ └── customer-agreement.pdf │ │ │ ├── interviews │ │ │ │ └── post-usage.md │ │ │ └── invoices │ │ │ └── tentative.xlsx │ │ └── 2025 │ │ └── customer-agreement │ │ ├── customer-agreement.md │ │ └── customer-agreement.pdf │ ├── ideas.md │ └── README.md ├── pinnacle-services │ ├── IDEAS.md │ ├── projects │ │ └── fieldworks-integrations │ │ └── client-agreements │ │ └── 2026 │ │ ├── software.md │ │ └── software.pdf │ └── README.md └── VendorLicense.pdf ``` Important feature that also needs included - quickly generating high-quality PDF for any given markdown file.
addison marked this conversation as resolved
@ -0,0 +6,4 @@
# Import Transactions from Found
Import banking transactions from Found (found.com) into the budget tracking system (spec 1). CSV export is the initial method, with API integration as a future option. Imported transactions are mapped to budget categories with auto-suggest and manual confirmation.
Owner

Don't mention API integration. Only focus on CSV import.

Don't mention API integration. Only focus on CSV import.
@ -0,0 +10,4 @@
Kwila Development needs to generate invoices for consulting and development work. Currently using ad-hoc methods. A built-in generator linked to customer data streamlines billing and keeps all business context connected.
Invoice creation selects a customer (from spec 2), adds line items (description, quantity, unit rate, calculated amount), and sets invoice number, date, due date, payment terms, and notes. Line items support both hourly billing (hours × rate) and fixed amounts. Invoice numbers auto-increment with a configurable prefix (e.g., “KWI-001”).
Owner

We also need good support for calculating sales tax. I'm often unclear which line items require sales tax and which do not.

We also need good support for calculating sales tax. I'm often unclear which line items require sales tax and which do not.
addison marked this conversation as resolved
@ -0,0 +22,4 @@
### View Mode
- Chosen: Kanban board (primary) + list view (secondary), togglable
Owner

How will you implement kanban board effectively on mobile?

How will you implement kanban board effectively on mobile?
addison marked this conversation as resolved
@ -0,0 +8,4 @@
Estimated taxes, deduction tracking, and projections for quarterly tax planning. Calculates estimated quarterly tax payments based on income and deductible expenses from the budget tracking system (spec 1).
As a small business, Kwila Development must make quarterly estimated tax payments. Currently estimating manually. Automating projections based on actual income/expense data reduces errors and tax-time surprises. This is an estimation tool, not tax advice — a clear disclaimer is shown in the UI.
Owner

At this point I file Kwila as a schedule C on my taxes. Kwila is small enough that I do not need to do quarterly payments.

At this point I file Kwila as a schedule C on my taxes. Kwila is small enough that I do not need to do quarterly payments.
addison marked this conversation as resolved
- Rename customer-tracking to client-tracking, update directory model
  to match actual hierarchical client directory structure, add PDF
  generation from markdown (review comments 1 & 2)
- Remove all API integration references from found-import, focus
  exclusively on CSV import (review comment 3)
- Add per-line-item sales tax support to invoice-generator with
  taxability toggles and visual indicators (review comment 4)
- Add concrete mobile-first kanban approach to sales-pipeline with
  single-stage view, swipe navigation, and long-press actions
  (review comment 5)
- Reframe tax-planning around Schedule C sole proprietor filing,
  remove quarterly payment tracking (review comment 6)
- Update cross-references in invoice and pipeline specs from
  'customer' to 'client' for consistency with renamed spec 2

Co-authored-by: Shelley <shelley@exe.dev>
@ -0,0 +10,4 @@
Kwila Development needs to generate invoices for consulting and development work. Currently using ad-hoc methods. A built-in generator linked to client data streamlines billing and keeps all business context connected.
Invoice creation selects a client (from spec 2), adds line items (description, quantity, unit rate, calculated amount), and sets invoice number, date, due date, payment terms, and notes. Line items support both hourly billing (hours × rate) and fixed amounts. Invoice numbers auto-increment with a configurable prefix (e.g., "KWI-001").
Owner

You must use proper markdown links for ALL cross-spec references.

You must use proper markdown links for ALL cross-spec references.
addison marked this conversation as resolved
@ -0,0 +65,4 @@
A key workflow is generating polished PDFs from markdown files — agreements, proposals, and invoices need to be shared with clients as PDF. The app provides a one-tap "Export to PDF" action on any markdown file, rendering it with clean typography and professional formatting entirely client-side.
Files are stored in IndexedDB via sql.js, consistent with the budget tracking data layer. The full directory tree is represented as rows with path, content, and metadata columns. Mobile-first with touch-friendly navigation, large tap targets, and swipe to reveal actions. All data local, offline-capable, Chromium-only.
Owner

The rows in the DB are for caching only, right? The source of truth must be the user's local directory. We don't want to have pain syncing the user's files with the DB. What happens if the user adds new directories or files outside the loam interface?

The rows in the DB are for caching only, right? The source of truth must be the user's local directory. We don't want to have pain syncing the user's files with the DB. What happens if the user adds new directories or files outside the loam interface?
addison marked this conversation as resolved
- Use proper markdown links for all cross-spec references (review 112)
- Make local filesystem source of truth for client tracking; sql.js
  is a read cache/search index only. File System Access API for
  directory access, scan-on-foreground reconciliation, external
  changes picked up automatically (review 113)

Co-authored-by: Shelley <shelley@exe.dev>
addison deleted branch feat/feature-specs 2026-02-18 04:46:28 -05:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
kwila/loam!2
No description provided.