DEV Community: Koustubh

gharasathi (घरासाठी): Start Here

Koustubh — Sun, 18 Oct 2026 06:08:12 +0000

gharasathi ("for home" in Marathi) is a household AI that runs entirely in our house. It brings together money, photos and documents so we can make better decisions as a family without sending our data to anyone's cloud.

The whole project in under a minute and a half: the mission, how it works, Hishob, security, and what's next.

It follows the same rules everywhere:

The data stays home. Inference runs on a Mac Studio in the house.
Code counts, the model explains. No figure comes from the model's head.
Every finding shows its evidence. That means a transaction, or a line quoted from a document.

This page lists every series. I update it whenever a new part is published.

1. The idea: gharasathi: Building a Household AI

How it started: a $200 mini PC, Neo4j at the core, and a 3B model.

2. Finance: Hishob (हिशोब)

A private money dashboard. It reads bank data, bills and statements, finds where the money goes, and explains what to do about it.

Coming later

Photos: Immich on the Mac Studio. Our photo library, off iCloud and Google Photos.

New parts are added to the series they belong to, and listed here.

Reading Bills and Statements Without AI, and the Money They Found

Koustubh — Sun, 18 Oct 2026 06:08:06 +0000

Part of gharasathi, a private household AI. Start here for all the series.

Bank data tells you what left the account. It rarely tells you why. A direct debit to the childcare centre doesn't show the fee, the subsidy, or which days were absences. An energy debit doesn't show how many kilowatt-hours you used, or that the price changed on 1 July. That detail lives in PDFs attached to emails.

This part covers how Hishob reads those documents, and why it deliberately doesn't use the LLM to do it.

Getting the documents: labels, not inbox access

Gmail filters apply labels such as gharasathi/utilities and gharasathi/childcare. The nightly job (aapla-patrakar) reads only those labels.
It reads without changing anything. IMAP EXAMINE opens the mailbox read-only, and BODY.PEEK[] fetches messages without setting the \Seen flag. A test runs the client against a fake IMAP server and fails if any command could change the mailbox.
A drop folder. Any PDF dropped into Nextcloud's Gharasathi/Inbox is read too, then filed as Statements/<type>/<vendor>/<date>-<type>.pdf. Exact duplicates are detected by SHA-256.
Re-reading. When a parser improves, every filed document is read again the next night, because each extraction records the parser version that produced it.

Ingestion doesn't care what a label is for. The labels map to consumers, and "statements" is just the first. Reminders from email could be a later one.

Why parsers instead of the LLM

A 122B model would read a utility bill fine 99% of the time. For money, I want to know about the other 1%.

aapla-olakh runs pdftotext -layout and then a hand-written parser for each document type: an energy retailer's electricity, gas and broadband bills, the water utility's bills, and our childcare centre's statements. Each parser checks the document against itself:

usage tiers × rates = the charges, and the tiers add up to the meter reading;
charges + credits = the bill total;
the childcare statement's running balance, fee − subsidy = gap for every day, the summary totals, and the amount due.

If anything doesn't add up, it's a warning, not a guess. All 120 real documents (87 childcare statements, 17 energy and broadband bills, 16 water bills) now parse with zero warnings. Getting there took fixes for column layouts that changed between years, a step label wrapped onto its own line, and the subsidy column being blank before the subsidy was approved.

Every extracted field keeps the exact line it came from. When anna or the dashboard explains a debit, it quotes the statement.

Matching documents to the bank

A bill matches a debit when the amount is exactly equal and the debit falls between 7 days before and 14 days after the due date.
Childcare uses each statement's own "payment" lines, and the latest statement wins for each day of care.
Reversed debits are tracked: "returned by the bank, then paid a week later" is a status, not two unrelated transactions.
Debits to these vendors with no document are listed as "payments with no bill on file", with a note on how to add the missing bill.

What the documents found

The most useful finding, the childcare absence allowance from part 1, came from a single line the parser reads off every statement: YTD Absences at service NN. In the bank data it was only a run of unusually large debits in March. The detector compares the year's count with the 42-day allowance, warns when it gets within 12 days, and projects where the year will end.

Other findings, all from documents plus the bank:

The childcare subsidy passed on was less than the government's entitlement for two short periods. The statement prints both figures, so the gap is exact.
The CCS rate changed five times in two years. Each step is shown with what it adds to the gap per fortnight.
Water use was up 34% on the same quarter last year. The bill prints last year's daily average, so this needs no estimate.
Prices changed on 1 July: electricity per kWh went down 8% and water went up 7%. The bill checks itself, so the rates are exact.
Sixteen payments had no bill on file, mostly broadband. Those are the bills to forward next.

Read from 87 statements. As the subsidy rate stepped down, our share of each month's fee grew. Amounts and rates are removed for the screenshot.

Each bar is one bill's use per day, and the tick is the same period a year earlier. Figures are removed for the screenshot.

Cutting spending: what actually held up

Combining the documents with the bank data and the analyst, the cuts that held up when I checked them myself were:

Dining crept up about 15% between two half-years.
Car insurance renewed 13% higher than the previous renewal: shop around.
Broadband went up 7% mid-year: compare plans.
A gym membership charged weekly: keep it only if it's used.
Transfers labelled "family support" included flights and food delivery, so dining and travel are bigger than they look. Re-labelling them from the transfer memo is next.
The mortgage: not a refinance (part 2), but keeping more cash in the offset.

None of these needed a cloud service, and none of the documents left the house.

What's next

More document types (insurance renewals, kids' activity invoices), and an energy plan comparison that uses our real usage from the bills. Beyond that, money is only one kind of household record. The same rules apply to any other kind: the data stays home, code does the counting, and the model explains.

Running Qwen3.5-122B on a Mac Studio as a Household Finance Analyst (and Keeping It Honest)

Koustubh — Sun, 18 Oct 2026 06:08:01 +0000

Part of gharasathi, a private household AI. Start here for all the series.

In the original series, a 3B model on a 6 GB mini PC could route a question to the right tool and turn its result into a sentence. That was about all. It couldn't analyse a year of household spending. This part covers what changed when the model got 40 times bigger, and what didn't.

The setup


Machine	Mac Studio, M3 Ultra, 96 GB unified memory
Server	`llama-server` from llama.cpp, installed with Nix, run by a launchd agent
Model	Qwen3.5-122B-A10B, GGUF, 4-bit (`UD-IQ4_NL`)
Memory in use	about 62 GB
Context	128k tokens, 2 parallel slots
API	OpenAI-compatible on `:8092`; services call it as `ChatOpenAI`

llama-server \
  --model Qwen3.5-122B-A10B-UD-IQ4_NL-00001-of-00003.gguf \
  --alias qwen3.5-122b --port 8092 \
  --ctx-size 131072 --parallel 2 \
  --n-gpu-layers 99 --flash-attn on --jinja \
  --chat-template-kwargs '{"enable_thinking":false}' \
  --temp 0.7 --top-p 0.8 --top-k 20 --presence-penalty 1.5

Why this model. It's a mixture of experts: 122B parameters in total, but only about 10B are active for each token. All the experts must sit in memory, which unified memory handles well, while each token costs roughly what a 10B dense model would. The quality is that of a big model at a speed that's fine for an overnight job and acceptable for chat. A typical dashboard follow-up question with tool calls takes about 25 seconds.

Why llama.cpp rather than Ollama. I started on Ollama. I moved to llama-server for direct control over context size, parallel slots, the chat template and the thinking switch. Nix pins the build, and launchd restarts it if it dies.

Thinking on and off. Qwen3.5 "thinks" by default. The server turns that off, and each caller turns it back on per request where it's worth it: the overnight analyst thinks, while chat and routing don't. Thinking also has no natural stop on hard prompts (I once saw 35k tokens on a single call), so thinking requests are capped.

Two ways the model is used

1. anna (chat, and the dashboard's Explain button). This is a LangGraph agent with about a dozen finance tools: spending analysis, insights, goals, a mortgage what-if calculator, bills and statements, and a read-only Cypher query. The rule in its prompt is blunt: always call a tool before answering; never do arithmetic in your head; use the calculate tool. On the dashboard you can click a fixed question, such as "Explain this and what to do", and then type follow-ups. The follow-ups carry the conversation, so "the loan is fixed, does that change it?" gets an answer about that finding.

2. The overnight analyst. This is where the bigger model earns its place.

Fact packs. Code builds one pack per topic: mortgage and offset, childcare, utilities, groceries, dining, insurance and so on. A pack holds monthly totals, merchants, recurring charges, balances and, now, facts read from bills and statements. Every number in a pack is computed, never estimated.
Overview, then topics. The model first names the household's 3 to 6 themes. Then it writes up to 3 findings per topic. Before writing, it may ask for extra data from a fixed list of requests, such as "transactions for merchant X" or "this category by month".
Fact-check (code). Every dollar amount and percentage in a finding must appear in the pack, or follow from it with one step of arithmetic. If not, the finding gets one repair round, then it is rejected.
Judge, synthesis, editor. A second pass asks whether the advice actually follows from the facts. Then the model connects findings across topics, ranks them against our past feedback ("not useful", "already handled"), merges duplicates and caps the number of new findings each night.

The fact-checker is not decoration. From last night's log:

PACK childcare: [
 {'title': 'Recurring cost from exceeding 42-day absence allowance',
  'outcome': "rejected by fact-check: 156.0 in saving_calculation isn't from the data"},
 {'title': 'CCS rate dropped …, adding ~$…/year',
  'outcome': 'withdrawn by analyst after fact-check'}, ...]

Both rejections were plausible-sounding numbers that the model had worked out rather than read from the data.

Where a big model still goes wrong: confident advice without context

The analyst once told me our mortgage rate was a fraction of a percent "above a previously negotiable rate" and that I should call the bank. Every figure in that finding passed the fact-check, but the advice was useless:

The loan is fixed, so repricing it means break costs.
Our loan-to-value ratio means moving to another lender would mean paying Lenders Mortgage Insurance again, which wipes out years of a small rate saving.
The "negotiable" rate came from an earlier finding, not from any rate in the data.

Two fixes:

Domain rules in the pack. The mortgage pack now starts with what is realistic: fixed-rate break costs, LMI above 80% loan-to-value, never quote a rate that isn't in the data, and the real levers (the offset balance, a retention rate when the fixed term ends, and refinancing once the loan-to-value ratio drops below 80%).
Household facts. Some things only we know, such as the loan-to-value ratio, so they go to the analyst and anna as a short "household says" note.

Now when I ask whether refinancing is realistic, anna says no, explains LMI and break costs, and points to the offset. The offset is where the data shows real money: in the months the offset held the most cash, interest per day fell by about a fifth.

What I'd tell someone trying this

A bigger model makes the explanations better. It doesn't make the arithmetic safe. Keep the counting in code at any model size.
Make it cite. Every finding stores its evidence: transaction ids, or the exact line quoted from a PDF. The fact-checker checks against that.
Feed it the constraints you'd tell a human adviser. Most bad advice came from missing context, not from weak reasoning.
Unified memory is the enabler. A 4-bit 122B mixture-of-experts model in about 62 GB leaves room for Immich, Nextcloud and a Kubernetes cluster on the same machine.

Next, part 3: bills and statements. They're the one place I deliberately didn't use the LLM, and they turned out to hold the most valuable findings.

Hishob (हिशोब): A Private Money Dashboard With a Local AI That Finds Where It Goes

Koustubh — Sun, 18 Oct 2026 06:07:56 +0000

Part of gharasathi, a private household AI. Start here for all the series. This one follows on from gharasathi: Building a Household AI, which set out the idea on a $200 mini PC. This one is about the part I use every week: money.

Hishob (हिशोब) is Marathi for "accounts", as in keeping account of things. It's the money dashboard of gharasathi, and its job is simple to state: show me where the household's money goes, and point at the places where we're paying more than we need to.

What changed since the first series

The first series ran everything on a 6 GB mini PC with a 3B model, and part 2 ended with "a better LLM requires better hardware". That hardware arrived: a Mac Studio (M3 Ultra, 96 GB unified memory). It now hosts most of the household's private services:

Immich: our photo library, off iCloud and Google Photos (a post of its own later)
Nextcloud: documents, plus the bills and statements this series is about
llama.cpp serving Qwen3.5-122B-A10B: the model behind everything "AI" here
A k3d cluster running the gharasathi services

The mini PC still runs the media server and other services with little to do. The finance stack moved because the model had to be big enough to reason about money, and close enough to the data that nothing has to leave the house.

The architecture

As before, every service has a Marathi name:

Service	Meaning	What it does
aapla-dhan (Go)	"our wealth"	Syncs bank accounts through Australia's Consumer Data Right into Neo4j. I start each sync by hand, about once a week.
aapla-patrakar (Go)	"our reporter"	Reads bills and statements from labelled Gmail folders and a Nextcloud drop folder, and files the PDFs.
aapla-olakh (Go)	"our recognition"	Hand-written PDF parsers that pull out fields and check each document's own arithmetic.
aapla-hushar (Python, FastAPI, LangGraph)	"our clever one"	Rule-based detectors, the overnight AI analyst, and anna, the chat assistant.
aapla-hishob (React)	"our accounts"	The dashboard.

Only two things reach outside the house, and both only read: the bank feed (through an accredited CDR intermediary) and Gmail over IMAP. All inference runs on the Mac Studio.

All the accounts, not just one

Most budgeting apps see a single transaction account. Hishob sees the whole household balance sheet, pulled through Australia's Consumer Data Right (open banking): read-only, consented per account, and revocable from the bank's app.

Account	Type	What it adds
Everyday account	transaction	Day-to-day spending, bills, salary
Offset account	transaction, offsets the loan	Savings that reduce mortgage interest every day
Home loan	mortgage	Balance, repayments, and the interest actually charged

Having all three in one graph is what makes the dashboard more than a spending tracker:

Spending is counted once. Moving money between our own accounts, or into the offset, isn't spending. Mortgage principal counts as saving (it builds equity), and mortgage interest counts as a real cost.
Interest is connected to cash. With the offset balance and the interest charged side by side, the effect is visible: in the months the offset held the most cash, interest per day fell by about a fifth. A rule flags cash sitting in the everyday account that could be reducing interest instead.
The mortgage can be modelled. Balance, offset, repayments and an estimated rate all come from the data, so "what if we kept $10k more in the offset?" is a calculation, not a guess.
Refunds and reversed debits are matched to the original payment instead of looking like extra income and extra spending.
No fake "complete" months. Each bank feed syncs separately. The dashboard only treats data as complete up to the oldest account's last transaction, so one lagging feed can't make a month look cheap.

How the data gets in: semi-automatic, on purpose

Hishob isn't fully automatic, and that's deliberate. Each kind of data comes in the way that keeps the most control in our hands.

Data	How it arrives	Who does what
Bank transactions	Pulled once a week	I start the sync by hand. Nothing touches the bank feed unless I ask.
Bills and statements	Forwarded to a dedicated mailbox	Gmail filters label each one by type (`gharasathi/utilities`, `gharasathi/childcare`). The nightly job reads only those labels, read-only, and the parsers take it from there.
Anything else	Dropped into a Nextcloud folder	The same nightly job picks it up and files it.

So the routine is: forward a bill when it arrives, and press sync once a week. Everything after that, from parsing and filing to matching, the rules and the analyst, runs overnight on its own.

One graph: the bank and the paperwork

Everything lands in a Neo4j knowledge graph, so a debit, the bill it paid and the line on that bill are connected, not just sitting in separate tables.

The bank side: each Account (everyday, offset, home loan) is the SOURCE_OF its Transactions, about 1,900 of them so far.
The paperwork side: an email HAS_ARTIFACT a PDF, the PDF is PARSED_AS a Document, and the document ASSERTS Facts (usage, unit rates, the subsidy, the absence count). Each fact is EVIDENCED_BY the PDF it came from. A bill also creates an Obligation: an amount, a due date, and who it's OWED_TO.
The join: code matches each obligation to the transaction that paid it, on the exact amount within a date window. For now that match is computed when the data is read; writing it back into the graph as an edge is next.

The graph is what lets anna answer "what did this debit pay for?" by walking from the transaction to the bill and quoting the line, instead of guessing from a merchant name. Postgres keeps the original records, and the graph is the connected view the assistant and the analyst query.

A small ontology, not a pile of nodes

Those labels and relationship names aren't ad hoc. They form a small ontology: a fixed vocabulary of the kinds of things in a household and the ways they can relate. Only the listed relationships are allowed, so nothing like a generic LINKED_TO edge. Three things follow from that:

The model can query it reliably. With a short, known list of node types and relationships, the Cypher that anna writes stays predictable: there's one way to say "this document asserts this fact", not five.
Evidence is part of the structure. Every Fact points to the PDF it came from. A link the system guessed, such as a document mentioning an organisation, carries a confidence and a status, so it can be confirmed or rejected instead of being treated as true.
It isn't specific to money. Communication → Artifact → Document → Fact → Entity describes any household paperwork. The schema already defines entity types such as Person, Property, Policy, Vehicle and Event, so an insurance renewal or a medical letter fits the same shape without a redesign.

What the dashboard shows

Every dollar figure in these screenshots is hidden with the dashboard's own "Hide $" switch. Percentages and charts stay visible, so I can show the dashboard without showing our finances.

The month so far against a typical month for the same number of days. Comparing the 14th of the month with a whole previous month made every month look cheap until the last week.
Six months of spending by category, with income as a line and one-off payments marked rather than counted.
What changed against the usual, and which merchants drove it.
Bills & statements: every utility bill and childcare statement, matched to the bank debit that paid it (part 3).
Things anna noticed: the part that matters most, covered next.

The star of the show: "Things anna noticed" and Explain

Charts tell you what happened. The bottom of the dashboard tells you what to do about it.

Every morning there is a short, ranked list of findings. Some come from deterministic rules (a price rise, a bill that wasn't paid, a subsidy gap) and some from the overnight AI analyst. Each one carries its evidence: the transactions, or the exact line from a bill. Each one has two buttons:

Explain: anna, the assistant running on the local model, reads the finding, pulls the underlying data with her tools and explains it in plain words: what happened, the evidence, and what to do.
Resolve: "not an issue". The finding disappears, and the overnight editor learns to rank similar ones lower.

Under every explanation there's a box for follow-up questions, so it reads like a conversation with someone who has all the statements open in front of them.

Three things it caught, with our own data:

"Did we pay that bill twice?" No. The same energy bill amount left our account twice, a week apart. On the bank feed alone, that looks exactly like a double charge. Hishob had the bill itself (read from email, part 3) and matched it to the bank. The first debit was returned by the bank, and the second was the real payment: one bill, paid once. The finding said so in one line.

Childcare subsidy we didn't know we were losing. Australia's Child Care Subsidy covers up to 42 absent days per child per year, and our statements showed we went past it. Explain walked through it: the statement's own count showed the limit was passed in February, and every absent day after that was charged the full fee. My follow-up, "how many absence days have we used this year, and what would one more cost?", got this year's count and the price of an extra day. Now a rule warns us before we reach the limit.

Advice that changed when I gave it context. A finding suggested negotiating the mortgage rate. My follow-up added what the data couldn't know: the loan is on a fixed rate, and our loan-to-value ratio means a new lender would charge Lenders Mortgage Insurance (LMI). The answer changed: refinancing would mean paying LMI again, and repricing a fixed loan means break costs. The real lever was keeping more cash in the offset account. Part 2 shows how this context now reaches the analyst every night.

None of this needed a cloud service. The question, the statements and the answer all stayed on a machine in the house.

How it runs: overnight, like a colleague who reads everything

01:30: new bills and statements are read and filed.
Hourly: about twenty deterministic detectors run, but only when the data has changed. They cover recurring charges, price rises, duplicates, offset balance, unpaid or returned bills, and childcare subsidy gaps.
02:30: the AI analyst reads exact "fact packs" built by code and writes findings, which are then fact-checked (part 2).
Morning: the dashboard and anna show the results.

The rule that shaped everything: code counts, the model explains

The first series learned this on a 3B model, and it still holds at 122B. The model never adds up money. Code computes every total, average and match. The model gets those exact figures and does the part code is bad at: noticing that two things are related, explaining why, and suggesting what to do. A fact-checker then rejects any finding that contains a dollar figure or percentage that doesn't trace back to the data.

Part 2 covers how that works with Qwen on the Mac Studio. Part 3 covers bills and statements, which turned out to hold the most valuable findings.

What's next in this series

Part 2: Running Qwen3.5-122B on a Mac Studio as a household finance analyst, and keeping it honest
Part 3: Reading bills and statements without AI, and what they revealed

Money is just where it starts. Once the data stays home, a capable model runs next to it, and the ontology has room for more than money, the possibilities are wide open. Any part of household life that leaves a record can get the same treatment: code does the counting, and the model explains.

What OpenClaw Teaches Us About Personal AI Security

Koustubh — Sun, 08 Feb 2026 03:58:13 +0000

OpenClaw and gharasathi are both local-first AI assistants. Both run on your own hardware. Both handle personal data. In February 2026, OpenClaw had a very bad month — and the lessons aren't what you might expect.

Quick Context: gharasathi's Setup

gharasathi runs on a ByteNUC mini PC using Talos Linux — an immutable, minimal OS built for Kubernetes. No SSH. No shell. No package manager.

LAN only. No port forwarding. No public IP. The only way to reach these services is to be on my home Wi-Fi.

What Happened to OpenClaw

OpenClaw (formerly Clawdbot) is an open-source AI agent that went viral in early 2026 — 150K+ GitHub stars. It's also local-first: you install it on your machine, it stores data locally, and it connects to LLMs for task automation.

But OpenClaw is far more ambitious than gharasathi. It can execute shell commands, control browsers, send emails, and automate multi-step workflows. It integrates with WhatsApp, Telegram, and Slack. It has a community marketplace (ClawHub) for third-party skills. gharasathi just queries a database and explains the results in natural language.

That difference in scope turned out to matter a lot. In February 2026, multiple security teams published findings within days of each other:

CVE-2026-25253: One-Click RCE (CVSS 8.8)

A browser-based attack that let attackers hijack any OpenClaw instance — even ones running only on localhost. A user visits a crafted webpage, JavaScript steals the gateway token via WebSocket, and the attacker gains full operator access: disable security features, escape Docker containers, execute arbitrary commands on the host. (The Hacker News)

This is worth pausing on. OpenClaw was running locally. It was listening on localhost. And it was still compromised — because the victim's own browser initiated the connection. "Local" alone doesn't mean "secure."

Misconfigured Instances Leaking Data

Users who exposed their OpenClaw instances to the internet — against best practices — were found leaking API keys, chat histories, and credentials. Some had zero authentication. (Trend Micro)

341 Malicious Skills in ClawHub

Security researchers found 341 malicious packages on ClawHub, OpenClaw's community marketplace. These impersonated legitimate tools but contained Atomic Stealer malware and ClawHavoc C2 implants — harvesting SSH keys, browser passwords, crypto wallet keys, and API tokens. (The Hacker News, The Register)

The Honest Comparison

It would be easy to say "gharasathi is local, therefore safe" — but OpenClaw is local too. The RCE vulnerability worked on localhost. "Runs on your machine" is not a security strategy.

The actual differences that matter are about scope and attack surface:

	OpenClaw	gharasathi
What can the AI do?	Execute code, send emails, control browsers, shell access	Query Neo4j (read-only), explain results
External integrations	WhatsApp, Telegram, Slack, browser automation	None — LAN-only chat interface
Plugin/skill marketplace	ClawHub (2,800+ community skills)	None — all code in monorepo
Cloud API keys	GPT-4, Claude, Gemini keys in local config	None — local Ollama only
Blast radius if compromised	Full host access, all connected services	Read access to household data

The RCE vulnerability (CVE-2026-25253) is a browser-based WebSocket attack. Could something similar affect gharasathi? Honestly — yes, in principle. Any service with a web interface is potentially vulnerable to browser-based attacks. I won't pretend otherwise.

But the blast radius is fundamentally different. If someone compromised OpenClaw, they got shell access, email sending, browser control, and every API key stored locally. If someone compromised gharasathi's chat interface, they'd get... read-only access to my grocery spending and photo metadata. The LLM can't execute code. It can't send messages. It can't modify data. It queries Neo4j and formats the response.

This Is a Trade-Off, Not a Win

I want to be clear: OpenClaw's broader scope is exactly what makes it useful. People use it to automate real workflows — managing emails, booking flights, controlling browsers, orchestrating multi-step tasks across services. gharasathi can't do any of that. It answers questions about household data. That's it.

OpenClaw with 150K+ GitHub stars solves problems that gharasathi doesn't even attempt. The shell access, the messaging integrations, the plugin marketplace — those features exist because users need them. Removing them isn't a security strategy anyone building a general-purpose AI agent can adopt.

gharasathi gets away with a narrow scope because it was designed for a narrow purpose: surface household data in natural language. That's a fundamentally different ambition from what OpenClaw is trying to do, and comparing them on security alone misses the point. The security comparison is only meaningful if you understand that these tools serve very different needs.

What I Actually Learned

Three takeaways from watching OpenClaw's February:

1. "Local-first" is necessary but not sufficient. Running on your own hardware avoids cloud data exposure, but it doesn't protect against browser-based attacks or supply chain compromises. Don't confuse deployment model with security model.

2. Scope is your best defense. The most effective security decision in gharasathi isn't the network topology — it's that the LLM can only read data and explain it. No code execution. No external integrations. No plugins. Every capability you add is attack surface you have to defend.

3. Marketplaces need guardrails. Plugin ecosystems are how tools like OpenClaw scale — 2,800 community skills is an incredible achievement. But 341 of them were malicious, and they ran with the same permissions as the core agent. The lesson isn't "don't have a marketplace" — it's that plugins touching personal data need sandboxing, permission scoping, and review processes that match the sensitivity of what they can access.

Where This Stands

gharasathi is still an MVP. The architecture works: graph database for structured household data, local LLM for natural language, Kubernetes for orchestration, all on a $200 mini PC.

What's proven:

Neo4j handles household data relationships elegantly
A small LLM (phi3:mini) works for structured query-and-explain
K8s resource limits keep 5 services running in 6GB RAM
Minimal scope limits blast radius even if something goes wrong

What's not:

The LLM can't do real analysis (needs hardware upgrade for larger models)
Photo processing isn't implemented yet
It's a one-household system, not a product

The Idea Scales

The current MVP handles finances and photos, but the core idea — put your household data in a graph, give it a natural language interface — extends to almost anything: health records, home energy usage, kids' school schedules, vehicle maintenance, meal planning. Each new data domain is just another node type in Neo4j with relationships to what's already there. The query patterns stay the same: start at a node, walk relationships, explain the result.

The interface scales too. Right now it's chat. But the same LangGraph pipeline that answers a typed question could answer a spoken one — swap the text input for speech-to-text and the response for text-to-speech. The architecture doesn't change. The hardware constraints are the real bottleneck for now, not the design.

I'm not open-sourcing gharasathi. The codebase contains patterns specific to my household's financial accounts and data structure. Releasing it would require sanitizing all of that, and "privacy-first project accidentally leaks developer's banking patterns" is exactly the kind of irony I'd rather avoid.

Your most personal data — your finances, your photos, your family's memories — deserves to stay personal. Not discoverable on Shodan. Not accessible through a marketplace plugin you didn't audit. Just yours, on a box in your garage.

This is Part 3 of a 3-part series. Use the series navigation above to read Part 1 (Architecture & Neo4j) and Part 2 (LLM Model Selection).

Sources:

Running an LLM on 6GB RAM — Model Selection for Edge AI

Koustubh — Sun, 08 Feb 2026 03:58:12 +0000

The hardest part of building a self-hosted AI isn't the architecture — it's choosing the right LLM for your actual use case and your actual hardware. A multimodal model that understands images is pointless when your task is explaining bank transactions. A model that tops benchmarks is useless if it takes 20 seconds to respond on your CPU. Here's what happened when I learned both lessons.

The Hardware

The entire gharasathi system runs on a ByteNUC mini PC:

Spec	Value
CPU	Intel (no discrete GPU)
RAM	6GB total
Disk	2TB SSD
OS	Talos Linux (immutable, K8s-native)
Cost	~$200

6GB RAM. That's it. And it needs to run the OS, Kubernetes, Neo4j, four microservices, and an LLM.

The Memory Budget

Every megabyte matters. Here's how the 6GB is carved up, based on actual K8s resource limits from our deployment manifests:

Service	K8s requests	K8s limits	Notes
Ollama sidecar	2Gi	3Gi	LLM inference engine
FastAPI (aapla-hushar)	512Mi	1Gi	Python service
Neo4j	512Mi	1Gi	Graph database
aapla-dhan	256Mi	512Mi	Go finance service

The LLM service gets ~3GB total (Ollama + FastAPI together in one K8s pod via sidecar pattern). After the Python runtime, FastAPI, and LangChain dependencies eat ~500MB, the actual model has roughly 2.5GB to work with.

The Model Selection Journey

I evaluated 15+ open-source models across four tiers. The question: what's the best LLM you can run in ~2.5GB?

The top 5 candidates that passed the filter:

Model	Size	Context	Key Strength
Qwen3:4b	2.5GB	256K	Rivals 72B performance
Phi-3-mini	2.2GB	128K	Strong reasoning (Microsoft)
Llama 3.2-3B	2.0GB	128K	Instruction following
Qwen2.5-3B	1.9GB	32K	Good coding/math
Gemma3-4B	3.3GB	128K	Multimodal (images)

The research was clear: Qwen3:4b was the winner. 2.5GB, 256K context window, benchmarks rivaling 72B models. A no-brainer.

Reality Disagreed

I deployed Qwen3:4b to the ByteNUC. It fit in memory. It loaded fine. Then I asked it a question.

Problem 1: Painfully slow. On a CPU-only Intel NUC with 6GB RAM, Qwen3:4b took 15-20+ seconds for simple responses. For a household chat assistant, that's unusable. You ask "how much did I spend on groceries?" and wait long enough to check the bank app yourself.

Problem 2: Hallucinations in Chinese. Qwen3 is a multilingual model supporting 100+ languages. On constrained hardware with limited context, the model would occasionally bleed into Chinese mid-response. Great for a multilingual product. Confusing for a household assistant that only needs English.

The benchmarks didn't lie — Qwen3:4b is a remarkable model. But benchmarks run on A100 GPUs with 80GB VRAM, not on a $200 mini PC with shared system RAM and no GPU.

The Downgrade

I switched to phi3:mini (Microsoft's Phi-3 Mini, 3.8B parameters, 2.2GB):

	Qwen3:4b	phi3:mini
Size	2.5GB	2.2GB
Context	256K	128K
Speed on ByteNUC	15-20s+	3-7s
Language stability	Occasional Chinese bleed	Stable English
Benchmark ranking	Higher	Lower
Actually usable?	No	Yes

phi3:mini is less capable on paper. Smaller context window. Lower benchmark scores. But it responds in seconds, stays in English, and gives coherent answers about household data. That's what matters.

Lesson: benchmarks ≠ real-world performance on constrained hardware. Test on your actual target device, not on specs.

A Note on Choosing Models for Constrained Hardware

A few things I wish I'd prioritized earlier in the evaluation:

Quantized models matter. On hardware like this, quantized variants (Q4_0, Q4_K_M) are far more practical than full-precision weights. They reduce memory footprint and improve inference speed with minimal quality loss. All the Ollama models above are already quantized — that's how a 4B parameter model fits in 2.5GB.
Match the model to the task, not the leaderboard. A multimodal model that understands images is wasted when your use case is explaining bank transactions. A model with a 256K context window is overkill when your prompts are 200 tokens. Pick for what you actually need.
CPU inference is slow — plan for it. Even with phi3:mini, responses take around 30 seconds end-to-end on the ByteNUC. That's liveable for a household assistant you check a few times a day, but it rules out anything conversational or real-time. If you need snappy responses, you need a GPU or a smaller model.

Why the LLM Barely Matters

Here's the counterintuitive insight that makes a smaller model viable: the LLM is just the natural language interface. Neo4j does the heavy lifting.

The architecture follows a "tools first, LLM explains" pattern:

Intent classification is deterministic keyword matching — no LLM needed
Data retrieval uses specialized tools that run Cypher queries against Neo4j
The LLM only translates between natural language and presenting structured results

The LLM never calculates, never queries, never decides what data to fetch. It receives pre-fetched results and writes a human-readable response. For that job, phi3:mini is more than sufficient.

From the actual code (aapla-hushar/src/agents/graph.py):

# Deterministic routing — no LLM involved
finance_keywords = ["spend", "expense", "budget", "transaction", ...]
if any(k in last_message for k in finance_keywords):
    intent = "finance"

# Tools fetch data first, then LLM explains
data = get_spending_summary()  # Cypher query to Neo4j
response = llm.invoke([
    SystemMessage(content="You are a financial assistant."),
    HumanMessage(content=f"ONLY interpret this data:\n{data}")
])

The Ollama sidecar runs alongside FastAPI in the same K8s pod — localhost communication, zero network latency between the Python service and the LLM.

Future: Better LLM Requires Better Hardware

The current setup works for structured queries against Neo4j. But for actual data analysis — "what trends do you see in my spending?" or "suggest ways to save money" — the model needs to reason over larger contexts with more capability.

That upgrade means upgrading the ByteNUC's RAM first. A 7B or 8B model needs 8-16GB total system memory. Until then, phi3:mini handles the structured query-and-explain pattern well.

What's Next

The model runs. The queries work. But is "runs locally" enough to keep your data safe?

In Part 3, I look at what happened to OpenClaw — another local-first AI assistant — and why the real security lesson isn't about where your AI runs, but what it's allowed to do.

This is Part 3 of a 3-part series. Use the series navigation above to read Part 1 (Architecture & Neo4j) and Part 3 (What OpenClaw Teaches Us).

gharasathi (घरासाठी) — A Privacy-First Household AI Running on a $200 Mini PC

Koustubh — Sun, 08 Feb 2026 03:58:11 +0000

gharasathi ("for home" in Marathi) is a privacy-first household AI that connects finances, photos, and memories — running entirely on a $200 mini PC in my garage. No cloud. No subscriptions. No data leaving the house.

The Problem

Household data is scattered everywhere. Bank transactions in three different apps. Photos split across iCloud and Google Photos. Bills in s or individual company portals. Memories in your head.

Every "smart" assistant that promises to unify this — Alexa, Google Home, ChatGPT — requires shipping your most intimate data to someone else's servers. Your spending patterns. Your family photos. Your location history. All flowing through infrastructure you don't control, governed by privacy policies that change quarterly.

I wanted something different: a private AI that ties all household data together and runs entirely on my home network. Something I could ask "How much did we spend during the Christmas trip?" and get an answer by traversing actual data, not hallucinating one. Something where the answer to "where is my data?" is always "in the living room."

Architecture

The system is a set of microservices on Kubernetes. All services are named in Marathi — the language spoken in western India.

Service	Language	Role
aapla-dhan (आपलं धन)	Go	Finance — syncs bank transactions, loans, investments
aaplya-athvani (आपल्या आठवणी)	Go	Memories — photo sync, tagging, storage
aapla-hushar (आपला हुशार)	Python + LangGraph	AI chat — intent routing, agents, Ollama sidecar
aapla-mahitisatha (आपला माहिती साठा)	Neo4j	Graph database for all structured data
gharasathi-ios	Swift/SwiftUI	Native iOS app
gharasathi-web	React/TypeScript	Browser interface

Everything runs on a single ByteNUC mini PC — 6GB RAM, 2TB disk, no GPU — running Talos Linux. The entire stack — OS, K8s, database, LLM, and all services — fits in that 6GB with CPU-only inference.

A core design principle: services write data to Neo4j, and the LLM reads from it. The AI layer never modifies your data — it only queries and explains. This separation means the LLM can be swapped, restarted, or upgraded without any risk to your actual records.

Why Neo4j?

Household data is inherently a graph. People own accounts. Accounts generate transactions. Transactions happen at places. Photos feature people at events. Events are held at places. Places contain other places.

The schema has 6 node types and 17 relationship types — from OWNS and SOURCE_OF to FEATURES, SIMILAR_TO, and LOCATED_IN. This density of connections is exactly what graph databases excel at.

Consider what "our Sydney trip" means in data terms. It's an Event node connected to: Transaction nodes (what we spent), Photo nodes (what we captured), Person nodes (who went), and Place nodes (where we went) — which themselves link upward via LOCATED_IN to "Sydney" to "NSW" to "Australia." In a relational database, that's a normalized nightmare. In a graph, it's just… the shape of the data.

The Query That Sells It

"How much did we spend during the Christmas trip?"

In a relational database, this requires JOINing across 4+ tables: events, transactions, places, and a trip-transaction mapping table. In Neo4j, it's a single traversal:

MATCH (e:Event)
WHERE e.title CONTAINS 'Christmas' AND e.startDate.year = 2025
OPTIONAL MATCH (e)<-[:PART_OF]-(photo:Photo)
OPTIONAL MATCH (e)<-[:RELATED_TO]-(t:Transaction)
OPTIONAL MATCH (e)<-[:ATTENDED]-(person:Person)
RETURN e.title,
  collect(DISTINCT person.name) as attendees,
  count(DISTINCT photo) as photos,
  sum(t.amount) as totalSpent

One query. It starts at the Christmas event node, walks outward along relationships, and gathers everything connected: who attended, how many photos were taken, and the total cost. No JOINs. No subqueries. The relationships are the schema.

This pattern repeats across every use case:

"What are my top spending categories?" — aggregate Transaction nodes by category
"Show photos from the reef trip" — traverse Photo → PART_OF → Event
"Find photos similar to this one" — vector similarity search on embeddings
"What did we do last year?" — walk Events by date, gather connected Transactions and Photos
"Show spending by location" — traverse Transaction → OCCURRED_AT → Place

The query file has 25+ patterns covering financial analysis, photo search, people lookup, event timelines, and cross-domain insights. Every one of them follows the same shape: start at a node, walk relationships, aggregate what you find.

Vector Search Built In

Neo4j 5.11+ supports native vector indexes. Every Photo, Transaction, and Event node carries a 1536-dimension embedding vector. This enables semantic search without a separate vector database:

CALL db.index.vector.queryNodes('photo_embedding', 5, p.embedding)
YIELD node, score
RETURN node.filename, node.aiDescription, score

"Find sunset photos" doesn't need exact keyword matching — it searches by meaning. No separate Pinecone or Weaviate instance needed — one database handles both structured queries and semantic search.

Dual Storage: Graph + Object

One thing Neo4j shouldn't store is binary files. Photos and videos go to MinIO — a self-hosted, S3-compatible object store. Neo4j holds the metadata (who's in the photo, where it was taken, AI-generated description, embedding vector) while MinIO holds the actual JPEG. The Photo node's storagePath property links the two.

This keeps Neo4j lean — critical when you're running it in 1GB of RAM — while MinIO happily stores terabytes of photos on the 2TB disk.

What's Next

The architecture makes sense on paper. But how do you run Neo4j + an LLM + 4 microservices on a machine with only 6GB RAM?

In Part 2, I cover the model selection journey — where research recommended one model, reality disagreed, and I had to learn the hard way that benchmarks don't mean much on constrained hardware.

This is Part 1 of a 3-part series on building a privacy-first household AI. Use the series navigation above to read Part 2 (LLM Model Selection) and Part 3 (Privacy & Lessons from OpenClaw).

Building Apps with AI: Deep Dive into beads Workflow

Koustubh — Tue, 20 Jan 2026 22:25:56 +0000

Building Apps with AI: Deep Dive into beads Workflow

Part 2 of 2: JSONL Memory, Real Examples, and Honest Drawbacks

Recap

In Part 1, I introduced beads — a git-native issue tracker designed for AI-assisted development. We looked at the Mission House app and the basic workflow. Now let’s go a bit deeper.

Scope and Assumptions

This post reflects a solo, AI-assisted development workflow on a small but non-trivial codebase (dozens of tasks, explicit dependencies, multiple external APIs).

Assumptions:

The AI agent has read access to the full issue graph
Execution efficiency matters more than prolonged design deliberation

For ambiguous product discovery, multi-team coordination, or regulated environments, spec-driven approaches may be a better first step.

The JSONL Advantage: Compact and Queryable

Every beads issue is stored as a single line of JSON in .beads/issues.jsonl:

{
  "id": "mission-house-ogp",
  "title": "Implement myschool.edu.au scraper",
  "description": "Create Puppeteer-based scraper...",
  "status": "closed",
  "priority": 1,
  "close_reason": "NAPLAN scraper implemented in server.js",
  "dependencies": [{ "depends_on_id": "mission-house-5mv" }]
}

Compare this to a typical markdown task file that might span dozens of lines with headers, descriptions, and nested checklists for the same information.

Why Compact Matters

The AI gets structured data it can query, not prose it must interpret:

bd ready - What's unblocked and highest priority?
bd blocked - What's waiting on other work?
bd show <id> - Full details on one issue
bd stats - Project health at a glance

Close Reasons: Implementation Memory

When you close an issue, you document what was actually built:

bd close mission-house-ogp --reason="NAPLAN scraper implemented in server.js, handles terms acceptance and score extraction"

This is not just status — it’s ground truth.

Specs capture intent.
Close reasons capture reality.

Real Example: Session Continuity

Here's what happened when I resumed work on NAPLAN scoring after a break:

Session 1 (ended with):

bd close mission-house-ogp --reason="NAPLAN scores integration complete: scraper implemented in server.js"

Session 2 (started with):

> bd ready

mission-house-6t1 [P2] [task] open - Display NAPLAN scores in UI
  └─ Blocked by: mission-house-ogp (closed), mission-house-0ch (closed)
  └─ All blockers resolved - ready to work!

Claude immediately knew:

The scraper was done (from ogp's close reason)
The schema was updated (from 0ch's close reason)
The next logical step was UI display

No manual context re-establishment was needed, because dependencies and implementation details were already encoded.

The Hierarchy: Epics → Features → Tasks

We organized Mission House using a three-level hierarchy:

Why This Structure Works

Level	Purpose	Typical Count	Lifetime
Epic	Strategic goal, multiple sessions	2-5 per project	Weeks
Feature	User-facing capability	5-15 per epic	Days
Task	Single implementation unit	3-10 per feature	Hours

The AI works at the task level but understands the feature and epic context.

Real Issues from Mission House

Let me show you actual issues from our project to illustrate different patterns:

Pattern 1: Task with Clear Dependencies

{
  "id": "mission-house-73p",
  "title": "Calculate Flinders Street Station travel time",
  "description": "Calculate travel time to Flinders Street Station during peak hours on a working day from: (a) the nearest train station, (b) the property address directly.",
  "status": "closed",
  "priority": 2,
  "issue_type": "task",
  "close_reason": "Implemented MapsService.getTravelToFlinders() with peak hour scheduling. Calculates transit, driving, walking routes from property and via nearest station",
  "dependencies": [
    {
      "depends_on_id": "mission-house-utk",
      "type": "blocks"
    }
  ]
}

What the AI learned from this:

Can't calculate commute until "Find nearest train station" (utk) is done
Implementation went into MapsService.getTravelToFlinders()
Peak hour scheduling was added
Multiple route types were implemented

Pattern 2: Bug with Acceptance Criteria

{
  "id": "mission-house-v4e",
  "title": "Fix naplan score web scraping logic",
  "description": "Naplan score web scraping not working as expected. Check the requirements document",
  "acceptance_criteria": "Naplan score written in json file as in the requirements document",
  "status": "closed",
  "priority": 0,
  "issue_type": "bug",
  "close_reason": "Implemented naplan_quality metric: added benchmark constants, quality calculation function, and UI display in both hub-spoke view and compare page radar chart"
}

Priority 0 (P0) is the highest priority level. The AI knew to work on this first.

Pattern 3: Tombstone (Deleted Issue)

{
  "id": "mission-house-ck6",
  "title": "Implement spider/radar chart visualization",
  "status": "tombstone",
  "deleted_at": "2026-01-17T23:15:21.909135+11:00",
  "deleted_by": "batch delete",
  "delete_reason": "batch delete",
  "original_type": "task"
}

Tombstones preserve history while removing clutter. The AI knows this was deleted and won't try to work on it.

beads vs. agent-os (an SDD Framework)

Spec-Driven Development (SDD) is a methodology - different tools implement it differently. Let's compare beads to agent-os, one popular SDD framework.

Note: This comparison is specific to agent-os. Other SDD implementations may work differently.

Two Different Philosophies

agent-os follows a six-phase workflow:

Plan Product → 2. Shape Spec → 3. Write Spec → 4. Create Tasks → 5. Implement → 6. Orchestrate

It uses layered context (Standards/Product/Specs) in markdown files. Tasks are derived from specs.

beads is task-first:

Create issues → 2. Add dependencies → 3. Run bd ready → 4. Implement

No ongoing spec phase was required. A lightweight requirements document seeded the task graph, after which dependencies were tracked as explicit graph edges rather than implied through prose.

Comparison Table (agent-os vs beads)

Aspect	agent-os	beads
Philosophy	Spec-first	Task-first
Persistence	✅ MD files in git	✅ JSONL in git
Context layers	Standards/Product/Specs	Flat issue list
Task creation	Derived from specs	Created directly (or through a file input)
Dependencies	Implicit in spec narrative	Explicit graph edges
"What's next?"	Derived from spec phase	`bd ready` computes it
Upfront design	Required (spec phases)	Optional
Best for	Complex features needing design	Iterative, fast-moving work

When to Use Which

Use agent-os (or similar SDD frameworks) when:

Complex features - You need to think through architecture before coding
Team alignment - Specs help communicate intent to other humans
Stakeholder buy-in - Non-technical people need to review plans
Regulated industries - Formal specs may be required

Use beads when:

Fast iteration - You want to jump straight to tasks
Clear requirements - You already know what to build
Dependency-heavy work - Many tasks blocking each other
Solo or AI-assisted - Less need for human-readable specs

Can You Use Both?

Yes. You could:

Use SDD's planning phases to think through architecture
Export tasks to beads for execution with graph-based tracking
Keep high-level context in a README, detailed execution in beads

My approach: For Mission House, I skipped formal specs and went straight to beads. The requirements doc was enough context - I didn't need a full SDD workflow for a personal project.

The Drawbacks: What Didn't Work

Let me be honest about the challenges:

1. Learning Curve

The CLI commands take time to internalize. bd dep add A B means "A depends on B" (B blocks A) - I got this backwards several times.

2. Sync Conflicts

When working across multiple branches or machines, sync conflicts can occur:

> bd list
💡 Tip: Run 'bd sync' to resolve sync conflict

The fix is usually simple (bd sync --from-main), but it's an extra step that spec documents don't have.

3. Over-Granularity Temptation

It's tempting to create a task for everything:

# Too granular - don't do this
bd create --title="Add import statement for React"
bd create --title="Create empty component file"
bd create --title="Add basic JSX structure"

Better: One task for "Create React component for X with basic structure"

4. Daemon Startup Delays

Occasionally the beads daemon takes time to start:

> bd list
Warning: Daemon took too long to start (>5s). Running in direct mode.

Not a blocker, but noticeable.

5. No Visual Dashboard

This is not entirely true. You have a lot of community built dashboards available here which will make your life much easier.

Advanced Features We Used

Bulk Operations

When we had duplicate issues, we cleaned up with:

bd delete mission-house-ck6 mission-house-d1s mission-house-hqs --reason="batch delete" --force

This created tombstones preserving the history.

Priority System

beads uses P0-P4 priorities:

Priority	Meaning	Our Usage
P0	Critical	Blocking bugs
P1	High	Core features
P2	Medium	Most tasks
P3	Low	Nice-to-haves
P4	Backlog	Future ideas

Close Reasons

Always close with a reason:

bd close mission-house-qvs --reason="Added Google Maps API with Places and Geometry libraries. MapsService provides geocoding, directions, nearest station search, and autocomplete"

This becomes searchable context for future sessions.

Integrations

beads also supports syncing with Jira if your team needs to keep stakeholders updated in traditional issue trackers.

Project Timeline Visualization

Here's how our project actually progressed:

Total active development time: ~3 hours across 2 days

Final Thoughts

beads and SDD frameworks like agent-os represent different philosophies:

SDD frameworks say: "Think first, spec it out, then derive tasks"
beads says: "Create tasks directly, let the graph handle prioritization"

Neither is universally better. SDD frameworks shine when you need upfront design and human-readable documentation. beads shines when you want to move fast with automatic dependency resolution.

What makes beads unique:

Task-first workflow - Skip straight to issue creation
Graph-based dependencies - Explicit edges, not prose to interpret
Automatic prioritization - bd ready computes what's next via graph traversal
Compact JSONL - High signal-to-noise ratio as projects grow

The Mission House project went from idea to working app in about 3 hours of active development, spread across multiple sessions. The graph kept track of what was blocked, what was ready, and what was done - no spec documents required.

Choose the approach that fits your project. Or use both.

Resources

Thanks for reading! If you try beads on your next AI-assisted project, I'd love to hear how it goes.

Building Apps with AI: How beads Changed My Development Workflow

Koustubh — Tue, 20 Jan 2026 22:25:54 +0000

Building Apps with AI: How `beads` Changed My Development Workflow

Part 1 of 2: From Spec Documents to Living Issue Trackers

TL;DR

I built a real estate comparison app using Claude Code and a tool called beads - a git-native issue tracker designed for AI-assisted development. This post explores how beads transformed my workflow from writing lengthy spec documents to having a living, breathing project tracker that my AI assistant actually understands.

Source Code: GitHub Repository
Live Demo: Mission House App - This is a SPA with no backend, so it requires a Google Maps Platform API key to be provided on the UI to render fully. Have a look at the snapshots in the source code repository above to get an idea of the app.

Spec-Driven Development (SDD)

If you've used AI coding assistants for larger projects, you've likely encountered Spec-Driven Development (SDD) - a methodology where detailed specifications drive the implementation process. I've written about SDD in detail previously - it's a powerful approach that works well for many projects. Different frameworks implement SDD differently.

One popular implementation is agent-os, which formalizes SDD into a six-phase workflow:

agent-os uses layered context (Standards → Product → Specs) stored in markdown files like mission.md, roadmap.md, and tech-stack.md. Tasks are derived from specs, not created directly.

agent-os works well, but has trade-offs:

Spec-first philosophy - You write specs before creating tasks
Tasks derived from prose - The AI interprets specs to generate tasks
Layered context - Rich documentation, but more files to maintain
Sequential phases - Structured workflow from planning to orchestration

SDD frameworks like agent-os are great for complex features that need upfront design. But what if you want to skip straight to task management?

The key difference is where control flow lives:

In SDD, control flow is implicit in prose.
In beads, control flow is explicit in a DAG.

To be clear: SDD shines when architectural intent must be stabilized early — beads optimizes for execution once intent is roughly understood.

Enter `beads`: Task-First with Graph-Based Dependencies

Beads is what its creator Steve Yegge calls "a drop-in cognitive upgrade for your coding agents." Instead of the spec-first approach, beads is task-first - you create issues directly, with explicit dependencies stored as graph edges.

1. Compact JSONL, Not Verbose Markdown

.beads/
├── issues.jsonl    # All issues in ONE compact file
├── config.yaml     # Project configuration
└── db.sqlite       # Local cache for fast queries

One line per issue. No walls of prose. The AI can quickly parse the entire project state:

{
  "id": "mission-house-ogp",
  "title": "Implement scraper",
  "status": "closed",
  "dependencies": [{ "depends_on_id": "mission-house-5mv" }]
}

2. Automatic "What's Next?" via Graph Traversal

This is the killer feature. Instead of the AI parsing prose to figure out order of execution:

bd ready  # Shows only unblocked, high-priority tasks

The graph database computes eligibility automatically based on explicit status, dependencies, and user-defined priority.

3. Explicit Dependencies = Enforced Execution Order

bd dep add mission-house-abc mission-house-xyz
# "abc depends on xyz" (xyz blocks abc)

This isn't prose that might be ignored - it's a graph edge. The AI literally cannot see abc in bd ready until xyz is closed.

Quick Start: Installing beads

For macOS users:

brew tap steveyegge/beads
brew install bd

# Initialize in your project
cd your-project
bd init

Other options: npm install -g @beads/bd or go install github.com/steveyegge/beads/cmd/bd@latest

That's it. You now have a .beads directory in your repo.

Also install the beads claude code plugin following this.

The App: Mission House

Before diving deeper into beads, let me briefly introduce what we built. Mission House is a property comparison tool for Melbourne house hunters. It helps answer questions like:

Which catchment schools serve this address?
How do their NAPLAN scores compare to each other?
How long is the commute to the CBD?
How do these 4 properties compare on a radar chart?

The interesting part isn't the app itself - it's how we built it using beads.

How I Used beads: A Real Example

Although beads is task-first, I didn’t start from a blank slate.

I began with a lightweight requirements.md that described:

core user flows
data sources (e.g. NAPLAN, Google Maps)
output expectations (comparison metrics, charts)

I then asked Claude Code (with beads installed) to:

Read requirements.md
Propose epics, features, and tasks
Encode them directly into beads issues with explicit dependencies

In other words, requirements existed, but they were treated as input, not as a continuously consulted execution artifact.

Once the task graph existed, beads became the primary source of truth.

Here's where the magic happens. When I started my next Claude Code session:

> bd ready

mission-house-5mv [P1] [task] open - Set up frontend project structure
  └─ No blockers - ready to work!

Claude immediately knew what to work on. No spec re-reading, no context reconstruction - just:

> bd update mission-house-5mv --status=in_progress

And we're coding.

The Dependency Graph

Here's what our project looked like after the initial planning:

Every arrow represents a bd dep add command. The AI knows it can't work on "Web Scraper" until "URL Input Form" is done.

What's Coming in Part 2

In the next post, I'll dive deep into:

The JSONL Advantage - How storing issues in plain text gives AI assistants "long memory"
Workflow Patterns - Epics → Features → Tasks hierarchy
Real Issue Examples - Actual JSON from our project
beads vs. Spec-Driven Development - A detailed comparison
The Drawbacks - What didn't work so well
Advanced Features - Tombstones, sync branches, and multi-session workflows

Key Takeaways

Task-first vs. spec-first - beads lets you create issues directly; SDD requires specs first
Graph-based dependencies - Explicit edges, not prose to interpret
bd ready is the killer feature - Automatic prioritization via graph traversal
Enforced execution order - Blocked tasks are invisible until unblocked

Continue to Part 2: Deep Dive into beads Workflow →

Part 5: Building Station Station - Should You Use Spec-Driven Development?

Koustubh — Tue, 04 Nov 2025 05:46:51 +0000

We've covered a lot in this series. In Part 1, we introduced Spec-Driven Development. In Part 2, we explored the Station Station project—8 features solving a real hybrid work compliance problem. In Part 3, we walked through the agent-os workflow. In Part 4, we got honest about the challenges and limitations.

Now for the decision: Should you use SDD for your next project?

This part gives you a decision framework based on real experience, not theory. No marketing fluff—just practical guidance on when SDD makes sense and when it's overkill.

What We Actually Built

Let's recap what the SDD approach delivered for Station Station:

The Project:

Personal web application for tracking office attendance via Melbourne Myki transit data
8 features across 3 phases (Foundation, Data Layer, Integration & UI)
Live and deployed at https://koustubh25.github.io/station-station/
Fully autonomous daily execution via GitHub Actions
Zero hosting costs (GitHub Pages + GitHub Actions free tier)

The Tech:

~6,000 lines of code (3,500 Python + 2,500 React)
Python backend with Playwright for browser automation and Cloudflare bypass
React frontend with Tailwind CSS v4, responsive mobile-first design
Lighthouse scores 95+ across the board

The Timeline:

~4-5 hours on specs
~2 days on implementation
~4-6 hours debugging hard problems (Cloudflare, timezone, multi-layer integration)
Total: ~3 days for 8 features shipped and deployed

The Result:
I use this app regularly to check my attendance compliance. It solves my actual problem. All planned features are complete. I can (and did) add new features weeks later by creating new specs and following the same workflow.

When to Use Spec-Driven Development

Based on the Station Station experience, here's when SDD is worth the upfront investment:

✅ Use SDD When:

1. You're building a complete project, not just prototyping

If you want to actually ship something and maintain it, SDD helps you finish. The structure prevents the "60% complete and abandoned" problem that plagues side projects.

Station Station could have easily become another abandoned project. Authentication alone took 2 days to solve. Without the roadmap keeping me focused on the goal, I might have given up after Cloudflare kept blocking me.

2. You'll be coming back to the code later

If there's any gap between coding sessions (days, weeks, months), the documentation is invaluable. The spec tells you what you were building and why. The task list shows what's done and what's next.

I added the manualAttendanceDates feature a week after the initial deployment. The existing specs told me exactly how the system worked, where to add the new field, and what components would be affected.

3. You're working solo or on a small team

SDD provides structure when you don't have teammates to keep you accountable. The roadmap prevents scope creep. The task breakdown prevents getting overwhelmed.

For Station Station, I was the only developer. The workflow kept me organized and prevented me from jumping between random features.

4. The project involves multiple components or layers

When your project has backend + frontend, or data extraction + processing + visualization, specs help you think through the integration points upfront.

Station Station has Python backend, GitHub Actions automation, and React frontend. The specs documented how data flows between these layers, which made debugging multi-layer issues much easier.

5. You want to learn a structured development process

If you're tired of chaotic development and want to build better habits, SDD provides a framework. The first project has a learning curve, but future projects benefit from the workflow.

6. You're solving a non-trivial problem

Simple CRUD apps or one-off scripts don't benefit much from SDD. But if your problem has complexity (Cloudflare bypass, API reverse engineering, browser automation), the structure helps you tackle it systematically.

❌ Skip SDD When:

1. You're doing quick experiments or throwaway code

If you're testing an idea and will likely discard the code, specs are overkill. Just write code and see if the idea works.

2. You have a crystal-clear mental model

If you've built this exact thing 10 times before and know every step, specs won't add much value. You already have the structure in your head.

3. The project is extremely simple

A single-file script, a basic static site, or a trivial automation doesn't need specs. Just write it.

4. You're under extreme time pressure

If you need something working in the next 2 hours, don't spend 30 minutes on a spec. But recognize you're trading speed now for maintenance pain later.

5. You're learning a completely new technology

If you're learning React for the first time, just following tutorials and experimenting might be better than trying to spec everything out. Learn first, then apply structure to real projects.

Decision Framework

Here's a simple decision tree:

Is this a real project you want to finish and maintain?
├─ No → Skip SDD, just code
└─ Yes ↓

Will you be working on this over multiple sessions?
├─ No → Skip SDD unless project is complex
└─ Yes ↓

Does the project involve multiple components/layers?
├─ No, single component → SDD optional
└─ Yes, multiple layers ↓

Are you working solo or small team?
├─ No, large team with existing processes → Evaluate SDD fit
└─ Yes ↓

→ USE SDD. The upfront investment will pay off.

The Honest Trade-offs

Let's be real about what you're signing up for:

What You Give Up:

Time to first code: Specs take time. You'll spend 30 minutes to several hours documenting before you write a single line of code.

Flexibility to "just try things": SDD encourages thinking before coding. If you like to experiment your way to a solution, the structure might feel constraining.

Simplicity: You're adding agent-os to your workflow. There's a learning curve. The first project takes longer.

What You Get:

Actually finishing projects: Structure prevents abandonment. The roadmap keeps you focused. The task breakdown prevents overwhelm.

Resumability: Come back weeks later and know exactly where you left off. No re-learning your own codebase.

Systematic debugging: When things break, the spec tells you what should happen. The task breakdown shows you where to look.

Documented decisions: Future you (or future contributors) can understand why things were built a certain way.

Less decision fatigue: The spec tells you what to build next. No "what should I work on today?" paralysis.

The Bottom Line:

SDD trades upfront time for higher completion rate and better maintainability.

If you care more about finishing than starting, SDD is worth it.

How to Get Started

If you've decided SDD might work for your next project, here's how to begin:

1. Try It With a Real Project

Don't practice with a tutorial. Pick an actual problem you want to solve. Station Station worked because I genuinely needed to track my attendance.

Your first SDD project will be slower. That's normal. The second project will be much faster once you internalize the workflow.

2. Start With Agent-OS

Agent-os is the tool I used for Station Station. It's built for Claude and provides the complete workflow: product creation, spec shaping, spec writing, task breakdown, and implementation.

Agent-OS Repository: https://github.com/cyanheads/agent-os
Getting Started Guide: Check the repository README for setup instructions

3. Try Station Station Yourself

Station Station is open source and free to use. If you're a Melbourne train commuter with hybrid work requirements:

Live Application: https://koustubh25.github.io/station-station/
GitHub Repository: https://github.com/koustubh25/station-station

Two options to get started:

Get onboarded to the existing app - See your attendance on the same GUI. Check the README for onboarding instructions.
Fork and deploy your own - Complete control and privacy. The README has full deployment instructions using GitHub Actions and GitHub Pages (all free).

The repository also includes complete specs for all 8 features and task breakdowns, so you can study the SDD approach in action.

4. Other SDD Tools

Agent-os isn't the only way to do Spec-Driven Development. Other tools exist like OpenSpec, Speckit, and others. However, I found some too simple (lacking the structure I needed) and others too verbose (overwhelming with process overhead). Agent-os struck a good balance for my workflow—structured enough to keep me organized, but not so heavy that it gets in the way of actually building.

Your preferences might differ. If agent-os doesn't feel right, explore the alternatives.

Final Thoughts

Spec-Driven Development isn't revolutionary. It's structure. It's documentation. It's thinking before coding.

It won't make you code faster. It won't eliminate bugs. It won't replace your judgment.

But it might help you finish instead of abandon. It might help you resume instead of restart. It might help you debug systematically instead of randomly.

For Station Station, that was enough. In 3 days, I went from "I need to track attendance" to a fully deployed application solving my real problem. Two weeks later, I added new features without re-learning the codebase. A month later, the app is still running autonomously, requiring zero maintenance.

Your mileage may vary. Your projects are different. Your workflow preferences are different.

But if you're tired of abandoned side projects, forgotten codebases, and chaotic development, maybe give SDD a try. Pick a real problem. Write a spec. Follow the workflow. See if it works for you.

And if you do try it—or if you've been using SDD and have your own experiences to share—I'd love to hear about it. Drop a comment, open a GitHub discussion, or reach out.

Thanks for reading this series. Now go build something.

Links:

Station Station Live App: https://koustubh25.github.io/station-station/
Station Station GitHub: https://github.com/koustubh25/station-station
Agent-OS GitHub: https://github.com/cyanheads/agent-os
OpenSpec GitHub: https://github.com/openspec-dev/openspec

Part 4: Building Station Station - Where SDD Helped (and Where It Didn't)

Koustubh — Tue, 04 Nov 2025 05:45:52 +0000

In Parts 1-3, we covered Spec-Driven Development, the Station Station project, and the agent-os workflow. We saw a structured process that delivered 8 features, fully deployed and working. But I've been painting a rosy picture. Let me be honest about the challenges.

This part is about the real development experience: Where did the structured SDD approach actually help? Where did I still struggle despite having specs and tasks? What problems can structure solve, and what problems require good old-fashioned debugging?

If you're considering SDD for your next project, this is the part you need to read. Because understanding what structure can and can't solve is critical to setting realistic expectations.

Challenge 1: Cloudflare Authentication Bypass

Let me start with the most frustrating part of the entire project: getting authentication to work with the Myki portal.

The Context:
The whole project depends on accessing Myki transaction data. No authentication = no data = no project. This was the critical blocker. Everything else was blocked until this worked.

The Problem:
The Myki portal is protected by Cloudflare Turnstile, which actively detects and blocks headless browsers. My first attempt using standard Playwright headless mode failed immediately with the "Verifying you are human..." overlay blocking form access.

The Spec:
"Use Playwright to authenticate with Myki portal and extract session tokens for API calls."

Simple requirement, right? But the spec didn't capture the complexity of Cloudflare bot detection.

How SDD Helped

The structured approach provided a framework for tackling this beast:

Clear success criteria: "Extract Bearer token from authentication response" - The spec told the AI (and me) exactly what success looked like, even if neither of us knew how to get there yet.

Task breakdown kept me focused: Instead of having the AI try to solve "make authentication work" all at once, the tasks broke it down into pieces:

Launch browser with Playwright
Navigate to login page
Fill in credentials
Submit form
Extract authentication tokens

When the AI's implementation of step 3 (fill in credentials) was blocked by Cloudflare, the task breakdown showed me exactly where the problem was.

Documentation of attempts: Each failed approach got documented in the spec as "out of scope" or "doesn't work because..." This prevented me from asking the AI to retry the same failed approaches days later.

What SDD Couldn't Solve

But here's the brutal truth: specs don't solve hard technical problems for you.

The AI tried implementing authentication multiple ways based on the spec. Each attempt failed. Over two days, I kept iterating:

Attempt 1: AI implements standard headless Playwright

browser = playwright.chromium.launch(headless=True)

Result: Blocked by Cloudflare immediately. "Verifying you are human..."

Attempt 2: I ask AI to try headed mode (visible browser)

browser = playwright.chromium.launch(headless=False)

Result: Better, but still detected as automation. Random CAPTCHA challenges.

Attempt 3: I ask AI to try user-agent and header spoofing

context = browser.new_context(user_agent="...")

Result: Cloudflare is smarter than that. Still blocked.

Attempt 4: AI tries stealth mode plugins
Result: Helped a bit, but not consistent. Sometimes worked, sometimes didn't.

The Solution (After Two Days of Frustration)

What finally worked: Browser profile trust signals

After researching Cloudflare bypass techniques, I figured out the solution and told the AI to implement it:

# Create empty Chrome profile directory structure
profile_dir = create_empty_chrome_profile()
# Launch with profile - appears as "real" browser to Cloudflare
browser = playwright.chromium.launch_persistent_context(
    user_data_dir=profile_dir,
    headless=False
)

The profile directory contains just enough metadata (Cookies, Preferences, History files - all empty) to make Playwright look like a legitimate Chrome browser instead of automation.

Why This Was So Frustrating

The spec couldn't help because:

This required deep knowledge of browser fingerprinting and bot detection
Solutions aren't documented well (Cloudflare actively tries to prevent bypass)
Trial and error was the only way to find what worked
Each attempt took 5-10 minutes to test (AI implements → I run the code → see if blocked)

What I actually needed to do:

Research how Cloudflare Turnstile detects automation
Learn that browser profiles affect fingerprinting
Try approach after approach until something worked
Debug headless browser issues by inspecting what Cloudflare was detecting

None of this came from the spec. The spec told the AI what to achieve. But figuring out how required me to research, experiment, find the solution, and then tell the AI to implement it.

The Takeaway

What SDD provided:

Clear goal to work toward (extract Bearer token)
Focus on one step at a time instead of being overwhelmed
Documentation of failed approaches to avoid repetition
Motivation to keep going (this was Task 1 on a roadmap of 8 features - couldn't give up)

What SDD couldn't provide:

Technical solution to Cloudflare bypass
Knowledge of browser fingerprinting
Shortcuts to avoid trial-and-error debugging
The actual working approach (that required research and experimentation)

Would specialized subagents have helped?
Honestly, I don't know—I didn't try them for this problem. Agent-os has advanced features like specialized research agents and orchestrated task execution that might have helped with researching Cloudflare bypass techniques. But I was using the standard workflow, so I can't say whether those advanced features would have shortened the two-day struggle.

Lesson learned:
SDD gives you structure to tackle hard problems systematically. But hard problems are still hard. Structure doesn't replace technical knowledge, research, and persistence. It just gives you a framework to keep trying without getting lost.

When I finally got authentication working after two days, having it documented as "Task 1: COMPLETE ✓" with detailed notes on the working approach was incredibly valuable. Future features could reference "see Task 1 for Cloudflare bypass pattern." Without that documentation, I might have forgotten the solution by the time I needed to debug it again.

Challenge 2: The Multi-Layer Bug

After finally getting authentication working, I ran into a different kind of frustration: the manualAttendanceDates feature bug.

The Context:
This requirement came much later, after the entire end-to-end system was already working. The app was successfully tracking attendance based on Myki transactions, deployed and running. But then I realized I needed a way to record office attendance on days when I drove to work instead of taking the train. No Myki transaction = no automatic detection. The solution was to add a manualAttendanceDates config field where I could explicitly list dates I was in the office.

This was an enhancement to an already-working system, not part of the original implementation.

The Spec:
Clear requirements. Well-defined tasks. Config schema documented. Expected behavior spelled out.

The Implementation:
Feature got implemented according to the tasks. Initial version deployed.

The Problem:
Manual dates weren't showing up correctly. But it wasn't just one bug—it was multiple issues across different parts of the system.

How SDD Helped

Having the spec gave me a debugging roadmap:

Check the spec requirements - What should happen? "Manual dates should appear on the calendar with the same styling as PTV-detected dates"
Follow the task breakdown - Config parsing → Python backend → GitHub Actions workflow → JSON output → Frontend rendering
Trace the data flow - The spec documented the exact data structure at each layer

I could systematically check each layer by reviewing the code:

Python code: Reviewing the implementation, I could see it wasn't properly merging manual dates with PTV-detected dates
Workflow file: Looking at GitHub Actions, I realized it needed updates to handle the new field
UI: Checking the frontend code, I spotted where it needed changes to render manual dates correctly

This wasn't a single bug, but multiple integration issues across three different components.

What SDD Couldn't Solve

Even with perfect specs, I still had to:

Actually review the code across all three layers to spot the issues
Give the AI specific hints - "Look at how manual dates are merged in the Python code," "Check the workflow file," "The UI might not be checking the right field"
Understand the integration points - recognizing that adding one field means touching Python backend, GitHub Actions workflow, and React frontend
Connect the dots across components - understanding how the config file flows through Python processing, gets written to JSON, picked up by GitHub Actions, and rendered by the UI

The spec told me what should happen. It didn't tell me that integrating a new field into an existing multi-layer system would require touching all these different pieces. The AI could implement each fix once I pointed it to the right location, but finding those locations required me to review the code and understand the full data flow.

The Takeaway

What SDD provided:

Clear expected behavior to test against
Systematic way to isolate which layer was failing
Documentation of the intended data structure

What still required human debugging:

Understanding multi-layer integration issues
Recognizing when different components had different assumptions
Finding the exact line where the mismatch occurred

Challenge 3: Timezone Handling

The Context:
Calendar dates were displaying incorrectly—off by 1 day from the actual values in attendance.json.

The Spec:
"Display attended days on calendar matching the dates in the JSON file exactly."

Simple, right? Match the dates. But there was a subtle problem.

How SDD Helped

The spec was clear about what should happen (dates must match), which made it obvious when they didn't. Without a spec, I might have thought "close enough" or missed the off-by-one bug entirely.

The task breakdown also helped isolate the problem:

Task: "Parse attendance dates from JSON"
Task: "Mark calendar tiles for attended dates"

The bug was in the date parsing task, not the calendar rendering task. Task isolation made debugging faster.

What SDD Couldn't Solve

The spec said "match the dates exactly" but didn't specify how to handle timezones. The bug was subtle:

// Initial implementation - caused timezone conversion
const dateString = date.toISOString().split('T')[0];
// For dates near midnight, UTC conversion shifts the date!

The problem: JavaScript's toISOString() converts to UTC. For dates near midnight, this can shift the date forward or backward. Nov 1, 2024 01:00 AEDT becomes Oct 31, 2024 14:00 UTC—wrong day!

Why the spec didn't prevent this:
The spec didn't say "use local timezone, not UTC" because I didn't think about timezones when writing it. The requirement seemed obvious: match the dates. But "obvious" hides assumptions.

The Fix

// Corrected implementation - uses local timezone
const dateString = date.toLocaleDateString('en-CA'); // YYYY-MM-DD format

The Takeaway

What SDD provided:

Clear success criteria (dates must match exactly)
Quick detection that something was wrong
Task isolation to narrow down where the bug was

What SDD didn't prevent:

Subtle implementation details (timezone handling)
Hidden assumptions in "obvious" requirements
Need for domain knowledge (how JavaScript handles dates)

Lesson learned:
Good specs need to surface non-obvious assumptions. "Match the dates" should have been "Match the dates using local timezone to avoid UTC conversion issues." But you often don't know to specify this until you've been bitten by the bug.

Challenge 4: Third-Party Library Integration

The Context:
Integrating the date-holidays npm package to automatically detect Victoria public holidays.

The Spec:
"Use date-holidays library to fetch Victoria public holidays. Display them on the calendar with red text."

How SDD Helped

The spec documented exactly which library to use and what the expected behavior was. When the integration didn't work as expected, I could reference the spec to confirm what was supposed to happen.

What SDD Couldn't Solve

The library returned dates in an unexpected format: "YYYY-MM-DD HH:MM:SS" strings instead of JavaScript Date objects.

// Initial attempt based on spec
const holidayDate = new Date(holiday.date);
// Assumed library returns Date objects - it doesn't!

Why the spec didn't prevent this:
The spec said "use the library" but didn't document the exact return format because I hadn't investigated the library deeply when writing the spec. I assumed standard Date objects.

The Fix

I had to inspect the actual library output, recognize the format mismatch, and handle it explicitly:

// Working solution after investigation
const dateString = holiday.date.substring(0, 10); // "2025-11-04"
const [year, month, day] = dateString.split('-').map(Number);
const holidayDate = new Date(year, month - 1, day); // Uses local timezone

The Takeaway

What SDD provided:

Documentation of which library to use (no decision paralysis)
Clear requirement for what should be displayed (public holidays with red text)
Task to test the integration

What SDD didn't prevent:

Runtime surprises from third-party libraries
Need to investigate actual library behavior vs documented behavior
Format mismatch that only appears when you run the code

Lesson learned:
Specs can't predict every third-party library quirk. You discover these by running code and inspecting actual output. The structured approach helps you document the quirks once you find them, so future tasks can reference the pattern.

Challenge 5: User Preferences vs Developer Assumptions

The Context:
During development, weekends were displaying in red text (standard react-calendar behavior). I assumed this was confusing since it wasn't attendance data.

The Plan:
Remove the red weekend styling via CSS override. Seemed like a clean UI improvement.

What Actually Happened:
Before implementing the change, I asked the user (myself, wearing the user hat instead of developer hat). Response: "I really liked keeping weekends and public holidays in red."

I almost removed a feature I valued because I was thinking like a developer, not a user.

How SDD Helped

The structured workflow created natural checkpoints for user feedback:

After completing a task group, review with user
Before removing functionality, validate with user
Spec updates require user approval

Without this structure, I would have just removed the feature mid-coding session without stopping to think "Should I ask about this?"

What SDD Couldn't Solve

SDD doesn't tell you what users want. It creates opportunities to ask, but you still have to:

Actually ask the question
Listen to the answer
Override your own assumptions

The Takeaway

What SDD provided:

Natural review checkpoints to get user feedback
Process that encourages "ask before removing"
Documentation of decisions (why we kept the feature)

What SDD didn't prevent:

Making wrong assumptions in the first place
Need for actual user communication
Temptation to "just fix it" without asking

Lesson learned:
Structure creates opportunities for better decisions, but you still have to take advantage of those opportunities. The review checkpoint is useless if you skip it.

Where SDD Provided the Most Value

After going through these challenges, here's where the structured approach actually helped:

1. Clear Success Criteria

Every bug was obvious because the spec defined success. "Dates should match exactly" meant off-by-one was clearly wrong. Without specs, I might have rationalized it: "Close enough, probably a display thing."

2. Systematic Debugging

Task breakdown gave me a debugging roadmap. Instead of randomly checking files, I could trace the data flow through the task list:

Config parsing (Task 1)
Backend processing (Task 2)
JSON output (Task 3)
Frontend rendering (Task 4)

Check each layer systematically until you find the broken one.

3. Documentation of Decisions

When I came back a week later to add a new feature, the specs told me:

Why certain approaches were chosen
What assumptions were made (and documented)
How data flows through the system

Without this documentation, I would have re-learned the codebase every time.

4. Review Checkpoints

The workflow forced me to pause and review:

After each task group
Before major changes
When user feedback was needed

These pauses prevented rushing ahead with wrong assumptions.

Where SDD Couldn't Replace Human Judgment

But let's be honest about what structure can't solve:

1. Multi-Layer Integration Issues

Specs describe individual components well. But when components need to work together, you still have to understand the full picture. The manualAttendanceDates bug required understanding backend + frontend + data contract all at once.

2. Hidden Assumptions and Edge Cases

"Match the dates" seemed clear until timezone conversion bit me. "Use the library" seemed clear until format mismatches appeared. Good specs surface assumptions, but you often don't know what to surface until you've been bitten.

3. Third-Party Library Quirks

Specs can't predict runtime behavior of external dependencies. You discover these by running code, inspecting output, and debugging when things don't work as documented.

4. User Preferences and Domain Knowledge

Structure can't tell you what users value or what domain-specific constraints matter. You still need actual user communication and domain expertise.

The Honest ROI of SDD

Let's be real about the time investment:

Time spent on specs: ~4-5 hours across all features
Time spent on implementation: ~2 days
Time spent debugging: ~4-6 hours (timezone, manualAttendanceDates, library integration)

Total: ~3 days for 8 features shipped and deployed

Where SDD Saved Time

Debugging was faster:

Systematic task-by-task checking vs random file jumping
Spec told me what should happen vs guessing
Data flow documented vs reverse-engineering it

Resumability was huge:

Came back a week later, knew exactly where I left off
Spec reminded me why decisions were made
Task list showed what was done and what was next

Fewer forgotten requirements:

Everything documented upfront vs relying on memory
Edge cases captured in spec vs discovered in production
Complete feature set shipped vs "80% done" abandonment

Where SDD Cost Time

Upfront spec creation:

4-5 hours thinking and documenting
But this is thinking time I'd need anyway, just formalized

Learning the workflow:

First project with agent-os had a learning curve
Second project would be faster

Maintaining documentation:

When specs changed, had to update docs
But this paid off when resuming work later

The Takeaway

Spec-Driven Development isn't magic. It won't prevent bugs, eliminate debugging, or replace human judgment. But it provides:

Structure when you'd otherwise be lost
Documentation when you'd otherwise forget
Checkpoints when you'd otherwise rush ahead with wrong assumptions
Resumability when you'd otherwise re-learn the codebase

The challenges I faced—timezone bugs, library quirks, multi-layer issues—would have happened with or without SDD. The difference is how I dealt with them:

Without SDD: Random debugging, forgotten context, abandoned projects
With SDD: Systematic debugging, documented decisions, completed features

That's the honest ROI.

What's Next

We've now seen the complete picture: the workflow (Part 3) and where it actually helps vs where you still struggle (Part 4). You know the realistic benefits and the honest limitations.

In Part 5, we'll wrap up with a decision framework: when should you use SDD for your project, and when is a simpler approach better? We'll also cover how to get started with Station Station yourself (it's free and open source), and where to go from here.

If you're ready to make the call on whether Spec-Driven Development fits your workflow, Part 5 has the answers.

Part 3: Building Station Station - Agent-OS Workflow in Action

Koustubh — Tue, 04 Nov 2025 05:43:12 +0000

In Parts 1 and 2, I introduced Spec-Driven Development and showed you the finished Station Station project—8 features, live on GitHub Pages, solving my real hybrid work compliance problem. But how did we actually get there? What does the agent-os workflow look like in practice?

This part walks you through the complete development process, using real examples from Station Station. No theoretical abstractions—just the actual workflow I followed to go from "I need to track my office attendance" to a deployed web application.

The Five Phases of Agent-OS

Agent-os structures development into five distinct phases, each with specific deliverables and human review checkpoints. For this project, I used Claude (Anthropic's AI) as the AI assistant throughout the entire workflow—from spec shaping to implementation.

AGENT-OS DEVELOPMENT WORKFLOW
════════════════════════════

1. Create Product  →  2. Shape Spec  →  3. Write Spec  →  4. Write Tasks  →  5. Implement
   Mission & Roadmap   Requirements      Technical Spec    Task Breakdown    AI + Human Code
         ↓                  ↓                  ↓                 ↓                 ↓
   [Human Review]     [Human Review]     [Human Review]    [Human Review]    [Human Review]

Notice the review checkpoints? That's deliberate. You're not waiting until the end to discover the AI misunderstood your requirements. You're validating assumptions at each phase before moving forward.

Let me show you what each phase actually looks like.

Phase 1: Create Product

The first step isn't writing code—it's defining what you're building and why. You start with just a raw idea, and agent-os helps you shape it into a structured product plan.

Here's how it actually works:

You start with a simple idea:
"I need to track my office attendance using my Myki train card data to meet my company's 50% hybrid work requirement."

Agent-os asks clarifying questions:

What problem are you solving? Who's the target user?
What are your key constraints? (Budget, timeline, technical preferences)
What features are must-haves vs nice-to-haves?
Do you have preferred technologies or deployment platforms?

You answer honestly:

Problem: I need proactive visibility into my attendance, not reactive manager notifications
User: Primarily me, but could be useful for other hybrid workers
Constraints: Zero hosting costs, mobile-first (I'll check this on my phone)
Tech: Python (I'm comfortable with it), React (modern and fast), GitHub Pages (free)

Agent-os generates three documents:

mission.md - The "why" behind the project:

Problem: Hybrid workers need transparency into office attendance compliance
Solution: Automated attendance tracking using Melbourne's Myki transit data
Target user: Me (and anyone else commuting via train for hybrid work)

roadmap.md - The "what" we're building:

8 features broken into 3 phases
Phase 1: Foundation (auth + API discovery)
Phase 2: Data Layer (extraction + processing)
Phase 3: Integration & UI (frontend + config)

tech-stack.md - The "how" we'll build it:

Backend: Python + Playwright for browser automation
Frontend: React + Tailwind CSS v4
Deployment: GitHub Pages (static site, zero hosting costs)

This took about 30 minutes—mostly answering questions and reviewing the generated documents. You don't write these from scratch; the AI creates them based on your answers. But you review and refine them to ensure they match your vision.

Human role here: You provide the raw idea and answer questions about your constraints, priorities, and technical preferences. AI can't guess that you want zero hosting costs or mobile-first design—that's domain knowledge only you have.

Phase 2: Shape the Spec

Once you have the product defined, you pick a feature from the roadmap and start spec shaping. This is where agent-os really shines—the spec-shaper agent asks clarifying questions to gather detailed requirements.

For the React frontend feature, the shaping process went like this:

Spec-shaper: "What data format will the frontend consume?"
Me: "JSON from GitHub raw URL, generated by Python backend"

Spec-shaper: "What visualizations do you need?"
Me: "Calendar view with attended days marked, monthly bar chart showing attendance trends, summary statistics"

Spec-shaper: "Mobile or desktop priority?"
Me: "Mobile-first. I'll be checking this on my phone most mornings."

Spec-shaper: "Should the calendar be read-only or interactive?"
Me: "Interactive—clicking an attended day should show which station and what time I tapped on."

This back-and-forth surfaces implementation details you might not think about upfront. By the end of shaping, you have a clear picture of what "build the frontend" actually means.

Important: This is iterative. The spec-shaper generates a draft spec based on your answers. You review it. If something's not quite right—maybe it misunderstood your intent, or you realized you forgot to mention a key requirement—you provide more input. The spec gets refined. You review again. This continues until you're satisfied.

For Station Station, I went through 2-3 refinement rounds on some specs. The first draft might have missed that I wanted public holidays automatically displayed on the calendar. I'd point that out, and the spec would be updated to include it. No starting over—just iterative improvement.

Human role here: Answer questions honestly about your use case, then review and refine the generated spec. The AI can't guess that you'll primarily use this on mobile, or that you care more about quick glances than detailed analytics. And if the first draft misses something, that's fine—just keep refining until it's right.

Phase 3: Write the Spec

Now the spec-writer agent takes your answers from the shaping phase and generates a detailed technical specification. Here's what the actual spec looked like for the frontend:

# Specification: Attendance Tracker Frontend UI

## Goal
Build a responsive static React web application to visualize work attendance data
from the Myki attendance tracker JSON output, enabling users to view attendance
statistics, explore monthly calendars with marked attended days, analyze trends
through bar charts, and filter data by date ranges across mobile and desktop devices.

## User Stories
- As a user, I want to see a monthly calendar with my attended days visually marked
  so that I can quickly identify when I was at the office
- As a user, I want to view monthly attendance percentages in a bar chart so that I
  can understand my attendance trends over time
- As a user, I want to filter data by date range so that I can focus on specific
  time periods like quarters or financial years

## Specific Requirements

**Calendar View Component**
- Display monthly grid calendar showing current month by default
- Provide previous/next month navigation buttons for browsing history
- Mark attended days with red visual indicators (red background circle or dot)
- Make attended days clickable to show detail modal or tooltip
- Display timestamp and target station name when attended day is clicked
- Use react-calendar library for calendar functionality
- Ensure keyboard navigation support for accessibility
- Mobile-optimized with touch-friendly date selection

**Monthly Bar Chart Visualization**
- Display one bar per month showing attendance percentage (0-100%)
- Use Recharts library for rendering responsive bar charts
- Color bars in red theme to match attended day indicators
- Include tooltips showing exact percentage, working days, and days attended on hover
- Ensure chart is fully responsive and readable on mobile screens

This continues for 9 specific requirement areas, totaling about 100 lines of detailed specifications. The spec-writer captured my shaping answers and translated them into implementable requirements.

Key insight: Notice the specificity. Not "build a chart" but "use Recharts library, red theme, responsive on mobile, tooltips on hover." That level of detail lets the AI implement without guessing.

Just like shaping, this is iterative too. The spec-writer generates a detailed spec based on the shaped requirements. You review it carefully. Maybe you notice it specified the wrong color theme, or it didn't include a requirement for error handling, or the accessibility requirements aren't strong enough. You provide feedback, and the spec gets updated. Review again. Refine again. Keep going until the spec accurately represents what you want built.

For the frontend spec, I noticed the first draft didn't specify what should happen when the JSON fetch fails. I asked for better error handling requirements—retry option, user-friendly messages, graceful degradation. The spec was updated to include those details. Same with accessibility—I pushed for stronger requirements around keyboard navigation and screen reader support.

Human role here: Review the spec thoroughly and keep refining until it's right. Did it capture your intent? Are there edge cases missing? Requirements that don't make sense? This is your last chance to catch misunderstandings before code gets written, so it's worth taking the time to get it right.

Phase 4: Write Tasks

With an approved spec, the task-writer agent breaks it into granular, actionable tasks. Here's how the frontend spec became 6 task groups with 40+ individual tasks:

# Task Breakdown: Attendance Tracker Frontend UI

## Task List

### Task Group 1: Initial Project Setup
**Dependencies:** None

- [x] 1.1 Create new Vite React project
  - Run: `npm create vite@latest attendance-tracker -- --template react`
  - Navigate into project directory
  - Install base dependencies: `npm install`

- [x] 1.2 Install and configure Tailwind CSS
  - Install: `npm install -D tailwindcss postcss autoprefixer`
  - Initialize: `npx tailwindcss init -p`
  - Configure tailwind.config.js with content paths and custom 'attended' color (#ef4444)
  - Add Tailwind directives to src/index.css

- [x] 1.3 Install required libraries
  - Chart library: `npm install recharts`
  - Calendar library: `npm install react-calendar`
  - Date picker: `npm install react-datepicker`

### Task Group 2: Data Fetching and Processing
**Dependencies:** Task Group 1

- [x] 2.1 Write 2-6 focused tests for data utilities
  - Test JSON fetch success scenario
  - Test error handling for network failures
  - Test date filtering calculation

- [x] 2.2 Create data fetching utility
  - File: src/utils/dataFetcher.js
  - Implement fetchAttendanceData() function
  - URL: https://raw.githubusercontent.com/koustubh25/station-station/main/output/attendance.json
  - Use cache: 'no-cache' for fresh data
  - Handle network errors with descriptive messages

Each task is concrete enough that I could hand it to any developer (or AI) and they'd know exactly what to build. Dependencies are explicit—you can't build the calendar component until data fetching works.

Human role here: Review the task breakdown. Is anything missing? Are tasks sequenced correctly? Do the dependencies make sense? Sometimes AI misses edge cases or creates circular dependencies.

Phase 5: Implement Tasks

This is where AI assistance actually writes code. But it's not fully autonomous—there are specific checkpoints where human review is critical.

For Station Station, the implementation flow looked like this:

AI implements task - The implementer agent writes code according to the task spec
AI runs tests - Verifies the implementation works (if tests exist)
Human reviews output - You check the code, test it manually, and approve or request changes
Move to next task - Repeat for each task in the breakdown

Here's where I learned an important aspect: agent-os CLI permissions. The AI can read files, write files, and run tests. But certain operations require your explicit approval:

Git commits - You review and commit changes yourself
Git pushes - You decide when to push to remote
Workflow triggers - You manually kick off CI/CD pipelines

This is by design. You maintain control over version history and deployments.

But here's what I discovered: After gaining confidence in the AI-generated code—once I'd reviewed a few implementations and saw they were solid—I started allowing the AI to do git push and use the gh CLI to view or trigger GitHub Actions workflows. This let the AI work more autonomously: push code, trigger the build, check if tests passed, and if they failed, fix the issues and try again.

The workflow became: AI implements → AI pushes → AI triggers workflow → AI monitors results → If failures, AI fixes and repeats. I'd check in periodically, but for well-defined tasks, the AI could iterate autonomously until everything passed.

This isn't the default (and probably shouldn't be for unfamiliar projects), but once you've established trust through review, you can grant more autonomy where it makes sense.

Note: Agent-os also has an orchestrate-tasks command that provides even more advanced multi-agent coordination and autonomous task execution. But that's beyond the scope of this blog—we'll cover it in detail in a future post. For Station Station, the standard task-by-task implementation workflow was sufficient.

Human role here: Code review, manual testing, and deployment decisions. AI can generate the boilerplate, but you verify it works in your specific context.

The Complete Agent-OS Workflow

Now that we've walked through all five phases, let's see how they fit together into a complete cycle.

The agent-os workflow follows a structured, iterative cycle. Notice the feedback loop where human review catches issues that require debugging before the feature is complete. This isn't full automation—it's a partnership where AI handles implementation and humans guide the architecture and review the results.

Human Review at Key Decision Points

This sequence diagram reveals the continuous human-AI collaboration throughout development. Review happens at multiple stages, not just at the end. Each phase includes a human checkpoint where you validate the AI's work before proceeding.

The key insight: this is continuous collaboration, not "AI does everything then human reviews at the end." You're involved throughout, making architectural decisions, reviewing outputs, and course-correcting when needed.

The Iterative Reality

Here's what the spec doesn't show: iteration. The workflow diagrams make it look linear, but reality is messier.

For Station Station, I went through multiple rounds:

Spec refinement: Realized mid-development I needed manual attendance dates (for days I drove to work instead of taking the train). Went back and updated the spec.
Task adjustments: Some tasks were too large and got broken into smaller chunks. Others were unnecessary and got removed.
Implementation bugs: AI couldn't fix the manualAttendanceDates field bug after several attempts. I had to review the code, identify the issue location, then let AI implement the fix.
New specs added later: The initial roadmap had 8 features, but I added more specs later for enhancements like security improvements and manual attendance features. You don't have to plan everything upfront—you can always create new specs for additional features as needs emerge.

The workflow provides structure, but you'll loop back. That's normal. The key difference from ad-hoc AI chat is that when you loop back, you update the spec or tasks—so the system stays consistent. Future features can reference the updated spec instead of inheriting outdated assumptions.

And when you think of new features? Just create a new spec and go through the same workflow. The product documentation evolves with your project.

What Makes This Different

The structured approach of agent-os SDD provides several key benefits:

Clear Direction Throughout

Every feature starts with documented requirements, not assumptions
The roadmap gives you a clear view of what's done and what's next
When you solve one problem (like Cloudflare bypass), the spec tells you exactly what comes next
No more "I got this working, but now what?"

Persistent Context

Because you have a record of all specs, tasks, and their completion status, the AI can pick up exactly where you left off—even weeks later
Come back after a break: "Task 7 is complete, Task 8 is next, here's what needs to be done"
No context loss, no re-explaining what you've already built
The documentation serves as persistent memory across sessions

Easier Debugging

When something breaks, you can reference the spec to understand intended behavior
Task breakdown makes it easy to isolate which component is failing
Specs document edge cases and requirements that are easy to forget during implementation

Iterative Refinement

Update specs as you learn—they evolve with your understanding
Add new specs for new features without disrupting existing work
Each iteration is documented, so you can see why decisions were made

The time investment is front-loaded. Spec creation took longer than just prompting Claude to "build a frontend." But I shipped all 8 planned features. The debugging was easier. The resumability was huge. And when I added new features a week later, the specs told me exactly where to hook them in.

That's the ROI of Spec-Driven Development—not faster initial code generation, but fewer surprises, clearer direction, and maintainable progress.

What's Next

We've seen the agent-os workflow in action: creating products, shaping specs, writing detailed specifications, breaking down tasks, and implementing with AI assistance. We have a structured process that transforms vague ideas into working code.

But this is the part where I need to be honest about limitations. The workflow isn't magic. AI still struggles with certain problems, and some features require significant human intervention. In Part 4, we'll dive into the real challenges: debugging stories where AI failed, the collaboration spectrum between AI and human, and when to know if Spec-Driven Development is overkill for your project.

If you're wondering whether this structured approach is always worth it—or where it breaks down—Part 4 has the answers.