thinkupfront

Upfront

Force thinking before code.

AI makes writing code effortless. That's the problem.

When code is cheap to produce, it's easy to stop thinking. Skip the spec. Skip the design. Let the AI figure it out. Ship it, fix it later. Except "later" is now a codebase full of confident mistakes that passed every automated check and got rubber-stamped in review.

This is how teams lose their skills. Not all at once — gradually. The senior engineer who used to catch architectural issues in review now approves AI-generated PRs because the code "looks right." The mid-level engineer who used to design systems now prompts for them. The junior engineer who should be learning to think never has to, because the AI thinks for them.

Nobody notices until something breaks and no one on the team understands the system well enough to fix it.

Upfront solves this by making the thinking process explicit, challenging, and auditable. Every command in this toolkit is designed to force humans to engage — not fill out templates, not click "yes" to AI suggestions, but actually think through what they're building and why.

If the AI can't talk you out of your approach, your approach is probably sound. If it can, you should know that before writing a single line of code.

---

How it works

Upfront is a set of skills for Claude Code that cover the full development lifecycle. Install as a plugin — two commands in your terminal, no dependencies, no build step, no SaaS.

The commands follow a natural flow:

Think → Define → Plan → Build → Ship → Learn

Every command that involves decisions challenges you. The AI doesn't suggest and wait for approval — it asks open questions, waits for your answer, then fills the gaps you missed. You think first. The AI decorates second.

---

Commands

Think

/ideate — Find a problem worth solving

For when you don't know what to build yet. Divergent brainstorming that starts wide ("what's bugging you?"), clusters related pain points, challenges whether each is worth solving, converges to 1-3 candidates, and helps you pick one. No output file — the output is clarity. When you have a problem, it hands off to /feature.

/explore — Document the codebase and its ecosystem

Five-phase investigation that produces specs/ARCHITECTURE.md — the shared reference document every other command reads. Goes beyond code: maps external connections (latency, SLAs, failure modes, data volumes), ecosystem context (upstream, downstream, blast radius), and operational reality (deployment, monitoring, who gets paged). Asks about ecosystem diagrams.

Greenfield projects get a fast exit: detects empty repos, creates minimal scaffolding, sends you to /feature.

/teach — Rebuild your understanding

For when you haven't touched the codebase in a while. Gauges your current level (refresher, domain expert but new to code, or completely new), walks through the system in layers (context → happy path → failure modes → invariants → connections), and optionally quizzes you with questions that test real understanding — not trivia.

Generates a study guide with your strong areas, focus areas, key files to read, invariants to memorize, and a safe first task to build familiarity.

---

Define

/feature — Define a feature through forced thinking

The core command. Four phases, each with a different AI role:

1. Intent — Five forcing-function questions. What problem? How will you know it worked? What's out of scope? What must NOT happen? Pre-mortem. The AI is adversarial — it pushes back on vague answers and refuses to move on until the thinking is substantive.

2. Behavioral Spec — Five-level funnel: user stories → mechanism (why will this approach work?) → states and transitions → concurrency and shared state → error cases. The AI challenges your causal logic before any code is discussed.

3. Design Conversation — The AI researches the codebase, presents options and tradeoffs. You make the decisions.

4. Implementation Design — The AI proposes architecture AND challenges the codebase itself. Flags inconsistent patterns, ambiguous placement, structural rot. Cleanup becomes a prerequisite.

Every phase transition produces a thinking record — what was decided, why, what was rejected, what was skipped. The spec is the audit trail of the thinking, not just the conclusions.

If your problem statement is vague, /feature suggests /ideate. If there's no architecture doc, it suggests /explore.

Appends design decisions to specs/DECISIONS.md for future reference.

/refine — Iterate on a spec without starting over