From 33a8d9dc118a53a35cd15e0e6e44b3592f58ac4f Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Tue, 31 Mar 2026 14:43:41 -0700 Subject: [PATCH] fix(ce-plan, ce-brainstorm): enforce repo-relative paths in generated documents (#473) Co-authored-by: Claude Opus 4.6 (1M context) --- .../agents/research/repo-research-analyst.md | 2 +- plugins/compound-engineering/skills/ce-brainstorm/SKILL.md | 3 +++ plugins/compound-engineering/skills/ce-plan/SKILL.md | 7 +++++-- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/plugins/compound-engineering/agents/research/repo-research-analyst.md b/plugins/compound-engineering/agents/research/repo-research-analyst.md index e7ffb00..b85b527 100644 --- a/plugins/compound-engineering/agents/research/repo-research-analyst.md +++ b/plugins/compound-engineering/agents/research/repo-research-analyst.md @@ -270,7 +270,7 @@ Structure your findings as: - Distinguish between official guidelines and observed patterns - Note the recency of documentation (check last update dates) - Flag any contradictions or outdated information -- Provide specific file paths and examples to support findings +- Provide specific file paths (repo-relative, never absolute) and examples to support findings **Tool Selection:** Use native file-search/glob (e.g., `Glob`), content-search (e.g., `Grep`), and file-read (e.g., `Read`) tools for repository exploration. Only use shell for commands with no native equivalent (e.g., `ast-grep`), one command at a time. diff --git a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md index eef82c1..53f8db2 100644 --- a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md +++ b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md @@ -14,6 +14,8 @@ The durable output of this workflow is a **requirements document**. In other wor This skill does not implement code. It explores, clarifies, and documents decisions for later planning or execution. +**IMPORTANT: All file references in generated documents must use repo-relative paths (e.g., `src/models/user.rb`), never absolute paths. Absolute paths break portability across machines, worktrees, and teammates.** + ## Core Principles 1. **Assess scope first** - Match the amount of ceremony to the size and ambiguity of the work. @@ -33,6 +35,7 @@ This skill does not implement code. It explores, clarifies, and documents decisi ## Output Guidance - **Keep outputs concise** - Prefer short sections, brief bullets, and only enough detail to support the next decision. +- **Use repo-relative paths** - When referencing files, use paths relative to the repo root (e.g., `src/models/user.rb`), never absolute paths. Absolute paths make documents non-portable across machines and teammates. ## Feature Description diff --git a/plugins/compound-engineering/skills/ce-plan/SKILL.md b/plugins/compound-engineering/skills/ce-plan/SKILL.md index 847e35f..a5cc624 100644 --- a/plugins/compound-engineering/skills/ce-plan/SKILL.md +++ b/plugins/compound-engineering/skills/ce-plan/SKILL.md @@ -26,6 +26,8 @@ Ask one question at a time. Prefer a concise single-select choice when natural o Do not proceed until you have a clear planning input. +**IMPORTANT: All file references in the plan document must use repo-relative paths (e.g., `src/models/user.rb`), never absolute paths (e.g., `/Users/name/Code/project/src/models/user.rb`). This applies everywhere — implementation unit file lists, pattern references, origin document links, and prose mentions. Absolute paths break portability across machines, worktrees, and teammates.** + ## Core Principles 1. **Use requirements as the source of truth** - If `ce:brainstorm` produced a requirements document, planning should build from it rather than re-inventing behavior. @@ -41,7 +43,7 @@ Do not proceed until you have a clear planning input. Every plan should contain: - A clear problem frame and scope boundary - Concrete requirements traceability back to the request or origin document -- Exact file paths for the work being proposed +- Repo-relative file paths for the work being proposed (never absolute paths — see Planning Rules) - Explicit test file paths for feature-bearing implementation units - Decisions with rationale, not just tasks - Existing patterns or code references to follow @@ -335,7 +337,7 @@ For each unit, include: - **Goal** - what this unit accomplishes - **Requirements** - which requirements or success criteria it advances - **Dependencies** - what must exist first -- **Files** - exact file paths to create, modify, or test +- **Files** - repo-relative file paths to create, modify, or test (never absolute paths) - **Approach** - key decisions, data flow, component boundaries, or integration notes - **Execution note** - optional, only when the unit benefits from a non-default execution posture such as test-first, characterization-first, or external delegation - **Technical design** - optional pseudo-code or diagram when the unit's approach is non-obvious and prose alone would leave it ambiguous. Frame explicitly as directional guidance, not implementation specification @@ -573,6 +575,7 @@ For larger `Deep` plans, extend the core template only when useful with sections #### 4.3 Planning Rules +- **All file paths must be repo-relative** — never use absolute paths like `/Users/name/Code/project/src/file.ts`. Use `src/file.ts` instead. Absolute paths make plans non-portable across machines, worktrees, and teammates. When a plan targets a different repo than the document's home, state the target repo once at the top of the plan (e.g., `**Target repo:** my-other-project`) and use repo-relative paths throughout - Prefer path plus class/component/pattern references over brittle line numbers - Keep implementation units checkable with `- [ ]` syntax for progress tracking - Do not include implementation code — no imports, exact method signatures, or framework-specific syntax