{"id":51305085,"url":"https://github.com/adeelahmad/agentic-agile","last_synced_at":"2026-06-30T23:03:04.338Z","repository":{"id":363338243,"uuid":"1262782929","full_name":"adeelahmad/agentic-agile","owner":"adeelahmad","description":"Claude Code plugin for agentic agile + autonomous TDD: hook-enforced AI coding agents that plan sprints, then write code RED→GREEN with deterministic gates. Agentic workflow for LLM developer tools.","archived":false,"fork":false,"pushed_at":"2026-06-08T13:31:41.000Z","size":385,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-08T14:18:09.542Z","etag":null,"topics":["agentic-ai","agentic-workflow","agile","ai-agents","ai-assistant","ai-coding","anthropic","automation","autonomous-agents","claude","claude-code","coding-agent","developer-tools","generative-ai","llm","mcp","plugin","rust","tdd","test-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/adeelahmad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-08T10:11:27.000Z","updated_at":"2026-06-08T13:22:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adeelahmad/agentic-agile","commit_stats":null,"previous_names":["adeelahmad/agentic-agile"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/adeelahmad/agentic-agile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2Fagentic-agile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2Fagentic-agile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2Fagentic-agile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2Fagentic-agile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adeelahmad","download_url":"https://codeload.github.com/adeelahmad/agentic-agile/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adeelahmad%2Fagentic-agile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34986248,"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-30T02:00:05.919Z","response_time":92,"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","agentic-workflow","agile","ai-agents","ai-assistant","ai-coding","anthropic","automation","autonomous-agents","claude","claude-code","coding-agent","developer-tools","generative-ai","llm","mcp","plugin","rust","tdd","test-driven-development"],"created_at":"2026-06-30T23:03:03.455Z","updated_at":"2026-06-30T23:03:04.322Z","avatar_url":"https://github.com/adeelahmad.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \n  # 🤖 agentic-agile\n  \n  ### Agentic agile + autonomous TDD for Claude Code — AI coding agents that plan your sprint, then write the code with hook-enforced, deterministic gates.\n  \n  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n  [![CI](https://github.com/adeelahmad/agentic-agile/actions/workflows/ci.yml/badge.svg)](https://github.com/adeelahmad/agentic-agile/actions/workflows/ci.yml)\n  [![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-D97757)](https://docs.anthropic.com/en/docs/claude-code)\n  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n  [![Stars](https://img.shields.io/github/stars/adeelahmad/agentic-agile?style=social)](https://github.com/adeelahmad/agentic-agile/stargazers)\n  \n  *Determinism comes from hooks, not model goodwill.*\n  \n  \u003c/div\u003e\n  \n  ---\n  \n  \u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"docs/diagrams/architecture.png\" alt=\"agentic-agile lifecycle: human-gated planning, autonomous hook-enforced TDD execution, and the deterministic enforcement layer\" width=\"900\"\u003e\n  \u003c/div\u003e\n  \n  ---\n  \n  # agentic-agile\n\nA Claude Code **plugin marketplace** containing the `agentic-agile` plugin:\n**two-stage agile planning** (interactive, human-gated) followed by **two-phase TDD\nexecution** (autonomous, hook-enforced). Determinism comes from hooks, not model\ngoodwill — every sub-agent stop is intercepted by a deterministic gate that can\nblock the stop and feed the failure reason back to the supervisor.\n\n\u003e This repository is self-contained and publishable as-is. The plugin lives in\n\u003e [`plugin/`](plugin/); the marketplace catalog is\n\u003e [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json).\n\n## Quick start\n\n```bash\n# 1) Build + install the gate backends (ctx-symbols + md-db, both from source)\n#    requires a Rust toolchain \u003e= 1.82 (rustup.rs or `brew install rust`)\n./plugin/tools/install.sh\n#    ensure ~/.local/bin (or ~/.cargo/bin) is on PATH\n\n# 2) Add the marketplace and install the plugin (inside Claude Code)\n/plugin marketplace add adeelahmad/agentic-agile\n/plugin install agentic-agile@agentic-agile-marketplace\n/reload-plugins   # apply hooks without a full restart\n#    (for local dev, point marketplace add at your checkout instead: ./path/to/repo)\n```\n\n\u003e **Staying current:** third-party marketplaces don't auto-update by default — run\n\u003e `/plugin marketplace update agentic-agile-marketplace` (or enable auto-update in\n\u003e `/plugin` → Marketplaces), then `/reload-plugins`. Step 1 (the Rust-built `ctx-symbols`\n\u003e + `md-db`) is what makes the gates run at full strength; without it they degrade to grep.\n\n## Using it\n\nThe plugin ships one skill — **`agentic-agile`** — which acts as the *supervisor*. You\ndon't invoke the 9 sub-agents or the gates directly; the skill dispatches them and\nreacts to gate verdicts. Two ways to start it inside Claude Code:\n\n- **Just ask.** The skill is model-invoked, so it auto-triggers on build / ship /\n  implement / add-a-feature / fix-via-TDD requests — even if you never say \"agile\":\n\n  ```\n  Build a rate limiter as a sprint with strict TDD.\n  Plan and implement the CSV export feature — tests first, with gates.\n  ```\n\n- **Explicitly**, via the namespaced entry-point command:\n\n  ```\n  /agentic-agile:init\n  ```\n\n  (`init` is a thin alias that loads the same supervisor playbook; the underlying\n  skill is also directly invokable as `/agentic-agile:agentic-agile`.)\n\nOnce started:\n\n1. **Planning (you're in the loop):** intake → standards → planner produce the sprint\n   contract + per-story `tasks.md` / `validate.md` / `plan.md`. The skill **stops for\n   your approval** — it will not start building until Stage-2 is approved.\n2. **Execution (autonomous):** after approval it runs RED → SCAFFOLD → GREEN →\n   STRUCTURAL-REVIEW per wave, then a once-per-sprint FINAL-GATE, each enforced by a\n   deterministic hook gate.\n\nThe gate backends (`ctx-symbols`, `md-db`) must be on PATH — see step 1 above. Without\nthem the gates WARN and fall back to grep (never a false block, never a silent pass).\n\n## What it does\n\n- **Planning** (human present, one sprint at a time): the supervisor *dispatches* the\n  `intake` → `standards` → `planner` agents to produce the sprint contract + per-story\n  `tasks.md` / `validate.md` / `plan.md` — then stops for your approval.\n- **Execution** (human absent): per wave, RED → SCAFFOLD → GREEN → STRUCTURAL-REVIEW,\n  then once per sprint a FINAL-GATE. One **git-worktree-isolated** sub-agent per task\n  (the harness's built-in `isolation: \"worktree\"`, on any committed git repo); merge on\n  pass, abandon the chain on a foundation-poisoning halt.\n- **Determinism is structural, not vibes.** Hooks enforce the invariants the model\n  can't talk its way past: the supervisor can't write production source\n  (`gate-supervisor-scope`), can't start execution with its backends missing\n  (`gate-tooling`), can't drop worktree isolation, and can't pass a sub-agent stop whose\n  gate failed (`gate-red/scaffold/green/structural/final-verify`).\n- **Agent comms** are a story-bound, append-only `init.md` ⇄ `output.md` pair: the\n  supervisor appends each dispatch's contract, the agent appends its report — the full\n  negotiation history, enforced (`validate_comms` blocks a dispatch that left no report).\n- **Transcripts**: full capture — every tool call's input *and* output, every user\n  prompt, and a complete session snapshot (all messages + thinking) per task, plus a\n  thin cross-task causal stream. Each sub-agent gets a READ-ONLY slice; the supervisor\n  reads the whole store.\n- **Retrospective + memory**: every planning session distills recurring failures (and\n  your own insights) into `docs/agents/memory.md`, injected into each sub-agent's contract.\n\nFull operator playbook: [`plugin/skills/agentic-agile/SKILL.md`](plugin/skills/agentic-agile/SKILL.md).\n\n## Token efficiency (a measured run)\n\n**TheNoteBook** — a full Go backend — was built with this plugin from a `README` +\n`/agentic-agile:init` + a handful of prompts. Measured directly from the Claude Code\ntranscript and the resulting repo:\n\n| Metric | Value |\n|--------|-------|\n| **Output tokens** | **~1.55M** total |\n| **Model mix** (by output) | **76% Sonnet 4.6 · 24% Opus 4.8** |\n| Agent turns | ~1,140 |\n| Input cache hits | **99.9%** — 135M cache-read vs 0.11M fresh read |\n| **Produced** | 18 internal packages · ~6.1K LOC production Go + ~11.3K LOC tests · **322 tests** · 74 commits across 6 sprints |\n\nThat's a fully-tested ~17K-LOC backend for **~1.5M output tokens**. The leanness is\nstructural, not luck:\n\n- **Scoped context per worker** — each sub-agent runs in its own git worktree carrying\n  only its task's contract (`init.md`) + the tests, never the whole repo, so cheaper\n  models (Sonnet did 76% of the work) handle most tasks.\n- **Gates verify deterministically** — `validate_comms`, `ctx-symbols`, `md-db`, and the\n  RED/GREEN/structural checks replace expensive model reasoning and re-reads.\n- **Caching covers ~99.9% of input**, and the hooks keep the orchestrator cheap by\n  blocking it from doing the context-heavy work itself.\n\nThese mechanisms are codebase-agnostic — greenfield is simply what's measured here.\n\n## Prerequisites\n\n| Tool | Required? | Purpose | Install |\n|------|-----------|---------|---------|\n| **ctx-symbols** | recommended | symbol uniqueness (`count==1`) + duplicate/orphan detection | `./plugin/tools/install.sh` (builds from `plugin/tools/ctx-symbols`) |\n| **md-db** | recommended | validates `.md` artifacts against `plugin/schemas/*.kdl` | `./plugin/tools/install.sh` (builds from vendored `plugin/tools/md-db`, AGPL-3.0) |\n| **Rust toolchain** | required to install | builds both backends; also runs the target repo's fmt/clippy/test/coverage matrix | rustup (\u003e= 1.82) |\n\nBoth backends are optional: absent → gates WARN and fall back to grep (never a false\nblock, never a silent pass). See [`plugin/README.md`](plugin/README.md) for the gate\nenv-contract and how to retarget a non-Rust repo.\n\n## Layout\n\n```\n.claude-plugin/marketplace.json   marketplace catalog (source: ./plugin)\nplugin/                           the installable plugin (see plugin/README.md)\ndocs/                             design + architecture docs for this plugin\n  ARCHITECTURE.md DESIGN.md PLATFORM-NOTES.md KICKSTART.md\n  agentic-agile-design.html diagrams/\nDEVLOG.md                         build journal + review dispositions\n```\n\n## Development (Makefile)\n\n`make` (no target) prints all targets. Common ones:\n\n```bash\nmake install        # build + install ctx-symbols and md-db to ~/.local/bin\nmake link           # register THIS repo as a local marketplace and install the plugin\nmake ci             # everything CI runs: fmt-check · lint · test · eval-validate\nmake test           # ctx-symbols + md-db unit tests\nmake lint           # clippy -D warnings + shellcheck + JSON sanity\nmake validate       # claude plugin validate ./plugin --strict\nmake eval-validate  # validate every eval suite's JSON (no tokens)\nmake eval SUITE=…   # run one eval suite live (YES=1 spends tokens; see scripts/eval/)\nmake hooks          # install the tracked git hooks (.githooks → core.hooksPath)\nmake smoke          # offline gate smoke test\nmake release        # verify (ci+validate+version-check) then tag vX.Y.Z\nmake publish        # push branch + tags to origin\nmake package        # bundle the release into package/ + publish the GitHub release (gh)\n```\n\nGit hooks (opt in with `make hooks`): **pre-commit** runs `fmt-check · json ·\neval-validate · version-check` (fast, no tokens); **pre-push** runs the full\n`make ci` (`fmt-check · lint · test · eval-validate`). Bypass with `SKIP_HOOKS=1`\n(e.g. `SKIP_HOOKS=1 git commit …`) for an intentional WIP commit or a known-failing\nlocal dependency.\n\n## Versioning \u0026 changelog\n\n[SemVer](https://semver.org); see [`CHANGELOG.md`](CHANGELOG.md). Keep the version in\n`plugin/.claude-plugin/plugin.json`, `plugin/tools/ctx-symbols/Cargo.toml`, and the\ntop `CHANGELOG.md` entry in lockstep — `make version-check` (and `make release`)\nenforce this. Tag releases `vMAJOR.MINOR.PATCH`.\n\n## First publish\n\n```bash\ngit init \u0026\u0026 git add -A \u0026\u0026 git commit -m \"agentic-agile v0.1.0\"\ngit remote add origin \u003cyour-repo-url\u003e\nmake hooks          # optional: enable local git hooks\nmake ci             # green before tagging\nmake release        # tags v0.1.0\nmake publish        # pushes branch + tags\n```\n\n## Continuous integration\n\n`.github/workflows/ci.yml` runs on every push/PR:\n\n- **ctx-symbols** — `cargo fmt --check`, `cargo clippy -D warnings`, `cargo test`.\n- **shellcheck** — lints every gate script (`plugin/bin/*`), errors fail the build.\n- **plugin validate** — JSON sanity on the manifest + marketplace, then\n  `claude plugin validate ./plugin --strict` (installs the Claude Code CLI).\n\n## Status\n\nPublished at [github.com/adeelahmad/agentic-agile](https://github.com/adeelahmad/agentic-agile).\nThe standards matrix targets **Rust** by default (retarget by editing `standards.md` +\nthe gates — see [`plugin/README.md`](plugin/README.md)). Gate bodies are unit-tested and\nverified offline (positive + negative); CI runs `plugin validate` but not a live session,\nso smoke-test the hook wiring in a real Claude Code session before relying on it\nend-to-end.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE). `ctx-symbols` is harvested from the MIT-licensed\n`ctxconfig` code-intelligence layer (see `plugin/tools/ctx-symbols/README.md`).\n\n`plugin/tools/md-db/` is **vendored third-party source under AGPL-3.0-or-later**\n([decisiongraph/md-db-rs](https://github.com/decisiongraph/md-db-rs)), kept under its\nown [`LICENSE`](plugin/tools/md-db/LICENSE). It is built into a standalone `md-db`\nbinary the gates shell out to — the MIT plugin code links to none of it — but anyone\nredistributing this repository must honor AGPL-3.0 terms for that subtree.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadeelahmad%2Fagentic-agile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadeelahmad%2Fagentic-agile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadeelahmad%2Fagentic-agile/lists"}