@blxzer/cursor-trellis 0.2.7 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/CHANGELOG.md +195 -133
  2. package/README.md +14 -0
  3. package/dist/cli/index.d.ts.map +1 -1
  4. package/dist/cli/index.js +18 -0
  5. package/dist/cli/index.js.map +1 -1
  6. package/dist/commands/init.d.ts.map +1 -1
  7. package/dist/commands/init.js +8 -1
  8. package/dist/commands/init.js.map +1 -1
  9. package/dist/commands/update.d.ts.map +1 -1
  10. package/dist/commands/update.js +4 -0
  11. package/dist/commands/update.js.map +1 -1
  12. package/dist/commands/validate-rules.d.ts +6 -0
  13. package/dist/commands/validate-rules.d.ts.map +1 -0
  14. package/dist/commands/validate-rules.js +33 -0
  15. package/dist/commands/validate-rules.js.map +1 -0
  16. package/dist/configurators/cursor2plus-local.d.ts.map +1 -1
  17. package/dist/configurators/cursor2plus-local.js +2 -1
  18. package/dist/configurators/cursor2plus-local.js.map +1 -1
  19. package/dist/migrations/manifests/0.2.2.json +8 -8
  20. package/dist/migrations/manifests/0.2.4.json +8 -8
  21. package/dist/migrations/manifests/0.2.5.json +8 -8
  22. package/dist/migrations/manifests/0.2.6.json +8 -8
  23. package/dist/migrations/manifests/0.2.7.json +8 -8
  24. package/dist/migrations/manifests/0.2.8.json +9 -0
  25. package/dist/migrations/manifests/0.2.9.json +9 -0
  26. package/dist/templates/common/bundled-skills/smart-search-cli/SKILL.md +7 -8
  27. package/dist/templates/common/bundled-skills/smart-search-cli/references/cli-contract.md +46 -46
  28. package/dist/templates/common/bundled-skills/trellis-cursor2plus-setup/SKILL.md +2 -2
  29. package/dist/templates/common/commands/finish-work.md +12 -0
  30. package/dist/templates/common/skills/check.md +4 -0
  31. package/dist/templates/cursor/agents/trellis-check.md +32 -0
  32. package/dist/templates/cursor/agents/trellis-implement.md +11 -0
  33. package/dist/templates/cursor/agents/trellis-research.md +29 -0
  34. package/dist/templates/cursor/fixtures/expected-rules.d.ts +14 -0
  35. package/dist/templates/cursor/fixtures/expected-rules.d.ts.map +1 -0
  36. package/dist/templates/cursor/fixtures/expected-rules.js +26 -0
  37. package/dist/templates/cursor/fixtures/expected-rules.js.map +1 -0
  38. package/dist/templates/cursor/rules/trellis-subagent-dispatch.mdc +34 -0
  39. package/dist/templates/markdown/spec/guides/execution-strategy.md.txt +42 -42
  40. package/dist/templates/markdown/spec/guides/retrieval-daily-guide.md.txt +12 -0
  41. package/dist/templates/trellis/config/execution-strategy-rules.json +30 -30
  42. package/dist/templates/trellis/local/README.md +61 -37
  43. package/dist/templates/trellis/local/index.d.ts +1 -0
  44. package/dist/templates/trellis/local/index.d.ts.map +1 -1
  45. package/dist/templates/trellis/local/index.js +1 -0
  46. package/dist/templates/trellis/local/index.js.map +1 -1
  47. package/dist/templates/trellis/local/patch_wpelc8.py +162 -38
  48. package/dist/templates/trellis/local/smoke.py +94 -0
  49. package/dist/templates/trellis/scripts/common/codebase_retrieval_router.py +2 -2
  50. package/dist/templates/trellis/scripts/common/cursor_retrieval_env.py +16 -2
  51. package/dist/templates/trellis/scripts/common/execution_strategy.py +267 -267
  52. package/dist/templates/trellis/scripts/common/retrieval_agent_instructions.py +26 -7
  53. package/dist/templates/trellis/scripts/common/semantic_plan_gate.py +18 -4
  54. package/dist/templates/trellis/scripts/common/smart_search_evidence.py +33 -1
  55. package/dist/templates/trellis/scripts/task.py +12 -0
  56. package/dist/utils/codebase-retrieval-router.js +2 -2
  57. package/dist/utils/codebase-retrieval-router.js.map +1 -1
  58. package/dist/utils/cursor-retrieval-env.d.ts +2 -0
  59. package/dist/utils/cursor-retrieval-env.d.ts.map +1 -1
  60. package/dist/utils/cursor-retrieval-env.js +11 -2
  61. package/dist/utils/cursor-retrieval-env.js.map +1 -1
  62. package/dist/utils/mirror-check.d.ts +22 -0
  63. package/dist/utils/mirror-check.d.ts.map +1 -0
  64. package/dist/utils/mirror-check.js +90 -0
  65. package/dist/utils/mirror-check.js.map +1 -0
  66. package/dist/utils/normalize-text.d.ts +7 -0
  67. package/dist/utils/normalize-text.d.ts.map +1 -0
  68. package/dist/utils/normalize-text.js +16 -0
  69. package/dist/utils/normalize-text.js.map +1 -0
  70. package/dist/utils/retrieval-agent-instructions.d.ts.map +1 -1
  71. package/dist/utils/retrieval-agent-instructions.js +14 -7
  72. package/dist/utils/retrieval-agent-instructions.js.map +1 -1
  73. package/dist/utils/retrieval-execution-telemetry.d.ts +12 -3
  74. package/dist/utils/retrieval-execution-telemetry.d.ts.map +1 -1
  75. package/dist/utils/retrieval-execution-telemetry.js +37 -1
  76. package/dist/utils/retrieval-execution-telemetry.js.map +1 -1
  77. package/dist/utils/retrieval-tool-classification.d.ts +2 -0
  78. package/dist/utils/retrieval-tool-classification.d.ts.map +1 -1
  79. package/dist/utils/retrieval-tool-classification.js +13 -0
  80. package/dist/utils/retrieval-tool-classification.js.map +1 -1
  81. package/dist/utils/semantic-plan-gate.d.ts.map +1 -1
  82. package/dist/utils/semantic-plan-gate.js +11 -4
  83. package/dist/utils/semantic-plan-gate.js.map +1 -1
  84. package/dist/utils/validate-rules.d.ts +21 -0
  85. package/dist/utils/validate-rules.d.ts.map +1 -0
  86. package/dist/utils/validate-rules.js +88 -0
  87. package/dist/utils/validate-rules.js.map +1 -0
  88. package/package.json +4 -3
@@ -3,6 +3,17 @@ name: trellis-research
3
3
  description: Trellis research agent. Use this exact agent for Trellis task research and research/ persistence. Do not use generic/default/generalPurpose agents for Trellis research.
4
4
  tools: Read, Write, Glob, Grep, Bash, WebSearch, WebFetch, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
5
5
  ---
6
+
7
+ ## Entry points
8
+
9
+ - **Agent session:** Open this agent file manually in a new chat — context from this file + your main-session prompt.
10
+ - **Task dispatch:** Run `python ./.trellis/scripts/generate_dispatch_prompt.py --agent research` → pass stdout as `Task(..., prompt=...)` — context from the Layer 2 prompt.
11
+
12
+ ## Context source
13
+
14
+ - **Layer 2 prompt = PRIMARY (guaranteed)** — always generate via CLI before `Task(trellis-research)`.
15
+ - **Hook `additional_context` = best-effort only** — Cursor #158452: not guaranteed to reach the model; optimization / fallback only.
16
+
6
17
  # Research Agent
7
18
 
8
19
  You are the Research Agent in the Trellis workflow.
@@ -55,6 +66,24 @@ Classify: internal / external / mixed. Determine scope (global / specific direct
55
66
 
56
67
  Run independent searches in parallel (Glob + Grep + smart-search CLI for external topics) for efficiency.
57
68
 
69
+ #### External search — provider relevance caveats
70
+
71
+ - **Context7** and generic third-party library docs are often **irrelevant** to Trellis/Cursor platform questions. Prefer **Cursor / Cursor++ official documentation**, `docs.cursor.com`, and **local `.trellis/spec/`** before trusting Context7 hits.
72
+ - Every smart-search result you persist must **label the provider source** (e.g. `exa`, `context7`, `cursor-docs`, `tavily`) in the research file — in frontmatter or per bullet — so downstream check/finish can audit provenance.
73
+ - Trellis harness facts: `./.trellis/scripts/run_smart_search.py` writes manifests under `{TASK}/research/smart-search/<run-id>/`; scored pack output (when built) is `{TASK}/research/retrieval-pack-latest.json`.
74
+
75
+ #### External search — manual query refinement
76
+
77
+ When the first smart-search pass returns irrelevant results, **refine before falling back** to Cursor web tools:
78
+
79
+ 1. Add site scope: `site:cursor.com`, `site:docs.cursor.com`, or `site:github.com/cursor-ide`
80
+ 2. Add product scope: `+Trellis`, `+cursor-trellis`, or the exact API/hook name
81
+ 3. Switch route: `--intent official-source --include-domain cursor.com` or `--intent docs` for API reference
82
+ 4. Narrow time or topic: shorter query, version number, or feature name from local spec
83
+ 5. Re-run: `python ./.trellis/scripts/run_smart_search.py "<refined query>" --intent deep-research --json`
84
+
85
+ Only use Cursor WebSearch/WebFetch when smart-search is unavailable (`not_configured` / `failed` / timeout) — then persist with `source: cursor-web-fallback`.
86
+
58
87
  ### Step 4: Persist Each Topic
59
88
 
60
89
  For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Expected Cursor rules manifest for validate-rules hard gate.
3
+ * Update alongside rule content changes in templates/cursor/rules/.
4
+ */
5
+ export interface ExpectedRule {
6
+ /** Filename including .mdc extension, e.g. "trellis-triage.mdc" */
7
+ filename: string;
8
+ /** Substrings that must appear in rule body (case-sensitive) */
9
+ requiredSections: string[];
10
+ /** Minimum byte length of normalized rule content */
11
+ minBytes: number;
12
+ }
13
+ export declare const expectedRules: ExpectedRule[];
14
+ //# sourceMappingURL=expected-rules.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"expected-rules.d.ts","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,YAAY,EAoBvC,CAAC"}
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Expected Cursor rules manifest for validate-rules hard gate.
3
+ * Update alongside rule content changes in templates/cursor/rules/.
4
+ */
5
+ export const expectedRules = [
6
+ {
7
+ filename: "trellis-triage.mdc",
8
+ requiredSections: [
9
+ "Decision tree",
10
+ "Classification mark",
11
+ "Consent gate",
12
+ ],
13
+ minBytes: 500,
14
+ },
15
+ {
16
+ filename: "trellis-subagent-dispatch.mdc",
17
+ requiredSections: ["Layer 2", "generate_dispatch_prompt", "CLI"],
18
+ minBytes: 400,
19
+ },
20
+ {
21
+ filename: "retrieval-routing.mdc",
22
+ requiredSections: ["Native", "BYOK", "codegraph", "smart-search"],
23
+ minBytes: 600,
24
+ },
25
+ ];
26
+ //# sourceMappingURL=expected-rules.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"expected-rules.js","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C;QACE,QAAQ,EAAE,oBAAoB;QAC9B,gBAAgB,EAAE;YAChB,eAAe;YACf,qBAAqB;YACrB,cAAc;SACf;QACD,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,+BAA+B;QACzC,gBAAgB,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,CAAC;QAChE,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,uBAAuB;QACjC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC;QACjE,QAAQ,EAAE,GAAG;KACd;CACF,CAAC"}
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: "Trellis subagent dispatch — generate dispatch prompt via CLI before Task tool (hook injection is broken in Cursor 3.8.22; this rule is the D-1 workaround)"
3
+ alwaysApply: true
4
+ ---
5
+
6
+ # Trellis Subagent Dispatch (CLI Layer 2 — MANDATORY)
7
+
8
+ **CLI Layer 2 is the primary Cursor path.** The `preToolUse` hook does NOT fire for the Task tool in Cursor 3.8.22. Agent definition body does NOT enter subagent system prompt. The ONLY reliable context channel is the `Task` tool's `prompt` parameter.
9
+
10
+ ## Rule
11
+
12
+ Before calling `Task(subagent_type="trellis-research|trellis-implement|trellis-check", ...)` you MUST:
13
+
14
+ 1. Generate a complete dispatch prompt via CLI:
15
+
16
+ ```powershell
17
+ python ./.trellis/scripts/generate_dispatch_prompt.py --agent <research|implement|check> --task "<task-path>" --repo-root "<repo-root>"
18
+ ```
19
+
20
+ 2. Use the CLI output as the `prompt` parameter value for `Task(...)`.
21
+
22
+ 3. Append any additional user instructions AFTER the generated prompt, separated by `\n\n---\n\n`.
23
+
24
+ ## Why
25
+
26
+ The generated prompt carries role identity ("You are the Trellis Research/Implement/Check Agent"), write scope constraints, recursion guard, and dynamic context (prd.md, design.md, implement.md, spec tree, jsonl files). Without this, the subagent receives only a bare user instruction with no Trellis context.
27
+
28
+ ## Auto-detection
29
+
30
+ If `--task` is omitted, the script resolves the currently selected task. If `--repo-root` is omitted, it auto-detects via `.trellis` or `.git` upward search.
31
+
32
+ ## Exception
33
+
34
+ This rule does NOT apply to `generalPurpose`, `explore`, `shell`, or other non-Trellis subagent types. Only `trellis-research`, `trellis-implement`, `trellis-check` require CLI-generated prompts.
@@ -1,43 +1,43 @@
1
- # Execution strategy (execution_mode / isolation)
2
-
3
- > **Purpose**: Suggest a Development Strategy Contract before you freeze `implement.md`, and align Phase 2 dispatch with the approved contract.
4
-
5
- ---
6
-
7
- ## Two orthogonal dimensions
8
-
9
- | Field | Question |
10
- | --- | --- |
11
- | `execution_mode` | **Who** implements and checks? (`inline` main session, `worker` trellis-implement/check agents, `child-task` Child worker) |
12
- | `isolation` | **Where** are files edited? (`main-worktree` vs `git-worktree` for Child) |
13
-
14
- Non-git repo roots do **not** force `inline` for code Full tasks; they only affect whether `git-worktree` / `prepare-child-worktree` is recommended.
15
-
16
- ## Suggest (planning)
17
-
18
- ```bash
19
- python3 ./.trellis/scripts/task.py suggest-execution-strategy <task-dir>
20
- python3 ./.trellis/scripts/task.py suggest-execution-strategy <task-dir> --json
21
- ```
22
-
23
- Run during brainstorm / before finalizing the YAML block in `implement.md`. Reconcile suggestion with product intent; the contract in `implement.md` is authoritative after approval.
24
-
25
- ## Default policy (v1)
26
-
27
- | Profile / signal | Suggested `execution_mode` | Suggested `isolation` |
28
- | --- | --- | --- |
29
- | Lite | (no contract) | — |
30
- | Full + touches code | `worker` | `main-worktree` |
31
- | Full + doc-only capabilities | `inline` | `main-worktree` |
32
- | Parent / has children | `inline` | `main-worktree` |
33
- | Child (`task.json` parent set) | `child-task` | `git-worktree` when git package root resolves; else `main-worktree` + WARN |
34
-
35
- `touches_code` is deterministic: code `optional_capabilities`, `package`/`scope` path segments (`src`, `packages`, `scripts`, …), or Full with `design.md` and non-doc-only capabilities. Rules live in `.trellis/config/execution-strategy-rules.json`.
36
-
37
- ## Drift warning (preflight)
38
-
39
- `task.py start-execution <task> --check` prints `[execution-strategy] WARN` when the approved contract differs from a fresh suggestion. **Advisory only** — does not fail the gate.
40
-
41
- ## Phase 2 alignment
42
-
1
+ # Execution strategy (execution_mode / isolation)
2
+
3
+ > **Purpose**: Suggest a Development Strategy Contract before you freeze `implement.md`, and align Phase 2 dispatch with the approved contract.
4
+
5
+ ---
6
+
7
+ ## Two orthogonal dimensions
8
+
9
+ | Field | Question |
10
+ | --- | --- |
11
+ | `execution_mode` | **Who** implements and checks? (`inline` main session, `worker` trellis-implement/check agents, `child-task` Child worker) |
12
+ | `isolation` | **Where** are files edited? (`main-worktree` vs `git-worktree` for Child) |
13
+
14
+ Non-git repo roots do **not** force `inline` for code Full tasks; they only affect whether `git-worktree` / `prepare-child-worktree` is recommended.
15
+
16
+ ## Suggest (planning)
17
+
18
+ ```bash
19
+ python3 ./.trellis/scripts/task.py suggest-execution-strategy <task-dir>
20
+ python3 ./.trellis/scripts/task.py suggest-execution-strategy <task-dir> --json
21
+ ```
22
+
23
+ Run during brainstorm / before finalizing the YAML block in `implement.md`. Reconcile suggestion with product intent; the contract in `implement.md` is authoritative after approval.
24
+
25
+ ## Default policy (v1)
26
+
27
+ | Profile / signal | Suggested `execution_mode` | Suggested `isolation` |
28
+ | --- | --- | --- |
29
+ | Lite | (no contract) | — |
30
+ | Full + touches code | `worker` | `main-worktree` |
31
+ | Full + doc-only capabilities | `inline` | `main-worktree` |
32
+ | Parent / has children | `inline` | `main-worktree` |
33
+ | Child (`task.json` parent set) | `child-task` | `git-worktree` when git package root resolves; else `main-worktree` + WARN |
34
+
35
+ `touches_code` is deterministic: code `optional_capabilities`, `package`/`scope` path segments (`src`, `packages`, `scripts`, …), or Full with `design.md` and non-doc-only capabilities. Rules live in `.trellis/config/execution-strategy-rules.json`.
36
+
37
+ ## Drift warning (preflight)
38
+
39
+ `task.py start-execution <task> --check` prints `[execution-strategy] WARN` when the approved contract differs from a fresh suggestion. **Advisory only** — does not fail the gate.
40
+
41
+ ## Phase 2 alignment
42
+
43
43
  See `workflow.md` Phase 2.1 / 2.2 tables: spawn `trellis-implement` / `trellis-check` only when `execution_mode: worker`.
@@ -78,6 +78,18 @@ When `smart-search doctor` is not ok or `run_smart_search.py` status is `not_con
78
78
 
79
79
  **CLI discovery (Cursor):** `TRELLIS_SMART_SEARCH_COMMAND` / `smart_search.command` → PATH `smart-search` → project `node_modules/.bin/smart-search` (when installed as a dependency). Agent entrypoint is always `./.trellis/scripts/run_smart_search.py`.
80
80
 
81
+ **Research flags (smart-search ≥ 0.1.15):** pass through `run_smart_search.py` for `--intent deep-research`:
82
+
83
+ | Flag | Values | Use |
84
+ | --- | --- | --- |
85
+ | `--locale-scope` | `cn`, `en`, `both` (CLI default) | Skip bilingual discovery when cost matters |
86
+ | `--dry-run` | flag | Plan + routing preview only; no live providers |
87
+ | `--progress` | flag | `[research]` stage logs to stderr |
88
+
89
+ Research JSON may include `output_schema_version: 1` and structured `citations` (`id`, `source_type`, `verified`, `content_len`). Trellis manifests preserve those fields when present.
90
+
91
+ **Cursor skill surface:** `smart-search-cli` is an internal workflow name — it is **not** installed under `.cursor/skills/` (commands-only policy). On Cursor, follow this guide + `run_smart_search.py`; bundled skill assets ship for Codex/Gemini via `.agents/skills/` only.
92
+
81
93
  ## Router vs execution
82
94
 
83
95
  `route_codebase_retrieval.py` returns **intent + route suggestions** and **`agentInstructions`** (numbered steps with Cursor-native tool names). **codebase-evidence** is **candidate** until confirmed by Read/Git/tests.
@@ -1,31 +1,31 @@
1
- {
2
- "version": 1,
3
- "doc_only_capabilities": [
4
- "markdown-documentation"
5
- ],
6
- "code_capabilities": [
7
- "cli-templates",
8
- "python-task-scripts",
9
- "vitest-integration",
10
- "typescript",
11
- "python"
12
- ],
13
- "code_path_segments": [
14
- "src",
15
- "packages",
16
- "scripts",
17
- "lib"
18
- ],
19
- "pair_warnings": [
20
- {
21
- "execution_mode": "worker",
22
- "isolation": "git-worktree",
23
- "message": "worker usually runs in main-worktree; git-worktree is rare for trellis-implement"
24
- },
25
- {
26
- "execution_mode": "inline",
27
- "isolation": "git-worktree",
28
- "message": "inline + git-worktree is unusual; consider child-task if isolation is intentional"
29
- }
30
- ]
1
+ {
2
+ "version": 1,
3
+ "doc_only_capabilities": [
4
+ "markdown-documentation"
5
+ ],
6
+ "code_capabilities": [
7
+ "cli-templates",
8
+ "python-task-scripts",
9
+ "vitest-integration",
10
+ "typescript",
11
+ "python"
12
+ ],
13
+ "code_path_segments": [
14
+ "src",
15
+ "packages",
16
+ "scripts",
17
+ "lib"
18
+ ],
19
+ "pair_warnings": [
20
+ {
21
+ "execution_mode": "worker",
22
+ "isolation": "git-worktree",
23
+ "message": "worker usually runs in main-worktree; git-worktree is rare for trellis-implement"
24
+ },
25
+ {
26
+ "execution_mode": "inline",
27
+ "isolation": "git-worktree",
28
+ "message": "inline + git-worktree is unusual; consider child-task if isolation is intentional"
29
+ }
30
+ ]
31
31
  }
@@ -1,59 +1,83 @@
1
- # Cursor++ BYOK — Trellis subagent model routing
1
+ # Cursor++ Local Bundle
2
2
 
3
- **Who needs this:** Cursor IDE with [Cursor++](https://ccursor.cometix.dev) (BYOK proxy). **Native Cursor API users can ignore this directory.**
3
+ > **Native Cursor users:** safe to ignore or delete this directory unless using **Cursor++ BYOK**.
4
4
 
5
- ## Agent-led setup (recommended)
5
+ **Who needs this:** Cursor IDE with [Cursor++](https://ccursor.cometix.dev) (BYOK proxy). Method 2.5 patches the `WPeLc8` resolver so Trellis Task subagents get per-role BYOK slugs instead of inheriting the parent model.
6
6
 
7
- In **Cursor Agent**, run skill **`trellis-cursor2plus-setup`** (after `trellis init` with Cursor, or anytime `providers.json` changes). The agent lists models, writes commented **`~/.ccursor/trellis-task-models.json5`** with **primary** and **fallback** per role, runs `patch_wpelc8.py`, and reports WARN/ERROR from the resolver.
7
+ ## Bundle files
8
8
 
9
- Copy `../trellis-task-models.json5.example` only if you prefer a manual starting point.
9
+ | File | Purpose |
10
+ |------|---------|
11
+ | `patch_wpelc8.py` | Operator CLI: dry-run map, compat check, apply (with `--approve`), revert |
12
+ | `smoke.py` | Health smoke: env, patch status, configured roles (no secret reads) |
13
+ | `trellis_task_models_config.py` | JSON5 + providers catalog resolver (used by patch) |
14
+ | `config.local.json.example` | Optional paths (`extensionJs`, `ccursorHome`, …) |
15
+ | `config.local.json` | Your local paths (gitignored; never commit secrets) |
10
16
 
11
- ## What to put in `trellis-task-models.json5`
17
+ User-wide model doc: `~/.ccursor/trellis-task-models.json5` (see `../trellis-task-models.json5.example`). Project override: `../subagent-models.json` (optional).
12
18
 
13
- | JSON key (under `models`) | Meaning |
14
- |-----------------|--------|
15
- | `trellis-research` | Trellis research Task subagent |
16
- | `trellis-implement` | Trellis implement (+ Parent/Child default Task) |
17
- | `trellis-check` | Trellis check Task subagent |
18
- | `generalPurpose` / `shell` / `best-of-n-runner` | Cursor built-in Task types |
19
+ ## Compatibility window
19
20
 
20
- Each role: `{ "primary": "<name>", "fallback": "<name>" }`. **Names:** use **apiModel** or **displayName** from Cursor++ (not `model-xxxxx` unless you want to). Patch time resolves against `providers.json`; missing primary → WARN + fallback; ERROR only if both fail.
21
+ - **Verified:** Cursor **3.7.27** / Cursor++ **v0.0.11** (see `.trellis/spec/guides/cursor-subagent-policy.md`, 2026-06-18)
22
+ - **Re-verify** after any Cursor or Cursor++ upgrade: `python patch_wpelc8.py --check-compat`
23
+ - If `--check-compat` reports `fail` or `unknown`, treat the patch as stale until you re-apply or revert
21
24
 
22
- ```bash
23
- python patch_wpelc8.py --explain # key meanings
24
- python patch_wpelc8.py --list-models # current catalog from providers.json
25
- ```
26
-
27
- **Explore** is not in this file — use the Cursor++ panel.
25
+ ## Method 2.5 workflow
28
26
 
29
- ## When Cursor++ models change
27
+ 1. **Dry-run map** `python patch_wpelc8.py --print-map` (no file writes)
28
+ 2. **Operator approval** — review map and compat output; decide to proceed
29
+ 3. **Apply** — `python patch_wpelc8.py --apply --approve` (writes `extension.js`)
30
+ 4. **Reload Cursor** — Developer: Reload Window (once per apply/revert)
31
+ 5. **A ≠ B probe** — parent chat model must differ from a patched subagent map target; dispatch a `trellis-*` Task and confirm the subagent self-reports the **map target** slug/model, not the parent
32
+ 6. **Revert if needed** — `python patch_wpelc8.py --revert` then Reload Window
30
33
 
31
- `providers.json` is the live catalog. Slugs (`model-xxxxx`) can change when you add/remove models in Cursor++.
34
+ Agent-led setup: run skill **`trellis-cursor2plus-setup`** in Cursor Agent (lists models, writes JSON5, runs patch steps).
32
35
 
33
- 1. Re-run skill **`trellis-cursor2plus-setup`**, or `python patch_wpelc8.py --list-models` and fix JSON5
34
- 2. `python patch_wpelc8.py` → Reload Window only if you had not patched yet or reverted
36
+ ## Revert recipe
35
37
 
36
- You may **omit** keys for Task types you never use.
38
+ ```bash
39
+ cd .trellis/local/cursor2plus
40
+ python patch_wpelc8.py --revert
41
+ ```
37
42
 
38
- ## Two-layer JSON (project overrides user)
43
+ Then **Developer: Reload Window**. Subagents return to **inherit parent** BYOK model. Re-apply only after `--check-compat` is `ok` and you have explicit `--approve`.
39
44
 
40
- | File | Scope |
41
- |------|--------|
42
- | `~/.ccursor/trellis-task-models.json5` (or `.json`) | User — all repos |
43
- | `{repo}/.trellis/local/subagent-models.json` | Project overrides (optional) |
45
+ ## A B verification recipe
44
46
 
45
- ## Paths
47
+ Goal: prove the patch routes **subagent** model independently of the **parent** session model.
46
48
 
47
- `providers.json` default: `~/.ccursor/providers.json`. Override: `config.local.json` `providersJson`, or env `TRELLIS_CCURSOR_PROVIDERS`.
49
+ 1. Set parent chat to model **A** (any BYOK model in Cursor++).
50
+ 2. Ensure `trellis-task-models.json5` maps e.g. `trellis-implement` to model **B** (`primary`/`fallback` resolving to a different slug than A).
51
+ 3. `python patch_wpelc8.py --print-map` — note the slug for `trellis-implement` (= map target **B**).
52
+ 4. `python patch_wpelc8.py --apply --approve` → Reload Window.
53
+ 5. Dispatch a `trellis-implement` Task from a parent on model **A**.
54
+ 6. **Pass:** subagent self-report / trace shows **B** (map target), not **A**.
55
+ 7. **Fail:** subagent shows **A** → patch stale or not applied; run `--check-compat`, re-patch, or `--revert`.
48
56
 
49
- ## Apply / revert
57
+ ## CLI reference
50
58
 
51
59
  ```bash
52
- cd .trellis/local/cursor2plus
53
- python patch_wpelc8.py --print-map
54
- python patch_wpelc8.py
60
+ python patch_wpelc8.py --print-map # dry-run slug map
61
+ python patch_wpelc8.py --check-compat # WPeLc8 locatability (no writes)
62
+ python patch_wpelc8.py --apply --approve # write patch (requires --approve)
63
+ python patch_wpelc8.py --apply --dry-run # validate without write
64
+ python patch_wpelc8.py --revert # remove patch
65
+ python patch_wpelc8.py --explain # JSON5 key meanings
66
+ python patch_wpelc8.py --list-models # catalog from providers.json
67
+ python smoke.py # env + patch_status smoke
55
68
  ```
56
69
 
57
- **Developer: Reload Window** after patch.
70
+ `--apply` without `--approve` **refuses** and exits non-zero.
71
+
72
+ ## What to put in `trellis-task-models.json5`
73
+
74
+ | JSON key (under `models`) | Meaning |
75
+ |---------------------------|---------|
76
+ | `trellis-research` | Trellis research Task subagent |
77
+ | `trellis-implement` | Trellis implement (+ Parent/Child default Task) |
78
+ | `trellis-check` | Trellis check Task subagent |
79
+ | `generalPurpose` / `shell` / `best-of-n-runner` | Cursor built-in Task types |
80
+
81
+ Each role: `{ "primary": "<name>", "fallback": "<name>" }`. Names: **apiModel** or **displayName** from Cursor++ (`--list-models`). **Explore** is not in this file — use the Cursor++ panel.
58
82
 
59
- Policy: `.trellis/spec/guides/cursor-subagent-policy.md` (Method 2.5 / 2.6).
83
+ Policy: `.trellis/spec/guides/cursor-subagent-policy.md` (Method 2.5 / 2.6).
@@ -1,5 +1,6 @@
1
1
  export declare const cursor2plusPatchScript: string;
2
2
  export declare const cursor2plusReadme: string;
3
+ export declare const cursor2plusSmokeScript: string;
3
4
  export declare const cursor2plusConfigExample: string;
4
5
  export declare const subagentModelsExample: string;
5
6
  export declare const trellisTaskModelsJson5Example: string;
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AACxD,eAAO,MAAM,wBAAwB,QAAyC,CAAC;AAC/E,eAAO,MAAM,qBAAqB,QAA4C,CAAC;AAC/E,eAAO,MAAM,6BAA6B,QAEzC,CAAC;AACF,eAAO,MAAM,yBAAyB,QAA6C,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AACxD,eAAO,MAAM,sBAAsB,QAAwB,CAAC;AAC5D,eAAO,MAAM,wBAAwB,QAAyC,CAAC;AAC/E,eAAO,MAAM,qBAAqB,QAA4C,CAAC;AAC/E,eAAO,MAAM,6BAA6B,QAEzC,CAAC;AACF,eAAO,MAAM,yBAAyB,QAA6C,CAAC"}
@@ -7,6 +7,7 @@ function readLocal(name) {
7
7
  }
8
8
  export const cursor2plusPatchScript = readLocal("patch_wpelc8.py");
9
9
  export const cursor2plusReadme = readLocal("README.md");
10
+ export const cursor2plusSmokeScript = readLocal("smoke.py");
10
11
  export const cursor2plusConfigExample = readLocal("config.local.json.example");
11
12
  export const subagentModelsExample = readLocal("subagent-models.json.example");
12
13
  export const trellisTaskModelsJson5Example = readLocal("trellis-task-models.json5.example");
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,iBAAiB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC,2BAA2B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAS,CACpD,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC,+BAA+B,CAAC,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,iBAAiB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC,2BAA2B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAS,CACpD,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC,+BAA+B,CAAC,CAAC"}