@mengde1231/rudder 0.6.21 → 0.6.22

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 (22) hide show
  1. package/README.md +148 -148
  2. package/bin/rudder.js +0 -0
  3. package/dist/migrations/manifests/0.6.22.json +9 -0
  4. package/dist/templates/claude/agents/rudder-check.md +170 -170
  5. package/dist/templates/codex/agents/rudder-check.toml +95 -95
  6. package/dist/templates/codex/config.toml +30 -30
  7. package/dist/templates/common/bundled-skills/rudder-meta/references/customize-local/change-workflow.md +5 -4
  8. package/dist/templates/common/bundled-skills/rudder-meta/references/local-architecture/task-system.md +7 -2
  9. package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/SKILL.md +41 -41
  10. package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/mcp-setup.md +90 -90
  11. package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/repository-analysis.md +59 -59
  12. package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-task-planning.md +61 -61
  13. package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-writing.md +70 -70
  14. package/dist/templates/common/commands/continue.md +9 -5
  15. package/dist/templates/common/commands/start.md +8 -8
  16. package/dist/templates/common/skills/brainstorm.md +28 -27
  17. package/dist/templates/rudder/scripts/common/task_readiness.py +12 -5
  18. package/dist/templates/rudder/scripts/common/task_store.py +15 -36
  19. package/dist/templates/rudder/scripts/common/workflow_phase.py +45 -0
  20. package/dist/templates/rudder/scripts/task.py +18 -5
  21. package/dist/templates/rudder/workflow.md +41 -16
  22. package/package.json +26 -27
@@ -1,59 +1,59 @@
1
- # Repository Analysis
2
-
3
- The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.
4
-
5
- ## Analysis Order
6
-
7
- 1. Read the existing `.rudder/spec/` tree and note which files are templates, outdated, or already project-specific.
8
- 2. Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
9
- 3. Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
10
- 4. Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
11
- 5. Read representative source and test files directly before turning any finding into a spec rule.
12
-
13
- ## What To Capture
14
-
15
- | Area | Questions |
16
- |------|-----------|
17
- | Package boundaries | What does each package own? What imports cross boundaries? |
18
- | Runtime layers | Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling? |
19
- | Core abstractions | Which types, services, stores, commands, routes, or adapters define the system shape? |
20
- | Data flow | Where does user input enter, how is it validated, and where does state persist? |
21
- | Error handling | How are failures represented, logged, surfaced, and tested? |
22
- | Configuration | Where do defaults, environment config, generated files, and templates live? |
23
- | Tests | Which test styles are trusted examples for new work? |
24
-
25
- ## GitNexus Usage
26
-
27
- Start broad, then inspect specific symbols:
28
-
29
- ```text
30
- gitnexus_query({query: "CLI command execution flow"})
31
- gitnexus_query({query: "template generation and migration"})
32
- gitnexus_context({name: "SymbolName"})
33
- gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})
34
- ```
35
-
36
- Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.
37
-
38
- ## ABCoder Usage
39
-
40
- Use ABCoder when the spec needs exact code shapes:
41
-
42
- ```text
43
- list_repos()
44
- get_repo_structure({repo_name: "package-name"})
45
- get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
46
- get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})
47
- ```
48
-
49
- ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.
50
-
51
- ## Analysis Notes
52
-
53
- Keep short notes while analyzing. The notes should include:
54
-
55
- - Package or layer name.
56
- - Files that define the local pattern.
57
- - Rules the spec should teach.
58
- - Anti-patterns found in old code, comments, tests, or migration paths.
59
- - Spec files that should be created, deleted, renamed, or merged.
1
+ # Repository Analysis
2
+
3
+ The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.
4
+
5
+ ## Analysis Order
6
+
7
+ 1. Read the existing `.rudder/spec/` tree and note which files are templates, outdated, or already project-specific.
8
+ 2. Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
9
+ 3. Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
10
+ 4. Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
11
+ 5. Read representative source and test files directly before turning any finding into a spec rule.
12
+
13
+ ## What To Capture
14
+
15
+ | Area | Questions |
16
+ |------|-----------|
17
+ | Package boundaries | What does each package own? What imports cross boundaries? |
18
+ | Runtime layers | Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling? |
19
+ | Core abstractions | Which types, services, stores, commands, routes, or adapters define the system shape? |
20
+ | Data flow | Where does user input enter, how is it validated, and where does state persist? |
21
+ | Error handling | How are failures represented, logged, surfaced, and tested? |
22
+ | Configuration | Where do defaults, environment config, generated files, and templates live? |
23
+ | Tests | Which test styles are trusted examples for new work? |
24
+
25
+ ## GitNexus Usage
26
+
27
+ Start broad, then inspect specific symbols:
28
+
29
+ ```text
30
+ gitnexus_query({query: "CLI command execution flow"})
31
+ gitnexus_query({query: "template generation and migration"})
32
+ gitnexus_context({name: "SymbolName"})
33
+ gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})
34
+ ```
35
+
36
+ Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.
37
+
38
+ ## ABCoder Usage
39
+
40
+ Use ABCoder when the spec needs exact code shapes:
41
+
42
+ ```text
43
+ list_repos()
44
+ get_repo_structure({repo_name: "package-name"})
45
+ get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
46
+ get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})
47
+ ```
48
+
49
+ ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.
50
+
51
+ ## Analysis Notes
52
+
53
+ Keep short notes while analyzing. The notes should include:
54
+
55
+ - Package or layer name.
56
+ - Files that define the local pattern.
57
+ - Rules the spec should teach.
58
+ - Anti-patterns found in old code, comments, tests, or migration paths.
59
+ - Spec files that should be created, deleted, renamed, or merged.
@@ -1,61 +1,61 @@
1
- # Spec Task Planning
2
-
3
- Use a single agent as the default execution model. The agent may create Rudder tasks for traceability, but the skill should not require a specific platform, CLI, or parallel worker model.
4
-
5
- ## Decomposition
6
-
7
- Create spec work units around real ownership boundaries:
8
-
9
- - One package when a package has its own conventions.
10
- - One layer when the same package has distinct frontend, backend, CLI, worker, or shared-library rules.
11
- - One cross-cutting guide when a pattern spans packages and is not owned by one layer.
12
-
13
- Avoid artificial decomposition. A small library usually needs one focused spec pass, not several tasks.
14
-
15
- ## Task Shape
16
-
17
- When a Rudder task is useful, write a concise PRD with these sections:
18
-
19
- ```markdown
20
- # Fill <package-or-layer> Rudder Specs
21
-
22
- ## Goal
23
- Write project-specific `.rudder/spec/` guidance for <scope>.
24
-
25
- ## Scope
26
- - Spec directory:
27
- - Source directories to inspect:
28
- - Tests to inspect:
29
- - Out of scope:
30
-
31
- ## Architecture Context
32
- Summarize the concrete findings from repository analysis.
33
-
34
- ## Files To Create Or Update
35
- - `.rudder/spec/.../index.md`
36
- - `.rudder/spec/.../<topic>.md`
37
-
38
- ## Rules
39
- - Adapt the spec file set to the real codebase.
40
- - Use real source examples with file paths.
41
- - Remove template-only sections that do not apply.
42
- - Do not modify product source code unless the task explicitly asks for it.
43
-
44
- ## Acceptance Criteria
45
- - [ ] Specs contain concrete examples and anti-patterns from the repository.
46
- - [ ] No placeholder text remains.
47
- - [ ] Index files match the final spec files.
48
- - [ ] Claims are backed by source files, tests, or project docs.
49
- ```
50
-
51
- ## Optional Helper Agents
52
-
53
- If the host supports subagents, helpers can inspect independent packages or run verification. They are optional. The main agent still owns integration and final quality.
54
-
55
- Helper tasks must have clear ownership:
56
-
57
- - Read-only research tasks may inspect any source needed for the assigned scope.
58
- - Write tasks should own disjoint spec directories.
59
- - Verification tasks should check placeholder removal, broken links, and consistency.
60
-
61
- Do not encode helper-agent names, vendor-specific commands, or platform-specific routing in the skill. Put only the required work and acceptance criteria in the task.
1
+ # Spec Task Planning
2
+
3
+ Use a single agent as the default execution model. The agent may create Rudder tasks for traceability, but the skill should not require a specific platform, CLI, or parallel worker model.
4
+
5
+ ## Decomposition
6
+
7
+ Create spec work units around real ownership boundaries:
8
+
9
+ - One package when a package has its own conventions.
10
+ - One layer when the same package has distinct frontend, backend, CLI, worker, or shared-library rules.
11
+ - One cross-cutting guide when a pattern spans packages and is not owned by one layer.
12
+
13
+ Avoid artificial decomposition. A small library usually needs one focused spec pass, not several tasks.
14
+
15
+ ## Task Shape
16
+
17
+ When a Rudder task is useful, write a concise PRD with these sections:
18
+
19
+ ```markdown
20
+ # Fill <package-or-layer> Rudder Specs
21
+
22
+ ## Goal
23
+ Write project-specific `.rudder/spec/` guidance for <scope>.
24
+
25
+ ## Scope
26
+ - Spec directory:
27
+ - Source directories to inspect:
28
+ - Tests to inspect:
29
+ - Out of scope:
30
+
31
+ ## Architecture Context
32
+ Summarize the concrete findings from repository analysis.
33
+
34
+ ## Files To Create Or Update
35
+ - `.rudder/spec/.../index.md`
36
+ - `.rudder/spec/.../<topic>.md`
37
+
38
+ ## Rules
39
+ - Adapt the spec file set to the real codebase.
40
+ - Use real source examples with file paths.
41
+ - Remove template-only sections that do not apply.
42
+ - Do not modify product source code unless the task explicitly asks for it.
43
+
44
+ ## Acceptance Criteria
45
+ - [ ] Specs contain concrete examples and anti-patterns from the repository.
46
+ - [ ] No placeholder text remains.
47
+ - [ ] Index files match the final spec files.
48
+ - [ ] Claims are backed by source files, tests, or project docs.
49
+ ```
50
+
51
+ ## Optional Helper Agents
52
+
53
+ If the host supports subagents, helpers can inspect independent packages or run verification. They are optional. The main agent still owns integration and final quality.
54
+
55
+ Helper tasks must have clear ownership:
56
+
57
+ - Read-only research tasks may inspect any source needed for the assigned scope.
58
+ - Write tasks should own disjoint spec directories.
59
+ - Verification tasks should check placeholder removal, broken links, and consistency.
60
+
61
+ Do not encode helper-agent names, vendor-specific commands, or platform-specific routing in the skill. Put only the required work and acceptance criteria in the task.
@@ -1,70 +1,70 @@
1
- # Spec Writing
2
-
3
- Rudder specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.
4
-
5
- ## Write From Evidence
6
-
7
- Each important rule should be backed by one of these:
8
-
9
- - A source file that demonstrates the preferred pattern.
10
- - A test file that shows expected behavior.
11
- - A project document that defines the convention.
12
- - A repeated pattern across multiple files.
13
-
14
- Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.
15
-
16
- ## File Structure
17
-
18
- Keep the spec tree aligned with the project:
19
-
20
- - Keep `index.md` as the navigation file for the spec directory.
21
- - Split topics when developers would look for them independently.
22
- - Merge topics when separate files would repeat the same rule.
23
- - Delete template files that do not apply.
24
- - Add new files for important local patterns the template missed.
25
-
26
- ## Content Standards
27
-
28
- Good spec sections include:
29
-
30
- - When the rule applies.
31
- - The local pattern to follow.
32
- - The source or test files that prove the pattern.
33
- - Common mistakes or anti-patterns.
34
- - Verification commands or checks when they are specific and reliable.
35
-
36
- Avoid:
37
-
38
- - Placeholder prose.
39
- - Generic framework advice.
40
- - Tool instructions that only work in one agent host.
41
- - Long copied code blocks.
42
- - Rules based on a single accidental implementation detail.
43
-
44
- ## Example Shape
45
-
46
- ```markdown
47
- ## Command Handlers
48
-
49
- Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:
50
-
51
- - Parse CLI flags at the command boundary.
52
- - Convert raw inputs into typed task options before invoking core logic.
53
- - Keep filesystem writes in the command or service layer, not in template helpers.
54
-
55
- Reference files:
56
- - `packages/cli/src/commands/example.ts`
57
- - `packages/cli/test/commands/example.test.ts`
58
-
59
- Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.
60
- ```
61
-
62
- ## Final Pass
63
-
64
- Before finishing:
65
-
66
- ```bash
67
- grep -R "To be filled\\|TODO: fill\\|placeholder" .rudder/spec
68
- ```
69
-
70
- Also check links, index files, and whether any spec still describes a template rather than this repository.
1
+ # Spec Writing
2
+
3
+ Rudder specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.
4
+
5
+ ## Write From Evidence
6
+
7
+ Each important rule should be backed by one of these:
8
+
9
+ - A source file that demonstrates the preferred pattern.
10
+ - A test file that shows expected behavior.
11
+ - A project document that defines the convention.
12
+ - A repeated pattern across multiple files.
13
+
14
+ Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.
15
+
16
+ ## File Structure
17
+
18
+ Keep the spec tree aligned with the project:
19
+
20
+ - Keep `index.md` as the navigation file for the spec directory.
21
+ - Split topics when developers would look for them independently.
22
+ - Merge topics when separate files would repeat the same rule.
23
+ - Delete template files that do not apply.
24
+ - Add new files for important local patterns the template missed.
25
+
26
+ ## Content Standards
27
+
28
+ Good spec sections include:
29
+
30
+ - When the rule applies.
31
+ - The local pattern to follow.
32
+ - The source or test files that prove the pattern.
33
+ - Common mistakes or anti-patterns.
34
+ - Verification commands or checks when they are specific and reliable.
35
+
36
+ Avoid:
37
+
38
+ - Placeholder prose.
39
+ - Generic framework advice.
40
+ - Tool instructions that only work in one agent host.
41
+ - Long copied code blocks.
42
+ - Rules based on a single accidental implementation detail.
43
+
44
+ ## Example Shape
45
+
46
+ ```markdown
47
+ ## Command Handlers
48
+
49
+ Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:
50
+
51
+ - Parse CLI flags at the command boundary.
52
+ - Convert raw inputs into typed task options before invoking core logic.
53
+ - Keep filesystem writes in the command or service layer, not in template helpers.
54
+
55
+ Reference files:
56
+ - `packages/cli/src/commands/example.ts`
57
+ - `packages/cli/test/commands/example.test.ts`
58
+
59
+ Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.
60
+ ```
61
+
62
+ ## Final Pass
63
+
64
+ Before finishing:
65
+
66
+ ```bash
67
+ grep -R "To be filled\\|TODO: fill\\|placeholder" .rudder/spec
68
+ ```
69
+
70
+ Also check links, index files, and whether any spec still describes a template rather than this repository.
@@ -22,11 +22,15 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
22
22
 
23
23
  ## Step 3: Decide Where You Are
24
24
 
25
- `get_context.py` shows the active task's `status` field. Route by `status` + artifact presence:
25
+ First apply **Request routing** in `.rudder/workflow.md`: direct questions, code inspection, scheduler administration, and commit-wording requests do not advance a task. Verify that any development request serves the task's business objective and acceptance scope. Supplements, fixes, continuation, and moving from design to implementation reuse related unfinished work; an unrelated objective follows direct-low-risk/new-task routing instead. Same session/module alone does not establish relevance.
26
26
 
27
- - `status=planning` + no `prd.md` → **1.1** (load `rudder-brainstorm`)
28
- - `status=planning` + `prd.md` exists + `implement.jsonl` not curated (only the seed `_example` row) → **1.3**
29
- - `status=planning` + `prd.md` + curated `implement.jsonl` → **1.4** (run `task.py start` to enter Phase 2)
27
+ For a related task, route by `status`, PRD completeness, approval, and the invoking platform's execution mode (`codex.dispatch_mode` for Codex; inline by default):
28
+
29
+ - `status=planning` + missing/incomplete PRD or unresolved business decisions → **1.1** (load `rudder-brainstorm`). File existence alone is insufficient.
30
+ - `status=planning` + complete PRD + no user approval → **1.1**, ask only for the unresolved approval/decision. An explicit instruction to implement the agreed plan is already approval; do not ask again.
31
+ - `status=planning` + approved PRD + missing/stale recorded confirmation → record it using `task.py confirm <task-dir>`; do not request the same approval again unless requirements materially changed.
32
+ - `status=planning` + confirmed PRD + sub-agent execution + either JSONL missing, invalid, or seed-only → **1.3**, curate both `implement.jsonl` and `check.jsonl`.
33
+ - `status=planning` + confirmed PRD + (inline execution, or sub-agent execution with both JSONL files valid/curated) → **1.4**, run `task.py start <task-dir> --platform {{CLI_FLAG}}`. Inline ignores old JSONL seeds. A failed readiness gate leaves status planning; resolve the reported blockers instead of entering Phase 2.
30
34
  - `status=in_progress` + implementation not started → **2.1**
31
35
  - `status=in_progress` + implementation done, not yet checked → **2.2**
32
36
  - `status=in_progress` + check passed → **3.1**
@@ -35,7 +39,7 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
35
39
  Phase rules (full detail in `.rudder/workflow.md`):
36
40
 
37
41
  1. Run steps **in order** within a phase — `[required]` steps must not be skipped
38
- 2. `[once]` steps are already done if the output exists (e.g., `prd.md` for 1.1; `implement.jsonl` with curated entries for 1.3) — skip them
42
+ 2. Skip `[once]` steps only when their completion conditions hold: a complete/approved PRD, current confirmation, and both valid curated JSONL files when applicable. Artifact presence alone is insufficient.
39
43
  3. You may go back to an earlier phase if discoveries require it
40
44
 
41
45
  ## Step 4: Load the Specific Step
@@ -34,14 +34,14 @@ cat .rudder/spec/<package>/<layer>/index.md # for each relevant layer
34
34
  Index files list the specific guideline docs to read when you actually start coding.
35
35
 
36
36
  ## Step 4: Decide next action
37
- From Step 1 you know the current task. Check the task directory:
38
-
39
- - **Active task + `prd.md` exists** → Phase 2 step 2.1. Load the step detail:
40
- ```bash
41
- {{PYTHON_CMD}} ./.rudder/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
42
- ```
43
- - **Active task + no `prd.md`** → Phase 1.1. Load the `rudder-brainstorm` skill.
44
- - **No active task** → when the user describes multi-step work, load the `rudder-brainstorm` skill to clarify requirements, then create a task via `task.py create`. For simple one-off questions or trivial edits, skip this and just answer directly — no task needed.
37
+ Apply **Request routing** in `.rudder/workflow.md` before resuming any phase:
38
+
39
+ 1. Questions, code inspection, scheduler administration, and commit-message drafting are direct requests. Do not create or advance a task; only provide the requested output/action. Business features involving scheduled jobs follow normal routing.
40
+ 2. Check whether the request serves an unfinished task's **business objective and acceptance scope**. Read its PRD and status before reuse; same session/module or an active pointer alone does not establish relevance. Supplements, corrections, pre-acceptance fixes, continuation, and design-to-development reuse that task and update relevant artifacts. Check other unfinished tasks when needed; ask one focused question only if ownership is unclear.
41
+ 3. A clear, local, low-risk independent edit can be made directly with relevant guidelines and checks; no special bypass phrase or file-count threshold is required.
42
+ 4. Otherwise create a task for the independent objective needing durable tracking; an unrelated active task must not absorb it. Use `task.py create "<title>" --slug <name> --platform {{CLI_FLAG}}`, then load `rudder-brainstorm`.
43
+
44
+ For a related task, follow {{CMD_REF:continue}}'s status/approval/mode-aware routing. A planning task with a PRD is **not automatically ready for implementation**. Resolve missing requirements and open questions first; user approval of the agreed plan counts as confirmation without another prompt. Curate both JSONL files only for sub-agent execution, record approval via `task.py confirm`, then run `task.py start <task-dir> --platform {{CLI_FLAG}}`. Codex inline does not require JSONL, including old seed files.
45
45
 
46
46
  ---
47
47
 
@@ -1,6 +1,6 @@
1
1
  # Brainstorm - Requirements Discovery (AI Coding Enhanced)
2
2
 
3
- **CoreRule**: Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
3
+ **CoreRule**: Resolve business decisions and acceptance boundaries before implementation. Ask only questions that remain unanswered, one at a time, with a recommended option. An explicit instruction to implement a clearly agreed plan is approval; record it and continue without repeating the same confirmation.
4
4
 
5
5
  Ask the questions one at a time.
6
6
 
@@ -30,8 +30,8 @@ Triggered from {{CMD_REF:start}} when the user describes a development task, esp
30
30
 
31
31
  ## Core Principles (Non-negotiable)
32
32
 
33
- 1. **Task-first (capture early)**
34
- Always ensure a task exists at the start so the user's ideas are recorded immediately.
33
+ 1. **Route first, then capture**
34
+ Apply Request routing in `.rudder/workflow.md` before entering this skill. Direct answers, scheduler administration, commit-message drafting, and independent low-risk edits do not need a task. For tracked work, reuse a related unfinished task or create one for a new objective.
35
35
 
36
36
  2. **Action before asking**
37
37
  If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
@@ -54,21 +54,25 @@ Triggered from {{CMD_REF:start}} when the user describes a development task, esp
54
54
 
55
55
  ---
56
56
 
57
- ## Step 0: Ensure Task Exists (ALWAYS)
57
+ ## Step 0: Establish Task Ownership
58
58
 
59
- Before any Q&A, ensure a task exists. If none exists, create one immediately.
59
+ Compare the request with the current and, when relevant, other unfinished tasks' business objectives and acceptance scopes. Reuse a related task for supplements, fixes, continuation, or design-to-development; update its PRD rather than creating a duplicate. Same session/module or an active pointer alone is not evidence of relevance. If ownership is genuinely unclear, ask one focused question.
60
+
61
+ For a new objective requiring durable tracking, create a task even when an unrelated task is active. Direct work was already routed out before this skill. Preserve any previous task's artifacts and status.
60
62
 
61
63
  * Use a **temporary working title** derived from the user's message.
62
64
  * It's OK if the title is imperfect — refine later in PRD.
63
65
 
64
66
  ```bash
65
- TASK_DIR=$(python3 ./.rudder/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
67
+ TASK_DIR=$(python3 ./.rudder/scripts/task.py create "brainstorm: <short goal>" --slug <auto> --platform <platform>)
66
68
  ```
67
69
 
68
70
  Use a slug without a date prefix. `task.py create` adds the `MM-DD-`
69
71
  directory prefix automatically.
70
72
 
71
- Create/seed `prd.md` immediately with what you know:
73
+ Replace `<platform>` with the actual invoking CLI flag (e.g. `codex`, `claude`, `gemini`), not the last platform that wrote this shared skill. Task creation and startup must use that same platform; Codex resolves its inline/sub-agent setting from `.rudder/config.yaml`.
74
+
75
+ For a new task, create/seed `prd.md` immediately with what you know. For a related task, update its existing sections and preserve prior decisions:
72
76
 
73
77
  ```markdown
74
78
  # brainstorm: <short goal>
@@ -140,16 +144,15 @@ Write findings into PRD:
140
144
 
141
145
  ---
142
146
 
143
- ## Step 2: Classify Complexity (still useful, not gating task creation)
147
+ ## Step 2: Choose Discovery Depth
144
148
 
145
149
  | Complexity | Criteria | Action |
146
150
  | ------------ | ------------------------------------------------------ | ------------------------------------------- |
147
- | **Trivial** | Single-line fix, typo, obvious change | Skip brainstorm, implement directly |
148
- | **Simple** | Clear goal, 1–2 files, scope well-defined | Ask 1 confirm question, then implement |
149
- | **Moderate** | Multiple files, some ambiguity | Light brainstorm (2–3 high-value questions) |
150
- | **Complex** | Vague goal, architectural choices, multiple approaches | Full brainstorm |
151
+ | **Clear** | Goal, scope, and acceptance are already agreed | Persist the plan; reuse approval and proceed |
152
+ | **Moderate** | Some unresolved business decisions | Ask only the remaining high-value questions |
153
+ | **Complex** | Vague goal, architectural choices, multiple approaches | Explore options and converge on acceptance |
151
154
 
152
- > Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
155
+ > Discovery depth does not determine task boundaries. File count alone is neither a risk measure nor a reason to ask for confirmation. If the user has already approved the scope, skip settled questions and expansion sweeps; revisit only new business decisions or material changes.
153
156
 
154
157
  ---
155
158
 
@@ -404,7 +407,7 @@ Record the outcome in PRD as an ADR-lite section:
404
407
 
405
408
  ## Step 8: Final Confirmation + Implementation Plan
406
409
 
407
- When open questions are resolved, confirm complete requirements with a structured summary:
410
+ When open questions are resolved, persist the complete requirements and implementation plan. If the user has already instructed you to implement that agreed plan, reuse that approval and continue. Otherwise present the structured summary once and ask only for the outstanding approval. Do not repeat confirmation between workflow phases or for implementation-detail adjustments.
408
411
 
409
412
  ### Final confirmation format
410
413
 
@@ -449,8 +452,8 @@ For complex tasks with multiple independent work items, create subtasks:
449
452
 
450
453
  ```bash
451
454
  # Create child tasks
452
- CHILD1=$(python3 ./.rudder/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
453
- CHILD2=$(python3 ./.rudder/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
455
+ CHILD1=$(python3 ./.rudder/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR" --platform <platform>)
456
+ CHILD2=$(python3 ./.rudder/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR" --platform <platform>)
454
457
 
455
458
  # Or link existing tasks
456
459
  python3 ./.rudder/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
@@ -512,25 +515,23 @@ Context / Decision / Consequences
512
515
 
513
516
  ## Integration with Start Workflow
514
517
 
515
- After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
518
+ After requirements are complete and approved (including approval already given for the agreed plan), continue within `.rudder/workflow.md` Phase 1:
516
519
 
517
520
  ```text
518
521
  Brainstorm
519
- Step 0: Create task directory + seed PRD
522
+ Step 0: Reuse related task or create a new tracked objective
520
523
  Step 1–7: Discover requirements, research, converge
521
- Step 8: Final confirmation → user approves
524
+ Step 8: Persist complete requirements → reuse approval or ask once
522
525
  ↓
523
- Task Workflow Phase 2 (Prepare for Implementation)
524
- Code-Spec Depth Check (if applicable)
525
- → Research codebase (based on confirmed PRD)
526
- → Configure code-spec context (jsonl files)
527
- → Activate task
526
+ Phase 1.3: Curate both JSONL files for sub-agent execution; skip for inline
527
+ → Phase 1.4: task.py confirm <task-dir>
528
+ → task.py start <task-dir> --platform <platform>
528
529
  ↓
529
- Task Workflow Phase 3 (Execute)
530
- Implement → Check → Complete
530
+ Phase 2 (Execute)
531
+ Implement → Check → Verify → Phase 3 (Finish)
531
532
  ```
532
533
 
533
- The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
534
+ Do not recreate the task or discard the PRD when moving from design to implementation. A PRD file alone does not mean planning is complete: requirements, approval/hash, and applicable context must pass the startup gate. Inline startup ignores existing JSONL seed files.
534
535
 
535
536
  ---
536
537
 
@@ -8,6 +8,7 @@ import json
8
8
  import re
9
9
  from pathlib import Path
10
10
 
11
+ from .workflow_phase import requires_task_context
11
12
 
12
13
  _SECTION_RE = re.compile(r"^##\s+(.+?)\s*$", re.IGNORECASE)
13
14
  _CHECKBOX_RE = re.compile(r"^\s*[-*+]\s+\[[ xX]\]\s+\S+")
@@ -116,6 +117,9 @@ def _jsonl_entries(path: Path, repo_root: Path) -> tuple[int, list[str]]:
116
117
  except json.JSONDecodeError:
117
118
  errors.append(f"{path.name}:{line_number} contains invalid JSON")
118
119
  continue
120
+ if not isinstance(data, dict):
121
+ errors.append(f"{path.name}:{line_number} must contain a JSON object")
122
+ continue
119
123
  file_path = data.get("file")
120
124
  if not file_path:
121
125
  continue
@@ -129,11 +133,13 @@ def _jsonl_entries(path: Path, repo_root: Path) -> tuple[int, list[str]]:
129
133
  return entries, errors
130
134
 
131
135
 
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
+ def validate_context_files(
137
+ task_dir: Path, repo_root: Path, platform: str | None = None,
138
+ ) -> list[str]:
139
+ """Require curated JSONL for sub-agent execution, including missing files."""
140
+ if not requires_task_context(repo_root, platform):
136
141
  return []
142
+ files = [task_dir / "implement.jsonl", task_dir / "check.jsonl"]
137
143
  errors: list[str] = []
138
144
  for path in files:
139
145
  entries, entry_errors = _jsonl_entries(path, repo_root)
@@ -147,10 +153,11 @@ def validate_task_readiness(
147
153
  task_dir: Path,
148
154
  repo_root: Path,
149
155
  task_data: dict,
156
+ platform: str | None = None,
150
157
  ) -> list[str]:
151
158
  """Return blocking reasons for a planning task entering implementation."""
152
159
  errors = validate_prd(task_dir / "prd.md")
153
- errors.extend(validate_context_files(task_dir, repo_root))
160
+ errors.extend(validate_context_files(task_dir, repo_root, platform))
154
161
 
155
162
  requirements = task_data.get("requirements")
156
163
  if not isinstance(requirements, dict) or requirements.get("status") != "confirmed":