- Shared Constraints SSOT:../shared/constraints.md
This skill follows the Shared Constraints SSOT: gating markers, yaml-summary-v1, Task delegation, user confirmation, Recovery format, read-only / dry-run, FUTURE tri-state, realign / spec_version see skills/shared/constraints.md. This file only describes dev-workflow private rules (11-step flow, Sprint Contract, headless safety, Step 1.5 five pieces of evidence, Phase 1-4 external review, EXT state machine, Commit 1/2 dual commit).
Single Authoritative File Principle(mandatory since spec_version 1.1):
- Phase 4 / Parallel Scheduling /
diff_hash/ Rerun Mechanism → verification-flow.md sole authority- Step 1.5 each branch / Batch-Id identification → task-orchestration.md sole authority
- Phase 2-UI review checklist → ui-quality-checklist.md sole authority
- review_profile / drain / review_pending → verification-flow.md + task-orchestration.md
- Risk classifier (review_profile proposal) → /dev-tasks
- Other files (SKILL.md / auto-mode.md / execution-flow.md)only 2-3 line pointer references allowed, repetition and paraphrase strictly prohibited. Violation of this principle is regarded as complexity degradation and must be reverted.
Perspective: senior developer — pragmatism first, no over-engineering, tests first, atomic commits.
Quick Start
Execute development tasks, using skeleton-first + layered TDD. Common usage:/dev-workflow T-03(single task),T-01~T-05(batch). Use /dev-tasksto break down tasks, use /bugfixto fix bugs. Supports questions in Chinese and English, replies uniformly in Chinese.
Mode Selection
| Mode | Applicable Scenario | Flow |
|---|---|---|
| Lightweight | Bug fix, small change, configuration change | → /bugfix(existing) |
| Standard | New feature, requirement change | → Full Requirements→Design→Tests→Tasks→Dev |
| Exploration | Prototype, technical research | → Allowed to skip part of verification; after the fact, once the user confirms the target behavior, backfill and create ACs |
Minimum behavior verification in exploration mode: documentation enforcement (AC/traceability annotations/full TDD) and adversarial verification may be skipped, butmust not skip S6 green verification (skipped/todo=0) and at least 1 piece of "target behavior evidence" (AC / UT/IT assertion /
--ui --livescreenshot / explicit exemption); write to task ledgerexploration_mode: true, so that after the fact, once the user confirms the target behavior, real ACs can be backfilled and created. No evidence ⛔ blocks commit.
Trigger Conditions
The user starts/batches/continues development tasks (T-01 / T-01~T-05 / F-001 / "run all the rest"); keywords such as "development task", "execute task", "start T-XX", "batch development", "continue development", "unattended".
Run Mode
Syntax
| Specifier | Example | Description |
|---|---|---|
| Single task | T-03 |
Execute a single task (existing behavior) |
| Range | T-01~T-05 |
Execute all tasks within the range |
| Enumeration | T-01,T-03,T-07 |
Execute the specified task list |
| Feature point | F-001 |
Reverse-look up all associated tasks via the 关联需求 field |
| User story | US-001 |
Same as above |
| Lightweight entry | Directly describe the task + acceptance criteria | Can also enter without the 04 document: materialize a stub (01 AC entries + 04 task entries) according to inline-entry.md , then switch to the single-task path; review_profile lower bound guarded |
⛔ No
M-XXXspecifier. A milestone is not an execution unit—to run a segment, specify it by itsF-XXXorT-XXscope.
Stopping halfway through is normal. 01-requirements.md When milestones are defined, the queue executes by segment;once a segment is done it will stop and ask you to actually use it—it is not stuck, it is the purpose of this process: all Fs done, all unit tests passing, yet everything is broken when connected and used together. Only a person using it can find this kind of thing. After you have used it, say "usable" to continue to the next segment, or say "there is a problem" to fix it first. Projects without milestones do not have this stopping point. For segmentation rules, see task-orchestration.md § 1.5。
Protocol parameters are not on the user surface. Unattended / auto-commit / review level / external review rounds / context reset / single commit / skip traceability are all normalized from your natural language by the orchestration layer and passed down (
task/intent-normalization); you do not need to remember parameter names.Authorization requires you to speak up: unattended and auto-commit are not default behavior and must be stated explicitly; conversely, irreversible actions beyond your authorization scope must be confirmed on the spot when they occur (
task/consent-at-action）。
Unified orchestration process
All modes useorchestrator + sub-agent: the orchestrator parses specifiers, dependencies/breakpoints, starts sub-agents, receives yaml-summary-v1, schedules /sync//test-run//compound; task sub-agents execute TDD, adversarial verification, Blocker fixes, self-description, and Commit 1. When there is >1 task after expansion, topologically sort and atomically commit task by task. For the general Task delegation protocol, see shared constraints §3; for batch/continuation details, see task-orchestration.md。
Preconditions
- Task document:
docs/devdocs/04-dev-tasks.md, and the task has been defined and includes: associated requirements, acceptance criteria, test method - orDirectly provide the task definition and acceptance criteria (no parameters needed): materialize a stub according to inline-entry.md and then enter S1; in the Test Agent input, the 02/03 fields are marked
—(inline), with the S1.5 Sprint Contract as the test input constraint
Workflow
This document retains the S1~S11 skeleton; S12 document synchronization/knowledge consolidation belongs to the post-Commit 2 process, see execution-flow.md。
| Step | Quality gate |
|---|---|
| S1 Read task definition | From 04-dev-tasks.md Get task and F/AC/UT/IT/E2E associations |
| S1.5 Sprint Contract | The Test Agent generates an executable acceptance contract based on AC + the current code context (function signatures, return value types, boundary conditions, exception scenarios); the orchestrator trims over-contracts and fills in missing contracts, and after confirmation this serves as the test input constraint |
| S2-S3 Skeleton | Interface skeleton + test skeleton; ⛔ Do not write any keel number in the code; traceability is written into documents by Commit 2 |
| S4-S7 Red-Green-Refactor | The Test Agent writes assertions; the orchestrator performs red verification; the Impl Agent implements, performs green verification, and refactors; green verification must skipped/todo=0; comments follow /code-quality comment conventions(No changelog-style/source-record-style comments, including fix loops), logs follow logging standards(security red lines/level discipline/no log-and-throw) |
| S8 Completion Check | 5 quality floor items + AC completeness table (fast evidence summary / audit full AC type×evidence matrix) + claimed vs actual diff cross-validation; missing evidence or unlinked large diff blocks → ⛔ do not proceed |
| S9 Pre-validation | guarded/audit /verify --impl; fast only quality floor (no pre-validation); 🟢 UI tasks with design mockups additionally run /verify --ui --impl alignment with design mockups (does not vary with profile) |
| S9 Phase 1~3 | Built-in role-play adversarial validation (independent review):audit inline fail-fast；fast/guarded deferredto /verify --review-drain, during the task marked review_pending；--review can temporarily overlay inline |
| S9 Phase 4 | External adversarial review embedded-headless (independent review):audit inline；fast/guarded deferred drain; T1 codex CLI → T2 codex-mcp, T1/T2 all fail fail-fast; status EXT_REVIEWED/EXT_UNRESOLVED/EXT_BLOCKED(distinguished from review_pending ) |
| S10 Self-description | /code-self-describe --update（workspace_context.capabilities.code_metadata_write_policy is explicit_opt_in whenskipped by default——self-description artifacts are written inside the code directory, violating the zero-pollution red line. Skipping must be recorded in the yaml summary with ℹ️ skipped: code_metadata_write_policy=explicit_opt_in. Only when the user explicitly --force-code-docs is it executed) |
| S11 Commit 1 | Code commit, following the "commit message format"; when Phase 4 triggers, write ext_review_state into the task ledger |
| After Commit 2 | /sync Update trace + documentation commit; if AGENTS.md exists only update "current status"; batch default /compound |
Step status (S1~S11 + S1.5) is used for breakpoint recovery; for the detailed matrix, post-S12 sync, and status markers see execution-flow.md。
Stale task card pre-gate (within S1, ⛔ blocking)
Task card carries superseded_by field → ⛔ stop immediately, do not enter S1.5。
⛔ T-01 已被 ADR-015 取代（superseded_by: ADR-015）
该任务卡的执行步骤属于旧决策，照它执行会复原已被删除的设计。
请先读指向的 ADR 确认当前决策，再决定：
(a) 做新决策下的等价工作 → 用 /dev-tasks 立新任务
(b) 确实要复原旧行为 → 需先推翻该 ADR
Why block instead of warn: the danger of a stale task card is that itlooks completely normal——status ✅ completed, concrete steps, clear paths. The executor has no clue that these steps are outdated, and warnings get skimmed over as noise. ⛔ does not provide --force skip.
Top-down Development Mode
Define the skeleton first, then fill in details. Ensure the traceability chain is established at code generation time. The dual-Agent model (Test Agent → red validation → Impl Agent → completion check + commit) is fully expanded above in "Workflow" and execution-flow.md in the enforcement-level matrix.
Skeleton Generation Constraints
See the criteria checklist in skeleton-examples.md(interface signature completeness / traceability annotations / unimplemented methods throw errors / test skeleton skip markers).
Layered TDD Mode
All tasks follow a unified 11-step execution flow + 5 quality floor items (constant inline);review_profile only determinesthe timing of independent review (Phase 1~3 + Phase 4):
| review_profile | Trigger | Dual Agent | Quality Floor | Pre-validation | Phase 1~3 | Phase 4 | Commit Status |
|---|---|---|---|---|---|---|---|
| fast(default) | Low risk (see risk classifier) | ✓ | ✓ | — | Deferred drain | Deferred drain | review_pending |
| guarded | Medium risk | ✓ | ✓ | /verify --impl inline |
Risk triggers inline, otherwise deferred | Deferred drain | review_pending |
| audit | High risk | ✓ | ✓ | /verify --impl inline |
inline fail-fast | inline fail-fast | Submit only after review |
Detailed criteria see verification-flow.md; risk classifier signal criteria → /dev-tasks (initial proposal); execution-phase review (raise only, never lower) → task-orchestration.md; shared definitions see ../shared/constraints.md. Legacy 🔴🟡🟢⚪ tier labelsdemoted to one of the risk classifier input signals, no longer independently determining process strength.
For the enforcement level differences of S1~S11 across review_profiles, see execution-flow.md. For UI tasks, Phase 2-UI self-check still follows ui-quality-checklist.md。
TDD loop (dual-Agent model)
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Test Agent│ → │ 红色验证 │ → │ Impl Agent│
│ 写骨架+ │ │ 编排器确认│ │ 写实现+ │
│ 写测试 │ │ 测试失败 │ │ 重构 │
└──────────┘ └──────────┘ └──────────┘
⛔ Information barrier: Test Agent must not see implementation code; Impl Agent must not see 03-test-*.md (only test code files)(Recovery method: check the file access list in the sub-Agent prompt).
⛔ Tests are immutable: Impl Agent is strictly forbidden from modifying test code produced by Test Agent. Test failures may only be fixed by modifying the implementation. Suspected test defects must be confirmed via AskUserQuestion, then rolled back to Test Agent for fixing.
See execution-flow.md unified task execution process + enforcement level matrix
Orchestration specification (sub-Agent scheduling)
Development execution and skill invocation in all modes (including single-task) must launch sub-Agents via the Task tool：
| Phase | Scheduled content | Scheduling method |
|---|---|---|
| Acceptance contract | Test Agent: Sprint Contract generation → orchestrator review | Test Agent output + orchestrator lightweight review |
| Test writing | Test Agent: skeleton + test code (constrained by Contract) | Task tool sub-Agent |
| Red verification | Run tests to confirm failure | Orchestrator lightweight execution |
| Implementation writing | Impl Agent: implementation + refactoring | Task tool sub-Agent |
| Pre-verification | /verify --impl |
Task tool sub-Agent |
| UI alignment | /verify --ui |
Task tool sub-Agent |
| Traceability sync | /sync |
Task tool sub-Agent |
| Knowledge capture | /compound |
Task tool sub-Agent |
| Full test | /test-run |
Task tool sub-Agent |
Scheduling principles
- Context isolation + information barrier: Sub-Agents read documents themselves; the readable ranges of Test Agent and Impl Agent are strictly isolated (see orchestration isolation constraints)
- Summary passing: receive only YAML summaries,
test_defectstriggers user confirmation when non-empty - Tests are immutable: after Impl Agent completes, diff the test files; any change is a Blocker
- Main Agent is forbidden from directly executing TDD: the orchestrator does not write code—except for the lightweight file scanning of red verification and breakpoint detection
Skill collaboration
| Phase | Collaborating Skill | Description |
|---|---|---|
| Write business code | /code-quality |
MTE principles, dependency injection, avoid over-engineering, comment conventions, logging conventions |
| Write test code | /testing-guide |
Assertion quality, mutation testing, coverage |
| UI implementation | /ui-orchestrator |
Accessibility, animation, layout constraints |
| Implementation review | /verify --impl |
guarded/audit mandatory by default (full AC); fast does not run pre-validation (quality floor only) |
| UI alignment | /verify --ui --impl |
When UI task has design mockupswith /verify --impl run once each in parallel(must not be merged into a single call,--ui --impl only covers the design mockup↔implementation dimension); without design mockups it degrades to Phase 2-UI self-check (does not vary with profile) |
| Completion verification | /code-quality + /testing-guide |
Adversarial verification: audit inline automatic / fast,guarded deferred drain;--review temporary overlay |
| Completion check | /code-self-describe |
Update module self-description (--update) |
| Code commit | /git-safety |
Use git mv/rm to handle files |
| Commit message | /commit-convention |
Follow project commit conventions |
| Dependency resolution | /dev-tasks |
Read task dependencies and status |
| Task completion | /sync |
Follow-up: update traceability matrix (traceability sync) |
| Knowledge capture | /compound |
Recommended: extract experience patterns after sync (executed by default in batch mode) |
| Full test | /test-run |
After batch completion --trace(full + traceability); after single task completion --affected(change-affected tests), fall back when affected has no match --trace |
| External adversarial review (contract reuse) | /adversarial-review |
dev-workflow S9 Phase 4 only reuses its references/external-reviewer-integration.md underlying T1/T2 dual-channel + circuit-breaker protocol(does not use T3 Task sub-agent fallback), does not directly invoke the entire multi-turn skill (to avoid AskUserQuestion blocking). Phase 4 scheduler runs in embedded-headless mode;/adversarial-review can still be invoked independently by the user for interactive review |
Constraints
Layered TDD constraints
- audit/guarded tasks enforce test-first(dual-Agent red-green + test freeze);quality floor 5 items constant across all profiles
- Test Agent writes tests first, Impl Agent writes implementation afterward(physical isolation)
- Test Agent assertions come from behavior contracts + 03-test-*.md, Impl Agent is forbidden from reading 03-test-*.md
- Impl Agent is strictly forbidden from modifying test code produced by Test Agent(suspected defects must be confirmed via AskUserQuestion)
- □/○ When a step is skipped, the reason must be recorded in the commit message
Completion check constraints
- S8 must produce an AC completeness table(per AC: number/AC type(behavioral/visual/structural, required)/evidence type/code or test location/verdict)
- Any AC missing valid evidence / violating the AC type × evidence type grading matrix → ⛔ forbidden to continue(recovery method: regenerate the evidence table after adding implementation or tests)
- Phase 4
ext_review_statemust beEXT_REVIEWED(triggered inline by audit task) or when Phase 4 is not triggeredEXT_REVIEWED/empty only then can Commit 1 be entered; during the fast/guarded deferred drain period the commit status isreview_pending；EXT_UNRESOLVED/EXT_BLOCKED⛔ blocked (for recovery see verification-flow.md truth table） - Claimed vs actual diff cross-verification is mandatory(mandatory for S8 at all tiers, no longer triggered only by --review)
- Test pass determination excludes skipped / todo(skipped/todo count > 0 → ⛔ forbidden to continue, unless the task document explicitly exempts it and records the reason)
AC completeness table template, AC type classification (behavioral/visual/structural), AC type × evidence type grading matrix, Step 1.5 [A] verifiable criteria see verification-flow.md AC completeness section. Violating the grading table → S8 directly ⛔ judged as failed (recovery: add test assertions or go through the exemption enumeration).
Quality floor (constant inline across all review_profiles, cannot be downgraded)
Regardless of tier, the 5 invariants are always inline in effect (for definitions see ../shared/constraints.md): green verification skipped/todo=0 / test freeze / claimed vs actual diff consistency / at least 1 independent piece of evidence for behavioral ACs / affected tests deferred.
Distinguishing the three types of mechanisms (critical, do not conflate):
- Quality floor(the above 5 items) — inline for all tiers.
- Pre-verification
/verify --impl(AC↔implementation semantic consistency) — belongs to the "pre-verification gate", Blocker inline blocks the commit; guarded/audit run it, fast does not.- Independent adversarial review(Phase 1~3 + Phase 4)——the only part that can be deferred, fast/guarded defer to drain, audit inline.
"review_profile only changes the timing of independent review" holds: the floor and pre-verification are always inline and not within the deferred scope.
Adversarial verification (optional)
Review code from different role perspectives, simulating the multi-person collaboration pattern of "development → review → testing".
Relationship with review_profile (important): what this section describes is themechanismof independent review (Phase 1~3/4, INT/EXT states), and itstrigger timingis determined by
review_profile— for the tier table see "Layered TDD Mode" above; this section does not repeat it.
Design principles：
- Pre-verification is minimally mandatory by review_profile: guarded/audit must have an independent pre-verifier (
/verify --impl); fast only has the quality floor. - Phase 13 (built-in role enactment) and Phase 4 (external independent review)independent determination: each maintains
INT_*/EXT_*canonical state；--reviewcontrols Phase 13，--external-reviewcontrols Phase 4;audit inline / fast,guarded defer to/verify --review-drain。 - Pre-verification failure (Blocker) ⛔ blocks Commit 1, and is not let through because "--review was not added".
No skip channel: Phase 1~3 and Phase 4 do not provide a skip parameter. The original --skip-review-reason / --skip-external-review-reason has been removed — the INT_PENDING/EXT_PENDING marked by the two blocks all pass paths, and is completely equivalent to "review not run → *_UNRESOLVED" in terms of blocking nature and recovery action; the only difference is that reason line (which can be written into the commit body). Keeping them would merely transform "must do now" into "debt to make up afterwards".
For the detailed invocation contract of Phase 4 (T1/T2 dual channel, max_rounds, truth table, L2 authoritative evidence protocol), see verification-flow.md Phase 4 section. The Phase 1~3 verification flow (code quality/test completeness/UI self-check/comprehensive report/AC↔diff cross-validation) is in the same file.
Adversarial verification constraints
- Blockers must be fixed before submission; each Phase declares a review role; results are graded (Blocker/Suggestion)
- audit triggers Phase 1~3+4 inline by default；fast/guarded defer drain(marked during the task as
review_pending); after fixing Blockers, re-run verification - The drain-side external review must use the commit diff of Commit 1, ⛔ do not use the workspace diff (otherwise you receive an empty diff, which amounts to no review); see verification-flow.md § diff source
Dependency resolution constraints
- Circular dependencies must error out and terminate(list the circular path)
- An "in progress" dependency is asked about via AskUserQuestion
Atomic commit constraints
- Each task is committed independently, no cross-task merging
- Code commits and documentation commits are separated(Commit 1: code, Commit 2: documentation status + trace sync result)
- After committing, update status:audit → completed；fast/guarded →
review_pending(only after passing/verify --review-draindoes it turn to completed) -
modeis notinline, expand to an N+1 repo commit: Commit 1 is split into one commit per changed code root, Commit 2 is one commit in the shell repo (documentation + pointer bumps for all changed submodules;linkedhas no pointers, documentation only). For the protocol see workspace-topology/references/protocol.md § N+1 repo commit protocol. Code roots are taken from the handshakeworkspace_context.code_roots（inlineis a single item,path= absolute path of the repo root, degenerating to today's Commit 1 + Commit 2).modeislinkedwhen the code root is not owned by this repo; each repo commits separately, ⛔ do not bump pointers, see protocol.md §6.5。 - Must pass the detached HEAD gate before committing: for each changed submodule code root
git -C <path> symbolic-ref -q HEADfailure means ⛔ blocked; for handling see workspace-topology/references/migration.md § detached HEAD handling -
modeis notinlinewhen--single-commitis unavailable: cross-repo cannot be merged into a single commit, ⚠️ ignore the flag and notify
Resume-from-breakpoint constraints
- Perform state detection before each task starts(6-step pipeline: Step 1 / 1.5 evidence review / 2~5)
- Irrelevant changes must warn the user(AskUserQuestion: stash/ignore/terminate)
- Tasks with traces of completion may be skipped only after passing the Step 1.5 five-item evidence review: [A] AC table reviewable / [B] tests have no skip/todo / [C] trace matrix index maintained as needed — missing ones recorded as
trace_pendingincrementally filled in, not used as a hard gate for release / [D1] Phase 1~3 built-in adversarial verification evidence (mandatory check for audit tasks) / [D2] Phase 4 external adversarial review evidence (mandatory check for audit tasks,ext_review_state=EXT_REVIEWEDand L2 yaml readable) / [E] post-test evidence (skip_trace_reasonshall not be used as a release) - Git history has code+doc commits but task status is not completed: no longer skipped directly; instead, enter the Step 1.5 evidence review path
- Legacy task (completed in a previous version, without A/D1/D2/E artifacts) → AskUserQuestion: review and continue / register exemption reason / terminate
-
modeis notinline, status detection is expanded to five dimensions: the "workspace" dimension iterates over N+1 repositories; the "Git history" dimension is tightened to "the shell repository has a commit bearing this T-XX and the submodule SHA recorded in the body matches the current pointer"; a fifth dimension, "pointer consistency", is added; if inconsistent → enter Step 1.5 evidence review without skipping directly.The "evidence review" dimension (A/B/C/D1/D2/E) is unchanged—it reviews AC table / test / trace / adversarial verification evidence, and is independent of repository topology
Auto-commit constraint (protocol parameter auto_commit）
- Auto-commit when all tests pass and there is no Blocker, without asking
- Pause and ask when a Blocker appears or tests fail
- and
--headlessare mutually exclusive (--headlessalready includes auto-commit semantics) - Safety invariants same as
--headless: do not commit if tests have not passed, do not commit if a Blocker is unresolved
Memory file synchronization constraint
- Only updating the
## 当前状态section is allowed(ledger or status document link; when a task summary already exists, synchronize only its fields) - Modifying structural sections is prohibited(Project Overview, Skill Architecture, Conventions, etc. are managed by /agent-memory)
- CLAUDE.md is automatically imported via @AGENTS.md, no synchronization needed
- Only perform text replacement, do not call /agent-memory
- Skip if AGENTS.md does not exist, or if the "Current Status" section contains only ledger/status document links (without task number and progress fields); ⛔ do not add a progress snapshot
Orchestration isolation constraint
- Test Agent is forbidden to read existing implementations in src/; Impl Agent is forbidden to read 03-test-*.md and 01-requirements.md
- The orchestrator diffs the test files after Impl Agent completes; any change is a ⛔ Blocker
- The main Agent only performs orchestration and decision-making, and does not directly execute TDD
Full test verification constraint
- After batch mode completes, it is recommended to call
/test-run --trace(full verification + traceability check); trace traceability check may be incremental/lazy and does not block commits; trace gaps are recorded astrace_pendingrather than blocking; the tests themselves (affected/green verification skipped/todo=0) remain a quality floor that cannot be lowered - After single-task mode completes, it must call
/test-run --affected(tests affected by the change, based on git diff, see/test-runSKILL）--affectedwhen there is no match (test-run returns "recommend running full suite") → fall back to/test-run --trace- A single task must not skip this verification entirely, unless explicitly
--skip-trace="<原因>"and registered
-
--skip-traceis tightened: the reason must be written into the task ledgerskip_trace_reason, listed separately in the batch delivery report (to facilitate later re-runs) - Tasks that use
--skip-traceare automatically markedpostcheck_pending, and must not enter the "completed, can be skipped" state (recovery method: re-run/test-run --affectedor--trace, and only Step 1.5 [E] releases it) - Full/affected test failure does not roll back committed tasks (atomic commit already persisted)
- --headless / --auto-commit mode: log a warning to the delivery report, do not interrupt
Unattended constraints (protocol parameters unattended）
- workspace must be clean(validated before startup + after each task Commit 2)
- prerequisite dependencies must not be in "in progress" status(otherwise fail-fast)
- after fail-fast, output the resume command
- annotations must not be deleted during the fix process
- the number of assertions must not decrease during the fix process
- Suggestion is automatically skipped(unless
--fix-suggestions） - never push to remote
see auto-mode.md
task completion flow
After the Impl Agent completes, the orchestrator executes: test file immutability check (diff) → AC verification → adversarial verification → self-description update → commit decision → atomic commit (Commit 1 code + Commit 2 docs)
see execution-flow.md full steps and enforcement matrix
Commit message format
⛔ do not write any keel numbers or process status in the commit. Criterion: every piece of information must be understandable and usable by a maintainer who does not know keel exists. Task numbers, AC numbers, review batches, downgrade reasons are pure noise to them—their subject istask, which belongs to the task ledger (see below).
<type>(<scope>): <描述可观察结果的一句话>
Why: <只写代码和 diff 表达不了的决策、约束、取舍>
Tests: <实际执行过的精确命令>
| rule | mandatory | how to check |
|---|---|---|
the title describes an observable result, ⛔ without T-/F-/AC-/UT- number |
⛔ | lexical |
Tests is generated byactual execution recordexact command |
⛔ | machine-generated, ⛔ hand-filling "tested" is not allowed |
⛔ placeholder text forbidden: template original text,TODO、N/A, "related changes", "tests pass" |
⛔ | lexical check, not semantic verification |
Why only write trade-offs; mechanical changes ⛔ do not force fabrication |
soft | not judged |
| ⛔ do not restate the diff | — | git already stores it |
| keep commits atomic | soft | a small, single diff is easier to recover context from than four paragraphs of vague explanation |
banning placeholder text is the main defense against filling in blanks: it captures most of the benefit, yet is still only a lexical check. ⛔ using pure format
rulescannot guarantee Why is valuable—the strategy is to compress the subjective content that must be handwritten into one field, automatically generate the rest of the evidence, and ⛔ not pretend that format validation equals content quality.
type category：feat | fix | refactor | test | docs | chore
task ledger (the sole carrier of process status)
all 7 process fields previously attached as a footnote to Commit 1 are migrated to 04-dev-tasks.md 's task entry.
Their semantics were originally "task T-07's external review is still owed"—the subject is the task, not the commit.
| field | when to fill | semantics |
|---|---|---|
commits |
written by Commit 2 after Commit 1 is persisted | <repository>@<full-sha> + patch_id + one-sentence description, multiple allowed.same shape as the traceability matrix changed_by same shape, sharing the §2.4 three-level degradation chain |
review_state |
when fast/guarded is deferred | pending / done |
batch / due |
same as above | batch ID / sprint:<id> or YYYY-MM-DD |
pending_reason |
same as above | deferred-fast / deferred-guarded |
ext_review_state |
audit Phase 4 | EXT_REVIEWED / EXT_UNRESOLVED / EXT_BLOCKED |
profile_downgrade_reason |
when downgrading explicitly | reason for downgrade (not needed for upgrade) |
skip_trace_reason |
--skip-trace when |
reason for skipping the post trace validation |
exploration_mode |
exploration mode | true + evidence/exemption reason |
⛔ bound to task number, not to commit hash. when squash / rebase changes the hash,commits the archaeological index of the field
will become invalid, butthe gating status (review_state / batch / due) is unaffected—
this is the reason for binding them separately.
commits degradation chain when it becomes invalid(the same set as the traceability matrix, see sync trace-mode.md）：
| case | how drain does it |
|---|---|
| sha is resolvable | take that commit's diff and send it for external review |
sha is not resolvable + there is patch_id |
find an equivalent commit in the current history; if found, update commits and continue |
| none can be found | ⚠️ report drain.commit_not_found, keep review_pending；Recovery: manually locate the commit by description and backfill commits, or explicitly switch to re-reviewing the current code state (must be listed in the report) |
⛔ must not be judged as EXT_REVIEWEDjust because it cannot be located—no review means no evidence. But also ⛔ the task must not be allowed to
be permanently stuck: the Recovery in the third row of the table above is a clear way out and must be provided; do not merely report an error.
legal ext_review_state enum：EXT_REVIEWED / EXT_UNRESOLVED / EXT_BLOCKED.
Disable CONVERGED / DEGRADED / SKIPPED and other non-canonical terms.
Sub-Agent summary format
when this Skill runs as a Sub-Agent, the envelope follows shared constraint §2 yaml-summary-v1; private fields only go in summary.details：
| details field | meaning |
|---|---|
task |
task number T-XX |
commits.code / commits.docs |
Commit 1 code commit, Commit 2 document commit |
test_summary |
passed/failed/coverage |
blockers_resolved / suggestions_skipped |
result of this task |
ac_verified |
list of verified ACs |
decision_log |
key decision events such as Contract review, retry, Blocker fix, etc. |
current_milestone / milestones_pending |
segmented execution only: current segment, segment awaiting manual verification.must be uploaded with the envelope—the orchestration layer does not read the output document, it only consumes the summary; failing to upload it will make the upper layer treat "waiting for manual verification" as completion of the development phase and continue wrapping up |
next_recommended commonly used /sync; if Commit 2 has been completed, you may recommend /compound or leave it empty.
reference materials
- skeleton-examples.md - interface/test skeleton examples
- execution-flow.md - detailed task execution process
- verification-flow.md - detailed adversarial verification process
- task-orchestration.md - multi-task orchestration (batch/dependencies/resume from breakpoint)
- auto-mode.md - detailed unattended mode
- realign.md - dev-workflow spec_version rescan