Use when the task involves reading, creating, or editing `.docx` documents, especially when formatting or layout fidelity matters; prefer `python-docx` plus the bundled `scripts/render_docx.py` for visual checks.

2026-05-312

name	codex-workflow-autopilot
description	Use after intent is known to route build, fix, review, debug, docs, or Scrum requests into ordered workflow steps with exit criteria.
load_priority	on-demand

TL;DR

Route tasks by complexity: complex -> Thinking Partner + Devil's Advocate, teaching -> Teaching Mode + explain_code.py, simple -> direct execution. Map intent to workflow (build/fix/review/debug/docs). Use BMAD 4-phase for complex. Always end with Phase X quality gate.

Workflow Autopilot

Activation

Activate after intent analysis is confirmed.
Activate on explicit $codex-workflow-autopilot or $route.
Activate teaching mode on $teach, "explain", or "walk me through".
Activate Scrum overlay on backlog, story, sprint, review, retrospective, release-readiness, or shorthand commands such as $sprint-plan, $story-ready-check, $retro, and $release-readiness.
Activate reasoning rigor on $codex-reasoning-rigor, $rigor, "don't be generic", "go deeper", "make it specific", or "use the repo, not generic advice".
Activate on alias triggers: $plan, $debug, $create, $prototype, $review, $deploy, $handoff, $refactor.
When activated via alias, load the corresponding .workflows/<name>.md file before executing the flow.
Activate brainstorm mode on $brainstorm, "brainstorm", "think through options", or "explore approaches".
Activate review-feedback routing on $review-feedback, "address review feedback", or "respond to code review".
Route "prototype", "MVP", "fullstack", "from scratch", or "build whole app" to $prototype and require codex-spec-driven-development before implementation.
Activate project pulse on $today, $pulse, $daily, $status, $brief, "hôm nay thế nào?", "what's next?", "what should I work on?", or "project status". Route to codex-project-pulse.

Behavioral Protocol Decision Tree

Agent context loaded?
    |- Yes -> apply agent behavioral rules + file_ownership boundaries
    |   `- Then route to the matching workflow mode or alias file
    |
    `- No -> fallback to existing keyword-based mode detection
        |
        `- Task complexity?
            |- Complex (architecture/design/multi-file) -> activate Thinking Partner mode
            |   `- Before presenting solution -> activate Devil's Advocate mode
            |
            |- Teaching request -> activate Teaching Mode + explain_code.py
            |
            `- Simple (single file fix) -> direct execution

Behavioral Modes

Signals	Mode	Behavior
what if, ideas, options	brainstorm	ask clarifying questions and present alternatives, no code
think with me, compare options, help me decide	thinking-partner	co-think with tradeoff-first framing and explicit decision criteria
build, create, implement	implement	execute quickly with production-focused output, enforce TDD
prototype, MVP, fullstack, from scratch	prototype	run `$hook` -> `$init-profile` if needed -> `$genome`/`$init-docs` -> `$spec` -> `$plan` -> implementation -> `$check-full`
test first, TDD, red-green, failing test	tdd	enforce RED-GREEN-REFACTOR cycle via `$tdd`, no production code without failing test
error, bug, broken	debug	4-phase systematic debugging via `$root-cause`: root cause → pattern → hypothesis → fix
review, audit, check	review	inspect and report findings by severity
challenge this, poke holes, red team, counterargument	devils-advocate	stress-test assumptions, expose risks, and propose mitigations
explain, teach, learn	teach	explain progressively with examples
deploy, release, ship	ship	prioritize stability and complete checks

Scrum Overlay Trigger

Trigger Scrum overlay when the request mentions:

backlog, user story, acceptance criteria, refinement
sprint planning, sprint backlog, sprint goal, daily scrum
sprint review, retrospective, release readiness
product owner, scrum master, cross-functional handoff
Scrum shorthand aliases such as $scrum-install, $scrum-update, $sprint-plan, $story-ready-check, $story-delivery, $retro, and $release-readiness

Load and apply: references/workflow-scrum.md. Keep the routing contract in sync with references/workflow-routing-contract.json.

Rules:

keep the base workflow (build, fix, debug, review, or deploy) for the actual engineering work
add a Scrum coordination layer when the request depends on ceremony output or multi-role handoffs
recommend codex-scrum-subagents when the project needs a local .agent kit for repeatable role briefs and workflows
if a story is not ready, route back to refinement instead of coding immediately

Reasoning Rigor Trigger

Trigger this overlay when the user asks for:

deeper thinking or stronger tradeoffs
less generic output
more evidence, monitoring, or explicit risks
repo-grounded recommendations instead of generic best practices

Load and apply: codex-reasoning-rigor.

Rules:

force a task contract before solutioning
compare at least 2 options when tradeoffs are non-trivial
add evidence, risks, and next-step contract to the output
recommend $output-guard before finalizing high-stakes written deliverables

Thinking-Partner Trigger

Trigger this mode when user asks for collaborative reasoning rather than immediate implementation.

Signal examples: "think with me", "compare options", "which approach is better", "help me decide".
Load and apply: references/thinking-partner-mode.md.
Ask focused clarifying questions before proposing workflow.
Present option matrix with tradeoffs, risks, and recommended path.
Convert selected path back to workflow steps and exit criteria.

Devil's Advocate Trigger

Trigger this mode when user asks for challenge, risk probing, or plan hardening.

Signal examples: "be critical", "find blind spots", "red team this plan", "play devil's advocate".
Load and apply: references/devils-advocate-mode.md.
Attack assumptions explicitly and rank findings by impact/likelihood.
Provide mitigation actions and clear stop/ship criteria.
Return to normal workflow mode only after key risks are addressed or explicitly accepted.

Teaching Mode Trigger

Trigger this mode when user asks to understand project code, not to modify it.

Signal examples: $teach, "explain this", "teach me", "how does this work", "walk me through".
Load and apply: references/teaching-mode-spec.md.
Prefer project-specific explanation over generic language/framework theory.
Use scripts/explain_code.py as optional context helper for functions/imports/imported-by mapping.
Output in four layers: what, how, why, connections, then gotchas.
Keep scope tight to user request (function/file/module) and avoid unnecessary full-file dumps.

Intent to Workflow

Intent	Steps	Exit Criteria
build	analyze → plan ($plan) → isolate ($worktree) → TDD implement ($tdd) → test → gate	tests pass, TDD verified, gate pass
prototype	preflight ($hook) -> profile/context/docs -> spec ($spec) -> plan ($plan) -> TDD implementation -> role-doc/knowledge update -> full gate	spec exists, acceptance criteria pass, full gate pass or advisory warnings listed
fix	systematic debug ($root-cause) → root-cause → regression test ($tdd) → fix → gate	root cause found, regression test pass, gate pass
review	inspect → categorize findings → recommend actions	findings documented with severity
debug	systematic debug ($root-cause) → Phase 1-4 → test → gate	verified fix with evidence, gate pass
docs	scope change → update docs → verify links/accuracy → gate	docs updated and verified

Scrum Ceremony Routing

Scrum Signal	Suggested Ceremony	Base Workflow	Recommended Roles
vague backlog item, user story, acceptance criteria	backlog refinement	build	product-owner -> scrum-master
sprint planning, sprint goal, forecast	sprint planning	build	scrum-master -> product-owner -> delivery leads
blocker, dependency, daily sync	daily scrum	debug	scrum-master
ready story in sprint	story delivery	build or fix	scrum-orchestrator + delivery roles + qa-engineer
sprint demo, stakeholder feedback	sprint review	review	product-owner + scrum-master + qa-engineer
process issue, improvement experiment	retrospective	review	scrum-master + squad
ship decision, rollback, release gate	release readiness	deploy	scrum-master + qa-engineer + security-engineer + devops-engineer

BMAD for Complex Requests

Use BMAD when intent analysis marks complexity: complex.

Phase 1: Analysis (no code)

confirm requirements and constraints
inspect existing patterns
capture key decisions

Phase 2: Planning (no code)

create plan via $codex-plan-writer or $plan
define task-level input/output/verify

Checkpoint: wait for explicit user approval before Phase 3.

Phase 3: Solutioning (no code)

finalize architecture and data flow decisions
identify cross-file impacts

Phase 4: Implementation (code)

For complex tasks: Set up isolated workspace via $worktree
For plan with independent tasks: Use subagent execution via $sdd
For all code changes: Follow TDD cycle via $tdd
implement task by task
run tests/docs as workflow requires

Phase X: Verification (always last)

Run $codex-execution-quality-gate or $gate.
If gate fails, fix blockers and rerun.
Do not declare completion before gate decision.
Use $finish to handle branch completion if using worktree.

Reference Files

references/workflow-routing-contract.json: machine-checkable routing contract for modes, overlays, and output fields.
references/thinking-partner-mode.md: use only when collaborative option analysis is requested.
references/devils-advocate-mode.md: use only when explicit challenge/risk probing is requested.
references/teaching-mode-spec.md: use when user asks for code walkthrough, explanation, or teaching.
references/workflow-scrum.md: use when the request maps to Scrum ceremonies, story readiness, or release readiness.
references/workflow-create.md: execution template for new feature workflows.
../.workflows/prototype.md: alias workflow for MVP/fullstack prototype execution.
references/workflow-debug.md: execution template for debugging workflows.
references/workflow-review.md: execution template for review workflows.
references/workflow-refactor.md: execution template for refactoring workflows.
references/workflow-deploy.md: execution template for deployment workflows.
references/workflow-handoff.md: execution template for session handoff workflows.
references/workflow-plan.md: execution template for planning and BMAD Phase 1-2 workflows.
../.workflows/plan.md: alias workflow for planning and BMAD Phase 1-2.
../.workflows/debug.md: alias workflow for 4-phase debugging.
../.workflows/create.md: alias workflow for build-mode execution.
../.workflows/review.md: alias workflow for review plus written-output quality checks.
../.workflows/deploy.md: alias workflow for ship preparation and full gate.
../.workflows/handoff.md: alias workflow for session transfer and summary generation.
../.workflows/refactor.md: alias workflow for restructuring and simplifying code.

Helper Script

scripts/explain_code.py: optional context helper for functions, imports, and imported-by mapping.
See skills/.system/REGISTRY.md for full script paths.

Script Invocation Discipline

Always run --help before invoking a script.
Treat scripts as black-box helpers and prefer direct execution over source inspection.
Read script source only when customization or bug fixing is required.

Overrides

"skip test": remove test step and warn quality confidence is reduced.
"no docs": remove docs step and warn maintainability confidence is reduced.
"just do it": default to build workflow and still show brief step plan.
"skip plan": allow for simple scope; for complex scope warn and reconfirm.

Scope Heuristic

small: 1-3 files, single concern
medium: 4-10 files, multiple concerns
large: 10+ files or architectural impact

Output Contract

Return fenced JSON in conversation:

{
  "mode": "brainstorm | thinking-partner | implement | tdd | debug | review | devils-advocate | teach | ship",
  "workflow_type": "build | fix | review | debug | docs | refactor | deploy | handoff",
  "steps": ["step1", "step2"],
  "exit_criteria": ["criterion1"],
  "estimated_scope": "small | medium | large",
  "phase": "analysis | planning | solutioning | implementation | verification",
  "coordination_overlay": "none | scrum",
  "ceremony": "none | backlog-refinement | sprint-planning | daily-scrum | story-delivery | sprint-review | retrospective | release-readiness"
}

Primary execution remains sequential by default. Native Codex custom agents can participate when they are installed and explicitly selected.