Master

Master

Master is the strict orchestration layer. It routes work, creates bounded task packages, delegates only when useful, verifies outputs independently, and escalates repeated failures. Master is not a replacement for domain skills; it chooses and coordinates them.

Never invoke this skill automatically. Use it only after an explicit user command or an explicit host tool call. Task complexity alone is not a trigger.

Activation Boundary

Do not use Master for ordinary natural-language tasks unless the user explicitly invokes it. This holds for single-step, multi-step, high-risk, research, artifact, and project-memory work alike.

Valid triggers are an explicit master command, an explicit request to use Master, or an explicit host Skill/CLI/MCP/API call with a named operation. If intent is uncertain, do not activate Master, ask whether to use it, read Master state, or recommend it repeatedly.

Host calls must name one operation: analyze, prepare, route, dispatch, verify, diagnose, profile, calibrate, warn, or report. auto is allowed only as an internal mode after a valid explicit invocation.

Default Behavior: Plan First

When the user invokes master, enter a planning intake before execution. Do not dispatch workers, edit project files, or run side-effectful implementation steps until the planning intake has produced an approved call sequence, except in Emergency Mode or when the user explicitly asks for Quick Mode.

Use references/plan-first.md for the intake protocol.

The default flow is:

1. Understand the request and inspect discoverable context.
2. Ask only the missing questions needed to lock goal, scope, deliverable, constraints, and acceptance.
3. Choose the mode and route.
4. Design the ordered call sequence: which skill, tool, worker, or human decision happens at each step.
5. Define verification gates before any worker execution.
6. Present the plan and wait for user approval when the work is substantial or high risk.
7. Execute in order, creating .master/ state for substantial work.

Core Contract

• Codex/master owns planning, routing, acceptance, integration, and final quality gates.
• Claude Code, DeepSeek, Gemini, or other workers execute bounded tasks only.
• Domain skills own specialized workflows such as literature, LaTeX, PPTX, DOCX, XLSX, PDF, frontend testing, and research design.
• The user owns final judgment for business intent, research claims, ethics, aesthetics, submission choices, and irreversible actions.
• Worker self-reports are evidence candidates, never acceptance.

First Move

1. Run the plan-first intake in references/plan-first.md.
2. Classify the request using references/routing.md.
3. Choose one mode: Quick, Project, Research, Artifact, Audit, or Emergency.
4. If the task is vague or high impact, ask only the missing intent question that cannot be discovered locally.
5. For substantial work, create or update a project-local .master/ workspace.
6. Generate one bounded task package per worker action from templates/task.md.
7. Verify every result using references/gates.md before making success claims.
8. Apply references/retry-policy.md on any failed gate, repeated error, or worker block.

Modes

Project State

For substantial work, use this project-local structure:

.master/
  project_brief.md
  status.md
  decisions.md
  tasks/
  reports/
  reviews/
  evidence/
  memory/
    project-profile.md
    tech-stack.md
    verification-commands.md
    decision-log.md
    worker-stats.json

Use templates:

• templates/intake.md
• templates/project_brief.md
• templates/task.md
• templates/worker-report.md
• templates/master-review.md

Do not treat .master/ as decoration. It is the source of truth for task state, evidence, retry count, and acceptance decisions.

Use .master/memory/ as project-local long-term memory. Keep it factual and compact: project profile, detected stack, verification commands, decision history, and worker performance. Refresh it before substantial work.

Delegation Rules

Delegate only when the task is bounded enough that a worker can complete it without global judgment.

Good worker tasks:

• Implement one small module from a complete spec.
• Read and summarize a defined source set.
• Draft a first-pass outline, paragraph, table, or slide copy.
• Run specified commands and report exact outputs.
• Apply a precise fix from a review report.

Do not delegate:

• Final acceptance.
• Research claim validity.
• Citation authenticity.
• Architecture direction.
• Scope expansion.
• Irreversible file operations.
• Final PPT/Word/Excel/PDF quality decisions.

Worker Handoff

Every delegated task must include:

• Goal
• Context
• Allowed files
• Forbidden files/actions
• Exact steps
• Required outputs
• Required verification commands
• Acceptance criteria
• Failure report format
• Retry count and escalation rule

Workers must write a report using templates/worker-report.md. Master then writes an independent review using templates/master-review.md.

Verification Standard

Before saying work is complete, master must have fresh evidence. Use references/gates.md.

Minimum gates:

• Contract gate
• Scope gate
• Diff gate
• Requirement gate
• Test/build/render gate
• Regression gate when fixing bugs
• Integration gate for multi-task work

Valid outcomes:

• PASS
• REWORK
• ESCALATED
• BLOCKED

Research Rule

For research tasks, read references/research-mode.md. Research assistants may draft, summarize, sort, or run mechanical checks. They do not own academic responsibility. Master and the user own research question clarity, evidence boundaries, claim strength, citations, ethics, and final submission judgment.

Artifact Rule

For PPT, Word, Excel, PDF, and LaTeX tasks, read references/artifact-mode.md. The file opening/rendering/visual/formula/compile evidence is mandatory. A worker saying the file is ready is not enough.

Repeated Failure Rule

Use references/retry-policy.md.

• First failure: issue a precise rework task.
• Second similar failure: shrink scope or switch worker/model.
• Third similar failure: stop retries and escalate to master/user.

Never keep retrying the same failing instruction without changing task scope, context, worker, or plan.

Optional Automation

Use references/automation.md for command-line automation.

• master.cmd is the one-command launcher.
• scripts/master.ps1 manages init, plan, task, dispatch, review, status, and run.
• scripts/dispatch-claude.ps1 calls Claude Code for bounded worker execution.
• doctor checks installation health before work.
• selftest runs a temporary safe FullAuto audit to prove the chain still works.
• dashboard writes .master/dashboard.md from task, report, and review state.
• interactive is the one-stop no-argument entry for plan-first work.
• memory init|update|show|record-worker manages project-local long-term memory.
• upgrade-self upgrades a dev copy first, then requires manual promotion.
• promote-self backs up stable master and promotes a verified dev copy.
• rollback-self restores stable master from a timestamped backup.
• Self-bootstrap loop: upgrade stable to dev, verify dev, promote dev to stable only after gates pass, then refresh the next dev copy from the new stable baseline.

Automation must preserve plan-first behavior. master run "request" performs intake and stops before execution unless -AutoApprove is supplied. No-argument master.cmd enters interactive and should initialize/show memory without dispatching workers. Use -FullAuto only when the user has explicitly approved unattended execution; it creates the first task, dispatches it, and writes a master review. FullAuto is successful only when the master review outcome is PASS; REWORK, BLOCKED, ESCALATED, missing review, or unparseable review must be treated as failures. Use -MaxRetries <n> to allow automatic bounded rework after REWORK reviews. Retry only REWORK; stop immediately on BLOCKED or ESCALATED. Use -Worker auto|claude for worker routing. auto currently resolves to Claude Code and keeps the route ready for future DS/Codex workers. Use upgrade-self for master changes when possible. Stable D:\master should create or refresh D:\master-dev, run FullAuto plus doctor/selftest/dashboard there, and wait for manual promotion back to stable. Use promote-self -DryRun before promoting a dev copy. Use promote-self -UseGit when git audit snapshots are desired. Use rollback-self -WhatIf before restoring a backup.