@mengde1231/rudder 0.5.23 → 0.6.1
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 -119
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +70 -2
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/update.d.ts.map +1 -1
- package/dist/commands/update.js +57 -2
- package/dist/commands/update.js.map +1 -1
- package/dist/configurators/workflow.d.ts +3 -0
- package/dist/configurators/workflow.d.ts.map +1 -1
- package/dist/configurators/workflow.js +13 -1
- package/dist/configurators/workflow.js.map +1 -1
- package/dist/templates/claude/agents/rudder-check.md +37 -3
- package/dist/templates/codebuddy/agents/rudder-check.md +37 -3
- package/dist/templates/codex/agents/rudder-check.toml +10 -3
- package/dist/templates/codex/config.toml +30 -35
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/SKILL.md +41 -0
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/mcp-setup.md +90 -0
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/repository-analysis.md +59 -0
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-task-planning.md +61 -0
- package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-writing.md +70 -0
- package/dist/templates/cursor/agents/rudder-check.md +37 -3
- package/dist/templates/droid/droids/rudder-check.md +37 -3
- package/dist/templates/gemini/agents/rudder-check.md +37 -3
- package/dist/templates/kiro/agents/rudder-check.json +1 -1
- package/dist/templates/opencode/agents/rudder-check.md +37 -3
- package/dist/templates/pi/agents/rudder-check.md +68 -1
- package/dist/templates/qoder/agents/rudder-check.md +37 -3
- package/dist/templates/rudder/config.yaml +15 -2
- package/dist/templates/rudder/config_local.yml +17 -0
- package/dist/templates/rudder/gitignore.txt +1 -1
- package/dist/templates/rudder/index.d.ts +1 -0
- package/dist/templates/rudder/index.d.ts.map +1 -1
- package/dist/templates/rudder/index.js +1 -0
- package/dist/templates/rudder/index.js.map +1 -1
- package/dist/templates/rudder/scripts/common/config.py +37 -7
- package/dist/templates/rudder/scripts/common/rudder_config.py +26 -4
- package/dist/templates/rudder/workflow.md +6 -2
- package/dist/templates/shared-hooks/session-start.py +2 -0
- package/dist/utils/registry-config.d.ts +7 -0
- package/dist/utils/registry-config.d.ts.map +1 -0
- package/dist/utils/registry-config.js +171 -0
- package/dist/utils/registry-config.js.map +1 -0
- package/dist/utils/template-fetcher.d.ts +11 -0
- package/dist/utils/template-fetcher.d.ts.map +1 -1
- package/dist/utils/template-fetcher.js +51 -2
- package/dist/utils/template-fetcher.js.map +1 -1
- package/package.json +2 -2
|
@@ -2,7 +2,7 @@ import path from "node:path";
|
|
|
2
2
|
import { DIR_NAMES, PATHS } from "../constants/paths.js";
|
|
3
3
|
import { copyRudderDir } from "../templates/extract.js";
|
|
4
4
|
// Import rudder templates (generic, not project-specific)
|
|
5
|
-
import { workflowMdTemplate, configYamlTemplate, gitignoreTemplate, } from "../templates/rudder/index.js";
|
|
5
|
+
import { workflowMdTemplate, configYamlTemplate, configLocalYmlTemplate, gitignoreTemplate, } from "../templates/rudder/index.js";
|
|
6
6
|
// Import markdown templates
|
|
7
7
|
import { agentProgressIndexContent,
|
|
8
8
|
// Backend structure (multi-doc)
|
|
@@ -31,6 +31,7 @@ export async function createWorkflowStructure(cwd, options) {
|
|
|
31
31
|
const projectType = options?.projectType ?? "fullstack";
|
|
32
32
|
const skipSpecTemplates = options?.skipSpecTemplates ?? false;
|
|
33
33
|
const skipConfig = options?.skipConfig ?? false;
|
|
34
|
+
const skipLocalConfig = options?.skipLocalConfig ?? false;
|
|
34
35
|
const packages = options?.packages;
|
|
35
36
|
const remoteSpecPackages = options?.remoteSpecPackages;
|
|
36
37
|
// Create base .rudder directory
|
|
@@ -47,6 +48,17 @@ export async function createWorkflowStructure(cwd, options) {
|
|
|
47
48
|
if (!skipConfig) {
|
|
48
49
|
await writeFile(path.join(cwd, DIR_NAMES.WORKFLOW, "config.yaml"), configYamlTemplate);
|
|
49
50
|
}
|
|
51
|
+
// Copy config_local.yml (personal tool path overrides, gitignored)
|
|
52
|
+
// Only create if not already present — never overwrite user's local config.
|
|
53
|
+
// Skipped during platform configure (skipLocalConfig=true) so test assertions
|
|
54
|
+
// comparing collectPlatformTemplates vs actual files stay in sync.
|
|
55
|
+
const localConfigPath = path.join(cwd, DIR_NAMES.WORKFLOW, "config_local.yml");
|
|
56
|
+
if (!skipConfig && !skipLocalConfig) {
|
|
57
|
+
const { existsSync } = await import("node:fs");
|
|
58
|
+
if (!existsSync(localConfigPath)) {
|
|
59
|
+
await writeFile(localConfigPath, configLocalYmlTemplate);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
50
62
|
// Create workspace/ with index.md
|
|
51
63
|
ensureDir(path.join(cwd, PATHS.WORKSPACE));
|
|
52
64
|
await writeFile(path.join(cwd, PATHS.WORKSPACE, "index.md"), replacePythonCommandLiterals(agentProgressIndexContent));
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/configurators/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,0DAA0D;AAC1D,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AAEtC,4BAA4B;AAC5B,OAAO,EACL,yBAAyB;AACzB,gCAAgC;AAChC,mBAAmB,EACnB,gCAAgC,EAChC,gCAAgC,EAChC,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B;AAC3B,iCAAiC;AACjC,oBAAoB,EACpB,iCAAiC,EACjC,yBAAyB,EACzB,6BAA6B,EAC7B,kCAAkC,EAClC,gCAAgC,EAChC,8BAA8B;AAC9B,mBAAmB;AACnB,kBAAkB,EAClB,oCAAoC,EACpC,mCAAmC,GACpC,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EACL,eAAe,GAGhB,MAAM,8BAA8B,CAAC;
|
|
1
|
+
{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/configurators/workflow.ts"],"names":[],"mappings":"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"}
|
|
@@ -73,9 +73,38 @@ After finding issues:
|
|
|
73
73
|
|
|
74
74
|
### Step 4: Run Verification
|
|
75
75
|
|
|
76
|
+
#### Step 4a: Static Checks
|
|
77
|
+
|
|
76
78
|
Run project's lint and typecheck commands to verify changes.
|
|
77
79
|
|
|
78
|
-
|
|
80
|
+
#### Step 4b: Compile/Build Verification
|
|
81
|
+
|
|
82
|
+
Detect the project type and run the appropriate compile command:
|
|
83
|
+
|
|
84
|
+
| Project type | Detect by | Compile command |
|
|
85
|
+
|-------------|-----------|-----------------|
|
|
86
|
+
| Java (Maven) | `pom.xml` | `mvn compile -q` |
|
|
87
|
+
| Java (Gradle) | `build.gradle` or `build.gradle.kts` | `./gradlew compileJava -q` |
|
|
88
|
+
| Go | `go.mod` | `go build ./...` |
|
|
89
|
+
| Rust | `Cargo.toml` | `cargo check --all-targets` |
|
|
90
|
+
| Kotlin (Gradle) | `build.gradle.kts` | `./gradlew compileKotlin -q` |
|
|
91
|
+
| TypeScript | `tsconfig.json` | `npx tsc --noEmit` |
|
|
92
|
+
| Node.js (JS only) | `package.json` (no tsconfig) | `npx eslint . --no-error-on-unmatched-pattern` |
|
|
93
|
+
|
|
94
|
+
**Tool path resolution**: Use the paths from the `<tool-paths>` block injected at session-start (e.g., `<tool-paths> - java: /path/to/java </tool-paths>`). If a tool's absolute path is listed there, use it; otherwise fall back to the system PATH.
|
|
95
|
+
|
|
96
|
+
**Tool path discovery**: 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.
|
|
97
|
+
|
|
98
|
+
#### Step 4c: Compile-Fix Retry Loop
|
|
99
|
+
|
|
100
|
+
If compilation fails, enter a fix loop (max 3 rounds):
|
|
101
|
+
|
|
102
|
+
1. Parse compiler error output — identify file, line, and error message
|
|
103
|
+
2. Fix the source code that caused the error
|
|
104
|
+
3. Re-run the compile command
|
|
105
|
+
4. If still failing after 3 rounds, stop and report remaining errors
|
|
106
|
+
|
|
107
|
+
If failed (static checks), fix issues and re-run before entering Step 4b.
|
|
79
108
|
|
|
80
109
|
---
|
|
81
110
|
|
|
@@ -100,8 +129,13 @@ If failed, fix issues and re-run.
|
|
|
100
129
|
|
|
101
130
|
### Verification Results
|
|
102
131
|
|
|
103
|
-
-
|
|
104
|
-
-
|
|
132
|
+
- Lint: PASS / FAIL
|
|
133
|
+
- TypeCheck: PASS / FAIL
|
|
134
|
+
- Compile: PASS / FAIL (project: Maven/Gradle/Go/Rust/TS/JS, rounds: N)
|
|
135
|
+
|
|
136
|
+
### Compile Errors (if any)
|
|
137
|
+
|
|
138
|
+
(List unresolved compiler errors if max retry reached)
|
|
105
139
|
|
|
106
140
|
### Summary
|
|
107
141
|
|
|
@@ -73,9 +73,38 @@ After finding issues:
|
|
|
73
73
|
|
|
74
74
|
### Step 4: Run Verification
|
|
75
75
|
|
|
76
|
+
#### Step 4a: Static Checks
|
|
77
|
+
|
|
76
78
|
Run project's lint and typecheck commands to verify changes.
|
|
77
79
|
|
|
78
|
-
|
|
80
|
+
#### Step 4b: Compile/Build Verification
|
|
81
|
+
|
|
82
|
+
Detect the project type and run the appropriate compile command:
|
|
83
|
+
|
|
84
|
+
| Project type | Detect by | Compile command |
|
|
85
|
+
|-------------|-----------|-----------------|
|
|
86
|
+
| Java (Maven) | `pom.xml` | `mvn compile -q` |
|
|
87
|
+
| Java (Gradle) | `build.gradle` or `build.gradle.kts` | `./gradlew compileJava -q` |
|
|
88
|
+
| Go | `go.mod` | `go build ./...` |
|
|
89
|
+
| Rust | `Cargo.toml` | `cargo check --all-targets` |
|
|
90
|
+
| Kotlin (Gradle) | `build.gradle.kts` | `./gradlew compileKotlin -q` |
|
|
91
|
+
| TypeScript | `tsconfig.json` | `npx tsc --noEmit` |
|
|
92
|
+
| Node.js (JS only) | `package.json` (no tsconfig) | `npx eslint . --no-error-on-unmatched-pattern` |
|
|
93
|
+
|
|
94
|
+
**Tool path resolution**: Use the paths from the `<tool-paths>` block injected at session-start (e.g., `<tool-paths> - java: /path/to/java </tool-paths>`). If a tool's absolute path is listed there, use it; otherwise fall back to the system PATH.
|
|
95
|
+
|
|
96
|
+
**Tool path discovery**: 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.
|
|
97
|
+
|
|
98
|
+
#### Step 4c: Compile-Fix Retry Loop
|
|
99
|
+
|
|
100
|
+
If compilation fails, enter a fix loop (max 3 rounds):
|
|
101
|
+
|
|
102
|
+
1. Parse compiler error output — identify file, line, and error message
|
|
103
|
+
2. Fix the source code that caused the error
|
|
104
|
+
3. Re-run the compile command
|
|
105
|
+
4. If still failing after 3 rounds, stop and report remaining errors
|
|
106
|
+
|
|
107
|
+
If Step 4a failed (static checks), fix issues and re-run before entering Step 4b.
|
|
79
108
|
|
|
80
109
|
---
|
|
81
110
|
|
|
@@ -100,8 +129,13 @@ If failed, fix issues and re-run.
|
|
|
100
129
|
|
|
101
130
|
### Verification Results
|
|
102
131
|
|
|
103
|
-
-
|
|
104
|
-
-
|
|
132
|
+
- Lint: PASS / FAIL
|
|
133
|
+
- TypeCheck: PASS / FAIL
|
|
134
|
+
- Compile: PASS / FAIL (project: Maven/Gradle/Go/Rust/TS/JS, rounds: N)
|
|
135
|
+
|
|
136
|
+
### Compile Errors (if any)
|
|
137
|
+
|
|
138
|
+
(List unresolved compiler errors if max retry reached)
|
|
105
139
|
|
|
106
140
|
### Summary
|
|
107
141
|
|
|
@@ -47,11 +47,15 @@ Review checklist:
|
|
|
47
47
|
- Check whether tests should be added or updated.
|
|
48
48
|
- Check whether `.rudder/spec/` docs need sync after implementation.
|
|
49
49
|
- Run lint and type-check; fix any failures.
|
|
50
|
+
- Detect project type and run compile: Maven (`mvn compile -q`), Gradle (`./gradlew compileJava -q`), Go (`go build ./...`), Rust (`cargo check --all-targets`), TypeScript (`npx tsc --noEmit`), or Node.js (`npx eslint . --no-error-on-unmatched-pattern`).
|
|
51
|
+
- 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.
|
|
52
|
+
- Use tool paths from the `<tool-paths>` block injected at session-start if available; otherwise fall back to system PATH.
|
|
53
|
+
- 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.
|
|
50
54
|
- Prefer concrete findings over speculative warnings.
|
|
51
55
|
|
|
52
56
|
When you find an issue:
|
|
53
57
|
1. Fix it directly using edit/write tools.
|
|
54
|
-
2. Re-run lint
|
|
58
|
+
2. Re-run lint, type-check, and compile until green.
|
|
55
59
|
3. Record what you changed and why.
|
|
56
60
|
|
|
57
61
|
Output format:
|
|
@@ -66,9 +70,12 @@ Only list issues you could not self-fix (e.g. missing product decision, out-of-s
|
|
|
66
70
|
## Verification
|
|
67
71
|
- Lint: pass/fail
|
|
68
72
|
- TypeCheck: pass/fail
|
|
69
|
-
-
|
|
73
|
+
- Compile: pass/fail (project: Maven/Gradle/Go/Rust/TS/JS, rounds: N)
|
|
70
74
|
|
|
71
|
-
|
|
75
|
+
## Compile Errors (if any)
|
|
76
|
+
(List unresolved compiler errors if max retry reached)
|
|
77
|
+
|
|
78
|
+
If no issues are found, say so explicitly after verifying lint/type-check/compile pass.
|
|
72
79
|
"""
|
|
73
80
|
|
|
74
81
|
# Disable Codex collab tools entirely for this sub-agent. With both
|
|
@@ -1,35 +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
|
-
#
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
#
|
|
26
|
-
#
|
|
27
|
-
#
|
|
28
|
-
#
|
|
29
|
-
#
|
|
30
|
-
#
|
|
31
|
-
# ceiling is 3,600,000 (1 h).
|
|
32
|
-
[features.multi_agent_v2]
|
|
33
|
-
enabled = true
|
|
34
|
-
max_concurrent_threads_per_session = 6
|
|
35
|
-
min_wait_timeout_ms = 480000
|
|
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.
|
|
@@ -0,0 +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.
|
|
@@ -0,0 +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
|
+
```
|
package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/repository-analysis.md
ADDED
|
@@ -0,0 +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.
|
package/dist/templates/common/bundled-skills/rudder-spec-bootstarp/references/spec-task-planning.md
ADDED
|
@@ -0,0 +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.
|
|
@@ -0,0 +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.
|
|
@@ -72,9 +72,38 @@ After finding issues:
|
|
|
72
72
|
|
|
73
73
|
### Step 4: Run Verification
|
|
74
74
|
|
|
75
|
+
#### Step 4a: Static Checks
|
|
76
|
+
|
|
75
77
|
Run project's lint and typecheck commands to verify changes.
|
|
76
78
|
|
|
77
|
-
|
|
79
|
+
#### Step 4b: Compile/Build Verification
|
|
80
|
+
|
|
81
|
+
Detect the project type and run the appropriate compile command:
|
|
82
|
+
|
|
83
|
+
| Project type | Detect by | Compile command |
|
|
84
|
+
|-------------|-----------|-----------------|
|
|
85
|
+
| Java (Maven) | `pom.xml` | `mvn compile -q` |
|
|
86
|
+
| Java (Gradle) | `build.gradle` or `build.gradle.kts` | `./gradlew compileJava -q` |
|
|
87
|
+
| Go | `go.mod` | `go build ./...` |
|
|
88
|
+
| Rust | `Cargo.toml` | `cargo check --all-targets` |
|
|
89
|
+
| Kotlin (Gradle) | `build.gradle.kts` | `./gradlew compileKotlin -q` |
|
|
90
|
+
| TypeScript | `tsconfig.json` | `npx tsc --noEmit` |
|
|
91
|
+
| Node.js (JS only) | `package.json` (no tsconfig) | `npx eslint . --no-error-on-unmatched-pattern` |
|
|
92
|
+
|
|
93
|
+
**Tool path resolution**: Use the paths from the `<tool-paths>` block injected at session-start (e.g., `<tool-paths> - java: /path/to/java </tool-paths>`). If a tool's absolute path is listed there, use it; otherwise fall back to the system PATH.
|
|
94
|
+
|
|
95
|
+
**Tool path discovery**: 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.
|
|
96
|
+
|
|
97
|
+
#### Step 4c: Compile-Fix Retry Loop
|
|
98
|
+
|
|
99
|
+
If compilation fails, enter a fix loop (max 3 rounds):
|
|
100
|
+
|
|
101
|
+
1. Parse compiler error output — identify file, line, and error message
|
|
102
|
+
2. Fix the source code that caused the error
|
|
103
|
+
3. Re-run the compile command
|
|
104
|
+
4. If still failing after 3 rounds, stop and report remaining errors
|
|
105
|
+
|
|
106
|
+
If Step 4a failed (static checks), fix issues and re-run before entering Step 4b.
|
|
78
107
|
|
|
79
108
|
---
|
|
80
109
|
|
|
@@ -99,8 +128,13 @@ If failed, fix issues and re-run.
|
|
|
99
128
|
|
|
100
129
|
### Verification Results
|
|
101
130
|
|
|
102
|
-
-
|
|
103
|
-
-
|
|
131
|
+
- Lint: PASS / FAIL
|
|
132
|
+
- TypeCheck: PASS / FAIL
|
|
133
|
+
- Compile: PASS / FAIL (project: Maven/Gradle/Go/Rust/TS/JS, rounds: N)
|
|
134
|
+
|
|
135
|
+
### Compile Errors (if any)
|
|
136
|
+
|
|
137
|
+
(List unresolved compiler errors if max retry reached)
|
|
104
138
|
|
|
105
139
|
### Summary
|
|
106
140
|
|