@mengde1231/rudder 0.6.1 → 0.6.20

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 CHANGED
@@ -121,18 +121,6 @@ Nah. Personal workspace journals are per-developer. Shared specs and tasks go th
121
121
 
122
122
  </details>
123
123
 
124
- ## A Note from the Author
125
-
126
- **Why does the version start at 0.5?**
127
-
128
- The version numbers aren't skipped — I iterated locally for many rounds before publishing. Rudder was born in May (the 5th month), so the major version is 0.5, with the first public release at 0.5.30.
129
-
130
- Rudder draws from many open-source projects, and I grew up learning from the open-source community. But open-source covers a broad set of use cases — most of them aren't battle-tested in real production workflows. As a Java full-stack developer, I use Rudder daily myself and keep iterating on it. That makes it relatively more friendly to Java full-stack engineers — the Java spec templates are also being actively updated. That said, every other language works just as well — Rudder itself is completely platform-agnostic.
131
-
132
- One person can only do so much, but every pit I fall into will be filled. Hope it helps you who are using AI to write code.
133
-
134
- > 📖 Rudder's online documentation and user manual are being gradually improved. Stay tuned.
135
-
136
124
  ## Acknowledgments
137
125
 
138
126
  Rudder wouldn't exist without the open-source coding agent community. We studied how many projects solve the same problems — context injection, workflow gates, multi-platform support — and built the version we wished we had.
@@ -79,17 +79,44 @@ Run project's lint and typecheck commands to verify changes.
79
79
 
80
80
  #### Step 4b: Compile/Build Verification
81
81
 
82
- Detect the project type and run the appropriate compile command:
82
+ **Priority**: Use the project's own declared build command when available.
83
+ Only fall back to defaults when no project-level declaration exists.
83
84
 
84
- | Project type | Detect by | Compile command |
85
- |-------------|-----------|-----------------|
85
+ 1. **Node/Frontend projects** — check `package.json`:
86
+ - Has `scripts.build`? → Run `npm run build` (or `pnpm run build` / `yarn build` per lockfile)
87
+ - Has `scripts.typecheck` but no `build`? → Run `npm run typecheck`
88
+ - Neither? → `npx tsc --noEmit` if `tsconfig.json` exists; else `npx eslint . --no-error-on-unmatched-pattern`
89
+
90
+ 2. **Other projects** — use the standard compile for the detected tool:
91
+
92
+ | Project type | Detect by | Default compile command |
93
+ |-------------|-----------|------------------------|
86
94
  | Java (Maven) | `pom.xml` | `mvn compile -q` |
87
- | Java (Gradle) | `build.gradle` or `build.gradle.kts` | `./gradlew compileJava -q` |
95
+ | Java (Gradle) | `build.gradle` / `.kts` | `./gradlew compileJava -q` |
88
96
  | Go | `go.mod` | `go build ./...` |
89
97
  | Rust | `Cargo.toml` | `cargo check --all-targets` |
90
98
  | 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` |
99
+
100
+ **Note**: Build performance tuning (parallel, caching, daemon) belongs in the
101
+ build tool's own config, not in this command. Rudder runs the standard command;
102
+ the tool reads its own optimization flags automatically.
103
+
104
+ #### Step 4b-hint: Build Performance Recommendation
105
+
106
+ After compilation completes, if it took **> 30 seconds**, check whether the
107
+ build tool's standard performance config exists. If missing, add a
108
+ recommendation to the report Summary:
109
+
110
+ | Build tool | Check for | Recommend creating |
111
+ |-----------|-----------|-------------------|
112
+ | Maven | `.mvn/maven.config` exists? | Create it with `-T 1C` (parallel multi-module build) |
113
+ | Gradle | `org.gradle.parallel=true` in `gradle.properties`? | Add the property |
114
+ | Node/Frontend | (typically fast; skip) | — |
115
+
116
+ **Rules**:
117
+ - Only **recommend** in the report — do NOT create the file automatically.
118
+ - If the config already exists, stay silent (one-time hint, not recurring noise).
119
+ - Phrasing: "Compilation took Xs. Consider creating `.mvn/maven.config` with `-T 1C` to enable parallel builds — Maven will read it automatically on every invocation."
93
120
 
94
121
  **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
122
 
@@ -47,7 +47,11 @@ 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`).
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.
51
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.
52
56
  - Use tool paths from the `<tool-paths>` block injected at session-start if available; otherwise fall back to system PATH.
53
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.
@@ -7,7 +7,9 @@ description: "Captures executable contracts and coding knowledge into .rudder/sp
7
7
 
8
8
  When you learn something valuable (from debugging, implementing, or discussion), use this skill to update the relevant code-spec documents.
9
9
 
10
- **Timing**: After completing a task, fixing a bug, or discovering a new pattern
10
+ **Timing**: Only when the task changes durable project knowledge. The current
11
+ task's requirements belong in `prd.md`; implementing a business request does
12
+ not automatically require a Spec update.
11
13
 
12
14
  ---
13
15
 
@@ -33,6 +35,17 @@ Required sections for infra/cross-layer specs:
33
35
 
34
36
  ## When to Update Code-Specs
35
37
 
38
+ Update a code-spec when the change introduces or changes a durable business
39
+ rule, workflow/state transition, acceptance rule, API/DTO/VO/database/
40
+ permission/transaction/cache contract, reusable implementation convention, or
41
+ prevention rule. Also update it when the existing Spec is shown to be wrong or
42
+ incomplete.
43
+
44
+ Do not update a code-spec for one-off copy, styling, customer campaign rules,
45
+ single-page behavior, or implementation details that future work does not need
46
+ to repeat. If no trigger applies, record `no durable Spec change` in the task
47
+ summary and stop this skill.
48
+
36
49
  | Trigger | Example | Target Spec |
37
50
  |---------|---------|-------------|
38
51
  | **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
@@ -1,8 +1,15 @@
1
1
  # Update Code-Spec - Capture Executable Contracts
2
2
 
3
- When you learn something valuable (from debugging, implementing, or discussion), use this to update the relevant code-spec documents.
4
-
5
- **Timing**: After completing a task, fixing a bug, or discovering a new pattern
3
+ Use this skill only when a task changes durable project knowledge. The current
4
+ business requirements belong in `prd.md`; implementing a requirement does not
5
+ automatically require a Spec update.
6
+
7
+ **Timing**: Update after a task adds or changes a durable business rule,
8
+ workflow/state transition, acceptance rule, API/DTO/VO/database/
9
+ permission/transaction/cache contract, reusable convention, prevention rule,
10
+ or exposes an incorrect Spec. Skip one-off copy, styling, customer campaigns,
11
+ and local implementation details; record `no durable Spec change` in the task
12
+ summary when skipped.
6
13
 
7
14
  ---
8
15
 
@@ -101,6 +101,19 @@ function buildBreadcrumb(id, status, templates, source = null) {
101
101
  return `<workflow-state>\n${header}\n${body}\n</workflow-state>`
102
102
  }
103
103
 
104
+ function shouldSkipPrompt(input) {
105
+ const prompt = typeof input?.prompt === "string"
106
+ ? input.prompt
107
+ : typeof input?.message === "string"
108
+ ? input.message
109
+ : ""
110
+ return [
111
+ "skip rudder", "no task", "just do it", "don't create a task",
112
+ "do not create a task", "跳过 rudder", "别走流程", "小修一下",
113
+ "直接改", "先别建任务",
114
+ ].some((keyword) => new RegExp(`(?<![\\w-])${keyword.replace(/[.*+?^${}()|[\\]\\]/g, "\\\\$&")}(?![\\w-])`, "i").test(prompt))
115
+ }
116
+
104
117
  // OpenCode 1.2.x expects plugins to be factory functions (see inject-subagent-context.js comment).
105
118
  export default async ({ directory }) => {
106
119
  const ctx = new RudderContext(directory)
@@ -124,6 +137,10 @@ export default async ({ directory }) => {
124
137
  if (process.env.OPENCODE_NON_INTERACTIVE === "1") {
125
138
  return
126
139
  }
140
+ if (shouldSkipPrompt(input)) {
141
+ debugLog("workflow-state", "Skipping breadcrumb for explicit fast path")
142
+ return
143
+ }
127
144
  if (!ctx.isRudderProject()) {
128
145
  return
129
146
  }
@@ -102,6 +102,28 @@ max_journal_lines: 2000
102
102
  # codex:
103
103
  # dispatch_mode: inline # or "sub-agent" to dispatch rudder-* sub-agents
104
104
 
105
+ #-------------------------------------------------------------------------------
106
+ # Prompt injection escape hatch
107
+ #-------------------------------------------------------------------------------
108
+ # When the current user message contains one of Rudder's explicit skip phrases,
109
+ # the per-turn workflow breadcrumb is omitted for that turn. This does not
110
+ # disable SessionStart or sub-agent context injection.
111
+ #
112
+ # prompt_injection:
113
+ # skip_keyword: "skip rudder" # empty string disables the configured alias
114
+
115
+ #-------------------------------------------------------------------------------
116
+ # Sub-agent context injection limits
117
+ #-------------------------------------------------------------------------------
118
+ # Context is truncated safely at UTF-8 boundaries. Once the total budget is
119
+ # exhausted, remaining files are represented by an index line and can be read
120
+ # on demand by the agent. A value of 0 disables that limit.
121
+ #
122
+ # context_injection:
123
+ # max_file_bytes: 32768
124
+ # max_artifact_bytes: 65536
125
+ # max_total_bytes: 131072
126
+
105
127
  #-------------------------------------------------------------------------------
106
128
  # Tool Path Configuration
107
129
  #-------------------------------------------------------------------------------
@@ -117,10 +117,11 @@ def _parse_yaml_block(
117
117
  key, _, value = stripped.partition(":")
118
118
  key = key.strip()
119
119
  value = _strip_inline_comment(value).strip()
120
+ was_quoted = len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'")
120
121
  value = _unquote(value)
121
122
  current_list = None
122
123
 
123
- if value:
124
+ if value or was_quoted:
124
125
  # key: value
125
126
  target[key] = value
126
127
  i += 1
@@ -168,10 +169,50 @@ DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
168
169
  DEFAULT_MAX_JOURNAL_LINES = 2000
169
170
  DEFAULT_SESSION_AUTO_COMMIT = False # journal / task archive auto-commit
170
171
  DEFAULT_CODE_AUTO_COMMIT = False # Phase 3.4 code commit
172
+ DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD = "skip rudder"
173
+ DEFAULT_CONTEXT_INJECTION_MAX_FILE_BYTES = 32768
174
+ DEFAULT_CONTEXT_INJECTION_MAX_ARTIFACT_BYTES = 65536
175
+ DEFAULT_CONTEXT_INJECTION_MAX_TOTAL_BYTES = 131072
171
176
 
172
177
  CONFIG_FILE = "config.yaml"
173
178
 
174
179
 
180
+ def get_prompt_injection_skip_keyword(repo_root: Path | None = None) -> str:
181
+ """Return the per-turn workflow breadcrumb escape-hatch keyword."""
182
+ config = _load_config(repo_root)
183
+ section = config.get("prompt_injection")
184
+ if not isinstance(section, dict):
185
+ return DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD
186
+ value = section.get("skip_keyword", DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD)
187
+ return value if isinstance(value, str) else DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD
188
+
189
+
190
+ def get_context_injection_limits(repo_root: Path | None = None) -> dict[str, int]:
191
+ """Return safe byte limits for sub-agent context injection.
192
+
193
+ A value of zero disables that limit. Invalid or negative values fall back
194
+ to the documented default so malformed local config cannot break hooks.
195
+ """
196
+ config = _load_config(repo_root)
197
+ section = config.get("context_injection")
198
+ defaults = {
199
+ "max_file_bytes": DEFAULT_CONTEXT_INJECTION_MAX_FILE_BYTES,
200
+ "max_artifact_bytes": DEFAULT_CONTEXT_INJECTION_MAX_ARTIFACT_BYTES,
201
+ "max_total_bytes": DEFAULT_CONTEXT_INJECTION_MAX_TOTAL_BYTES,
202
+ }
203
+ if not isinstance(section, dict):
204
+ return defaults
205
+ result = dict(defaults)
206
+ for key, default in defaults.items():
207
+ value = section.get(key, default)
208
+ try:
209
+ parsed = int(value)
210
+ except (TypeError, ValueError):
211
+ parsed = default
212
+ result[key] = parsed if parsed >= 0 else default
213
+ return result
214
+
215
+
175
216
  def _is_true_config_value(value: object) -> bool:
176
217
  """Return True when a config value represents an enabled flag."""
177
218
  if isinstance(value, bool):
@@ -120,7 +120,7 @@ python3 ./.rudder/scripts/get_context.py --mode phase --step <X.Y> # detailed g
120
120
  TAG ↔ PHASE scoping:
121
121
  [workflow-state:no_task] → no active task; before Phase 1
122
122
  [workflow-state:planning] → all of Phase 1 (status='planning')
123
- [workflow-state:in_progress] → Phase 2 + Phase 3.1-3.4
123
+ [workflow-state:in_progress] → Phase 2 + Phase 3.2-3.4
124
124
  (status stays 'in_progress' from
125
125
  task.py start until task.py archive)
126
126
  [workflow-state:completed] → currently DEAD: cmd_archive flips
@@ -151,8 +151,8 @@ Phase 3: Finish → distill lessons + wrap-up
151
151
 
152
152
  [workflow-state:no_task]
153
153
  No active task. **A Direct answer** — pure Q&A / explanation / lookup / chat; no file writes + one-line answer + repo reads ≤ 2 files → AI judges, no override needed.
154
- **B Create a task** — any implementation / code change / build / refactor work. Entry sequence: (1) `python3 ./.rudder/scripts/task.py create "<title>"` to create the task (status=planning, breadcrumb switches to [workflow-state:planning] for brainstorm + jsonl phase guidance) → (2) load `rudder-brainstorm` skill to discuss requirements with the user and iterate on prd.md → (3) once prd is done and jsonl is curated, run `task.py start <task-dir>` to enter [workflow-state:in_progress] for the implementation skeleton. **"It looks small" is NOT grounds for downgrading B to A or C**.
155
- **C Inline change** (per-turn only, escape hatch for B) — the user's CURRENT message MUST contain one of: "skip rudder" / "no task" / "just do it" / "don't create a task" / "跳过 rudder" / "别走流程" / "小修一下" / "直接改" / "先别建任务" → briefly acknowledge ("ok, skipping rudder flow this turn"), then inline. **Without seeing one of these phrases you must NOT inline on your own**; do not invent an override the user never said.
154
+ **B Create a task** — implementation / code change / build / refactor work that is not an explicit Fast Path or requires a durable task record. Entry sequence: create the task, load `rudder-brainstorm`, complete the PRD and required context, then run `task.py start <task-dir>`.
155
+ **C Inline change** (per-turn fast path) — the user's CURRENT message may explicitly contain one of: "skip rudder" / "no task" / "just do it" / "don't create a task" / "跳过 rudder" / "别走流程" / "小修一下" / "直接改" / "先别建任务". When present, acknowledge briefly, skip task creation and per-turn workflow injection, then make the requested low-risk change and run the smallest relevant validation. This is not permission to bypass safety checks for database, API, permission, transaction, cache, or cross-module changes.
156
156
  [/workflow-state:no_task]
157
157
 
158
158
  ### Phase 1: Plan
@@ -192,13 +192,13 @@ Then run `task.py start <task-dir>` to flip status to in_progress.
192
192
  - 2.3 Rollback `[on demand]`
193
193
 
194
194
  <!-- Per-turn breadcrumb: shown while status='in_progress'.
195
- Scope: all of Phase 2 + Phase 3.1-3.4 (status stays 'in_progress' from
195
+ Scope: all of Phase 2 + Phase 3.2-3.4 (status stays 'in_progress' from
196
196
  task.py start until task.py archive; only archive flips it). The body
197
197
  therefore must cover every required step from implementation through
198
198
  commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
199
199
 
200
200
  [workflow-state:in_progress]
201
- **Flow**: rudder-implement → rudder-check → rudder-update-spec → commit (Phase 3.4) → `/rudder:finish-work`.
201
+ **Flow**: rudder-implement → rudder-check (full task diff) → conditional rudder-update-spec → commit (Phase 3.4) → `/rudder:finish-work`.
202
202
  **Main-session default (no override)**: dispatch the `rudder-implement` / `rudder-check` sub-agents — the main agent does NOT edit code by default. Phase 3.4 commit (required, once): after rudder-update-spec, or whenever implementation is verifiably complete, the main agent **drives the commit** — run `git diff --stat` to show changes, state the proposed commit message, then check `code_auto_commit` in `.rudder/config.yaml`: if **false** (default), **ask the user for confirmation (Y/n)** before running `git commit`; if **true**, commit directly without prompting. Only after commit, suggest `/rudder:finish-work`. `/finish-work` refuses to run on a dirty working tree (paths outside `.rudder/workspace/` and `.rudder/tasks/`).
203
203
  **Sub-agent self-exemption**: if you are already running as `rudder-implement`, implement directly from the loaded task context and do NOT spawn another `rudder-implement`; if you are already running as `rudder-check`, review/fix directly and do NOT spawn another `rudder-check`. The default dispatch rule applies to the main session only.
204
204
  **Sub-agent dispatch protocol (all platforms, all sub-agents)**: When you spawn `rudder-implement` / `rudder-check` / `rudder-research`, your dispatch prompt **MUST** start with one line: `Active task: <task path from \`task.py current\`>`. No exceptions. On class-2 platforms (codex / copilot / gemini / qoder) the sub-agent depends on this line because there is no hook to inject task context. On class-1 platforms (claude / cursor / opencode / kiro / codebuddy / droid) the line is normally redundant — the hook injects context directly — but it serves as a critical fallback when the hook fails (Windows + Claude Code PreToolUse silent skip, `--continue` resume, fork distribution, hooks disabled, etc.). For `rudder-research`, the line tells the sub-agent which `{task_dir}/research/` to write into.
@@ -211,15 +211,15 @@ Then run `task.py start <task-dir>` to flip status to in_progress.
211
211
  instead of dispatching sub-agents. -->
212
212
 
213
213
  [workflow-state:in_progress-inline]
214
- **Flow** (inline mode): main session loads `rudder-before-dev` → main session edits code → main session loads `rudder-check` → run lint / type-check / tests → fix → `rudder-update-spec` → commit (Phase 3.4) → `/rudder:finish-work`.
214
+ **Flow** (inline mode): main session loads `rudder-before-dev` → main session edits code → main session loads `rudder-check` for the full task diff → run lint / type-check / tests → fix → conditional `rudder-update-spec` → commit (Phase 3.4) → `/rudder:finish-work`.
215
215
  **Main-session default (inline dispatch_mode)**: the main agent edits code directly. Do NOT dispatch `rudder-implement` / `rudder-check` sub-agents. Load the `rudder-before-dev` skill before writing code; load the `rudder-check` skill before reporting completion.
216
216
  Phase 3.4 commit (required, once): after `rudder-update-spec`, or whenever implementation is verifiably complete, the main agent **drives the commit** — run `git diff --stat` to show changes, state the proposed commit message, then check `code_auto_commit` in `.rudder/config.yaml`: if **false** (default), **ask the user for confirmation (Y/n)** before running `git commit`; if **true**, commit directly without prompting. Only after commit, suggest `/rudder:finish-work`. `/finish-work` refuses to run on a dirty working tree (paths outside `.rudder/workspace/` and `.rudder/tasks/`).
217
217
  [/workflow-state:in_progress-inline]
218
218
 
219
219
  ### Phase 3: Finish
220
- - 3.1 Quality verification `[required · repeatable]`
220
+ - 3.1 Quality verification `[folded into 2.2 and commit preamble]`
221
221
  - 3.2 Debug retrospective `[on demand]`
222
- - 3.3 Spec update `[required · once]`
222
+ - 3.3 Spec update `[conditional · once]`
223
223
  - 3.4 Commit changes `[required · once]`
224
224
  - 3.5 Wrap-up reminder
225
225
 
@@ -566,16 +566,6 @@ If issues are found → fix → re-check, until green.
566
566
 
567
567
  Goal: ensure code quality, capture lessons, record the work.
568
568
 
569
- #### 3.1 Quality verification `[required · repeatable]`
570
-
571
- Load the `rudder-check` skill and do a final verification:
572
- - Spec compliance
573
- - lint / type-check / tests
574
- - Compile/build verification (detect project type, run compile command, fix errors up to 3 rounds)
575
- - Cross-layer consistency (when changes span layers)
576
-
577
- If issues are found → fix → re-check, until green.
578
-
579
569
  #### 3.2 Debug retrospective `[on demand]`
580
570
 
581
571
  If this task involved repeated debugging (the same issue was fixed multiple times), load the `rudder-break-loop` skill to:
@@ -585,14 +575,18 @@ If this task involved repeated debugging (the same issue was fixed multiple time
585
575
 
586
576
  The goal is to capture debugging lessons so the same class of issue doesn't recur.
587
577
 
588
- #### 3.3 Spec update `[required · once]`
578
+ #### 3.3 Spec update `[conditional · once]`
589
579
 
590
- Load the `rudder-update-spec` skill and review whether this task produced new knowledge worth recording:
591
- - Newly discovered patterns or conventions
592
- - Pitfalls you hit
593
- - New technical decisions
580
+ Load `rudder-update-spec` only when this task adds or changes durable project knowledge:
581
+ - a business rule, workflow, state transition, or acceptance rule that future tasks must follow;
582
+ - an API/DTO/VO, database, permission, transaction, cache, or other cross-layer contract;
583
+ - a reusable implementation pattern, technical convention, or prevention rule;
584
+ - a bug or mismatch showing that the current Spec is incomplete or incorrect.
594
585
 
595
- Update the docs under `.rudder/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment.
586
+ The task's current business requirements always belong in `prd.md`; a one-off page,
587
+ copy, customer campaign, or implementation detail does not require a Spec update.
588
+ If none of these triggers apply, record "no durable Spec change" in the task summary
589
+ and continue without loading the full update-spec skill.
596
590
 
597
591
  #### 3.4 Commit changes `[required · once]`
598
592
 
@@ -664,7 +658,7 @@ All 4 tag blocks live in the `## Phase Index` section above, immediately after e
664
658
  |---|---|
665
659
  | No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
666
660
  | All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
667
- | Phase 2 + Phase 3.1–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
661
+ | Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |
668
662
  | After Phase 3.5 (archived) | `[workflow-state:completed]` (after Phase 3 summary; **currently DEAD**) |
669
663
 
670
664
  ### Changing the per-turn prompt text
@@ -62,6 +62,10 @@ AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK)
62
62
  # All supported agents
63
63
  AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_RESEARCH)
64
64
 
65
+ DEFAULT_MAX_FILE_BYTES = 32768
66
+ DEFAULT_MAX_ARTIFACT_BYTES = 65536
67
+ DEFAULT_MAX_TOTAL_BYTES = 131072
68
+
65
69
 
66
70
  def find_repo_root(start_path: str) -> str | None:
67
71
  """
@@ -136,7 +140,10 @@ def read_file_content(base_path: str, file_path: str) -> str | None:
136
140
  if os.path.exists(full_path) and os.path.isfile(full_path):
137
141
  try:
138
142
  with open(full_path, "r", encoding="utf-8") as f:
139
- return f.read()
143
+ content = f.read()
144
+ # Binary files are not useful prompt context and can explode the
145
+ # payload after replacement decoding.
146
+ return None if "\x00" in content else content
140
147
  except Exception:
141
148
  return None
142
149
  return None
@@ -186,6 +193,71 @@ def read_directory_contents(
186
193
  return results
187
194
 
188
195
 
196
+ def _get_context_limits(repo_root: str) -> dict[str, int]:
197
+ """Read configured limits without making the hook depend on YAML libs."""
198
+ scripts_dir = Path(repo_root) / DIR_WORKFLOW / "scripts"
199
+ if str(scripts_dir) not in sys.path:
200
+ sys.path.insert(0, str(scripts_dir))
201
+ try:
202
+ from common.config import get_context_injection_limits # type: ignore[import-not-found]
203
+
204
+ return get_context_injection_limits(Path(repo_root))
205
+ except Exception:
206
+ return {
207
+ "max_file_bytes": DEFAULT_MAX_FILE_BYTES,
208
+ "max_artifact_bytes": DEFAULT_MAX_ARTIFACT_BYTES,
209
+ "max_total_bytes": DEFAULT_MAX_TOTAL_BYTES,
210
+ }
211
+
212
+
213
+ class _ContextBudget:
214
+ """Track the total UTF-8 bytes emitted into one agent prompt."""
215
+
216
+ def __init__(self, max_total_bytes: int) -> None:
217
+ self.max_total_bytes = max_total_bytes
218
+ self.used = 0
219
+ self.seen: set[str] = set()
220
+
221
+ def add(self, size: int) -> None:
222
+ self.used += size
223
+
224
+ def has_room(self, size: int) -> bool:
225
+ return self.max_total_bytes <= 0 or self.used + size <= self.max_total_bytes
226
+
227
+
228
+ def _truncate_utf8(content: str, max_bytes: int) -> tuple[str, bool]:
229
+ """Truncate text without splitting a UTF-8 sequence."""
230
+ if max_bytes <= 0:
231
+ return content, False
232
+ raw = content.encode("utf-8")
233
+ if len(raw) <= max_bytes:
234
+ return content, False
235
+ return raw[:max_bytes].decode("utf-8", errors="ignore"), True
236
+
237
+
238
+ def _format_context_entry(
239
+ path: str,
240
+ content: str,
241
+ budget: _ContextBudget,
242
+ max_bytes: int,
243
+ ) -> str:
244
+ """Format one entry, degrading to an index line when the budget is full."""
245
+ normalized = str(Path(path).as_posix())
246
+ if normalized in budget.seen:
247
+ return ""
248
+ budget.seen.add(normalized)
249
+ original_size = len(content.encode("utf-8"))
250
+ content, truncated = _truncate_utf8(content, max_bytes)
251
+ if truncated:
252
+ content += f"\n[Rudder: truncated at {max_bytes} bytes; read {path} for full content]"
253
+ block = f"=== {path} ===\n{content}"
254
+ block_size = len(block.encode("utf-8"))
255
+ if not budget.has_room(block_size):
256
+ return f"=== {path} ({original_size} bytes; read on demand) ==="
257
+ budget.add(block_size)
258
+ return block
259
+
260
+
189
261
  def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]:
190
262
  """
191
263
  Read all file/directory contents referenced in jsonl file
@@ -257,7 +329,13 @@ def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]
257
329
 
258
330
 
259
331
 
260
- def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
332
+ def get_agent_context(
333
+ repo_root: str,
334
+ task_dir: str,
335
+ agent_type: str,
336
+ budget: _ContextBudget,
337
+ max_file_bytes: int,
338
+ ) -> str:
261
339
  """
262
340
  Get context from {agent_type}.jsonl for the specified agent.
263
341
  Only reads implement.jsonl or check.jsonl (the two JSONL files the task system creates).
@@ -266,7 +344,9 @@ def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
266
344
 
267
345
  agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
268
346
  for file_path, content in read_jsonl_entries(repo_root, agent_jsonl):
269
- context_parts.append(f"=== {file_path} ===\n{content}")
347
+ formatted = _format_context_entry(file_path, content, budget, max_file_bytes)
348
+ if formatted:
349
+ context_parts.append(formatted)
270
350
 
271
351
  return "\n\n".join(context_parts)
272
352
 
@@ -281,23 +361,39 @@ def get_implement_context(repo_root: str, task_dir: str) -> str:
281
361
  3. info.md (technical design)
282
362
  """
283
363
  context_parts = []
364
+ limits = _get_context_limits(repo_root)
365
+ budget = _ContextBudget(limits["max_total_bytes"])
284
366
 
285
367
  # 1. Read implement.jsonl
286
- base_context = get_agent_context(repo_root, task_dir, "implement")
368
+ base_context = get_agent_context(
369
+ repo_root, task_dir, "implement", budget, limits["max_file_bytes"]
370
+ )
287
371
  if base_context:
288
372
  context_parts.append(base_context)
289
373
 
290
374
  # 2. Requirements document
291
375
  prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
292
376
  if prd_content:
293
- context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
377
+ formatted = _format_context_entry(
378
+ f"{task_dir}/prd.md (Requirements)",
379
+ prd_content,
380
+ budget,
381
+ limits["max_artifact_bytes"],
382
+ )
383
+ if formatted:
384
+ context_parts.append(formatted)
294
385
 
295
386
  # 3. Technical design
296
387
  info_content = read_file_content(repo_root, f"{task_dir}/info.md")
297
388
  if info_content:
298
- context_parts.append(
299
- f"=== {task_dir}/info.md (Technical Design) ===\n{info_content}"
389
+ formatted = _format_context_entry(
390
+ f"{task_dir}/info.md (Technical Design)",
391
+ info_content,
392
+ budget,
393
+ limits["max_artifact_bytes"],
300
394
  )
395
+ if formatted:
396
+ context_parts.append(formatted)
301
397
 
302
398
  return "\n\n".join(context_parts)
303
399
 
@@ -307,13 +403,24 @@ def get_check_context(repo_root: str, task_dir: str) -> str:
307
403
  Context for Check Agent: check.jsonl + prd.md
308
404
  """
309
405
  context_parts = []
406
+ limits = _get_context_limits(repo_root)
407
+ budget = _ContextBudget(limits["max_total_bytes"])
310
408
 
311
409
  for file_path, content in read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl"):
312
- context_parts.append(f"=== {file_path} ===\n{content}")
410
+ formatted = _format_context_entry(file_path, content, budget, limits["max_file_bytes"])
411
+ if formatted:
412
+ context_parts.append(formatted)
313
413
 
314
414
  prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
315
415
  if prd_content:
316
- context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
416
+ formatted = _format_context_entry(
417
+ f"{task_dir}/prd.md (Requirements)",
418
+ prd_content,
419
+ budget,
420
+ limits["max_artifact_bytes"],
421
+ )
422
+ if formatted:
423
+ context_parts.append(formatted)
317
424
 
318
425
  return "\n\n".join(context_parts)
319
426
 
@@ -229,12 +229,41 @@ def _read_rudder_config(root: Path) -> dict:
229
229
  from common.rudder_config import read_rudder_config # type: ignore[import-not-found]
230
230
  except Exception:
231
231
  return {}
232
+
232
233
  try:
233
234
  return read_rudder_config(root)
234
235
  except Exception:
235
236
  return {}
236
237
 
237
238
 
239
+ def _prompt_requests_skip(prompt: object, config: dict) -> bool:
240
+ """Return whether this turn explicitly opts out of Rudder breadcrumbs."""
241
+ if not isinstance(prompt, str):
242
+ return False
243
+ configured = ""
244
+ section = config.get("prompt_injection") if isinstance(config, dict) else None
245
+ if isinstance(section, dict) and isinstance(section.get("skip_keyword"), str):
246
+ configured = section["skip_keyword"].strip()
247
+ keywords = {
248
+ "skip rudder",
249
+ "no task",
250
+ "just do it",
251
+ "don't create a task",
252
+ "do not create a task",
253
+ "跳过 rudder",
254
+ "别走流程",
255
+ "小修一下",
256
+ "直接改",
257
+ "先别建任务",
258
+ }
259
+ if configured:
260
+ keywords.add(configured)
261
+ return any(
262
+ re.search(r"(?<![\w-])" + re.escape(keyword) + r"(?![\w-])", prompt, re.IGNORECASE)
263
+ for keyword in keywords
264
+ )
265
+
266
+
238
267
  def _build_tool_paths_block(root: Path) -> str:
239
268
  """Build <tool-paths> block for per-turn breadcrumb."""
240
269
  try:
@@ -353,9 +382,12 @@ def main() -> int:
353
382
  if root is None:
354
383
  return 0 # not a Rudder project
355
384
 
385
+ config = _read_rudder_config(root)
386
+ if _prompt_requests_skip(data.get("prompt", ""), config):
387
+ return 0
388
+
356
389
  templates = load_breadcrumbs(root)
357
390
  platform = _detect_platform(data)
358
- config = _read_rudder_config(root)
359
391
  task = get_active_task(root, data)
360
392
  if task is None:
361
393
  # No active task — still emit a breadcrumb nudging AI toward
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mengde1231/rudder",
3
- "version": "0.6.1",
3
+ "version": "0.6.20",
4
4
  "description": "AI capabilities grow like ivy — Rudder provides the structure to guide them along a disciplined path",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",