UPIIXIA Agentic Kit

Ship with a team of AI coding agents, in parallel, without chaos.

Multi-agent coordination for Claude Code, Codex, Cursor and Gemini CLI. Agents claim tasks, run bounded verify → fix loops, review each other and merge. It works across several humans and machines, with no server: just a Git branch and Bash.

sprint mode wins hackathons · marathon mode ships secure, scalable products

Quick start · Why · Orchestration · Modes · Loop engineering · Graph engineering · Token economy · Results · Contributing

Try it in 30 seconds (no setup, no API key)

git clone --depth 1 https://github.com/JoahanMorales/upiixia-agentic-kit && bash upiixia-agentic-kit/kit/.uak/bin/uak demo

It runs a real 3-agent session in a temp repo with a local Git remote:

• parallel claims, and an overlapping claim rejected;
• a bounded fix loop (LOOP_FAIL → LOOP_FAIL → LOOP_PASS);
• a review of the exact SHA by another agent, then a gated merge;
• a dependent task unlocking by itself;
• the team board.

Quick start

1. Install into any Git repo (30 s; needs Bash 3.2+ and Git):

git clone --depth 1 https://github.com/JoahanMorales/upiixia-agentic-kit ~/.uak-kit
bash ~/.uak-kit/install.sh --mode sprint .          # hackathon / AI prototype
# or: --mode marathon                               # real product: specs, CODEOWNERS, security reviews
# options: --stack fastapi-react   --skills ai,tdd   --update (refresh the engine later)
bash .uak/bin/doctor                                 # minute-0 preflight: remote, gh perms, hooks, freeze, ports

Or, in Claude Code:

/plugin marketplace add JoahanMorales/upiixia-agentic-kit
/plugin install uak@upiixia-agentic-kit
/uak:setup

2. Plan: open your agent in the repo and run /uak-setup, then /uak-plan. Codex, Cursor and Gemini read AGENTS.md natively.

3. Start the team:

bash .uak/bin/uak up 4 --tmux                 # claim the 4 best tasks, one worktree + agent each (tmux)
# or one agent at a time:
bash .uak/bin/wt new HACK-003 --agent ana-1   # branch + worktree + identity + port + claim
bash .uak/bin/uak board --watch 10            # live team kanban for the humans

That's it. uak next always tells every agent what to do next.

Why

One agent in one terminal is easy. Five agents run by four people on three machines is chaos:

• two agents edit the same file;
• one runs out of tokens while holding the task everyone waits on;
• a force-push wipes a teammate's work;
• the human becomes a traffic light for every merge.

This kit is the protocol we used to ship 76 PRs in ~14 hours with 5 agents and 4 humans at Hack-Nation 2026, rebuilt from a data-driven post-mortem of everything that went wrong (retro).

Two modes, one engine

The mode is one line, Mode: in .uak/PROJECT.md. Rules: AGENTS.md · sprint · marathon.

How it works

flowchart LR
  P[Planner<br/>/uak-plan] -->|TASKS.md · uak plan| C[(claims branch<br/>tasks · leases · worklogs · inbox)]
  A1[Agent ana-1<br/>worktree hack-003] <-->|claim · heartbeat · msg| C
  A2[Agent bob-1<br/>worktree hack-004] <-->|claim · heartbeat · msg| C
  A1 -->|PR + evidence| R{Reviewer<br/>by rotation}
  R -->|approve SHA| M[uak merge<br/>or human]
  M --> main[(main)]
  H[Human] -->|one digest| C

• The claims branch is the database. Every state change is a commit pushed fast-forward. Races resolve like Git does: fetch, rebase, re-validate, retry. It works across machines, people and tools.
• Path reservations. Tasks declare Paths. Overlapping claims are rejected, and shared files (lockfiles, schemas, CI) need an owner.
• Typed async inbox. contract, request, review, approve, reject. Hooks inject only the actionable messages into the agent's context.
• Guards. A PreToolUse hook blocks destructive Git, sudo, .env reads and publishing. A UserPromptSubmit hook blocks pasted secrets.

Subagent orchestration: Haiku swarms, Sonnet builds, Opus advises

The best result per token: the strongest model wakes up only where judgment changes the outcome (ORCHESTRATION.md).

• Configured for you: install.sh writes:
  • model: sonnet, advisorModel: opus, effortLevel per mode;
  • CLAUDE_CODE_SUBAGENT_MODEL=haiku, so any unpinned subagent is cheap;
  • spawn depth 1, so there are no nested swarms;
  • per-subagent model, effort and maxTurns.
• Enforced, not just suggested: the guard agent hook caps parallel subagents (4 in sprint, 3 in marathon) and Opus subagents per session (2 / 4), even under ultracode, which bypasses Claude Code's own limit. UAK_ALLOW_OPUS=1 is the human override.
• No advisor tool (Bedrock, Vertex) or a long session: /uak-advise plan|stuck|done sends Opus a ≤40-line packet instead of replaying the whole transcript.
• We checked the viral claims against the docs. /advisor is real; --subagents, "dispatcher pools" and "JEV 16 ms" are not (details).

Loop engineering

Every loop declares a trigger, a verifier, a budget, a stop condition and an escalation, or it isn't allowed (LOOPS.md).

# An unattended, bounded fix loop. Works with any CLI agent that reads a prompt on stdin.
bash .uak/bin/uak loop --verify "uv run pytest -q" --agent "claude -p --permission-mode acceptEdits" --max 5 --task HACK-007
# LOOP_FAIL iteration=1 exit=1 · test_api.py::test_search FAILED
# LOOP_PASS iteration=2 · 12 passed in 1.9s

• Inner loop (/uak-loop): implement → q verify → fix; 5 tries; the same error twice → BLOCKED with that error.
• Hook loops: a heartbeat every 8 min and an inbox poll every 2 min, both throttled and in the background.
• Review loop: done → reviewer by rotation → approve or reject → merge queue.
• Deadline loop: decisions resolve after 15 min (routine only), backlog P0s after 10 min, freeze on schedule.
• Failures are fed back as a 40-line tail, never full logs. Agent output goes to a log file, never into your context.

Graph engineering

A team of agents is a graph: members, mandates, message paths, shared state, routing, traceability. Every edge here is a file or a command (GRAPH.md).

bash .uak/bin/uak graph --min-wave1 4
# GRAPH 9 tasks · 3 waves · critical path 135 min: HACK-002 → HACK-006 → HACK-009
# wave 1 (5): HACK-001 HACK-002 HACK-003 HACK-004 HACK-005
bash .uak/bin/uak graph --mermaid      # live state colors, paste into any PR or issue

uak lint fails on dependency cycles and unknown IDs. Uses contract: edges let consumers work on mocks instead of waiting.

Token economy

Tokens are the scarcest resource of an agent team. Every default is tuned to spend fewer of them:

• AGENTS.md is 60 lines, lint-capped at 100. Detail loads on demand from a trigger table.
• q turns a 2,000-line test log into one line on success, or a 40-line tail on failure.
• Noisy work runs in subagents (a Haiku runner, a Sonnet reviewer); only a summary comes back.
• Only actionable messages are injected. Duplicate broadcasts are gone: 194 of 717 messages in our event were noise.
• Skills are installed per mode: each installed skill's description costs tokens in every session.
• One task = one session, a 6-line handoff, and /clear. Compaction keeps only ID, next step, failures and commands.

Battle-tested: Hack-Nation 2026

5 agents, 4 humans, 3 machines (one a Jetson Orin Nano), 76 PRs in ~14 h. Every v3 rule cites the incident behind it (WHY.md).

70+ integration tests run against real Git processes and local bare remotes, in CI on Linux (mawk) and macOS (BSD awk): cd kit && bash .uak/bin/smoke --package-only.

Works with

Mix them freely: coordination lives in Git, not in any tool.

Commands

Full reference: CLI.md. Example backlog: examples/ai-hackathon. Slash commands: /uak-setup, /uak-plan, /uak-start, /uak-loop, /uak-ship, /uak-review, /uak-handoff, /uak-retro, plus /uak-design-lock and /uak-demo (sprint) and /uak-spec (marathon).

What's inside

AGENTS.md · CLAUDE.md        60-line core every agent reads · Claude Code extras
.uak/bin/                    uak CLI, wt, loop, graph, guard, doctor, q, secret-scan (Bash 3.2, no jq)
.uak/modes/                  sprint.md · marathon.md
.uak/docs/                   CLI · PROTOCOL · LOOPS · GRAPH · SECURITY · WHY
.uak/templates/              PROJECT, TASKS, OWNERS, IDEA, spec, plan, ADR
.uak/skills/                 curated skills (superpowers, Anthropic, Vercel, taste-skill), pinned, licensed
.uak/stacks/fastapi-react/   optional stack preset
.claude/                     slash commands, subagents, hooks (settings per mode)

How it compares

They are complementary: use them for planning or UI, and this kit for coordinating many agents and humans.

FAQ

Do I need a server, a database or an API key? No. Bash, Git and a remote (GitHub, GitLab, or even a bare repo on a USB drive). gh is optional.

How is this different from Spec Kit, BMAD or Task Master? They structure one human's work with agents. This kit coordinates many humans and agents in parallel: claims, leases, reviews, merges. It borrows the best of those for planning (INSPIRATIONS).

And from agent orchestrators or swarms? They spawn agents on one machine. This kit has no daemon: any agent, anywhere, coordinates through git push.

Windows? Yes, with Git Bash. macOS ships Bash 3.2, which is supported.

Will it burn my Opus budget? No. Opus is pinned to checkpoints, and the guard blocks Opus fan-out beyond the per-session budget. Run uak stats to see subagent use by tier.

Is my vibe-coded backend safe to launch? Run /uak-secure. It checks IDOR, enumeration, rate limits, idempotent payments, transactions, CORS, log redaction, backups and 15 more items, each with how to verify it. It leaves the human-only items (key rotation, 2FA, the restore drill, watching the logs) to you.

Is the guard a sandbox? No. It is defense in depth against accidents. For untrusted agents, use your tool's sandbox as well.

Contributing

PRs are welcome, especially stack presets, an i18n locale, new loop and graph checks, and retros from your own hackathon. Read CONTRIBUTING.md: every rule needs evidence, and every engine change needs a test.

License

MIT © Joahan Morales and contributors. Vendored skills keep their licenses (SOURCES).

_{Keywords: multi-agent coding, AI agent team, Claude Code multi-agent, Codex, Cursor, Gemini CLI, AGENTS.md, git worktrees, parallel agents, loop engineering, graph engineering, agentic workflow, hackathon kit, spec-driven development, AI pair programming, agent coordination, vibe coding guardrails.}