Skip to content
DHF Written Specification

Lifecycle and skill routing.

The complete stage map for moving from recovered facts to bounded work, fresh verification, and a recoverable handoff.

Source file: docs/LIFECYCLE_SKILL_ROUTING.md (maintainer entry). Regenerate this HTML page after changing the source file.

Lifecycle And Skill Routing

DHF_PUBLIC_STATUS_V1 · 2026-08-03: This router documents the current stage-based source architecture. Source availability does not prove runtime activation or publication. See the canonical status in English or 中文. The proposed light/standard/governed simplification profiles are not active.

Purpose

This document explains which workflows MyCodexEnv covers, how the Harness Runtime maps work to lifecycle stages, and which Codex/gstack skills should be used at each stage.

MyCodexEnv has three layers:

  • Runtime layer: AGENTS.md, hooks, tool policy, evidence schema, verification scripts, and checkpoint helpers.
  • Router layer: delivery-harness-framework, which reads durable state, classifies the lifecycle stage, and selects the next workflow.
  • Specialist layer: repo-specific lifecycle adapters, gstack skills, local planning/testing/review skills, and deterministic helper scripts.

The generic lifecycle skill should stay generic. Project-only paths, fixtures, checks, smoke matrices, and business safety boundaries belong in repo-specific adapter skills.

DHF Source-Stage Contract Mirror

Canonical profile and Result Invariant semantics live in codex/skills/delivery-harness-framework/SKILL.md; routing and rollout-switch behavior live in codex/hooks/dhf_preprompt.py.

  • Governance profiles are light, standard, and governed.
  • Generic injection requires explicit generic activation; an ordinary non-project prompt stays continue-only. Opt-out is evaluated before every route. The dispatcher recognizes the ShipQ project boundary and directly lazy-delegates; generic DHF must not recover, read shared state, or pre-classify before the ShipQ adapter owns the task.
  • Every completion preserves exactly result, scope_and_constraints, verification_receipt, and remaining_risk_or_next_action; profile-specific ceremony is conditional rather than repeated by default.
  • The source simplified route uses DHF_PREPROMPT_SIMPLIFIED_PROFILES=1; values 0, false, off, and legacy roll back. Runtime evidence must report either source_stage_unsynced or runtime_promoted and reject drift.

Visual Guides

  • docs/dhf-architecture-status-en.html: canonical English source/runtime/publication status.
  • docs/dhf-architecture-status-cn.html: canonical Chinese source/runtime/publication status.
  • docs/index.html: Chinese Delivery Harness Framework public landing page for GitHub Pages.
  • docs/index-en.html: English Delivery Harness Framework public landing page for English readers.
  • docs/dhf-workflow-skills-cn.html: 中文 DHF workflow skills matrix，逐步列出每个阶段使用的 skill、职责说明和 GitHub 源码链接。
  • docs/dhf-workflow-skills-en.html: English DHF workflow skills matrix with stage-by-stage skill explanations and GitHub source links.
  • docs/delivery-harness-beginner-guide-cn.html: 中文 beginner guide，用一句话定义、三层架构、五步流程、例子和术语表解释 Delivery Harness Framework。
  • docs/project-lifecycle-harness-flow-cn.html: 中文纵向主流程图，帮助用户从入口、状态恢复、阶段分类一路看到验证、发布和交接。
  • docs/project-lifecycle-harness-flow-skills.html: 中文 skill/helper 路由速查页，帮助用户理解每个生命周期阶段应使用哪个 skill，以及 helper 的执行职责。
  • docs/project-lifecycle-harness-flow-skills-zh-status-style.html: 新版中文 Delivery Harness Framework skill/helper 路由图，使用和 LinkedIn 素材一致的状态风格。
  • docs/project-lifecycle-harness-flow-skills-en-status-style.html: English status-style Delivery Harness Framework flow map for public sharing.
  • README.md: top-level quick start and Harness Runtime overview.
  • docs/repo-index.md: low-token repo navigation and runtime surface index.
  • docs/index.html: Chinese public Delivery Harness Framework docs entry.
  • docs/index-en.html: English public Delivery Harness Framework docs entry.
  • docs/dhf-workflow-skills-cn.html: Chinese workflow skill inventory with GitHub links.
  • docs/dhf-workflow-skills-en.html: English workflow skill inventory with GitHub links.
  • docs/delivery-harness-beginner-guide-cn.html: beginner-oriented Chinese explanation.
  • docs/HARNESS_RUNTIME.md: lifecycle, evidence, checkpoint, permission, and subagent contracts.
  • docs/AGENT_HARNESS_STATUS.md: Agent Harness workflow/infra status map.
  • docs/CODEX_ENV_REPRODUCTION.md: Codex + Claude environment reproduction guide.
  • docs/project-lifecycle-harness-flow-cn.html: Chinese vertical lifecycle flow.
  • docs/project-lifecycle-harness-flow-skills.html: Chinese lifecycle skill/helper routing visual guide.
  • docs/project-lifecycle-harness-flow-skills-zh-status-style.html: current styled Chinese lifecycle skill/helper routing visual guide.

Covered Workflows

Workflow What It Covers Primary Entry
Environment reproduction Clone, bootstrap, sync Codex/Claude homes, install pinned prerequisites, verify local setup. README.md, bootstrap.sh, scripts/verify_codex_env.sh
Global rules and repo routing Keep cross-repo Codex rules in one source and route repo-local constraints through AGENTS.md. codex/AGENTS.md, root AGENTS.md, scripts/manage_agents.py
Skill synchronization Keep codex/skills/* as source of truth and copy managed skills into ~/.codex/skills/*. scripts/sync_codex_home.sh
Harness lifecycle routing Recover state, classify phase, choose generic/repo-specific/gstack workflow, define gates. delivery-harness-framework
Requirements and planning Capture success criteria, scope, constraints, domain docs, ADR conflicts, vertical slices, risks, and validation gates before implementation. planner, req-to-dev, task-flow-orchestrator, scripts/harness_requirements.py
Backlog-ready issue/spec authoring Turn vague implementation intent into a bounded issue or executable spec before coding starts. vendored gstack spec, delivery-harness-framework
Development execution Make scoped repo changes, use tests first when behavior changes, preserve unrelated user work. tdd-guide, atdd-guide, repo-local workflow
Validation and evidence Run fresh tests/checks and record check, how it exited, what it showed, when it ran. verification-loop, scripts/harness_evidence.py, scripts/harness_report.py
Review and QA Inspect diffs, browser behavior, security/privacy boundaries, and user-visible regressions. gstack-review, code-reviewer, gstack-qa, security-reviewer
Committee review loop Run an explicit expert-committee scoring loop with a separate revision worker until a target rating is met. committee-review-loop
Ship and deployment Commit/PR/release/deploy/canary only when explicitly requested and verified. gstack-ship, gstack-land-and-deploy, gstack-canary
Handoff and recovery Append state, preserve next safe task, recover without chat history, and optionally save/restore user-facing gstack context. scripts/harness_checkpoint.py, scripts/harness_recover.py, vendored gstack context-save / context-restore
Documentation release Keep README/docs aligned with shipped behavior and skill/runtime changes; generate missing docs, polished artifacts, or source-backed diagrams when requested. gstack-document-release, vendored gstack document-generate, vendored gstack make-pdf, vendored gstack diagram, doc-updater

Lifecycle Stage Map

Stage Signals Default Permission Skill Or Helper Purpose
research Unknown repo, stale handoff, unclear source ownership, missing context. Read-only. delivery-harness-framework, scripts/harness_recover.py, scripts/harness_env_probe.py Read durable sources and recover the next safe task before acting.
requirements Goal, audience, acceptance criteria, scope, constraints, or domain language are unclear. Read-only. planner, req-to-dev, scripts/harness_requirements.py Turn ambiguity into success criteria, read CONTEXT.md / CONTEXT-MAP.md and relevant ADRs when present, then validate requirements artifacts before treating them as source of truth.
planning The user wants a backlog-ready GitHub issue, ticket, or executable spec before implementation begins. Read-only by default. vendored gstack spec, delivery-harness-framework Preserve runtime state, lane boundaries, and validation gates while turning vague intent into a bounded spec or issue.
planning Architecture, API shape, migration, runtime, data flow, cross-module decisions, or multi-step work breakdown. Read-only by default. gstack-plan-eng-review, planner, task-flow-orchestrator Produce an implementation plan, vertical slice breakdown, risk list, and validation gate before edits.
development Acceptance criteria are clear and touched files/modules are bounded. Scoped writes. tdd-guide, atdd-guide, repo workflow, scoped worker agents Implement the change with tests appropriate to the risk.
validation Work is implemented or docs/config changed and needs fresh evidence. Tests/checks by default. verification-loop, scripts/harness_report.py, scripts/verify_codex_env.sh Prove the result with fresh check output and required evidence fields.
review Diff exists, work is near handoff/PR/landing, or user asks for review. Read-only by default. gstack-review, code-reviewer, review-swarm, security-reviewer Find bugs, regressions, security risks, and missing tests before shipping.
review User explicitly asks for a committee, expert panel, subagent reviewer/worker split, rating loop, or improvement until a score such as 9.5/10. Committee read-only; revision worker scoped writes. committee-review-loop, scripts/harness_agent_team.py Keep ordinary review routes separate while iterating committee findings into bounded, verified revisions.
ship User requests commit, push, PR, merge, release, deploy, production verification, or version-slot queue visibility. Requested release actions only. gstack-ship, gstack-land-and-deploy, gstack-canary, vendored gstack landing-report Complete release steps, verify deployment, and preserve rollback or version-queue context.
handoff Session is ending, task crosses phases, work spans sessions, next safe task must survive, or the user asks to save/restore working context. Docs/state only unless a gstack context skill is explicitly invoked. scripts/harness_checkpoint.py, vendored gstack context-save / context-restore, gstack-retro, gstack-learn Append harness checkpoint state, capture blockers, preserve resumable user context, and leave a recoverable next step.

Specialist Skill Map

Skill Use For Notes
delivery-harness-framework Generic startup/resume routing, durable state reads, phase classification, helper selection, evidence expectations. Use first for complex or resumed work; delegate after phase selection.
repo-specific lifecycle harnesses Project paths, local checks, business fixtures, deployment topology, smoke matrices. These adapters take over after the generic router identifies a repo-specific boundary.
gstack-plan-ceo-review Product framing, user value, scope, demo boundaries, strategic tradeoffs. Use when product judgment is the work.
vendored gstack spec Backlog-ready GitHub issues, tickets, and executable specs with explicit acceptance criteria before implementation begins. Use when the work needs a durable spec artifact rather than immediate coding.
gstack-office-hours Founder-style pressure testing, market/user/business clarity. Useful before committing to a product direction. In gstack 1.52.x, it can use configured gbrain context during planning preflight.
gstack-plan-eng-review Architecture, data model, API contract, migration, performance, test strategy, and distribution/publish readiness for new artifacts. Use before implementation on complex engineering plans; the current upstream workflow is explicitly search-aware, completeness-biased, and brain-aware when gbrain is configured.
gstack-plan-design-review UX structure, visual direction, responsive behavior, design acceptance, and mockup-first plan refinement. Use before UI implementation or major design changes. When a design binary/mockup path exists, prefer visual review over prose-only critique; when gbrain is configured, let the planning skill consume it as specialist context.
gstack-qa Browser QA, screenshots, console/network checks, responsiveness, accessibility smoke, then iterative bug fixing with regression evidence. Use for user-facing web behavior when fixes are allowed.
gstack-qa-only Report-only QA when fixes should not be applied automatically. Keeps QA read-only.
gstack-ios-qa Real-device iOS QA on a live app via the embedded StateServer and agent loop. Use for "test my iPhone app", device-only bug hunts, or live iOS smoke runs.
gstack-ios-design-review Real-device iOS visual audit against Apple HIG and app design intent. Use for shipped iOS UI review, not pre-implementation design planning.
gstack-ios-fix Closed-loop iOS bug fixing after a real-device repro exists. Use when an iOS defect should be fixed, redeployed, and reverified autonomously.
vendored gstack ios-sync / ios-clean Maintain or remove the gstack iOS debug bridge and debug-only instrumentation. Use only for explicit iOS bridge regeneration or release-cleanup requests.
gstack-cso Infrastructure-first security and privacy review. Use for auth, tokens, secrets, PII, or public/private boundaries.
security-reviewer Code-level security review for validation, auth, injection, secret leakage, error disclosure. Good for narrower security audits.
gstack-review Pre-landing diff review, specialist checks, and fix-first handling of mechanical findings. Use near PR, handoff, or ship; current upstream review is explicitly geared toward auto-fixing low-risk findings before asking.
code-reviewer Local code review of staged or unstaged changes. Use for focused findings with file/line references.
review-swarm Parallel read-only review across behavioral/security/performance/test risks. Use when the user asks for multi-agent review.
committee-review-loop Explicit expert-committee/subagent loops with scoring, revision briefs, and a target rating such as 9.5/10. Do not use for one-off design/code/QA review; preserve read-only committee roles and bounded revision-worker write sets.
gstack-ship Opinionated release workflow before PR/landing, including coverage audit, plan-completion audit, pre-landing review, PR title/version hygiene, and documentation sync. Only use when user asks to ship.
gstack-land-and-deploy Merge and deploy workflow with post-deploy checks. Requires explicit release/deploy intent.
gstack-canary Post-deploy canary monitoring. Use after deploy when live behavior must be watched.
gstack-document-release Post-ship documentation update across README/docs/CHANGELOG/TODOS/VERSION, with coverage-map and documentation-debt checks. Use when docs must reflect shipped behavior.
vendored gstack document-generate Missing tutorials, how-to docs, reference pages, or explanatory docs for a feature/module/project. Use when documentation must be created from scratch rather than just updated after release.
vendored gstack make-pdf Convert Markdown into a polished PDF artifact. Use for publication-quality exports, not routine repo docs.
vendored gstack diagram Turn an English description or mermaid source into a diagram triplet (.mmd, editable .excalidraw, rendered SVG/PNG). Use for offline source-backed diagrams that may later be embedded into docs or exported through make-pdf.
vendored gstack landing-report Read-only version queue and PR landing visibility before ship. Use when asking what version slot or landing order comes next.
vendored gstack context-save / context-restore User-facing save/resume of working context across sessions or Conductor workspaces. Use alongside, not instead of, scripts/harness_checkpoint.py; the harness checkpoint remains the repo-local append-only state source.
vendored gstack scrape / skillify Read-only browser data extraction and codifying repeated scrape flows into browser-skills. Use for extraction workflows; use gstack-qa for behavior testing and bug fixing.
vendored gstack setup-gbrain / sync-gbrain Configure or refresh optional gbrain-backed repo memory/search. Use only when the user explicitly wants gbrain setup, refresh, or repo re-indexing.
gstack-plan-tune Tune repeated planning questions, developer profile preferences, and question-memory behavior. Use only when the user asks to tune how gstack asks questions or to inspect/update developer profile signals; this is operator preference state, not repo lifecycle state.
doc-updater Targeted docs/codemap/README updates for feature, API, or structure changes. Use for repo-local documentation maintenance.
verification-loop Build/static/test/coverage/security verification before completion. Use when a full validation loop is required.
tdd-guide Test-first implementation for behavior changes and bug fixes. Use before writing production code.
atdd-guide Acceptance-test-first workflow for business-facing criteria. Use when external behavior and acceptance scenarios matter.
planner Requirement analysis, architecture sorting, task decomposition, risk detection. Use for complex features and refactors.
task-flow-orchestrator Ordered execution across Karpathy, Planner, TDD, and verification workflows. Use when the task needs workflow sequencing.
skill-evaluator Skill existence, routing, eval matrix, baseline comparison, off-target load diagnosis. Use before expanding or revising critical skills, especially when upstream workflow text changed and routing precision may drift.
visual-explainer Self-contained HTML diagrams, flowcharts, architecture views, tables, and visual explanations. Use for visual documentation and system explanations.

Skillset Gap Routes

Pattern Lifecycle Slot Harness Rule
Domain docs and ADRs requirements, planning Read CONTEXT.md, CONTEXT-MAP.md, and relevant ADR files when present; use their domain vocabulary and flag conflicts instead of inventing terms.
Vertical slices planning, development Break multi-step work into independently verifiable vertical slice units; mark each unit AFK when a worker can proceed from durable context or HITL when human judgment is required.
Feedback loop first debug/investigation Establish a runnable feedback loop before hypotheses or fixes: failing test, CLI fixture, curl script, browser check, trace replay, throwaway harness, fuzz loop, or differential run.
Prototype learning planning Use a throwaway prototype only to answer one named logic, state, interface, or UI question; delete it or capture the durable decision before handoff.
Durable agent brief planning, development, handoff Use docs/templates/harness-agent-brief.md for a durable agent brief when worker contracts need current behavior, desired behavior, key interfaces, acceptance criteria, and out of scope.
Expert committee rating loop review, development Route only explicit committee/subagent rating loops to committee-review-loop; capture expert domains, target rating, revision worker scope, verification gate, and stopping condition.
Deep module review planning, review Prefer a deep module shape with small public interfaces and meaningful behavior behind them; use the interface as the test surface and preserve locality/leverage.

Runtime Helper Map

Helper Lifecycle Slot Purpose
scripts/harness_recover.py research, handoff Read repo index, harness state, git status/log, and local evidence summary to recover current phase and next safe task.
scripts/harness_env_probe.py research, validation Report observable Codex runtime config, hooks, tool policy, evidence schema, sandbox fields, and approval fields.
scripts/harness_requirements.py requirements Validate requirements artifacts before planning or development treats them as source of truth.
scripts/harness_agent_team.py planning, development Validate agent role, scope, write set, verification check, protected harness-state boundaries, and optional durable worker brief before parallel worker dispatch.
scripts/harness_evidence.py validation Validate and append structured local evidence events.
scripts/harness_report.py validation, review, handoff Summarize local JSONL evidence by phase, event type, time window, or JSON output.
scripts/harness_checkpoint.py handoff, phase transitions Append checkpoint entries to docs/harness-state.md with changed surfaces, verification, blockers, and next safe task.
scripts/verify_codex_env.sh validation Verify Codex/Claude runtime sync, managed skills, hooks, runtime policies, and supported Codex CLI version.
main repository regression suite validation Main repo regression suite for sync, hooks, runtime helpers, skill boundaries, eval fixtures, and docs/config behavior.

Routing Rules

  • Start with delivery-harness-framework when work is complex, resumed, cross-session, security-sensitive, release-facing, or ambiguous.
  • Prefer repo-specific lifecycle harnesses when a known project adapter owns the business domain.
  • Prefer gstack skills when the task is product review, engineering review, backlog/spec authoring, design review, browser QA, real-device iOS QA, security review, ship, deploy, canary, release documentation, retro, or learning capture.
  • Prefer the richer upstream gstack posture when available: gstack-office-hours for problem discovery, mockup-first gstack-plan-design-review for UI planning, fix-first gstack-review for near-landing diffs, coverage-aware gstack-ship for release readiness, and debt-aware gstack-document-release for post-ship docs. With gstack 1.52.x, planning skills may use configured gbrain digests as specialist context, but DHF still owns repo state, lane, checkpoint, and validation boundaries; use gstack-plan-tune only for explicit question/developer-profile tuning. Also prefer gstack-ios-qa / gstack-ios-design-review / gstack-ios-fix for live-device iOS workflows, vendored ios-sync / ios-clean only for explicit iOS debug-bridge maintenance, vendored context-save / context-restore for user-facing session continuity, landing-report for version queue visibility, document-generate / make-pdf / diagram for generated docs and artifacts, and setup-gbrain / sync-gbrain only for explicit persistent memory setup.
  • Prefer deterministic helper scripts when the runtime already provides one; do not reimplement their parsing or validation manually.
  • Use verification-loop or repo-native checks before any completion claim.
  • Keep docs/harness-state.md as an integrator-owned checkpoint surface for delegated worker plans; workers should report or write slice-local handoff artifacts instead. Single-line main-agent tasks may still append verified checkpoints directly.
  • Use harness_checkpoint.py append before ending long-running work, after a meaningful validated slice, or before risky remote/release actions.

Evidence Standard

Any claim that work is complete, fixed, or passing must include fresh evidence:

check
how it exited
what it showed
when it ran

If a check is blocked by credentials, network, remote approval, sandbox, or an external dependency, report the exact blocker and the safest next check.