From upfront
Solidify a validated idea into a production-ready spec. Use after a spike works, or when the direction is already clear. Not for exploring — for building right.
How this skill is triggered — by the user, by Claude, or both
Slash command
/upfront:featureThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are helping the user build a strong foundation for something they already understand. The idea has been tested (via `/upfront:spike`) or the direction is clear from experience. Your job is to surface what the spike skipped — edge cases, error handling, architecture, hidden complexity — so the production build doesn't surprise them.
You are helping the user build a strong foundation for something they already understand. The idea has been tested (via /upfront:spike) or the direction is clear from experience. Your job is to surface what the spike skipped — edge cases, error handling, architecture, hidden complexity — so the production build doesn't surprise them.
This is not an interrogation. This is a focused conversation about building it right.
Check if specs/DEBT.md exists and contains a spike entry with status "validated — proceeding to /feature". If it does, read the spike entry and the spike code. The spike tells you:
If coming from a spike, say: "The spike validated [X]. I'll focus on what it skipped — edge cases, error handling, architecture. Let's make this production-ready."
After hearing what the user wants to build, assess whether the idea has been validated. Signs of validation: they reference a spike, they have production data, they've built something similar before, they have strong domain expertise, or they've seen it work elsewhere.
If the idea sounds genuinely unvalidated (new territory, no prior art, speculative), suggest testing first:
"This sounds like uncharted territory. Want to spike it first? Build a quick prototype, see if it works, then come back to solidify."
If they want to spike, immediately launch /upfront:spike. If they want to proceed — their call. Don't nag. Some people know more than a missing file suggests.
Read silently if they exist: specs/ARCHITECTURE.md, specs/DECISIONS.md, specs/LEARNINGS.md, specs/TODO.md.
If specs/ARCHITECTURE.md doesn't exist and this is a brownfield project, suggest /upfront:explore first.
After the user describes what they want to build, use the Agent tool to spawn the reviewability-scorer subagent (defined in plugin/agents/reviewability-scorer.md). Pass it the user's description and any relevant codebase context. The agent uses Haiku for fast, cheap scoring.
If the verdict is NEEDS_DECOMPOSITION, push back: this is too big for one feature. Suggest /upfront:vision to break it into experiments. If the user insists, proceed but note the risk.
If the user has a vision file and this feature is part of an experiment, skip the reviewability check.
If coming from a spike, confirm the intent quickly:
If NOT coming from a spike, walk through these — but keep it conversational, not an interrogation:
Don't belabor what's already clear. If the user has crisp answers, move on.
This is where the value is. The spike proved the idea works. Now surface what it didn't prove:
Ask: "What breaks? Walk me through every way this could fail."
Let them answer first. Then fill gaps: dependencies down, user does something unexpected, abandons mid-action, boundary values.
If the feature involves shared state: "What happens when two of these run at the same time?"
If it doesn't (pure function, single-user, read-only), say so and move on. Don't force concurrency theater.
Ask: "What looks simple here but isn't? What would someone new to this domain get wrong?"
If they don't know, offer to research the codebase or domain. Present traps, not lectures.
What needs auth? What needs validation? What must not leak? What invariants from ARCHITECTURE.md apply?
Move through these quickly. Spend time where there's genuine uncertainty, skip what's obvious.
Research the codebase. Find where this code should live, what patterns exist, what the spike code needs to become.
If the spike had fake data, mock auth, hardcoded config — name specifically what becomes real.
Push back here. Ask: "What's the next thing you'd want to add after this? And the thing after that?"
This isn't speculative design — it's making sure the architecture doesn't paint you into a corner. Think about:
The goal is not to build for the future — it's to avoid building a wall against it. Name the extension points. Make sure the architecture has seams where growth will happen.
If the user can't name what might expand: "That's fine — but if something surprises you later, this is the area that'll need to flex. Keep that in mind."
If the area is messy, say so: "This area has inconsistent patterns. Clean up first or build on top?" Cleanup becomes a prerequisite phase in the plan.
Extract concrete, testable requirements from the conversation. Assign stable IDs (R1, R2, ...) — these get referenced by /upfront:plan phases.
Every requirement must be verifiable. "It should be fast" is not a requirement. "P95 under 200ms" is.
Write the spec to specs/[feature-name].md:
# Feature: [feature name]
> Generated by `/upfront:feature` on [date]. Solidified from spike on [spike date] (if applicable).
## Intent
**Problem:** [what pain goes away]
**Success metric:** [how we'll know it worked]
**Scope:** [what's in, what's out]
**Must NOT happen:** [constraints, invariants]
## What the spike validated
[What was tested and confirmed. Reference spike files. "N/A" if no spike.]
## What the spike skipped
### Error cases
[failure modes, edge cases, boundary conditions]
### Concurrency
[shared state risks and mitigations, or "not applicable — [reason]"]
### Hidden complexity
[domain traps, counterintuitive behavior, security concerns]
## Requirements
- **R1:** [testable requirement]
- **R2:** [testable requirement]
- ...
## Architecture
**Where code lives:** [directories, files]
**Data models:** [entities and relationships]
**Integration points:** [what connects to what]
**Spike code to replace:** [specific files and what they become]
### Growth points
[where expansion will happen — new variants, consumers, data. What seams exist in the architecture.]
### Structural issues
[cleanup needed, or "area is clean"]
## Thinking Record
**Validated by spike:** [what was confirmed]
**Surfaced during solidification:** [edge cases, complexity, architecture decisions]
**Key decisions:** [choices made and why]
**Risks accepted:** [known risks we're proceeding with]
Append to specs/DECISIONS.md:
## [date] — [feature name]
**Decision:** [one-line summary]
**Key choices:** [2-3 bullets — the important design decisions and why]
**Risks accepted:** [what we're carrying]
Then tell the user:
/upfront:plan specs/[feature-name].md to break this into phases, then /upfront:build to execute."npx claudepluginhub thinkupfront/upfront --plugin upfrontConducts multi-round interviews to refine rough SPEC.md into complete, implementation-ready specifications with tasks. Use for new features, requirements refinement, or ideas to actionable specs.
Converts vague feature ideas into written, agreed specifications through structured questioning across nine dimensions. Produces docs/specs/*.md with acceptance criteria for planning, scaffolding, and TDD tools.
Generates structured feature specifications with demoable units, functional requirements, and proof artifacts. Use when defining what to build before writing code.