waypoint-codex 0.5.0 → 0.6.1

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`
@@ -61,11 +131,14 @@ repo/
 - `ux-states-audit`
 - `docs-sync`
 - `code-guide-audit`
+- `break-it-qa`
 - `workspace-compress`
 - `pre-pr-hygiene`
 - `pr-review`
 - `e2e-verify`
 
+These are repo-local, so the workflow travels with the project.
+
 ## Optional reviewer roles
 
 If you initialize with `--with-roles`, Waypoint scaffolds:
@@ -74,23 +147,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 post-commit: make your change, commit it, run the reviewers in parallel, fix real findings, then close out.
+
+## 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

@@ -455,6 +455,7 @@ export function doctorRepository(projectRoot) {
         "ux-states-audit",
         "docs-sync",
         "code-guide-audit",
+        "break-it-qa",
         "workspace-compress",
         "pre-pr-hygiene",
         "pr-review",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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

@@ -0,0 +1,184 @@
+---
+name: break-it-qa
+description: Verify a user-facing feature by trying to break it on purpose instead of only following the happy path. Use after building forms, multistep flows, settings pages, onboarding, stateful UI, destructive actions, or any browser-facing feature where invalid inputs, refreshes, back navigation, repeated clicks, wrong action order, or recovery paths might expose real bugs.
+---
+
+# Break-It QA
+
+Use this skill to attack the feature like an impatient, confused, or careless user.
+
+This is not the same as `e2e-verify`.
+
+- `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
+
+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:
+
+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 or nearby code that define the feature being tested
+
+## 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 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 7: Try To Break It On Purpose
+
+Do more than a happy-path walkthrough.
+
+Actively try:
+
+- invalid inputs
+- empty required fields
+- boundary-length or malformed inputs
+- repeated or double clicks
+- submitting twice
+- wrong action order
+- back and forward navigation
+- page refresh during the flow
+- closing and reopening modals or screens
+- canceling mid-flow and re-entering
+- stale UI state after edits
+- conflicting selections or toggles
+- error recovery after a failed action
+
+If the feature is stateful, also check whether the UI, network result, and persisted state stay coherent after those interactions.
+
+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 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 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 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/break-it-qa/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Break-It QA"
+  short_description: "Try to break a feature through the UI"
+  default_prompt: "Use this skill to verify a user-facing feature by trying to break it through the browser with invalid inputs, wrong action order, refreshes, back navigation, repeated clicks, and other adversarial interactions, then fix clear issues and repeat."

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

@@ -69,6 +69,7 @@ Do not document every trivial implementation detail. Document the non-obvious, d
 - `ux-states-audit` when async/data-driven UI likely lacks loading, empty, or error states
 - `docs-sync` when routed docs may be stale, missing, or inconsistent with the codebase
 - `code-guide-audit` when a specific feature or file set needs a targeted coding-guide compliance check
+- `break-it-qa` when a browser-facing feature should be attacked with invalid inputs, refreshes, repeated clicks, wrong action order, or other adversarial manual QA
 - `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

package/templates/managed-agents-block.md

@@ -36,6 +36,7 @@ Working rules:
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
 - 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
 - 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