Maestro Impeccable

Plan tracking: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 update_plan({ explanation?, plan: [{ step, status }] }) 维护（整体提交步骤数组，status: pending | in_progress | completed），权威状态始终在 session 工件中；依赖/认领（addBlockedBy/owner）是工件字段，不是工具参数。

If required reading was not expanded by the host, or is no longer in context, Read it explicitly before execution.

Retain the resolved parent as <impeccable-base> for the entire Run. Every path in the bundled Skill and references is relative to that directory; substitute the concrete path before reading a reference or running a script.

Rules:

1. Never resolve or invoke another Skill named impeccable.
2. Never run npx impeccable install, npx impeccable update, or depend on an external Impeccable package during execution.
3. Load the bundled SKILL.md, then only the single command/reference file it routes to. Respect its deferred-reading rules.
4. Run node <impeccable-base>/scripts/context.mjs once per session from the user's project cwd. Do not rerun it after init.
5. Preserve platform routing: audit.native.md / adapt.native.md for native projects; live and the HTML detector are web-only.
6. Preserve bounded verification: one batched inspection/fix pass and at most one confirmation pass. Do not recreate the retired open-ended refine loop.
7. If the bundled core or a required bundled file is missing, stop with E001/E003 and repair the Maestro installation; never fetch or install another Skill as recovery.
8. Impeccable core updates ship only through Maestro source/release updates. Never offer an upstream package update during design work.

Bundled core synchronized from upstream Impeccable Skill 4.1.3 (pbakaus/impeccable@4c5243f) and adapted for Maestro. The bundled copy remains authoritative until Maestro updates it.

Maestro Symbol Style

Use these symbols consistently in Maestro-owned displays. Do not substitute colorful success/failure emoji.

Upstream machine values and required report fields remain unchanged. For an upstream degraded critique banner, normalize only the symbol presentation to ⚠ DEGRADED: single-context (<reason>); do not weaken or omit the degraded disclosure.

Input Routing

Parse $ARGUMENTS without inventing a static workflow chain.

Apply this table top-to-bottom; specific routes override the generic command route.

continue, next, and -c are not Impeccable resume commands. Run/session continuation belongs to the canonical Maestro Session/Run lifecycle in run-mode.md.

Current Impeccable Commands

This table is a routing index only. The bundled workflows/impeccable/SKILL.md and its references own the full instructions.

Normal Execution

1. Attach the canonical Run

   • Follow run-mode.md before design work. If a birth packet says run_already_created: true, consume its exact locator, task, continuation, run_dir, and revisions; never create a duplicate Run.
   • For a self-started invocation, negotiate capabilities and execute the receipt-chained Session open → chain insert → run next flow from run-mode.md.
   • Retain whether this executor has mutation authority. An executor without it may write outputs/report and run read-only checks, but must return completion to the coordinator instead of advancing the Run itself.

2. Resolve bundled core

   • Read the first available bundled SKILL.md defined in <embedded_contract> and retain its parent as <impeccable-base>.
   • Emit E001 only if both bundled paths fail. Do not search external Skill locations.

3. Run bundled setup

   • Follow the loaded bundled core's Setup exactly.
   • Inspect the target and at least one representative source of incumbent visual truth before editing.
   • A missing PRODUCT.md blocks only new-surface or replacement-world work as upstream specifies; it does not block narrow refinement.
   • Report CONTEXT_STALE; never repair drift unless requested or marked auto by upstream.

4. Resolve route

   • Explicit or clearly implied command → load its one owning reference.
   • Two plausible commands → request_user_input once.
   • New surface or replacement visual world → current reference/new-work.md.
   • No arguments → current reference/routing.md; recommendations require confirmation.

5. Display Maestro execution panel

   ── Impeccable: {command|general} ──────────────
   Target: {target|project context}
   Mode: {Persuade|Operate|Read|Experience}
   Platform: {web|ios|android|adaptive|unknown}
   Reference: {relative reference path}
   ──────────────────────────────────────────────
   → Setup
   

   If platform is unknown, do not default to web. Resolve platform from project evidence or run init before platform-sensitive routing; never run live or the HTML detector on an unconfirmed native target.

6. Track major phases

   • Create update_plan items from the loaded reference's major phases; do not invent a generic chain.

   • Format: [impeccable:{command}] {phase}.

   • Mark each phase complete immediately when its verifiable outcome is complete.

   • User-facing progress:

     → [impeccable:{command}] {phase}
     ✓ [impeccable:{command}] {phase}
     ⚠ [impeccable:{command}] {phase} — W###: {reason}
     FAIL [impeccable:{command}] {phase} — E###: {reason}
     

7. Execute bundled reference

   • Follow all current MUST rules, platform variants, output schemas, provenance, and safety boundaries from the bundled reference.
   • Load reference/craft-floor.md immediately before UI edits, never for planning-only work.
   • For critique, preserve dual independent assessment and explicit degraded disclosure. Persist snapshots and report trends only when upstream resolves a non-null slug; otherwise follow its documented skip path.
   • Never assume critique is scored out of 40: excluded heuristics are n/a, and the applicable maximum may vary.

8. Bounded verification

   • Show a gate only when the loaded reference defines one:

     ◆ {gate}: {actual evidence} — PASS|FAIL
     ↺ confirmation pass 1/1
     

   • Do not fabricate a numeric threshold or score.

   • Do not report PASS without actual evidence from the executed check.

9. Finish the Run

   • Write the human-readable synthesis to {run_dir}/report.md using the exact frontmatter vocabulary and whitelist from run-mode.md; put every caveat in concerns.
   • Run maestro run check {run_id} --session {session_id} --json and repair blocking gates.
   • With mutation authority, complete using the exact fenced maestro run complete ... --verdict done|done_with_concerns --advance --json continuation from run-mode.md; parse and retain the returned revisions. Without mutation authority, return the report and check result to the coordinator and do not complete or advance.
   • Follow the completion receipt: dispatch a remaining pending step only when authorized, or complete the Session when the chain is terminal. Never treat the display status below as a substitute for Run completion.

   === IMPECCABLE RESULT ===
   Command: {command|general}
   Target: {target}
   Evidence: {checks, snapshots, detector output, or files}
   Warnings: {none|<warning-code> ...}
   --- STATUS ---
   Status: DONE | FAILED
   

   Suggest only the next step supported by the loaded bundled reference or current findings.

Maestro Codify Extension

Arguments: --codify <source-path> [--package-name <name>] [--output-dir <path>] [--overwrite]

Boundaries:

1. Discovered source inputs are strictly read-only. Canonicalize and snapshot the source file list before creating workspaces; exclude --output-dir, .workflow/codify-temp-*, {run_dir}, and other generated directories from discovery, even when they are nested beneath source_path. Never edit a discovered source file.
2. User-facing package writes stay under --output-dir (default .workflow/reference_style/). Maestro runtime writes may also use the exact {run_dir}/report.md, {run_dir}/outputs|evidence|work, and the phase-scoped .workflow/codify-temp-* directory required by the referenced workflows.
3. Governed knowledge/spec corpus files are never written directly. Phase 4 may create the manifest and stage candidates with explicit --run {run_id}; review/promotion occurs after sealing under run-mode.md.
4. Load each deferred workflow only when its phase starts.
5. Never overwrite an existing package without --overwrite. With --overwrite, clear the validated target package before generation or build in a fresh temporary package and replace it; artifact checks must prove current-Run provenance and must not pass on stale files.
6. Phase 2 runs Style, Animation, and Layout extraction in parallel as ui-codify.md specifies; do not invent a token-first dependency.
7. Ask the user before knowhow candidate generation.
8. Verify the requested artifact scope and candidate stage receipts before terminal status.
9. Always clean the phase temporary directory on success, failure, or preview-only exit.

Display:

── Impeccable: codify ─────────────────────
Source: {source-path}
Output: {output-dir}
───────────────────────────────────────────
→ Phase 1: Validate + workspace setup
◆ GATE 1: source and output policy valid
→ Phase 2: Parallel extraction (Style + Animation + Layout)
◆ GATE 2: extraction artifacts satisfy ui-codify.md
→ Phase 3: Reference package
◆ GATE 3: current-Run preview and required token/layout artifacts exist
→ Phase 4: Manifest + governed candidate staging (confirmation required)
◆ GATE 4: knowhow-manifest.json + stage receipts recorded

At the Phase 3 → 4 gate, request_user_input:

• 继续生成 knowhow — generate the manifest and stage governed candidates with --run {run_id}; promotion remains post-seal
• 仅保留 preview，跳过 knowhow — clean the temporary directory, verify preview-only artifacts, and finish with an explicit preview-only scope report

Codify diagnostics originate in the referenced workflows. Translate them for Maestro-owned output so they do not collide with normal-mode codes:

• workflow E001 → C001 (source argument missing)
• workflow E002 → C002 (source missing/not a directory)
• workflow E003 → C003 (package exists without --overwrite)
• workflow W001 → CW001 (optional animation tokens missing; continue without animation tokens)

Follow the referenced workflows for all other phase instructions and recovery. For every Phase 4 stage command, this adapter additionally requires explicit --run {run_id}, a defined valid --category (never undefined), and a captured candidate receipt. Stage only; never write or promote governed corpus files during the active Run.

Codify mode:

• Source remained read-only; package, temporary, and Run writes stayed within declared boundaries
• Deferred workflows were phase-loaded and parallel extraction semantics were preserved
• Overwrite/current-Run provenance prevented stale artifacts from passing gates
• Knowhow candidate generation required explicit user confirmation and used --run {run_id}
• Requested artifact scope and stage receipts were verified before terminal status
• Temporary workspace was cleaned on every exit path