# Lifecycle And Skill Routing

## 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,
commands, smoke matrices, and business safety boundaries belong in repo-specific
adapter skills.

## Visual Guides

- `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.

## Related Documentation

- `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 `command`, `exit_code`, `key_output`, `timestamp`. | `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 command 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 commands, 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 command, 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. |
| `python3 test_runner.py` | `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 commands 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:

```text
command
exit_code
key_output
timestamp
```

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