@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.
- package/README.md +148 -148
- package/bin/rudder.js +0 -0
- package/dist/migrations/manifests/0.6.22.json +9 -0
- package/dist/templates/claude/agents/rudder-check.md +170 -170
- package/dist/templates/codex/agents/rudder-check.toml +95 -95
- package/dist/templates/codex/config.toml +30 -30
- package/dist/templates/common/bundled-skills/rudder-meta/references/customize-local/change-workflow.md +5 -4
- package/dist/templates/common/bundled-skills/rudder-meta/references/local-architecture/task-system.md +7 -2
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/SKILL.md +41 -41
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/mcp-setup.md +90 -90
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/repository-analysis.md +59 -59
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-task-planning.md +61 -61
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-writing.md +70 -70
- package/dist/templates/common/commands/continue.md +9 -5
- package/dist/templates/common/commands/start.md +8 -8
- package/dist/templates/common/skills/brainstorm.md +28 -27
- package/dist/templates/rudder/scripts/common/task_readiness.py +12 -5
- package/dist/templates/rudder/scripts/common/task_store.py +15 -36
- package/dist/templates/rudder/scripts/common/workflow_phase.py +45 -0
- package/dist/templates/rudder/scripts/task.py +18 -5
- package/dist/templates/rudder/workflow.md +41 -16
- package/package.json +26 -27
package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/repository-analysis.md
CHANGED
|
@@ -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.
|
package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-task-planning.md
CHANGED
|
@@ -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.
|
package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-writing.md
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
- `status=planning` +
|
|
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
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
-
|
|
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**:
|
|
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. **
|
|
34
|
-
|
|
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:
|
|
57
|
+
## Step 0: Establish Task Ownership
|
|
58
58
|
|
|
59
|
-
|
|
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
|
-
|
|
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:
|
|
147
|
+
## Step 2: Choose Discovery Depth
|
|
144
148
|
|
|
145
149
|
| Complexity | Criteria | Action |
|
|
146
150
|
| ------------ | ------------------------------------------------------ | ------------------------------------------- |
|
|
147
|
-
| **
|
|
148
|
-
| **
|
|
149
|
-
| **
|
|
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
|
-
>
|
|
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,
|
|
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
|
|
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:
|
|
522
|
+
Step 0: Reuse related task or create a new tracked objective
|
|
520
523
|
Step 1–7: Discover requirements, research, converge
|
|
521
|
-
Step 8:
|
|
524
|
+
Step 8: Persist complete requirements → reuse approval or ask once
|
|
522
525
|
↓
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
→
|
|
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
|
-
|
|
530
|
-
Implement → Check →
|
|
530
|
+
Phase 2 (Execute)
|
|
531
|
+
Implement → Check → Verify → Phase 3 (Finish)
|
|
531
532
|
```
|
|
532
533
|
|
|
533
|
-
|
|
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(
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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":
|