waypoint-codex 0.6.0 → 0.7.0

package/README.md

@@ -2,58 +2,128 @@
 
 Waypoint is a docs-first repository operating system for Codex.
 
-It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:
+It helps the next agent understand your repo by making the important context live in the repo itself instead of disappearing into chat history.
 
-- `AGENTS.md` for startup instructions
-- `.waypoint/WORKSPACE.md` for live state, with timestamped multi-topic entries
-- `.waypoint/docs/` for durable project memory, with `summary`, `last_updated`, and `read_when` frontmatter on routable docs
+## Why people use it
+
+Most agent workflows break down the same way:
+
+- the next session starts half-blind
+- important project docs exist, but the agent does not know which ones matter
+- workspace notes turn into noisy append-only logs
+- repo conventions live in people's heads instead of files
+- review and cleanup happen inconsistently
+
+Waypoint gives you a lightweight repo contract that fixes those problems with explicit files, generated context, and a strong default skill set.
+
+## What Waypoint sets up
+
+Waypoint scaffolds a Codex-friendly repo structure built around a few core pieces:
+
+- `AGENTS.md` for the startup contract
+- `.waypoint/WORKSPACE.md` for live operational state
+- `.waypoint/docs/` for durable project memory
 - `.waypoint/DOCS_INDEX.md` for docs routing
-- repo-local skills for planning, audits, verification, workspace compression, and review closure
+- `.waypoint/context/` for generated startup context
+- `.agents/skills/` for repo-local workflows like planning, audits, and QA
+
+The philosophy is simple:
+
+- less hidden runtime magic
+- more repo-local state
+- more markdown
+- better continuity for the next agent
+
+## Best fit
+
+Waypoint is most useful when you want:
+
+- multi-session continuity in a real repo
+- a durable docs and workspace structure for agents
+- stronger planning, review, QA, and closeout defaults
+- repo-local scaffolding instead of a bunch of global mystery behavior
+
+If you only use Codex for tiny one-off edits, Waypoint is probably unnecessary.
 
 ## Install
 
+Waypoint requires Node 20+.
+
 ```bash
 npm install -g waypoint-codex
 ```
 
-Or use it without installing globally:
+Or run it without a global install:
 
 ```bash
 npx waypoint-codex@latest --help
 ```
 
-## Start using it
+## Quick start
 
-Inside your Codex project:
+Inside the repo you want to prepare for Codex:
 
 ```bash
-waypoint init --with-automations --with-roles
+waypoint init --with-roles --with-automations
 waypoint doctor
 ```
 
-That scaffolds:
+That gives you a repo that looks roughly like this:
 
 ```text
 repo/
 ├── AGENTS.md
-├── .agents/skills/
+├── .agents/
+│   └── skills/
 └── .waypoint/
     ├── WORKSPACE.md
     ├── DOCS_INDEX.md
     ├── docs/
     ├── context/
+    ├── scripts/
     └── ...
 ```
 
+From there, start your Codex session in the repo and follow the generated bootstrap in `AGENTS.md`.
+
+## Common init modes
+
+### Minimal setup
+
+```bash
+waypoint init
+```
+
+### Full local workflow setup
+
+```bash
+waypoint init --with-roles --with-rules --with-automations
+```
+
+### App-friendly profile
+
+```bash
+waypoint init --app-friendly --with-roles --with-automations
+```
+
+Flags you can combine:
+
+- `--app-friendly`
+- `--with-roles`
+- `--with-rules`
+- `--with-automations`
+
 ## Main commands
 
 - `waypoint init` — scaffold or refresh the repo
-- `waypoint doctor` — check for drift and missing pieces
-- `waypoint sync` — rebuild `.waypoint/DOCS_INDEX.md` and sync optional automations/rules
-- `waypoint upgrade` — update the global Waypoint CLI and refresh the current repo with its existing config
-- `waypoint import-legacy` — import from an older repo layout
+- `waypoint doctor` — validate health and report drift
+- `waypoint sync` — rebuild the docs index and sync optional user-home artifacts
+- `waypoint upgrade` — update the CLI and refresh the current repo using its saved config
+- `waypoint import-legacy` — analyze an older repo layout and produce an adoption report
 
-## Shipped skills
+## Built-in skills
+
+Waypoint ships a strong default skill pack for real coding work:
 
 - `planning`
 - `error-audit`
@@ -65,7 +135,8 @@ repo/
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`
-- `e2e-verify`
+
+These are repo-local, so the workflow travels with the project.
 
 ## Optional reviewer roles
 
@@ -75,23 +146,54 @@ If you initialize with `--with-roles`, Waypoint scaffolds:
 - `code-reviewer`
 - `plan-reviewer`
 
-The intended workflow is post-commit: after your own commit lands, run `code-reviewer` and `code-health-reviewer` in parallel in the background, then fix real findings before you call the work finished.
+The intended workflow is chunk-based: once there is a meaningful reviewable slice, run the reviewers in parallel, fix real findings, then close out. A recent self-authored commit is the preferred scope anchor when one cleanly represents the slice, but it is not the only valid trigger.
+
+## What makes it different
+
+Waypoint is not trying to hide everything behind hooks and background machinery.
+
+It is opinionated, but explicit:
 
-## Update
+- state lives in files you can inspect
+- docs routing is generated, not guessed from memory
+- repo conventions are encoded in markdown
+- startup context is rebuilt on purpose
+- the repo remains the source of truth
+
+## Upgrading
+
+Recommended path:
 
 ```bash
 waypoint upgrade
 ```
 
-If you only want to update the CLI without refreshing the repo:
+That updates the global CLI and refreshes the current repo using its existing Waypoint config.
+
+If you only want to update the CLI:
 
 ```bash
 waypoint upgrade --skip-repo-refresh
 ```
 
+## Importing an existing repo
+
+If you already have an older assistant setup or repo-memory system:
+
+```bash
+waypoint import-legacy /path/to/source-repo /path/to/new-repo --init-target
+```
+
+This generates an adoption report and helps separate durable docs from old runtime-specific scaffolding.
+
 ## Learn more
 
 - [Overview](docs/overview.md)
 - [Architecture](docs/architecture.md)
 - [Upgrading](docs/upgrading.md)
 - [Importing Existing Repositories](docs/importing-existing-repos.md)
+- [Releasing](docs/releasing.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/src/core.js

@@ -459,7 +459,6 @@ export function doctorRepository(projectRoot) {
         "workspace-compress",
         "pre-pr-hygiene",
         "pr-review",
-        "e2e-verify",
     ]) {
         const skillPath = path.join(projectRoot, ".agents/skills", skillName, "SKILL.md");
         if (!existsSync(skillPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.agents/skills/break-it-qa/SKILL.md

@@ -7,12 +7,21 @@ description: Verify a user-facing feature by trying to break it on purpose inste
 
 Use this skill to attack the feature like an impatient, confused, or careless user.
 
-This is not the same as `e2e-verify`.
+This skill is for adversarial manual QA. It tries to make the feature fail through invalid, interrupted, stale, repeated, or out-of-order interactions instead of only proving the happy path works.
 
-- `e2e-verify` proves the intended flow works end to end.
-- `break-it-qa` tries to make the feature fail through invalid, interrupted, stale, repeated, or out-of-order interactions.
+## Step 1: Ask The Three Setup Questions
 
-## Read First
+Before testing, ask the user these questions if the answer is not already clear from context:
+
+- what exact feature or scope should this cover?
+- how many attack items should the break log reach before stopping?
+- should the skill stop at findings or also fix clear issues after they are found?
+
+Keep this intake short. These are the main user-controlled knobs for the skill.
+
+If the user does not specify a count, use a reasonable default such as `40`.
+
+## Step 2: Read First
 
 Before verification:
 
@@ -23,20 +32,94 @@ Before verification:
 5. Read every file listed in that manifest
 6. Read the routed docs or nearby code that define the feature being tested
 
-## Step 1: Identify Break Surfaces
+## Step 3: Identify Break Surfaces
 
 - Identify the happy path first so you know what "broken" means.
 - Find the fragile surfaces: forms, wizards, pending states, destructive actions, async transitions, navigation changes, and persisted state.
+- For each major step or transition, ask explicit "What if...?" questions before testing. Examples:
+  - What if the user refreshes here?
+  - What if they go back now?
+  - What if they click twice?
+  - What if this input is empty, malformed, too long, or contradictory?
+  - What if this action succeeds in the UI but fails in persistence?
 
 Do not test blindly.
 
-## Step 2: Use The Real UI
+## Step 4: Create A Break Log
+
+Write or update a durable markdown log under `.waypoint/docs/`.
+
+- Prefer a focused path such as `.waypoint/docs/verification/<feature>-break-it-qa.md`.
+- If a routed verification doc already exists for this feature, update it instead of creating a competing file.
+- The log is part of the skill, not an optional extra.
+- Pre-generate the attack plan in this log before executing it. Do not improvise everything live.
+
+Use one item per attempted action. A good entry shape is:
+
+```markdown
+- [ ] What if the user refreshes on the confirmation step before the request finishes?
+  Step: confirmation
+  Category: navigation
+  Status: pending
+  Observed: not tried yet
+```
+
+Then update each item as you go:
+
+- `survived`
+- `broke`
+- `fixed`
+- `retested-survived`
+- `blocked`
+- `not-applicable`
+
+Every executed item must include:
+
+- `Step`
+- `Category`
+- `Status`
+- `Observed`
+
+If the user sets a target such as "make this file 150 items long before you stop," treat that as a hard stopping condition unless you hit a real blocker and explain why.
+
+Use consistent categories such as:
+
+- `navigation`
+- `input-validation`
+- `repeat-action`
+- `stale-state`
+- `error-recovery`
+- `destructive-action`
+- `permissions`
+- `async-state`
+- `persistence`
+
+## Step 5: Enforce Coverage Before Execution
+
+Before you start executing attacks:
+
+- pre-generate a meaningful attack list
+- spread it across the major flow steps
+- spread it across relevant categories
+- make sure the count is not satisfied by one repetitive corner of the feature
+
+Do not treat total item count alone as sufficient coverage.
+
+If the user asks for a large target such as `150`, ensure the log covers multiple steps and multiple categories instead of padding one surface.
+
+Anti-cheating rules:
+
+- no filler items
+- each attack must be meaningfully distinct
+- reworded duplicates do not count toward the target
+
+## Step 6: Use The Real UI
 
 - Use `playwright-interactive`.
 - Exercise the actual UI instead of mocking the flow in code.
 - Keep the scope focused on the feature the user asked you to verify.
 
-## Step 3: Try To Break It On Purpose
+## Step 7: Try To Break It On Purpose
 
 Do more than a happy-path walkthrough.
 
@@ -58,30 +141,41 @@ Actively try:
 
 If the feature is stateful, also check whether the UI, network result, and persisted state stay coherent after those interactions.
 
-## Step 4: Record And Fix Real Bugs
+As you test, keep expanding the break log with new "What if...?" cases that emerge from the flow. Do not rely on memory or chat-only notes.
+
+## Step 8: Record And Fix Real Bugs
 
 - Document each meaningful issue you find.
-- Fix the issue when the remediation is clear.
+- Fix the issue when the remediation is clear and the chosen mode includes fixes.
 - If the behavior is ambiguous, call out the product decision instead of bluffing a fix.
 - Update docs when the verification exposes stale assumptions about how the feature works.
+- Update the break log entry for each attempted action with what happened and whether the feature survived.
+- Require a short observed-result note for every executed item. "Worked" is too weak; capture what actually happened.
 
 Do not stop at the first bug.
 
-## Step 5: Repeat Until The Feature Resists Abuse
+## Step 9: Repeat Until The Feature Resists Abuse
 
 After fixes:
 
 - rerun the relevant happy path
 - rerun the break attempts that previously failed
+- rerun directly related attacks
+- rerun neighboring attacks that touch the same step, state transition, or failure surface
 - verify the fix did not create a new inconsistent state
+- keep adding and executing new "What if...?" items until the requested target coverage is reached
 
 The skill is not done when the feature only works once. It is done when the feature behaves predictably under sloppy real-world use.
 
-## Step 6: Report Truthfully
+## Step 10: Report Truthfully
 
 Summarize:
 
+- the path to the break log markdown file
+- how many attack items were recorded and exercised
+- how coverage was distributed across steps and categories
 - what break attempts you tried
 - which issues you found
 - what you fixed
+- a short systemic-risks summary describing recurring weakness patterns, not just individual bugs
 - what still looks risky or was not exercised

package/templates/.agents/skills/code-guide-audit/SKILL.md

@@ -11,7 +11,9 @@ This skill owns one job: inspect the specific code the user points at, map it ag
 
 ## Step 1: Load The Right Scope
 
-- Read `.waypoint/docs/code-guide.md`.
+- Read the repo's routed code guide.
+- In standard Waypoint repos, use `.waypoint/docs/code-guide.md`.
+- If the repo routes the code guide somewhere else, follow the repo's own docs and routing instead of assuming another fixed path.
 - Read only the files, routes, tests, contracts, and nearby docs needed to understand the specific feature or slice under review.
 - If the scope is ambiguous, resolve it to a concrete file set, feature path, or commit-sized change surface before auditing.
 

package/templates/.agents/skills/pre-pr-hygiene/SKILL.md

@@ -16,7 +16,9 @@ Before the hygiene pass:
 3. Read `.waypoint/WORKSPACE.md`
 4. Read `.waypoint/context/MANIFEST.md`
 5. Read every file listed in that manifest
-6. Read `.waypoint/docs/code-guide.md` and the routed docs relevant to the area being shipped
+6. Read the repo's routed code guide and the routed docs relevant to the area being shipped
+
+In standard Waypoint repos, the code guide lives at `.waypoint/docs/code-guide.md`. If the repo routes it somewhere else, follow the repo's own docs and routing instead of assuming another fixed path.
 
 ## Step 1: Audit The Whole Change Surface
 

package/templates/.waypoint/agent-operating-manual.md

@@ -73,7 +73,6 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 - `workspace-compress` after meaningful chunks, before stopping, and before review when the live handoff needs compression
 - `pre-pr-hygiene` before pushing or opening/updating a PR for substantial work
 - `pr-review` once a PR has active review comments or automated review in progress
-- `e2e-verify` for major user-facing or cross-system changes that need manual end-to-end verification
 
 ## When to use the optional reviewer agents
 
@@ -83,14 +82,15 @@ If the repo was initialized with Waypoint roles enabled, use them as focused sec
 - `code-health-reviewer` for maintainability drift
 - `plan-reviewer` to challenge weak implementation plans before execution
 
-## Post-Commit Review Loop
+## Review Loop
 
-If Waypoint's optional roles are enabled and you authored a commit, immediately after that commit:
+If Waypoint's optional roles are enabled, run the reviewer pair after a meaningful reviewable implementation chunk, not just as a reflex after every tiny commit.
 
-1. Launch `code-reviewer` and `code-health-reviewer` in parallel as background, read-only reviewers.
-2. Scope them to the commit you just made, then widen only when surrounding files are needed to validate a finding.
-3. Do not call the work finished before you read both reviewer results.
-4. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
+1. Launch `code-reviewer` and `code-health-reviewer` in parallel as background, read-only reviewers once there is a coherent slice of work worth reviewing.
+2. If you have a recent self-authored commit that cleanly represents that slice, use it as the default review scope anchor. Otherwise scope the reviewers to the current changed slice.
+3. Widen only when surrounding files are needed to validate a finding.
+4. Do not call the work finished before you read both reviewer results.
+5. Fix real findings, rerun the relevant verification, update workspace/docs if needed, and make a follow-up commit when fixes change the repo.
 
 ## Quality bar
 

package/templates/.waypoint/agents/code-health-reviewer.md

@@ -59,7 +59,13 @@ Do not create findings for:
 
 ## Scope
 
-In Waypoint's default post-commit review loop, start with the latest self-authored commit, then widen only when related files are needed to validate a maintainability issue. Focus on:
+In Waypoint's default review loop, start with the reviewable slice the main agent hands you.
+
+- If there is a recent self-authored commit that cleanly represents the slice, use that commit as the default scope anchor.
+- Otherwise, start from the current changed files or diff under review.
+- Widen only when related files are needed to validate a maintainability issue.
+
+Focus on:
 
 - recently changed files
 - their importers

package/templates/.waypoint/agents/code-reviewer.md

@@ -41,7 +41,11 @@ Not:
 
 ### 1. Get the Changes
 
-In Waypoint's default post-commit review loop, start with the latest self-authored commit. Review the actual diff or recent changed files first, then widen only as needed.
+In Waypoint's default review loop, start with the reviewable slice the main agent hands you.
+
+- If there is a recent self-authored commit that cleanly represents the slice, use that commit as the default scope anchor.
+- Otherwise, start from the current changed files or diff the main agent is asking you to review.
+- Widen only as needed.
 
 ### 2. Deep Research
 

package/templates/managed-agents-block.md

@@ -37,9 +37,8 @@ Working rules:
 - Use `docs-sync` when the docs may be stale or a change altered shipped behavior, contracts, routes, or commands
 - Use `code-guide-audit` for a targeted coding-guide compliance pass on a specific feature, file set, or change slice
 - Use `break-it-qa` for browser-facing features that should be tested against invalid inputs, refreshes, repeated clicks, wrong navigation, and other adversarial user behavior
-- If optional reviewer roles are present and you make a commit, run `code-reviewer` and `code-health-reviewer` in parallel before calling the work done
+- If optional reviewer roles are present and there is a meaningful reviewable implementation chunk, run `code-reviewer` and `code-health-reviewer` in parallel before calling the work done; use a recent self-authored commit as the default scope anchor when one cleanly represents that slice
 - Before pushing or opening/updating a PR for substantial work, use `pre-pr-hygiene`
 - Use `pr-review` once a PR has active review comments or automated review in progress
-- Use `e2e-verify` for major user-facing or cross-system changes that need manual end-to-end verification
 - Treat the generated context bundle as required session bootstrap, not optional reference material
 <!-- waypoint:end -->

package/templates/.agents/skills/e2e-verify/SKILL.md

@@ -1,63 +0,0 @@
----
-name: e2e-verify
-description: Perform manual end-to-end verification for a shipped feature or major change. Use when frontend and backend behavior must be verified together, when a feature needs a realistic walkthrough, or when the agent should manually exercise the flow, inspect logs and persisted state, document issues, fix them, and repeat until no meaningful end-to-end issues remain.
----
-
-# E2E Verify
-
-Use this skill when "it should work" is not enough and the flow needs to be proven end to end.
-
-## Read First
-
-Before verification:
-
-1. Read `.waypoint/SOUL.md`
-2. Read `.waypoint/agent-operating-manual.md`
-3. Read `.waypoint/WORKSPACE.md`
-4. Read `.waypoint/context/MANIFEST.md`
-5. Read every file listed in that manifest
-6. Read the routed docs that define the feature, flow, or contract being verified
-
-## Step 1: Exercise The Real Flow
-
-- For browser-facing paths, manually exercise the feature through the real UI.
-- For backend-only or service flows, drive the real API or runtime path directly.
-- Follow the feature from entry point to persistence to user-visible outcome.
-
-## Step 2: Inspect End-To-End State
-
-Check the surfaces that prove the system actually behaved correctly:
-
-- UI state
-- server responses
-- logs
-- background-job state if relevant
-- database or persisted records when relevant
-
-Do not stop at "the page looked okay."
-
-## Step 3: Record And Fix Issues
-
-- Document each meaningful issue you find.
-- Fix the issue when the remediation is clear.
-- Update docs or contracts if verification exposes stale assumptions.
-
-## Step 4: Repeat Until Clean
-
-Re-run the end-to-end flow after fixes.
-
-The skill is complete only when:
-
-- the intended flow works
-- the persisted state is correct
-- the logs tell a truthful story
-- no meaningful issues remain
-
-## Step 5: Report Verification Truthfully
-
-Summarize:
-
-- the flows exercised
-- the state surfaces inspected
-- the issues found and fixed
-- any residual risks or unverified edges

package/templates/.agents/skills/e2e-verify/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "E2E Verify"
-  short_description: "Manually verify a feature end to end"
-  default_prompt: "Use this skill for manual end-to-end verification of a feature or major change. Exercise the real flow, inspect UI plus logs and persisted state, document issues, fix them, and repeat until no meaningful end-to-end issues remain."