upiixia-agentic-kit

# UPIIXIA Agentic Kit (uak)

> Multi-agent coordination for AI coding agents (Claude Code, Codex, Cursor, Gemini CLI). Several humans and agents work in parallel on one repo with no server: claims, leases, live summaries, typed messages, bounded verify-fix loops (loop engineering), a task DAG (graph engineering), reviewer rotation and a gated merge queue, all stored on a Git branch; `uak tokens` measures the real token spend per task, model and subagent from local transcripts; `uak map` is a deterministic code graph agents read instead of files; `uak learn` keeps lessons anchored to paths; one Git round trip per call (`uak next` ~2 s on GitHub) and `uak wait` instead of polling; a frontend gate (`product-ui` skill, `uak design-lint` after every UI edit, a design lock picked from screenshots) so screens don't look generated; `uak deploy` writes the Dockerfile and a Render Blueprint (Vercel for Next.js) for the detected stack. Two modes: sprint (hackathons, fast AI prototypes) and marathon (secure, scalable products). Bash 3.2 + Git only. MIT.

Install into a repo: `git clone --depth 1 https://github.com/JoahanMorales/upiixia-agentic-kit ~/.uak-kit && bash ~/.uak-kit/install.sh --mode sprint .` (add `--solo` in marathon when you are the only human on the GitHub repo), then `bash .uak/bin/uak start`: every step to the first claim, in order, and the command that starts.
Try it with no setup (30 s, no keys): `git clone --depth 1 https://github.com/JoahanMorales/upiixia-agentic-kit && bash upiixia-agentic-kit/kit/.uak/bin/uak demo`
Claude Code plugin: `/plugin marketplace add JoahanMorales/upiixia-agentic-kit`, then `/plugin install uak@upiixia-agentic-kit`, then `/uak:setup`.

## Core
- [README](README.md): what it is, quick start, modes, results
- [AGENTS.md (kit core)](kit/AGENTS.md): the 76-line rules every agent follows
- [Sprint mode](kit/.uak/modes/sprint.md): hackathon clock, design lock, freeze, submission
- [Marathon mode](kit/.uak/modes/marathon.md): spec-driven flow, security, scalability, CI

## Reference
- [CLI](kit/.uak/docs/CLI.md): every uak command
- [Protocol](kit/.uak/docs/PROTOCOL.md): claims branch, leases, reviews, merges
- [Subagent orchestration](kit/.uak/docs/ORCHESTRATION.md): fast/balanced/strong tiers for Claude Code (Haiku/Sonnet/Opus 5.5), Codex (GPT-6 Luna/6.1 Sol/6 Astra; GPT-5.6 Luna/Terra/Sol), Cursor (Composer 2.5) and Gemini CLI; strong model only at 3 checkpoints; parallel and strong budgets enforced by hooks
- [Costs and pacing](kit/.uak/docs/COSTS.md): `uak tokens` (the real bill), API prices, Claude Pro/Max, Codex Plus/Pro, Cursor Pro/Ultra limits; `uak pace` spends the 5-hour and weekly windows at the right speed (surge, conserve, critical)
- [Black box](kit/.uak/docs/BLACKBOX.md): `uak bb`, an anonymous flight recorder of kit failures, on by default, harvested across public repos to improve the kit
- [Loop engineering](kit/.uak/docs/LOOPS.md): trigger, verifier, budget, stop, escalation; `uak loop` (stops on no progress or an edited test; `--parallel` per failing file)
- [Graph engineering](kit/.uak/docs/GRAPH.md): members, mandates, message paths, task DAG; `uak graph` (`--assign` suggests who takes what)
- [Security](kit/.uak/docs/SECURITY.md): guards, the secret scanner, the mawk trap, a 22-item launch checklist
- [Why each rule exists](kit/.uak/docs/WHY.md): incident-backed rules

## Evidence
- [Example AI hackathon backlog](examples/ai-hackathon/TASKS.md): 10 tasks, 7 in wave 1
- [Hack-Nation 2026 retro](docs/RETRO-hacknation-2026.md): 5 agents, 4 humans, 76 PRs, with data
- [First black box harvest](docs/blackbox/upiixsol-2026-10.md): 16 kit issues from a 3-day marathon project, each mapped to a v4.1 fix
- [Reap buildathon autopsy](docs/blackbox/reap-2026-10.md): a 4 h event, 11 agents on Codex/Cursor/Claude Code, 13 findings each mapped to a v4.2 fix (scope gate, scaled freeze, `uak allow`, context hygiene)
- [MLB hackathon autopsy](docs/blackbox/mlb-2026-10.md): 10 days, 4 Windows laptops, 13 identities on Claude Code/Codex/Cursor; 15 findings mapped to v4.3 (merge by any agent after approval, approvals that survive merges of main, gate venv, retire, followup, output cap on Windows and Codex)
- [Chilangatón autopsy (first place)](docs/blackbox/chilangaton-2026-10.md): 7 h, 10 Claude Code identities on macOS and Windows; 23 findings mapped to v5.4 (frontend gate, `uak deploy`, reviews only to agents, CI with the stack's tools)
- [HackADA autopsy (first place)](docs/blackbox/hackada-2026-10.md): ~4 h on a repo copied from the previous event (kit v5.3.0); 14 findings mapped to v5.9 (kit-version check in `uak start`, Verify parse and missing-command gates, Verify tools in `doctor`, `.env` in worktrees) or to earlier releases
- [Windows audit of HackADA](docs/blackbox/windows-audit-2026-10.md): the suite and the product on an event laptop (Git Bash, Store python3 alias, Node 20.16, no uv/rg); 19 rows mapped to v5.9.1 (Python run not found in `doctor`, `tzdata`/Node `engines`/`envDir` checks, kit tags from GitHub in `uak start`, hooks through `git`, LF `.gitattributes`)
- [Hacktoberfest autopsy](docs/blackbox/hacktoberfest-2026-10.md): an overnight sprint, 13 identities on Claude Code and Codex; 18 findings mapped to v5.5 (a reject stands, held reviews, gate false positives, `.env.example`, Codex on Windows, plan holes behind a recorded demo); v5.6–v5.7 closed a nine-part audit after it (claims trust, human authority, messages, the merge lock, MCP cancellation); v5.8 carries the frontend gate to every screen (screenshots and the critic's SHIP on done, a locked shell and three screens, a stricter design-lint with contrast)
- [Hackathon in one page](docs/HACKATHON.md): minute-0 commands, `uak clock`, freeze exceptions, fixes per error
- [Inspirations](docs/INSPIRATIONS.md): AGENTS.md, Spec Kit, BMAD, Kiro, Task Master, superpowers