Skip to content

How it was built

SMARA Account is a learning implementation of two things at once: a tamper-evident ledger, and AI spec-driven development. Every line of application code is written by AI — but not freely. It's constrained by a strict set of engineering guidelines and by feature specifications defined through OpenSpec. The specs drive the implementation, not the other way around.

Why spec-first, not vibe-coded

It's tempting to treat an AI coding assistant as a fast typist and just describe what you want in the moment. That works for small, throwaway things. It falls apart for a project meant to keep working and stay coherent over many sessions and many months: without a written record of what the system is supposed to do, each session re-derives intent from whatever code already exists — and drift compounds. OpenSpec exists to keep "what should happen" written down, reviewable, and separate from "what the code currently does."

Concretely, that means: no behavior ships that isn't backed by a spec scenario. If a review finds code that isn't covered by one, the fix is either a spec update or a code change to match the spec — not silence.

The workflow: propose → apply → archive

Every change to the project goes through the same three stages:

  1. Propose — before writing any code, describe the change: why it's needed (proposal.md), how it will work for anything non-trivial (design.md), and the exact testable behavior it adds or changes, as SHALL/MUST requirements with WHEN/THEN scenarios (a spec delta under specs/<capability>/). A tasks.md checklist breaks the implementation into steps.
  2. Apply — implement the change by working through tasks.md, checking off each task as it's completed, writing tests alongside the code they cover.
  3. Archive — once a change is merged, its spec deltas are folded into the single source of truth for that capability under openspec/specs/, and the change itself moves to an archive directory, keeping a record of why each capability exists the way it does.

This keeps two things true at all times: the specs under openspec/specs/ describe what the app actually does right now (not what's planned), and every past change is still readable later, instead of being squashed into an opaque commit history.

Want to build the same way?

The full workflow, branching convention, and the engineering guidelines this project holds itself to are documented in CONTRIBUTING.md in the repository. Pull requests are welcome, and expected to follow the same spec-first discipline as the rest of the project.