Cline rules

1# Cline Recursive Chain-of-Thought System (CRCT) - Execution Plugin (Worker Focus)
2 
3This Plugin provides detailed instructions and procedures for a Worker instance within
4the Execution phase of the CRCT system. A Worker is invoked by a Dispatcher
5(`execution_dispatcher_plugin.md`) to execute a single `Execution_*` task (or a defined
6step-range of one).
7 
8## Core Concept (Worker Perspective)
9 
10- You are a Worker instance. Your sole focus is the single Execution task assigned by the Dispatcher.
11- You load minimal context: the task file, its parent plan, and the dependency context package.
12- You execute the task step-by-step with pre-action verification, save outputs, and signal
13  completion with `<attempt_completion>`.
14- CRITICAL: You DO NOT manage `.clinerules`, DO NOT mark `project_roadmap.md`, and DO NOT
15  select the next task.
16 
17> **IMPORTANT**
18> - If you have already read a file and have not edited it since, DO NOT read it again.
19> - Do not use tool XML tags in general responses.
20> - Before generating or modifying any code, the dependency context review below is MANDATORY.
21 
22## Entering Execution Phase (Worker Role)
23 
24You are triggered by a message from a Dispatcher instance. Proceed directly to Section I.
25 
26## I. Worker Task Execution
27 
28### Guiding Principles (Worker Focus)
291. **Scoped Task Execution.** Execute only the assigned task/step-range.
302. **Minimal Context Loading.** Load the task, parent plan, context package, and only
31   explicitly required files.
323. **Mandatory Dependency Context.** Before any code modification, load the tracker-backed
33   context package (`build-context`) and confirm understanding of interactions.
344. **Pre-Action Verification.** Before every file modification, verify expected vs actual
35   file state.
365. **WIP Beacon Lifecycle.** Delete beacons whose work is complete; re-anchor unfinished
37   `NEXT:` items as standalone beacons BEFORE deleting the parent.
386. **Dependency Tracker Updates.** If your changes create new functional dependencies,
39   update the relevant mini-tracker with `add-dependency` and state your reasoning.
40 
41### Step W.1: Initialize Worker
421. Parse Dispatcher's message: task path, parent plan path, scope (full task or step-range),
43   revision notes (if any), expected outputs.
442. Load this plugin. Load minimal sections of `activeContext.md` only if directed.
453. `read_file` the task instruction file and the parent plan.
464. Create `Worker_Output_Exec_[TaskName]_[Timestamp].md` in `cline_docs/dispatch_logs/`.
47   Populate the header. If revision notes exist, record them.
485. State: "Worker initialized. Task: `[path]`. Scope: `[scope]`. Revision: `[Yes/No]`."
496. Initial Worker MUP: log initialization in the Worker Output file.
50 
51### Step W.2: Load Execution Context (MANDATORY)
52**Phase A — Resolve Keys:**
53- Determine the key(s) for the target file(s) via `cline_utils/dependency_system/core/state/global_key_map.json`.
54- Confirm keys via `[AUTO] STATION_HEADER` comments when modifying source files.
55- Disambiguate globally duplicated base keys (`KEY#N`).
56 
57**Phase B — Build Context Package (PRIMARY):**
58    python -m cline_utils.dependency_system.dependency_processor build-context \
59      --keys <KEY1>[,<KEY2>...] --output cline_docs/temp_context/{key}_context.md
60 
61**`build-context` Command Reference:**
62 
63| Argument | Required | Purpose |
64|----------|----------|---------|
65| `--keys` | Yes | Comma-separated target keys |
66| `--mode` | No | `auto` (default), `local` (~20k token ceiling), `cloud` (~100k token ceiling) |
67| `--max-tokens` | No | Override budget; clamped to mode ceiling |
68| `--output` | Recommended | Write Markdown package to disk (avoids flooding `execute_command` stdout) |
69 
70**Prerequisites:**
71- Run `analyze-project` first if the global key map is missing (error: `"Global key map not found. Please run analyze-project first."`).
72- Resolve ambiguous keys (`3Ba2#1`) before passing to `--keys`. Directory keys are omitted by the packager — do not use them as targets.
73- Create `cline_docs/temp_context/` if missing. Packages are ephemeral execution artifacts (not changelog entries); cleanup occurs in Consolidation phase.
74 
75**Output format** (what the LLM must parse from the generated package):
76- `# TARGET CORE LOGIC` — full content of target file(s)
77- `# Tier N: ...` — tiered dependencies: `x` (Tier 1) → `<`/`>` (Tier 2) → `d` (Tier 3) → `S` (Tier 4) → `s` (Tier 5)
78- `(Full Content)` vs `(SES Signatures Only)` — full file vs structural/signature fallback
79- Truncation marker: `> Context ceiling of N tokens reached...` — outer-ring deps were dropped
80 
81- `read_file` the generated package.
82- Summarize coverage: which keys loaded as Full Content vs SES Signatures Only vs truncated.
83 
84**Phase C — Fallback Gap Fill:** Trigger when `build-context` errors, truncation omits
85required tier files, the task lists non-tracked context (Strategy docs, plans), or SES-only
86content is insufficient:
87- Run `show-dependencies --key <key>` for affected keys.
88- `read_file` only the missing files.
89- State: "Filling context gaps via show-dependencies + read_file: [paths]."
90 
91Failure to gather required context before modification is HIGH RISK for introducing errors.
92 
93### Step W.3: Execute Task Steps
94For each numbered step in scope:
95 
96**A. Understand the Step.** Clarify the action against the task objective and parent plan.
97 
98**B. Review Dependencies & Context (MANDATORY).** Before generating/modifying code:
99- Complex or multi-file steps: re-run `build-context` if the prior package may be stale.
100- Localized steps: `show-dependencies --key <key>` for quick spot-checks.
101- State: "Confirming understanding of interaction with dependencies `[keys]` before step N."
102 
103**C. Pre-Action Verification (MANDATORY for file modifications).** Re-read target file(s)
104and produce a Chain-of-Thought:
1051. Intended Change. 2. Dependency Context Summary. 3. Expected Current State.
1064. Actual Current State. 5. Validation (proceed only on match). If mismatch: STOP,
107re-evaluate, record in Worker Output file.
108 
109**D. Perform Action.** Use the most token-efficient tool (`insert_content` >
110`search_and_replace`/`apply_diff` > `write_to_file`), per Core Prompt guidelines.
111 
112**E. Document Results (Mini-CoT).** Record: action taken, result, observations, next.
113Append to the Worker Output file.
114 
115**F. WIP Beacon Management:**
116- If the step fully satisfies a `# WIP` (or `# │ WIP:`) beacon: re-anchor any uncompleted
117  `NEXT:` items as standalone beacons at their proper code sites FIRST, then DELETE the
118  parent beacon. Never convert to `DONE:`.
119- Use whitespace/box-drawing-tolerant searches (regex `#\s*│?\s*WIP:`).
120 
121**G. Error Handling.** Document the error and diagnosis (syntax, permissions, dependency
122conflict, logic). Propose and execute a fix. Document the resolution. If the error reveals
123a plan defect beyond your scope, record it in the Worker Output file as a follow-up for the
124Dispatcher rather than expanding scope.
125 
126**H. Code Generation and Modification Guidelines.**
127*(Reminder: Before generating/modifying code, ensure Step W.3.B 'Review Dependencies & Context' including the W.2 context package was performed)*
128When performing actions that involve writing or changing code, adhere strictly to the following:
1291. **Context-Driven**: Code **must** align with the interactions, interfaces, data formats,
130   and requirements identified during dependency review (W.3.B) and pre-action verification (W.3.C).
1312. **Modularity**: Write small, focused functions/methods/classes. Aim for high cohesion and
132   low coupling. Design reusable components to enhance maintainability.
1333. **Clarity and Readability**: Use meaningful names for variables, functions, and classes.
134   Follow language-specific formatting conventions (e.g., PEP 8 for Python). Add comments only
135   for complex logic or intent, avoiding redundant explanations of *what* the code does.
136   Provide complete, runnable code blocks or snippets as appropriate for the task step.
1374. **Error Handling**: Anticipate errors (e.g., invalid inputs, file not found) and implement
138   robust handling (e.g., try-except, return value checks). Validate inputs and assumptions
139   to prevent errors early.
1405. **Efficiency**: Prioritize clarity and correctness but be mindful of algorithmic complexity
141   for performance-critical tasks.
1426. **Documentation**: Add docstrings or comments for public APIs or complex functions, detailing
143   purpose, parameters, and return values. Keep documentation concise and synchronized with code changes.
1447. **Testing**: Write testable code and, where applicable, suggest or include unit tests for
145   new functionality or fixes.
1468. **Dependency Management**: Use existing dependencies where possible. Avoid adding new external
147   libraries unless explicitly planned. If code changes introduce *new functional dependencies*
148   between project files, prepare to update the relevant mini-tracker (see W.4 step 2).
1499. **Security**: Follow secure coding practices to mitigate vulnerabilities (e.g., avoid injection
150   risks, secure credential handling).
15110. **WIP Markings & Lifecycle Protocol (CRITICAL)**: Note that any areas or code blocks that
152    require additional steps, deferred logic, or future modifications **require** a clear,
153    descriptive `# WIP` tag (or `# │ WIP:` box-drawing tag, or language-appropriate comment
154    syntax like `// WIP` or `<!-- WIP -->`) directing to the additional work needed. Reference
155    the `comment-skill` package path defined under `[SKILLS_WORKFLOWS]` in
156    `.clinerules/default-rules.md`.
157    - **Beacon Removal on Completion**: When a task step fully satisfies and verifies the work
158      described in a `# WIP` beacon, **DELETE** the beacon block. Do not convert it to `DONE:`
159      or retain dead comment scaffolding — git commit history records completion.
160    - **NEXT-Item Re-Anchor Rule (MANDATORY)**: Prior to removing any `# WIP` (or `# │ WIP:`)
161      beacon whose `NEXT` field contains uncompleted or follow-up items, the executing agent
162      **MUST** instantiate each remaining item as its own proper, standalone `# WIP` (or
163      `# │ WIP:`) beacon at the specific code site where that work belongs *BEFORE* the parent
164      beacon is deleted. Recording remaining items only in plan files or activeContext is
165      prohibited as it causes information loss.
166      - Each re-anchored beacon must include proper fields per `comment-skill-wip.md`: `INTENT`,
167        `STATUS`, `NEXT` (quoting or detailing the item), `REQUIRES`, `CRCT_PHASE`, and
168        `HDTA_TASK` (or plan reference).
169    - **Grep Syntax Awareness**: Always use whitespace- and box-drawing-tolerant searches
170      (e.g. regex `#\s*│?\s*WIP:`) to avoid missing indented or box-drawing formatted beacons.
171      Anchor on unique beacon prose rather than line numbers.
172 
173### Step W.4: Final Worker MUP & Completion Signal
1741. **Update Task Instruction File:** Mark completed steps `[DONE]`, record observations,
175   update overall status if the full task is complete. Save.
1762. **Update Mini-Trackers (if new functional dependencies):**
177   Use `add-dependency` on the relevant `{module_name}_module.md`. State reasoning:
178       python -m cline_utils.dependency_system.dependency_processor add-dependency \
179         --tracker path/to/module_X_module.md --source-key <A> --target-key <B> --dep-type "<"
1803. **Update Domain Module / Implementation Plan Documents (If Significant):** If the task
181   execution led to a significant design change or outcome not captured in the original plan,
182   briefly note this in the relevant Domain Module (`*_module.md`) or Implementation Plan
183   (`implementation_plan_*.md`). Keep the note concise and synchronized with the actual work done.
1844. **Update Worker Output File:** Final summary — steps completed, files modified,
185   WIP beacon actions, dependency updates applied, follow-ups/child-task requests,
186   status "[x] Completed".
1875. **Final save check:** verify all files saved.
1886. Use `<attempt_completion>` to signal completion.
189 
190CRITICAL FOR WORKER: Worker MUST NOT update `.clinerules[LAST_ACTION_STATE]` and MUST NOT
191mark the roadmap task complete. The Dispatcher verifies and marks completion.
192 
193## II. Quick Reference (Worker Focus)
194 
195**Workflow:** W.1 Initialize (parse message, load task + plan, create Worker Output file)
196→ W.2 Load context (resolve keys → `build-context` → gap fill) → W.3 Execute steps
197(understand → dependencies → pre-action verification → perform → document → WIP lifecycle)
198→ W.4 Final MUP (task file, mini-trackers, Worker Output) → `<attempt_completion>`.
199 
200**Key Outputs:** Modified project files, updated task instruction file, updated
201mini-trackers (when applicable), Worker Output file in `cline_docs/dispatch_logs/`.
202 
203## III. Flowchart (Worker Focus)
204 
205```mermaid
206graph TD
207subgraph Worker Instance
208W_Start(Dispatcher Message) --> W_Init[W.1: Parse task, load plan, create Output file];
209W_Init --> W_Ctx[W.2: build-context package + gap fill];
210W_Ctx --> W_Loop{Steps remaining in scope?};
211W_Loop -- Yes --> W_Verify[Pre-Action Verification];
212W_Verify --> W_Act[Perform Action + Mini-CoT + WIP lifecycle];
213W_Act --> W_Loop;
214W_Loop -- No --> W_MUP[W.4: Update task file, mini-trackers, Output file];
215W_MUP --> W_End[<attempt_completion>];
216end
217```
218 
219## IV. Detailed Execution Flowchart (Step-Level)
220 
221```mermaid
222flowchart TD
223    subgraph Task Selection
224        Start_Exec[Start Execution Phase] --> Load_Roadmap[Load project_roadmap.md]
225        Load_Roadmap --> Find_Next_Task{Find Next Incomplete Task in Sequence}
226        Find_Next_Task -- Task Found --> Load_Task_File[Load Task Instruction File]
227        Find_Next_Task -- No Tasks Left --> End_Phase[Exit Execution Phase]
228    end
229 
230    subgraph Task Execution
231        Load_Task_File --> Load_Context["Load Parent Plan & build-context Package<br>(fallback: show-dependencies + read_file)"]
232        Load_Context --> A[Start Step] --> B[Understand Step]
233        B --> C["Review Dependencies & Context Package<br>MANDATORY"]
234        C --> D{File Modification?}
235        D -- Yes --> E[Pre-Action Verification<br> with Context]
236        D -- No --> G[Perform Action]
237        E -- Match & Valid --> G
238        E -- No Match or Invalid --> F[Re-evaluate Plan/Context]
239        F --> B
240        G --> H[Document Results]
241        H --> I{Error?}
242        I -- Yes --> J[Handle Error]
243        I -- No --> K[MUP]
244        J --> K
245        K --> L{Next Step in Task?}
246        L -- Yes --> A
247        L -- No --> M[End Task - Update Roadmap]
248    end
249    
250    M --> Find_Next_Task
251```
252