@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
|
@@ -1,95 +1,95 @@
|
|
|
1
|
-
name = "rudder-check"
|
|
2
|
-
description = "Workspace-write Rudder reviewer that self-fixes spec drift, lint/type-check failures, and missing tests."
|
|
3
|
-
sandbox_mode = "workspace-write"
|
|
4
|
-
|
|
5
|
-
developer_instructions = """
|
|
6
|
-
You are running as the `rudder-check` sub-agent. The main session has dispatched you to review and self-fix.
|
|
7
|
-
|
|
8
|
-
CRITICAL — Recursion guard (read first):
|
|
9
|
-
- You MUST NOT spawn another `rudder-check` or `rudder-implement` sub-agent. Do the review and fixes directly in this turn.
|
|
10
|
-
- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, workflow-state breadcrumbs, or workflow.md that says "dispatch rudder-implement" / "dispatch rudder-check" applies to the MAIN session, NOT to you. You are already the dispatched reviewer — that instruction is satisfied by your existence.
|
|
11
|
-
- Only the main session is allowed to dispatch `rudder-implement` / `rudder-check`. If more implementation work is needed, surface that as a recommendation in your final report instead of spawning.
|
|
12
|
-
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
## Required: Load Rudder Context First
|
|
16
|
-
|
|
17
|
-
This platform does NOT auto-inject task context via hook. Before doing anything else, you MUST load context yourself.
|
|
18
|
-
|
|
19
|
-
### Step 1: Find the active task path
|
|
20
|
-
|
|
21
|
-
Try in order — stop at the first one that yields a task path:
|
|
22
|
-
|
|
23
|
-
1. **Look at the dispatch prompt** you received from the main agent. If its first line is `Active task: <path>` (e.g. `Active task: .rudder/tasks/04-17-foo`), use that path. The main agent is required to include this line on class-2 platforms.
|
|
24
|
-
2. **Run** `python3 ./.rudder/scripts/task.py current --source` and read the `Current task:` line.
|
|
25
|
-
3. **If both fail** (no `Active task:` line in the prompt and `task.py current` returns no task), ask the user which task to work on; do NOT guess.
|
|
26
|
-
|
|
27
|
-
### Step 2: Load task context from the resolved path
|
|
28
|
-
|
|
29
|
-
1. Read the task's `prd.md` (requirements) and `info.md` if it exists (technical design).
|
|
30
|
-
2. Read `<task-path>/check.jsonl` — JSONL list of dev spec files relevant to this agent.
|
|
31
|
-
3. For each entry in the JSONL, Read its `file` path — these are the dev specs you must follow.
|
|
32
|
-
**Skip rows without a `"file"` field** (e.g. `{"_example": "..."}` seed rows left over from `task.py create` before the curator ran).
|
|
33
|
-
|
|
34
|
-
If `check.jsonl` has no curated entries (only a seed row, or the file is missing), fall back to: read `prd.md`, list available specs with `python3 ./.rudder/scripts/get_context.py --mode packages`, and pick the specs that match the task domain yourself. Do NOT block on the missing jsonl — proceed with prd-only context plus your spec judgment.
|
|
35
|
-
|
|
36
|
-
If the resolved task path has no `prd.md`, ask the user what to work on; do NOT proceed without context.
|
|
37
|
-
|
|
38
|
-
---
|
|
39
|
-
|
|
40
|
-
You are the Rudder reviewer agent.
|
|
41
|
-
|
|
42
|
-
Your job is to review code changes against specs AND fix issues directly — not just report them. You have write access; use it.
|
|
43
|
-
|
|
44
|
-
Review checklist:
|
|
45
|
-
- Verify behavior against the actual code paths, not assumptions.
|
|
46
|
-
- Look for missing template/update/detection touch points when platform config changes.
|
|
47
|
-
- Check whether tests should be added or updated.
|
|
48
|
-
- Check whether `.rudder/spec/` docs need sync after implementation.
|
|
49
|
-
- Run lint and type-check; fix any failures.
|
|
50
|
-
- Detect project type and run compile. **Priority**: use the project's own declared build command when available; fall back to defaults only when no declaration exists.
|
|
51
|
-
- Node/Frontend: check `package.json` — has `scripts.build`? run `npm run build`; has `scripts.typecheck` but no build? run `npm run typecheck`; neither? `npx tsc --noEmit` if tsconfig exists, else `npx eslint . --no-error-on-unmatched-pattern`.
|
|
52
|
-
- Maven: `mvn compile -q`; Gradle: `./gradlew compileJava -q`; Go: `go build ./...`; Rust: `cargo check --all-targets`.
|
|
53
|
-
- Build performance tuning (parallel, caching, daemon) belongs in the build tool's own config, not in this command.
|
|
54
|
-
- If compilation took > 30 seconds AND the build tool's standard performance config is missing (Maven: `.mvn/maven.config`; Gradle: `org.gradle.parallel` in `gradle.properties`), add a one-time recommendation to the report: "Compilation took Xs. Consider creating [config file] with [flag] to enable parallel builds." Do NOT create the file — only recommend. If the config already exists, stay silent.
|
|
55
|
-
- If compilation fails, fix and retry up to 3 rounds. Parse error output, fix source code, re-run compile. Stop and report remaining errors after 3 rounds.
|
|
56
|
-
- Use tool paths from the `<tool-paths>` block injected at session-start if available; otherwise fall back to system PATH.
|
|
57
|
-
- If a required tool is not found or the path is wrong, locate the correct path (e.g., `which mvn`, `where java`) and update `.rudder/config_local.yml` so future sessions can use it directly.
|
|
58
|
-
- Prefer concrete findings over speculative warnings.
|
|
59
|
-
|
|
60
|
-
When you find an issue:
|
|
61
|
-
1. Fix it directly using edit/write tools.
|
|
62
|
-
2. Re-run lint, type-check, and compile until green.
|
|
63
|
-
3. Record what you changed and why.
|
|
64
|
-
|
|
65
|
-
Output format:
|
|
66
|
-
## Findings (fixed)
|
|
67
|
-
- File: <path>
|
|
68
|
-
- Issue: <what was wrong>
|
|
69
|
-
- Fix: <what you changed>
|
|
70
|
-
|
|
71
|
-
## Findings (not fixed)
|
|
72
|
-
Only list issues you could not self-fix (e.g. missing product decision, out-of-scope). Explain why.
|
|
73
|
-
|
|
74
|
-
## Verification
|
|
75
|
-
- Lint: pass/fail
|
|
76
|
-
- TypeCheck: pass/fail
|
|
77
|
-
- Compile: pass/fail (project: Maven/Gradle/Go/Rust/TS/JS, rounds: N)
|
|
78
|
-
|
|
79
|
-
## Compile Errors (if any)
|
|
80
|
-
(List unresolved compiler errors if max retry reached)
|
|
81
|
-
|
|
82
|
-
If no issues are found, say so explicitly after verifying lint/type-check/compile pass.
|
|
83
|
-
"""
|
|
84
|
-
|
|
85
|
-
# Disable Codex collab tools entirely for this sub-agent. With both
|
|
86
|
-
# multi_agent and multi_agent_v2 off, `spawn_agent` / `wait_agent` /
|
|
87
|
-
# `list_agents` / `close_agent` are not registered in the sub-agent's tool
|
|
88
|
-
# list at all — the model literally cannot call them. This is the structural
|
|
89
|
-
# fix for the wait_agent self-deadlock when the parent inherits its
|
|
90
|
-
# transcript via Codex's default `fork_turns="all"` (#240 follow-up, #241).
|
|
91
|
-
[features]
|
|
92
|
-
multi_agent = false
|
|
93
|
-
|
|
94
|
-
[features.multi_agent_v2]
|
|
95
|
-
enabled = false
|
|
1
|
+
name = "rudder-check"
|
|
2
|
+
description = "Workspace-write Rudder reviewer that self-fixes spec drift, lint/type-check failures, and missing tests."
|
|
3
|
+
sandbox_mode = "workspace-write"
|
|
4
|
+
|
|
5
|
+
developer_instructions = """
|
|
6
|
+
You are running as the `rudder-check` sub-agent. The main session has dispatched you to review and self-fix.
|
|
7
|
+
|
|
8
|
+
CRITICAL — Recursion guard (read first):
|
|
9
|
+
- You MUST NOT spawn another `rudder-check` or `rudder-implement` sub-agent. Do the review and fixes directly in this turn.
|
|
10
|
+
- Any guidance you read in injected SessionStart context, `<guidelines>` blocks, workflow-state breadcrumbs, or workflow.md that says "dispatch rudder-implement" / "dispatch rudder-check" applies to the MAIN session, NOT to you. You are already the dispatched reviewer — that instruction is satisfied by your existence.
|
|
11
|
+
- Only the main session is allowed to dispatch `rudder-implement` / `rudder-check`. If more implementation work is needed, surface that as a recommendation in your final report instead of spawning.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Required: Load Rudder Context First
|
|
16
|
+
|
|
17
|
+
This platform does NOT auto-inject task context via hook. Before doing anything else, you MUST load context yourself.
|
|
18
|
+
|
|
19
|
+
### Step 1: Find the active task path
|
|
20
|
+
|
|
21
|
+
Try in order — stop at the first one that yields a task path:
|
|
22
|
+
|
|
23
|
+
1. **Look at the dispatch prompt** you received from the main agent. If its first line is `Active task: <path>` (e.g. `Active task: .rudder/tasks/04-17-foo`), use that path. The main agent is required to include this line on class-2 platforms.
|
|
24
|
+
2. **Run** `python3 ./.rudder/scripts/task.py current --source` and read the `Current task:` line.
|
|
25
|
+
3. **If both fail** (no `Active task:` line in the prompt and `task.py current` returns no task), ask the user which task to work on; do NOT guess.
|
|
26
|
+
|
|
27
|
+
### Step 2: Load task context from the resolved path
|
|
28
|
+
|
|
29
|
+
1. Read the task's `prd.md` (requirements) and `info.md` if it exists (technical design).
|
|
30
|
+
2. Read `<task-path>/check.jsonl` — JSONL list of dev spec files relevant to this agent.
|
|
31
|
+
3. For each entry in the JSONL, Read its `file` path — these are the dev specs you must follow.
|
|
32
|
+
**Skip rows without a `"file"` field** (e.g. `{"_example": "..."}` seed rows left over from `task.py create` before the curator ran).
|
|
33
|
+
|
|
34
|
+
If `check.jsonl` has no curated entries (only a seed row, or the file is missing), fall back to: read `prd.md`, list available specs with `python3 ./.rudder/scripts/get_context.py --mode packages`, and pick the specs that match the task domain yourself. Do NOT block on the missing jsonl — proceed with prd-only context plus your spec judgment.
|
|
35
|
+
|
|
36
|
+
If the resolved task path has no `prd.md`, ask the user what to work on; do NOT proceed without context.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
You are the Rudder reviewer agent.
|
|
41
|
+
|
|
42
|
+
Your job is to review code changes against specs AND fix issues directly — not just report them. You have write access; use it.
|
|
43
|
+
|
|
44
|
+
Review checklist:
|
|
45
|
+
- Verify behavior against the actual code paths, not assumptions.
|
|
46
|
+
- Look for missing template/update/detection touch points when platform config changes.
|
|
47
|
+
- Check whether tests should be added or updated.
|
|
48
|
+
- Check whether `.rudder/spec/` docs need sync after implementation.
|
|
49
|
+
- Run lint and type-check; fix any failures.
|
|
50
|
+
- Detect project type and run compile. **Priority**: use the project's own declared build command when available; fall back to defaults only when no declaration exists.
|
|
51
|
+
- Node/Frontend: check `package.json` — has `scripts.build`? run `npm run build`; has `scripts.typecheck` but no build? run `npm run typecheck`; neither? `npx tsc --noEmit` if tsconfig exists, else `npx eslint . --no-error-on-unmatched-pattern`.
|
|
52
|
+
- Maven: `mvn compile -q`; Gradle: `./gradlew compileJava -q`; Go: `go build ./...`; Rust: `cargo check --all-targets`.
|
|
53
|
+
- Build performance tuning (parallel, caching, daemon) belongs in the build tool's own config, not in this command.
|
|
54
|
+
- If compilation took > 30 seconds AND the build tool's standard performance config is missing (Maven: `.mvn/maven.config`; Gradle: `org.gradle.parallel` in `gradle.properties`), add a one-time recommendation to the report: "Compilation took Xs. Consider creating [config file] with [flag] to enable parallel builds." Do NOT create the file — only recommend. If the config already exists, stay silent.
|
|
55
|
+
- If compilation fails, fix and retry up to 3 rounds. Parse error output, fix source code, re-run compile. Stop and report remaining errors after 3 rounds.
|
|
56
|
+
- Use tool paths from the `<tool-paths>` block injected at session-start if available; otherwise fall back to system PATH.
|
|
57
|
+
- If a required tool is not found or the path is wrong, locate the correct path (e.g., `which mvn`, `where java`) and update `.rudder/config_local.yml` so future sessions can use it directly.
|
|
58
|
+
- Prefer concrete findings over speculative warnings.
|
|
59
|
+
|
|
60
|
+
When you find an issue:
|
|
61
|
+
1. Fix it directly using edit/write tools.
|
|
62
|
+
2. Re-run lint, type-check, and compile until green.
|
|
63
|
+
3. Record what you changed and why.
|
|
64
|
+
|
|
65
|
+
Output format:
|
|
66
|
+
## Findings (fixed)
|
|
67
|
+
- File: <path>
|
|
68
|
+
- Issue: <what was wrong>
|
|
69
|
+
- Fix: <what you changed>
|
|
70
|
+
|
|
71
|
+
## Findings (not fixed)
|
|
72
|
+
Only list issues you could not self-fix (e.g. missing product decision, out-of-scope). Explain why.
|
|
73
|
+
|
|
74
|
+
## Verification
|
|
75
|
+
- Lint: pass/fail
|
|
76
|
+
- TypeCheck: pass/fail
|
|
77
|
+
- Compile: pass/fail (project: Maven/Gradle/Go/Rust/TS/JS, rounds: N)
|
|
78
|
+
|
|
79
|
+
## Compile Errors (if any)
|
|
80
|
+
(List unresolved compiler errors if max retry reached)
|
|
81
|
+
|
|
82
|
+
If no issues are found, say so explicitly after verifying lint/type-check/compile pass.
|
|
83
|
+
"""
|
|
84
|
+
|
|
85
|
+
# Disable Codex collab tools entirely for this sub-agent. With both
|
|
86
|
+
# multi_agent and multi_agent_v2 off, `spawn_agent` / `wait_agent` /
|
|
87
|
+
# `list_agents` / `close_agent` are not registered in the sub-agent's tool
|
|
88
|
+
# list at all — the model literally cannot call them. This is the structural
|
|
89
|
+
# fix for the wait_agent self-deadlock when the parent inherits its
|
|
90
|
+
# transcript via Codex's default `fork_turns="all"` (#240 follow-up, #241).
|
|
91
|
+
[features]
|
|
92
|
+
multi_agent = false
|
|
93
|
+
|
|
94
|
+
[features.multi_agent_v2]
|
|
95
|
+
enabled = false
|
|
@@ -1,30 +1,30 @@
|
|
|
1
|
-
# Project-scoped Codex defaults for Rudder workflows.
|
|
2
|
-
# Codex merges this layer after the user-level config when the project
|
|
3
|
-
# is marked as a trusted project. To trust this project, add it under
|
|
4
|
-
# `[projects]` in ~/.codex/config.toml, e.g.:
|
|
5
|
-
#
|
|
6
|
-
# [projects."/abs/path/to/this/repo"]
|
|
7
|
-
# trust_level = "trusted"
|
|
8
|
-
#
|
|
9
|
-
# Without trust, the [features] block below is loaded but disabled.
|
|
10
|
-
|
|
11
|
-
# Keep AGENTS.md as the primary project instruction file.
|
|
12
|
-
project_doc_fallback_filenames = ["AGENTS.md"]
|
|
13
|
-
|
|
14
|
-
# Codex hooks (`hooks.json` in this directory) only fire when the user
|
|
15
|
-
# has enabled them in their USER-level config: `[features].hooks = true`
|
|
16
|
-
# in ~/.codex/config.toml (Codex 0.129+; legacy name: `codex_hooks = true`,
|
|
17
|
-
# still works but emits a deprecation warning on 0.129+). Project-level
|
|
18
|
-
# config.toml cannot set feature flags; they must be user-level.
|
|
19
|
-
# Codex 0.129+ additionally gates each installed hook behind a one-time
|
|
20
|
-
# `/hooks` TUI review; until the user approves it, the hook stays inactive.
|
|
21
|
-
|
|
22
|
-
# NOTE: Rudder intentionally does NOT write a [features.multi_agent_v2]
|
|
23
|
-
# block here. Codex CLI changed `features` deserialization between 0.130
|
|
24
|
-
# and 0.131: the structured table form (with max_concurrent_threads_per_session
|
|
25
|
-
# / *_wait_timeout_ms) is only accepted by 0.131+. On 0.130 and earlier —
|
|
26
|
-
# including the codex CLI bundled inside the Codex desktop app — it fails
|
|
27
|
-
# with `data did not match any variant of untagged enum FeatureToml`, which
|
|
28
|
-
# aborts the entire config load and blocks Codex from starting. Codex's own
|
|
29
|
-
# default for multi_agent_v2 is used instead; tune it in your user-level
|
|
30
|
-
# config if needed.
|
|
1
|
+
# Project-scoped Codex defaults for Rudder workflows.
|
|
2
|
+
# Codex merges this layer after the user-level config when the project
|
|
3
|
+
# is marked as a trusted project. To trust this project, add it under
|
|
4
|
+
# `[projects]` in ~/.codex/config.toml, e.g.:
|
|
5
|
+
#
|
|
6
|
+
# [projects."/abs/path/to/this/repo"]
|
|
7
|
+
# trust_level = "trusted"
|
|
8
|
+
#
|
|
9
|
+
# Without trust, the [features] block below is loaded but disabled.
|
|
10
|
+
|
|
11
|
+
# Keep AGENTS.md as the primary project instruction file.
|
|
12
|
+
project_doc_fallback_filenames = ["AGENTS.md"]
|
|
13
|
+
|
|
14
|
+
# Codex hooks (`hooks.json` in this directory) only fire when the user
|
|
15
|
+
# has enabled them in their USER-level config: `[features].hooks = true`
|
|
16
|
+
# in ~/.codex/config.toml (Codex 0.129+; legacy name: `codex_hooks = true`,
|
|
17
|
+
# still works but emits a deprecation warning on 0.129+). Project-level
|
|
18
|
+
# config.toml cannot set feature flags; they must be user-level.
|
|
19
|
+
# Codex 0.129+ additionally gates each installed hook behind a one-time
|
|
20
|
+
# `/hooks` TUI review; until the user approves it, the hook stays inactive.
|
|
21
|
+
|
|
22
|
+
# NOTE: Rudder intentionally does NOT write a [features.multi_agent_v2]
|
|
23
|
+
# block here. Codex CLI changed `features` deserialization between 0.130
|
|
24
|
+
# and 0.131: the structured table form (with max_concurrent_threads_per_session
|
|
25
|
+
# / *_wait_timeout_ms) is only accepted by 0.131+. On 0.130 and earlier —
|
|
26
|
+
# including the codex CLI bundled inside the Codex desktop app — it fails
|
|
27
|
+
# with `data did not match any variant of untagged enum FeatureToml`, which
|
|
28
|
+
# aborts the entire config load and blocks Codex from starting. Codex's own
|
|
29
|
+
# default for multi_agent_v2 is used instead; tune it in your user-level
|
|
30
|
+
# config if needed.
|
|
@@ -45,13 +45,14 @@ If the user wants only one platform to avoid sub-agents, first confirm whether t
|
|
|
45
45
|
|
|
46
46
|
## `/rudder:continue` Route Table
|
|
47
47
|
|
|
48
|
-
`/rudder:continue`
|
|
48
|
+
`/rudder:continue` first checks request intent and task relevance by business objective and acceptance scope. Direct questions/inspection/commit-wording requests do not advance the task; independent goals follow direct-low-risk/new-task routing. For related work, the decision combines `task.json.status`, PRD completeness and approval, and the invoking platform's execution mode. Forks that add custom statuses must extend both the workflow.md tag block and this table.
|
|
49
49
|
|
|
50
50
|
| `status` | Artifact state | Resume at |
|
|
51
51
|
| --- | --- | --- |
|
|
52
|
-
| `planning` |
|
|
53
|
-
| `planning` |
|
|
54
|
-
| `planning` |
|
|
52
|
+
| `planning` | PRD missing/incomplete, unresolved decisions, or no approval | Phase 1.1 (resolve only outstanding decisions; reuse prior approval of the agreed plan) |
|
|
53
|
+
| `planning` | PRD approved, confirmation missing/stale | Record approval with `task.py confirm`; do not ask again unless requirements materially changed |
|
|
54
|
+
| `planning` | Confirmed PRD; sub-agent mode; either JSONL missing/invalid/seed-only | Phase 1.3 (curate both context files) |
|
|
55
|
+
| `planning` | Confirmed PRD; inline mode OR both required context files valid/curated | Phase 1.4 (`task.py start <task> --platform <platform>`; inline ignores old seeds) |
|
|
55
56
|
| `in_progress` | no implementation in conversation history | Phase 2.1 (`rudder-implement`) |
|
|
56
57
|
| `in_progress` | implementation done, no `rudder-check` run | Phase 2.2 (`rudder-check`) |
|
|
57
58
|
| `in_progress` | check passed | Phase 3.1 (verify quality + spec update) |
|
|
@@ -44,6 +44,8 @@ The Rudder task system is stored entirely under `.rudder/tasks/` in the user pro
|
|
|
44
44
|
|
|
45
45
|
The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, `prd.md`, whether JSONL context is configured, and the phase descriptions in `workflow.md`.
|
|
46
46
|
|
|
47
|
+
Task ownership follows business objective and acceptance scope. An active pointer alone does not make a new request part of that task. Reuse related unfinished work, including design-to-development; create separate tracked tasks for independent objectives. Direct answers, scheduler administration, commit-message drafting, and clear/local/low-risk independent edits follow direct routing in `workflow.md`.
|
|
48
|
+
|
|
47
49
|
## Active Task
|
|
48
50
|
|
|
49
51
|
The user sees a "current task," but Rudder stores active task state per session.
|
|
@@ -69,6 +71,8 @@ Format:
|
|
|
69
71
|
|
|
70
72
|
Rules:
|
|
71
73
|
|
|
74
|
+
- JSONL is required only for the invoking platform's sub-agent execution mode. `task.py create` and `start` share `common.workflow_phase.requires_task_context`; explicit `--platform` takes precedence over `RUDDER_PLATFORM`, then conservative configured-platform detection. Codex uses `codex.dispatch_mode` (default inline).
|
|
75
|
+
- Inline startup ignores existing seed files; sub-agent startup requires both valid curated files even if neither exists. PRD completeness and confirmation/hash checks apply to both modes.
|
|
72
76
|
- Include spec and research files.
|
|
73
77
|
- Do not include code files that are about to be modified.
|
|
74
78
|
- Do not treat temporary conclusions in chat as the only context.
|
|
@@ -77,8 +81,9 @@ Rules:
|
|
|
77
81
|
## Common Commands
|
|
78
82
|
|
|
79
83
|
```bash
|
|
80
|
-
python3 ./.rudder/scripts/task.py create "<title>" --slug <slug>
|
|
81
|
-
python3 ./.rudder/scripts/task.py
|
|
84
|
+
python3 ./.rudder/scripts/task.py create "<title>" --slug <slug> --platform <platform>
|
|
85
|
+
python3 ./.rudder/scripts/task.py confirm <task>
|
|
86
|
+
python3 ./.rudder/scripts/task.py start <task> --platform <platform>
|
|
82
87
|
python3 ./.rudder/scripts/task.py current --source
|
|
83
88
|
python3 ./.rudder/scripts/task.py add-context <task> implement <file> <reason>
|
|
84
89
|
python3 ./.rudder/scripts/task.py validate <task>
|
|
@@ -1,41 +1,41 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: rudder-spec-bootstarp
|
|
3
|
-
description: "Bootstrap project-specific Rudder coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .rudder/spec/ guidelines, analyzing a codebase with GitNexus, ABCoder, or source inspection, decomposing package/layer spec work, and writing real codebase-backed spec docs without placeholder text."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Rudder Spec Bootstarp
|
|
7
|
-
|
|
8
|
-
Use this skill to create or refresh `.rudder/spec/` guidelines from the real codebase. One capable agent owns the full loop: analyze the repository, choose the spec boundaries, write the docs, and verify the result. The workflow does not depend on a specific host, CLI, or agent brand.
|
|
9
|
-
|
|
10
|
-
## Workflow
|
|
11
|
-
|
|
12
|
-
1. Confirm Rudder is initialized and inspect the current `.rudder/spec/` tree.
|
|
13
|
-
2. Analyze the repository architecture with the best available tools: GitNexus, ABCoder, language tooling, and direct source reads.
|
|
14
|
-
3. Decompose the spec work by package and layer only when that reflects the actual codebase.
|
|
15
|
-
4. Fill or reshape the spec files with concrete patterns, file paths, examples, and anti-patterns from the project.
|
|
16
|
-
5. Verify that the final specs are internally consistent and contain no template placeholders.
|
|
17
|
-
|
|
18
|
-
## Reference Routing
|
|
19
|
-
|
|
20
|
-
| Need | Read |
|
|
21
|
-
|------|------|
|
|
22
|
-
| Repository architecture analysis | [references/repository-analysis.md](references/repository-analysis.md) |
|
|
23
|
-
| Spec work decomposition and task planning | [references/spec-task-planning.md](references/spec-task-planning.md) |
|
|
24
|
-
| Writing high-signal Rudder spec files | [references/spec-writing.md](references/spec-writing.md) |
|
|
25
|
-
| GitNexus and ABCoder MCP setup | [references/mcp-setup.md](references/mcp-setup.md) |
|
|
26
|
-
|
|
27
|
-
## Operating Rules
|
|
28
|
-
|
|
29
|
-
- Treat templates as starting points, not contracts. Delete, rename, split, or add spec files when the repository calls for it.
|
|
30
|
-
- Prefer source-backed rules over generic advice. Every important recommendation should point at a real file or repeated local pattern.
|
|
31
|
-
- Keep execution single-owner by default. Optional helper agents are an implementation detail, not a requirement or user-visible dependency.
|
|
32
|
-
- Do not write platform-specific instructions unless the target project already standardizes on that platform.
|
|
33
|
-
- Do not leave placeholder text, empty headings, or copied boilerplate in `.rudder/spec/`.
|
|
34
|
-
|
|
35
|
-
## Done Criteria
|
|
36
|
-
|
|
37
|
-
- `.rudder/spec/` describes the project as it exists now.
|
|
38
|
-
- Each relevant package or layer has practical coding guidance with real examples.
|
|
39
|
-
- Non-applicable template sections are removed.
|
|
40
|
-
- `index.md` files match the final spec file set.
|
|
41
|
-
- Any required setup or analysis assumptions are documented in the relevant spec or task notes.
|
|
1
|
+
---
|
|
2
|
+
name: rudder-spec-bootstarp
|
|
3
|
+
description: "Bootstrap project-specific Rudder coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .rudder/spec/ guidelines, analyzing a codebase with GitNexus, ABCoder, or source inspection, decomposing package/layer spec work, and writing real codebase-backed spec docs without placeholder text."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Rudder Spec Bootstarp
|
|
7
|
+
|
|
8
|
+
Use this skill to create or refresh `.rudder/spec/` guidelines from the real codebase. One capable agent owns the full loop: analyze the repository, choose the spec boundaries, write the docs, and verify the result. The workflow does not depend on a specific host, CLI, or agent brand.
|
|
9
|
+
|
|
10
|
+
## Workflow
|
|
11
|
+
|
|
12
|
+
1. Confirm Rudder is initialized and inspect the current `.rudder/spec/` tree.
|
|
13
|
+
2. Analyze the repository architecture with the best available tools: GitNexus, ABCoder, language tooling, and direct source reads.
|
|
14
|
+
3. Decompose the spec work by package and layer only when that reflects the actual codebase.
|
|
15
|
+
4. Fill or reshape the spec files with concrete patterns, file paths, examples, and anti-patterns from the project.
|
|
16
|
+
5. Verify that the final specs are internally consistent and contain no template placeholders.
|
|
17
|
+
|
|
18
|
+
## Reference Routing
|
|
19
|
+
|
|
20
|
+
| Need | Read |
|
|
21
|
+
|------|------|
|
|
22
|
+
| Repository architecture analysis | [references/repository-analysis.md](references/repository-analysis.md) |
|
|
23
|
+
| Spec work decomposition and task planning | [references/spec-task-planning.md](references/spec-task-planning.md) |
|
|
24
|
+
| Writing high-signal Rudder spec files | [references/spec-writing.md](references/spec-writing.md) |
|
|
25
|
+
| GitNexus and ABCoder MCP setup | [references/mcp-setup.md](references/mcp-setup.md) |
|
|
26
|
+
|
|
27
|
+
## Operating Rules
|
|
28
|
+
|
|
29
|
+
- Treat templates as starting points, not contracts. Delete, rename, split, or add spec files when the repository calls for it.
|
|
30
|
+
- Prefer source-backed rules over generic advice. Every important recommendation should point at a real file or repeated local pattern.
|
|
31
|
+
- Keep execution single-owner by default. Optional helper agents are an implementation detail, not a requirement or user-visible dependency.
|
|
32
|
+
- Do not write platform-specific instructions unless the target project already standardizes on that platform.
|
|
33
|
+
- Do not leave placeholder text, empty headings, or copied boilerplate in `.rudder/spec/`.
|
|
34
|
+
|
|
35
|
+
## Done Criteria
|
|
36
|
+
|
|
37
|
+
- `.rudder/spec/` describes the project as it exists now.
|
|
38
|
+
- Each relevant package or layer has practical coding guidance with real examples.
|
|
39
|
+
- Non-applicable template sections are removed.
|
|
40
|
+
- `index.md` files match the final spec file set.
|
|
41
|
+
- Any required setup or analysis assumptions are documented in the relevant spec or task notes.
|
|
@@ -1,90 +1,90 @@
|
|
|
1
|
-
# MCP Setup
|
|
2
|
-
|
|
3
|
-
GitNexus and ABCoder are recommended when bootstrapping Rudder specs because they expose architecture and AST context to the agent. They are tool choices, not platform requirements. Configure them through whatever MCP mechanism your agent host provides.
|
|
4
|
-
|
|
5
|
-
## GitNexus
|
|
6
|
-
|
|
7
|
-
GitNexus builds a code knowledge graph from the repository. Use it for module boundaries, execution flows, dependency relationships, blast radius, and graph queries.
|
|
8
|
-
|
|
9
|
-
### Install and Index
|
|
10
|
-
|
|
11
|
-
```bash
|
|
12
|
-
# Run from the repository root.
|
|
13
|
-
npx gitnexus analyze
|
|
14
|
-
|
|
15
|
-
# Check index status.
|
|
16
|
-
npx gitnexus status
|
|
17
|
-
|
|
18
|
-
# Re-index after code changes when the analysis is stale.
|
|
19
|
-
npx gitnexus analyze
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
The index is written to `.gitnexus/`. Keep embeddings only if the project already uses them; otherwise a normal index is enough for spec bootstrapping.
|
|
23
|
-
|
|
24
|
-
### MCP Server Command
|
|
25
|
-
|
|
26
|
-
Use this server command in the host's MCP configuration:
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
npx -y gitnexus mcp
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
### Useful Tools
|
|
33
|
-
|
|
34
|
-
| Tool | Purpose |
|
|
35
|
-
|------|---------|
|
|
36
|
-
| `gitnexus_query` | Find execution flows and functional areas by concept |
|
|
37
|
-
| `gitnexus_context` | Inspect callers, callees, references, and process participation for a symbol |
|
|
38
|
-
| `gitnexus_impact` | Understand blast radius before changing a symbol |
|
|
39
|
-
| `gitnexus_detect_changes` | Check changed symbols and affected flows before finishing |
|
|
40
|
-
| `gitnexus_cypher` | Run direct graph queries |
|
|
41
|
-
| `gitnexus_list_repos` | List indexed repositories |
|
|
42
|
-
|
|
43
|
-
## ABCoder
|
|
44
|
-
|
|
45
|
-
ABCoder parses code into UniAST and gives precise package, file, and node-level structure. Use it for signatures, type shapes, implementations, dependencies, and reverse references.
|
|
46
|
-
|
|
47
|
-
### Install
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
go install github.com/cloudwego/abcoder@latest
|
|
51
|
-
abcoder --help
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
### Parse Repositories
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
abcoder parse /absolute/path/to/package \
|
|
58
|
-
--lang typescript \
|
|
59
|
-
--name package-name \
|
|
60
|
-
--output ~/abcoder-asts
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
For monorepos, parse each package with a stable `--name` so task notes can reference the same repository names.
|
|
64
|
-
|
|
65
|
-
### MCP Server Command
|
|
66
|
-
|
|
67
|
-
Use this server command in the host's MCP configuration:
|
|
68
|
-
|
|
69
|
-
```bash
|
|
70
|
-
abcoder mcp ~/abcoder-asts
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
### Useful Tools
|
|
74
|
-
|
|
75
|
-
| Tool | Layer | Purpose |
|
|
76
|
-
|------|-------|---------|
|
|
77
|
-
| `list_repos` | 1 | List parsed repositories |
|
|
78
|
-
| `get_repo_structure` | 2 | Inspect packages and files |
|
|
79
|
-
| `get_package_structure` | 3 | Inspect nodes within a package |
|
|
80
|
-
| `get_file_structure` | 3 | Inspect functions, classes, types, and signatures in a file |
|
|
81
|
-
| `get_ast_node` | 4 | Retrieve code, dependencies, references, and implementations |
|
|
82
|
-
|
|
83
|
-
## Verification
|
|
84
|
-
|
|
85
|
-
After configuration, verify from the agent host that both MCP servers are visible. Then run one simple query against each server before starting the spec writing pass.
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
ls .gitnexus/meta.json
|
|
89
|
-
ls ~/abcoder-asts/*.json
|
|
90
|
-
```
|
|
1
|
+
# MCP Setup
|
|
2
|
+
|
|
3
|
+
GitNexus and ABCoder are recommended when bootstrapping Rudder specs because they expose architecture and AST context to the agent. They are tool choices, not platform requirements. Configure them through whatever MCP mechanism your agent host provides.
|
|
4
|
+
|
|
5
|
+
## GitNexus
|
|
6
|
+
|
|
7
|
+
GitNexus builds a code knowledge graph from the repository. Use it for module boundaries, execution flows, dependency relationships, blast radius, and graph queries.
|
|
8
|
+
|
|
9
|
+
### Install and Index
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# Run from the repository root.
|
|
13
|
+
npx gitnexus analyze
|
|
14
|
+
|
|
15
|
+
# Check index status.
|
|
16
|
+
npx gitnexus status
|
|
17
|
+
|
|
18
|
+
# Re-index after code changes when the analysis is stale.
|
|
19
|
+
npx gitnexus analyze
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The index is written to `.gitnexus/`. Keep embeddings only if the project already uses them; otherwise a normal index is enough for spec bootstrapping.
|
|
23
|
+
|
|
24
|
+
### MCP Server Command
|
|
25
|
+
|
|
26
|
+
Use this server command in the host's MCP configuration:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npx -y gitnexus mcp
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### Useful Tools
|
|
33
|
+
|
|
34
|
+
| Tool | Purpose |
|
|
35
|
+
|------|---------|
|
|
36
|
+
| `gitnexus_query` | Find execution flows and functional areas by concept |
|
|
37
|
+
| `gitnexus_context` | Inspect callers, callees, references, and process participation for a symbol |
|
|
38
|
+
| `gitnexus_impact` | Understand blast radius before changing a symbol |
|
|
39
|
+
| `gitnexus_detect_changes` | Check changed symbols and affected flows before finishing |
|
|
40
|
+
| `gitnexus_cypher` | Run direct graph queries |
|
|
41
|
+
| `gitnexus_list_repos` | List indexed repositories |
|
|
42
|
+
|
|
43
|
+
## ABCoder
|
|
44
|
+
|
|
45
|
+
ABCoder parses code into UniAST and gives precise package, file, and node-level structure. Use it for signatures, type shapes, implementations, dependencies, and reverse references.
|
|
46
|
+
|
|
47
|
+
### Install
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
go install github.com/cloudwego/abcoder@latest
|
|
51
|
+
abcoder --help
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Parse Repositories
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
abcoder parse /absolute/path/to/package \
|
|
58
|
+
--lang typescript \
|
|
59
|
+
--name package-name \
|
|
60
|
+
--output ~/abcoder-asts
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
For monorepos, parse each package with a stable `--name` so task notes can reference the same repository names.
|
|
64
|
+
|
|
65
|
+
### MCP Server Command
|
|
66
|
+
|
|
67
|
+
Use this server command in the host's MCP configuration:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
abcoder mcp ~/abcoder-asts
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Useful Tools
|
|
74
|
+
|
|
75
|
+
| Tool | Layer | Purpose |
|
|
76
|
+
|------|-------|---------|
|
|
77
|
+
| `list_repos` | 1 | List parsed repositories |
|
|
78
|
+
| `get_repo_structure` | 2 | Inspect packages and files |
|
|
79
|
+
| `get_package_structure` | 3 | Inspect nodes within a package |
|
|
80
|
+
| `get_file_structure` | 3 | Inspect functions, classes, types, and signatures in a file |
|
|
81
|
+
| `get_ast_node` | 4 | Retrieve code, dependencies, references, and implementations |
|
|
82
|
+
|
|
83
|
+
## Verification
|
|
84
|
+
|
|
85
|
+
After configuration, verify from the agent host that both MCP servers are visible. Then run one simple query against each server before starting the spec writing pass.
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
ls .gitnexus/meta.json
|
|
89
|
+
ls ~/abcoder-asts/*.json
|
|
90
|
+
```
|