𓀀 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.

Examples:

• Architectural constraints
• Security rules
• Performance guarantees
• Forbidden patterns
• Non-negotiable principles

If a Phase violates a law, the Phase is invalid.

🖋️ Style

(.ushabti/style.md)

How the project is written and structured.

Examples:

• Directory layout
• Naming conventions
• Testing strategy
• Error handling
• Logging and observability norms

Style may evolve over time. Laws should not, except deliberately.

🏺 The Agents

Ushabti uses seven specialized agents, each with a narrow, enforced role.

🦅 Ushabti Lawgiver

Purpose: Define and maintain project laws.

• Captures invariants into .ushabti/laws.md
• Asks clarifying questions when invariants are ambiguous
• Does not plan work
• Does not write code

This agent establishes the immovable ground rules of the project.

🧱 Ushabti Artisan

Purpose: Define and maintain project style.

• Creates and updates .ushabti/style.md
• Ensures style does not contradict laws
• Encodes "how we build things here"

This agent shapes consistency and readability over time.

🐊 Ushabti Surveyor

Purpose: Onboard existing projects by creating documentation.

• Explores the codebase to understand its structure
• Creates structured documentation in .ushabti/docs/
• Produces an index and working document for tracking progress
• Operates in four parts: Setup, Discovery, Writing, Handoff

This agent does not plan Phases, write code, review work, or define laws or style. It creates documentation only.

The documentation Surveyor creates becomes a critical resource for other agents. Once created, these docs are consulted during planning and updated during development to stay current with the codebase.

📜 Ushabti Scribe

Purpose: Plan a Phase.

• Creates a new Phase directory under .ushabti/phases/
• Writes:
  • phase.md (intent, scope, acceptance)
  • steps.md (explicit work steps)
  • progress.yaml (machine-tracked state)
• Keeps Phases intentionally small and reviewable

The Scribe never writes production code.

🧱 Ushabti Builder

Purpose: Implement the Phase.

• Reads laws, style, and the Phase plan
• Implements steps in order
• Updates progress.yaml truthfully
• Adds new steps if missing work is discovered (never silently)

The Builder does not decide scope and does not declare completion.

👁️ Ushabti Overseer

Purpose: Review and gate the Phase.

• Verifies acceptance criteria
• Verifies laws and style compliance
• Reviews code and tests
• Adds required follow-up steps if needed
• Declares the Phase green when complete

No Phase is complete without Overseer approval.

🧙 Ushabti Vizier

Purpose: Advisory agent for questions and guidance.

• Answers questions about the codebase
• Evaluates technical options and tradeoffs
• Identifies risks and technical debt
• Suggests high-impact work
• Maintains memory at .ushabti/vizier.md
• Curates a Reference Library of official documentation for project technologies

Vizier does not plan, build, or review Phases. It does not modify code, laws, style, or documentation. If asked to make changes, Vizier offers to create a Scribe prompt instead.

🗂️ Cards

Ushabti uses Hieroglyphs-compatible cards to track work items, bugs, and features outside the current Phase. Cards are stored as directories containing a card.md file with YAML frontmatter and markdown body in .ushabti/cards/{slug}/.

When to create cards:

• Capture improvement ideas during planning or implementation
• Document technical debt discovered during development
• Record feature requests or enhancements for later consideration
• Track work that's out of scope for the current Phase

Card workflow:

1. Create a card using the create-card skill (generates UUID, derives slug from title)
2. When ready to work on it, Scribe creates a Phase from the card
3. After the Phase completes, Overseer marks the card as done (updates status: done)

Cards use the Hieroglyphs format with UUID identifiers and status fields, providing alignment with the Hieroglyphs task management tool. Unlike the previous ticket system, cards track lifecycle state with a status field (todo, in-progress, done) rather than moving files to archived directories. See Getting Started for detailed card workflow and examples.

🏛️ Repository Structure

.
├── .claude-plugin/
│   └── plugin.json       # Claude Code plugin manifest
├── .ushabti/
│   ├── laws.md           # Project invariants
│   ├── style.md          # Project conventions
│   ├── docs/             # Project documentation (created by Surveyor)
│   ├── cards/            # Work items (Hieroglyphs-compatible)
│   └── phases/
│       └── NNNN-slug/
│           ├── phase.md
│           ├── steps.md
│           ├── progress.yaml
│           └── review.md
├── agents/               # Agent definitions
├── skills/               # Skill definitions (26 skills)
├── CLAUDE.md
└── README.md

Everything Ushabti needs to reason about the project lives inside the repo.

🧭 How You Use Ushabti

New projects: Bootstrap with Lawgiver (laws) → Artisan (style) → Surveyor (docs), then enter the Phase loop.

Existing projects: Survey first with Surveyor, then establish laws and style, then begin the Phase loop.

Phase loop: Scribe plans → Builder implements → Overseer reviews → repeat.

See Greenfield Projects and Brownfield Projects for detailed workflows.

📜 Documentation in the Loop

The .ushabti/docs/ directory is a living resource that stays current with the codebase. Scribe consults docs when planning, Builder updates them when code changes, and Overseer verifies they're reconciled before approving a Phase. A Phase cannot be marked complete if docs are out of sync with code.

☀️ Design Philosophy

• Iteration over ceremony
• Files over prompts
• Explicit state over vibes
• Small Phases beat big specs
• Review is mandatory, not optional

Ushabti is not trying to replace engineering judgment. It exists to amplify it without losing control.

🏺 Onboarding an Existing Project

Ushabti works with existing codebases. Start with Surveyor to document what exists, then establish laws and style, then begin the Phase loop. The documentation Surveyor creates becomes the foundation for all subsequent planning and development.

See Brownfield Projects for the complete onboarding workflow.

🏜️ Status

Ushabti is under active design.

Agent prompts, schemas, and conventions will evolve—but the core loop and roles are intentional and stable.

🧱 Development

Ushabti is developed using itself. All changes go through the Phase loop: planned by Scribe, implemented by Builder, reviewed by Overseer.