@mengde1231/rudder 0.6.11 → 0.6.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +12 -0
  2. package/dist/migrations/manifests/0.4.0-beta.1.json +5 -5
  3. package/dist/migrations/manifests/0.5.14.json +9 -0
  4. package/dist/migrations/manifests/0.5.15.json +9 -0
  5. package/dist/migrations/manifests/0.5.16.json +9 -0
  6. package/dist/migrations/manifests/0.5.17.json +9 -0
  7. package/dist/migrations/manifests/0.5.19.json +9 -0
  8. package/dist/migrations/manifests/0.5.20.json +9 -0
  9. package/dist/migrations/manifests/0.5.21.json +9 -0
  10. package/dist/migrations/manifests/0.5.22.json +9 -0
  11. package/dist/migrations/manifests/0.5.23.json +9 -0
  12. package/dist/migrations/manifests/0.5.30.json +9 -0
  13. package/dist/migrations/manifests/0.6.1.json +9 -0
  14. package/dist/migrations/manifests/0.6.11.json +9 -0
  15. package/dist/migrations/manifests/0.6.20.json +9 -0
  16. package/dist/migrations/manifests/0.6.21.json +9 -0
  17. package/dist/templates/claude/agents/rudder-check.md +170 -143
  18. package/dist/templates/codex/agents/rudder-check.toml +95 -91
  19. package/dist/templates/codex/skills/update-spec/SKILL.md +14 -1
  20. package/dist/templates/common/skills/check.md +8 -1
  21. package/dist/templates/common/skills/update-spec.md +10 -3
  22. package/dist/templates/opencode/plugins/inject-workflow-state.js +17 -0
  23. package/dist/templates/rudder/config.yaml +35 -2
  24. package/dist/templates/rudder/index.d.ts +1 -0
  25. package/dist/templates/rudder/index.d.ts.map +1 -1
  26. package/dist/templates/rudder/index.js +2 -0
  27. package/dist/templates/rudder/index.js.map +1 -1
  28. package/dist/templates/rudder/scripts/common/config.py +42 -1
  29. package/dist/templates/rudder/scripts/common/task_context.py +42 -1
  30. package/dist/templates/rudder/scripts/common/task_readiness.py +169 -0
  31. package/dist/templates/rudder/scripts/common/task_store.py +10 -2
  32. package/dist/templates/rudder/scripts/common/types.py +1 -0
  33. package/dist/templates/rudder/scripts/task.py +28 -0
  34. package/dist/templates/rudder/workflow.md +52 -45
  35. package/dist/templates/shared-hooks/inject-subagent-context.py +116 -9
  36. package/dist/templates/shared-hooks/inject-workflow-state.py +33 -1
  37. package/dist/utils/task-json.d.ts +6 -0
  38. package/dist/utils/task-json.d.ts.map +1 -1
  39. package/dist/utils/task-json.js +6 -0
  40. package/dist/utils/task-json.js.map +1 -1
  41. package/package.json +2 -2
@@ -0,0 +1,169 @@
1
+ #!/usr/bin/env python3
2
+ """Readiness checks for entering the implementation phase."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import hashlib
7
+ import json
8
+ import re
9
+ from pathlib import Path
10
+
11
+
12
+ _SECTION_RE = re.compile(r"^##\s+(.+?)\s*$", re.IGNORECASE)
13
+ _CHECKBOX_RE = re.compile(r"^\s*[-*+]\s+\[[ xX]\]\s+\S+")
14
+ _EMPTY_QUESTIONS = {
15
+ "none",
16
+ "no",
17
+ "n/a",
18
+ "na",
19
+ "resolved",
20
+ "\u65e0",
21
+ "\u65e0\u95ee\u9898",
22
+ "\u5df2\u89e3\u51b3",
23
+ }
24
+
25
+ # Conservative checks for unambiguous mutually exclusive rules.
26
+ _CONFLICT_RULES: tuple[tuple[str, str, str], ...] = (
27
+ (
28
+ "automatic save vs explicit save",
29
+ r"(?:automatic|auto[- ]?)save|自动保存",
30
+ r"(?:click(?:s|ed)?|button|manual|explicit)[ -]?save|点击保存|手动保存|点击[“\"]?保存",
31
+ ),
32
+ (
33
+ "lock after success vs continue editing",
34
+ r"(?:lock|locked|read[- ]only)\b.{0,50}(?:after|on|when)?\s*success|成功后锁定|成功后只读",
35
+ r"(?:continue|仍可|继续)\s*(?:edit|editing)|成功后继续编辑|成功后仍可编辑",
36
+ ),
37
+ (
38
+ "row mutation allowed vs forbidden",
39
+ r"(?:allow|支持|允许).{0,30}(?:add|delete|remove)\s*(?:row|rows)?|允许新增|允许删除|可新增|可删除",
40
+ r"(?:cannot|must not|禁止|不允许).{0,30}(?:add|delete|remove)\s*(?:row|rows)?|禁止新增|禁止删除|不可新增|不可删除",
41
+ ),
42
+ )
43
+
44
+
45
+ def prd_hash(prd_path: Path) -> str:
46
+ """Return a stable SHA-256 hash for a UTF-8 PRD file."""
47
+ return hashlib.sha256(prd_path.read_bytes()).hexdigest()
48
+
49
+
50
+ def _section_body(content: str, title: str) -> list[str] | None:
51
+ lines = content.splitlines()
52
+ in_section = False
53
+ body: list[str] = []
54
+ for line in lines:
55
+ match = _SECTION_RE.match(line.strip())
56
+ if match:
57
+ if in_section:
58
+ break
59
+ in_section = match.group(1).strip().lower() == title.lower()
60
+ continue
61
+ if in_section:
62
+ body.append(line)
63
+ return body if in_section else None
64
+
65
+
66
+ def _has_unresolved_questions(body: list[str]) -> bool:
67
+ for line in body:
68
+ value = re.sub(r"^\s*(?:[-*+]\s+|\d+[.)]\s+)", "", line).strip()
69
+ if not value or value.startswith("<!--") or value.endswith("-->"):
70
+ continue
71
+ if value.lower().rstrip("。.!!") in _EMPTY_QUESTIONS:
72
+ continue
73
+ return True
74
+ return False
75
+
76
+
77
+ def validate_prd(prd_path: Path) -> list[str]:
78
+ """Validate the minimum PRD contract required before implementation."""
79
+ errors: list[str] = []
80
+ if not prd_path.is_file():
81
+ return ["prd.md is missing"]
82
+
83
+ try:
84
+ content = prd_path.read_text(encoding="utf-8")
85
+ except OSError as exc:
86
+ return [f"prd.md cannot be read: {exc}"]
87
+ if not content.strip():
88
+ errors.append("prd.md is empty")
89
+
90
+ acceptance = _section_body(content, "Acceptance Criteria")
91
+ if acceptance is None:
92
+ errors.append("prd.md is missing an 'Acceptance Criteria' section")
93
+ elif not any(_CHECKBOX_RE.match(line) for line in acceptance):
94
+ errors.append("Acceptance Criteria must contain at least one checklist item")
95
+
96
+ questions = _section_body(content, "Open Questions")
97
+ if questions is not None and _has_unresolved_questions(questions):
98
+ errors.append("prd.md contains unresolved Open Questions")
99
+ lowered = content.lower()
100
+ for label, left, right in _CONFLICT_RULES:
101
+ if re.search(left, lowered, re.IGNORECASE) and re.search(right, lowered, re.IGNORECASE):
102
+ errors.append(f"prd.md contains conflicting rules: {label}")
103
+ return errors
104
+
105
+
106
+ def _jsonl_entries(path: Path, repo_root: Path) -> tuple[int, list[str]]:
107
+ if not path.is_file():
108
+ return 0, [f"{path.name} is missing"]
109
+ entries = 0
110
+ errors: list[str] = []
111
+ for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
112
+ if not line.strip():
113
+ continue
114
+ try:
115
+ data = json.loads(line)
116
+ except json.JSONDecodeError:
117
+ errors.append(f"{path.name}:{line_number} contains invalid JSON")
118
+ continue
119
+ file_path = data.get("file")
120
+ if not file_path:
121
+ continue
122
+ entries += 1
123
+ target = repo_root / str(file_path).rstrip("/")
124
+ if data.get("type", "file") == "directory":
125
+ if not target.is_dir():
126
+ errors.append(f"{path.name}:{line_number} references missing directory: {file_path}")
127
+ elif not target.is_file():
128
+ errors.append(f"{path.name}:{line_number} references missing file: {file_path}")
129
+ return entries, errors
130
+
131
+
132
+ def validate_context_files(task_dir: Path, repo_root: Path) -> list[str]:
133
+ """Validate JSONL only when the task opted into sub-agent context files."""
134
+ files = [task_dir / "implement.jsonl", task_dir / "check.jsonl"]
135
+ if not any(path.exists() for path in files):
136
+ return []
137
+ errors: list[str] = []
138
+ for path in files:
139
+ entries, entry_errors = _jsonl_entries(path, repo_root)
140
+ errors.extend(entry_errors)
141
+ if entries == 0:
142
+ errors.append(f"{path.name} has no curated context entries (seed-only or empty)")
143
+ return errors
144
+
145
+
146
+ def validate_task_readiness(
147
+ task_dir: Path,
148
+ repo_root: Path,
149
+ task_data: dict,
150
+ ) -> list[str]:
151
+ """Return blocking reasons for a planning task entering implementation."""
152
+ errors = validate_prd(task_dir / "prd.md")
153
+ errors.extend(validate_context_files(task_dir, repo_root))
154
+
155
+ requirements = task_data.get("requirements")
156
+ if not isinstance(requirements, dict) or requirements.get("status") != "confirmed":
157
+ errors.append("requirements are not confirmed; run 'task.py confirm <task-dir>'")
158
+ else:
159
+ expected_hash = requirements.get("prd_hash")
160
+ prd_path = task_dir / "prd.md"
161
+ current_hash: str | None = None
162
+ if prd_path.is_file():
163
+ try:
164
+ current_hash = prd_hash(prd_path)
165
+ except OSError:
166
+ current_hash = None
167
+ if not isinstance(expected_hash, str) or expected_hash != current_hash:
168
+ errors.append("prd.md changed after confirmation; reconfirm the requirements")
169
+ return errors
@@ -229,6 +229,12 @@ def cmd_create(args: argparse.Namespace) -> int:
229
229
  "relatedFiles": [],
230
230
  "notes": "",
231
231
  "meta": {},
232
+ "requirements": {
233
+ "status": "pending",
234
+ "confirmed_by": None,
235
+ "confirmed_at": None,
236
+ "prd_hash": None,
237
+ },
232
238
  }
233
239
 
234
240
  write_json(task_json_path, task_data)
@@ -293,9 +299,11 @@ def cmd_create(args: argparse.Namespace) -> int:
293
299
  "see .rudder/workflow.md Phase 1.3)",
294
300
  file=sys.stderr,
295
301
  )
296
- print(" 3. Run: python3 task.py start <dir>", file=sys.stderr)
302
+ print(" 3. Run: python3 task.py confirm <dir>", file=sys.stderr)
303
+ print(" 4. Run: python3 task.py start <dir>", file=sys.stderr)
297
304
  else:
298
- print(" 2. Run: python3 task.py start <dir>", file=sys.stderr)
305
+ print(" 2. Run: python3 task.py confirm <dir>", file=sys.stderr)
306
+ print(" 3. Run: python3 task.py start <dir>", file=sys.stderr)
299
307
  print("", file=sys.stderr)
300
308
 
301
309
  # Output relative path for script chaining
@@ -49,6 +49,7 @@ class TaskData(TypedDict, total=False):
49
49
  relatedFiles: list[str]
50
50
  notes: str
51
51
  meta: dict
52
+ requirements: dict
52
53
 
53
54
 
54
55
  # =============================================================================
@@ -7,6 +7,7 @@ Usage:
7
7
  python3 task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>]
8
8
  python3 task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
9
9
  python3 task.py validate <dir> # Validate jsonl files
10
+ python3 task.py confirm <dir> # Confirm PRD requirements
10
11
  python3 task.py list-context <dir> # List jsonl entries
11
12
  python3 task.py start <dir> # Set active task
12
13
  python3 task.py current [--source] # Show active task
@@ -58,9 +59,11 @@ from common.task_store import (
58
59
  )
59
60
  from common.task_context import (
60
61
  cmd_add_context,
62
+ cmd_confirm,
61
63
  cmd_validate,
62
64
  cmd_list_context,
63
65
  )
66
+ from common.task_readiness import validate_task_readiness
64
67
 
65
68
 
66
69
  # =============================================================================
@@ -92,6 +95,25 @@ def cmd_start(args: argparse.Namespace) -> int:
92
95
 
93
96
  task_json_path = full_path / FILE_TASK_JSON
94
97
 
98
+ if not task_json_path.is_file():
99
+ print(colored(f"Error: task.json not found at {full_path}", Colors.RED))
100
+ return 1
101
+
102
+ # Only planning -> implementation is gated. Re-running start for an
103
+ # already active task remains idempotent for existing sessions.
104
+ task_data = read_json(task_json_path)
105
+ if not task_data:
106
+ print(colored(f"Error: task.json is invalid at {full_path}", Colors.RED))
107
+ return 1
108
+ if task_data and task_data.get("status") == "planning":
109
+ readiness_errors = validate_task_readiness(full_path, repo_root, task_data)
110
+ if readiness_errors:
111
+ print(colored("Task is not ready for implementation:", Colors.RED))
112
+ for error in readiness_errors:
113
+ print(f" - {error}")
114
+ print("Hint: complete the PRD, run task.py confirm, then retry task.py start.")
115
+ return 1
116
+
95
117
  if not resolve_context_key():
96
118
  # Degraded mode: no session identity available.
97
119
  # Hook didn't inject RUDDER_CONTEXT_ID (common on Windows + Claude Code,
@@ -309,6 +331,7 @@ Usage:
309
331
  python3 task.py create <title> --parent <dir> Create task as child of parent
310
332
  python3 task.py add-context <dir> <jsonl> <path> [reason] Add entry to jsonl
311
333
  python3 task.py validate <dir> Validate jsonl files
334
+ python3 task.py confirm <dir> Confirm requirements and PRD
312
335
  python3 task.py list-context <dir> List jsonl entries
313
336
  python3 task.py start <dir> Set active task
314
337
  python3 task.py current [--source] Show active task
@@ -410,6 +433,10 @@ def main() -> int:
410
433
  p_validate = subparsers.add_parser("validate", help="Validate context files")
411
434
  p_validate.add_argument("dir", help="Task directory")
412
435
 
436
+ # confirm
437
+ p_confirm = subparsers.add_parser("confirm", help="Confirm task requirements")
438
+ p_confirm.add_argument("dir", help="Task directory")
439
+
413
440
  # list-context
414
441
  p_listctx = subparsers.add_parser("list-context", help="List context entries")
415
442
  p_listctx.add_argument("dir", help="Task directory")
@@ -475,6 +502,7 @@ def main() -> int:
475
502
  "create": cmd_create,
476
503
  "add-context": cmd_add_context,
477
504
  "validate": cmd_validate,
505
+ "confirm": cmd_confirm,
478
506
  "list-context": cmd_list_context,
479
507
  "start": cmd_start,
480
508
  "current": cmd_current,
@@ -73,7 +73,7 @@ python3 ./.rudder/scripts/task.py create-pr [name] [--dry-run]
73
73
 
74
74
  > Run `python3 ./.rudder/scripts/task.py --help` to see the authoritative, up-to-date list.
75
75
 
76
- **Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.rudder/.runtime/sessions/`. If no context key is available from hook input, `RUDDER_CONTEXT_ID`, or a platform-native session environment variable, there is no active task and `task.py start` fails with a session identity hint. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
76
+ **Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. After the final PRD is confirmed with `task.py confirm`, `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`; it refuses to start when the PRD, confirmation hash, acceptance criteria, or applicable JSONL context is incomplete. State is stored under `.rudder/.runtime/sessions/`. If no context key is available, start still performs the readiness gate and then uses degraded mode without persisting a session pointer. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task.
77
77
 
78
78
  ### Workspace System
79
79
 
@@ -120,7 +120,7 @@ python3 ./.rudder/scripts/get_context.py --mode phase --step <X.Y> # detailed g
120
120
  TAG ↔ PHASE scoping:
121
121
  [workflow-state:no_task] → no active task; before Phase 1
122
122
  [workflow-state:planning] → all of Phase 1 (status='planning')
123
- [workflow-state:in_progress] → Phase 2 + Phase 3.1-3.4
123
+ [workflow-state:in_progress] → Phase 2 + Phase 3.2-3.4
124
124
  (status stays 'in_progress' from
125
125
  task.py start until task.py archive)
126
126
  [workflow-state:completed] → currently DEAD: cmd_archive flips
@@ -151,8 +151,8 @@ Phase 3: Finish → distill lessons + wrap-up
151
151
 
152
152
  [workflow-state:no_task]
153
153
  No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat; no file writes + one-line answer + repo reads ≤ 2 files → AI judges, no override needed.
154
- **B Create a task** — any implementation / code change / build / refactor work. Entry sequence: (1) `python3 ./.rudder/scripts/task.py create "<title>"` to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load `rudder-brainstorm` skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run `task.py start <task-dir>` to enter [workflow-state:in_progress] for the implementation skeleton. **"It looks small" is NOT grounds for downgrading B to A or C**.
155
- **C Inline change** (per-turn only, escape hatch for B) — the user's CURRENT message MUST contain one of: "skip rudder" / "no task" / "just do it" / "don't create a task" / "跳过 rudder" / "别走流程" / "小修一下" / "直接改" / "先别建任务" → briefly acknowledge ("ok, skipping rudder flow this turn"), then inline. **Without seeing one of these phrases you must NOT inline on your own**; do not invent an override the user never said.
154
+ **B Create a task** — implementation / code change / build / refactor work that is not an explicit Fast Path or requires a durable task record. Entry sequence: create the task, load `rudder-brainstorm`, complete the PRD and required context, then run `task.py start <task-dir>`.
155
+ **C Inline change** (per-turn fast path) — the user's CURRENT message may explicitly contain one of: "skip rudder" / "no task" / "just do it" / "don't create a task" / "跳过 rudder" / "别走流程" / "小修一下" / "直接改" / "先别建任务". When present, acknowledge briefly, skip task creation and per-turn workflow injection, then make the requested low-risk change and run the smallest relevant validation. This is not permission to bypass safety checks for database, API, permission, transaction, cache, or cross-module changes.
156
156
  [/workflow-state:no_task]
157
157
 
158
158
  ### Phase 1: Plan
@@ -170,7 +170,7 @@ No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat;
170
170
  Load the `rudder-brainstorm` skill and iterate on prd.md with the user.
171
171
  Phase 1.0.5 (conditional, once): if this task involves DDL operations (create/alter tables, add/drop columns, migration scripts), create `{TASK_DIR}/sql/` via `mkdir -p .rudder/tasks/<task-dir>/sql/`. Skip if no database changes.
172
172
  Phase 1.3 (required, once): before `task.py start`, you MUST curate `implement.jsonl` and `check.jsonl` — list the spec / research files sub-agents need so they get the right context injected. You may skip only if the jsonl already has agent-curated entries (the seed `_example` row alone doesn't count).
173
- Then run `task.py start <task-dir>` to flip status to in_progress.
173
+ Before `task.py start`, run `task.py confirm <task-dir>` after the user approves the final `prd.md`; this records the PRD hash and blocks stale or unconfirmed requirements. Then run `task.py start <task-dir>` to flip status to in_progress.
174
174
  [/workflow-state:planning]
175
175
 
176
176
  <!-- Per-turn breadcrumb: shown throughout Phase 1 when codex.dispatch_mode=inline.
@@ -183,22 +183,22 @@ Then run `task.py start <task-dir>` to flip status to in_progress.
183
183
  Load the `rudder-brainstorm` skill and iterate on prd.md with the user.
184
184
  Phase 1.0.5 (conditional, once): if this task involves DDL operations (create/alter tables, add/drop columns, migration scripts), create `{TASK_DIR}/sql/` via `mkdir -p .rudder/tasks/<task-dir>/sql/`. Skip if no database changes.
185
185
  Phase 1.3 jsonl curation is **skipped** in inline dispatch mode — the main session loads `rudder-before-dev` directly in Phase 2 and reads spec context itself, so there is no sub-agent to inject jsonl into.
186
- Then run `task.py start <task-dir>` to flip status to in_progress.
186
+ Before `task.py start`, run `task.py confirm <task-dir>` after the user approves the final `prd.md`; this records the PRD hash and blocks stale or unconfirmed requirements. Then run `task.py start <task-dir>` to flip status to in_progress.
187
187
  [/workflow-state:planning-inline]
188
188
 
189
189
  ### Phase 2: Execute
190
- - 2.1 Implement `[required · repeatable]`
191
- - 2.2 Quality check `[required · repeatable]`
190
+ - 2.1 Implement `[required · repeatable until complete]`
191
+ - 2.2 Verify `[required · after implementation; repeat only after fixes]`
192
192
  - 2.3 Rollback `[on demand]`
193
193
 
194
194
  <!-- Per-turn breadcrumb: shown while status='in_progress'.
195
- Scope: all of Phase 2 + Phase 3.1-3.4 (status stays 'in_progress' from
195
+ Scope: all of Phase 2 + Phase 3.2-3.4 (status stays 'in_progress' from
196
196
  task.py start until task.py archive; only archive flips it). The body
197
197
  therefore must cover every required step from implementation through
198
198
  commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
199
199
 
200
200
  [workflow-state:in_progress]
201
- **Flow**: rudder-implement → rudder-check → rudder-update-spec → commit (Phase 3.4) → `/rudder:finish-work`.
201
+ **Flow**: finish all implementation work → rudder-check review → Verify (lint/type-check/tests/build) → fix all findings → rerun Verify if needed → conditional rudder-update-spec → commit (Phase 3.4) → `/rudder:finish-work`.
202
202
  **Main-session default (no override)**: dispatch the `rudder-implement` / `rudder-check` sub-agents — the main agent does NOT edit code by default. Phase 3.4 commit (required, once): after rudder-update-spec, or whenever implementation is verifiably complete, the main agent **drives the commit** — run `git diff --stat` to show changes, state the proposed commit message, then check `code_auto_commit` in `.rudder/config.yaml`: if **false** (default), **ask the user for confirmation (Y/n)** before running `git commit`; if **true**, commit directly without prompting. Only after commit, suggest `/rudder:finish-work`. `/finish-work` refuses to run on a dirty working tree (paths outside `.rudder/workspace/` and `.rudder/tasks/`).
203
203
  **Sub-agent self-exemption**: if you are already running as `rudder-implement`, implement directly from the loaded task context and do NOT spawn another `rudder-implement`; if you are already running as `rudder-check`, review/fix directly and do NOT spawn another `rudder-check`. The default dispatch rule applies to the main session only.
204
204
  **Sub-agent dispatch protocol (all platforms, all sub-agents)**: When you spawn `rudder-implement` / `rudder-check` / `rudder-research`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) the line is normally redundant — the hook injects context directly — but it serves as a critical fallback when the hook fails (Windows + Claude Code PreToolUse silent skip, `--continue` resume, fork distribution, hooks disabled, etc.). For `rudder-research`, the line tells the sub-agent which `{task_dir}/research/` to write into.
@@ -211,15 +211,15 @@ Then run `task.py start <task-dir>` to flip status to in_progress.
211
211
  instead of dispatching sub-agents. -->
212
212
 
213
213
  [workflow-state:in_progress-inline]
214
- **Flow** (inline mode): main session loads `rudder-before-dev` → main session edits code → main session loads `rudder-check` → run lint / type-check / tests → fix → `rudder-update-spec` → commit (Phase 3.4) → `/rudder:finish-work`.
214
+ **Flow** (inline mode): main session loads `rudder-before-dev` → main session finishes all code changes → main session loads `rudder-check` for the full task diff → Verify lint / type-check / tests / build → fix all findings → rerun Verify if needed → conditional `rudder-update-spec` → commit (Phase 3.4) → `/rudder:finish-work`.
215
215
  **Main-session default (inline dispatch_mode)**: the main agent edits code directly. Do NOT dispatch `rudder-implement` / `rudder-check` sub-agents. Load the `rudder-before-dev` skill before writing code; load the `rudder-check` skill before reporting completion.
216
216
  Phase 3.4 commit (required, once): after `rudder-update-spec`, or whenever implementation is verifiably complete, the main agent **drives the commit** — run `git diff --stat` to show changes, state the proposed commit message, then check `code_auto_commit` in `.rudder/config.yaml`: if **false** (default), **ask the user for confirmation (Y/n)** before running `git commit`; if **true**, commit directly without prompting. Only after commit, suggest `/rudder:finish-work`. `/finish-work` refuses to run on a dirty working tree (paths outside `.rudder/workspace/` and `.rudder/tasks/`).
217
217
  [/workflow-state:in_progress-inline]
218
218
 
219
219
  ### Phase 3: Finish
220
- - 3.1 Quality verification `[required · repeatable]`
220
+ - 3.1 Verify evidence `[folded into 2.2 and commit preamble]`
221
221
  - 3.2 Debug retrospective `[on demand]`
222
- - 3.3 Spec update `[required · once]`
222
+ - 3.3 Spec update `[conditional · once]`
223
223
  - 3.4 Commit changes `[required · once]`
224
224
  - 3.5 Wrap-up reminder
225
225
 
@@ -254,7 +254,7 @@ When a user request matches one of these intents, load the corresponding skill (
254
254
  |---|---|
255
255
  | Wants a new feature / requirement unclear | `rudder-brainstorm` |
256
256
  | About to write code / start implementing | Dispatch the `rudder-implement` sub-agent per Phase 2.1 |
257
- | Finished writing / want to verify | Dispatch the `rudder-check` sub-agent per Phase 2.2 |
257
+ | Finished all implementation / want to verify | Dispatch the `rudder-check` sub-agent once per Phase 2.2 |
258
258
  | Stuck / fixed same bug several times | `rudder-break-loop` |
259
259
  | Spec needs update | `rudder-update-spec` |
260
260
 
@@ -268,7 +268,7 @@ When a user request matches one of these intents, load the corresponding skill (
268
268
  |---|---|
269
269
  | Wants a new feature / requirement unclear | `rudder-brainstorm` |
270
270
  | About to write code / start implementing | `rudder-before-dev` (then implement directly in the main session) |
271
- | Finished writing / want to verify | `rudder-check` |
271
+ | Finished all implementation / want to verify | `rudder-check` |
272
272
  | Stuck / fixed same bug several times | `rudder-break-loop` |
273
273
  | Spec needs update | `rudder-update-spec` |
274
274
 
@@ -283,7 +283,7 @@ When a user request matches one of these intents, load the corresponding skill (
283
283
  | "This is simple, I'll just code it in the main thread" | Dispatching `rudder-implement` is the cheap path; skipping it tempts you to write code in the main thread and lose spec context — sub-agents get `implement.jsonl` injected, you don't |
284
284
  | "I already thought it through in plan mode" | Plan-mode output lives in memory — sub-agents can't see it; must be persisted to prd.md |
285
285
  | "I already know the spec" | The spec may have been updated since you last read it; the sub-agent gets the fresh copy, you may not |
286
- | "Code first, check later" | `rudder-check` surfaces issues you won't notice yourself; earlier is cheaper |
286
+ | "Check after every small change" | Check is a post-implementation gate; finish the complete change set first so the reviewer sees the real cross-file contract |
287
287
 
288
288
  [/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
289
289
 
@@ -294,7 +294,7 @@ When a user request matches one of these intents, load the corresponding skill (
294
294
  | "This is simple, just code it" | Simple tasks often grow complex; `rudder-before-dev` takes under a minute and loads the spec context you'll need |
295
295
  | "I already thought it through in plan mode" | Plan-mode output lives in memory — must be persisted to prd.md before code |
296
296
  | "I already know the spec" | The spec may have been updated since you last read it; read again |
297
- | "Code first, check later" | `rudder-check` surfaces issues you won't notice yourself; earlier is cheaper |
297
+ | "Check after every small change" | Check is a post-implementation gate; finish the complete change set first so the reviewer sees the real cross-file contract |
298
298
 
299
299
  [/codex-inline, Kilo, Antigravity, Windsurf]
300
300
 
@@ -437,9 +437,10 @@ Skip this step. Context is loaded directly by the `rudder-before-dev` skill in P
437
437
 
438
438
  #### 1.4 Activate task `[required · once]`
439
439
 
440
- Once prd.md is complete and 1.3 jsonl curation is done, flip the task status to `in_progress`:
440
+ Once prd.md is complete, the user has confirmed it, and 1.3 jsonl curation is done when applicable, confirm and activate the task:
441
441
 
442
442
  ```bash
443
+ python3 ./.rudder/scripts/task.py confirm <task-dir>
443
444
  python3 ./.rudder/scripts/task.py start <task-dir>
444
445
  ```
445
446
 
@@ -452,6 +453,7 @@ If `task.py start` errors with a session-identity message (no context key from h
452
453
  | Condition | Required |
453
454
  |------|:---:|
454
455
  | `prd.md` exists | ✅ |
456
+ | `prd.md` has acceptance criteria and no unresolved questions/conflicts | ✅ |
455
457
  | User confirms requirements | ✅ |
456
458
  | `task.py start` has been run (status = in_progress) | ✅ |
457
459
  | `research/` has artifacts (complex tasks) | recommended |
@@ -467,16 +469,18 @@ If `task.py start` errors with a session-identity message (no context key from h
467
469
 
468
470
  ## Phase 2: Execute
469
471
 
470
- Goal: turn the prd into code that passes quality checks.
472
+ Goal: turn the confirmed PRD into code. Project syntax, build, lint, type-check,
473
+ and business acceptance tests are run after implementation during Phase 3;
474
+ `task.py start` performs readiness checks only and does not replace those checks.
471
475
 
472
- #### 2.1 Implement `[required · repeatable]`
476
+ #### 2.1 Implement `[required · repeatable until complete]`
473
477
 
474
478
  [Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
475
479
 
476
480
  Spawn the implement sub-agent:
477
481
 
478
482
  - **Agent type**: `rudder-implement`
479
- - **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
483
+ - **Task description**: Implement all requirements in prd.md, consulting materials under `{TASK_DIR}/research/`; continue until the complete change set is written and report implementation complete. Do not dispatch `rudder-check` or run the quality gate during this step.
480
484
  - **Dispatch prompt guard**: Tell the spawned agent it is already the `rudder-implement` sub-agent and must implement directly, not spawn another `rudder-implement` / `rudder-check`.
481
485
 
482
486
  The platform hook/plugin auto-handles:
@@ -490,7 +494,7 @@ The platform hook/plugin auto-handles:
490
494
  Spawn the implement sub-agent:
491
495
 
492
496
  - **Agent type**: `rudder-implement`
493
- - **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
497
+ - **Task description**: Implement all requirements in prd.md, consulting materials under `{TASK_DIR}/research/`; continue until the complete change set is written and report implementation complete. Do not dispatch `rudder-check` or run the quality gate during this step.
494
498
  - **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `rudder-implement` and must implement directly without spawning another `rudder-implement` / `rudder-check`.
495
499
 
496
500
  The Codex sub-agent definition auto-handles the context load requirement:
@@ -504,7 +508,7 @@ The Codex sub-agent definition auto-handles the context load requirement:
504
508
  Spawn the implement sub-agent:
505
509
 
506
510
  - **Agent type**: `rudder-implement`
507
- - **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
511
+ - **Task description**: Implement all requirements in prd.md, consulting materials under `{TASK_DIR}/research/`; continue until the complete change set is written and report implementation complete. Do not dispatch `rudder-check` or run the quality gate during this step.
508
512
  - **Dispatch prompt guard**: Tell the spawned agent it is already the `rudder-implement` sub-agent and must implement directly, not spawn another `rudder-implement` / `rudder-check`.
509
513
 
510
514
  The platform prelude auto-handles the context load requirement:
@@ -518,19 +522,28 @@ The platform prelude auto-handles the context load requirement:
518
522
  1. Load the `rudder-before-dev` skill to read project guidelines
519
523
  2. Read `{TASK_DIR}/prd.md` for requirements
520
524
  3. Consult materials under `{TASK_DIR}/research/`
521
- 4. Implement the code per requirements
522
- 5. Run project lint and type-check
525
+ 4. Implement the complete code change per requirements
526
+ 5. Report implementation complete; do not load `rudder-check` yet
523
527
 
524
528
  [/codex-inline, Kilo, Antigravity, Windsurf]
525
529
 
526
- #### 2.2 Quality check `[required · repeatable]`
530
+ #### 2.2 Verify `[required · after implementation; repeat only after fixes]`
531
+
532
+ **Check/Verify boundary (mandatory):** `Check` is the review of the complete
533
+ diff; `Verify` is the execution of lint, type-check, tests, build, and business
534
+ acceptance commands. Do not dispatch or load `rudder-check` while
535
+ 2.1 is still writing code. The implementer must finish the complete
536
+ requirement set first. Then run Check once over the full task diff, followed by
537
+ one Verify pass. If Check or Verify finds issues, fix them and rerun the
538
+ affected stage; do not alternate implementation and verification for individual
539
+ files or partial requirements.
527
540
 
528
541
  [Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi]
529
542
 
530
543
  Spawn the check sub-agent:
531
544
 
532
545
  - **Agent type**: `rudder-check`
533
- - **Task description**: Review all code changes against spec and prd; fix any findings directly; ensure lint and type-check pass
546
+ - **Task description**: Review the complete implementation diff against spec and prd, then run the Verify commands (lint, type-check, tests, and build). Fix all findings directly. This is the first full Check + Verify pass for the task, not an incremental review.
534
547
  - **Dispatch prompt guard**: Tell the spawned agent it is already the `rudder-check` sub-agent and must review/fix directly, not spawn another `rudder-check` / `rudder-implement`.
535
548
 
536
549
  The check agent's job:
@@ -544,7 +557,7 @@ The check agent's job:
544
557
 
545
558
  [codex-inline, Kilo, Antigravity, Windsurf]
546
559
 
547
- Load the `rudder-check` skill and verify the code per its guidance:
560
+ Only after the complete implementation is written, load the `rudder-check` skill for the full Check + Verify pass:
548
561
  - Spec compliance
549
562
  - lint / type-check / tests
550
563
  - Compile/build verification (detect project type, run `mvn compile` / `go build` / `cargo check`, fix errors up to 3 rounds)
@@ -566,16 +579,6 @@ If issues are found → fix → re-check, until green.
566
579
 
567
580
  Goal: ensure code quality, capture lessons, record the work.
568
581
 
569
- #### 3.1 Quality verification `[required · repeatable]`
570
-
571
- Load the `rudder-check` skill and do a final verification:
572
- - Spec compliance
573
- - lint / type-check / tests
574
- - Compile/build verification (detect project type, run compile command, fix errors up to 3 rounds)
575
- - Cross-layer consistency (when changes span layers)
576
-
577
- If issues are found → fix → re-check, until green.
578
-
579
582
  #### 3.2 Debug retrospective `[on demand]`
580
583
 
581
584
  If this task involved repeated debugging (the same issue was fixed multiple times), load the `rudder-break-loop` skill to:
@@ -585,14 +588,18 @@ If this task involved repeated debugging (the same issue was fixed multiple time
585
588
 
586
589
  The goal is to capture debugging lessons so the same class of issue doesn't recur.
587
590
 
588
- #### 3.3 Spec update `[required · once]`
591
+ #### 3.3 Spec update `[conditional · once]`
589
592
 
590
- Load the `rudder-update-spec` skill and review whether this task produced new knowledge worth recording:
591
- - Newly discovered patterns or conventions
592
- - Pitfalls you hit
593
- - New technical decisions
593
+ Load `rudder-update-spec` only when this task adds or changes durable project knowledge:
594
+ - a business rule, workflow, state transition, or acceptance rule that future tasks must follow;
595
+ - an API/DTO/VO, database, permission, transaction, cache, or other cross-layer contract;
596
+ - a reusable implementation pattern, technical convention, or prevention rule;
597
+ - a bug or mismatch showing that the current Spec is incomplete or incorrect.
594
598
 
595
- Update the docs under `.rudder/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment.
599
+ The task's current business requirements always belong in `prd.md`; a one-off page,
600
+ copy, customer campaign, or implementation detail does not require a Spec update.
601
+ If none of these triggers apply, record "no durable Spec change" in the task summary
602
+ and continue without loading the full update-spec skill.
596
603
 
597
604
  #### 3.4 Commit changes `[required · once]`
598
605
 
@@ -664,7 +671,7 @@ All 4 tag blocks live in the `## Phase Index` section above, immediately after e
664
671
  |---|---|
665
672
  | No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
666
673
  | All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
667
- | Phase 2 + Phase 3.1–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
674
+ | Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
668
675
  | After Phase 3.5 (archived) | `[workflow-state:completed]` (after Phase 3 summary; **currently DEAD**) |
669
676
 
670
677
  ### Changing the per-turn prompt text