agent-issues 0.0.119

package/skills/ai-start-work/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ai-start-work
+description: Start work on an initiative. Find the next workable issue, decide how to approach it, then drive the build with ai-tdd or ai-implement.
+argument-hint: Initiative or issue ID to start working on (optional)
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Start Work
+
+Pick up an initiative that is already planned: grilled, captured as a PRD, broken into issues, and handed off. Begin the real build. This skill answers two questions, *what to work on next* and *how to approach it*, then hands the active issue to the `ai-tdd` skill to build.
+
+This skill is the bridge between planning and coding.
+
+## Process
+
+### 1. Select the active initiative
+
+Find the scope you were asked to work on.
+
+- If the user gave an initiative or issue ID, start there. If not, ask one routing question to find the initiative.
+
+### 2. Select the next workable issue
+
+Start the `ai-next-work` skill for the active scope. It runs the **Next Work** recipe. If the user supplied an explicit issue, treat it as confirmed and continue to step 3. Otherwise, show its result and confirm the selected issue with the user before you write code. If it reports the work is complete or blocked, stop and return that result.
+
+### 3. Decide how to approach it
+
+Once the issue is selected, work out the approach before you start the build.
+
+- Explore the codebase to understand the current state of the area the issue touches.
+- Run the **Relation Query** recipe for the selected issue with its complete relation set. Use the result to identify constraining ADRs, fixed user stories, open blockers, and parent or sub-issue boundaries. Do not repeat relation queries per relation type when one complete result provides them.
+- Find the public interface the slice must expose and the behavior the user stories require.
+- Surface any assumption the plan left open. If a real, hard-to-reverse design question comes up, send it to `/ai-grill-with-docs`. Do not decide it on your own.
+
+Summarize the approach in a few lines: the interface, the behaviors that matter, and the layers the slice cuts through.
+
+### 4. Hand off to a build skill
+
+Begin the build under test-driven development. Use incremental implementation instead when the change does not fit a red-green-refactor loop, for example a broad refactor, a config or infrastructure change, or a multi-file migration.
+
+- Run the **Entity State And Structure** recipe to set the selected issue to `in-progress`.
+- Start `ai-tdd` with the selected issue and approach, or `ai-implement` when the change has no fast test seam. Wait for its completion result and its next-workable-issue result before you continue.
+- Do not write production code outside that loop. This skill chooses the work. The build skill builds it.
+
+### 5. Continue or stop
+
+When the build skill reports the finished issue and its next-workable-issue result:
+
+- If it recommends an issue, show that issue and ask whether to continue with it.
+- If the user agrees, treat the recommendation as the selected issue and return to step 3 to decide the approach. Do not repeat step 2.
+- If no issue is workable, report whether the initiative's issue work is complete, or show the remaining blocker chain that the build skill reported.
+- If the user declines, or when the work is complete, blocked, or out of scope, leave the tracker accurate. Offer `/ai-handoff` so the next session can start cleanly.
+
+Do not run more than one issue through one tdd run. One issue at a time keeps the tracker and the slices honest.

package/skills/ai-tdd/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ai-tdd
+description: Test-driven development with a red-green-refactor loop, anchored to the active agent-issues issue.
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# Test-Driven Development
+
+## Philosophy
+
+Test observable behavior through public interfaces. Prefer integration-style tests that survive internal refactors.
+
+See [tests.md](tests.md) for examples. See [mocking.md](mocking.md) for mocking rules.
+
+## Removed behavior
+
+When an issue removes a feature, constraint, or compatibility path, remove or update its obsolete tests. Do not add a new test whose only purpose is to confirm that deleted code or an obsolete restriction has not returned. That test has no current behavior contract and adds maintenance cost. Test a replacement or newly supported observable behavior when the change creates one. Add an absence test only when the active issue or a relevant ADR makes the absence an explicit, observable requirement.
+
+## Static declarations
+
+Do not add a test that reads a static declaration and restates its literal shape or values. Examples include object trees, route tables, dependency lists, manifests, schema entries, and constant maps. Such a test duplicates the implementation and fails on an intentional edit without protecting caller behavior.
+
+For a static declaration change, test the behavior that consumes the declaration through its public interface. If no distinct behavior can fail, do not force a red-green cycle. Use the existing behavioral suite, type-check, lint, build, or focused inspection as validation instead. Test the declaration directly only when its serialized shape is itself a supported external contract.
+
+## Anti-pattern: horizontal slices
+
+Use vertical tracer bullets. Do not write all the tests first and all the implementation second.
+
+## Workflow
+
+### 1. Planning
+
+Run the **Entity Read** recipe, the **Relation Query** recipe, and the **Context Read** recipe for the active issue and its scope. Read every linked `planEntries` item returned by the issue; its current body can contain implementation decisions and constraints. Confirm the public interface, the priority behaviors, and the approach. Resolve any hard-to-reverse question before you code. See [deep modules](deep-modules.md) and [interface design](interface-design.md) when these concerns matter.
+
+Treat the issue's `planEntries` as planning inputs. Do not create or change Plan-entry links. Report missing Plan-entry provenance to the issue creator.
+
+### 2. Tracer bullet
+
+Write one test that confirms one thing about the system.
+
+```
+RED:   Write test for first behavior -> test fails
+GREEN: Write minimal code to pass -> test passes
+```
+
+Confirm the test fails for the expected reason before you write the implementation.
+
+### 3. Incremental loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test -> fails
+GREEN: Minimal code to pass -> passes
+```
+
+Run one test at a time. Write only enough code to pass it. Then move to the next behavior.
+
+### 4. Refactor
+
+Refactor only while the tests are green. Use the [refactoring guidance](refactoring.md). Run the focused tests again after each step.
+
+### 5. Implementation review gate
+
+You, the visible `ai-tdd` agent, own the TDD cycles, the focused validation, and any repairs. Do not hand the build to a subagent: you hold the context on what the active `ai-*` skills expect, and a subagent does not have it. Do not treat the first passing test as the end of the work.
+
+After your first focused validation passes, start one read-only review subagent. This is the only step that runs as a subagent. Give the reviewer the active issue context, the changed-file diff, the validation you already ran, and the shared [language standard](../agent-issues-language.md). The reviewer's report, its findings, and every message it writes must follow that standard.
+
+The reviewer must cover both of these:
+
+- **Behavior and contract:** Compare the implementation and tests against the active issue, the linked user stories, the relevant ADRs, and the observable public behavior. Find missing behaviors, wrong semantics, and gaps in behavior coverage.
+- **Code and regression risk:** Inspect the changed code for correctness defects, unplanned scope, regressions, gaps in error handling, maintainability concerns, and gaps in validation.
+
+The reviewer must not edit files. It must return either no findings, or structured findings with a severity, a file and location, evidence, and a concrete fix.
+
+`ai-tdd` rejects a finding only when it can explain why the finding is invalid or out of scope. For every valid, material finding, fix it yourself. Then run the focused validation that covers the fix. Do not hand repairs to a subagent. If there are no material findings, `ai-tdd` records the reviewer report before the final validation. Do not mark the issue done until this gate is complete.
+
+### 6. Complete and report
+
+After the review gate and the final focused validation pass, mark the active issue `done`. Start the `ai-next-work` skill with the active initiative. Include its result in the completion report. Do not start the selected issue.
+
+## Implementer standards
+
+If you need a paragraph-long comment to justify a workaround, the code is wrong. Fix the code.
+
+## Checklist per cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Test does not restate a static declaration unless that shape is an external contract
+[ ] Test covers current or newly supported behavior, not only the absence of removed behavior
+[ ] Obsolete tests were removed or updated
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/skills/ai-tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From *A Philosophy of Software Design*:
+
+**Deep module**: a small interface with a lot of implementation behind it.
+
+```
+┌─────────────────────┐
+│   Small Interface   │
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module**: a large interface with little implementation behind it.
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │
+├─────────────────────────────────┤
+│  Thin Implementation            │
+└─────────────────────────────────┘
+```
+
+When you design an interface, ask:
+
+- Can you reduce the number of methods?
+- Can you simplify the parameters?
+- Can you hide more complexity inside?

package/skills/ai-tdd/interface-design.md

@@ -0,0 +1,20 @@
+# Interface Design for Testability
+
+A good interface makes testing easy:
+
+1. Accept dependencies. Do not create them inside the function.
+
+   ```typescript
+   function processOrder(order, paymentGateway) {}
+   ```
+
+2. Return a result. Do not rely on a side effect.
+
+   ```typescript
+   function calculateDiscount(cart): Discount {}
+   ```
+
+3. Keep the surface area small.
+
+- Fewer methods need fewer tests.
+- Fewer parameters need simpler test setup.

package/skills/ai-tdd/mocking.md

@@ -0,0 +1,28 @@
+# When to Mock
+
+Mock only at system boundaries:
+
+- External APIs.
+- Databases, when a test database is not practical.
+- Time and randomness.
+- File system access, when you need it.
+
+Do not mock:
+
+- Your own classes or modules.
+- Internal collaborators.
+- Anything you control.
+
+## Design for Mockability
+
+At system boundaries, design an interface that is easy to mock.
+
+1. Use dependency injection.
+2. Prefer an SDK-style interface over a generic fetcher.
+
+The SDK approach gives you:
+
+- One specific shape per mock.
+- No conditional logic in test setup.
+- A clear view of which endpoints a test uses.
+- Better type safety for each endpoint.

package/skills/ai-tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After a TDD cycle, look for:
+
+- Duplication: extract a function or a class.
+- Long methods: break them into private helpers. Keep the tests on the public interface.
+- Shallow modules: combine them or add depth.
+- Feature envy: move the logic to where the data lives.
+- Primitive obsession: introduce value objects.
+- Existing code that the new work shows is a problem.

package/skills/ai-tdd/tests.md

@@ -0,0 +1,74 @@
+# Good and Bad Tests
+
+## Good tests
+
+An integration-style test goes through a real interface. It does not mock internal parts.
+
+```typescript
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Look for these traits:
+
+- Tests behavior that users or callers care about.
+- Uses the public API only.
+- Survives an internal refactor.
+- Describes what the code does, not how.
+- Has one logical assertion per test.
+
+## Bad tests
+
+An implementation-detail test is tied to the internal structure.
+
+```typescript
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Watch for these warning signs:
+
+- Mocking internal collaborators.
+- Testing private methods.
+- Asserting on call counts or call order.
+- Breaking on a refactor with no behavior change.
+- Test names that describe how, not what.
+- Checking through an external system instead of through the interface.
+- Restating a static object, manifest, route table, schema, or constant map.
+- Failing on an intentional declaration edit when no caller behavior changed.
+
+```typescript
+test("groups accounting setup modules", () => {
+  expect(moduleTree).toMatchObject({
+    setup: {
+      accountingsetup: {
+        codingtemplate: {},
+        invoiceagreement: {},
+      },
+    },
+  });
+});
+```
+
+This test copies the declaration into the assertion. Test behavior that resolves or inherits modules from this hierarchy. If there is no distinct consumer behavior to test, use a type-check, lint, build, or focused inspection instead.
+
+```typescript
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/skills/ai-to-issues/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: ai-to-issues
+description: Break a plan or PRD into independently grabbable issues, then create and link those issues in agent-issues.
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+# To Issues
+
+Break a plan into sequenced, independently verifiable issues. Use tracer-bullet vertical slices.
+
+## Process
+
+### 1. Gather context
+
+Work from what is already in the conversation context. If the user gives an entity ID, run the **Entity Read** recipe to resolve it. If the user gives a file path, read the file first.
+
+Run the **Initiative Read** recipe and the **Relation Query** recipe for the active scope to find:
+
+- the parent initiative that must structurally own the new issues
+- the PRD and user stories the issues must satisfy
+- the active Plan entries that each new issue implements, when the work comes from a Plan
+- any existing issues or blockers you must reuse instead of duplicate
+
+### 2. Explore the codebase
+
+If you have not explored the codebase yet, do so now to understand the current state of the code. Issue titles and descriptions must use the established vocabulary and respect the ADRs in the area you touch.
+
+### 3. Draft vertical slices
+
+List every testable behavior, contract, state, integration, and verification change in the plan. Draft one tracer-bullet issue per change. Dependencies remain linked issues; a shared feature outcome is not a reason to merge them.
+
+A slice can be `HITL` or `AFK`. Prefer `AFK` over `HITL` when you can. If the choice matters to the user, state it in the text you present. Do not invent unsupported tracker fields.
+
+Rules:
+
+- Each slice delivers one narrow, complete change through the affected behavior.
+- A finished slice is demoable or verifiable on its own.
+- Merge changes only when they share one implementation boundary and one acceptance check.
+- Use sub-issues when related changes must roll up under one parent issue. In this shape, leaf sub-issues normally carry the `fixes` links to user stories.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- Title
+- Type: `HITL` or `AFK`
+- Blocked by
+- User stories covered
+
+Ask whether the size of each slice and the dependencies feel right, whether to merge or split any slices, and whether the `HITL` and `AFK` split is correct.
+
+Repeat until the user approves the breakdown.
+
+### 5. Publish the issues in agent-issues
+
+For each approved slice:
+
+1. Write a short markdown issue body from the [Issue recipe](../recipes/issue.md) before you publish it. Keep the substance of the approved slice in the body, not just in the title. Include the slice type (`AFK` or `HITL`), the user-visible outcome, the main implementation seam, the acceptance criteria, and any explicit blocker or dependency from the approved breakdown.
+2. The **Entity Create And Edit** recipe sends the body as direct MCP text. Its CLI fallback reads the body from standard input; do not place multiline text in a shell argument.
+3. Run the **Entity Create And Edit** recipe to create the issue under the correct structural parent: the initiative for top-level work or the parent issue for a sub-issue.
+4. If you reuse an existing issue whose body is missing or old, run the **Entity Create And Edit** recipe to update its body before you link anything else.
+5. Run the **Entity Relations** recipe to link each leaf issue to every user story it satisfies with `fixes`.
+6. For Plan-based work, run the **Plan Entry Issue Link** recipe to link each issue to every active Plan entry it implements with `informs`. Issue creation owns these links.
+7. Run the **Entity Relations** recipe to record dependencies with `blocks`.
+
+Publish blockers first, so later issues can link to real issue IDs.
+
+Return a short summary that shows each created issue ID, its linked Plan entries and user stories, and its blockers.

package/skills/ai-to-prd/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ai-to-prd
+description: Turn an explicit ready Plan into a PRD, create the tracked PRD in agent-issues, and create the user stories that the PRD commits to.
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+This skill turns an explicit ready Plan and relevant codebase knowledge into a PRD. Do not run an open-ended interview.
+
+A PRD is not created until the `prd` entity exists and its user stories exist as child `userStory` entities.
+
+## Process
+
+1. Require one explicit ready Plan reference. If it is missing or resolves to more than one Plan, stop and ask for the reference. Do not infer a Plan from conversation context.
+
+2. Run the **Entity Read** recipe for the Plan and the **Relation Query** recipe for its direct incoming `owns` relation. Reject a record that is not a Plan or is not `ready`. The Plan must have one initiative owner.
+
+3. Run the **Plan Entry Read** recipe to read the Plan entries. Select active entries by excluding an entry with `tombstone: true` and an entry whose ID occurs in another entry's `supersededEntryIds`. Use only active Plan entries as the source for the PRD and user stories. Do not copy obsolete entry history.
+
+4. If you have not explored the repo yet, do so now to understand the current state of the code. Choose seams where you will test the feature. Use the established vocabulary throughout the PRD and respect applicable ADRs.
+
+5. Write the PRD from the [PRD recipe](../recipes/prd.md). Write each user story from the [User Story recipe](../recipes/user-story.md). Map active entry roles into the relevant product requirements, decisions, scope, constraints, preferences, considerations, and unresolved implementation questions. The child `userStory` entities are authoritative. Do not duplicate their story text in the PRD body.
+
+6. Save the full PRD markdown from the template in the tracked record body. Run the **Entity Create And Edit** recipe to create the `prd` with its initiative parent and direct body text. This preserves initiative ownership of the PRD.
+
+7. Run the **Entity Create And Edit** recipe to create one `userStory` entity for each approved numbered user story with the PRD as parent. The title can be short, but the body must keep the full committed user story sentence and any essential note tied to that story.
+
+8. Run the **Plan Entry Issue Link** recipe to create the non-structural Plan `informs` PRD provenance relation. The MCP operation supports issue targets. If this Plan link targets a PRD, use the explicit CLI fallback in that recipe. Verify that the PRD has initiative ownership and Plan provenance.
+
+9. Return the PRD content together with the tracked IDs you created. Do not create or update a markdown PRD file. The tracked `prd` and `userStory` records are the only canonical PRD representation for this workflow.
+
+Do not treat a markdown document, chat response, or external issue as the source of truth on its own. Do not create a side markdown PRD as part of this workflow. Do not infer a Plan or reuse an existing PRD during conversion.

package/skills/ai-wayfinder/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: ai-wayfinder
+description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
+disable-model-invocation: true
+---
+
+Follow the shared [language standard](../agent-issues-language.md).
+Follow the shared [skill operating contract](../agent-issues-operating-contract.md).
+
+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 `agent-issues`, 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.
+
+## Plan, don't do
+
+Wayfinder is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear — 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. An effort can override this in its **Notes** — carrying execution into the map itself — but absent that, produce decisions, not deliverables.
+
+## Refer by title
+
+Every map and ticket is an issue, so it has a **title**. In everything the human reads — narration and the map's Decisions-so-far — refer to it by title, not by an internal id, number, or slug. Include the complete `reference` returned by `agent-issues` in its link. Do not abbreviate or replace that reference.
+
+## The Map
+
+The map is a single `agent-issues` issue under the active initiative — the canonical artifact. Its tickets are child issues of the map.
+
+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.
+
+Use `agent-issues` as the source of truth. Run the **Entity Create And Edit** recipe to create the map as a `wayfinder-map` issue under the initiative and each ticket as a `wayfinder-ticket` child of the map. Run the **Entity Relations** recipe to add dependencies after creation with `blocks` relations.
+
+### The map body
+
+The whole map at low resolution, loaded once per session. Open tickets are **not** listed — run the **Entity List** recipe for child issues under the map when needed.
+Use the [Wayfinder Map recipe](../recipes/wayfinder-map.md). It preserves the current map format.
+
+### Tickets
+
+Each ticket is a **child issue** of the map. Its body contains one question, sized to one 100K token agent session:
+Use the [Wayfinder Ticket recipe](../recipes/wayfinder-ticket.md). It preserves the current ticket format.
+
+The `## Ticket type` value is one of `research`, `prototype`, `grilling`, or `task`; see Ticket Types below.
+
+A session **claims** a ticket before work by running the **Entity State And Structure** recipe to set its status to `in-progress`. If this fails because another session changed the ticket, reload the frontier and select another ticket. An open `todo` or `ready` ticket is unclaimed.
+
+Blocking uses the native `blocks` relation. A ticket is **unblocked** when every blocker has status `done`; the **frontier** is the open, unblocked, unclaimed child issues. Run the **Entity List** recipe and use each child issue's `openBlockers` to identify it.
+
+Run the **Entity Create And Edit** recipe to record the answer in `## Resolution` when the ticket is complete, then run the **Entity State And Structure** recipe to set the ticket status to `done`. Link assets created while resolving a ticket from the issue body; do not paste them into the map.
+
+### Plan-backed ticket planning
+
+For a grilling ticket, give `ai-plan` the complete ticket reference. It runs the **Entity Create And Edit** recipe to create an initiative-owned Plan for a new effort, or resumes only an explicit Plan reference. Every Plan entry from that session uses the **Plan Entry Write** recipe to link back to the ticket reference.
+
+The Plan is the canonical detailed resolution. When the ticket is done, retain its Question and status, and use a concise Resolution link to the Plan. Do not copy the detailed reasoning into the ticket. A Plan does not inform a Wayfinder map.
+
+## 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): Read documentation, third-party APIs, or local resources to find a fact that a decision needs. Resolve it with a read-only research subagent. Use this type when knowledge outside the current working directory is required.
+- **Prototype** (HITL): Raise the fidelity of the discussion with a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI or logic code through `ai-prototype`. Link the prototype as an asset. Use this type when "how should it look" or "how should it behave" is the key question.
+- **Grilling** (HITL): Conversation. This is the default type. Always use `ai-plan` with `ai-domain-modeling` active.
+- **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. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (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.
+
+## 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 — **close it** (a closed ticket is 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 closed 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.
+
+### Chart the map
+
+User invokes with a loose idea.
+
+1. **Resolve the tracked scope.** Run the **Entity Read** recipe and the **Context Read** recipe to find the active initiative and read its context. For a new feature, run the **Entity Create And Edit** recipe to create a new initiative by default. Do not create a map outside an initiative.
+2. **Name the destination.** Run `ai-plan` with `ai-domain-modeling` active to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so settle it first.
+3. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surface the open decisions and the first steps that are possible now. **If this finds no fog** — the way to the destination is already clear and small enough for one session — do not create a map. Ask the user how to proceed.
+4. **Create the map** as a `wayfinder-map` child issue of the initiative: Destination and Notes filled in, Decisions-so-far empty, and the fog recorded in **Not yet specified**.
+5. **Create the tickets you can specify now** as `wayfinder-ticket` child issues of the map. Then wire `blocks` relations in a second pass, because issues need references before they can link to each other. This separates the frontier from blocked tickets. Keep everything you cannot yet specify in **Not yet specified**.
+6. **Start research subagents.** For each new `research` ticket, start a read-only research subagent. It returns its findings to the current agent, which records the resolution and updates the ticket. Do not create a branch unless the research needs a prototype or another tracked artifact.
+7. Stop — charting is one session's work; it does not resolve a HITL ticket.
+
+### Work through the map
+
+User invokes with a map (URL or number). A ticket is **optional** — without one, you pick the next decision, not the user.
+
+1. Run the **Entity Read** recipe to load the **map**, then run the **Context Read** recipe for its scoped context. Do not load every ticket body.
+2. Choose the ticket. If the user named one, use it. Otherwise select the first frontier ticket. **Claim it** by setting it to `in-progress` before work.
+3. Resolve it — **zoom as needed**: run the **Entity Read** recipe or the **Relation Query** recipe to load related or closed tickets only when needed. Use the skills named in `## Notes`. For a grilling ticket, use `ai-plan` with `ai-domain-modeling` active and follow Plan-backed ticket planning.
+4. Record the resolution: for a Plan-backed grilling ticket, retain its Ticket type and Question and use the **Entity Create And Edit** recipe to update only `## Resolution` with the concise Plan link. For other tickets, use that recipe to replace the ticket body with its completed `## Resolution`. Run the **Entity State And Structure** recipe to set the ticket status to `done`, and append a title-and-reference link with a one-line gist to the map's Decisions-so-far.
+5. Add newly surfaced tickets with the **Entity Create And Edit** recipe, then link them with the **Entity Relations** recipe; graduate any fog that the answer made specific. Remove each graduated patch from **Not yet specified** so it exists only in its new ticket. If the answer shows that a ticket sits beyond the destination, **rule it out of scope** instead of resolving it on the route. If the decision invalidates other map parts, update or delete those tickets. When no open tickets or in-scope fog remain, run the **Entity State And Structure** recipe to set the map status to `done`.
+
+The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.

package/skills/recipes/README.md

@@ -0,0 +1,29 @@
+# Record Body Recipe Catalog
+
+Use the recipe for the record that you create or edit.
+
+## Shared Rules
+
+- Keep typed facts outside body prose. Typed facts include status, parentage, timestamps, revisions, and references.
+- Keep graph relations outside body prose.
+- Keep committed user stories in child `userStory` entities. Do not duplicate them in a PRD body.
+- Use `<angle brackets>` for authored placeholders. Replace them with authored content before you save the body.
+- Use `Not derived from tracker metadata.` only in generated bodies when tracker metadata cannot supply content. Do not use it as an authored placeholder.
+
+## Recipes
+
+- [Context Summary](./context-summary.md)
+- [Context Term](./context-term.md)
+- [Project](./project.md)
+- [Epic](./epic.md)
+- [Version](./version.md)
+- [Initiative](./initiative.md)
+- [PRD](./prd.md)
+- [User Story](./user-story.md)
+- [Issue](./issue.md)
+- [Debt](./debt.md)
+- [ADR](./adr.md)
+- [Handoff](./handoff.md)
+- [Issue Comment](./issue-comment.md)
+- [Wayfinder Map](./wayfinder-map.md)
+- [Wayfinder Ticket](./wayfinder-ticket.md)

package/skills/recipes/adr.md

@@ -0,0 +1,21 @@
+# ADR Recipe
+
+Use this recipe for an architecture decision record body.
+
+```markdown
+## Status
+
+<Accepted | Superseded | Archived>
+
+## Context
+
+<The decision context and constraints.>
+
+## Decision
+
+<The decision that this ADR records.>
+
+## Consequences
+
+- <A result of this decision.>
+```

package/skills/recipes/context-summary.md

@@ -0,0 +1,17 @@
+# Context Summary Recipe
+
+Use this recipe for an initiative-scoped context summary.
+
+```markdown
+## Purpose
+
+<The shared domain purpose for this scope.>
+
+## Boundaries
+
+- <A durable scope boundary.>
+
+## Working Agreements
+
+- <A shared rule that applies to work in this scope.>
+```

package/skills/recipes/context-term.md

@@ -0,0 +1,3 @@
+A context term is a compact definition. Do not use section headings.
+
+`<Term>`: <A concise definition that gives the term one stable meaning in its scoped context.>

package/skills/recipes/debt.md

@@ -0,0 +1,21 @@
+# Debt Recipe
+
+Use this recipe for a debt record body. Keep category, priority, lifecycle, ownership, resolver links, and context links in typed fields and graph relations.
+
+```markdown
+## Description
+
+<The accepted cost or risk that this record describes.>
+
+## Impact
+
+<The effect if this debt remains open.>
+
+## Evidence
+
+<The facts that support this debt record.>
+
+## Suggested Remediation
+
+<A possible way to reduce or remove the debt.>
+```