@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,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` resumes a task by deciding which phase step to load next. The decision combines `task.json.status` with the presence of artifacts inside the task directory. The mapping is fixed in the command itself; forks that add custom statuses must extend both the workflow.md tag block and this table.
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` | `prd.md` missing | Phase 1.1 (load `rudder-brainstorm`) |
53
- | `planning` | `prd.md` exists, `implement.jsonl` only has the seed `_example` row | Phase 1.3 (curate JSONL context) |
54
- | `planning` | `prd.md` exists, `implement.jsonl` curated | Phase 1.4 (run `task.py start`) |
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 start <task>
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
+ ```