{"id":48438408,"url":"https://github.com/yarlson/snap","last_synced_at":"2026-04-06T14:04:31.833Z","repository":{"id":340963270,"uuid":"1162355378","full_name":"yarlson/snap","owner":"yarlson","description":"CLI that turns requirements into committed code.","archived":false,"fork":false,"pushed_at":"2026-03-19T11:36:39.000Z","size":718,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T04:44:53.346Z","etag":null,"topics":["claude","claude-code","codex","ralph","ralph-wiggum"],"latest_commit_sha":null,"homepage":"","language":"Go","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/yarlson.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":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"yarlson"}},"created_at":"2026-02-20T06:46:06.000Z","updated_at":"2026-03-19T11:37:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yarlson/snap","commit_stats":null,"previous_names":["yarlson/snap"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yarlson/snap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarlson%2Fsnap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarlson%2Fsnap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarlson%2Fsnap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarlson%2Fsnap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yarlson","download_url":"https://codeload.github.com/yarlson/snap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yarlson%2Fsnap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31475207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T08:36:52.050Z","status":"ssl_error","status_checked_at":"2026-04-06T08:36:51.267Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["claude","claude-code","codex","ralph","ralph-wiggum"],"created_at":"2026-04-06T14:04:31.744Z","updated_at":"2026-04-06T14:04:31.823Z","avatar_url":"https://github.com/yarlson.png","language":"Go","funding_links":["https://github.com/sponsors/yarlson"],"categories":[],"sub_categories":[],"readme":"# snap\n\nWithout snap, this is your afternoon:\n\n```\nYou: \"implement auth middleware\"  →  Claude writes it\nYou: \"run the tests\"              →  they fail\nYou: \"fix the failing test\"       →  Claude fixes it\nYou: \"review the code\"            →  2 issues found\nYou: \"fix those\"                  →  Claude fixes them\nYou: \"run tests again\"            →  pass\nYou: \"commit this\"                →  done\nYou: \"now do task 2...\"           →  repeat from the top\n```\n\nSame loop, every task, one prompt at a time.\n\nsnap runs the loop for you. `snap plan`, `snap run`, walk away. Come back to tested, reviewed, committed code.\n\n## Quickstart\n\n```bash\n# Install\ngo install github.com/yarlson/snap@latest\n\n# Plan your tasks interactively (creates a session automatically)\nsnap plan my-feature\n\n# Let snap implement everything\nsnap run my-feature\n\n# Or run the full 10-step flow from one task file only\nsnap run --task-file /path/to/custom-task.md\n```\n\nThat's it. `snap plan` walks you through requirements and generates task files. `snap run` picks them up one by one and implements each to completion. If you already have a single task file and no planning docs, `snap run --task-file ...` runs that one file through the same 10-step loop. On a fresh project with no sessions, `snap plan` automatically creates a default session.\n\n### Prerequisites\n\n- Go 1.25.6+\n- [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) in your PATH (default provider)\n- Or: [Codex CLI](https://openai.com/index/introducing-codex/) with `SNAP_PROVIDER=codex`\n- For GitHub remotes: [gh CLI](https://cli.github.com/) (optional, only needed if pushing to GitHub)\n\n## Planning\n\n`snap plan` is an interactive session where you describe what you want to build. Chat about your requirements, type `/done`, and snap generates the full planning scaffold: PRD, technology decisions, design doc, and numbered task files.\n\nIf you already know the scope, say it plainly. Planning mode now treats explicit constraints and exclusions as hard boundaries, asks for clarification instead of \"helpfully\" expanding scope, and keeps generated task files focused on outcomes and acceptance criteria rather than over-prescribing implementation details.\n\n```bash\nsnap plan my-feature           # Chat about requirements, type /done when ready\nsnap run my-feature            # Implements everything\n```\n\nOn a fresh project with no sessions, `snap plan` automatically creates a session. You can also pre-create named sessions with `snap new \u003cname\u003e`.\n\nIf you run `snap plan` again on a session with existing planning artifacts, snap will prompt you to either clean up and re-plan, or create a new session (in interactive mode). Non-interactive mode shows clear instructions to prevent accidental overwrites.\n\nOr skip the chat and feed a requirements file:\n\n```bash\nsnap plan --from requirements.md\n```\n\n### Manual task files\n\nIf you prefer full control, write task files directly in `docs/tasks/` and run `snap run`. Name them `TASK1.md`, `TASK2.md`, etc. (uppercase, numbered). Each should describe what to build, requirements, and acceptance criteria. See `example/` for a working sample.\n\n### Single task file mode\n\nIf you only have one task file, you can skip PRD, TECHNOLOGY, DESIGN, and session setup entirely:\n\n```bash\nsnap run --task-file ./notes/custom-task.md\n```\n\nThe file can have any name and live anywhere on disk. snap still runs the full 10-step implementation flow, and stores resumable state under `.snap/adhoc/`.\n\n## The workflow\n\nEach task goes through 10 steps. snap saves state after every step — interrupt anytime, resume exactly where you left off.\n\n```\nTASK1.md ──┐\n           │   ┌─────────────────────────────────────┐\n           ├──▶│  1. Implement feature               │ ◀─ Thinking model (deep)\n           │   │  2. Verify completeness             │ ◀─ Thinking model (deep)\n           │   │  3. Lint \u0026 test                     │\n           │   │  4. Code review                     │ ◀─ Thinking model (deep)\n           │   │  5. Apply fixes from review         │\n           │   │  6. Re-validate after fixes         │\n           │   │  7. Update docs                     │\n           │   │  8. Commit code                     │\n           │   │  9. Update project context          │\n           │   │ 10. Commit context                  │\n           │   └──────────────────┬──────────────────┘\n           │                      │\nTASK2.md ──┘                      ▼ next task\n```\n\nSteps 1, 2, and 4 use a thinking model (Opus) for deep analysis. The rest use a fast model (Haiku) for speed. Context carries across steps within a task.\n\nAfter each task, snap updates `docs/context/` — a project knowledge base it maintains itself. Architecture decisions, conventions, terminology, and domain knowledge accumulate as tasks complete. Task 10 understands the codebase as well as task 1 built it.\n\n## Auto-push and PR creation\n\nWhen all tasks are complete, snap automatically pushes commits to your configured git remote (`origin`):\n\n- **No remote configured**: Pushes are skipped, workflow completes cleanly\n- **Non-GitHub remote**: Commits are pushed; PR and CI features are skipped\n- **GitHub remote**: Commits are pushed, then snap creates a PR with an LLM-generated title and description, then monitors CI status until completion\n\nIf push fails (e.g., rejected by remote), the error is displayed and the workflow stops.\n\n### GitHub PR Creation\n\nOn GitHub remotes, after pushing:\n\n1. snap skips PR creation if you're on the default branch (e.g., `main`)\n2. snap skips PR creation if a PR already exists for this branch\n3. snap uses Claude to generate a concise PR title (\u003c 72 chars) and body that explains _why_ the changes were made, using your PRD as context\n4. snap creates the PR via `gh` CLI and displays the URL\n\nRequires `gh` CLI in PATH — pre-validated during startup if you're on a GitHub remote.\n\n### CI Status Monitoring \u0026 Auto-Fix\n\nAfter pushing and creating a PR (or pushing to the default branch), snap monitors GitHub Actions workflows:\n\n- If no CI workflows are configured (no `.github/workflows/*.yml`), snap completes cleanly\n- If CI workflows exist, snap polls their status with live terminal updates showing check progress\n- Individual check status is displayed when ≤5 checks (e.g., `lint: passed, test: running`)\n- When \u003e5 checks exist, status is summarized (e.g., `3 passed, 1 running, 2 pending`)\n- When all checks pass, snap prints `CI passed — PR ready for review` and completes\n- **If any check fails, snap automatically attempts to fix it**:\n  - Fetches the CI failure logs (in-memory only, never written to disk)\n  - Calls Claude to diagnose the issue and apply a minimal fix\n  - Creates a new commit with message `fix: resolve \u003ccheck-name\u003e CI failure`\n  - Pushes the fix and re-polls CI\n  - Repeats up to 10 times; if CI still fails after 10 attempts, stops with an error\n\nStatus updates only print when check status changes — polls with no changes are silent.\n\n## Steering while it runs\n\nWhile snap works, type a directive and press Enter. It queues up and runs between steps.\n\n```\n▶ Step 3/10: Validate implementation\n\u003e use table-driven tests instead of individual test functions\n┌──────────────────────────────────────────────────────┐\n│  Queued: \"use table-driven tests instead of...\"      │\n│  Will run after Step 3/10: Validate implementation   │\n└──────────────────────────────────────────────────────┘\n```\n\nYou stay in control without breaking the flow.\n\n## Commands\n\n| Command                 | Description                                       |\n| ----------------------- | ------------------------------------------------- |\n| `snap run [session]`    | Run the implementation workflow                   |\n| `snap plan [session]`   | Interactively plan and generate task files        |\n| `snap new \u003cname\u003e`       | Create a named session                            |\n| `snap list`             | List all sessions with progress                   |\n| `snap status [session]` | Show task completion and current step             |\n| `snap delete \u003cname\u003e`    | Delete a session (`--force` to skip confirmation) |\n\nSession argument is optional: `snap plan` auto-creates a default session if none exist, and auto-detects when exactly one session exists.\n\n### Flags\n\n| Flag                | Description                                              |\n| ------------------- | -------------------------------------------------------- |\n| `--fresh`           | Discard saved state, start over                          |\n| `--show-state`      | Print current progress and exit (`--json` for raw state) |\n| `--task-file`       | Run one task file directly, with no PRD/session required |\n| `--tasks-dir`, `-d` | Custom tasks directory (default: `docs/tasks`)           |\n| `--prd`, `-p`       | Custom PRD file path                                     |\n| `--from`            | Feed requirements from file (plan command only)          |\n| `--version`         | Print version                                            |\n\n## Configuration\n\n| Variable        | Description                                   | Default  |\n| --------------- | --------------------------------------------- | -------- |\n| `SNAP_PROVIDER` | AI provider: `claude`, `claude-code`, `codex` | `claude` |\n| `NO_COLOR`      | Disable colored output (any non-empty value)  | unset    |\n\n## Resume from anywhere\n\nsnap checkpoints after every step. Ctrl+C, crash, reboot — doesn't matter.\n\n```bash\nsnap run my-feature\n# ... interrupted at step 5 of TASK2 ...\n\nsnap run my-feature\n# snap: my-feature | claude | 3 tasks (1 done) | resuming TASK2 from step 5\n```\n\nPicks up exactly where it stopped. State lives in `.snap/state.json` for legacy runs, `.snap/sessions/\u003cname\u003e/state.json` for sessions, or `.snap/adhoc/\u003chash\u003e/state.json` for `--task-file` runs.\n\n## Troubleshooting\n\n| Problem                     | Fix                                                                                              |\n| --------------------------- | ------------------------------------------------------------------------------------------------ |\n| `claude: command not found` | Install [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) or use `SNAP_PROVIDER=codex` |\n| `codex: command not found`  | Install Codex CLI and add to PATH                                                                |\n| Corrupt state file          | `snap run --fresh`                                                                               |\n| Wrong task running          | `snap run --show-state` to check, `snap run --fresh` to reset                                    |\n\n## Development\n\n```bash\ngo test ./...          # Tests\ngolangci-lint run      # Lint\ngo build .             # Build\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyarlson%2Fsnap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyarlson%2Fsnap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyarlson%2Fsnap/lists"}