{"id":50304512,"url":"https://github.com/rijkvanzanten/rolling-wave-engineering","last_synced_at":"2026-05-28T15:01:19.056Z","repository":{"id":359419835,"uuid":"1237833791","full_name":"rijkvanzanten/rolling-wave-engineering","owner":"rijkvanzanten","description":"Rolling-wave Codex skills for shaping, implementing, reviewing, and completing one concrete slice at a time.","archived":false,"fork":false,"pushed_at":"2026-05-21T20:07:00.000Z","size":124,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-22T04:40:36.918Z","etag":null,"topics":["agentic-engineering","ai-agents","codex","codex-skills","prompt-engineering","rolling-wave-planning","software-engineering"],"latest_commit_sha":null,"homepage":"","language":null,"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/rijkvanzanten.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-05-13T14:52:33.000Z","updated_at":"2026-05-21T20:17:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rijkvanzanten/rolling-wave-engineering","commit_stats":null,"previous_names":["rijkvanzanten/rolling-wave-engineering"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rijkvanzanten/rolling-wave-engineering","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rijkvanzanten%2Frolling-wave-engineering","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rijkvanzanten%2Frolling-wave-engineering/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rijkvanzanten%2Frolling-wave-engineering/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rijkvanzanten%2Frolling-wave-engineering/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rijkvanzanten","download_url":"https://codeload.github.com/rijkvanzanten/rolling-wave-engineering/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rijkvanzanten%2Frolling-wave-engineering/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33613431,"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-05-28T02:00:06.440Z","response_time":99,"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-engineering","ai-agents","codex","codex-skills","prompt-engineering","rolling-wave-planning","software-engineering"],"created_at":"2026-05-28T15:01:18.010Z","updated_at":"2026-05-28T15:01:19.051Z","avatar_url":"https://github.com/rijkvanzanten.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rolling-Wave Engineering\n\nA lot of agentic engineering workflows want to scope the whole project up front, then have the agent execute across that entire plan. That works surprisingly well for getting 70-90% of a lot of things done. It also tends to leave the last 10-30% of every step spread across the whole project: unclear edge cases, fuzzy scope calls, incomplete verification, and review debt that all comes due at once.\n\nThis is at odds with my own personal working style. I personally keep a clear project finish line, sketch the broad implementation sequence, then fully prepare, implement, review, and complete one concrete slice before moving on to the next one. Each completed slice updates the project context, and the next slice gets prepared with those learnings in mind.\n\n## What It Adds\n\n- Project shaping that defines the finish line and broad roadmap without turning the whole project into a giant upfront implementation plan\n- Slice preparation that grills the next implementation step until behavior, scope, risks, and verification intent are clear\n- Execution-fit calls that identify whether a slice or chunk is better suited for agent work, human work, either, or a hybrid handoff\n- Exploratory implementation first, then focused test implementation once the slice has settled\n- Implementation, testing, and review workflows that can use focused subagents when that actually helps\n- Slice completion that records learnings, risks, and reviewer notes before moving on\n- Supporting passes for local code review, simplification, debugging, and PR descriptions\n\n## Skills\n\n### Rolling-Wave Workflow\n\n| Skill | Purpose |\n| --- | --- |\n| `shape-project` | Define or update the global project direction, success criteria, non-goals, constraints, risks, and rough slice sequence. |\n| `prepare-next-slice` | Pick the next slice, grill unresolved slice-level decisions, identify execution fit, and mark exactly one slice ready. |\n| `implement-slice` | Implement a ready slice exploratorily, delegate agent-fit chunks, and pause for human-fit chunks when useful. |\n| `implement-tests` | Add focused tests for the newly implemented slice before review. |\n| `review-slice` | Review an in-progress slice against its original contract, using reviewer subagents when available. |\n| `complete-slice` | Capture learnings, risks, and review notes, then mark the slice done after manual review. |\n\n### Supporting Skills\n\n| Skill | Purpose |\n| --- | --- |\n| `code-review` | Review local or branch changes with language and risk-specific reviewer agents. |\n| `code-simplify` | Tighten changed code for reuse, quality, and efficiency while preserving behavior. |\n| `debug` | Investigate failures from reproduction to root cause and fix. |\n| `grill-me` | Pressure-test an existing plan or design artifact while preserving its current format. |\n| `rolling-wave-common` | Shared references and templates used by the workflow skills. |\n| `pr-description` | Draft a PR body from branch changes, rolling-wave project context, and the completed slice. |\n\n## Reviewer Agents\n\nThe repo includes reviewer-agent prompt sources under `agents/`:\n\n- Correctness, testing, maintainability, security, reliability, API contract, and adversarial reviewers\n- Document reviewers for coherence, feasibility, scope, and flow\n- Language/framework reviewers for TypeScript, Vue, and Rust\n\nWorth noting: Codex currently loads plugin skills from `.codex-plugin/plugin.json`, but custom spawnable agents are registered separately from `~/.codex/agents/**/*.toml` or project `.codex/agents/**/*.toml`.\n\nThe `agents/*.agent.md` files in this repo are source prompts. Convert or register them as Codex agent TOML files if you want `spawn_agent` to see them.\n\n## Project Artifacts\n\nRolling-wave project state lives in the repository being worked on:\n\n```text\ndocs/rolling-wave/{project}/\n  project.md\n  slices/\n    001-example-slice.md\n```\n\n`project.md` is the project-level source of truth. It carries the finish line, success criteria, broad roadmap, cross-slice decisions, open questions, risks, review notes, and change history.\n\nEach slice file describes one concrete implementation step:\n\n- behavior\n- acceptance criteria\n- verification intent\n- likely approach\n- execution fit\n- parallel work chunks\n- scope boundaries\n- risks\n- implementation notes\n- test notes\n- review notes\n- completion learnings\n\nSlice statuses:\n\n- `pending`\n- `ready`\n- `in progress`\n- `in review`\n- `done`\n\n## Workflow\n\n1. Use `shape-project` to establish the finish line and rough slice sequence.\n2. Use `prepare-next-slice` to make one pending slice ready.\n3. Use `implement-slice` to build that slice, keeping implementation exploratory.\n4. Use `implement-tests` to lock down the newly added logic with focused tests.\n5. Use `review-slice` until the implementation matches the slice contract.\n6. Do whatever manual cleanup or review you want.\n7. Use `complete-slice` to capture learnings and mark the slice done.\n8. Repeat from `prepare-next-slice`.\n\nUseful supporting passes:\n\n- Use `code-review` before opening or merging a PR\n- Use `code-simplify` for a focused cleanup pass after implementation\n- Use `pr-description` to draft a PR body from branch diff plus rolling-wave context\n- Use `debug` when a test, runtime error, or reported bug needs root-cause analysis\n\n## How To Use This\n\nThis repo is mainly meant as source material, not as a polished plugin distribution.\n\nI'd urge you to make this your own:\n\n1. Read through the skills and agents\n2. Keep the parts that match how you work\n3. Rewrite the parts that do not\n4. Install your edited versions into your own Codex setup\n\nThe useful bit here is the shape of the workflow, not the exact wording of every prompt :)\n\nFor Codex, the skills live under:\n\n```text\nskills/\n```\n\nand the reviewer-agent source prompts live under:\n\n```text\nagents/\n```\n\nYou can copy individual skill folders into your Codex skills directory, or keep this repo as a local plugin while you experiment.\n\n## Optional Local Plugin Setup\n\nThe repo is also structured as a local Codex plugin. The manifest lives at:\n\n```text\n.codex-plugin/plugin.json\n```\n\nClone it somewhere stable:\n\n```bash\ngit clone https://github.com/rijkvanzanten/rolling-wave-engineering.git\n```\n\nAdd a local marketplace entry that points at the parent folder containing this repository:\n\n```toml\n[marketplaces.local]\nsource_type = \"local\"\nsource = \"/path/to/parent-folder\"\n\n[plugins.\"rolling-wave-engineering@local\"]\nenabled = true\n```\n\nRestart Codex after enabling the plugin or bumping the plugin version.\n\n## Attribution\n\nThis plugin was shaped by a few related agent-workflow projects:\n\n- [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) by Every: several debugging, review, simplification, and reviewer-agent patterns were adapted from its MIT-licensed plugin\n- [grill-me](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) by Matt Pocock: inspired the pressure-testing workflow behind `grill-me`, `shape-project`, and slice preparation\n- [superpowers](https://github.com/obra/superpowers) by Jesse Vincent: inspired the broader idea of composing durable agent skills into opinionated engineering workflows\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frijkvanzanten%2Frolling-wave-engineering","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frijkvanzanten%2Frolling-wave-engineering","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frijkvanzanten%2Frolling-wave-engineering/lists"}