{
  "markdown": "# unagi\n\n> Spec-driven AFK coding. Think first, then walk away to working, tested code.\n\nUnagi is a set of Claude Code skills and a bash loop that takes features from idea to pull request — autonomously. It combines **spec-driven development** (research → spec → plan → tasks) with the **ralph loop** (autonomous TDD implementation). Runs on Claude Code, Cursor, Windsurf, Cline, Copilot, Gemini, opencode, Codex, and more.\n\nThe methodology: think carefully, write a spec, generate tasks, walk away.\n\n---\n\n## How it works\n\n```\nSPEC-DRIVEN PHASE                    IMPLEMENTATION PHASE (ralph loop)\n─────────────────                    ────────────────────────────────────\n/research \"what to build\"            Each iteration:\n  └─ parallel subagents              1. Find next - [ ] item in PRD.md\n       investigate                   2. Write failing test (RED)\n                                     3. Implement minimum code (GREEN)\n/spec \"add CSV export\"               4. Run all tests — must pass\n  └─ structured spec.md              5. Commit\n       WHAT + WHY                    6. Update progress.md\n                                     7. Mark - [x] in PRD.md\n/plan specs/.../spec.md\n  └─ technical plan.md       →   PRD.md   →   ./scripts/ralph.sh\n       HOW                        (tasks)       (repeats N times)\n\n/tasks specs/.../spec.md\n  └─ generates PRD.md\n       atomic stories\n\nHTML OUTPUT (optional, any stage)\n──────────────────────────────────\n/html   specs/.../     → spec.html + plan.html + research.html\n/diagram specs/.../    → diagram.html  (SVG architecture / flow)\n/slides  specs/.../    → slides.html   (keyboard-navigable deck)\n/pr writeup | review   → pr.html       (PR narrative or diff review)\n```\n\nEach ralph iteration spawns a **fresh agent context**. The spec and progress files are the only memory. Stateless, auditable, capable of running for hours.\n\n---\n\n## Install\n\n**macOS / Linux / WSL / Git Bash** — requires Node ≥18\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/curiousfurbytes/unagi/main/install.sh | bash\n```\n\n**Windows (PowerShell 5.1+)**\n\n```powershell\nirm https://raw.githubusercontent.com/curiousfurbytes/unagi/main/install.ps1 | iex\n```\n\n**Local clone**\n\n```bash\ngit clone https://github.com/curiousfurbytes/unagi.git\ncd unagi\nnode bin/install.js\n```\n\nThe installer detects which AI coding agents are on your machine and installs the skills to each one automatically. To see what it found:\n\n```bash\nnode bin/install.js --list\n```\n\n---\n\n## What you get\n\n### Spec-driven development skills\n\n| Command | What it does |\n|---|---|\n| `/research <topic>` | Spawn parallel subagents to investigate before writing a spec |\n| `/spec <description>` | Create a structured specification: WHAT users need + WHY |\n| `/plan <spec-path>` | Generate a technical plan (HOW): architecture, decisions, risks |\n| `/tasks <spec-path>` | Break spec + plan into a `PRD.md` for the ralph loop |\n\n### HTML document skills\n\nTurn specs, plans, and diffs into browser-ready documents — no external dependencies, open in any browser.\n\n| Command | What it produces |\n|---|---|\n| `/html <path>` | Styled HTML from `research.md`, `spec.md`, or `plan.md`; pass a directory to render all three |\n| `/diagram <path>` | SVG architecture map or process flowchart — click nodes to see details |\n| `/slides <path>` | Keyboard-navigable slide deck from a spec or plan (← → Space to advance) |\n| `/pr writeup` | Author narrative: motivation, before/after, file-by-file tour, test plan |\n| `/pr review` | Annotated code review: risk map, diff view with inline comments, blocking-issues checklist |\n\n### AFK implementation skills\n\n| Command / Script | What it does |\n|---|---|\n| `/afk` | Enter AFK mode: pick next task, TDD cycle, commit, update progress |\n| `/ralph` | Quick PRD creation through an interview (no spec/plan needed) |\n| `/ralph-loop` | Show loop status and commands; explain the loop architecture |\n| `./scripts/ralph-once.sh` | Single HITL iteration — watch before going AFK |\n| `./scripts/ralph.sh [N]` | AFK loop: run N iterations (default 10) |\n\n---\n\n## Step-by-step usage\n\n### 1. Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/curiousfurbytes/unagi/main/install.sh | bash\n```\n\n### 2. Go to your project and create a branch\n\n```bash\ncd my-project\ngit checkout -b feat/my-feature\n```\n\n### 3. (Optional) Research first\n\nFor complex features or unfamiliar codebases:\n\n```\n/research \"add CSV export for user data\"\n```\n\nClaude spawns parallel subagents — each investigating a specific angle — and produces `specs/<date>-<name>/research.md`.\n\n### 4. Create a spec\n\n```\n/spec Add CSV export for user data\n```\n\nClaude interviews you (actors, constraints, success criteria) and writes a structured `spec.md`. The spec captures WHAT users need and WHY — not HOW to build it.\n\nOr use the quick `/ralph` path if you don't need a formal spec:\n```\n/ralph   ← interview-style PRD creation, skips spec/plan\n```\n\n### 5. Generate the technical plan\n\n```\n/plan specs/20260511-csv-export/spec.md\n```\n\nClaude reads the spec, investigates the codebase, makes architecture decisions, and writes `plan.md` with implementation order and risk assessment.\n\n### 6. (Optional) Render as HTML documents\n\nBefore generating tasks, you can turn your spec and plan into polished browser-ready documents:\n\n```\n/html specs/20260511-csv-export/      ← renders research.html + spec.html + plan.html\n/diagram specs/20260511-csv-export/plan.md  ← implementation-order flow diagram\n/slides specs/20260511-csv-export/spec.md   ← slide deck for design review (← → Space)\n```\n\nAll outputs are self-contained `.html` files — no server, no build step, just open in a browser.\n\nAfter the ralph loop finishes, document the PR:\n\n```\n/pr writeup   ← author narrative (motivation, before/after, file tour)\n/pr review    ← annotated review (risk map, diffs, blocking issues)\n```\n\n### 7. Generate the task list (PRD.md)\n\n```\n/tasks specs/20260511-csv-export/spec.md\n```\n\nClaude breaks the plan into atomic, right-sized stories and writes `PRD.md` — the input to the ralph loop. Each story traces back to a spec requirement.\n\n### 8. Set up AGENTS.md\n\nTell the loop how to run your tests:\n\n```bash\ncp /path/to/unagi/templates/AGENTS.md AGENTS.md\n# edit to add your test runner, lint, build commands\n```\n\n### 9. Watch one iteration (HITL)\n\n```bash\n./scripts/ralph-once.sh\n```\n\nWatch what the agent does. Does it find the right task? Write tests first? Commit cleanly? Run 2–3 times until you trust the loop.\n\n### 9. Go AFK\n\n```bash\n./scripts/ralph.sh           # 10 iterations (default)\n./scripts/ralph.sh 25        # custom count\n./scripts/ralph.sh 10 my.md  # custom PRD file\n```\n\nWalk away. The loop exits when all items are done or the iteration limit is reached.\n\n### 10. Review and open a PR\n\n```bash\ngit log --oneline\nnpm test                       # verify everything passes\ncat progress.md                # read implementation notes\ngit push -u origin feat/my-feature\n```\n\nGenerate a PR document while you're at it:\n\n```\n/pr writeup   ← beautifully formatted author narrative as pr.html\n/pr review    ← annotated diff review with risk classification as pr.html\n```\n\nSee [docs/workflow.md](docs/workflow.md) for the complete Linear → PR walkthrough.\n\n---\n\n## Spec-driven development\n\nInspired by [alexop.dev](https://alexop.dev/posts/spec-driven-development-claude-code-in-action/) and [github/spec-kit](https://github.com/github/spec-kit).\n\nThe core insight: **specs as the source of truth, code as their expression**. Writing a clear spec before implementing produces better code and catches ambiguity before it becomes a bug.\n\n```\n┌─ SPEC PHASE ─────────────────────────────────────────────────────────────────┐\n│                                                                               │\n│  /research \"topic\"                                                            │\n│    ├── Agent 1: existing patterns in codebase      ─┐                        │\n│    ├── Agent 2: library options                      │ parallel               │\n│    ├── Agent 3: data model impact                    │ (faster than seq.)     │\n│    └── Agent 4: edge cases & failure modes         ─┘                        │\n│                 │                                                             │\n│                 ▼                                                             │\n│  /spec \"description\"    →    specs/<date>-<name>/spec.md                    │\n│    - WHAT users need                  - Functional requirements (REQ-NNN)    │\n│    - WHY it matters                   - Non-functional (NFR-NNN)             │\n│    - Actors & stories                 - Success criteria                     │\n│                 │                                                             │\n│                 ▼                                                             │\n│  /plan spec.md          →    specs/<date>-<name>/plan.md                    │\n│    - HOW to implement         - Architecture decisions + rationale           │\n│    - Files to change          - Risks & mitigations                          │\n│    - Implementation order     - Testing strategy                             │\n│                 │                                                             │\n│                 ▼                                                             │\n│  /tasks spec.md         →    PRD.md                                         │\n│    - Atomic stories           - Each traces to REQ-NNN                      │\n│    - Sized for one context    - Ordered by dependency                        │\n│    - Parallel markers         - Ready for ralph loop                         │\n└───────────────────────────────────────────────────────────────────────────────┘\n                 │\n                 ▼\n┌─ IMPLEMENTATION PHASE ────────────────────────────────────────────────────────┐\n│  ./scripts/ralph.sh  →  for each - [ ] in PRD.md:                           │\n│    RED → GREEN → refactor → commit → update progress → mark done             │\n└───────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Spec quality principles (from github/spec-kit)\n\n- **WHAT + WHY, never HOW**: specs describe user needs, not implementation details\n- **Testable requirements**: every `REQ-NNN` has a clear pass/fail condition\n- **Constitutional governance**: `AGENTS.md` carries project principles the loop respects\n- **Research before speccing**: parallel agents find facts; specs record them; plans act on them\n\n---\n\n## The ralph loop in detail\n\n```bash\n# ralph.sh core logic (simplified)\nfor i in 1..MAX_ITER; do\n  if [ no unchecked items in PRD.md ]; then exit \"All done\"; fi\n\n  claude --dangerously-skip-permissions -p \"\n    Read PRD.md. Find next - [ ] item.\n    TDD: write failing test → implement → all tests pass.\n    Commit. Update progress.md. Mark - [x] in PRD.md.\n    One task only.\n  \"\ndone\n```\n\n**Key principles:**\n\n| Principle | Why |\n|---|---|\n| Fresh context per iteration | No context poisoning; each loop starts clean |\n| Files as memory | PRD.md + progress.md persist; git is the history |\n| Cap iterations | Stochastic systems need circuit breakers |\n| HITL before AFK | Watch first, go AFK when confident |\n| TDD enforced | Tests are the exit criterion for every story |\n| Commit every story | Atomic history; easy to bisect bad iterations |\n\n---\n\n## Multi-agent support\n\nUnagi installs to whichever AI coding agents you have installed:\n\n| Agent | Mechanism | Auto-activates |\n|---|---|:-:|\n| Claude Code | Plugin skills (`/afk`, `/ralph`, `/ralph-loop`) | Yes |\n| Cursor | `.cursor/rules/unagi-afk.mdc` | Yes (with `--with-init`) |\n| Windsurf | `.windsurf/rules/unagi-afk.md` | Yes (with `--with-init`) |\n| Cline | `.clinerules/unagi-afk.md` | Yes (with `--with-init`) |\n| GitHub Copilot | `.github/copilot-instructions.md` | Yes (with `--with-init`) |\n| Gemini CLI | Extension via `GEMINI.md` | Yes |\n| opencode | `AGENTS.md` | Yes (with `--with-init`) |\n| Codex | `.codex/hooks.json` | Yes |\n| Aider | `CONVENTIONS.md` | Yes (with `--with-init`) |\n| Amp | `AGENTS.md` | Yes (with `--with-init`) |\n\nUse any agent with `AGENT_CMD`:\n\n```bash\nAGENT_CMD=codex ./scripts/ralph.sh\nAGENT_CMD=opencode ./scripts/ralph.sh 20\nAGENT_CMD=aider ./scripts/ralph.sh\n```\n\n---\n\n## TDD: red/green in the loop\n\nEvery story goes through the full TDD cycle:\n\n```\n1. RED   → Write a failing test. Run it. It must fail.\n2. GREEN → Write minimum code to pass. Run all tests. All must pass.\n3. Refactor → Clean up. Tests still pass.\n4. Commit → git commit -m \"feat(...): ...\"\n```\n\nThe `/afk` skill enforces this. Claude never marks a story done if tests are failing.\n\n---\n\n## Safety\n\n- **Always run `ralph-once.sh` before going AFK.** Builds intuition for the loop.\n- **Set a reasonable iteration cap.** Default is 10. Use 25–50 for large PRDs.\n- **Run in a sandbox.** `--dangerously-skip-permissions` lets the agent execute arbitrary commands. Use Docker or a VM for untrusted projects.\n- **Keep PRD stories small.** Each story should fit in one context window. If Claude gets stuck, the story is too big — split it.\n- **Commit before starting.** The loop modifies files. Start from a clean git state.\n\n---\n\n## Tests\n\n```bash\nbash tests/ralph.test.sh   # ralph loop scripts\nbash tests/spec.test.sh    # spec-driven skills\n```\n\n---\n\n## Complete workflow\n\nSee [docs/workflow.md](docs/workflow.md) for the full Linear → PR example with all commands.\n\n---\n\n## License\n\nAGPL-3.0 — see [LICENSE](LICENSE)\n",
  "bytes": 13498,
  "sha": "31a471151c1636fa8e8ca1c06e130fa93d5208e11fdfdae72e2b07c5b5c1496b",
  "repo_slug": "curiousfurbytes/unagi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_curiousfurbytes_unagi_9ac3eedb/readme"
}