Hammurapi

Hammurapi is a web platform that runs the whole product development cycle with an AI agent as a partner — from an idea or a problem, through specifications with quality gates, to code, validation, release and the value metric — while git stays the source of truth for every document and line of code.

Product managers find it awkward to keep specifications directly in git and markdown, wiki tools don't enforce a sequence of reviews, and coding agents need a finished, approved specification to work from. Hammurapi gives people a WYSIWYG editor, an approval workflow and a chat with an agent; the agent researches issues, writes the technical and QA specifications, implements them in the service repositories as pull requests, and a release goes out only after people sign it off.

This repository holds the documentation, Helm chart and default rules. The code lives in two sibling repositories; the agent is Nabu, the corporate agent platform, which Hammurapi requires:

Repository	What it is
hammurapi-core	Backend: one Go binary with the modes api, worker, cleaner, migrate
hammurapi-web	Frontend: React single-page app with the Milkdown editor
hammurapi (this one)	Docs, Helm chart, rules/

Contents

• Hammurapi SDLC (H-SDLC)
• How it works
• Features
• Installation for your team
• Architecture
• Repository layout
• Documentation
• Development

Hammurapi SDLC (H-SDLC)

The Hammurapi software development lifecycle (H-SDLC) has three stages — Discovery, Development and Delivery. They go one after another in a circle: what a release teaches you becomes the input of the next Discovery.

Stage	What happens	What Hammurapi automates
Discovery	An idea or a problem becomes an issue; its value and a way to measure it are worked out, and the issue is accepted into a feature	The agent analyses every new issue: value, a metric checked against a real metric source, context, similar issues and features
Development	The feature goes through the specifications — product, design, architecture, tech, QA — and becomes code	Quality gates in a strict order, generated tech and QA specifications, code generation into pull requests in every service, CI results linked to test cases
Delivery	The changes are merged, deployed and measured	Merge in the service order, deploy, feature flags, the value metric against its target, confirmation — or one-click rollback

Hammurapi automates this lifecycle. People make the decisions — accept an issue, approve a specification, sign the validation, confirm a release — and Hammurapi with its AI agent does the work between them. Every step is a durable workflow, so nothing is lost on a restart, and git stays the source of truth for every document and line of code. Delivery closes the circle: the value metric of a release confirms the feature, and a rollback returns its issues to Discovery.

How it works

The H-SDLC stages are the pages of the web app:

Discovery     issue ISS.FMS.CAR-0012 (idea | problem)
              → Analysis: the agent writes value, metric and context, finds similar work
              → an expert accepts it into a feature
Development   feature FTR.FMS.CAR-0005
              → product → design → arch  (people write, experts approve)
              → tech, qa                 (generated by the agent, approved by experts)
              → code generation: one task per service, a PR in every repository
              → validation: CI results per QA test case, product and technical signatures
Delivery      release RLS.FMS.CAR-0003
              → merge in the service order → deploy → feature flag → value metric → confirm
              → or rollback: revert, redeploy, flag off, issues back to Discovery

Each gate is a markdown document with a status:

Draft ──submit──▶ Awaiting approval ──approve──▶ Approved
  ▲                                                 │
  └──────────── any edit (by a person or the agent) ┘

• Any edit returns a gate to draft, so an approval always covers the current text. A diff "since the last approval" shows exactly what changed.
• A gate can be approved only after every earlier gate is approved, by a product or technical expert of the domain. Requirements need IDs (**R1.**) so tests and code can trace back to them.
• When the human gates are approved, the agent generates the tech and QA specifications from the rules and the services of the domain; they are read-only and can be regenerated.
• Every step after that is a durable workflow in Postgres: restarts never lose it, failed effects are retried, and a step that keeps failing blocks the run with the reason and waits on the General page for someone to retry or roll back.

Every feature has its own branch and PR/MR in the specification repository, and one branch and PR per service repository. People commit with their own git account; the agent commits as a bot, and every commit carries trailers linking it to the feature, the task and the initiator.

Features

• General page: what waits for you (approvals, signatures, blocked steps, confirmations), and a board of Discovery, Development and Delivery, updated live.
• Discovery: issues from people or the agent, Analysis by the agent (value, a measurable metric checked against a real metric source, context, similar issues and features); accept, reject, merge or move.
• Quality gates for product, design, architecture, tech and QA specifications, with sequential approval, history of every event (author, time, commit) and diffs since approval.
• Code generation: a task per service — a service agent of Nabu works in a sandbox on a copy of the repository, Hammurapi commits the changes as the bot and opens the PR, autonomy chosen by the service owner (plan, pr, autonomous), review comments on the PR go back to the agent, and a coverage matrix of requirements → services → test cases → PRs.
• Validation: JUnit results from CI linked to QA test cases, optional stage deploy and e2e, product and technical signatures.
• Releases: merge in the order of the tech specification, deploy through GitHub Actions, GitLab CI or a webhook (or a manual mark), feature flags, the value metric, confirmation and one-click rollback.
• Services and domains from a Backstage catalog or entered by hand; catalog owners become domain experts and service owners.
• WYSIWYG editor over markdown (CommonMark + GFM: tables, task lists), with deterministic serialization — opening and saving a document never produces a noisy diff.
• AI agent as a partner in a chat on every screen: the personal agent of the user in Nabu, the same as in the messenger, aware of the open issue, feature or release; it acts only within the user's permissions and cannot delete anything.
• Voice input (push-to-talk with a transcript you review before sending), attachments and a personal agent name and tone.
• Rules: document templates per area edited in the admin panel; a change becomes a PR/MR and applies only after another admin of that area approves.
• Import from a zip archive of existing specifications, edit locks, deletion with confirmation (numbers are never reused).
• Five interface languages: English (default), Russian, German, Spanish, Chinese (Simplified); light and dark theme; desktop and mobile layouts.
• GitHub or GitLab (cloud or self-hosted), one provider per instance.

Installation for your team

1. Create the specifications repository on GitHub or GitLab and copy rules/ into it — Hammurapi creates every new document from these templates.
2. Register an OAuth application with the callback URL <PUBLIC_URL>/api/v1/auth/callback:
   • GitLab: an application with scopes api and read_user;
   • GitHub: a GitHub App with user-to-server tokens (contents, pull requests and issues: read & write).
3. Add a webhook (push, tag, merge request / pull request, review and comment events) to the specification repository and every service repository: URL <PUBLIC_URL>/hooks/v1/git, secret WEBHOOK_SECRET. This is how Hammurapi learns about edits, PRs, reviews and tags, including changes made directly in git.
4. Set up the bot: the GitHub App installed on all repositories, or a GitLab bot account with GITLAB_BOT_TOKEN. Then connect CI results, deploy, feature flags, the catalog and metric sources — see docs/cycle.md.
5. Connect Nabu. Hammurapi does not start without it: create the service client of Hammurapi in Nabu and set NABU_URL, NABU_CLIENT_ID, NABU_CLIENT_SECRET. After the first sign-in bind the scenarios to service agents of Nabu in Administration → Nabu (see docs/agent.md).
6. Run it with the Helm chart in helm/hammurapi (see docs/deployment.md).
7. Sign in with a login listed in BOOTSTRAP_ADMINS — it becomes the first global administrator — and make your team area admins and domain experts.

Architecture

Browser ── SPA (hammurapi-web) ──▶ api ──────────────▶ GitHub / GitLab API
              ▲   SSE               │  ▲               (specs, service repos, CI, tags)
              │                     │  │ /mcp/nabu     webhooks: git, CI results, deploy, flags
              │       chat proxy ───┼──┼──────────▶ Nabu (personal agents, service agents,
              │                     ▼  │                  sandboxes for code)
              │                 Postgres ◀── worker ◀── Kafka        ▲ runs, working copies
              └──── NOTIFY ◀────────┘     workflows ─────────────────┘ MCP of runs (:8083)
                             MinIO (attachments, archives)   Whisper (voice)   metric sources

Component	Role
api	REST API for the SPA and admin panel, SSE stream, webhook intake (git, CI results, deploy, flags), the chat proxied to the personal agent of the user in Nabu, /mcp/nabu for the personal agents
worker	Kafka consumers (git events, imports), the workflow engine (Discovery, gate generation, code generation, validation, release, rollback), runs of the service agents of Nabu and their MCP (:8083), code tasks, daily catalog sync
cleaner	Daily job: expired attachments, sessions, locks, unconfirmed imports, leftover branches
migrate	Database migrations (goose), run before api/worker roll out
Postgres	Issues, features, gates, tasks, releases, workflow runs and outbox, users, roles
Git provider	Source of truth for documents, rules and code; accessed only through its API, no local clone
Kafka	Git events (partitioned by repository and feature, so changes are applied in order) and imports
MinIO / S3	Chat attachments and import archives
Whisper	Speech recognition for voice input
Nabu	The agent: models, skills, MCP, sandboxes, usage and audit; required

Key design decisions:

• Git is the source of truth for content, Postgres for statuses. Edits reach the database only through push webhooks, so an edit made directly in git resets approval just like one made in the UI.
• No stale approvals. Before approving, Hammurapi asks the provider for the latest commit of the gate and refuses if the database has not seen it yet.
• The agent's permissions come from the user or the task. A personal agent calls Hammurapi with the roles of its user; each run of a service agent gets a grant for its one job (Discovery of an issue, generation of a gate, the code of one service). There is no delete tool.
• Durable workflows. Every cycle step is a state machine persisted in Postgres with an outbox of effects; workers lease runs with SKIP LOCKED, retry effects with backoff, and block a run with the reason instead of failing silently.
• Code runs in the sandbox of Nabu, git stays in Hammurapi. A code task uploads a working copy of the branch to Nabu; the agent changes it in a sandbox without git credentials; the worker takes the changes, commits them as the bot and opens the PR.

Repository layout of a Hammurapi instance

/rules
  /product/  template.md  fix-template.md
  /design/   template.md  fix-template.md
  /arch/     template.md  fix-template.md
  /tech/     template.md  fix-template.md
  /qa/       template.md  fix-template.md
/specs
  /<domain>/<system>/<feature key>/discovery/discovery.md   (+ materials of the research)
  /<domain>/<system>/<feature key>/<product|design|arch|tech|qa>/spec.md
  e.g. /specs/FMS/CAR/FTR.FMS.CAR-0005/product/spec.md

Commits made by Hammurapi carry trailers — Hammurapi-Feature, Hammurapi-Area, Hammurapi-Agent for agent edits, Hammurapi-Generated for generated gates, Hammurapi-Task, Hammurapi-Req and Hammurapi-Initiator for code, Hammurapi-Release for merges and reverts, Hammurapi-Import, Hammurapi-Delete — so every change is traceable in git.

Documentation

Document	Contents
docs/configuration.md	Every environment variable
docs/git-providers.md	GitHub App / GitLab application, webhook, repository setup
docs/cycle.md	Development cycle: bot, services and catalog, code tasks, CI results, deploy, feature flags, metric sources, releases
docs/agent.md	Nabu as the agent: the chat, service agents of the scenarios, code in the sandbox, MCP tools, LLM errors
docs/deployment.md	Kubernetes (Helm)
docs/operations.md	Health checks, metrics, logs, tracing, backups, troubleshooting
docs/api.md	HTTP API overview and error codes
docs/development.md	Local development and tests

Development

# backend (Go 1.27)
cd ../hammurapi-core && make test && make test-integration   # integration needs Docker

# frontend (Node 24)
cd ../hammurapi-web && npm ci && npm test && npm run dev      # dev server proxies to localhost:8080

See docs/development.md.

License

Apache License 2.0 — see LICENSE.