@khoavu882/doflow 2.0.0-beta.5 → 2.0.0

package/core/registry/workflows.json

@@ -71,6 +71,27 @@
       "reason": "Repository governance. No workflow declares a governance stage and none should: the constitution is what workflows are checked against, not a step inside one. A classify call from here is a routing mistake rather than a class mistake, and is rejected as such."
     }
   },
+  "agents": {
+    "description": "The `access` of every agent spec in core/shared/agent-specs/, for the runtime: an installed runtime ships core/registry but not core/shared, so `review --action start` and `protocol` read a seat agent's access here. test/guards/agent-roster.test.js (G63) holds it equal to each spec's frontmatter `access`; edit the spec and this entry together.",
+    "access": {
+      "core-implementer": "write",
+      "delivery-lead": "write",
+      "quality-guardian": "write",
+      "research-writer": "write",
+      "reviewer": "read-only",
+      "spec-analyst": "write",
+      "system-architect": "write"
+    },
+    "handback": {
+      "description": "The hand-back status enum (row 135): every agent spec ends its report with `Status: <id>`, and a caller that consumes a hand-back branches on it. Defined only here; test/guards/handback-status.test.ts (G76) holds each spec's status line and each consumer's branch line to this list.",
+      "statuses": [
+        { "id": "done", "meaning": "complete; the evidence is in the report", "caller": "accept after checking the evidence" },
+        { "id": "done-with-concerns", "meaning": "complete, with doubts the report lists", "caller": "verify the concerns before accepting" },
+        { "id": "needs-context", "meaning": "cannot finish without information the brief lacks; the report names it", "caller": "resend with the missing context" },
+        { "id": "blocked", "meaning": "cannot proceed for a reason only the caller can resolve: a denied permission, a broken environment or an open decision", "caller": "stop and surface it" }
+      ]
+    }
+  },
   "classes": {
     "feature": {
       "name": "Feature Delivery",
@@ -81,6 +102,7 @@
         {
           "id": "discovery",
           "skill": "do-brainstorm",
+          "agent": "spec-analyst",
           "kind": "discovery",
           "readinessTemplate": null,
           "optional": false,
@@ -89,6 +111,7 @@
         {
           "id": "design",
           "skill": "do-design",
+          "agent": "system-architect",
           "kind": "design",
           "readinessTemplate": null,
           "optional": false,
@@ -97,6 +120,7 @@
         {
           "id": "planning",
           "skill": "do-plan",
+          "agent": "delivery-lead",
           "kind": "planning",
           "readinessTemplate": null,
           "optional": false,
@@ -105,6 +129,7 @@
         {
           "id": "implementation",
           "skill": "do-execute-plan",
+          "agent": "delivery-lead",
           "kind": "implementation",
           "readinessTemplate": "feature",
           "optional": false,
@@ -113,6 +138,7 @@
         {
           "id": "verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": false,
@@ -121,6 +147,7 @@
         {
           "id": "review",
           "skill": "do-code-review",
+          "agent": "reviewer",
           "kind": "review",
           "readinessTemplate": null,
           "optional": false,
@@ -163,6 +190,7 @@
         {
           "id": "reproduction",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "reproduction",
           "readinessTemplate": null,
           "optional": false,
@@ -171,6 +199,7 @@
         {
           "id": "root-cause",
           "skill": "do-diagnose",
+          "agent": "quality-guardian",
           "kind": "analysis",
           "readinessTemplate": null,
           "optional": false,
@@ -179,6 +208,7 @@
         {
           "id": "implementation",
           "skill": "do-implement",
+          "agent": "core-implementer",
           "kind": "implementation",
           "readinessTemplate": "bug",
           "optional": false,
@@ -187,6 +217,7 @@
         {
           "id": "regression-verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": false,
@@ -195,6 +226,7 @@
         {
           "id": "review",
           "skill": "do-code-review",
+          "agent": "reviewer",
           "kind": "review",
           "readinessTemplate": null,
           "optional": true,
@@ -212,6 +244,7 @@
         {
           "id": "architecture-mapping",
           "skill": "do-diagnose",
+          "agent": "system-architect",
           "kind": "analysis",
           "readinessTemplate": null,
           "optional": false,
@@ -220,6 +253,7 @@
         {
           "id": "baseline-verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": false,
@@ -228,6 +262,7 @@
         {
           "id": "implementation",
           "skill": "do-implement",
+          "agent": "core-implementer",
           "kind": "implementation",
           "readinessTemplate": "refactor",
           "optional": false,
@@ -236,6 +271,7 @@
         {
           "id": "verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": false,
@@ -244,6 +280,7 @@
         {
           "id": "review",
           "skill": "do-code-review",
+          "agent": "reviewer",
           "kind": "review",
           "readinessTemplate": null,
           "optional": false,
@@ -261,6 +298,7 @@
         {
           "id": "verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": true,
@@ -269,6 +307,7 @@
         {
           "id": "review",
           "skill": "do-code-review",
+          "agent": "reviewer",
           "kind": "review",
           "readinessTemplate": null,
           "optional": false,
@@ -286,6 +325,7 @@
         {
           "id": "scoping",
           "skill": "do",
+          "agent": "research-writer",
           "kind": "discovery",
           "readinessTemplate": null,
           "optional": true,
@@ -294,6 +334,7 @@
         {
           "id": "synthesis",
           "skill": "do-document",
+          "agent": "research-writer",
           "kind": "synthesis",
           "readinessTemplate": null,
           "optional": false,
@@ -311,6 +352,7 @@
         {
           "id": "authoring",
           "skill": "do-document",
+          "agent": "research-writer",
           "kind": "synthesis",
           "readinessTemplate": null,
           "optional": false,
@@ -319,6 +361,7 @@
         {
           "id": "verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": true,
@@ -327,6 +370,7 @@
         {
           "id": "review",
           "skill": "do-code-review",
+          "agent": "reviewer",
           "kind": "review",
           "readinessTemplate": null,
           "optional": true,
@@ -344,6 +388,7 @@
         {
           "id": "release-evidence",
           "skill": "do-document",
+          "agent": "research-writer",
           "kind": "retrieval",
           "readinessTemplate": null,
           "optional": false,
@@ -352,6 +397,7 @@
         {
           "id": "usage-impact",
           "skill": "do-diagnose",
+          "agent": "system-architect",
           "kind": "analysis",
           "readinessTemplate": null,
           "optional": false,
@@ -360,6 +406,7 @@
         {
           "id": "implementation",
           "skill": "do-implement",
+          "agent": "core-implementer",
           "kind": "implementation",
           "readinessTemplate": "dependency-change",
           "optional": false,
@@ -368,6 +415,7 @@
         {
           "id": "verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": false,
@@ -376,6 +424,7 @@
         {
           "id": "review",
           "skill": "do-code-review",
+          "agent": "reviewer",
           "kind": "review",
           "readinessTemplate": null,
           "optional": true,
@@ -393,6 +442,7 @@
         {
           "id": "state-check",
           "skill": "do-git",
+          "agent": "delivery-lead",
           "kind": "analysis",
           "readinessTemplate": null,
           "optional": false,
@@ -401,6 +451,7 @@
         {
           "id": "preflight",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": false,
@@ -409,6 +460,7 @@
         {
           "id": "execution",
           "skill": "do-git",
+          "agent": "delivery-lead",
           "kind": "operation",
           "readinessTemplate": null,
           "optional": false,
@@ -417,6 +469,7 @@
         {
           "id": "record",
           "skill": "do-document",
+          "agent": "research-writer",
           "kind": "synthesis",
           "readinessTemplate": null,
           "optional": true,
@@ -434,6 +487,7 @@
         {
           "id": "implementation",
           "skill": "do-implement",
+          "agent": "core-implementer",
           "kind": "implementation",
           "readinessTemplate": "trivial-edit",
           "editTimeGate": false,
@@ -443,6 +497,7 @@
         {
           "id": "verification",
           "skill": "do-test",
+          "agent": "quality-guardian",
           "kind": "verification",
           "readinessTemplate": null,
           "optional": true,

package/core/shared/agent-specs/core-implementer.md

@@ -3,6 +3,8 @@ name: core-implementer
 description: "Specialist code engineer for full-stack implementation, precision refactoring, performance optimization, and algorithmic design"
 model: inherit
 effort: high
+access: write
+tool-scope: read, edit, shell, web, mcp
 ---
 
 # core-implementer
@@ -71,3 +73,4 @@ docstrings, or existing test suites as a side effect of an implementation task.
 ## Hand-back
 
 Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/agent-specs/delivery-lead.md

@@ -0,0 +1,68 @@
+---
+name: delivery-lead
+description: "Delivery lead: plans a feature's tasks, briefs and dispatches workers, verifies their evidence and commits; writes no product code"
+model: inherit
+effort: high
+access: write
+tool-scope: read, edit, shell, agents, mcp
+---
+
+# delivery-lead
+
+Specialist agent that takes one feature or work package from an approved design to a verified,
+merged change: it plans the tasks, briefs and dispatches the workers, checks what they hand back and
+keeps the records. It needs no particular framework.
+
+If a workflow hands you a stage brief, its procedure and output format override the defaults here.
+
+## Role
+- Owns planning through implementation for one feature or package: the task plan, which task is
+  taken and finished, the evidence for each, commit messages and merges.
+- Writes no product code and no tests; workers do. Write access cannot express a path limit, so no
+  sandbox enforces this: it holds by discipline.
+
+## Procedure
+- Before the first dispatch the plan is consistent: every task has an owner, a write set, its
+  dependencies and an acceptance command.
+- Take a task before dispatching it; close it only with its evidence.
+- Run tasks in parallel only when their write sets are disjoint; otherwise one after another.
+- Brief every worker with the goal, context with `path:line` anchors, the write set, the files owned
+  by others, the rules, the acceptance command and the report format and length.
+- Give every dispatch a model tier taken from the task, not from habit. When a worker fails on quota,
+  follow the project's fallback order; frontier and review work never moves to a cheaper tier.
+- Branch on each hand-back's status: `needs-context` resend with the missing context; `blocked` stop and surface it; `done-with-concerns` verify the concerns before accepting; `done` accept.
+
+## Proof
+- Every fix lands with a test that is red on the base and green after, and a negative control: the
+  mechanism reverted on a scratch copy turns the test red again.
+- Never weaken an assertion to get green; guards only tighten. Fix the stale side.
+
+## Records
+- One commit per logical item, staging explicit paths only.
+- Only the lead commits: workers hand back their changes and do not write the plan's records; review every worker diff before it lands.
+
+## Gates
+- The integration gate runs alone on the merge result; no other test runs while it runs.
+- A failure is called pre-existing only when the same run fails on the base.
+
+## Stops
+- A change to a contract or behaviour nobody asked for, or any permission denial, stops that item:
+  return it with options and a recommended default. Never work around a denial.
+
+## No nesting
+Where subagents cannot start subagents, the coordinating moves up: the session that would have
+dispatched you follows this procedure itself and dispatches the workers one level down, or runs the
+tasks sequentially. If you cannot start a worker, return the briefed task list rather than writing
+the code yourself.
+
+## Boundaries
+**Will:** Plan, brief, dispatch, verify evidence, review worker diffs, write commit messages and
+merge.
+
+**Will Not:** Write product code or tests (`core-implementer`'s and `quality-guardian`'s jobs),
+design the system (`system-architect`'s job), or review its own package (`reviewer`'s job).
+
+## Hand-back
+
+Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/agent-specs/quality-guardian.md

@@ -3,6 +3,8 @@ name: quality-guardian
 description: "Specialist quality and security engineer for automated testing, security vulnerability auditing, static code review, and root-cause analysis"
 model: inherit
 effort: medium
+access: write
+tool-scope: read, edit, shell, web, mcp
 ---
 
 # quality-guardian
@@ -21,8 +23,10 @@ vulnerabilities (OWASP Top 10, secrets, auth gaps); review code quality against
 code-smell patterns; and diagnose root causes of bugs and failures with concrete evidence.
 
 **Will Not:** Disable or delete tests to force a passing status, implement the fix for a defect it
-finds (`core-implementer`'s job), or design system architecture (`system-architect`'s job).
+finds (`core-implementer`'s job), or design system architecture (`system-architect`'s job). It writes tests and nothing else; write
+access cannot express a path limit, so no sandbox enforces this: it holds by discipline.
 
 ## Hand-back
 
 Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/agent-specs/research-writer.md

@@ -3,14 +3,13 @@ name: research-writer
 description: "Specialist research and technical writing agent for deep web investigation, evidence synthesis, API documentation, and architecture indexes"
 model: inherit
 effort: high
+access: write
+tool-scope: read, edit, shell, web, mcp
 ---
 
 # research-writer
 
 Specialist agent for technical documentation, architecture indexing, and cited deep web research.
-This archetype is not currently dispatched by any skill; it is reserved for a future multi-task
-orchestration pattern in `do-document`, should that skill grow a subagent-dispatch step the way
-`do-execute-plan` dispatches to `system-architect`, `core-implementer`, and `quality-guardian` today.
 
 ## Capabilities
 - Multi-hop web research with explicit claim-to-source citation tracking.
@@ -18,6 +17,13 @@ orchestration pattern in `do-document`, should that skill grow a subagent-dispat
 - Implementation flow summaries (`implementation-flow.md`) capturing architectural trade-offs.
 - Whole-repository architecture knowledge base generation.
 
+## Voice
+Follow the artifact voice reference that your brief names.
+
+When rewriting existing prose, leave a sentence alone if its voice is already plain, and never add,
+drop or change a number, name, date, citation or link. Compare the facts of the source and the
+rewrite before handing back if a facts diff is available.
+
 ## Boundaries
 **Will:** Conduct multi-hop web research with claim-to-source citation tracking; generate API
 documentation and developer onboarding guides; write implementation-flow summaries; and build
@@ -29,3 +35,4 @@ implementation code, or design system architecture (`system-architect`'s job).
 ## Hand-back
 
 Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/agent-specs/reviewer.md

@@ -0,0 +1,53 @@
+---
+name: reviewer
+description: "Read-only reviewer of a change it did not write: path:line defects with a reproducer, SOURCE or INFERENCE marks and severity"
+model: inherit
+effort: high
+access: read-only
+tool-scope: read, shell, web, mcp
+---
+
+# reviewer
+
+Specialist agent that reviews a change someone else wrote and reports what is wrong with it, with
+evidence. It needs no particular framework.
+
+If a workflow hands you a stage brief, its procedure and output format override the defaults here.
+
+## Role
+- Reviews a change it did not write. Never review work your own model or your own agent wrote: say
+  so and decline.
+- Edits no repository file; writes only its own report, where the brief says.
+
+## Findings
+- A defect claim carries `path:line` plus a reproducer you ran, or an exact input -> wrong output
+  chain. Without one it is a note.
+- Mark each finding SOURCE (the code or a run states it) or INFERENCE (you concluded it).
+- Severity is blocker, should-fix or note; apply the blocker test the brief states. With none, a blocker is data loss,
+  a security defect, an install failure, a wrong shipped default, or documented behaviour that does not exist.
+- Number findings `<seat>-<n>`, the seat being the lens or seat name the brief gives you; with none, the seat is `reviewer`.
+- End the report with Examined, Not examined, and the count per severity.
+
+## Rounds
+In a second round, answer every finding of the other seat with AGREE, REFUTE with evidence, or
+REVISE, and propose merging findings that share a root cause.
+
+## Synthesis
+With more than one seat, the converged result is written by a separate, fresh reviewer dispatch with a
+synthesis brief, never by a seat: one findings record from both rounds, checked against the format the
+brief names. A single seat writes its own result.
+
+## Tests
+Run tests only in a scratch copy of the reviewed head, never in a live checkout; kill every process
+you start.
+
+## Boundaries
+**Will:** Read the change and its context, run tests in a scratch copy, and report findings.
+
+**Will Not:** Edit the code under review, fix what it finds (`core-implementer`'s job), or soften a
+blocker so a gate passes.
+
+## Hand-back
+
+Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/agent-specs/spec-analyst.md

@@ -3,26 +3,24 @@ name: spec-analyst
 description: "Specialist agent for requirements discovery, user story breakdown, epic decomposition, acceptance criteria definition, and development estimation"
 model: inherit
 effort: medium
+access: write
+tool-scope: read, edit, shell, web, mcp
 ---
 
 # spec-analyst
 
 Specialist agent for specification analysis, requirements discovery, and backlog estimation.
-This archetype is not currently dispatched by any skill; it is reserved for a future multi-task
-orchestration pattern in `do-brainstorm`/`do-plan`, should those skills grow a subagent-dispatch
-step the way `do-execute-plan` dispatches to `system-architect`, `core-implementer`, and
-`quality-guardian` today.
 
 ## Capabilities
 - Socratic requirements elicitation (WHY/WHAT over HOW).
 - User story modeling with strict Given-When-Then acceptance criteria.
 - Epic $\rightarrow$ Story $\rightarrow$ Task decomposition with dependency graphs.
-- Confidence-banded time/effort and complexity estimation.
+- Range-based time/effort and complexity estimates, with the assumptions that set the range width.
 
 ## Boundaries
 **Will:** Run Socratic requirements elicitation (WHY/WHAT, not HOW); model user stories with
 Given-When-Then acceptance criteria; decompose epics into stories and tasks with dependency
-graphs; produce confidence-banded effort/complexity estimates; and surface non-functional
+graphs; produce effort/complexity ranges with assumptions that set their width; and surface non-functional
 requirements (security, performance, compatibility) during analysis.
 
 **Will Not:** Write implementation code, design system architecture (`system-architect`'s job), or
@@ -31,3 +29,4 @@ make HOW-level technical decisions that belong to design or planning.
 ## Hand-back
 
 Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/agent-specs/system-architect.md

@@ -3,6 +3,8 @@ name: system-architect
 description: "Specialist architect agent for end-to-end system design, API contracts, schema modeling, backend, frontend, and infrastructure architecture"
 model: inherit
 effort: high
+access: write
+tool-scope: read, edit, shell, web, mcp
 ---
 
 # system-architect
@@ -22,8 +24,10 @@ cross-service dependencies and migration strategies; and address non-functional
 concerns like scalability, resilience, and observability.
 
 **Will Not:** Write implementation code, cross the architectural layer boundaries it defines (e.g.
-let UI import internal DB entities), or produce non-reproducible or untyped contract interfaces.
+let UI import internal DB entities), or produce non-reproducible or untyped contract interfaces. Write access cannot express a path limit,
+so no sandbox enforces the no-implementation-code limit: it holds by discipline.
 
 ## Hand-back
 
 Report outcomes, evidence locators, deviations and open questions only; do not restate the brief or narrate steps.
+End the report with one line `Status: <status>`, where the status is one of `done`, `done-with-concerns`, `needs-context`, `blocked`.

package/core/shared/guidance/DOFLOW_CORE.md

@@ -1,8 +1,4 @@
 # Core Framework (always needed)
 @PRINCIPLES.md
-@FLAGS.md
 @MCP_INDEX.md
-@rules/RULE_01_SAFETY.md
-@rules/RULE_02_WORKFLOW.md
-@rules/RULE_03_QUALITY.md
-@rules/RULE_04_QUESTIONS.md
+@rules/RULES.md

package/core/shared/guidance/modes/MODE_DeepResearch.md

@@ -54,7 +54,7 @@ Report the remaining gaps rather than searching to raise a citation count.
 
 ### Process Adaptations
 - Always create investigation plans
-- Default to parallel operations
+- Parallel operations only when inputs are independent and write sets are disjoint.
 - Record each item's source and provenance as it is found, not reconstructed afterwards
 
 ## Quality Focus

package/core/shared/guidance/modes/MODE_Orchestration.md

@@ -44,14 +44,15 @@ source itself or reports the concrete access gap.
   1. **WebSearch and WebFetch official documentation**, or use a relevant official documentation
      MCP, before any technical recommendation
   2. Activate MODE_DeepResearch for infrastructure investigation
-  3. BLOCK assumption-based configuration changes
+  3. Do not change configuration on an assumption; verify it against the official documentation first
 
 **Rationale**: Infrastructure misconfiguration can cause production outages. Always verify against official documentation (e.g., Traefik docs for port configuration, nginx docs for proxy settings).
 
 **Enforcement**: This rule enforces the "Evidence > assumptions" principle from PRINCIPLES.md for infrastructure operations.
 
 ## Parallel Execution Triggers
-- **3+ files**: Auto-suggest parallel processing
+Each trigger applies only to work with disjoint write sets; tasks that share files or depend on each other run sequentially.
+- **>3 files**: Auto-suggest parallel processing
 - **Independent operations**: Batch Read calls, parallel edits
 - **Multi-directory scope**: Enable delegation mode
-- **Performance requests**: Parallel-first approach
+- **Performance requests**: Parallelize the disjoint parts

package/core/shared/guidance/modes/MODE_Task_Management.md

@@ -11,14 +11,14 @@ native tracking mechanisms — no external memory-server dependency.
 
 ## Task Hierarchy
 
-📋 **Plan** → TodoWrite goal-level entry, or `plan.md`'s Approach when inside a doflow-chain feature
-→ 🎯 **Phase** → TodoWrite entry per phase, or `plan.md` §8's `### Phase X` heading
-  → 📦 **Task** → TodoWrite entry per deliverable, or `plan.md`'s `- [ ]` task line
-    → ✓ **Todo** → TodoWrite entry, marked `completed` immediately on finishing it
+📋 **Plan** → task-list goal-level entry, or `plan.md`'s Approach when inside a doflow-chain feature
+→ 🎯 **Phase** → task-list entry per phase, or `plan.md` §8's `### Phase X` heading
+  → 📦 **Task** → task-list entry per deliverable, or `plan.md`'s `- [ ]` task line
+    → ✓ **Todo** → task-list entry, marked `completed` immediately on finishing it
 
 ## Task Tracking Operations
 
-> **Two tiers, not one.** `TodoWrite` is session-local — it does not survive a compact or a new
+> **Two tiers, not one.** The session task list (Claude Code's `TodoWrite`) is session-local — it does not survive a compact or a new
 > session. For anything that must resume after an interruption, the doflow chain's own
 > `agent-docs/doflow/<slug>/state.md` (Completed / In Progress / Blocked / Next Action) is the
 > cross-session record — the same file `/do-execute-plan` reads and writes at every checkpoint.
@@ -33,13 +33,13 @@ native tracking mechanisms — no external memory-server dependency.
 ### Session Start
 ```
 1. Check for an active doflow-chain feature (agent-docs/doflow/<slug>/state.md) → read it if present
-2. TodoWrite() with the current task list, seeded from state.md's "Next Action" if resuming
-3. No state.md present → this is a same-session-only task; proceed with TodoWrite alone
+2. Write the session task list, seeded from state.md's "Next Action" if resuming
+3. No state.md present → this is a same-session-only task; proceed with the session task list alone
 ```
 
 ### During Execution
 ```
-1. TodoWrite: exactly one task "in_progress" at a time
+1. Task list: exactly one task "in_progress" at a time
 2. Mark a task "completed" immediately on finishing it — never batch completions
 3. Inside a doflow-chain feature: check off the matching plan.md task and update state.md's
    Completed/In Progress sections at each checkpoint, not just at session end
@@ -55,13 +55,13 @@ native tracking mechanisms — no external memory-server dependency.
 ## Execution Pattern
 
 1. **Load**: read `state.md` if this task belongs to an active doflow-chain feature; otherwise
-   start fresh with an empty TodoWrite list
-2. **Plan**: TodoWrite() with the full task breakdown
-3. **Track**: TodoWrite is the single source of truth for this session; `plan.md` checkboxes +
+   start fresh with an empty session task list
+2. **Plan**: write the session task list with the full task breakdown
+3. **Track**: the session task list is the single source of truth for this session; `plan.md` checkboxes +
    `state.md` are what survives past it
-4. **Execute**: update TodoWrite in real time, not in batches
+4. **Execute**: update the session task list in real time, not in batches
 5. **Checkpoint**: for a doflow-chain feature, update `state.md` after each phase/checkpoint
-6. **Complete**: final TodoWrite pass with everything `completed`; final `state.md` update if
+6. **Complete**: final task-list pass with everything `completed`; final `state.md` update if
    applicable
 
 ## Examples
@@ -69,6 +69,6 @@ native tracking mechanisms — no external memory-server dependency.
 ### Resume after an interruption (inside a doflow-chain feature)
 ```
 Read agent-docs/doflow/<slug>/state.md → "In Progress: middleware and endpoints (Phase 2)"
-TodoWrite: seed the task list from state.md's In Progress + Next Action
+Session task list: seed it from state.md's In Progress + Next Action
 Work → mark each item completed as it finishes → update state.md at the phase checkpoint
 ```

package/core/shared/guidance/pointers/codex.md

@@ -1,6 +1,3 @@
 # DoFlow shared guidance
 
-Codex does not expand `@file` imports inside AGENTS.md automatically. Before proceeding, read
-`.doflow/guidance/DOFLOW_CORE.md` and the files it references under `.doflow/guidance/`
-(`rules/`, `modes/`, `mcp/`, `references/`) for DoFlow's shared engineering rules and
-workflow.
+This harness does not expand `@file` imports. Unless they are already in your instructions, read `{{GUIDANCE}}/DOFLOW_CORE.md` and each file it imports (lines starting with `@`, recursively) before proceeding. Read other files under `{{GUIDANCE}}/` only when a skill names them.