Designing.
The loop, on a foundation.
Spruce isn’t a single command — it’s a loop on a foundation. First you set the project’s character. Then you ground the work in named users and the jobs they’re hiring the product to do. The iteration loop — decide, review, refine — sits on top of that grounding and intermingles in any order until you ship.
This page walks through the loop with artifacts from the meditation-app project that threads through the catalog. For applied walkthroughs in specific situations, see Tutorials. For the full demo of any command, /commands. For the cumulative live result of running through the loop, see the Stillpoint case study.
First
Set up
Before any design happens, Spruce needs to know what the product is. /spruce-up runs a brief interview that captures the product’s character — audience, voice, density, what it should and shouldn’t feel like — into a .spruce.md file every subsequent command reads.
Five minutes of conversation; one persistent context. Without it, generative work has nothing to calibrate against.
› /spruce-up
What does this product do, and what’s the core experience you want users to have?
› A short-session meditation app for parents — five-minute practices designed to fit into the gaps of a busy day. The core experience is recovery, not transformation.
Got it. Next: who uses it? What do you know about them?
Foundation
Discover
Optional, but the loop reads better when it’s in place. The Discovery tier produces the HCD artifacts — personas, jobs, journeys, scenarios — that downstream commands ground decisions in. /personas writes .personas.md; /jtbd writes .jtbd.md; /journey and /scenarios write theirs. /audit evaluates against all of them.
Each command runs in three modes — draft from context when no research exists, structure user-supplied research when it does, or pressure-test a finished artifact for assumptions. Context-derived artifacts get labelled honestly, so the loop knows what to weight.
Without Discovery, the loop reasons from .spruce.md character alone. With Discovery, every decision can be tied to a named user doing a named thing.
Primary persona · from .personas.md
Maya— Daily Practitioner
“Wants the practice to be a small, reliable good choice in the day — not a project, not a transformation.”
+ .jtbd.md — six jobs across three layers
+ .journeys.md — current-state and future-state mapped
+ .scenarios.md — concrete moments, persona by persona
+ /audit — findings tied to named users + jobs
The loop
Iterate.
The iteration loop sits on the foundation. Decide, review, refine — three moments that intermingle. You critique what you just decided, refine based on the critique, decide more after refining, critique again. Any order, any number of times.
Each is a different kind of conversation with Spruce; the loop is what happens when you string them together. Every command in the loop reads from .spruce.md and the Discovery artifacts when they exist — so decisions stay grounded in the product’s character and the people it serves.
Decide
Review
Refine
Foundation
- .spruce.md
- .personas.md
- .jtbd.md
- .journeys.md
- .scenarios.md
Every command in the loop reads from these.
Loop
Decide
Generative work in Spruce isn’t one-shot. /decide walks you through the significant calls before generating; /design ships a confident first pass with notes on the decisions it made; /remix produces three distinct directions for the same brief; and /foundations establishes the tokens and primitives every other command composes within.
You direct the work; Spruce executes the reasoning.
Decision 1: How should the user enter their reflection?
Open canvas — write whatever comes up.
Prompts — one or two questions to respond to.
— Hybrid — a prompt above an open canvas; the prompt is optional.
Decide for me.
The Hybrid choice shaped the reflection screen visitors see in /design's Tonight home + /decide's reflection screen demos.
Loop
Review
Once something exists, you review it. Spruce offers four lenses, each with a different depth and a different question. /detect for fast anti-pattern scans; /survey for comprehensive findings with severity tiers; /uxreview for the UX substrate; /critique for design-director feedback at the level of feel.
/explain sits alongside as a fifth — not for finding problems, but for walking through the reasoning behind a recent design.
The overall take.
The meditation app is in strong directional shape. The character — warm, unhurried, calm without being precious — comes through in the typography and palette established by /foundations and threads through every surface the corrective tier has touched. The work isn’t hedging on its character. The remaining concerns are flow and state coverage rather than direction.
Loop
Refine
Reviews surface what to address; the corrective tier addresses each layer. /typeface, /colorgrade, /arrange, /refine, /pace, /voice, /reduce, /fortify — each operates on a single design dimension.
Run them based on what review surfaced; each command applies the discipline of its reference file. The corrective tier is where specific decisions get made about what changes — and what stays.
From /colorgrade on the featured-practice card
Before
- Cool gray-blue surface
- Blue ring on the popular tier
- Blue-to-purple gradient CTA
- Pure black title text
- Five colored elements competing
After /colorgrade
- Warm Canvas surface
- Quiet mono-caps eyebrow (no ring)
- Single committed amber-700 CTA
- Tinted stone-900 title
- One accent — on the CTA only
Last
Ship
/finish is the last conversation before deploy. By the time it runs, the heavy work has been done; what remains is a final tightening — straight quotes to smart quotes, balance on headlines, focus-ring offsets — and an honest verdict on ship-readiness.
The verdict is the differentiator. Other commands produce work; /finish produces a call.
Ready to ship. With minor items noted.
The verdict landed after eight polish items applied autonomously and three remaining concerns flagged at three severity tiers. The substantial item — touch targets on the practice library tier cards below 44×44px on mobile — was held for the next iteration; minor items can land later without affecting deployment.
Each new feature, each next iteration, starts again at /spruce-up.
The context evolves as the product does. Every command reads the latest version.