ushabti

𓀀 Ushabti

Your development practices have been weighed against Ma’at and found wanting. Come. Let us build.

Ushabti is a lightweight, file-backed, agent-driven development system for Claude Code. It is inspired by spec-kit, but deliberately not tied to spec-driven development. Ushabti is optimized for tight iteration loops, not one-shot bootstrapping.

In ancient Egypt, ushabti were small figurines placed in tombs to do work for you in the afterlife. In this project, Ushabti are small agents that do focused work for you so you can stay at the decision layer.

𓀠 Why Ushabti?

The road ahead is long. Let us plan accordingly and proceed carefully, for there are many perils along the way. We need not move but one step at a time.

Ushabti exists to account for, control for, and prevent the common failure modes that crop up in AI-augmented engineering. A common criticism you’ll often hear is: “It may be great that you bootstrapped a project so quickly, but wait until you need to extend and maintain your code.” Everybody agrees you can move fast with AI assistance, but there's a great deal of skepticism that working with AI can produce high quality mantainable code.

Ushabti is designed specifically to make maintainable, extensible codebases work with AI-augmented engineering over an indefinitely long time span. The agents and skills are assembled with that primary goal in mind: enable developers working with AI to create software that can be extended and grown indefinitely.

Ushabti sacrifices some of the raw velocity that unstructured AI development provides, but it invests that lost velocity into producing software that stays stable and extensible for as long as the developer wants to keep working.

🧱 Installation

/plugin marketplace add adamrdrew/marketplace
/plugin install ushabti@adamrdrew

Permissions Configuration

Ushabti skills use read-only bash commands to inspect repository state (e.g., finding the current phase, checking for required files). Following the principle of least privilege, Ushabti grants only the specific commands needed.

Add the following to your project's .claude/settings.json or .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash([ -f *)",
      "Bash([ -d *)",
      "Bash(ls *)",
      "Bash(grep *)",
      "Bash(awk *)",
      "Bash(basename *)",
      "Bash(echo *)",
      "Bash(sed *)",
      "Bash(sort *)",
      "Bash(tail *)",
      "Bash(printf *)"
    ]
  }
}

These permissions grant access to common read-only commands that skills use for file inspection and text processing. If you add new skills that require additional commands, update this list accordingly.

📚 Documentation

New to Ushabti? Start here:

• Getting Started — Prerequisites, installation, agent overview, and the development loop
• Greenfield Projects — Starting a new project from scratch with Ushabti
• Brownfield Projects — Onboarding Ushabti onto an existing codebase
• Tips and Tricks — Advanced patterns and non-obvious techniques

These guides provide detailed walkthroughs and practical examples. The sections below offer a quick overview.

𓁗 Core Idea

Development happens in Phases.

A Phase is a bounded unit of work that is:

1. Planned
2. Implemented
3. Reviewed
4. Completed (green)

Once a Phase is green, you move on. No half-finished work. No drifting scope. No invisible state.

Everything is tracked in files inside the repo, not in chat history.

𓁀 The Phase Loop

Plan → Build → Review
        ↑       ↓
        └── refine ──┘

• Planning produces a Phase folder on disk
• Building modifies code and updates progress
• Review either:
  • declares the Phase complete, or
  • adds concrete follow-up steps and sends it back to Build

There is no implicit “done.” A Phase is done only when the Reviewer marks it green.

☀️ Ir-Kat — Automated Phase Loop

The ir-kat skill ("Do the work" in ancient Egyptian) automates the entire Plan → Build → Review cycle. Give it a PHASE_PROMPT and it orchestrates Scribe, Builder, and Overseer end-to-end, including retry loops if the Overseer kicks back (up to 3 attempts before declaring the phase blocked).

/ir-kat Build a REST API for user management with JWT authentication

Or pass a file:

/ir-kat /path/to/PHASE_PROMPT.md

Ir-kat is also the orchestration layer used by Pharaoh, the autonomous phase runner.

📜 Project Invariants

Ushabti separates what must never change from what evolves.

⚖️ Laws

(.ushabti/laws.md)

Project invariants that must always hold.