groundup
A Claude Code framework for junior engineers who want to actually get better — not just ship features.
groundup makes Claude act as a senior engineer mentor who refuses to do the thinking for you. It enforces a structured workflow that builds real engineering skills: system design, debugging, pattern recognition, and code review.
The feature is a vehicle. The goal is the engineer who can build the next one independently.
What It Does
Every session follows a deliberate sequence:
flowchart LR
A([Start]) --> A1[Architecture]
A1 --> A2[Orient]
A2 --> B[Grill]
B --> C[Flow Map]
C --> D[Patterns]
D --> E[Pseudocode]
E --> F[Implement]
F --> G{Stuck?}
G -->|Error| RE[Read the Error]
RE --> H[Debug]
G -->|Blocked| AW[Ask Well]
AW --> F
H --> F
G -->|No| I[Tests]
I --> J[Review]
J --> K[Reflect]
K --> L{More files?}
L -->|Yes| D
L -->|No| M([PR])
Architecture — In a brownfield or unfamiliar codebase, Claude reads the system design and produces a Mermaid diagram showing layers, services, and dependency direction. Then interrogates you on why it is shaped that way — not just what it does.
Orient — After architecture, traces one real user journey hop-by-hop through the codebase with file and line references. Locates exactly where your change fits and names anything unknown as an explicit assumption.
Grill — Before any code, Claude interviews you relentlessly until you can state the approach, the affected files, and the key edge cases. One question at a time. No answer given until you've reasoned through it.
Flow Map — You draw the data flow. Claude interrogates it: transaction boundaries, failure modes, ownership, synchronous vs async. Both of you sign off on the diagram before any file is touched.
Patterns — Before you commit to a design or write a function, Claude checks: does this step have a known industry pattern? If yes, you learn it now — not in code review after you've already implemented something else.
Pseudocode — Claude writes the pseudocode directly into the file. Problem-domain language, not code. You have to think about how to translate it. That translation is where the skill gets built.
Implement — You write the code. Syntax help only if you ask, and only one targeted example.
Read the Error — When a test fails or an error is thrown, three gates before any debugging or Googling: what is the error type, what line is it pointing to, what is your hypothesis from the message alone.
Debug — When you're stuck, Claude doesn't suggest fixes. It walks you through: reproduce → hypothesise → instrument → verify. No fix without a stated root cause.
Ask Well — When you're about to ask a question — mid-session or externally — Claude structures it first: what you're trying to do, what you've tried, what you expected vs what happened, where specifically you're stuck. A well-formed question is already 50% of the answer.
Review — Per-file code review once tests exist. Edge cases from the pseudocode header must be covered.
Reflect — One targeted question after each file. Not a quiz — a question that builds the instinct for next time. Claude doesn't give the answer.
Install
claude plugin marketplace add Osireg17/groundup
claude plugin install groundup@groundup
That's it. Open Claude Code in any project and start describing what you want to build.
Optional team configuration: Add a .grounduprc.md to your project root to inject team-specific patterns, codebase context, domain idioms, required grill probes by file path, style guide rules, and onboarding context. Copy docs/grounduprc-template.md from this repo as a starting point. The mentor reads it at session start and applies it alongside the global rules. Commit it so all team members share the same configuration.
Session state: groundup tracks your progress in .groundup/session-state.json. If you close Claude mid-session and reopen it, the mentor reads this file and resumes from where you left off — no need to re-explain the task or redo the grill. Add .groundup/ to your .gitignore; it is per-engineer working state, not team configuration.
Growth log: groundup maintains a persistent growth log at ~/.claude/groundup/growth-log.md. After each file review, the mentor records what trap was observed, what went well, and how you reasoned through the reflection question. This log is global — it persists across all projects. At the start of each session, the mentor reads the last 10 entries and adapts: increasing probe depth for areas where you've stumbled repeatedly, and stepping back on gates you've mastered consistently.
Requirements: Claude Code (CLI or IDE extension)
Optional: GSD — if installed, groundup integrates with /gsd-ship for final review and PR creation.
Update
