aspark

An agile AI product team for Claude Code. You bring the idea. A Product Owner challenges it, an Engineering Manager plans it, the Developer builds it, a Reviewer audits the diff, a QA Tester clicks through your app in a real browser, and a Release Manager ships it — and nothing moves to the next phase until the previous gate is green.

aSPARK is a Claude Code plugin. No service, no account, no runtime: it is Markdown that installs into your project and leaves a reviewable paper trail in .spark/.

See it work

One command runs the whole loop. It stops at every gate and shows you the artifact before moving on — you stay the decision maker.

You:     /spark I want a dashboard where users see their weekly stats

Claude:  [Product Owner]  Challenges the idea, asks what "weekly" means for a user
                          in another timezone, writes spec.md with US-1…US-3 and
                          testable acceptance criteria. → Gate: you approve the spec.
         [Designer]       Flags an empty-state gap and a contrast risk in the spec.
         [Eng. Manager]   Decides the architecture, cuts 6 tasks into plan.md, each
                          mapped to a story. → Gate: you approve the plan.
         [Developer]      Builds task by task. No scope creep — the plan is the fence.
         [Reviewer]       Reads the diff, finds an off-by-one in the week boundary,
                          files F1 (Major) in review.md, fixes it, re-checks.
         [QA Tester]      Opens http://localhost:3000, verifies AC-1.1…AC-3.2 in the
                          browser, files a bug where the chart never loads on mobile.
                          → Gate: back to the Developer, then QA again.
         [Release Mgr]    Changelog, tag, PR. → Gate: your explicit go.

What lands in your repo:

.spark/
├── constitution.md         ← project-wide ground rules, set once with /charter
└── weekly-stats-dashboard/
    ├── spec.md             ← stories US-n, acceptance criteria AC-n.m, NFRs
    ├── plan.md             ← architecture decision, ordered tasks T1…Tn
    ├── review.md           ← findings F1…Fn with severity and location
    ├── qa.md               ← every AC and NFR verified, pass/fail, in the browser
    └── release.md          ← changelog, version, what was learned

Requirements carry stable IDs from the spec all the way through: the plan cites which AC each task covers, the review traces each Must AC to code, and QA verifies it under the same ID. Nothing silently falls out of the chain.

Two real, complete examples you can read today:

• steamcore — an ESP32 arcade console built from scratch with aSPARK: 13 features, each with its full spec → plan → review → QA → release trail under .spark/. Start with highscore-system. It has no browser surface, so it also shows the declared substitute-QA path.
• this repository — aSPARK is built with aSPARK; its own .spark/ folder is the trail of a library-type project.

Install

Requirements: Claude Code and Git. For /demo-day you also need a browser integration (Claude in Chrome, or a Playwright / Chrome DevTools MCP server), unless your project has no browser surface and /charter declares a substitute QA method.

Inside an interactive claude session:

/plugin marketplace add a-lottes/aSPARK
/plugin install aspark@aspark

Then restart Claude Code. /plugin should list aspark as enabled. From a plain shell or CI, the same two steps are claude plugin marketplace add a-lottes/aSPARK and claude plugin install aspark@aspark. To hack on aSPARK itself: claude --plugin-dir /path/to/aSPARK.

Start here: on a new project, empty or already full of code, run /charter first. On an empty repo it asks a handful of hard product questions and ends by offering /story-time with the first slice named. On an existing codebase it reads the repo and writes down what it found, for you to correct once. Either way the team stops re-deriving what your project is on every feature. You can skip it, but /spark and /next-steps will point you here first.

The loop

Every feature travels through five phases — Specify, Plan, Act, Review, Keep — and may only move forward when the previous phase's gate is green.

Review or QA findings go back to the Developer and the phase re-runs. Review stops after two Reviewer rounds by default, QA after three failed rounds; then the loop asks you whether the plan or the spec is wrong, instead of grinding.

The light path: not every change needs the whole loop (prompt-enforced)

A small change with no open decision does not need an Engineering Manager, a QA Tester and two review rounds. At the spec gate, /story-time offers a light path only when six checks all hold: one story with at most four acceptance criteria, no unconfirmed assumption, no UI change, nothing security- or data-format-related or relied on outside the repo, no other feature's trail naming the files to be touched, and the constitution's §11 does not switch it off. You choose; it never chooses for you. On the light path, /spark writes a short plan you approve, then build, one review, and /go-live releases without a QA report, stating QA: not run (light path). The moment the change stops fitting (a design choice, a file outside the plan, an open Major after the review), the feature goes back to the full loop and says why. Measured: five dry runs, no rate, savings not measured: .spark/light-path/evidence.md.

Cost and honesty controls (prompt-enforced)

• Models. Every agent runs on sonnet unless your constitution's optional §11 Models & Limits names another model for a role (reviewer: opus, for example). Up to and including 0.17.0 the Engineering Manager and the Reviewer were pinned to opus; this changes cost and possibly review depth for installed projects. The Developer in /increment is your session, so it runs on whatever model you chose.
• Reviewer rounds. /peer-review runs at most two Reviewer rounds per feature, then stops and asks you: waive a Major, grant one more round, or go back to the plan. §11 Reviewer rounds changes the number.
• Closing from the trail. /spark ends every run, finished or stopped, with a table of the Status rows it has just re-read from spec.md, plan.md, review.md, qa.md and release.md. What the model remembers is not a source.
• No code before an approved plan. /spark says so; aspark-guard 0.3.0 and later denies the write in code.

All four are instructions: likely, not certain. One dry run and what it missed: .spark/trail-closing-and-cost-controls/evidence.md.

The team

Each ceremony can also be run on its own. The artifacts on disk are the state, so you can /clear after a heavy phase and pick the loop back up with /spark.

The loop adapts to what you're building

/charter records what kind of software this is (website, web-app, api, cli, library) and what it does with data (auth, payments, PII, database, multiple languages, accessibility mandate). That switches on matching lenses: extra checks the existing team applies only where they apply. A public website gets SEO and Core Web Vitals in QA. An API gets error-envelope and versioning checks in review. A project that handles payments gets the security lens through every phase. Ten lenses are written; the tenth, observability (diagnosability of a running api), has only been dry-run, not exercised on a real project; adding one is a new file in lenses/. Without a constitution, no lens fires.

Gate hardening: searched, no rebuttal rows shipped

The gates are prompt-enforced: an agent can reason its way past one, and Core, being Markdown with no runtime, cannot stop it. Code-level enforcement is the optional sibling aspark-guard's concern.

• Rebuttal rows were to go only where an evasion was actually recorded. A search of this repo's own 51 review, QA and evidence files (evidence.md) found one recorded gate evasion where the bar was two at the same gate, so no rows shipped at any gate; no skill gained a row.
• The grounding is in-repo trails, not field reports. The search was fixed-term, not a census. Effectiveness is unmeasured, and whether a row would fire cannot be tested in Core.