{"id":48320100,"url":"https://github.com/markmdev/waypoint","last_synced_at":"2026-04-05T00:38:24.791Z","repository":{"id":342479680,"uuid":"1174112349","full_name":"markmdev/waypoint","owner":"markmdev","description":"Docs-first repository operating system for Codex","archived":false,"fork":false,"pushed_at":"2026-03-31T16:49:43.000Z","size":404,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T18:41:08.171Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/markmdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-03-06T04:41:00.000Z","updated_at":"2026-03-31T16:49:46.000Z","dependencies_parsed_at":"2026-03-23T20:02:07.021Z","dependency_job_id":null,"html_url":"https://github.com/markmdev/waypoint","commit_stats":null,"previous_names":["markmdev/waypoint"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/markmdev/waypoint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fwaypoint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fwaypoint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fwaypoint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fwaypoint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmdev","download_url":"https://codeload.github.com/markmdev/waypoint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fwaypoint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31420425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":[],"created_at":"2026-04-05T00:38:24.290Z","updated_at":"2026-04-05T00:38:24.766Z","avatar_url":"https://github.com/markmdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Waypoint\n\nWaypoint makes Codex better by default for real software work.\n\nCodex is already powerful. The problem is that most users still have to teach it\nthe same things over and over:\n\n- ask better questions before coding\n- plan thoroughly instead of making hidden assumptions\n- follow stronger coding standards\n- review the result seriously before merge\n- verify the work instead of guessing\n- learn from corrections instead of repeating the same mistakes\n\nWaypoint installs those defaults into a repo so you can spend less time\nprompting and more time building.\n\n## Install and upgrade\n\nWaypoint requires Node 20+.\n\nInstall globally:\n\n```bash\nnpm install -g waypoint-codex\n```\n\nOr try it without a global install:\n\n```bash\nnpx waypoint-codex@latest --help\n```\n\nInside the repo you want to prepare for Codex:\n\n```bash\nwaypoint init\nwaypoint doctor\n```\n\nKeep an existing repo up to date:\n\n```bash\nwaypoint upgrade\nwaypoint doctor\n```\n\n## What gets better\n\nWith Waypoint, Codex should become better at:\n\n- understanding the product and technical context before it starts\n- planning work in enough detail to avoid avoidable mistakes\n- writing code that matches the codebase and holds up in production\n- staying on track during larger or longer-running tasks\n- reviewing and verifying its own work before calling it done\n- improving its own guidance when the user corrects it\n\n## Why Waypoint exists\n\nWaypoint is for people using Codex on real apps and real codebases, not just\ntiny one-off edits.\n\nIt exists because most Codex users should not have to manually remember every\nbest practice, every guardrail, every planning question, and every review step\nfor every task.\n\nWaypoint packages that expertise into the repo so Codex starts from a much\nbetter default.\n\n## What Waypoint adds\n\n### 1. Better default behavior\n\nWaypoint gives Codex stronger repo guidance through the generated contract,\nworkspace files, and repo-local instructions.\n\nThat means the agent is pushed to:\n\n- investigate before narrating status\n- ask better questions about the product, architecture, and constraints\n- explain what it found in a clear way\n- verify what it changed\n- leave the repo clearer than it found it\n\n### 2. Better planning\n\nWaypoint ships a thorough planning workflow for work that should not start from\nguesswork.\n\nThat workflow pushes the agent to:\n\n- interview the user until the real requirements are clear\n- produce a detailed plan before implementation\n- challenge that plan with a reviewer agent\n- tighten the plan before coding starts\n\nThe goal is simple: fewer assumptions, fewer surprises, and a much better shot\nat one-shot execution.\n\n### 3. Better code quality\n\nWaypoint does not assume Codex will naturally write production-quality code by\ndefault.\n\nIt adds guardrails that push the agent toward:\n\n- stronger coding standards\n- better fit with the existing codebase\n- fewer lazy shortcuts\n- fewer architecture mistakes\n- fewer duplicated or premature abstractions\n\nReviewer agents and audit workflows add another pass before merge when the work\nneeds it.\n\n### 4. Better end-to-end execution\n\nWaypoint also helps Codex follow through on bigger tasks.\n\nIt includes workflows for:\n\n- ship-readiness audits\n- deliberate review passes before PR or merge\n\nThis helps the agent keep moving until the work is actually ready, not just\n\"probably done.\"\n\n### 5. Self-improvement\n\nWaypoint treats user corrections as product input, not just conversation noise.\n\nWhen the user corrects behavior, rules, or workflow, the agent is pushed to\nupdate the right durable layer so the same issue is less likely to happen\nagain.\n\nThat includes:\n\n- user-scoped guidance for true cross-project standing rules\n- project-scoped guidance for durable repo-wide context and always-on rules\n- repo-local skills for workflow-specific or method-specific guidance\n\n### 6. Better continuity\n\nWaypoint gives Codex explicit continuity artifacts so the next session does not\nstart half-blind.\n\nThat includes:\n\n- a generated docs index that tells the agent which docs exist and when to read\n  them\n- a live workspace file that records what is going on right now\n- a generated recent thread file that carries the most important prior\n  conversation context forward\n\n## What Waypoint sets up\n\nWaypoint scaffolds a Codex-friendly repo around a few core pieces:\n\n- `AGENTS.md` for the project-scoped startup contract and durable repo guidance\n- `.waypoint/WORKSPACE.md` for live operational state\n- `.waypoint/ACTIVE_PLANS.md` for the current active plan, checklist, blockers, and verification state\n- `.waypoint/docs/` for long-lived project docs\n- `.waypoint/plans/` for durable plan documents\n- `.waypoint/DOCS_INDEX.md` for docs routing, so the agent knows what to read and when\n- `.waypoint/context/` for generated volatile context\n- `.waypoint/context/SNAPSHOT.md` for repo state and PR context\n- `.waypoint/context/RECENT_THREAD.md` for compact continuity from the previous\n  conversation\n- `.agents/skills/` for optional structured workflows\n- `.codex/` for optional reviewer and helper agents\n\nBy default, Waypoint routes docs from `.waypoint/docs/`.\nIf your repo keeps routable docs elsewhere, you can add more explicit roots in\n`.waypoint/config.toml` with `docs_dirs`.\nWaypoint scans each configured root recursively and only includes Markdown files\nwith valid Waypoint frontmatter.\n\nThe continuity story matters:\n\n- `.waypoint/DOCS_INDEX.md` helps the agent find the right docs before work\n- `.waypoint/WORKSPACE.md` helps the next session understand what is in flight\n- `.waypoint/ACTIVE_PLANS.md` keeps the currently approved plan visible during execution\n- `.waypoint/context/RECENT_THREAD.md` helps the agent retain the important\n  parts of the previous conversation\n\nWaypoint defaults to Codex transcript discovery.\nIf you use Pi instead, set this in `.waypoint/config.toml`:\n\n```toml\ncoding_agent = \"pi\"\n```\n\nSupported values are `\"codex\"` and `\"pi\"`.\n\n## Best fit\n\nWaypoint is most useful when you want:\n\n- a better default Codex workflow in a real repo\n- stronger planning before implementation starts\n- stronger coding standards and review guardrails\n- better follow-through on long tasks\n- a personal workflow that can live in almost any repo without becoming a team\n  rollout\n\nWaypoint is primarily an individual tool.\nMost of its repo-local state is meant to stay personal and local by default.\n\nIf you only use Codex for tiny one-off edits, Waypoint is probably unnecessary.\n\n## Quick start\n\nInside the repo you want to prepare for Codex:\n\n```bash\nwaypoint init\nwaypoint doctor\n```\n\nThat gives you a repo that looks roughly like this:\n\n```text\nrepo/\n├── AGENTS.md\n├── .codex/\n│   ├── agents/\n│   └── config.toml\n├── .agents/\n│   └── skills/\n└── .waypoint/\n    ├── DOCS_INDEX.md\n    ├── WORKSPACE.md\n    ├── ACTIVE_PLANS.md\n    ├── docs/\n    ├── plans/\n    ├── context/\n    ├── scripts/\n    └── ...\n```\n\nFrom there, start your Codex session in the repo and follow the generated bootstrap in `AGENTS.md`.\n\nIf you want to add more routable roots, extend `.waypoint/config.toml` like this:\n\n```toml\ndocs_dirs = [\n  \".waypoint/docs\",\n  \"services/app/docs\",\n]\n```\n\n## Built-in skills\n\nWaypoint ships a strong default skill pack for real coding work:\n\n- `planning`\n- `foundational-redesign`\n- `verify-completeness`\n- `code-guide-audit`\n- `adversarial-review`\n- `frontend-ship-audit`\n- `backend-ship-audit`\n- `pr-review`\n- `frontend-context-interview`\n- `backend-context-interview`\n- `agi-help`\n\nThese are repo-local, so the workflow travels with the project.\n\nThe important design choice is that they stay out of the always-on voice.\nEach skill exists to improve the result when the task needs more rigor, without\nturning every normal interaction into a heavy process.\n\n## How to get full value\n\nInstalling Waypoint improves Codex's defaults right away, but the full workflow\nis not completely automatic.\n\nSome of Waypoint's biggest advantages come from user-invoked skills that should\nbe used deliberately when the moment calls for them.\n\nThe most important ones are:\n\n- `foundational-redesign` when the right move is a cleaner replacement that deletes legacy seams instead of patching around them\n- `verify-completeness` when you think implementation is done and need a strict final pass against approved scope, planned file changes, and completion gates\n- `code-guide-audit` when you want a code quality pass against your repo's\n  standards and working rules\n- `backend-ship-audit` when backend work needs a deeper production-readiness\n  pass\n- `frontend-ship-audit` when frontend work needs a deeper product, UX, and ship\n  readiness pass\n- `frontend-context-interview` / `backend-context-interview` when durable\n  project context is missing and would materially change implementation choices\n- `pr-review` when an open PR already has active review comments or automated\n  review in flight\n- `agi-help` when you want a high-quality external handoff package for\n  GPT-5.4-Pro\n\nThe practical rule is:\n\n- install Waypoint for better defaults\n- invoke the higher-rigor skills when you want a stronger planning, audit,\n  review, or closeout pass\n\n## Reviewer agents\n\nWaypoint scaffolds these reviewer agents by default:\n\n- `code-health-reviewer`\n- `code-reviewer`\n- `plan-reviewer`\n\nThey are available for deliberate second passes.\n\n## What makes Waypoint different\n\nWaypoint is opinionated, but explicit:\n\n- state lives in files you can inspect\n- docs routing is generated, not guessed from memory\n- the default contract tells the agent to ask better questions and investigate\n  first\n- durable guidance is separated into user-scoped AGENTS, project-scoped AGENTS, live workspace state, project docs, and plan docs\n- visual explanation stays lightweight: Mermaid in chat and screenshots from real UI inspection\n- heavier workflows stay in optional skills\n- user corrections are supposed to improve the system instead of disappearing\n  into chat history\n\n## Main commands\n\n- `waypoint init` — scaffold or refresh the repo and, by default, update the global CLI first\n- `waypoint doctor` — validate health and report drift\n- `waypoint sync` — rebuild the docs index\n- `waypoint upgrade` — update the CLI and refresh the current repo using its saved config\n\n## Learn more\n\n- [Overview](docs/overview.md)\n- [Architecture](docs/architecture.md)\n- [Upgrading](docs/upgrading.md)\n- [Releasing](docs/releasing.md)\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Fwaypoint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmdev%2Fwaypoint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Fwaypoint/lists"}