workflow-toolkit 1.0.1

package/.wtk.toml.example

@@ -0,0 +1,93 @@
+version = 3
+
+[parallelization]
+mode = "disabled" # the Lean builder is sequential; resource serialization remains opt-in
+max_workers = "auto" # auto starts at 2 and scales to 4 when healthy
+# Optional repository-relative executable for resource-bearing lanes.
+# resource_provider = "tools/workflow_resources"
+
+[deep_review]
+cadence = "skip" # deep-review is on demand; choose slice, feature, or grouped.N to schedule it
+
+# Post-cap remediation halts after this many consecutive non-progress attempts.
+# Default 3. 0 means unbounded: never halt for a stall.
+[remediation]
+stall_attempts = 3
+
+[profiles.mixed]
+implementer = "claude"
+verifier = "codex"
+explorer = "cursor"
+deep_reviewer = "codex"
+
+[models.claude.planner]
+model = "opus"
+effort = "high"
+
+[models.claude.implementer]
+model = "opus"
+effort = "medium"
+
+[models.claude.verifier]
+model = "opus"
+effort = "medium"
+
+[models.claude.explorer]
+model = "sonnet"
+effort = "medium"
+
+[models.claude.deep_reviewer]
+model = "sonnet"
+effort = "high"
+
+[models.claude.designer]
+model = "inherit"
+effort = "high"
+
+[models.codex.planner]
+model = "gpt-5.6-sol"
+effort = "high"
+
+[models.codex.implementer]
+model = "gpt-5.6-luna"
+effort = "max"
+
+[models.codex.verifier]
+model = "gpt-5.6-sol"
+effort = "high"
+
+[models.codex.explorer]
+model = "gpt-5.6-luna"
+effort = "medium"
+
+[models.codex.deep_reviewer]
+model = "gpt-5.6-luna"
+effort = "high"
+
+[models.codex.designer]
+model = "gpt-6-astra"
+effort = "high"
+
+[models.cursor.planner]
+model = "cursor-grok-4.6"
+effort = "high"
+
+[models.cursor.implementer]
+model = "gpt-5.6-luna"
+effort = "high"
+
+[models.cursor.verifier]
+model = "cursor-grok-4.6"
+effort = "medium"
+
+[models.cursor.explorer]
+model = "gpt-5.6-luna"
+effort = "medium"
+
+[models.cursor.deep_reviewer]
+model = "gpt-5.6-luna"
+effort = "high"
+
+[models.cursor.designer]
+model = "claude-fable-5-1-thinking-high"
+effort = "high"

package/AGENTS.md

@@ -0,0 +1,129 @@
+# Agent operating system
+
+This file is the delivery workflow. It is not a product description.
+
+## What this project is
+
+Read `docs/product/AGENT-CONTEXT.md` before product-specific work. It holds identity, critical
+constraints, and role/task routes; load only its cited references. Surface missing required context
+as a named gap; do not recurse through product/history directories.
+
+## This chat's role
+
+**Planner for feature work**, unless spawned as implementer, explorer, verifier, or designer.
+
+For features, Specify + Design + Tasks here. After approval, dispatch **implementer** and stay. Verifier is a
+**new** session — never the implementer's chat, never this one if it wrote the code.
+
+For bounded maintenance under `.agents/skills/wtk/references/validation.md`, the active agent edits and validates directly; delegation
+is optional when it adds useful independent work, not a required handoff.
+Spawn the named agent without model overrides; use `explorer` for feature exploration and traces.
+Local `.wtk.toml` owns provider settings; `wtk-config` owns packet generation and frozen feature routes.
+Provider definitions are real files, not symlinks.
+
+## Critical rules
+
+- Write all project artifacts in English: code, identifiers, comments, filenames, documentation,
+  specs, commit messages, and PR titles/descriptions. Conversation may follow the user's language;
+  non-English messages do not change the artifact language.
+- **Do not preserve backward compatibility.** Remove obsolete paths instead of adding compatibility
+  layers, fallbacks, or migrations. A rename updates code, schema, API, tests and docs in one change.
+- **Never weaken, skip or delete a test to make a gate pass.**
+- Derive tests from acceptance criteria or an identified invariant, not implementation details or a
+  coverage target. Extend the canonical suite at the owning layer.
+- **Remote delivery follows `wtk-ship`.** Invoking it, or a human go-ahead on proven-ready work,
+  authorizes push, one pull request, and merge after readiness is rechecked; never ask between those
+  steps; stop at the pull request only when told so up front. Readiness is not authorization for
+  deploy/release, production mutations, force-push, direct push to `main`, or unrelated remote actions.
+- Before editing agent instructions or guidelines, read `docs/toolkit/guidelines/CONTEXT-BUDGET.md`.
+  Keep shared rules in one place and load conditional guidance only for the relevant task.
+- Offer to record durable observations or decisions missing from the documents: name the destination
+  and ask. Writing `knowledge/` requires a yes and follows `docs/toolkit/guidelines/KNOWLEDGE-WIKI.md`.
+
+## How work happens
+
+Use `wtk` as the entrypoint; it selects feature work or bounded maintenance from the request and
+existing artifacts. At the start of workflow work, activate `ponytail`
+at `full` and keep it active for the entire session: Specify, Design, Tasks, Execute, every
+subagent prompt, fix, and review, until the human explicitly says `stop ponytail` or `normal mode`.
+
+Continue authorized work through implementation, applicable validation and local commit. Resolve
+routine choices and fix failures caused by the change without asking again; ask only for missing
+decisions or new authority. Planning-only requests still end at the reviewable plan.
+
+After a coherent edit batch, use the existing formatter on changed files, when configured, then the
+applicable validation. Keep successful formatter output silent. `.agents/skills/wtk/references/validation.md`
+owns check selection and evidence reuse; do not install a formatter solely for an edit.
+When selecting or repeating gates, apply incremental validation by impact from that reference.
+
+**Public hierarchy is `Feature -> Slice -> Check`.** A slice is observable end-to-end behaviour;
+a check is a proof-backed obligation. `plan.md` freezes decisions and `checks.md` freezes obligations.
+One builder handles whole slices sequentially; the coordinator owns handoff, verification, integration
+and cleanup. After Build, one fresh Verifier covers the complete feature range. `wtk-lean` owns the
+phase procedures; `wtk-config` owns review cadence. Every counted claim cites its producing command.
+
+Delivery is human-scheduled. Git and the artifacts named below own durable state.
+
+## wtk-lean
+
+profile: standard
+budget: 150k
+
+## Load (the heading, not the whole file)
+
+| When | Open |
+| --- | --- |
+| Writing, planning, or breaking a spec into tasks | `.agents/skills/wtk/references/test-contract.md` |
+| Starting a task in a multi-task feature | `docs/toolkit/guidelines/WORKFLOW-MEMORY.md` |
+| Specify touches a security surface | `docs/toolkit/guidelines/SECURITY.md` — `## 2. At Specify — declare the surfaces` |
+| Writing tests for an abuse case | `docs/toolkit/guidelines/SECURITY.md` — `## 3. At the test contract — abuse cases get IDs` |
+| Review residual | `docs/toolkit/guidelines/SECURITY.md` — `## 5. At review — the residual only` |
+| Adds or changes a screen | `docs/toolkit/guidelines/UI-UX.md` |
+| Front-end code or a mockup | `docs/toolkit/guidelines/FRONTEND.md` — only the heading in dispute |
+| Module boundary, port, or domain type | `docs/toolkit/guidelines/MODELING.md` |
+| Public surface — route, CLI verb, config key | `docs/toolkit/guidelines/DX.md` |
+| Diff changes user-visible behaviour | `docs/toolkit/guidelines/QA-SCENARIOS.md` |
+| QA pass at the end of a feature | `docs/toolkit/guidelines/QA-EXECUTION.md` |
+| Reviewing, or acting on findings | `docs/toolkit/guidelines/REVIEW-ROUNDS.md` |
+| Resolving feature workflow | `.agents/skills/wtk-config/SKILL.md` |
+| About to claim done, or to commit | `.agents/skills/wtk/references/evidence.md` |
+| Choosing which gate to run | `.agents/skills/wtk/references/validation.md` |
+| Branch or worktree | `.agents/skills/wtk/references/git.md` |
+| Keep or discard an artifact | `.agents/skills/wtk/references/artifacts.md` |
+| A rule stated in more than one document | `knowledge/wiki/index.md`, then the concept |
+| Recording or verifying the bundle | `docs/toolkit/guidelines/KNOWLEDGE-WIKI.md` |
+| Editing this file or a guideline | `docs/toolkit/guidelines/CONTEXT-BUDGET.md` |
+| Why a past choice (`AD-NNN`) | `.specs/AD-INDEX.md`; body `rg -A 20 '^### AD-NNN' .specs/STATE.md` |
+| Resume | `rg -A 20 '^## Handoff' .specs/STATE.md`, then reconcile Handoff + git and consult the current local `tasks.md` state when present, or the inline execution plan when Tasks was skipped |
+
+Docs and formatting do not trigger `SECURITY.md`.
+
+`AD-NNN` (three digits, `.specs/STATE.md`) are project decisions. Architecture invariants live in the
+consuming project's architecture docs. Cite the file with the label. Do not invent invariant ids in
+this pack.
+
+Recording an `AD-NNN` also runs `python3 .agents/skills/wtk-config/scripts/ad-index.py` in that commit. Lean validators
+live in `.agents/skills/wtk-lean/scripts/`; the consuming project owns `make check`.
+
+## Where the truth lives
+
+| You need | Read |
+| --- | --- |
+| What to build and why | `docs/product/` |
+| How the system is shaped | `docs/architecture/` |
+| How it looks and behaves | `docs/design/` |
+| Why a past choice was made | `.specs/AD-INDEX.md` |
+| Versioned feature requirements and proof state | `.specs/features/<feature>/plan.md`, `checks.md`, `verification.md` |
+| What the product currently promises users | `docs/qa/scenarios/` |
+
+## Isolated checkouts
+
+If the consuming project isolates checkouts (worktrees, sibling clones), **each checkout owns its
+runtime**. Never set `reuseExistingServer: true` across siblings — that lets a gate in one checkout
+silently test another's application.
+
+## Commit style
+
+Conventional Commits: `<type>(<scope>): <description>`, types `feat|fix|refactor|perf|docs|test|build|ci`.
+One commit per task. One commit per review-remediation batch. If a pre-commit hook fails, fix the
+issue and make a new commit — never `--amend`.

package/NOTICE.md

@@ -0,0 +1,12 @@
+# Workflow Toolkit notices
+
+The executable, installer, and bundled support scripts are project-owned MIT-licensed source.
+The workflow skill content is CC BY 4.0 unless its frontmatter states otherwise.
+
+The integrated Lean skill is an adaptation of Tech Leads Club's `tlc-spec-lean` at commit
+`0ab82f644cd9caf94c65347a50ad934800b0cbc4`. Its source URL, content hash, and `CC-BY-4.0`
+license are pinned in [`skills-lock.json`](skills-lock.json) and its attribution is retained in
+[`.agents/skills/wtk-lean/NOTICE.md`](.agents/skills/wtk-lean/NOTICE.md).
+
+Project-owned skill adaptations retain their per-file `CC-BY-4.0` frontmatter. External skill
+sources and reviewed revisions remain listed in [`skills-lock.json`](skills-lock.json).

package/README.md

@@ -0,0 +1,440 @@
+# Workflow Toolkit
+
+The npm package is `workflow-toolkit`; the executable is `wtk`.
+
+An operating system for agents. It ships the workflow-owned [`wtk`](.agents/skills/wtk/SKILL.md)
+router and its Lean skills (`wtk-lean`, `wtk-discover`, `wtk-plan`, `wtk-implement`)
+with a capped delivery loop, countable tests and security surfaces, and a knowledge bundle. It is
+not a product template and not a stack starter.
+
+The design problem is the usual one: **ship, without lying about quality**. Unbounded review feels
+responsible and never finishes. A green suite with no spec contract ships bugs. This pack picks a
+middle: small vertical slices, cheap gates while building, a hard cap on review rounds, and a
+human-owned merge.
+
+## Quick start
+
+From the repository you want to install into, run the guided Node.js installer:
+
+```bash
+npx workflow-toolkit install
+```
+
+The command targets the current directory, requires Node.js 18 or newer, and walks through module
+selection, state assessment, a complete preview, conflict decisions, final confirmation, and a
+result summary. It never requires Python. Existing files that are replaced or removed are copied
+byte-for-byte with their modes into `.my-workflow/backups/<UTC timestamp>/`; the adoption manifest
+is published last. Cancelling at any prompt writes nothing.
+
+Choose `core`, `quality`, or `extras`; selecting any non-core module also selects `core`.
+Every module is shown as `not installed`, `up to date`, `outdated`, `modified`, or `conflict`. A
+conflict must be explicitly backed up and replaced, excluded, or cancelled. Successful replacements
+that affect consumer guidance include a `knowledge-transfer.md` checklist with a pending human
+transfer; consumer knowledge is never merged automatically.
+
+The terminal wizard supports 80×24 and 120×40 layouts and `NO_COLOR=1`. The package's complete
+current workflow is documented in [docs/toolkit/](docs/toolkit/).
+
+Start here: **[docs/toolkit/](docs/toolkit/)** — an index of every stage, guideline, and choice.
+
+## Purpose
+
+| Delivery | Reliability |
+| --- | --- |
+| Auto-sized planning (one line needs no spec) | Tests assert spec outcomes, not the implementation |
+| Proportional scoped gate; full gate only when selected | Never weaken a test to go green |
+| Nitpicks become filed issues, not extra rounds | Critical and Major still hold the ship |
+| `ponytail` at `full` — shortest code that works | Security surfaces declared and given `SEC-` ids |
+| `wtk-ship` scopes remote delivery | Its invocation authorizes the feature-branch push, one pull request, and merge after readiness is rechecked; readiness is evidence, not authorization for deploy/release, production mutations, force-push, direct `main` push, or unrelated remote actions |
+
+The loop, the caps, and the guidelines are the mechanism. The tour explains **why** each exists.
+`AGENTS.md` is what agents run.
+
+## Current workflow
+
+Use plain intent in the request:
+
+- “Visual polish / UI-only correction; I am doing manual QA” keeps adjustments to colors, spacing,
+  typography, alignment, borders, and layout on the narrow inspect → implement → targeted check →
+  commit path when behavior stays unchanged.
+- “Feature” starts the smallest spec and slice route that fits the behavior. “Cross-feature” sets a
+  broader mapping floor. A neutral Linear `issue` is classified from its concrete outcome, not its
+  label.
+- Documentation maintenance, agent-instruction changes, and mixed executable changes automatically
+  use proportional checks from `.agents/skills/wtk/references/validation.md`. Named risk or changed public behavior selects stronger
+  evidence. Confirmed wtk-deep-review defects are fixed inside their run; cosmetics become follow-up work.
+
+The feature path is Plan → Checks → Build → Verify. Builders use whole observable slices and
+coherent commits, then one fresh independent Technical Verifier proves the complete feature range.
+Deep Review is optional and defaults to `skip`; QA runs when the changed surface requires a user-visible
+walk; the full gate remains selected by changed behavior and concrete risk.
+
+For UI work, Designer starts with constraints, reads selected references, and inspects existing
+components read-only. A design tool or isolated prototype supports exploration when useful. Three
+alternatives apply when a new screen or meaningful redesign leaves an actual design choice open;
+existing patterns handle bounded compositions. One exploration and one refinement is the default.
+Human visual acceptance is recorded only after the human confirms it.
+
+The shared workflow stays in `AGENTS.md`. Keep the product index short and point to existing
+documents, for example:
+
+```markdown
+## Critical constraints
+- [Only the project constraints every task must see.]
+
+## Role/task routes
+| Role or task | Read only |
+| --- | --- |
+| Visual polish | docs/design/SYSTEM.md#tokens-and-accessibility |
+| Customer-facing copy | docs/brand/VOICE.md |
+| Feature planning | docs/product/OVERVIEW.md and affected journey references |
+| Implementation | Assigned spec/task and the relevant architecture sections |
+```
+
+These paths are examples: replace them with real files and headings in your project. A visual-polish
+task does not load the voice guide or all product journeys merely because those documents exist.
+Project-specific operational rules, such as Linear routing and environment setup, can live in
+separate references selected by the matching task.
+
+## Credits and provenance
+
+This workflow is maintained by Antonio Fulgêncio. The process builds on work from the following
+authors and communities:
+
+- Tech Leads Club: the adapted [`wtk`](.agents/skills/wtk/SKILL.md),
+  based on [`tlc-spec-driven`](https://github.com/tech-leads-club/agent-skills/tree/main/skills/tlc-spec-driven),
+  and the security gate with its [security skills](https://github.com/tech-leads-club/agent-skills/tree/main/skills).
+  The integrated Lean source is pinned to commit `0ab82f644cd9caf94c65347a50ad934800b0cbc4` under
+  CC BY 4.0; see [`NOTICE.md`](NOTICE.md) and [`skills-lock.json`](skills-lock.json).
+- Pedro Nauck: [`wtk-deep-review`](https://github.com/pedronauck/skills/tree/main/skills/mine/wtk-deep-review),
+  whose review workflow is adapted here.
+- The project-owned `wtk-qa-plan` and `wtk-qa-execute` skills are Antonio's adaptations, inspired by Pedro's
+  [`qa-report`](https://github.com/pedronauck/skills/tree/main/skills/mine/qa-report) and
+  [`qa-execution`](https://github.com/pedronauck/skills/tree/main/skills/mine/qa-execution).
+
+The QA skills use their own wording and structure for this workflow; the links above identify the
+inspiration and do not claim upstream authorship.
+
+The workflow references four external security skills:
+
+- `security-spec` for security requirements and negative tests during Specify;
+- `security-threat-model` for repository-grounded threats and trust boundaries;
+- `security-implementation` for secure-by-default implementation and hardening;
+- `security-review` for high-confidence residual vulnerability reviews.
+
+Reviewed copies are versioned here for local agents, but excluded from the npm package.
+Their GitHub source, canonical path, reviewed commit, CLI
+version (`1.5.23`), and content hash are authoritative in [`skills-lock.json`](skills-lock.json).
+Adoption prints a
+separate installer command; run it only after explicit authorization because it uses the network
+and writes the consumer's `.agents/skills/` tree. It does not install `latest` or silently update
+these dependencies.
+
+## Guided installation details
+
+Copy the loop, not the product. New projects receive a neutral, consumer-owned
+`docs/product/AGENT-CONTEXT.md` index; fill its identity and routes with existing project references
+instead of copying this source pack's profile. Existing projects preserve their filled product
+paragraph and product-owned documentation. Knowledge transfer is always a human review step.
+
+The three fixed modules are `core` (Lean operating loop and shared tooling), `quality` (review and QA),
+and `extras` (optional Ponytail utilities and prompt-review). Selecting `quality` or `extras` automatically
+includes `core`. The guided command is:
+
+`core` contains the Lean operating loop and Bun tooling; `quality` adds review and QA skills; and
+`extras` adds optional Ponytail utilities and prompt-review. `full` resolves all three catalog modules.
+Invoke `$prompt-review` for instruction audits or requested simplification.
+
+```bash
+npx workflow-toolkit install
+```
+
+The target must be the current directory and the command must run in an interactive terminal.
+The command never invokes Python. It previews add, update, adopt, preserve, replace, remove, and
+no-change actions before asking for final confirmation.
+
+Cancellation exits 0 with no target, adoption, journal, or backup changes. Invalid state, unsafe
+paths, backup failures, and publication failures exit 1; non-interactive use exits 2 with the exact
+TTY guidance.
+
+Add capabilities later with another apply; installed layers are cumulative and omitted layers are
+never removed. `--skip-agents` preserves both instruction files byte-for-byte and skips local-config
+initialization and packet synchronization. Without it, adoption appends managed `core` and `quality`
+blocks while preserving consumer prose. A differing
+managed file or unowned destination is reported as a conflict and causes zero writes.
+
+### Recovery and conflict handling
+
+For an existing project copied from an older workflow release, the wizard inspects current files and
+the adoption manifest. It reports every conflict before writing. Choose `Back up and replace`,
+`Exclude module`, or `Cancel installation`; excluding `core` also excludes dependent modules.
+
+If the process stops after publication begins, the next run detects the transaction journal and
+offers restoration from its verified backup before allowing a new installation.
+
+### Test resources
+
+The Lean route uses one sequential builder. Consuming projects may serialize heavy commands that
+share a browser, database, container runtime, or other declared resource.
+
+Prerequisites: Node.js 18 or newer and an interactive terminal. Python is not an installer
+prerequisite; unrelated Python workflow tools remain available after installation.
+
+The preview is the review: inspect the complete action list and backup destination before confirming.
+
+Feature workflow state follows the [artifact lifecycle](.agents/skills/wtk/references/artifacts.md) and
+remains visible to Git. Adoption removes only the exact legacy `.specs/features/` ignore line,
+including duplicates, preserves consumer-owned lines and comments, and never stages or commits files
+from the transient feature tree.
+
+The tracked `.wtk.toml.example` documents the complete v3 matrix and `mixed` profile. Each
+checkout owns an ignored `.wtk.toml`, initialized from that example by adoption without
+`--skip-agents` or by explicit sync;
+it is the single editable source for all Claude, Codex, and Cursor model and effort choices. The
+tracked `.agents/skills/wtk-config/assets/agents/` trees hold canonical instruction bodies, while sync generates the
+ignored native runtime packets. Re-adoption preserves an existing local config byte-for-byte and
+regenerates runtime packets from the templates and that config when `--skip-agents` is not used.
+With `--skip-agents`, sync is an explicit later operator step.
+
+```bash
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root /path/to/target-project --sync-agents
+```
+
+Edit the `[models.<provider>.<role>]` tables in the local `.wtk.toml`, then run the explicit
+sync command. If the local file is missing, sync validates and copies
+`.wtk.toml.example` first. It reports changed and unchanged runtime packet paths and is
+idempotent. Native `model`, `effort`, and `model_reasoning_effort` fields are generated output; do
+not edit runtime packets manually. Runtime edits are disposable; edit tracked templates when
+changing instruction bodies.
+
+The `cadence` controls the wtk-deep-review groups:
+
+The default is `skip`: Deep Review runs only when the operator requests it or explicitly selects a
+scheduled cadence.
+
+- `slice`: one group per slice (`1, 2, 3, 4` → `[1] [2] [3] [4]`).
+- `feature`: one group for the whole feature (`1, 2, 3, 4` → `[1, 2, 3, 4]`).
+- `grouped.N`: consecutive, balanced groups with at most `N` slices (`grouped.3` with four
+  slices → `[1, 2] [3, 4]`).
+- `skip`: no groups (`[]`); final QA, readiness, and merge do not wait for wtk-deep-review, and the
+  human runs `wtk-deep-review` later.
+
+Post-cap remediation is bounded by `[remediation] stall_attempts`. It defaults to `3`; `0` means
+unbounded. The threshold is read from the current local config on every attempt and is not stored
+in the feature snapshot:
+
+```toml
+[remediation]
+stall_attempts = 3
+```
+
+After each remediation attempt, the scoped gate produces a normalized, sorted failing-test
+signature. A strictly smaller failing-test set resets the stall counter; an equal-size or larger
+set increments it, including when membership changes. A reached nonzero threshold halts with the
+signature, attempt count, and fixes tried. An unavailable gate halts immediately. The review cap
+never opens a third wtk-deep-review round.
+
+The resolver uses the native provider for every role unless a named profile or role override is
+selected. Precedence is `CLI override > profile > native provider`:
+
+When a feature has `tasks.md`, the resolver validates its vertical-slice closure table and derives
+the slice count from merge-alone outcomes. A feature without `tasks.md` uses one slice. `--slices`
+is an optional assertion against that derived count during initial resolution or refresh; it is not
+the source of truth.
+
+```bash
+# Native route: all roles use Codex.
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root /path/to/target-project --feature register-user-native \
+  --native-provider codex
+
+# Named profile: use the [profiles.mixed] routes from .wtk.toml.
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root /path/to/target-project --feature register-user-profile \
+  --native-provider codex --profile mixed
+
+# Role overrides win over both the selected profile and the native provider.
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root /path/to/target-project --feature register-user-override \
+  --native-provider codex --profile mixed \
+  --override deep_reviewer=cursor --override verifier=claude
+```
+
+The first resolution freezes the effective route and cadence in
+`.specs/features/<feature>/workflow.json`, including model and effort for every delegated role.
+Planner is synchronized but remains the top-level session, not a delegated snapshot role. On
+resume, the snapshot is authoritative and packet metadata must still match its frozen model and
+effort. If it differs, synchronize packets and explicitly refresh; ordinary resume will fail:
+
+```bash
+python3 .agents/skills/wtk-config/scripts/workflow_config.py \
+  --root /path/to/target-project --feature register-user-refresh \
+  --native-provider codex --refresh
+```
+
+The complete contract is in the
+[wtk-config skill](.agents/skills/wtk-config/SKILL.md).
+
+## Update an adopted project
+
+Start from a clean tree and a dedicated update branch. Read the changelog since the version the
+project adopted, then run the guided installer and inspect the complete diff before committing:
+
+```bash
+cd /path/to/target-project
+git status --short
+git switch -c build/update-wtk
+npx workflow-toolkit install
+git diff
+```
+
+Run `npx workflow-toolkit install` for every installation or update. It updates pristine
+workflow-owned files, promotes provider templates using recorded source hashes, refreshes managed
+instruction blocks and runtime packets, and stops with all conflicts before writing.
+
+Adoption preserves product context, local config, package metadata, existing knowledge, and unknown
+consumer files. A fresh target receives managed generic knowledge instructions plus neutral,
+consumer-owned wiki indexes and log. Source concepts and dated raw observations never cross the
+repository boundary. Retired workflow files are removed only when their managed hashes prove they
+are pristine; edited or unproven paths conflict with zero writes.
+
+Each release lists its upgrade steps under `### Migration` in the changelog; follow them in order
+after installation. The package identity for this release is `workflow-toolkit@1.0.1` with the `wtk` executable.
+
+## Managed paths
+
+Review the managed paths and the installer's per-file actions. Installation updates only workflow-owned files,
+preserves unknown consumer files, creates `.wtk.toml.example` and skill-owned runtime, and records ownership in `.my-workflow/adoption.json`. It never removes an
+installed layer or consumer file. Product documentation, `.specs/`, `package.json`, `bun.lock`, an
+existing local `.wtk.toml`, and an existing `docs/qa/README.md` remain consumer-owned.
+
+The local config is the source for generated provider packets. Installation preserves an existing
+`.wtk.toml` and installs tracked templates when missing. The guided command synchronizes and
+regenerates the ignored `.claude/agents/`,
+`.codex/agents/`, and `.cursor/agents/` packets from the templates and config. Edit the config or
+tracked templates, not generated runtime packets.
+
+## Troubleshooting
+
+**`conflict` during installation.** Review every listed path. Restore an owned file to its recorded
+hash or resolve an unowned collision, then run the guided command again. Installation is all-preflight:
+no selected file or manifest is written while any conflict remains.
+
+**`refusing adoption: Makefile:N uses machine-global workflow skill path`** Point the target's gate at
+the vendored `.agents/skills/wtk-config/scripts/...` path.
+
+**Claude skill symlinks point nowhere.** Re-run `npx workflow-toolkit install`; it recreates the `.claude/skills/`
+links into `.agents/skills/`.
+
+**A runtime packet has the wrong model or effort.** Edit the local `.wtk.toml`, then run
+`npx workflow-toolkit install`. Runtime packets are generated output.
+
+## Repository intelligence
+
+The workflow stays stack- and tool-agnostic while using provider-neutral repository-intelligence defaults.
+Graphify and Graft are the standard, checkout-local development tools for repository intelligence.
+They never enter application runtime dependencies, and specs plus current checkout source remain
+authoritative.
+
+Use the smallest route that answers the question:
+
+- Existing file, symbol, API, caller, and callee pointers: skip retrieval.
+- Architectural trigger (boundary, responsibility transfer, shared abstraction, central flow, or
+  unresolved architectural risk): query Graphify first, then use Graft for implementation pointers.
+- Unknown code location or call relationship: query Graft before broad native search.
+- Exact-text question: use exact native search.
+
+Tool output stays bounded. Missing, wrong-version, stale, failed, partial, or insufficient output
+produces one explicit degraded reason for the phase, then targeted native inspection. Degraded
+inspection is a fallback, not normal routing.
+
+Adoption reports these exact development-tool remediation commands without executing them or changing
+application dependencies:
+
+```bash
+npm install --save-dev --save-exact @nanonets/graft@0.10.1
+uv tool install graphifyy==0.9.14
+python3 .agents/skills/wtk-config/scripts/repository_intelligence.py \
+  graphify-setup --root . --backend <backend> --mode deep
+```
+
+Graphify semantic extraction requires an explicit backend and discloses its source scope before
+extraction. Each query refreshes or rejects state using the active checkout and working-tree
+fingerprint. Generated graphs, caches, backend metadata, and benchmark scratch records remain ignored
+under `graft/`, `graphify-out/`, and `.repository-intelligence/`.
+
+The directional retention pilot records one controlled terminal task per JSONL record, including task
+category, configuration (`baseline`, `graft`, or `routed`), snapshot and prompt controls, provider,
+model, effort, token metrics, repository-intelligence/native-search calls, files read, wall-clock time,
+gate, Verifier, findings, rework, and outcome. Compare the same controls within each category after
+10–20 terminal tasks. A promoted report is directional, not statistically conclusive; removing or
+changing routing requires a later explicit project decision.
+
+## Optional integrations
+
+**OpenDesign** remains an optional visual capability. The repository stores only the approved handoff;
+absence or failure falls back to normal repository artifacts. It is separate from standard Graphify
+and Graft routing. No integration is mandatory or installed by adoption for visual iteration.
+
+The installer merges workflow-owned ignore entries, copies missing example/templates, generates
+local runtime packets, and records per-file ownership in `.my-workflow/adoption.json`. It preserves
+consumer prose through managed blocks, never removes an installed layer, and leaves package
+metadata, local config, and unknown files untouched. Always review the plan and resulting diff
+before accepting managed-path updates.
+Adoption itself does not install external security skills. It prints the exact command for the
+separate authorized step and leaves the security gate uncovered until that command succeeds.
+
+## Skills
+
+Canonical copies live in `.agents/skills/`. Claude Code gets symlinks in `.claude/skills/`. Cursor,
+Codex and OpenCode consume `.agents`. Do not add `.cursor/skills` or other agent trees. The
+project-owned `wtk-qa-plan` and `wtk-qa-execute` skills use the consuming project's profile in
+`docs/qa/README.md`; they do not select a framework or replace the project's gate.
+
+`npx workflow-toolkit install` installs and updates only the workflow-owned `wtk` router, its Lean
+skills (`wtk-lean`, `wtk-discover`, `wtk-plan`, `wtk-implement`), Ponytail, Deep
+Review, QA, wtk-config, and wtk-ship skills. Keep those canonical copies in
+`.agents/skills/` and the Claude Code
+symlinks in `.claude/skills/`. The four external security skills are a separate authorized step:
+
+```bash
+python3 /path/to/workflow-toolkit/scripts/install_security_skills.py \
+  /path/to/target-project --yes
+```
+
+The installer uses only the reviewed refs and hashes in `skills-lock.json`; it does not resolve
+`latest` or perform automatic updates. Review its printed plan and authorize the command before
+running it. Until it succeeds, do not treat the security gate as covered.
+
+`wtk-ship` is vendored here. `CLAUDE.md` is the one line `@AGENTS.md` (not a symlink). Canonical
+packet templates live under `.agents/skills/wtk-config/assets/agents/{cursor,claude,codex}/`; generated implementer,
+explorer and verifier runtimes live under the ignored `.cursor/agents/`, `.claude/agents/` and
+`.codex/agents/` directories.
+
+## Knowledge checker
+
+These are optional source-pack maintainer checks, not adoption or consumer task gates.
+
+```bash
+bun install --frozen-lockfile
+bun run test:all
+bun run knowledge
+```
+
+The consuming project's full gate should not include this checker. Run it when writing to the
+bundle.
+
+## Out of scope
+
+Product domains, product-owned documentation, architecture, infrastructure, and framework choices
+belong to the consuming project. This pack is stack-agnostic on purpose and does not prescribe a
+browser, API, CLI, mobile, or manual QA runner.
+
+## Deliberately not included
+
+- Any product, domain, architecture, or design *concepts* from a source project's wiki
+- Dated `knowledge/raw/` observations
+- Library and stack skills
+- A product skeleton, Makefile, port scheme, or worktree-slot arithmetic
+- Retired orchestration history