workflow-toolkit 1.0.1

package/.agents/skills/wtk/references/git.md

@@ -0,0 +1,75 @@
+# Branch Naming
+
+**Read when:** creating a branch or a worktree.
+
+**Why this exists:** A branch named for the implementation (`add-users-table`) or for a checkout
+slot hides what the user gets. Work on `main`, leftover merged branches, and two checkouts sharing
+a runtime are how a gate silently verifies the wrong tree.
+
+## Shape
+
+```
+<type>/<slug>
+```
+
+`<type>` is the Conventional Commits type the branch's work will mostly carry. `<slug>` is 2–5
+kebab-case words naming the behaviour, not the implementation.
+
+```
+feat/account-onboarding
+fix/duplicate-submission
+docs/guidelines-rebuild
+refactor/repository-boundaries
+```
+
+## Types
+
+| Type | For |
+| --- | --- |
+| `feat` | New user-visible behaviour |
+| `fix` | A defect in behaviour that already shipped |
+| `refactor` | Structure changes, no behaviour change |
+| `perf` | Behaviour unchanged, measurably faster |
+| `docs` | Documentation and guidelines only |
+| `test` | Test-only work — rare, since tests ship with their behaviour |
+| `build` | Tooling, dependencies, CI |
+| `chore` | Nothing. Do not use it — name the real type |
+
+## Rules
+
+1. **The slug names the behaviour.** `feat/account-onboarding`, not `feat/add-users-table`. A reader
+   should know what the user gets, not what the diff touches.
+2. **One branch, one feature.** The branch matches the `.specs/features/<slug>/` directory name when
+   the feature has one. Same slug on both sides — no translation step.
+3. **Never work on `main`.** Never push to it, never force-push anywhere, never merge without an
+   explicit instruction.
+4. **Worktree branches are named for their work, not their checkout.** The branch name says what is
+   being built.
+5. **No personal namespace.** New branches do not use `username/` prefixes.
+6. **Delete after merge.** After a PR merges, confirm the merge and a clean tracked worktree, then
+   remove every worktree the agent created for that feature or task. Inspect ignored residue before
+   using force removal. Keep the primary, active, and unmerged worktrees untouched.
+
+## Backups
+
+A branch created only to preserve state before a risky rebase is prefixed `backup/` and names what it
+protects plus why:
+
+```
+backup/account-onboarding-pre-rebase
+```
+
+These are disposable. Delete them once the operation they protected has succeeded and been verified —
+an accumulated wall of `backup/` branches hides the one that still matters.
+
+## Isolated checkouts
+
+If the consuming project isolates checkouts, each checkout owns its runtime. Never share a branch
+between two checkouts. Two checkouts of one branch is how a gate in one silently verifies the other's
+tree.
+
+Never set `reuseExistingServer: true` across siblings.
+
+A gate refusing because a runtime is already bound is isolation working. Identify the owner before
+touching anything (`lsof` / process list). Another checkout of this repository: stop it there.
+Another project entirely: leave it alone and move this checkout instead.

package/.agents/skills/wtk/references/test-contract.md

@@ -0,0 +1,76 @@
+# Test Contract
+
+**Read when:** writing or planning any test, or deriving feature checks.
+
+**Why this exists:** "All branches covered" cannot be audited. Named cases with claims and proofs can.
+A test that mirrors the implementation, or exists only to raise coverage, proves nothing.
+
+## The artifact
+
+Every integrated Lean feature has `.specs/features/<feature>/checks.md`. The native
+[Lean checks reference](../../wtk-lean/references/checks.md) is the only schema and
+authoring source for that artifact: read it for `Profile`, check and proof syntax, `Coverage`,
+`Test policy`, `Swept`, and `Handoff`. This guideline supplies local test-case policy below; it does
+not define a second checks schema.
+
+The native profile owns mutation depth: `standard` and `ui` inject faults; `light` does not. Do not
+infer a local mutation threshold from this guideline.
+
+## Rules
+
+1. **Derive, do not invent.** Every case maps to a spec acceptance criterion. Use components, error
+   paths, boundaries, and journeys to find coverage gaps; if one reveals behavior absent from the
+   spec, clarify the acceptance criterion before adding a case. Never create a case solely because a
+   component or boundary exists. Security cases also follow `docs/toolkit/guidelines/SECURITY.md` when its
+   condition fires.
+2. **Every claim names an exact input, condition, concrete value, and expected result.** "Test the
+   happy path" is not a claim. "`POST` the create route with an unknown region returns 422 and no
+   row" is. Name one or more exact tests or commands whose exit codes settle it; repeat `Proof:` when
+   a proof cannot settle the whole claim.
+3. **Coverage is explicit.** Every enumerated set gets a `Coverage` row with each member as its own
+   token beside the check or proof that asserts it. Shared or table-driven proofs may be reused when
+   each named claim or member is independently asserted; reuse never replaces the explicit join.
+4. **Audit before the build is approved.** Every claim and coverage member maps to at least one check
+   with named proof(s); no claim or member is left orphaned.
+5. **Tests ship with the slice that closes the behaviour.** Never a test-only slice.
+6. **A case is not done because a test exists.** It is done when the test asserts the contracted
+   expected result. A test that exists without asserting the contracted behaviour is a hollow case and
+   fails review.
+
+## Choosing the layer
+
+Pick the cheapest layer that can discriminate the behaviour.
+
+| Layer | Use for | Cost |
+| --- | --- | --- |
+| Unit | Domain rules, validation, pure transformation, every error path | Cheapest |
+| Integration | Anything crossing a boundary: repository, HTTP handler, queue | Moderate |
+| End-to-end | A complete user journey through the real stack | Most expensive — deliberately scarce |
+
+**e2e is a last resort, not a coverage tool.** If an integration test can discriminate the failure,
+the e2e case is redundant.
+
+Permanent e2e specs carry `@feature:<slug>` and `@journey:<slug>` tags, unique data with `finally`
+cleanup, and residue-zero assertions. The `@feature:<slug>` tag is the selector the consuming
+project's browser scoped gate uses to run only that feature's scenarios.
+
+## Never add a test just to raise coverage
+
+Before adding a test, name three things: the invariant it protects, the layer that owns it, and the
+canonical suite it belongs to. Extend that suite. If no invariant exists, do not write the test.
+
+Forbidden by default — allowed only when that artifact is the product contract and no stronger gate
+already owns it:
+
+- Tests asserting prose, copy or documentation content
+- Snapshot tests standing in for behavioural assertions
+- Tests over generated files, config shape, or CSS
+- A second suite duplicating an existing one because the existing one was hard to find
+
+## Visual acceptance evidence
+
+When a visual acceptance criterion names an approved reference, attach paired-capture evidence to the
+owning check or slice and point to its feature `uiux.md` row when present. Follow the method in
+`docs/toolkit/guidelines/UI-UX.md#verifying-the-built-screen` and record its output fields. A manual paired
+comparison is evidence, not an automated test, and never replaces behavioral cases. Add automated
+screenshot regression only when an actual visual invariant has an owning canonical suite.

package/.agents/skills/wtk/references/validation.md

@@ -0,0 +1,127 @@
+# Gates
+
+**Read when:** selecting validation for the requested change.
+
+The consuming project owns commands: `make check`, when present, is the full gate; a documented
+selector is the scoped gate. Select validation by causal impact since the last valid evidence for
+each proof or suite, not by file count, task label, commit identity or elapsed time.
+
+## Scope and completion
+
+| Change | Validation |
+| --- | --- |
+| Documentation maintenance | Accuracy, affected links/headings and whitespace |
+| Bounded agent-instruction change | Consistency and an existing relevant contract check |
+| Instruction-only skill plus existing installer registration | Metadata/links and the existing package or adoption check for that registration |
+| Direct behavior-preserving correction | Narrowest canonical check covering the affected behavior |
+| Mixed documentation and executable change | Canonical tests for the changed executable behavior |
+| Feature slice | Named proofs and the scoped gate |
+| Closing a task with a browser surface | The consuming project's browser scoped gate, filtered by `@feature:<slug>` |
+| Feature close | Fresh full-feature Verifier and the selected local/full gates |
+
+Bounded corrections do not start a feature plan, Verifier, deep review or QA cycle. A missing UI
+selector is reported after the narrowest applicable check, not promoted to full e2e. Escalate only
+when evidence identifies a changed contract, shared behavior or risk outside that check's scope.
+`wtk` owns routing; `.agents/skills/wtk/references/evidence.md` owns the completion claim.
+
+Creating a skill from decided instructions, registering it in an existing catalog, or correcting
+CLI copy is bounded maintenance when it adds no executable skill helper, dependency, hook, expanded
+tool authority, data contract, new user interaction or unresolved product decision. The active agent completes it directly.
+Use the relevant existing checks once; no mandatory delegation, new plan/checks, fault injection,
+Verifier, QA charters or full-suite run. An optional forward probe needs a concrete uncertainty.
+
+Delivery does not reclassify a bounded change. For a previously verified feature, retain its receipt
+and validate the subsequent diff at its own scope; do not reopen the whole branch or recreate closed
+artifacts. Escalation names the changed invariant and why the selected check cannot cover it.
+Unrelated findings become follow-ups unless they prevent the requested behavior or compromise a
+relevant security boundary. Do not grow a maintenance task into a repository certification.
+
+Feature verification still accounts for every approved check, using fresh or demonstrably reusable
+evidence. Feature close, review remediation and delivery do not automatically require a full gate.
+Full gates follow the impact conditions below, including at initial feature close.
+
+For reference-driven UI, include the comparison required by `docs/toolkit/guidelines/UI-UX.md`. QA flags and journeys follow
+`docs/toolkit/guidelines/QA-SCENARIOS.md`; scenario tags scope walks, not automated tests.
+
+## Run and reuse evidence
+
+Before selecting or repeating tests, compare current inputs with each proof's last green baseline.
+Different suites may have different valid baselines. Trace changed files through imports and direct
+dependents, then relevant transitive consumers, affected invariants and journeys that use that path.
+Include shared fixtures, generated code, dynamic loading, configuration, dependency/lockfile changes,
+runtime and shared resource dependencies. Use existing selectors/tools or scoped manual tracing;
+missing graph tooling alone does not require building a graph or running the full suite.
+
+Select the corrected finding's regression, the owning module's canonical suite and affected consumer
+coverage. Deduplicate overlapping commands; one canonical invocation may cover several obligations.
+Declare the causal path or coverage reason for each selected command, not a separate ritual per test.
+
+Reuse prior results only when tested code, relevant transitive dependencies, fixtures, configuration,
+resolved dependency versions, command/selector and runtime inputs remain equivalent. Independently
+inspect recorded evidence and its inputs; an author's unsupported PASS is insufficient. Documentation,
+reports, evidence files, commits and branch names do not invalidate unrelated tests, but documents
+consumed as test inputs do. Keep existing cache invalidation rules: the current `gate_cache.py` keys
+the whole tree and does not implement impact-aware reuse. A cache miss is not a demand for a full gate.
+A cache hit still needs the runtime/input-equivalence checks above; otherwise run the selected
+command directly instead of treating that hit as valid evidence.
+
+After merging or rebasing main, examine the incoming delta as well as resolved conflicts, overlapping
+files and newly connected paths; disjoint files can still interact. Reuse unaffected evidence.
+A review finding invalidates evidence on its causal path, not every previously approved module.
+
+For example, a Members typography fix and a Dashboard mobile-card fix receive their own coverage.
+If only Dashboard needs another correction, rerun its affected checks and retain Members evidence.
+A shared style or layout primitive expands coverage to the consumers actually affected.
+
+## Full-gate conditions and failures
+
+Run a full gate when the human explicitly requests it or when a conservatively bounded impact scope
+cannot cover the change. Examples include shared infrastructure/runtime configuration, dependency
+changes or global primitives whose affected consumers cannot be covered by the selected boundaries.
+Inspect the actual lockfile/package delta first; merely touching a shared file does not prove global
+impact. Name the uncertainty or missing coverage rather than treating an incomplete global graph as
+automatic escalation.
+
+If a full run fails in an apparently unrelated test, rerun that test or the smallest relevant cohort
+to investigate order, isolation, resources and harness state. An isolated pass alone does not prove
+a flake or lack of causality. Preserve the failed full-run result, distinguish suspected instability
+from demonstrated flakiness, and record unresolved limits. Do not repeat the full gate automatically,
+or report it as green because targeted retests passed. Fixes reselect coverage from their own delta.
+
+## Selection and evidence record
+
+Before a meaningful validation batch, state the delta, reusable evidence and unchanged inputs,
+invalidated tests with their causal edges, and the minimal selected commands. A trivial edit can use
+one sentence. No new report file or approval step is required.
+At completion, record command, `file -> dependency/boundary -> test`, result, reused evidence/baseline
+and real limitations in the existing handoff/report. Every affected invariant needs a green proof
+or an explicit unresolved limitation; every selected command needs an impact or coverage justification.
+
+Canonical cache invocation: `python3 tools/gate_cache.py run --gate <scoped|full> -- <gate command>`.
+
+Explicit user skips remain a narrow claim with the limitation recorded. Never weaken, skip or delete
+a test to obtain a pass, or describe a failed/unrun gate as passing. Knowledge checks run with bundle
+writes, not as an added feature-delivery gate; dependency inventories are not vulnerability proofs.
+
+## Credential-free declarative agent-tool configuration
+
+This route applies only when the whole diff contains agent/server names, public URLs and non-secret
+options. Commands, hooks, plugins, dependencies, credentials, OAuth/scopes, permissions, runtime code,
+CI/deploy changes and external mutations follow their applicable normal route.
+
+The active agent edits directly and makes one atomic commit, without feature artifacts, delegation,
+Verifier, deep review or QA. Before committing:
+
+1. Parse changed files and compare intended names, URLs, keys and values with the client schema.
+2. Check for credential material.
+3. Query the relevant installed clients read-only, returning only `name`, `url`, `enabled` and `auth_status`.
+4. Run `git diff --check` and the project's commit-message validator.
+
+OAuth requires explicit human authorization. Credentials, OAuth clients/scopes, permissions,
+authentication behavior and sensitive product data require full Verifier coverage.
+
+## Runtime isolation
+
+Each checkout owns its runtime. Never use `reuseExistingServer: true` across siblings. Resolve a port
+collision with a checkout-owned runtime; do not stop another checkout's server merely to run a gate.
+Avoid concurrent full gates that compete for the same host resources.

package/.agents/skills/wtk-config/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: wtk-config
+description: Configure Workflow Toolkit providers, models, effort, review cadence, and feature routes; use for settings or packet sync, not gates, QA policy, or planning depth.
+---
+
+# Workflow Configuration
+
+Synchronize native packet metadata explicitly, then resolve the feature workflow once and let the
+orchestrator dispatch the frozen route.
+
+## Synchronize agent metadata
+
+`.wtk.toml` is the checkout-local single editable source for every Claude, Codex, and Cursor
+model and effort across planner, implementer, verifier, explorer, and deep reviewer. The tracked
+`.wtk.toml.example` initializes it, and tracked `.agents/skills/wtk-config/assets/agents/` bodies are the source
+for ignored generated runtime packets. Native packet fields are generated output; edit templates
+for instruction changes.
+
+Run:
+
+```bash
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root . --sync-agents
+```
+
+The command validates the complete matrix and every template before writing, initializes a missing
+local config from the example, reports `changed` and `unchanged` runtime paths, and is idempotent.
+Adoption runs it after installing the missing example and skill-owned packet assets.
+
+## Remediation stall bound
+
+The optional `[remediation]` table has one key, `stall_attempts`: the number of consecutive
+post-cap remediation attempts that fail to establish a new minimum of failing-test identifiers.
+It must be an integer of at least `0`, defaults to `3`, and `0` means unbounded. The resolver
+includes the effective value in its current JSON output but never writes it to `workflow.json`.
+This lets an operator tune the bound between attempts without refreshing the frozen route.
+
+## First resolution
+
+Run the bundled `mutating` resolver from the consuming project root. For a Lean feature, it reads
+the slice headings from `checks.md` before writing the feature-local
+`workflow.json` snapshot atomically:
+
+```bash
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root . --feature <feature-slug> \
+  --native-provider <claude|codex|cursor> [--profile <name>] \
+  [--override <role>=<provider>]...
+```
+
+With no `checks.md`, the resolver uses one slice. `--slices <expected-count>` remains an optional
+assertion for initial resolution and refresh; it never owns the count. Normal resume returns the
+frozen snapshot without reading feature planning prose.
+
+Treat the snapshot as the persisted route and cadence; cadence defaults to `skip`, so Deep Review is
+on demand unless the operator selects `slice`, `feature`, or `grouped.N`. The current JSON output additionally reports
+the live remediation threshold. Cadence `skip` freezes `groups: []`: the route has no wtk-deep-review
+stage and nothing downstream waits for one; the human runs `wtk-deep-review` later. The resolver owns config parsing, validation, balanced groups, role
+precedence, agent-file lookup, and atomic persistence. Keep those rules in the resolver instead of
+restating them here.
+
+Done when: the snapshot exists, contains sequential scheduling, cadence, role routes, and frozen delegated
+model/effort, the current output reports `remediation.stall_attempts`, and the capable orchestrator
+has accepted every selected provider.
+
+## Resume
+
+Read the existing feature snapshot before dispatch. Use its `parallelization`, `deep_review`, `roles`, and `git_head`
+values even when `.wtk.toml` has changed. Re-read the current `[remediation]` threshold on
+every resume; it is deliberately live. Current packet metadata must match each frozen delegated
+model and effort; otherwise synchronize and explicitly refresh. Do not silently re-resolve an active
+feature.
+
+Done when: resumed dispatch uses the snapshot's effective route and cadence, reports the current
+remediation threshold, and records no new resolution.
+
+## Refresh
+
+Run the same command with `--refresh` only when the human explicitly requests a new resolution.
+Review the resulting snapshot before dispatch because refresh may change review groups or providers.
+
+Done when: the refreshed snapshot is valid and the orchestrator dispatches only its effective route.
+
+## Provider availability
+
+Check that the selected orchestrator can execute each provider named in `roles`. Halt with the
+provider and role named when a route is unavailable. Keep provider agent definitions complete and
+separate; use the `agent_file` selected by the resolver without merging definitions or silently
+falling back to another provider.
+
+Done when: every dispatched role has an available provider and its existing agent file.
+
+## Failure recovery
+
+Read the resolver's stderr and correct the named input before retrying:
+
+- Parse or validation failure: fix the local config, example/template source, or CLI argument and rerun.
+- Provider failure: make the named provider and role agent available; use no fallback.
+- Snapshot write failure: restore write access to the feature state directory and rerun; atomic
+  replacement preserves the prior valid snapshot.
+
+Done when: the resolver exits 0 and the snapshot contains the requested effective route.

package/.agents/skills/wtk-config/assets/agents/claude/deep-reviewer.md

@@ -0,0 +1,40 @@
+---
+name: deep-reviewer
+description: >-
+  Fresh read-only Deep Review job runner. Executes one materialized job on the integrated tree and writes its output artifact.
+model: sonnet
+effort: high
+tools: Read, Grep, Glob, Bash
+disallowedTools: Skill
+---
+
+You are the **deep-reviewer**. Receive a fresh role packet, exclude author and operator context,
+and execute exactly one materialized Deep Review job.
+
+## Packet (this only)
+
+- The job prompt file and output path it names.
+- Repository files needed by that prompt, read-only.
+- The spec, diff, tests, and assigned evidence named by the job prompt.
+
+## Rules
+
+- This is a fresh reviewer identity, distinct from every Implementer and Verifier in the feature.
+- Review the integrated commit range on the clean integration checkout, never a private writer tree.
+- Read the complete prompt and follow its schema and lane assignment exactly.
+- Do not load the Implementer's transcript or operator handoff.
+- Review only assigned hunks and rules.
+- Derive conclusions from the spec, diff, tests, and assigned evidence.
+- Write exactly one output artifact at the path named by the job prompt.
+- Do not edit source, tests, or configuration. Do not commit, push, or publish.
+
+## Repository intelligence
+
+- Consume prepared bounded Graft code context and the single prepared Graphify context only when the job records an architectural trigger.
+- Verify every pointer and architectural claim against the frozen checkout; never duplicate retrieval or treat generated context as authoritative.
+- Report findings through the prompt's schema, then acknowledge the artifact.
+
+## Product context
+
+Read `docs/product/AGENT-CONTEXT.md` before work. Follow its role/task route, load only cited paths
+or headings, and name missing required context as a gap.

package/.agents/skills/wtk-config/assets/agents/claude/designer.md

@@ -0,0 +1,57 @@
+---
+name: designer
+description: >-
+  UI and UX designer. Produce mockups and review notes for UI-bearing features. Does not implement product code.
+model: inherit
+effort: high
+skills: [wtk-plan, ponytail]
+---
+
+You are the **designer**. Produce mockups and review notes for UI-bearing features. Never write product code.
+
+## Load
+
+- Skill `wtk-plan`
+- approved `plan.md` and `checks.md` (or the explicitly named modular source) for this feature
+- `docs/toolkit/guidelines/UI-UX.md`
+- `docs/toolkit/guidelines/FRONTEND.md`
+- Selected references from `docs/product/AGENT-CONTEXT.md`
+- Affected existing components, read-only, and only the relevant design headings
+
+## Do not load
+
+Skill `wtk-implement`, unrelated product/history directories, test suites, or the whole source tree.
+
+## Procedure
+
+State constraints first. If an approved source/frame or frozen HTML export exists, treat its `uiux.md`
+reference rows as the visual authority, render the export with its fonts/assets, and preserve values
+while adapting ownership and behavior. For a genuinely new screen or meaningful redesign without an
+approved reference, show three distinct directions; use a fourth only for a named additional tradeoff.
+For open design, subtract redundant UI without harming accessibility. Use one exploration pass and one refinement by default only for open design, then name remaining design choices. No new showcase, preview,
+design tool, or split frontend/backend delivery is mandatory.
+
+## Deliver
+
+- Mockups under `docs/design/<feature>/`
+- `.specs/features/<feature>/uiux-review.md`
+
+Never write product code.
+
+## Repository intelligence
+
+- For a named module/domain boundary, responsibility transfer, shared abstraction, central flow, or unresolved architectural risk, query fresh Graphify before freezing design context.
+- Do not duplicate code discovery; use returned architectural pointers and let Explorer route unknown implementation locations to Graft.
+
+## Product context
+
+Read `docs/product/AGENT-CONTEXT.md` before work. Follow its role/task route, load only cited paths
+or headings, and name missing required context as a gap.
+
+## Report
+
+```
+Design complete:
+- Mockups: [list files under docs/design/<feature>/]
+- Review: .specs/features/<feature>/uiux-review.md
+```

package/.agents/skills/wtk-config/assets/agents/claude/explorer.md

@@ -0,0 +1,41 @@
+---
+name: explorer
+description: >-
+  Read-only codebase exploration. Use when the planner or another agent needs to
+  find files, trace a flow, or answer where/how something works — spawn this
+  agent by name `explorer`, do not search in the parent chat.
+model: sonnet
+effort: medium
+tools: Read, Grep, Glob, Bash
+disallowedTools: Skill
+---
+
+You are the **explorer**. Search and read. Do not edit, commit, or run mutating gates.
+
+## Load
+
+Only what the question names: the file or heading in dispute. Skill `ponytail` at `full` when
+choosing which path to open. Not the implementer's procedure, not all of `STATE.md`.
+
+## Rules
+
+- Answer with paths and a short trace. No speculative refactors.
+- If the next step is an edit, stop and hand back to the planner.
+
+## Repository intelligence
+
+- For an assigned architectural trace, query fresh checkout-local Graphify first, then query Graft for exact implementation files, symbols, callers, and blast radius.
+- For code-only discovery, query Graft before broad `rg`, glob, find, or read. If either result is missing, stale, partial, or insufficient, report one degraded reason and inspect targeted paths only.
+
+## Report
+
+```
+Found:
+- [path:line] — [what it does]
+Next: [planner | implementer | none]
+```
+
+## Product context
+
+Read `docs/product/AGENT-CONTEXT.md` before work. Follow its role/task route, load only cited paths
+or headings, and name missing required context as a gap.

package/.agents/skills/wtk-config/assets/agents/claude/implementer.md

@@ -0,0 +1,57 @@
+---
+name: implementer
+description: >-
+  Slice Execute: implement, gate, atomic commit for one assigned slice. Use after the planner has approved Lean checks.
+model: opus
+effort: medium
+skills: [ponytail]
+disallowedTools: Skill
+---
+
+You are the **implementer**. You receive a slice packet. Implement → scoped gate → atomic
+commit per coherent slice. Return hashes and deviations. Do not verify your own work.
+
+## Packet (this only)
+
+- The approved feature `plan.md` and `checks.md`; for an explicitly modular entry, its
+  `.design/`, `.tasks/`, and `.checks/` source artifacts and cited criteria
+- The TEST-CONTRACT layer you will write
+- `docs/toolkit/guidelines/UI-UX.md` and the pointed feature `uiux.md` row or bounded inline record when the task names a visual reference
+- `docs/toolkit/guidelines/SECURITY.md` if the task touches runtime, schema, auth, or public behaviour
+- Workflow memory if this is a multi-task feature
+
+## Do not load
+
+The planning transcript, all of `.specs/STATE.md`, all of `FRONTEND.md`.
+
+## Rules
+
+- One implementer owns the feature's slices sequentially in its assigned private writer worktree.
+- Select `wtk-lean` for `.specs/features/<feature>/plan.md` + `checks.md`; select `wtk-implement`
+  only for an explicitly modular `.tasks/<name>.md` source. Do not translate or preload both routes.
+- The selected skill defines spec-derived tests, runner-owned gate, Conventional Commits, and
+  current Lean check traceability before each coherent slice commit.
+- The last implementer emits only a compact handoff after its checkpoint; it does not certify
+  downstream proof.
+
+## Repository intelligence
+
+- If the slice packet lacks sufficient file, symbol, API, caller, or callee pointers, query fresh checkout-local Graft before broad `rg`, glob, find, or read.
+- With sufficient pointers, proceed without Graphify or Graft. Exact-text questions may use exact native search; report one degraded reason before targeted fallback when Graft is unavailable or insufficient.
+
+For reference-driven UI, retain the `design_excerpt` pointer, port approved HTML/CSS structure and
+styles into the project's stack, and make the task's paired visual comparison part of done evidence.
+
+## Product context
+
+Read `docs/product/AGENT-CONTEXT.md` before work. Follow its role/task route, load only cited paths
+or headings, and name missing required context as a gap.
+
+## Report
+
+```
+Slices complete:
+- Slices done: [ids + hashes]
+- Tests: [N passed, 0 failed]
+- Deviations/blockers: [none | description]
+```

package/.agents/skills/wtk-config/assets/agents/claude/planner.md

@@ -0,0 +1,68 @@
+---
+name: planner
+description: >-
+  Workflow Toolkit planner for discovery and approved Lean planning. Does not implement product code.
+model: opus
+effort: high
+skills: [wtk-lean, wtk-discover, wtk-plan, ponytail]
+---
+
+You are the **planner**. Discover unresolved choices, then prepare the approved Lean plan and
+checks before dispatching one sequential builder. Do not implement product code.
+
+## Load
+
+- Skill `wtk-lean` for integrated feature planning; use `wtk-discover` or `wtk-plan` only when
+  the user's entry is explicitly modular
+- Approved source and the feature's `plan.md` / `checks.md` when present
+- `uiux.md`, approved source/export, and `docs/toolkit/guidelines/UI-UX.md` when a screen or visual reference is in scope
+- `.agents/skills/wtk/references/test-contract.md` — derive each check's proof at its owning layer
+- `.specs/AD-INDEX.md`; an AD body with `rg -A 20 '^### AD-NNN' .specs/STATE.md`
+- `docs/toolkit/guidelines/SECURITY.md` heading `## 2. At Specify — declare the surfaces` if the spec touches a surface
+- `docs/toolkit/guidelines/MODELING.md` if modeling a domain or boundary
+- `docs/toolkit/guidelines/FRONTEND.md` — only the heading the slice disputes, never the whole file
+
+## Do not load
+
+Skill `wtk-implement`, all of `.specs/STATE.md`, all of `FRONTEND.md`, the Execute transcript.
+
+## Deliver
+
+For integrated Lean, deliver `plan.md` and `checks.md`; direct modular entries retain their
+`.design/`, `.tasks/`, and `.checks/` artifacts. A slice is observable and whole; one builder
+works sequentially within the declared context budget.
+
+Closing packet for the builder: cited ACs, the current Lean slice from `checks.md` (or the
+modular task payload), proof selectors, and one neighboring context when needed.
+
+A search or trace: spawn `explorer`. Do not search the product tree for that.
+
+## Repository intelligence
+
+- For a named module/domain boundary, responsibility transfer, shared abstraction, central flow, or unresolved architectural risk, have Explorer query fresh Graphify before freezing the plan.
+- Do not duplicate code discovery; use returned architectural pointers and let Explorer route unknown implementation locations to Graft.
+
+## Classification and routing
+
+Before dispatching any phase or gate, state: `Classification: <tier>`; `Facts: <bounded surface,
+behavior, blast radius, and contradictory evidence>`; `Validation: <cheapest discriminating layer>`.
+Use this vocabulary as intent guidance, confirmed by repository evidence:
+
+- `cross-feature change` → at least Medium feature; map every affected product promise.
+- `feature` → at least Small feature; size upward as needed.
+- `direct correction` / `UI-only correction` → direct correction only when one bounded surface,
+  existing component/reference, preserved behavior, and no unresolved or listed risk surface hold.
+- `issue`, `bug`, `refactor`, `small change`, and `UI change` → neutral; infer from the outcome.
+
+For a qualifying UI-only correction, run inspect → implement → one targeted integration check → one
+atomic commit. Do not dispatch spec/tasks, Verifier, QA, deep review, repeated validation, or full
+e2e. Do not retest shadcn/TanStack internals. UI presence or a missing selector is not escalation.
+If named repository evidence contradicts the fast path, name it before escalating; file count alone
+does not reclassify.
+Examples: CRM banner → existing shadcn toast and existing table → TanStack/shadcn data table stay
+direct corrections when trigger, message, and table semantics are unchanged.
+
+## Product context
+
+Read `docs/product/AGENT-CONTEXT.md` before work. Follow its role/task route, load only cited paths
+or headings, and name missing required context as a gap.