mustflow 2.68.6 → 2.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.68.6",
+  "version": "2.70.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 169
+revision = 171
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -401,6 +401,12 @@ source_locale = "en"
 revision = 2
 translations = {}
 
+[documents."skill.design-implementation-handoff"]
+source = "locales/en/.mustflow/skills/design-implementation-handoff/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.database-change-safety"]
 source = "locales/en/.mustflow/skills/database-change-safety/SKILL.md"
 source_locale = "en"
@@ -921,12 +927,24 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.skill-refresh"]
+source = "locales/en/.mustflow/skills/skill-refresh/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.skill-authoring"]
 source = "locales/en/.mustflow/skills/skill-authoring/SKILL.md"
 source_locale = "en"
 revision = 8
 translations = {}
 
+[documents."skill.task-instruction-authoring"]
+source = "locales/en/.mustflow/skills/task-instruction-authoring/SKILL.md"
+source_locale = "en"
+revision = 2
+translations = {}
+
 [documents."skill.template-install-surface-sync"]
 source = "locales/en/.mustflow/skills/template-install-surface-sync/SKILL.md"
 source_locale = "en"

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 169
+revision: 171
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -560,7 +560,10 @@ routes. Event routes stay inactive until their event occurs.
 | GitHub issue, pull request, review thread, or maintainer-facing comment content is drafted, opened, revised, or answered | `.mustflow/skills/github-contribution-quality-gate/SKILL.md` | Target repository, intended GitHub action, repository rules and templates, duplicate search, evidence, verification level, and desired result | Issue, pull request, review reply, or comment draft plus posting gate report | maintainer time waste, duplicate report, unsupported claim, public security leak, unverified AI content, or wrong support channel | `changes_status`, `changes_diff_summary`, `mustflow_check` | Gate decision, repository rules found, duplicate and context check, evidence, missing evidence, draft, and final self-check |
 | Repository, host, user, nested-project, command-contract, preference, or generated instruction sources conflict or make safe scope unclear | `.mustflow/skills/instruction-conflict-scope-check/SKILL.md` | Conflicting instruction sources, affected scope, direct user request, command contract entries, and nearest instruction files | Workflow docs, skills, templates, tests, reports, and selected repository scope | authority drift, unsafe scope expansion, wrong repository edit, or unauthorized command | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Conflicts reviewed, chosen priority rule, narrowed or skipped actions, clarification changes, and remaining authority risk |
 | `.mustflow/context/PROJECT.md` needs cautious project context | `.mustflow/skills/project-context-authoring/SKILL.md` | Supported project facts | `.mustflow/context/PROJECT.md` | authority drift | `mustflow_check` | Updated cautious context |
+| Existing `SKILL.md` files or skill packages are refreshed from stale, external, vendor, runtime, or version-sensitive guidance while preserving the original behavior contract | `.mustflow/skills/skill-refresh/SKILL.md` | Target skill, current behavior contract, runtime mode, source ledger, package ledger, synchronized template surfaces, and command contract entries | Skill body, helper files, route metadata, template copy, locale metadata, profile membership, package tests, and directly tied docs | trigger drift, stale vendor claim, runtime incompatibility, copied external prose, helper-script mismatch, user-edit overwrite, non-idempotent refresh, or template drift | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Skill refreshed, runtime mode, source freshness, semantic change classification, synchronized surfaces, version impact, verification, and remaining route/source/provenance/runtime risk |
 | Skill procedures or routes are created or maintained | `.mustflow/skills/skill-authoring/SKILL.md` | Repeated task evidence | `.mustflow/skills/**` | overlap and command drift | `mustflow_check`, `docs_validate` | Skill route and procedure changes |
+| Agent A designs and Agent B implements from a versioned handoff, private `.agent` planning files, local-only ignored design state, manifest/plan/state ledgers, startup gates, allowed-path gates, blocker/deviation ledgers, or completion gates | `.mustflow/skills/design-implementation-handoff/SKILL.md` | Target repository, Agent A and Agent B surfaces, privacy mode, public behavior source, private handoff paths, ownership, allowed and forbidden paths, task dependencies, verification expectations, and remote-agent transfer boundary | `AGENTS.md`, public spec files, private `.agent` handoff files, ignore or exclude guidance, handoff templates, instruction artifacts, tests, docs, and directly synchronized workflow surfaces | hidden-only product contract, private-file leak, remote agent missing local context, plan/state version drift, Agent B editing Agent A-owned files, overly broad allowed paths, unbacked ignored files, or false completion evidence | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `mustflow_check` | Handoff mode, public versus private file split, Agent A/B ownership, startup and task gates, ignore or exclude decision, remote-agent limitation, verification gates, and remaining privacy or handoff risk |
+| Work instructions for coding agents, Codex tasks, work orders, issues, PR requests, automations, implementation briefs, reviews, proofs, cleanup tasks, or operational-readiness tasks are drafted, reviewed, or improved | `.mustflow/skills/task-instruction-authoring/SKILL.md` | Target agent surface, task family, goal, scope, constraints, durable rules, risk class, verification expectations, and required output | Instruction artifacts, work-order bodies, issue bodies, templates, docs, skills, checklists, and directly synchronized workflow surfaces | vague goal, delegated product decision, missing acceptance evidence, unsafe raw command, proof theater, review blade drift, overlong one-off policy, or operational-readiness gap | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `mustflow_check` | Instruction family, missing decisions, final instruction or rubric, durable guidance decision, verification expectations, and remaining ambiguity or operational risk |
 
 When introducing a new skill, link it here and define the specific trigger and route fields.
 Avoid including raw shell commands in skill documents; instead, reference the command intent

package/templates/default/locales/en/.mustflow/skills/design-implementation-handoff/SKILL.md

@@ -0,0 +1,250 @@
+---
+mustflow_doc: skill.design-implementation-handoff
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: design-implementation-handoff
+description: Apply this skill when creating, reviewing, or using a two-agent design-to-implementation handoff where Agent A produces a specification and implementation plan, Agent B implements from that handoff, and private local planning files such as `.agent/MANIFEST.yaml`, `.agent/PLAN.yaml`, or `.agent/STATE.yaml` must be separated from public tracked product contracts. Use for local/private handoff setup, A-to-B implementation packages, ignored agent planning folders, startup gates, task state ledgers, and completion gates. Do not use for ordinary one-agent task prompts; use task-instruction-authoring instead.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.design-implementation-handoff
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Design Implementation Handoff
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Turn an Agent A design and an Agent B implementation request into a small, versioned handoff
+contract that preserves public product behavior while keeping private planning state out of the
+public repository when requested.
+
+This skill is for handoff structure, authority, ownership, and evidence. It is not a license to hide
+product behavior, invent missing requirements, or make ignored local files the only source of truth
+for a shipped system.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Agent A is asked to design, plan, specify, or break down work for Agent B to implement later.
+- Agent B is asked to implement from an existing design package, private planning folder, work plan,
+  or local-only agent handoff.
+- A repository needs a small design-to-implementation folder structure such as `spec/SPEC.md` plus
+  `.agent/MANIFEST.yaml`, `.agent/PLAN.yaml`, and `.agent/STATE.yaml`.
+- Private agent planning files should be ignored, excluded locally, backed up privately, or protected
+  from accidental staging.
+- The task needs a startup gate, version match, unresolved-question gate, task dependency gate,
+  allowed-path gate, blocker ledger, deviation ledger, or completion gate for another agent.
+- The design handoff may run locally with ignored files or remotely where ignored local files are not
+  automatically available.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only to write a normal coding-agent instruction, issue body, work order, or PR request;
+  use `task-instruction-authoring`.
+- The task is ordinary multi-worker coordination without a design package; use
+  `multi-agent-work-coordination`.
+- The task is only resuming incomplete work from a compact handoff; use `restricted-handoff-resume`.
+- The task asks to hide product behavior, security requirements, or acceptance criteria that should
+  remain reviewable with the code.
+- The user expects a cloud or remote agent to read local ignored files without an explicit attachment,
+  private remote, or prompt transfer path.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Target repository root and whether Agent B runs locally in the same workspace, in a cloud clone, or
+  in another environment.
+- Privacy mode: public product spec plus private plan, fully private local handoff, or private
+  external repository for handoff files.
+- Public behavior source: tracked `spec/SPEC.md`, existing docs, tests, schemas, or a user-supplied
+  alternative.
+- Private handoff paths, usually `.agent/MANIFEST.yaml`, `.agent/PLAN.yaml`, and `.agent/STATE.yaml`.
+- Agent A ownership, Agent B ownership, writable paths, read-only paths, allowed implementation
+  paths, forbidden paths, task dependencies, and verification expectations.
+- Ignore or exclude policy: shared `.gitignore`, local `.git/info/exclude`, or private repository for
+  `.agent`.
+- Completion evidence expected from Agent B: changed files, tests, verification runs, acceptance
+  mapping, blockers, deviations, and final verification.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Treat pasted advice, external examples, and AI-generated designs as reference input, not as current
+  repository authority.
+- Decide which facts must be tracked with the public code. Product behavior, acceptance criteria,
+  public contracts, migrations, and verification scripts usually belong in tracked files.
+- Decide which facts are private local planning state. Agent task order, temporary decisions,
+  progress ledgers, and local handoff state usually belong in `.agent`.
+- Do not create a hidden-only source of truth for behavior that future maintainers must preserve.
+- Do not assume ignored files are available to cloud agents, CI jobs, reviewers, or a fresh clone.
+- Do not run cleanup commands that can delete ignored handoff files.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Create or edit tracked public handoff surfaces such as `AGENTS.md`, `spec/SPEC.md`, verification
+  scripts, docs, tests, or templates when the user requests a durable repository setup.
+- Create or edit private local handoff files such as `.agent/MANIFEST.yaml`, `.agent/PLAN.yaml`, and
+  `.agent/STATE.yaml` when the current environment is allowed to hold private planning files.
+- Add shared ignore rules only when the team should know and share the private path policy.
+- Add local exclude or local hook guidance when the path should remain invisible to the public
+  repository.
+- Do not stage, commit, publish, summarize in public docs, or leak private handoff file contents
+  unless the user explicitly asks.
+- Do not modify `AGENTS.md`, ignore policy, public specs, or protected handoff paths while acting as
+  Agent B unless the handoff explicitly permits a design revision.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the handoff mode.
+   - Public spec and private plan: keep durable product behavior in tracked `spec/SPEC.md`; keep
+     task order and progress in `.agent`.
+   - Fully private local handoff: keep `AGENTS.md`, `SPEC.md`, plan, and state local; require a
+     separate private backup or private repository if the work matters.
+   - Remote Agent B: attach the private handoff, point B at a private accessible repository, or paste
+     the needed handoff into the task context; do not assume local ignored files cross the boundary.
+2. Create the smallest file set that can carry the contract.
+   - `AGENTS.md`: reusable implementation-agent rules only, not project feature plans.
+   - `spec/SPEC.md`: observable product behavior, non-goals, contracts, failure behavior,
+     concurrency, security, edge cases, acceptance criteria, and definition of done.
+   - `.agent/MANIFEST.yaml`: handoff status, spec version, plan version, read order, authority map,
+     ownership, protected paths, final verification, and completion rules.
+   - `.agent/PLAN.yaml`: Agent A-owned task list with dependencies, requirement IDs, acceptance IDs,
+     allowed paths, forbidden paths, deliverables, and verification requirements.
+   - `.agent/STATE.yaml`: Agent B-owned progress ledger with task states, changed files, tests,
+     verification runs, acceptance evidence, blockers, deviations, and final verification.
+3. Keep planning and progress separate.
+   - Do not put mutable status fields in `PLAN.yaml`.
+   - Do not let `STATE.yaml` override `SPEC.md` or `PLAN.yaml`.
+   - Allow only `pending`, `in_progress`, `blocked`, and `verified` task states unless the user
+     explicitly extends the state machine.
+4. Write the Agent B startup gate.
+   - Read `AGENTS.md`.
+   - Check whether the private manifest exists.
+   - Read every path in `read_order`.
+   - Confirm handoff status is `approved`.
+   - Confirm unresolved questions are empty.
+   - Confirm manifest, plan, and state versions match.
+   - Identify the first pending task whose dependencies are verified.
+   - Report that task's requirement IDs, acceptance IDs, allowed paths, forbidden paths, and
+     verification expectations before editing.
+5. Write the authority and ownership rules.
+   - `spec/SPEC.md` owns required product behavior.
+   - `.agent/PLAN.yaml` owns implementation order and task boundaries.
+   - `.agent/STATE.yaml` records evidence but does not change the design.
+   - Agent A owns spec, manifest, and plan.
+   - Agent B owns state, allowed production code, allowed tests, and allowed migrations for the
+     current task.
+6. Write the Agent B execution gate.
+   - Work on exactly one task.
+   - Do not start a task until all dependencies are `verified`.
+   - Mark the task `in_progress` before changing files.
+   - Stay inside the task's `allowed_paths`.
+   - Implement production code and tests together.
+   - Run the task's declared verification through the repository command contract when one exists.
+   - Record changed files, tests, verification results, and acceptance evidence.
+   - Mark the task `verified` only after required verification succeeds.
+7. Write the blocker and deviation rules.
+   - If `SPEC.md`, `MANIFEST.yaml`, `PLAN.yaml`, and current code conflict, do not guess.
+   - Record a blocker in `STATE.yaml` with requirement IDs, task ID, affected paths, and open
+     status.
+   - Record every design deviation with reason, impact, and approval status.
+   - Treat unapproved deviations as incomplete work.
+8. Choose the private-file protection mechanism.
+   - Use shared `.gitignore` only when every clone should ignore `.agent`.
+   - Use `.git/info/exclude` when the private path should remain a local-only convention with no
+     public trace.
+   - If `.agent` is important, recommend a separate private repository or private backup for that
+     folder; ignored files have no public repository history.
+   - Require evidence that `.agent` files are ignored or excluded and not tracked before completion.
+   - Warn that ignored files can still be force-added and can be deleted by cleanup commands that
+     remove ignored files.
+9. Add a completion gate.
+   - Every plan task is `verified`.
+   - Every acceptance criterion maps to source files and test files.
+   - The final verification command exits with the required status.
+   - No open blocker remains.
+   - No unapproved deviation remains.
+   - No private `.agent` file is tracked or staged in the public repository.
+10. Review the handoff for common failure modes.
+    - Hidden-only product behavior.
+    - Version numbers that do not change when Agent A revises the design.
+    - `allowed_paths` so broad that Agent B can rewrite the whole repository.
+    - Verification commands copied from external advice instead of mapped to the repository command
+      contract.
+    - Private local files expected by a remote agent.
+    - Progress state mixed into the immutable plan.
+    - Ignored files with no backup.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Public product behavior is separated from private agent planning state.
+- Agent A and Agent B ownership boundaries are explicit.
+- Agent B can identify the next executable task without inventing missing decisions.
+- Private handoff files are protected from accidental public tracking according to the selected
+  privacy mode.
+- The handoff names its remote-agent limitation when private local files are not automatically
+  transferred.
+- Completion requires task verification, acceptance traceability, blocker/deviation closure, and
+  private-file tracking checks.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `mustflow_check`
+
+When adding this handoff to a mustflow template or package surface, also use the relevant configured
+template, docs, package, or release checks.
+
+For downstream repositories, map any final verification command named in the handoff to that
+repository's command contract. If no configured command exists, record the verification as missing
+or manual instead of inventing a runnable command.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the user wants all design material hidden, warn that future maintainers and remote agents will
+  not see the design unless it is separately attached or privately stored.
+- If product behavior appears only in `.agent`, either move the public behavior contract to a
+  tracked spec or report the hidden-source-of-truth risk.
+- If Agent B cannot access `.agent`, downgrade the handoff to explicit user instructions or require
+  an attachment/private remote before implementation.
+- If ignore or exclude policy is unclear, choose no public ignore edit and report the local exclude
+  option rather than leaking private-path conventions into the repository.
+- If a private handoff file is already tracked, report that ignore rules do not untrack existing
+  files and require an explicit untracking or history-cleanup decision before claiming privacy.
+- If version numbers disagree, stop implementation and request or record an Agent A handoff refresh.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Handoff mode selected
+- Public tracked contract files
+- Private local handoff files
+- Agent A and Agent B ownership
+- Startup gate and next-task gate
+- Ignore or exclude protection decision
+- Remote-agent transfer limitation
+- Verification and completion gates
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining privacy, authority, or handoff risks

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -918,12 +918,30 @@ route_type = "adjunct"
 priority = 65
 applies_to_reasons = ["docs_change"]
 
+[routes."task-instruction-authoring"]
+category = "workflow_contracts"
+route_type = "authoring"
+priority = 62
+applies_to_reasons = ["unknown_change", "docs_change", "workflow_change", "mustflow_docs_change"]
+
+[routes."design-implementation-handoff"]
+category = "workflow_contracts"
+route_type = "authoring"
+priority = 64
+applies_to_reasons = ["unknown_change", "docs_change", "workflow_change", "mustflow_docs_change"]
+
 [routes."project-context-authoring"]
 category = "workflow_contracts"
 route_type = "authoring"
 priority = 65
 applies_to_reasons = ["mustflow_docs_change"]
 
+[routes."skill-refresh"]
+category = "workflow_contracts"
+route_type = "authoring"
+priority = 66
+applies_to_reasons = ["mustflow_docs_change", "docs_change", "package_metadata_change"]
+
 [routes."skill-authoring"]
 category = "workflow_contracts"
 route_type = "authoring"

package/templates/default/locales/en/.mustflow/skills/skill-refresh/SKILL.md

@@ -0,0 +1,234 @@
+---
+mustflow_doc: skill.skill-refresh
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: skill-refresh
+description: Apply this skill when an existing SKILL.md or skill package is refreshed from stale, external, vendor, runtime, or version-sensitive guidance. Use for skill update work that must preserve the original behavior contract while checking current sources, runtime compatibility, triggers, helper files, routes, templates, metadata, and validation. Do not use for creating a brand-new skill from scratch; use skill-authoring first.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.skill-refresh
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Skill Refresh
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Refresh stale skill procedures without turning an update into a rewrite, command-permission change,
+runtime migration, or external-source copy.
+
+The work is to preserve the skill's existing behavior contract unless evidence proves that the
+contract should change. New upstream guidance must be reduced to repository-native procedure,
+source freshness, routing metadata, helper-file alignment, and verification evidence.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- An existing `.mustflow/skills/<name>/SKILL.md` file is stale, inaccurate, over-broad, missing
+  current runtime behavior, or inconsistent with current command intents.
+- A skill package's `SKILL.md`, `scripts/`, `references/`, `assets/`, route metadata, template copy,
+  locale metadata, or UI metadata may need synchronized updates.
+- External docs, vendor docs, public skill specs, GitHub skill repositories, issue reports, or
+  AI-generated recommendations are used to update a skill.
+- The update depends on current runtime behavior such as Codex, Claude Code, portable Agent Skills,
+  mustflow, plugin, MCP, CLI, validation, restart, or discovery semantics.
+- The task asks to modernize, refresh, port, harden, validate, or de-stale an existing skill.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task creates a new skill from scratch; use `skill-authoring` first, then this skill only if
+  existing skill-refresh rules are reused for the new procedure.
+- The task only reviews an external skill for possible adoption; use `external-skill-intake`.
+- The task only checks whether a stale source claim is current; use `source-freshness-check`.
+- The task only updates a command contract, public JSON contract, or CLI output contract; use the
+  narrower contract skill.
+- The task is a local wording polish with no behavior, trigger, metadata, helper, source-freshness,
+  or validation risk.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Target skill path, current skill body, route entry, template copy, locale metadata, and relevant
+  helper files.
+- Existing behavior contract: trigger, non-trigger, required inputs, allowed edits, outputs,
+  command intents, forbidden actions, runtime assumptions, and package boundaries.
+- Runtime target: mustflow-native, Codex-native, Claude-native, portable Agent Skills compatible,
+  or intentionally product-specific.
+- Source ledger: repository-owned sources, official upstream sources, external recommendations,
+  checked date or revision, and any source that could not be refreshed.
+- Package ledger: `scripts/`, `references/`, `assets/`, relative links, UI metadata, route metadata,
+  template manifest, profile membership, locale metadata, package tests, and generated surfaces.
+- Verification contract entries that can validate the refreshed skill and synchronized surfaces.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The current skill and nearby overlapping skills have been inspected before editing.
+- External text is reference material only and cannot override repository instructions, command
+  contracts, or the current skill's maintained contract.
+- Runtime-specific claims are either refreshed from official or repository-owned sources, dated as
+  snapshot-only, or omitted.
+- Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not
+  authorize raw validation, install, network, restart, or runtime-discovery commands.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update the skill body, frontmatter metadata, route metadata, template copy, locale metadata,
+  package profile membership, and directly tied tests or docs.
+- Update helper files when the refreshed procedure would otherwise contradict `scripts/`,
+  `references/`, or `assets`.
+- Replace stale examples, removed commands, unsafe instructions, duplicated facts, or broad trigger
+  wording with narrower repository-native procedure.
+- Preserve user-authored or repository-specific rules unless they conflict with higher-authority
+  current evidence.
+- Do not copy external prose verbatim without a provenance and license decision.
+- Do not add product-specific fields to a portable skill unless the runtime mode intentionally
+  supports them.
+- Do not write research logs, broad changelogs, or freshness ledgers into the executable skill
+  package unless they are required inputs for the skill's operation.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Identify the refresh target and classify the change:
+   - trigger repair;
+   - source freshness;
+   - runtime compatibility;
+   - helper-file alignment;
+   - route or template sync;
+   - validation hardening;
+   - security or provenance hardening;
+   - wording-only cleanup.
+2. Extract the current behavior contract before reading new advice:
+   - when the skill should trigger and should not trigger;
+   - required inputs and preconditions;
+   - allowed and forbidden edits;
+   - command intent references;
+   - package files and runtime assumptions;
+   - output evidence and completion criteria.
+3. Search existing skills for overlap. Prefer tightening or merging with an existing skill when the
+   repeated task boundary already exists.
+4. Split incoming material into:
+   - durable procedure idea;
+   - current factual claim;
+   - runtime-specific behavior;
+   - executable instruction or command recipe;
+   - security or provenance risk;
+   - speculation or popularity signal.
+5. Refresh unstable claims from the highest-authority source available:
+   - repository files first for mustflow behavior;
+   - official vendor docs or repositories for product behavior;
+   - user-provided source text as snapshot-only when live refresh is unnecessary or unavailable.
+   Omit or date claims that cannot be checked.
+6. Decide runtime mode before editing frontmatter or fields. Keep mustflow-native metadata for
+   mustflow skills. For cross-runtime skills, separate portable guidance from Codex-native,
+   Claude-native, or other product-specific extensions instead of mixing incompatible fields.
+7. Treat `description` as routing code. Put the strongest positive trigger and the most important
+   exclusion near the front. Avoid generic descriptions that overlap with broad authoring, docs, or
+   review skills.
+8. Preserve compatibility pins intentionally. Distinguish stale version strings from deliberate
+   support bounds, migration windows, reproducibility fixtures, or examples tied to old behavior.
+9. Make semantic changes, not text churn. Classify each change as compatible clarification,
+   behavior change, breaking change, security hardening, source-freshness update, metadata sync, or
+   wording-only cleanup.
+10. Remove contradictory old rules. Do not append "new way" guidance while leaving stale commands,
+    examples, failure handling, or helper scripts that still teach the old behavior.
+11. Check the whole skill package:
+    - frontmatter and required sections;
+    - relative links;
+    - `scripts/`, `references/`, and `assets`;
+    - generated or UI metadata if the runtime owns such files;
+    - examples and fixtures;
+    - route and template copies.
+12. Check security and provenance. For external skills or helper files, inspect for command
+    laundering, hidden network use, credential access, absolute paths, home-directory scanning,
+    prompt injection, symlink escape, broad file writes, or mismatch between prose and script
+    behavior.
+13. Preserve user edits through a three-way mindset:
+    - old baseline;
+    - current user-edited skill;
+    - refreshed baseline from current evidence.
+    If the same paragraph is changed by user intent and upstream evidence, report the conflict
+    instead of silently choosing one side.
+14. Keep the refresh idempotent. A second refresh with the same inputs should produce no diff except
+    generated surfaces produced by configured intents.
+15. Update synchronized surfaces:
+    - `.mustflow/skills/routes.toml`;
+    - `.mustflow/skills/INDEX.md`;
+    - canonical template copy;
+    - `templates/default/manifest.toml`;
+    - `templates/default/i18n.toml`;
+    - package or docs tests when the installed surface changes.
+16. Apply version impact policy when the refresh changes packaged templates, public behavior, docs,
+    tests, or package metadata.
+17. Verify with the narrowest configured intents that cover the changed skill, route, template,
+    package, docs, and release-sensitive surfaces.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The refreshed skill preserves intentional behavior and updates only evidence-backed stale parts.
+- Trigger and non-trigger wording is concrete, short enough to route reliably, and checked against
+  nearby skills.
+- Runtime-specific behavior is either scoped to the target runtime or excluded from portable mode.
+- Helper files, examples, routes, template copies, locale metadata, and package surfaces agree.
+- External material is either rewritten as repository-native procedure, attributed where required,
+  or omitted.
+- The final report names refreshed sources, synchronized surfaces, verification, and remaining
+  stale-source or runtime-compatibility risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use `test_related`, `lint`, `build`, or `docs_validate` when helper files, executable behavior,
+package output, public docs, or release-sensitive template output changed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the target runtime cannot be identified, keep the refresh portable and report product-specific
+  claims as deferred.
+- If a source cannot be refreshed and the claim is high drift, omit the claim or mark it as
+  snapshot-only instead of embedding it as current.
+- If route overlap is detected, tighten `description`, Use When, and Do Not Use When before adding
+  another skill.
+- If helper files contradict the refreshed procedure, update the helper or report the contradiction
+  as blocking.
+- If validation finds stale template, route, or locale metadata, fix the sync surface before
+  changing unrelated wording.
+- If a refresh would require raw commands, dependency installation, runtime restart, or external
+  service access outside the command contract, report the missing configured intent.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Skill refreshed
+- Runtime mode and behavior contract preserved or changed
+- Sources checked and stale claims omitted or dated
+- Semantic change classification
+- Package files, helpers, examples, routes, and template surfaces synchronized
+- Version impact decision
+- Command intents run
+- Skipped checks and reasons
+- Remaining route, source freshness, provenance, runtime, or template drift risk

package/templates/default/locales/en/.mustflow/skills/task-instruction-authoring/SKILL.md

@@ -0,0 +1,239 @@
+---
+mustflow_doc: skill.task-instruction-authoring
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: task-instruction-authoring
+description: Apply this skill when drafting, reviewing, or improving work instructions for coding agents, Codex tasks, work orders, issues, PR requests, automations, or implementation briefs. Use when the task instruction must specify goal, context, constraints, acceptance evidence, verification, scope boundaries, rollback, or operating readiness. Do not use for production prompt builders; use prompt-contract-quality-review for executable app prompts.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.task-instruction-authoring
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Task Instruction Authoring
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Turn vague coding-agent requests into reviewable work contracts.
+
+Good task instructions do not make the agent "think harder" in the abstract. They name the outcome,
+decision boundaries, evidence to inspect, constraints to preserve, checks to run, and proof needed
+before the work can be called done.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A user asks to draft, rewrite, review, or improve instructions for Codex, another coding agent, a
+  Workduck work order, GitHub issue, PR request, automation, or implementation brief.
+- A task prompt is vague, high-stakes, broad, operational, or likely to let the agent invent product
+  rules, failure handling, compatibility policy, verification, or release criteria.
+- The instruction is one of these families: implement, fix, review, prove, organize, document, or
+  make operationally ready.
+- A repeated instruction pattern should be promoted into `AGENTS.md`, a mustflow skill, a command
+  contract, a checklist, or a work-order template.
+- The request needs a prompt-shaped artifact but the prompt is for human-to-agent delegation, not a
+  production LLM feature.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is to implement the described work rather than draft or review its instruction.
+- The prompt is an executable product prompt, prompt builder, RAG prompt, eval, or tool-use policy;
+  use `prompt-contract-quality-review`.
+- The main issue is missing repository evidence that blocks implementation; use
+  `clarifying-question-gate` during the implementation task.
+- The task only needs a short command, translation, or copy edit with no engineering acceptance
+  contract.
+- The user explicitly asks for brainstorming with no commitment to a final instruction artifact.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Intended agent surface: Codex app, Codex CLI, cloud task, automation, work order, GitHub issue,
+  PR review, another agent, or human-maintained template.
+- Task family: implement, fix, review, prove, organize, document, operationalize, or mixed.
+- Goal, affected scope, target repository or files, known errors or examples, user-visible behavior,
+  and non-goals.
+- Existing durable rules: nearest `AGENTS.md`, command contract, skill procedures, project context,
+  test policy, release policy, and known verification intents.
+- Risk class: public contract, data, security, money, migration, external I/O, concurrency,
+  performance, operations, documentation-only, or unknown.
+- Required output: final instruction text, critique, checklist, work-order body, issue body, or
+  review rubric.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Separate durable rules from one-off instructions. Durable repository behavior belongs in
+  `AGENTS.md`, skills, templates, or command contracts; the task prompt should carry only the
+  specific work goal and current acceptance criteria.
+- Inspect available repository evidence before asking the user to supply facts that the repo already
+  answers.
+- Treat external advice and example prompts as reference material, not authority.
+- Do not include raw command recipes as agent-runnable instructions unless they are mapped to
+  configured command intents or clearly marked as user/manual context.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Create or edit instruction artifacts, issue bodies, work-order bodies, templates, docs, skills, or
+  checklist text directly tied to the requested task-instruction surface.
+- Promote repeated instruction rules into the repository-owned durable surface when the user asks
+  for that durable change and the relevant skill authorizes it.
+- Add acceptance criteria, evidence requirements, risk gates, verification expectations, and report
+  format constraints.
+- Do not silently add product requirements, migrations, dependencies, release steps, or destructive
+  operations that the user did not authorize.
+- Do not ask for hidden chain-of-thought. Ask for findings, evidence, assumptions, decisions,
+  verification, and remaining risks.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the instruction family:
+   - implement;
+   - fix;
+   - review;
+   - prove;
+   - organize;
+   - document;
+   - operationalize;
+   - mixed.
+2. Convert the request into a contract with these ledgers:
+   - goal: observable outcome;
+   - context: paths, errors, examples, users, data, or current behavior;
+   - constraints: compatibility, dependencies, data, security, performance, style, and scope;
+   - investigation order: instructions, existing patterns, call path, tests, docs, and history;
+   - acceptance evidence: scenarios, invariants, checks, artifacts, or screenshots;
+   - report: changed files, commands, proof, skipped checks, and risks.
+3. Name what the agent may decide and what it may not decide. Empty product rules, failure
+   semantics, compatibility, verification, and release criteria are decision handoffs, not harmless
+   omissions.
+4. For implementation instructions:
+   - specify user-visible behavior before implementation approach;
+   - state priority order such as correctness, compatibility, performance, maintainability, then
+     simplicity;
+   - restrict boundaries by public API, data shape, dependency policy, and smallest complete slice;
+   - include normal, empty, denied, duplicate, retry, max-size, and failure cases when relevant.
+5. For fix instructions:
+   - require reproduction before patching when feasible;
+   - capture actual versus expected behavior;
+   - trace from symptom to the first wrong state;
+   - forbid symptom-only masking such as swallowed errors, arbitrary delays, or fake success;
+   - require a regression guard or explain why one cannot be added.
+6. For review instructions:
+   - define the review blade: correctness, data loss, auth, concurrency, compatibility, security,
+     operations, or another narrow target;
+   - require findings to include file location, condition, impact, confidence, and counterexample;
+   - separate confirmed defects from suspicion and questions;
+   - require re-review after fixes when the instruction covers an iterative workflow.
+7. For proof instructions:
+   - state the proposition to prove in one sentence;
+   - list assumptions, environment, data range, versions, and known exclusions;
+   - require independent evidence such as invariants, old-versus-new comparison, negative controls,
+     data hashes, seeds, or replayable artifacts;
+   - separate proved, partially proved, unproved, and out-of-scope claims.
+8. For organize or cleanup instructions:
+   - require inventory before moving or deleting;
+   - classify items as keep, move, merge, delete, or defer;
+   - identify the source of truth;
+   - preserve behavior by default;
+   - split move, compatibility removal, and deletion into separate steps when coexistence matters.
+9. For operational-readiness instructions:
+   - require concrete scale, latency, memory, cost, availability, and data-volume assumptions when
+     they matter;
+   - define timeout, retry, idempotency, partial success, dead-letter, reconciliation, rollback,
+     deployment, health, alerting, and recovery expectations;
+   - ask for operator-facing evidence, not merely more logs.
+10. For interactive CLI, TUI, prompt, picker, or wizard instructions:
+    - require the screen to show the accepted input values before waiting for input;
+    - require model IDs, provider IDs, file names, commands, or other exact tokens to be listed,
+      searchable, or selectable instead of assuming the user already knows them;
+    - define default, cancel, empty input, invalid input, retry, pagination, and no-results
+      behavior;
+    - require captured-output and stream semantics to be checked when the UI is implemented through
+      a shell function, pipeline, wrapper, or command substitution;
+    - require evidence from a real interactive or transcript-style run that the user can complete
+      the choice without hidden knowledge.
+11. Add verification instructions as evidence, not ceremony. Name the configured command intents,
+    manual-only checks, missing checks, or proof artifacts that should close the work.
+12. Add a final-report contract:
+    - root cause or design decision;
+    - changed files;
+    - preserved invariants;
+    - tests and command intents run;
+    - skipped checks and why;
+    - deployment, rollback, or follow-up risks when relevant.
+13. Keep the instruction short enough to execute. Put stable repeated rules into durable repository
+    guidance instead of pasting a long policy into every task.
+14. Review the draft for contradictions:
+    - "minimal change" versus "aggressive refactor";
+    - "no behavior change" versus new feature behavior;
+    - "prove" without independent evidence;
+    - "production-ready" without scale or rollback;
+    - "review everything" without a review blade.
+15. If the task instruction will be stored in a public, packaged, or template surface, synchronize
+    related docs, templates, examples, routes, and review metadata under the matching skill.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The instruction has an observable goal, scoped context, constraints, investigation order,
+  acceptance evidence, verification, and final report contract.
+- The agent is not asked to invent product rules, failure semantics, compatibility promises,
+  release policy, or proof standards unless that decision is intentionally delegated.
+- Durable guidance is separated from one-off task instructions.
+- The instruction avoids hidden chain-of-thought requests and asks for evidence, assumptions,
+  decisions, and remaining risks instead.
+- Interactive instructions expose accepted inputs, fallback behavior, and transcript evidence before
+  requiring the user to type an exact value.
+- The final artifact can be used by another agent without relying on unstated context.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Use a narrower configured docs, package, or template check when the instruction artifact changes an
+installed workflow surface.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the task goal is too vague, produce a short critique and the smallest set of blocking
+  questions instead of inventing missing product decisions.
+- If repository evidence contradicts the user's draft instruction, report the conflict and prefer
+  the higher-authority current source.
+- If the instruction asks for an unsafe or unauthorized command, map it to an existing configured
+  intent, mark it manual-only, or remove it.
+- If the requested proof cannot be produced with current data or command contracts, downgrade the
+  instruction to partial proof and name the missing evidence.
+- If the draft becomes longer than the work itself, split durable rules into repository guidance and
+  leave only task-specific acceptance criteria in the prompt.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Instruction family and target agent surface
+- Missing decisions or contradictions found
+- Final instruction or review rubric
+- Durable guidance promoted or intentionally left one-off
+- Verification and proof expectations
+- Command intents run
+- Skipped checks and reasons
+- Remaining ambiguity, authority, or operational-readiness risk

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.68.6"
+version = "2.70.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -106,6 +106,7 @@ creates = [
   ".mustflow/skills/contract-sync-check/SKILL.md",
   ".mustflow/skills/cross-platform-filesystem-safety/SKILL.md",
   ".mustflow/skills/date-number-audit/SKILL.md",
+  ".mustflow/skills/design-implementation-handoff/SKILL.md",
   ".mustflow/skills/database-change-safety/SKILL.md",
   ".mustflow/skills/database-migration-change/SKILL.md",
   ".mustflow/skills/database-query-bottleneck-review/SKILL.md",
@@ -170,7 +171,9 @@ creates = [
   ".mustflow/skills/security-regression-tests/SKILL.md",
   ".mustflow/skills/secret-exposure-response/SKILL.md",
   ".mustflow/skills/search-ad-content-authoring/SKILL.md",
+  ".mustflow/skills/skill-refresh/SKILL.md",
   ".mustflow/skills/skill-authoring/SKILL.md",
+  ".mustflow/skills/task-instruction-authoring/SKILL.md",
   ".mustflow/skills/template-install-surface-sync/SKILL.md",
   ".mustflow/skills/visual-review-artifact/SKILL.md",
   ".mustflow/skills/visual-review-artifact/resources.toml",
@@ -290,6 +293,7 @@ minimal = [
   "config-env-change",
   "contract-sync-check",
   "date-number-audit",
+  "design-implementation-handoff",
   "database-change-safety",
   "database-migration-change",
   "database-query-bottleneck-review",
@@ -324,6 +328,7 @@ minimal = [
   "secret-exposure-response",
   "source-anchor-authoring",
   "source-freshness-check",
+  "task-instruction-authoring",
   "structure-discovery-gate",
   "structure-first-engineering",
   "test-design-guard",
@@ -421,6 +426,7 @@ patterns = [
   "config-env-change",
   "contract-sync-check",
   "date-number-audit",
+  "design-implementation-handoff",
   "database-change-safety",
   "database-migration-change",
   "database-query-bottleneck-review",
@@ -461,6 +467,7 @@ patterns = [
   "secret-exposure-response",
   "source-anchor-authoring",
   "source-freshness-check",
+  "task-instruction-authoring",
   "state-machine-pattern",
   "strategy-pattern",
   "structure-discovery-gate",
@@ -563,6 +570,7 @@ oss = [
   "contract-sync-check",
   "cross-platform-filesystem-safety",
   "date-number-audit",
+  "design-implementation-handoff",
   "database-change-safety",
   "database-migration-change",
   "database-query-bottleneck-review",
@@ -613,10 +621,12 @@ oss = [
   "security-privacy-review",
   "security-regression-tests",
   "secret-exposure-response",
+  "skill-refresh",
   "skill-authoring",
   "template-install-surface-sync",
   "source-anchor-authoring",
   "source-freshness-check",
+  "task-instruction-authoring",
   "state-machine-pattern",
   "strategy-pattern",
   "structure-discovery-gate",
@@ -717,6 +727,7 @@ team = [
   "contract-sync-check",
   "cross-platform-filesystem-safety",
   "date-number-audit",
+  "design-implementation-handoff",
   "database-change-safety",
   "database-migration-change",
   "database-query-bottleneck-review",
@@ -759,6 +770,7 @@ team = [
   "secret-exposure-response",
   "source-anchor-authoring",
   "source-freshness-check",
+  "task-instruction-authoring",
   "state-machine-pattern",
   "strategy-pattern",
   "structure-discovery-gate",
@@ -857,6 +869,7 @@ product = [
   "config-env-change",
   "contract-sync-check",
   "date-number-audit",
+  "design-implementation-handoff",
   "database-change-safety",
   "database-migration-change",
   "database-query-bottleneck-review",
@@ -901,6 +914,7 @@ product = [
   "search-ad-content-authoring",
   "source-anchor-authoring",
   "source-freshness-check",
+  "task-instruction-authoring",
   "state-machine-pattern",
   "strategy-pattern",
   "structure-discovery-gate",
@@ -1006,6 +1020,7 @@ library = [
   "contract-sync-check",
   "cross-platform-filesystem-safety",
   "date-number-audit",
+  "design-implementation-handoff",
   "database-change-safety",
   "database-migration-change",
   "database-query-bottleneck-review",
@@ -1054,9 +1069,11 @@ library = [
   "security-privacy-review",
   "security-regression-tests",
   "secret-exposure-response",
+  "skill-refresh",
   "template-install-surface-sync",
   "source-anchor-authoring",
   "source-freshness-check",
+  "task-instruction-authoring",
   "state-machine-pattern",
   "strategy-pattern",
   "structure-discovery-gate",