@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.
- package/README.md +12 -0
- package/dist/migrations/manifests/0.4.0-beta.1.json +5 -5
- package/dist/migrations/manifests/0.5.14.json +9 -0
- package/dist/migrations/manifests/0.5.15.json +9 -0
- package/dist/migrations/manifests/0.5.16.json +9 -0
- package/dist/migrations/manifests/0.5.17.json +9 -0
- package/dist/migrations/manifests/0.5.19.json +9 -0
- package/dist/migrations/manifests/0.5.20.json +9 -0
- package/dist/migrations/manifests/0.5.21.json +9 -0
- package/dist/migrations/manifests/0.5.22.json +9 -0
- package/dist/migrations/manifests/0.5.23.json +9 -0
- package/dist/migrations/manifests/0.5.30.json +9 -0
- package/dist/migrations/manifests/0.6.1.json +9 -0
- package/dist/migrations/manifests/0.6.11.json +9 -0
- package/dist/migrations/manifests/0.6.20.json +9 -0
- package/dist/migrations/manifests/0.6.21.json +9 -0
- package/dist/templates/claude/agents/rudder-check.md +170 -143
- package/dist/templates/codex/agents/rudder-check.toml +95 -91
- package/dist/templates/codex/skills/update-spec/SKILL.md +14 -1
- package/dist/templates/common/skills/check.md +8 -1
- package/dist/templates/common/skills/update-spec.md +10 -3
- package/dist/templates/opencode/plugins/inject-workflow-state.js +17 -0
- package/dist/templates/rudder/config.yaml +35 -2
- package/dist/templates/rudder/index.d.ts +1 -0
- package/dist/templates/rudder/index.d.ts.map +1 -1
- package/dist/templates/rudder/index.js +2 -0
- package/dist/templates/rudder/index.js.map +1 -1
- package/dist/templates/rudder/scripts/common/config.py +42 -1
- package/dist/templates/rudder/scripts/common/task_context.py +42 -1
- package/dist/templates/rudder/scripts/common/task_readiness.py +169 -0
- package/dist/templates/rudder/scripts/common/task_store.py +10 -2
- package/dist/templates/rudder/scripts/common/types.py +1 -0
- package/dist/templates/rudder/scripts/task.py +28 -0
- package/dist/templates/rudder/workflow.md +52 -45
- package/dist/templates/shared-hooks/inject-subagent-context.py +116 -9
- package/dist/templates/shared-hooks/inject-workflow-state.py +33 -1
- package/dist/utils/task-json.d.ts +6 -0
- package/dist/utils/task-json.d.ts.map +1 -1
- package/dist/utils/task-json.js +6 -0
- package/dist/utils/task-json.js.map +1 -1
- 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
|
|
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
|
|
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
|
|
@@ -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
|
|
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.
|
|
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** —
|
|
155
|
-
**C Inline change** (per-turn
|
|
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
|
|
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.
|
|
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-
|
|
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
|
|
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
|
|
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 `[
|
|
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
|
|
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
|
|
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
|
-
| "
|
|
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
|
-
| "
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
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 `[
|
|
591
|
+
#### 3.3 Spec update `[conditional · once]`
|
|
589
592
|
|
|
590
|
-
Load
|
|
591
|
-
-
|
|
592
|
-
-
|
|
593
|
-
-
|
|
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
|
-
|
|
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.
|
|
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
|