upstack

KO | EN

gitlite — search

#hacktoberfest #go #golang #machine-learning #rust #linux #docker #macos #java #windows #awesome #cli #awesome-list #vue

(★ 17)

Lightweight Red/Green TDD skill suite for Claude Code, Cursor, Codex, and Gemini CLI. Tests before code, always.

upstack Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# upstack

Lightweight Claude Code (+ others) skill suite, used by the team at [Upsolve AI](https://upsolve.ai/).

Red/Green TDD workflow with 9 focused skills, minimal dependencies. Inspired by [gstack](https://github.com/garrytan/gstack) and [simon wilson](https://simonwillison.net/guides/agentic-engineering-patterns/red-green-tdd/).

Hi, I'm [Serguei](https://www.linkedin.com/in/sbalanovich/), CTO at Upsolve. I built [Hyperauto](https://www.palantir.com/offerings/hyperauto/) at Palantir and I'm now working to help teams build robust, reliable data agents for their teams and customers. Like Garry, I think we're currently on the cusp of something huge in the AI coding space. But after playing around with gstack, I found its approach to be much more suited for new & ambitious greenfield projects than iterating on existing products.

At Upsolve, we are hyper focused on security, reliability, and grounding agents in real, auditable data. So our team's engineering approach requires a slightly different approach. With code being essentially free to write now, I believe we developers now need to focus on providing tightly scoped specs, project definitions, and test suites before touching a line of code. When you use upstack, it forces you to think test-first and submits code that is instantly provable and reliable. It takes 30 seconds to set up, so give it a try!

## Quick Start: Your First 5 Minutes

1. Install upstack (30 seconds, see below)
2. Open your project in Claude Code
3. Run `/advisor` to see where you stand
4. Run `/plan` on your first feature or bug
5. Run `/execute` to build it with TDD
6. Run `/ship-pr` to open a PR with screenshots and evidence

## Install — Takes 30 Seconds

### Install on your machine

Open Claude Code and paste this. Claude does the rest.

> Install upstack: clone `https://github.com/Upsolve-Labs/upstack.git` to `~/.claude/skills/upstack` (try HTTPS first, fall back to SSH with `git@github.com:Upsolve-Labs/upstack.git` if auth fails), then run `cd ~/.claude/skills/upstack && ./install.sh`. The script links skills and prints an `INSTALL_STATUS` report and `NEXT_STEPS`. Do NOT install anything yourself — read the status, then walk the user through each missing tool one AskUserQuestion at a time. Follow the `NEXT_STEPS` in the output.

### Codex, Gemini CLI, or Cursor

upstack uses the SKILL.md standard. Clone the repo, then copy the skills into your tool's skill directory:

```bash
git clone https://github.com/Upsolve-Labs/upstack.git ~/.claude/skills/upstack

# Codex
cp -r ~/.claude/skills/upstack/skills/* .agents/skills/

# Cursor
cp -r ~/.claude/skills/upstack/skills/* .cursor/skills/

# Gemini CLI
cp -r ~/.claude/skills/upstack/skills/* .gemini/skills/
```

Skills are plain markdown — they work in any agent that reads SKILL.md files.

## See It Work

```
you:    I want to build a telemetry dashboard for my SaaS app
you:    /plan
claude: [audits codebase, compares 2-3 alternatives, maps error paths, test coverage diagram, implementation plan, structured tickets with dependency DAG, offers to materialize to Linear/TODOS.md]

you:    /execute
claude: [navigates your app with agent-browser, writes failing tests, implements, confirms green]
        or: /execute --ticket P1-3
claude: [reads ticket brief, checks dependencies, scopes tests to acceptance criteria, implements, marks done in TODOS.md]

you:    /validate
claude: [walks through every planned path manually, screenshots UI, saves API examples to evidence/]

you:    /review
claude: [diffs against base branch, finds bugs and security issues, numbered findings like 1A, 2A]

you:    /ship-pr
claude: [writes docs, bumps version, opens PR with screenshots and Linear links]
```

## Workflow

```
/plan -> /execute -> /validate -> /review -> /ship-pr
```

| Skill         | What It Does                                                                           |
| ------------- | -------------------------------------------------------------------------------------- |
| **/plan**     | Purpose, scope, eng review, test proposal, implementation proposal, structured tickets with dependency DAG, optional Linear materialize. Tests before code. |
| **/execute**  | RED: write failing tests. GREEN: implement. Atomic commits. Supports `--ticket <ID>` for ticket-scoped execution with dependency checks and scope guardrails. |
| **/validate** | Manually verify every path works. Save screenshots + API examples to `evidence/`.      |
| **/review**   | Senior engineer code review against base branch. Best in a clean conversation.         |
| **/ship-pr**  | Docs, version bump, PR with evidence screenshots and Linear links.                     |

Automated flow:

| Skill            | What It Does                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **/upstack-run** | Full sprint: plan -> execute -> validate -> review -> ship-pr. Loops until clean, ends with a pushed PR. |

Independent skills:

| Skill            | What It Does                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **/qa-review**   | Exploratory testing: traverse UI with agent-browser, find edge cases, screenshot findings. |
| **/advisor**     | Analyze git state and recommend which skill to run next.                                   |
| **/setup**       | Check prerequisites and verify installation.                                               |
| **/upgrade**     | Pull latest upstack with backup.                                                           |

## Dependencies

| Tool | Required? | Why | Install |
| --- | --- | --- | --- |
| **[gh](https://cli.github.com/)** | Yes | `/ship-pr` uses it to push commits, create/update PRs, and generate release notes. | macOS: `brew install gh` · Linux: [see docs](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) · Windows: `winget install --id GitHub.cli` |
| **[agent-browser](https://github.com/vercel-labs/agent-browser)** (by Vercel) | Yes | `/plan`, `/validate`, `/review`, `/qa-review` use it to navigate frontend, click around the browser, and screenshot functionality. | macOS: `brew install agent-browser` · Other: `npm install -g agent-browser` |
| **[linear-cli](https://github.com/schpet/linear-cli)** | Optional | `/plan` materialize phase creates Linear tickets from structured plan output. `/execute` updates ticket status during work. Falls back to `TODOS.md` when unavailable. | macOS: `brew install schpet/tap/linear-cli` · Other: `npm install -g linear-cli` |

The install script detects your OS and what's missing, then walks you through each one.

## Upgrade

```
/upgrade
```

Or manually: `cd ~/.claude/skills/upstack && git pull`

## Philosophy

- **Tests before code, always.** Red/Green TDD is the default path.
- **Evidence-based PRs.** Screenshots and API examples ship with every PR.
- **Scope discipline.** Out-of-scope discoveries go to TODOS.md (or Linear tickets), not into the current work.
- **No bloat.** 10 skills, ~450 lines total. No build system, no templates, no binaries.

## License

MIT License. Free and open source.

upstack

upstack Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

upstack

upstack Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README