@evertonferreira96/agents 0.1.2 → 0.1.4

package/.claude/skills/grill-with-docs/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Grill with docs
 
-Call the Skill tool with "grilling". That skill is the interview: design tree, rounds, frontier, recommended answers. This skill adds three things around it: what to read before the first round, what to write while the rounds run, and what to return to the orchestrator at the end.
+Call the Skill tool twice, for "grilling" and "domain-modeling". The first is the interview: design tree, rounds, frontier, recommended answers. The second keeps the domain model sharp while the rounds run: it challenges terms against `GLOSSARY.md`, proposes canonical words, stress-tests them with scenarios, writes settled terms the moment they settle and offers an ADR only when a decision passes its three tests. This skill adds what this config needs around them: what to read before the first round, the Grill record, the ADR template and lifecycle, and what to return to the orchestrator at the end.
 
 Runs in the main session, because it needs the user. Subagents never run it.
 
@@ -18,24 +18,15 @@ Runs in the main session, because it needs the user. Subagents never run it.
 
 ## Written during the rounds
 
-### Glossary: `GLOSSARY.md` (repo root)
+### Grill record: `docs/plans/<task>.md`
 
-Capture domain language the moment it is settled, so code, tickets and agents share one vocabulary.
+After each round, append the answers to the plan's `## Grill record` (format in `docs/plans/README.md`): the decision, why in the user's words when they add nuance, the rejected alternatives and any constraint said in passing. `/product` plans from it, so write it while the round is fresh, never reconstructed at the end. No plan file yet (started from `/grill-with-docs` outside a task): keep the entries and return them in the closing block.
 
-- One entry per term: **Term** - definition in one or two sentences. Add `Not:` for synonyms to avoid and `See:` for related terms.
-- Write a term only when the user confirms its meaning. Ask when two words seem to name one thing, or one word names two.
-- Prefer the user's business words over technical ones; flag where the code currently uses a different name.
-- Create the file if missing, with the header `# Glossary - domain language for <project>`.
-- Keep it a glossary: no implementation detail, no decisions (those are ADRs).
+### Glossary and ADRs
 
-### ADRs: `docs/adr/`
-
-Write an ADR only for a decision that is hard to reverse or that a future reader would question: new domain or integration, storage or data ownership, sync vs async flow, retry/timeout/fallback policy, a rejected obvious option.
-
-- Follow the numbering and template in `docs/adr/README.md` (`NNNN-<slug>.md`: Status, Date, Context, Decision, Consequences).
-- Status `Proposed` while grilling. It becomes `Accepted` only with the change that implements it.
+- `GLOSSARY.md` (or the context glossaries a `GLOSSARY-MAP.md` lists): written by `domain-modeling` the moment a term settles, in its `GLOSSARY-FORMAT.md`. A term goes in only when the user confirms its meaning; flag where the code currently uses another name.
+- ADRs: `domain-modeling` decides **whether** a decision earns one (hard to reverse, surprising without context, the result of a real trade-off). `docs/adr/README.md` decides **how** it looks and lives, and wins over the skill's `ADR-FORMAT.md`: `NNNN-<slug>.md` with Status, Date, Context, Decision, Consequences; `Proposed` while grilling; `Accepted` only with the change that implements it; never edited once Accepted (a new one supersedes it).
 - If the decision meets an `/architect` trigger, say so: the orchestrator runs `/architect` on the proposal before it is accepted.
-- Never edit an Accepted ADR; write a new one that supersedes it.
 
 ## Close
 
@@ -50,6 +41,8 @@ Out of scope
 - <item>
 Plan changes
 - <what to add or change in docs/plans/<task>.md>
+Grill record
+- <entries, only when there was no plan file to append them to>
 Docs written
 - GLOSSARY.md: <terms added or changed>
 - docs/adr/NNNN-<slug>.md (Proposed): <title>
@@ -60,5 +53,6 @@ The orchestrator applies "Plan changes" to the plan file. A decision that meets
 ## It's working if
 
 - Facts were looked up, never asked; the user only answered decisions.
-- `GLOSSARY.md` and the Proposed ADRs were written during the rounds, not reconstructed after.
+- `GLOSSARY.md`, the Proposed ADRs and the Grill record were written during the rounds, not reconstructed after.
+- `/product` could plan from the Grill record without this conversation.
 - The closing block applies to `docs/plans/<task>.md` without anyone re-reading the conversation.

package/.claude/skills/orchestrate/SKILL.md

@@ -10,10 +10,10 @@ You are the parent orchestrator. You classify, grill, plan, brief, delegate, int
 ## Hard rule
 
 - You never call Edit, Write or NotebookEdit on code, and you never run lint, build or test yourself.
-- Allowed writes: `docs/plans/**`, `docs/adr/**`, `GLOSSARY.md`, and git integration commands (merge, apply, commit) per rule `git-workflow`.
+- Allowed writes: `docs/plans/**`, `docs/adr/**`, `GLOSSARY.md` (and `GLOSSARY-MAP.md` with its context glossaries), and git integration commands (merge, apply, commit) per rule `git-workflow`.
 - `.claude/agent-memory/**` belongs to the agents, not to you.
 - About to edit code or run a check? Stop and dispatch `/quick` or an implementer.
-- Hook `orchestrator-guard` blocks main-session edits outside `docs/plans/`, `docs/adr/`, `docs/README.md`, `.claude/` and root `*.md`.
+- Hook `orchestrator-guard` blocks main-session edits outside `docs/plans/`, `docs/adr/`, `docs/README.md`, `.claude/`, root `*.md` and context glossaries (`*/GLOSSARY.md`, `*/docs/adr/*.md`).
 
 ## The flow
 
@@ -21,6 +21,7 @@ You are the parent orchestrator. You classify, grill, plan, brief, delegate, int
 S: classify -> worktree -> /quick -> commit
 M: classify -> worktree -> grill (if a decision is open) -> /product -> tickets -> implementer per ticket -> /verifier -> commit
 L: classify -> worktree -> grill -> /product -> /architect -> tickets -> implementers on the frontier -> integrate -> /architect -> /verifier -> /security on trigger -> commit
+Fog: classify -> /wayfinder (the user, one decision per session) -> map done -> L with the map as input
 ```
 
 ## 1. Classify
@@ -31,12 +32,14 @@ L: classify -> worktree -> grill -> /product -> /architect -> tickets -> impleme
 | M | 1-2 scopes, paths known | Grill only if a decision is open. `/product` plan with tickets, one implementer per ticket in the task worktree, then `/verifier`. |
 | L | 3+ scopes, or any architecture trigger | Grill. `/product` -> `/architect` -> tickets -> implementers (parallel on the frontier) -> integrate -> `/architect` again -> `/verifier` -> `/security` on trigger. |
 
-S: the Stop hook (lint + test) is the DoD. `/quick` returns `escalate to M` -> reclassify and continue as M.
+S: the Stop hook (lint + the fast test suite) is the DoD. `/quick` returns `escalate to M` -> reclassify and continue as M.
+
+**Fog** is an L whose way is not visible yet: the destination is clear, but two or more decisions need research, a prototype or manual work before anyone can make them, or the plan would not fit one session. Grilling it into a plan now builds the plan on guesses. Tell the user so in one line and stop: they start `/wayfinder <idea>` (a manual skill, so you cannot call it) from the main checkout, not a task worktree; it charts `docs/plans/<effort>/map.md` and resolves one decision per session. The same exit applies when the grill's breadth-first round shows fog; then also set the task plan to `Status: blocked (fog: docs/plans/<effort>/map.md)`. When the map says `Status: done`, the build comes back here as L: at step 2 the effort folder is copied into the task worktree, the grill covers only what the map left open, and the `/product` brief carries the map path.
 
 Architecture triggers: new domain, integration, storage/ownership, sync/async flow, retry/timeout/fallback, regulatory/ops impact.
 Security triggers: auth, secrets, PII, payments, public routes.
 
-Raw report (a pasted error, a support message, a ticket nobody shaped yet): call the Skill tool with "triage" first; its Brief is what you classify. Bug entry: a bug report is classified like any work, with one extra rule. Known cause and a one-file fix: S. Unknown cause: the first ticket is the diagnosis, run by the owning implementer through `diagnosing-bugs` (a loop that goes red on this bug before any hypothesis); the fix with its regression test at the seam is the second ticket. `/verifier` checks that the regression test exists, or that the missing seam is recorded as a finding.
+Raw report (a pasted error, a support message, a ticket nobody shaped yet): call the Skill tool with "triage" first; its Brief is what you classify. Bug entry: a bug report is classified like any work, with one extra rule. Known cause and a one-file fix: S. Unknown cause: the first ticket is the diagnosis, run by the owning implementer through `diagnosing-bugs` (a loop that goes red on this bug before any hypothesis); the diagnosis returns the seam that reproduced the bug, which becomes the fix ticket's seam row (state it to the user in one line, as for an M with a single ticket), and the fix with its regression test at that row is the second ticket. `/verifier` checks that the regression test exists there, or that the missing seam is recorded as a finding.
 
 ## 2. Worktree
 
@@ -49,20 +52,23 @@ One task worktree per affected repo, inside that repo, never `git checkout` in t
 5. Copy the files listed in `.worktreeinclude` (`.env`, `graphify-out/`, ...) into the worktree if missing there. Never stage them.
 6. Move the session in: `EnterWorktree` when available, otherwise tell the user to run `claude -w <slug>` and stop.
 7. Create `docs/plans/<task>.md` from `docs/plans/README.md` with title, ticket, size and `Status: draft`. The rest comes from `/product`.
+8. Build from a wayfinder map: copy `docs/plans/<effort>/` from the main checkout into the task worktree (a docs write), so the decisions ship on the same branch as the build and every agent reads the map at the same relative path. The copy left in the main checkout is the user's to commit or remove.
 
 ## 3. Grill (main session, with the user)
 
 - L: always. M: when two competent implementers could build different things from the request. S: never.
 - Call the Skill tool with "grilling". Rounds over the design tree, every question with a recommended answer; facts come from the code or a sub-agent, decisions from the user.
-- While it runs, write what `grill-with-docs` writes: settled terms into `GLOSSARY.md`, hard-to-reverse decisions as `Proposed` ADRs in `docs/adr/` (template in `docs/adr/README.md`). The user may start the same thing with `/grill-with-docs`.
+- Call the Skill tool with "domain-modeling" too, and write what `grill-with-docs` writes while the rounds run: settled terms into `GLOSSARY.md` in that skill's format, decisions that pass its three ADR tests as `Proposed` ADRs in `docs/adr/` (template and lifecycle in `docs/adr/README.md`, which wins over the skill's `ADR-FORMAT.md`). The user may start the same thing with `/grill-with-docs`.
+- After each round, before asking the next one, append the answers to `## Grill record` in `docs/plans/<task>.md`: the decision, the reason in the user's own words when they add nuance, the alternatives rejected and why, and any constraint said in passing. It is the only place the grill's reasoning survives outside your window; the decisions block is its summary, not a substitute.
 - Close with the decisions block (Decisions / Deferred / Out of scope / Plan changes) and apply it to the plan. Decisions that meet an architecture trigger go to `/architect`, not silently into the plan.
 
 ## 4. Plan
 
-- Dispatch `/product` (skill `brief`) with the request, the ticket, the decisions block and the plan path. It returns the plan: objective, scope, stories, AC, decisions, test seams, tickets, DoR, open questions. Write it to `docs/plans/<task>.md`.
+- Dispatch `/product` (skill `brief`) with the request, the ticket, the decisions block and the plan path, saying that the plan's `## Grill record` is the source of intent. A build that comes from a wayfinder map also gets the map path: its Decisions so far are settled. It returns every section except Session state and Grill record (objective, scope, stories, AC, decisions, tickets, test seams per level, DoD, open questions, terms), plus the DoR gate result. Write them to `docs/plans/<task>.md` and leave those two sections as they are.
+- **Check against the grill.** Before the ticket gate, while the grill is still in your window, read the plan against the Grill record: every decision shows up in Decisions, AC or Out of scope; no rejected alternative came back; every constraint binds a ticket or the DoD. A wording gap you fix in the plan yourself (it is a docs write). A gap that changes scope, seams or tickets goes back to `/product` with the record entry quoted.
 - Open questions -> ask the user before any ticket is briefed. Answers go into the plan; a changed decision goes back through grill, not around it.
 - L, or any architecture trigger: `/architect` on the plan. ADR proposal into Decisions, constraints into the affected tickets.
-- **Ticket gate.** Show the user the Tickets table as a numbered list (title, what it delivers, blocked by, agent) and ask three things: is the granularity right (too coarse, too fine), does each ticket depend only on what truly gates it, should any be merged or split. Iterate until approved; approved edits go into the plan. M with a single ticket: state it in one line and continue unless the user objects. No brief leaves before this gate. If the user is away, say which breakdown you took and proceed; a disagreement later costs one re-brief, not the plan.
+- **Ticket gate.** Show the user the Tickets table as a numbered list (title, what it delivers, blocked by, agent) and ask three things: is the granularity right (too coarse, too fine), does each ticket depend only on what truly gates it, should any be merged or split. Then show the Test seams table (level, seam, criteria, catches, leaves to) and ask a fourth: are these the right levels for each criterion, is a level where the risk lives missing, does a row only repeat what another level proves? Say where it departs from the default levels for the size (agent `product`, step 6), so the user reviews the departures, not the boilerplate. If the plan's Terms section is not `n/a`, confirm each term with the user too. Iterate until approved; approved edits go into the plan. On approval, date the `Confirmed:` line under Test seams and write the confirmed terms to `GLOSSARY.md` (skill `domain-modeling`): those rows are the pre-agreed seams `tdd` requires, which an implementer cannot ask the user for. M with a single ticket: state the ticket and its seam rows in one line and continue unless the user objects. No brief leaves before this gate. If the user is away, say which breakdown and which levels you took, leave `Confirmed: pending (user away, defaults taken)`, leave the Terms unconfirmed (nothing goes to `GLOSSARY.md`) and proceed; a disagreement later costs one re-brief, not the plan.
 - Ready gate: objective, AC, context, dependencies, seams and tickets filled. Any gap: no delegation.
 
 ## 5. Tickets
@@ -72,7 +78,7 @@ The plan's Tickets table is the work. One ticket = one tracer bullet = one brief
 - A ticket cuts a complete vertical path (schema, API, UI, tests) and is demoable alone. Horizontal slices (all schema, then all API) are not tickets.
 - `Blocked by` edges define the **frontier**: every ticket whose blockers are done. Work the frontier; nothing else.
 - Parallel only when frontier tickets have disjoint paths. Shared files -> sequential.
-- Each brief carries the ticket (title, delivers, AC, seams, paths), the decisions that bind it, and the DoD. Never "read the plan"; paste what the ticket needs.
+- Each brief carries the ticket (title, delivers, AC, its seam rows with their level, paths), the decisions that bind it, and the DoD. Never "read the plan"; paste what the ticket needs.
 - A ticket that turns out bigger than one context window goes back to `/product` to split, not to a second implementer.
 
 ## 6. Roster
@@ -90,7 +96,7 @@ The plan's Tickets table is the work. One ticket = one tracer bullet = one brief
 | `/verifier` | fresh-context check of diff vs plan: Spec axis then Standards axis; runs lint/build/test | no edits, opus high |
 | `/security` | auth, secrets, PII, payments, public routes; severity report | readonly, opus xhigh |
 
-Readonly agents are enforced by the `readonly-guard` hook. Implementers run `tdd` at the seams the plan lists and `diagnosing-bugs` on bugs without a known cause.
+Readonly agents are enforced by the `readonly-guard` hook. Implementers run `tdd` at the seam rows the plan lists and the user confirmed at the ticket gate, and `diagnosing-bugs` on bugs without a known cause.
 
 ## 7. Dispatch discipline
 
@@ -125,7 +131,7 @@ After every parallel batch, before any verifier or next ticket.
 ## 10. Verify
 
 - `/verifier` only after integration into the task worktree. Pass only: `Worktree: <task-wt>`, `Base ref: <task base sha>`, the DoD and the plan path. No implementation narrative.
-- It reports two axes separately: Spec (AC, seams, DoD) and Standards (rules, smells, quality). Blocked on either -> findings back to the owning implementer with a new brief. Second Blocked -> stop and report to the user.
+- It reports two axes separately: Spec (AC, seams at their level, DoD) and Standards (rules, smells, duplicated tests, glossary, quality). It runs the slow suites (integration, e2e) the plan's levels need; the Stop hook runs only the fast one. Blocked on either -> findings back to the owning implementer with a new brief. Second Blocked -> stop and report to the user.
 - Security trigger -> `/security` before the final commit. Critical/High must be fixed or explicitly accepted by the user.
 
 ## 11. ADR (L with an architecture decision)
@@ -159,7 +165,7 @@ Your context is the scarcest resource in the task: the plan file is durable, you
 
 A **phase boundary** is the gap after grill, after the ticket gate, after each ticket is integrated, and after `/verifier`. Mid-phase there is no decision: continue, or split what is left into subagents. At a boundary, take the first yes:
 
-1. **Continue** when the next phase needs this one verbatim (grill -> plan is the standard case) and there is room for it. Costs nothing, loses nothing.
+1. **Continue** when the next phase needs this one verbatim (grill -> plan is the standard case: you check `/product`'s plan against the grill you still hold) and there is room for it. Costs nothing, loses nothing.
 2. **`/clear`** when nothing in the window matters to what comes next (the plan already holds it). Cheapest move; one-way, so be sure.
 3. **`/handoff`** only when the work travels: another harness (Cursor, Codex), another repo or worktree, a colleague, or a parallel session of your own. Skill `handoff` writes `.claude/handoffs/<task>-<stamp>.md`.
 4. **Subagent** when the next chunk can run without you steering it: that is every ticket, every verification, every research question. Your window stays untouched.
@@ -175,7 +181,8 @@ Hygiene that keeps you out of the upper bands: never read code yourself (agents
 ## It's working if
 
 - Every code change in the task was made by an agent with a brief; your own writes are only under `docs/plans/`, `docs/adr/` and `GLOSSARY.md`.
-- The plan's Tickets table matches what was built, and the user saw and approved it before the first brief.
+- The plan's Tickets table matches what was built, and the user saw and approved it, with the Test seams levels, before the first brief.
+- Every decision in the plan traces to an entry in the Grill record (or, for a build from a wayfinder map, to the map), and no alternative the user rejected reappears in a ticket.
 - `/verifier` ran on the integrated worktree and its evidence (commands, output) is in the report; none of it is yours.
 - The window never crossed 110k tokens without a Session state update, and the final report fits on one screen.
 

package/.claude/skills/review/SKILL.md

@@ -22,14 +22,14 @@ Detect the package manager by lockfile and run the repo scripts that exist: lint
 ## 3. Find the sources
 
 - **Spec**: `docs/plans/<task>.md` (AC, Test seams, DoD), the ticket when an id is given (read only), ADRs in the touched area. None of them -> the Spec axis reports "no spec available".
-- **Standards**: `AGENTS.md`, `CLAUDE.md`, every `.claude/rules/*.md` whose `paths:` match the diff, the `review.md` under `.claude/skills/arch-*/references/` for the stacks touched, `CONTRIBUTING.md` / `CODING_STANDARDS.md` when present, plus the smell baseline in [references/smells.md](references/smells.md).
+- **Standards**: `AGENTS.md`, `CLAUDE.md`, `GLOSSARY.md`, every `.claude/rules/*.md` whose `paths:` match the diff, the `review.md` under `.claude/skills/arch-*/references/` for the stacks touched, `CONTRIBUTING.md` / `CODING_STANDARDS.md` when present, plus the smell baseline in [references/smells.md](references/smells.md).
 - `graphify-out/graph.json` present: `graphify query` / `path` for what the diff touches, pass the cited files to both subagents.
 
 ## 4. Spawn both subagents in parallel (foreground)
 
-**Standards subagent** receives: the diff command and commit list; the standards files found in step 3; the smell baseline pasted in full (it has no other access to it); and this brief: "Call the Skill tool with "ponytail-review" for the quality lens (is the logic right, is it safe, does it hold under load, is risky code tested, is it fast enough, is every line needed). Report per file/hunk: (a) every breach of a documented standard, citing the file and rule; (b) every baseline smell you spot, named, with the hunk quoted; (c) ponytail findings. Hard violations apart from judgement calls; a documented repo standard overrides the baseline. Skip what tooling enforces. Severity Critical / High / Medium / Low. Under 500 words."
+**Standards subagent** receives: the diff command and commit list; the standards files found in step 3; the smell baseline pasted in full (it has no other access to it); and this brief: "Call the Skill tool with "ponytail-review" for the quality lens (is the logic right, is it safe, does it hold under load, is risky code tested, is it fast enough, is every line needed). Report per file/hunk: (a) every breach of a documented standard, citing the file and rule; (b) every baseline smell you spot, named, with the hunk quoted; (c) ponytail findings; (d) the same assertion tested at two levels, and names that contradict `GLOSSARY.md` or use one of its `_Avoid_` words. Hard violations apart from judgement calls; a documented repo standard overrides the baseline. Skip what tooling enforces. Severity Critical / High / Medium / Low. Under 500 words."
 
-**Spec subagent** receives: the diff command and commit list; the plan, ticket and ADR contents; and this brief: "Report: (a) acceptance criteria missing or partial; (b) seams in the plan with no test, and tests placed at a seam the plan did not list; (c) behavior the diff adds that nobody asked for; (d) criteria that look implemented but wrong; (e) DoD items not met (docs for a changed route/job/store/integration/fallback, secrets in the diff, diff outside scoped paths). Quote the criterion or seam for each finding. Severity Critical / High / Medium / Low. Under 500 words."
+**Spec subagent** receives: the diff command and commit list; the plan, ticket and ADR contents; and this brief: "Report: (a) acceptance criteria missing or partial; (b) seam rows in the plan with no test at their level, criteria not tested at every level their rows list, and tests placed at a level or interface no row lists; (c) behavior the diff adds that nobody asked for; (d) criteria that look implemented but wrong; (e) DoD items not met (docs for a changed route/job/store/integration/fallback, secrets in the diff, diff outside scoped paths). Quote the criterion or seam for each finding. Severity Critical / High / Medium / Low. Under 500 words."
 
 Whole-repo request instead of a diff -> `ponytail-audit` replaces both axes. Diff adds or removes `shortcut:` comments -> run `ponytail-debt` and list them under Residual risk.
 

package/.claude/skills/wayfinder/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: wayfinder
+description: Plan a huge chunk of work (more than one agent session can hold) as a shared map of decision tickets in docs/plans/<effort>/, and resolve them one at a time until the way to the destination is clear.
+disable-model-invocation: true
+---
+
+A loose idea has arrived, too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** in `docs/plans/<effort>/`, then works its **decision tickets** (questions whose resolution is a decision, not slices of a build to execute) one at a time until the route is clear.
+
+The destination varies per effort, and naming it is the first act of charting: it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic: engineering work, course content, whatever fits the shape.
+
+Runs in the main session, from the main checkout rather than a task worktree, because most tickets need the user. Everything it writes is docs: the map and tickets under `docs/plans/<effort>/`, plus `GLOSSARY.md` and Proposed ADRs from grilling tickets, all inside what hook `orchestrator-guard` allows. The main session never edits code here either: anything that has to run code goes to an agent with a brief (skill `brief`).
+
+## Plan, don't do
+
+Wayfinder is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear, with nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off (see [The way is clear](#the-way-is-clear)). An effort can override this in its **Notes**, carrying execution into the map itself, but absent that, produce decisions, not deliverables.
+
+## Refer by name
+
+Every map and ticket is a file, so it has a **name**: its title. In everything the human reads (narration, the map's Decisions-so-far), refer to it by that name, never by a bare number or slug. A wall of `03, 04, 05` is illegible; names read at a glance. The number and path don't vanish; a name wraps its link (`[Pick the cache owner](decisions/03-cache-owner.md)`), but they ride _inside_ the name, never stand in for it.
+
+## The Map
+
+The map is a single file, `docs/plans/<effort>/map.md`, the canonical artifact. `<effort>` is a short kebab-case slug of the destination. Its tickets are files in `docs/plans/<effort>/decisions/`, numbered from `01`: `NN-<slug>.md`.
+
+The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place, its ticket, so the map never restates it, only gists it and links.
+
+### The map body
+
+The whole map at low resolution, loaded once per session. Open tickets are **not** listed: they are the files in `decisions/` whose `Status` is `open`.
+
+```markdown
+# <effort title>
+
+Status: active | done
+
+## Destination
+
+<what reaching the end of this map looks like: the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
+
+## Notes
+
+<domain; skills every session should consult; standing preferences for this effort>
+
+## Decisions so far
+
+<!-- the index: one line per resolved ticket, enough to judge relevance, then zoom the link for the detail the ticket holds -->
+
+- [<resolved ticket title>](decisions/NN-<slug>.md): <one-line gist of the answer>
+
+## Not yet specified
+
+<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
+
+## Out of scope
+
+<!-- see "Out of scope": work ruled beyond the destination; never graduates -->
+```
+
+`Status: active` is what hook `post-compact` looks for: after a compaction it re-injects the newest active map next to the active task plan, so a session in the middle of a ticket keeps the map. Set it to `done` when the way is clear.
+
+### Tickets
+
+Each ticket is a file; its number is its identity. Its body is the question, sized to one agent session (well inside the 120k compaction window; see skill `orchestrate` section 14):
+
+```markdown
+# <ticket title>
+
+Type: research | prototype | grilling | task
+Status: open | claimed | resolved | dropped | out of scope
+Blocked by: <NN, NN, or ->
+
+## Question
+
+<the decision or investigation this ticket resolves>
+```
+
+The `Type` line is the ticket's type (see [Ticket Types](#ticket-types)); the body never restates it. Tickets are decisions, not implementation work: they never get an agent, paths or a Definition of Done, and they never become rows in a task plan.
+
+A session **claims** a ticket by setting `Status: claimed` and saving the file, **first**, before any work, so concurrent sessions skip it. That line _is_ the claim: an `open` ticket is unclaimed.
+
+Blocking is the `Blocked by` line. A ticket is **unblocked** when every ticket it lists is `resolved`, `dropped` or `out of scope`; the **frontier** is the open, unblocked tickets, the edge of the known. First by number wins.
+
+The answer isn't part of the question; it's recorded on resolution under `## Answer` (see [Work through the map](#work-through-the-map)). Assets created while resolving a ticket (a research note, a prototype branch) are linked from the ticket, not pasted in.
+
+## Ticket Types
+
+Every ticket is either **HITL** (human in the loop, worked _with_ a human who speaks for themselves) or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
+
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by an `Explore` subagent (no Write or Edit tools, for the codebase and the web alike) dispatched with a research brief (skill `brief`): the question, primary sources only (official docs, source code, specs, first-party APIs), a source cited for every claim, and a return under 2k tokens. You write its findings under the ticket's `## Answer`; a long finding goes to `docs/plans/<effort>/research/<slug>.md`, linked from the ticket. Use when knowledge outside the current working directory is required.
+- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to (an outline, a rough take, a stub, or UI/logic code). An outline or rough take you write in the ticket yourself. Code is never yours: a UI question ("how should it look") goes to `/ui`, which reads skill `prototype` and builds variants behind its picker; a logic or state question ("how should it behave") goes to the owning implementer (`/api`, `/web`, `/app`) for a throwaway single-file prototype. Either way it goes out as a spike brief (skill `brief`): own worktree, branch `spike/<effort>-<NN>`, `Commit: yes`, lint only and no tests (a prototype is throwaway, so skill `tdd` does not apply), never merged or pushed. The ticket links the branch and records the verdict. Use when "how should it look" or "how should it behave" is the key question.
+- **Grilling** (HITL): Conversation. The default case. Always call the Skill tool twice, for "grilling" and "domain-modeling".
+- **Task** (HITL or AFK): Manual work that must happen before a _decision_ can be made: nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that _does_ rather than decides, and it earns its place by unblocking a decision, not by delivering the destination. Work that touches code or infrastructure goes to the owning agent with a spike brief (AFK); anything else, or anything needing the human's credentials or accounts, is a precise checklist for the human (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on. Never write a secret into the ticket: point at where it lives.
+
+A decision that is hard to reverse, surprising without context and the result of a real trade-off also becomes a `Proposed` ADR in `docs/adr/` (skill `domain-modeling` decides whether, `docs/adr/README.md` how). The ticket links it; it becomes `Accepted` with the change that implements it.
+
+## Fog of war
+
+The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war**: the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets, one at a time, until the way to the destination is clear and no tickets remain.
+
+The map's **Not yet specified** section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier _toward_ the destination: everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
+
+**Fog or ticket?** The test is whether you can state the question precisely now, _not_ whether you can answer it now.
+
+- **Ticket when** the question is already sharp, even if it's blocked and you can't act on it yet.
+- **Not yet specified when** you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
+
+**Not yet specified** excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
+
+## Out of scope
+
+Fog only ever gathers _toward_ the destination. The destination fixes the scope, so work beyond it is **out of scope**: it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section on the map: work you've consciously ruled out of _this_ effort. Scope, not sharpness, lands it here.
+
+Out-of-scope work never graduates (the frontier stops at the destination), so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
+
+Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination (mis-scoped in while charting, or exposed by a resolution), set its `Status: out of scope` (it is then unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the ticket. It stays out of **Decisions so far**, which records the route actually walked; a scope boundary isn't a step on it.
+
+## Invocation
+
+Two modes. Either way, **never resolve more than one ticket per session**, with the exception of research tickets. A session ends at its phase boundary with `/clear`, not `/handoff`: the map already is the handoff, for the next session, a parallel one or a colleague.
+
+### Chart the map
+
+User invokes with a loose idea (`/wayfinder <idea>`), often because skill `orchestrate` classified the work as fog.
+
+1. **Name the destination.** Call the Skill tool twice, for "grilling" and "domain-modeling", to pin down what this map is finding its way to: the spec, decision, or change. The destination fixes the scope, so it's settled first.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** (the way to the destination is already clear, the whole journey small enough for one session), you don't need a map. Stop and ask the user how they'd like to proceed; usually that is an L task in skill `orchestrate`, with what you just learned as its grill.
+3. **Create the map** (`docs/plans/<effort>/map.md`, `Status: active`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
+4. **Create the tickets you can specify now** as files in `decisions/`, numbered in the order you expect to work them, then wire the `Blocked by` lines in a **second pass**, once every ticket has its number. Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog: the **Not yet specified** section.
+5. **Fire the research subagents.** For each `research` ticket you just created, dispatch its read-only subagent (see [Ticket Types](#ticket-types)) in parallel, at most five in flight, and record each answer as it returns.
+6. Stop: charting is one session's work; it hand-resolves nothing.
+
+### Work through the map
+
+User invokes with a map (`/wayfinder docs/plans/<effort>`). A ticket is **optional**: without one, you pick the next decision, not the user.
+
+1. Load the **map**: the low-res view, not every ticket body.
+2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket by number. **Claim it**: set `Status: claimed` and save before any work.
+3. Resolve it as the type its `Type` line names (see [Ticket Types](#ticket-types)). Read the line, not just the question. **Zoom as needed**: open any related or resolved ticket on demand; call the Skill tool for whichever skills the `## Notes` block names. If in doubt, call the Skill tool twice, for "grilling" and "domain-modeling".
+4. Record the resolution: write the answer under `## Answer`, set `Status: resolved`, and **append a context pointer** to the map's Decisions-so-far.
+5. Add newly-surfaced tickets (create, then wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals that a ticket (this one or another) sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update those tickets, or set them `dropped` with the reason: a dropped ticket fell off the route, which is not the same as sitting past the destination.
+
+The user may run unblocked tickets in parallel sessions, so expect other sessions to be editing the map concurrently: claim first, re-read the map before appending to it.
+
+## The way is clear
+
+When **Not yet specified** is empty and no ticket is `open` or `claimed`, the way is clear. Set the map's `Status: done` and hand off to the build: an L task in skill `orchestrate`, which opens its own worktree and `docs/plans/<task>.md` and copies `docs/plans/<effort>/` into that worktree, so the decisions ship on the build's branch. The decisions are already made, so its grill covers only what the map left open, and the `/product` brief carries the map path as the source of those decisions, next to the Grill record.

package/.claude/skills/wayfinder/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Wayfinder"
+  short_description: "Map a large effort as decision tickets"
+policy:
+  allow_implicit_invocation: false

package/README.md

@@ -21,6 +21,7 @@
   - [The big picture](#the-big-picture)
   - [What `setup:pull` does, step by step](#what-setuppull-does-step-by-step)
   - [How each file is decided](#how-each-file-is-decided)
+  - [Projects that already have an AGENTS.md](#projects-that-already-have-an-agentsmd)
   - [What lands in your project](#what-lands-in-your-project)
 - [Working in a configured project](#working-in-a-configured-project)
 - [Command reference](#command-reference)
@@ -38,9 +39,9 @@ A complete working setup for Claude Code, kept in one repo and shipped as the np
 | Piece | What you get |
 |---|---|
 | **Agents** (10) | An orchestrator flow plus specialists: `quick`, `product`, `architect`, `api`, `web`, `app`, `infra`, `ui`, `verifier`, `security` |
-| **Skills** (37) | Workflow (orchestrate, triage, brief, review, grilling, handoff, retro), architecture (`arch-api`, `arch-web`, `arch-app`, `arch-db`), quality (tdd, diagnosing-bugs, ponytail), design and motion |
+| **Skills** (39) | Workflow (orchestrate, triage, brief, review, grilling, domain-modeling, wayfinder, handoff, retro), architecture (`arch-api`, `arch-web`, `arch-app`, `arch-db`), quality (tdd, diagnosing-bugs, ponytail), design and motion |
 | **Rules** (9) | Loaded always or by path glob: git, tickets, api, web, mobile, db, ui, graphify, delivery diagram |
-| **Hooks** (8) | Deterministic guards that block what rules can only ask for: `git push`, `git add -A`, staging `.env`, the orchestrator editing code, lint and tests on Stop |
+| **Hooks** (8) | Deterministic guards that block what rules can only ask for: `git push`, `git add -A`, staging `.env`, the orchestrator editing code, lint and unit tests on Stop |
 | **AGENTS.md** | The shared base that Cursor and Codex read too |
 | **Updates** | A manifest of every installed file, so updates refresh what you did not touch and never overwrite what you changed |
 
@@ -182,12 +183,68 @@ flowchart TD
 
 **Never touched, not even with `--force`:** `CLAUDE.md`, `.claude/settings.local.json` and `.claude/agent-memory/**`.
 
+**Never shipped, so never touched either:** what the project's own work produces: `docs/plans/**` and `docs/adr/**` (except their `README.md` templates), `GLOSSARY.md`, `GLOSSARY-MAP.md` and context glossaries, `.claude/handoffs/**`. An update cannot overwrite or delete them even if a manifest lists them, and `check-catalog.mjs` fails if the config ever tries to ship one.
+
 | Situation | Result |
 |---|---|
 | New project, nothing installed | Everything added, `CLAUDE.md` created, `.gitignore` extended |
 | Configured project, nothing edited | New files added, changed files updated, removed files deleted |
 | You edited a shipped file | Kept and listed; `--force` replaces it with the config version |
 | Project configured before the manifest existed | Differing files count as edited; review them, then run `--force` once |
+| The project has its own `AGENTS.md` | You choose: keep, overwrite, append or print ([next section](#projects-that-already-have-an-agentsmd)) |
+
+### Projects that already have an AGENTS.md
+
+Many projects already carry an `AGENTS.md` with their own rules. When the project copy differs from the config, `setup:pull` asks what to do. Press Enter to keep yours; outside a terminal (CI, scripts) it keeps yours and lists the options.
+
+```text
+AGENTS.md already exists in this project and differs from the config. What should happen to it?
+  [k] keep yours as it is (default)
+  [o] overwrite it with the config version
+  [a] append the config version at the end, in a managed block that later pulls keep current
+  [p] print the config version here, to concatenate it yourself
+Choice [k/o/a/p]:
+```
+
+```mermaid
+flowchart TD
+    A["Project AGENTS.md differs<br/>from the config"] --> B{"Has a managed block?"}
+    B -- yes --> RB["Refresh only the block<br/>no question asked"]
+    B -- no --> Q{"Your choice<br/>prompt or --agents-md"}
+    Q -- keep --> K["Yours stays as it is"]
+    Q -- overwrite --> O["Replaced by the config version<br/>later pulls keep it current"]
+    Q -- append --> AP["Config version added at the end<br/>inside the managed block"]
+    Q -- print --> P["Config version printed<br/>you paste it where you want"]
+    AP -. "next pull" .-> RB
+    P -. "pasted with the markers" .-> RB
+
+    classDef keep fill:#f3f4f6,stroke:#9ca3af,color:#374151
+    classDef upd fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
+    classDef add fill:#dcfce7,stroke:#16a34a,color:#14532d
+    classDef out fill:#fef3c7,stroke:#d97706,color:#78350f
+    class K keep
+    class O,RB upd
+    class AP add
+    class P out
+```
+
+The managed block is plain Markdown between two comments. Everything outside the markers is yours; later pulls replace only what is inside them:
+
+```markdown
+# My project
+Rules that belong to this project.
+
+<!-- agents-config:start -->
+<!-- Managed by @evertonferreira96/agents: `chew agents setup:pull` refreshes this block. Edit outside the markers. -->
+...the config AGENTS.md...
+<!-- agents-config:end -->
+```
+
+| Want | Command |
+|---|---|
+| Decide without the question | `chew agents setup:pull --agents-md=keep` (or `overwrite`, `append`, `print`) |
+| Just see the config version | `chew agents setup:print` (in the managed block) or `chew agents setup:print --raw` (file alone) |
+| Concatenate from the shell | `chew agents setup:print >> AGENTS.md` (bash, zsh, cmd; in Windows PowerShell 5, `>>` writes UTF-16, so use `--agents-md=append`) |
 
 ### What lands in your project
 
@@ -205,7 +262,7 @@ your-project/
 ├── scripts/                   bootstrap, check-catalog, skills-update
 └── .claude/
     ├── agents/                10 agents
-    ├── skills/                37 skills
+    ├── skills/                39 skills
     ├── rules/                 9 rules
     ├── hooks/                 8 hooks
     ├── settings.json          hook wiring, worktree base, context limits
@@ -227,14 +284,17 @@ flowchart TD
     TRI --> CLS
 
     CLS -- "S: one file,<br/>one-sentence diff" --> QK["quick agent"]
-    QK --> STOP["Stop hook<br/>lint and tests"]
+    QK --> STOP["Stop hook<br/>lint and unit tests"]
+
+    CLS -- "fog: decisions need<br/>research or a prototype" --> WF["wayfinder<br/>one decision per session"]
+    WF -- "map done" --> WT
 
     CLS -- "M or L" --> WT["Task worktree<br/>.claude/worktrees/slug"]
     WT --> GRL["Grill with you<br/>L always, M on open decisions"]
-    GRL --> PRD["product agent<br/>scope, AC, test seams, tickets"]
+    GRL --> PRD["product agent<br/>scope, AC, test seams per level, tickets"]
     PRD -- "L or architecture trigger" --> ARC["architect agent"]
     PRD -- M --> GATE
-    ARC --> GATE{"You approve<br/>the tickets"}
+    ARC --> GATE{"You approve the tickets,<br/>test levels and terms"}
     GATE --> IMP["One implementer per ticket<br/>api, web, app, infra, ui<br/>test-first with tdd"]
     IMP --> INT["Integrate"]
     INT --> VER["verifier agent<br/>Spec axis, then Standards axis"]
@@ -246,7 +306,7 @@ flowchart TD
     classDef you fill:#fef3c7,stroke:#d97706,color:#78350f
     classDef agent fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
     classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d
-    class GRL,GATE you
+    class GRL,GATE,WF you
     class QK,PRD,ARC,IMP,VER,SEC agent
     class STOP guard
 ```
@@ -256,14 +316,14 @@ flowchart TD
 | Agent | Does | Mode |
 |---|---|---|
 | `quick` | S work: one file, one-sentence diff | writes |
-| `product` | Plan: scope, stories, acceptance criteria, test seams, tickets | read-only |
+| `product` | Plan: scope, stories, acceptance criteria, test seams per level, terms, tickets | read-only |
 | `architect` | Boundaries, contracts, failure modes; verdict and ADR proposal | read-only |
 | `api` | Server side: APIs, domain, persistence, workers (`arch-api`, `arch-db`, `tdd`) | writes |
 | `web` | Next.js app (`arch-web`, `tdd`) | writes |
 | `app` | React Native / Expo app (`arch-app`, `tdd`) | writes |
 | `infra` | Terraform, CI, deploy, observability; never applies | writes |
 | `ui` | Design system, tokens, components, motion, accessibility | writes |
-| `verifier` | Fresh-context check of the diff against the plan; runs lint, build, tests | no edits |
+| `verifier` | Fresh-context check of the diff against the plan; runs lint, build and every test suite, integration and e2e included | no edits |
 | `security` | Auth, secrets, PII, payments, public routes; severity report | read-only |
 
 **Guardrails enforced by hooks**
@@ -273,9 +333,9 @@ flowchart TD
 | `guard-bash` | Blocks `git push`, `git add -A` / `.`, staging `.env*`, `--no-verify`, `reset --hard`, `clean -f`, PR and issue writes |
 | `orchestrator-guard` | The main session can edit plans, ADRs and docs, never code |
 | `readonly-guard` | Read-only agents can only write their own memory |
-| `stop-verify` | Lint and tests on Stop when the tree changed |
+| `stop-verify` | Lint and the fast test suite (`test:unit`, else `test`) on Stop when the tree changed; integration and e2e run in `verifier` |
 | `context-budget` | Warns at 60k, 90k and 110k tokens; compaction at 120k |
-| `post-compact` | Re-injects the active plan after compaction |
+| `post-compact` | Re-injects the active plan, and the active wayfinder map, after compaction |
 | `graphify-update` | Refreshes the code graph after edits, when one exists |
 | `config-update-check` | One line at session start when a local-clone install has a newer version |
 
@@ -291,6 +351,7 @@ The full flow, with every section of the playbook, is in [`.claude/skills/orches
 |---|---|
 | `chew agents setup:pull [dir]` | Download the latest version and install or refresh it in `dir` (default: current folder) |
 | `chew agents setup:check [dir]` | Compare the project with the latest version; exit code 1 on drift |
+| `chew agents setup:print` | Print the latest config `AGENTS.md` in its managed block, to concatenate into yours (`--raw`: the file alone) |
 | `chew --version` | Version of the installed `chew` |
 
 | Flag | Effect |
@@ -298,6 +359,7 @@ The full flow, with every section of the playbook, is in [`.claude/skills/orches
 | `--force` | Also overwrite files edited in the project (protected files excepted) |
 | `--dry-run` | Show what would change, write nothing |
 | `--local` | Use the version installed with `chew` instead of downloading |
+| `--agents-md=<choice>` | When the project has its own `AGENTS.md`: `keep` (default), `overwrite`, `append` or `print`; skips the question |
 
 ### `agents` (same package, via `npx` or global)
 
@@ -306,6 +368,9 @@ The full flow, with every section of the playbook, is in [`.claude/skills/orches
 | `agents init [dir]` | Copy what is missing; never overwrites |
 | `agents update [dir]` | Same rules as `setup:pull`, using this installed version |
 | `agents check [dir]` | Report missing, outdated, edited and obsolete files; exit 1 on drift |
+| `agents print-agents-md` | Same as `chew agents setup:print`, for this installed version |
+
+`init` and `update` accept `--force`, `--dry-run` and `--agents-md=<choice>`, like `chew`.
 
 ### Legacy, from a local clone
 
@@ -409,6 +474,13 @@ By design: files edited in the project are kept and listed as `edited`. `chew ag
 
 </details>
 
+<details>
+<summary><b>My project's AGENTS.md was not touched</b></summary>
+
+Keeping it is the default when no choice is given, including every run outside a terminal. Run `chew agents setup:pull --agents-md=append` to add the config in a managed block below your content, or `--agents-md=overwrite` to replace it. See [Projects that already have an AGENTS.md](#projects-that-already-have-an-agentsmd).
+
+</details>
+
 <details>
 <summary><b>"no manifest from a previous install"</b></summary>
 

package/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.4