{"id":50949943,"url":"https://github.com/iwo-szapar/yalla","last_synced_at":"2026-06-18T00:30:45.588Z","repository":{"id":364322833,"uuid":"1267386016","full_name":"iwo-szapar/yalla","owner":"iwo-szapar","description":"Self-grounding autonomous coding pipeline for Claude Code. Agents classify → plan → build (test-seam slices) → review (binary gates) → compound, grounded in a project knowledge base of gotchas \u0026 risk checks, held to a Proof Contract: ships only when evidence artifacts prove it. Includes a runnable eval harness that grades every run.","archived":false,"fork":false,"pushed_at":"2026-06-12T15:37:23.000Z","size":146,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T16:17:07.565Z","etag":null,"topics":["agentic","ai-agents","anthropic","autonomous-agents","claude","claude-code","code-review","developer-tools","llm","multi-agent","pipeline","tdd"],"latest_commit_sha":null,"homepage":"https://github.com/iwo-szapar/yalla","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iwo-szapar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-12T13:47:03.000Z","updated_at":"2026-06-12T15:37:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iwo-szapar/yalla","commit_stats":null,"previous_names":["iwo-szapar/yalla"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/iwo-szapar/yalla","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwo-szapar%2Fyalla","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwo-szapar%2Fyalla/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwo-szapar%2Fyalla/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwo-szapar%2Fyalla/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iwo-szapar","download_url":"https://codeload.github.com/iwo-szapar/yalla/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iwo-szapar%2Fyalla/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34471638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agents","anthropic","autonomous-agents","claude","claude-code","code-review","developer-tools","llm","multi-agent","pipeline","tdd"],"created_at":"2026-06-18T00:30:45.478Z","updated_at":"2026-06-18T00:30:45.582Z","avatar_url":"https://github.com/iwo-szapar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Yalla\n\n**Give Claude Code a one-line task. Get back a tested, reviewed pull request.**\n\nYalla is an autonomous coding pipeline for [Claude Code](https://claude.com/claude-code). It turns a description into a planned, built, tested, reviewed, and shipped PR — using specialized agents and adaptive ceremony, **grounded in a project knowledge base** (your gotchas, risk checks, and architecture) and **held to a Proof Contract that a built-in eval harness grades**. A run only ships when evidence artifacts say it's proven. GitHub Issues are the task store; no database or external service required.\n\n```\n/yalla add rate limiting to the public API\n```\n\n```\n        ┌──────────────────── KNOWLEDGE BASE ────────────────────┐\n        │  gotchas · minimum diff · risk gates · review checks ·  │  grounds\n        │  architecture · test seams · task classification         │  every phase\n        └────────────────────────────┬───────────────────────────┘\n                                      ▼\n minimum-diff ─▶ classify ─▶ track ─▶ plan ─▶ work ─▶ test ─▶ review ─▶ compound ─▶ ship\n    │                  │       │       │        │           │          │\n  pick     adversarial build  write \u0026 binary  learnings   PR — only\n  ceremony + diagnosis vertical run    pass/   fed back    if verdict\n  + gates  plan        slices  tests   fail    into the    is PROVEN\n                                       gates   knowledge\n                                      ▲\n        ┌─────────────────────────────┴──────────────────────────┐\n        │  PROOF CONTRACT  →  evidence artifacts (.pipeline/*)     │  grades\n        │  verdict: PROVEN / NOT_PROVEN / INCONCLUSIVE             │  every run\n        │  graded by the eval harness  (npm run eval:yalla:smoke)  │\n        └─────────────────────────────────────────────────────────┘\n```\n\nTwo things wrap the linear pipeline and make it more than a prompt: the **knowledge base** feeds project-specific constraints into every phase, and **compound** routes each run's learnings back into it — so the pipeline gets sharper the more you run it. The **Proof Contract + eval harness** sit underneath, turning \"looks done\" into a graded, artifact-backed verdict.\n\n---\n\n## What it does\n\n| Phase | What happens |\n|-------|--------------|\n| **0 · Minimum Diff + Classify** | Runs the minimum-diff ladder, then picks a `task_type`, risk tier, ceremony mode, evidence mode, and gates. A no-build/docs/config answer, one-line fix, and payment-flow change get different ceremony. |\n| **1 · Track** | Creates (or resumes) a GitHub issue and a worktree branch. |\n| **2 · Plan** | Researches the codebase, designs an approach, and adversarially challenges it. Bugs run a diagnosis gate first. You approve before any code is written. |\n| **3 · Work** | Builds in vertical slices — each one a thin, demoable end-to-end behavior — writing a failing behavior test at the highest correct seam before the implementation that passes it. |\n| **4 · Test** | Runs the suite until green, verifies every acceptance criterion maps to evidence, and records falsifiable verification (`VERIFIED` / `NOT VERIFIED` / `INCONCLUSIVE`). |\n| **5 · Review** | Independent reviewers each answer **one** binary question (security? complexity? correctness?). Any Fail blocks the ship. The author never reviews their own code. |\n| **6 · Compound** | Captures actionable learnings to their smallest lasting home so the same mistake isn't repeated. |\n| **7 · Ship** | Writes `.pipeline/outcome-evaluation.json`, commits specific files, and opens a PR — PR-only by default; never auto-merges unless you asked in this run. |\n\nThe core idea: **keep the universal pipeline small, and activate risk-specific gates only when the diff touches that subsystem.** A docs typo doesn't get dragged through payment, migration, and auth review. A change to your billing code does.\n\n## The Proof Contract\n\nA run is \"done\" only when its **verdict is `PROVEN`** — and `PROVEN` is backed by artifacts, not prose. Before shipping, Yalla writes `.pipeline/outcome-evaluation.json` with a verdict of exactly one of:\n\n- **`PROVEN`** — every acceptance criterion is covered by valid evidence (a passing test, a static check, a browser/API probe, a smoke run), all required review checks pass, and no remaining delta exists. Only `PROVEN` may be called done, complete, or ready to merge.\n- **`NOT_PROVEN`** — evidence or review shows the promise isn't satisfied. An honest outcome, not a failure to hide.\n- **`INCONCLUSIVE`** — local proof is blocked or external evidence is unavailable. Can still open a PR, but the PR clearly says human review or external evidence is needed.\n\nMissing evidence never becomes `PROVEN`. Deterministic proof is preferred — Yalla won't lean on a model judge when a concrete test or check can verify the behavior. This is what stops \"looks done\" from masquerading as \"is done.\"\n\n## Adaptive classification\n\nNot every task deserves the same ceremony. Phase 0 first asks whether code is needed at all, then classifies the work and routes it:\n\n- **minimum-diff gate** — no-build, config/docs, existing code, stdlib/native, installed dependency, one local edit, then new implementation only if the higher rungs fail.\n\n- **tiny-hotfix** — one file or one value with a clear failing test: reproduce, make the smallest fix, rerun the exact test, `git diff --check`, hostile self-review inline. No heavyweight artifacts.\n- **bug / perf / hotfix** — run a **diagnosis gate** before planning: reproduce the symptom, record falsifiable hypotheses, identify a regression seam.\n- **feature** — full vertical-slice build with acceptance criteria written before code.\n- **architecture / refactor** — a depth-and-locality exploration before proposing implementation.\n- **prototype** — throwaway UI or logic prototype first, then plan production work once a direction is chosen.\n\nCeremony modes (`lean` / `standard` / `strict`), evidence modes (`minimal` / `standard` / `strict`), and risk tiers (`low` / `medium` / `high`) scale how much artifact weight and review depth a run carries. They never change the proof rule: only `PROVEN` is success.\n\n## Vertical slices and test seams\n\nYalla builds in **tracer-bullet vertical slices** — each slice is a thin slice of real, demoable, end-to-end behavior, not a horizontal layer (no \"all the models, then all the controllers\"). For every acceptance criterion it writes one **failing behavior test at the highest correct seam** — the public interface a user or caller actually hits (route, endpoint, MCP tool, exported function) — *before* the implementation that makes it pass. Tests cross the public seam and mock only system boundaries; they don't reach into private internals just to satisfy a gate. If no correct seam exists, the run records `TEST_SEAM_BLOCKED` and halts for a decision instead of writing a shallow test.\n\n## `.pipeline/*` evidence artifacts\n\nA run leaves a trail under `.pipeline/` so a reviewer can decide where to look closely instead of re-reading everything:\n\n- `classification.json` — task type, risk tier, evidence mode, gates armed.\n- `minimum_diff_decision` inside `classification.json` — selected ladder rung, reuse targets, skipped complexity, file/LOC budget.\n- `events.jsonl` — append-only run timeline: phase starts, tool/command notes, human decisions, checkpoints, and ship events.\n- `checkpoints/` + `latest-checkpoint.json` — resumable save points after classify, plan, each work slice, test, review, and ship.\n- `goal-contract.json` — desired end state, success criteria, constraints, budget, forbidden shortcuts, and required evidence.\n- `evaluator-results.json` / `loop-state.json` — independent evaluator verdicts and long-running loop decisions.\n- `visual-evidence/` / `benchmarks.json` — optional screenshot, image, and benchmark evidence rendered into the local report.\n- `acceptance-trace.json` — every criterion, its proof mode, and its evidence status.\n- `test-evidence.json` — commands run, pass/fail, falsifiable claim verdicts, smoke evidence.\n- `review-results.json` — each binary check and its verdict.\n- `intent-brief.md` / `progress.md` — what a senior reviewer needs before the diff, and the running build log.\n- `outcome-evaluation.json` — the final `PROVEN` / `NOT_PROVEN` / `INCONCLUSIVE` verdict.\n\nArtifacts are committed only when they explain non-obvious decisions, accepted risks, or review findings a reviewer needs in the diff; routine state stays local and is summarized in the PR body. Tiny hotfixes usually commit none.\n\n## The knowledge base\n\nThe pipeline engine is generic — what makes a run *yours* is the knowledge base in [`knowledge/yalla/`](knowledge/yalla/). It's read on demand at every phase and is the difference between a generic agent and one that knows your codebase:\n\n- **Your gotchas** — the non-obvious rules a new contributor trips on, loaded as hard constraints into every run (defined in your `YALLA.md`).\n- **Review checks** ([`REVIEW-CHECKS.md`](knowledge/yalla/REVIEW-CHECKS.md)) — the binary pass/fail library, including a risk-gate set (payments, migrations, auth, async, email, generated artifacts, UI) that arms only when the diff touches that subsystem.\n- **Project checks, minimum-diff, task classification, test seams, vertical slices, architecture depth, diagnosis** — the methodology files that tell the agents *how* to scope, plan, build, and verify.\n\nIt's also a **closed loop**: the **compound** phase routes each run's learnings back into the knowledge base and your `YALLA.md` gotchas, so the same mistake doesn't recur — the pipeline gets sharper the more you run it. A mature config (see [`examples/sbf/`](examples/sbf/)) carries a couple dozen earned gotchas and a full risk-gate map. An optional [**memory**](knowledge/yalla/MEMORY-PROTOCOL.md) subsystem can also persist those learnings to a project store and recall them before planning (off by default; enabled per-repo via a `memory:` block in `YALLA.md`).\n\n## Why binary review\n\nMost AI review produces \"rate this 1–10\" noise. Yalla forces every reviewer to answer one specific yes/no question with a file, a line, the offending code, and a concrete fix — or to Pass. Binary checks make disagreements resolvable and fixes obvious. The full check library is in [`knowledge/yalla/REVIEW-CHECKS.md`](knowledge/yalla/REVIEW-CHECKS.md).\n\n## The eval harness\n\nYalla ships a runnable TypeScript eval harness that grades the pipeline against itself — it checks that the proof contract holds, the test inventory covers risky categories, and outcomes are scored honestly. It lives at the repo root (`eval/yalla/`), not inside `.claude/`, and needs its own install (deps: `tsx`, `vitest`, `zod`):\n\n```bash\nnpm install\nnpm run eval:yalla:smoke    # runs proof-contract + test-inventory + outcome-quality + coverage suites\nnpm run eval:yalla:minimum-diff\nnpm run yalla:benchmark\n```\n\nThe smoke suite validates that:\n\n- legacy runs fail the strict proof contract while patched runs pass,\n- `INCONCLUSIVE` never gets counted as success,\n- minimum-diff fixtures reject avoidable dependencies, one-use abstractions, and over-budget diffs,\n- payment / auth / async / generated-artifact / UI / migration categories are represented and map to real tests,\n- model judges are rejected where a deterministic seam exists.\n\nThere's also a single-issue **autopilot dry-run** that probes one issue and writes telemetry without mutating GitHub:\n\n```bash\nnpm run yalla:autopilot -- run --issue issue-### --mode dry-run\nnpm run yalla:autopilot -- queue --mode dry-run\n```\n\nThe queue dry-run ranks eligible issues with the `yalla-ready` label, skips block labels, and writes `.pipeline/autopilot-queue-report.json` without mutating GitHub. For scheduled or unattended operation, use the staged runbook in [`docs/autopilot/`](docs/autopilot/). The default posture remains PR-only and dry-run/report-only until the readiness checklist passes.\n\n## Install\n\n### Option A — as a Claude Code plugin (recommended)\n\n```\n/plugin marketplace add iwo-szapar/yalla\n/plugin install yalla\n```\n\nThis installs the full engine — all Yalla skills, 4 agents, and the knowledge base (the skills load it from the plugin via `${CLAUDE_PLUGIN_ROOT}`). The only thing you add to your own repo is a project config:\n\n```bash\n# from your project root — create .claude/YALLA.md and edit it\nmkdir -p .claude \u0026\u0026 curl -sL https://raw.githubusercontent.com/iwo-szapar/yalla/main/YALLA.example.md -o .claude/YALLA.md\n```\n\nThe eval harness (`npm run eval:yalla:*`) and autopilot live in the cloned repo, not the plugin — clone it (Option B) if you want to run or extend those.\n\n### Other agent hosts\n\nYalla also ships compact adapters modeled after the same single-source rule file:\n\n- Codex: `.codex-plugin/plugin.json` plus `skills/` and `AGENTS.md`.\n- OpenCode: `.opencode/plugins/yalla.mjs` injects `hooks/yalla-instructions.cjs` each turn and supports `/yalla lean|standard|strict|off` mode persistence. Copy the plugin plus `hooks/yalla-*.cjs` together.\n- Gemini CLI: `gemini-extension.json` points at `AGENTS.md`.\n- Cursor, Windsurf, Cline, Copilot, Kiro: copy the matching rule file from this repo.\n\nSee [`docs/agent-portability.md`](docs/agent-portability.md). Run `npm run rules:check` before releasing adapter changes.\n\n### Option B — clone + install.sh\n\n```bash\ngit clone https://github.com/iwo-szapar/yalla\ncd your-project\n/path/to/yalla/install.sh .\n```\n\nEither way you end up with:\n\n```\nyour-project/.claude/\n├── skills/            yalla, yalla-plan, yalla-review, yalla-simplify,\n│                      yalla-simplify-audit, yalla-team, yalla-audit\n├── agents/            yalla-lead, yalla-implementer, yalla-tester, yalla-reviewer\n├── knowledge/yalla/   pipeline mechanics (classification, diagnosis, slices,\n│                      seams, artifacts, review checks) + your project checks\n└── YALLA.md           ← your config (the one file you edit)\n```\n\nThe installer copies only the engine (`skills/`, `agents/`, `knowledge/yalla/`) and seeds `YALLA.md`. The eval harness stays at the repo root — it's not part of your `.claude/`.\n\nFor a first-time repository setup, follow [`docs/onboarding/`](docs/onboarding/) after install. It covers the project config, GitHub labels, task template, eval fixtures, and autopilot readiness path.\n\nYou can also run the executable onboarding check from the Yalla repo:\n\n```bash\nnpm run yalla:onboard -- check --config /path/to/your-project/.claude/YALLA.md\nnpm run yalla:onboard -- init --config /path/to/your-project/.claude/YALLA.md\nnpm run yalla:onboard -- labels --dry-run --config /path/to/your-project/.claude/YALLA.md\nnpm run yalla:onboard -- template --dry-run --config /path/to/your-project/.claude/YALLA.md\n```\n\n## Configure\n\nOpen `.claude/YALLA.md` and set five things:\n\n1. **base_branch** — what PRs target (`main`, `develop`, `staging`, …).\n2. **commands** — your `test` / `typecheck` / `build` / `lint` commands.\n3. **test_dir** — where tests live.\n4. **gotchas** — the non-obvious rules a new contributor trips on. This is where your project's hard-won scar tissue lives.\n5. **risk_gates** — which subsystem checks to arm (payments, migrations, async, auth, …).\n\nThat's the whole adaptation. No code changes. See [`CUSTOMIZING.md`](CUSTOMIZING.md).\n\n## Use\n\n```\n/yalla \u003cwhat to build\u003e          full adaptive pipeline, single-agent build\n/yalla lean \u003cwhat to build\u003e     minimum ceremony, same proof contract\n/yalla strict \u003cwhat to build\u003e   strict artifacts and review posture\n/onboard                        guided setup + HTML readiness dashboard\n/yalla-team \u003cwhat to build\u003e     full multi-agent team (heavier, for complex work)\n/yalla-plan \u003cwhat to build\u003e     just the adversarial plan\n/yalla-review                   binary pass/fail review of the current diff\n/yalla-simplify                 deletion-only over-engineering review of the current diff\n/yalla-simplify-audit           repo-wide bloat audit\n/yalla-audit \u003cissue-### | PR#\u003e  post-mortem on a completed run\n/yalla issue-123                resume an interrupted run\n```\n\nOperator run-control helpers are also available from the cloned repo:\n\n```bash\nnpm run yalla:run -- doctor\nnpm run yalla:run -- goal --message \"Ship a verified healthcheck\" --criterion \"returns 200\" --evidence \"npm test\"\nnpm run yalla:run -- event --event stage.started --phase plan --message \"Planning started\"\nnpm run yalla:run -- checkpoint --phase test --message \"Focused tests passed\"\nnpm run yalla:run -- evaluate --evaluator reviewer --verdict PASS --message \"Evidence is sufficient\"\nnpm run yalla:run -- loop\nnpm run yalla:run -- status\nnpm run yalla:run -- report\nnpm run yalla:run -- mine-sessions\nnpm run yalla:run -- resume\nnpm run yalla:run -- rewind --target plan\nnpm run yalla:run -- export\n```\n\nThese commands are deliberately local and non-destructive. `resume` and `rewind` return the checkpoint and next action; they do not run destructive Git commands for you.\n\nRequires the [GitHub CLI](https://cli.github.com) (`gh auth login`) for default GitHub tracking. If you intentionally want no GitHub issue/PR workflow, set `tracking_mode: file-only` in `.claude/YALLA.md`.\n\n## Components\n\n- **Skills** (`skills/`) — the pipeline entry points and orchestration.\n- **Agents** (`agents/`) — the specialists: lead (orchestrator), implementer, tester, reviewer.\n- **Knowledge** (`knowledge/yalla/`) — pipeline mechanics (classification, diagnosis, vertical slices, test seams, artifacts, agent brief, preflight) plus the customizable check definitions in `REVIEW-CHECKS.md` and `PROJECT-CHECKS.md`.\n- **Eval harness** (`eval/yalla/`) — the runnable proof-contract / test-inventory / outcome-quality suites and their fixtures. Repo-root only.\n- **Onboarding docs** (`docs/onboarding/`) — what each repo needs: config, labels, issue shape, project checks, and eval fixtures.\n- **Autopilot docs** (`docs/autopilot/`) — staged scheduler/readiness guidance for moving from local dry-run to PR-only automation.\n\n## A real-world example\n\n`examples/sbf/` contains a sanitized, real production configuration from Second Brain Factory — an 8-subsystem Vite + Vercel + Stripe + Postgres app that has run thousands of tasks through Yalla. The matching real eval fixtures live in `eval/yalla/data/*.json` (drawn from that project's incidents and PRDs) as the worked dataset behind the proof checks. It shows what a mature `YALLA.md`, a project-specific check file, and real proof fixtures look like. Use it as a reference, not a starting point.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiwo-szapar%2Fyalla","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiwo-szapar%2Fyalla","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiwo-szapar%2Fyalla/lists"}