KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

upstack

★ 17 Open GitHub ↗

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

// 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

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README