@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.
- package/CHANGELOG.md +195 -133
- package/README.md +14 -0
- package/dist/cli/index.d.ts.map +1 -1
- package/dist/cli/index.js +18 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +8 -1
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/update.d.ts.map +1 -1
- package/dist/commands/update.js +4 -0
- package/dist/commands/update.js.map +1 -1
- package/dist/commands/validate-rules.d.ts +6 -0
- package/dist/commands/validate-rules.d.ts.map +1 -0
- package/dist/commands/validate-rules.js +33 -0
- package/dist/commands/validate-rules.js.map +1 -0
- package/dist/configurators/cursor2plus-local.d.ts.map +1 -1
- package/dist/configurators/cursor2plus-local.js +2 -1
- package/dist/configurators/cursor2plus-local.js.map +1 -1
- package/dist/migrations/manifests/0.2.2.json +8 -8
- package/dist/migrations/manifests/0.2.4.json +8 -8
- package/dist/migrations/manifests/0.2.5.json +8 -8
- package/dist/migrations/manifests/0.2.6.json +8 -8
- package/dist/migrations/manifests/0.2.7.json +8 -8
- package/dist/migrations/manifests/0.2.8.json +9 -0
- package/dist/migrations/manifests/0.2.9.json +9 -0
- package/dist/templates/common/bundled-skills/smart-search-cli/SKILL.md +7 -8
- package/dist/templates/common/bundled-skills/smart-search-cli/references/cli-contract.md +46 -46
- package/dist/templates/common/bundled-skills/trellis-cursor2plus-setup/SKILL.md +2 -2
- package/dist/templates/common/commands/finish-work.md +12 -0
- package/dist/templates/common/skills/check.md +4 -0
- package/dist/templates/cursor/agents/trellis-check.md +32 -0
- package/dist/templates/cursor/agents/trellis-implement.md +11 -0
- package/dist/templates/cursor/agents/trellis-research.md +29 -0
- package/dist/templates/cursor/fixtures/expected-rules.d.ts +14 -0
- package/dist/templates/cursor/fixtures/expected-rules.d.ts.map +1 -0
- package/dist/templates/cursor/fixtures/expected-rules.js +26 -0
- package/dist/templates/cursor/fixtures/expected-rules.js.map +1 -0
- package/dist/templates/cursor/rules/trellis-subagent-dispatch.mdc +34 -0
- package/dist/templates/markdown/spec/guides/execution-strategy.md.txt +42 -42
- package/dist/templates/markdown/spec/guides/retrieval-daily-guide.md.txt +12 -0
- package/dist/templates/trellis/config/execution-strategy-rules.json +30 -30
- package/dist/templates/trellis/local/README.md +61 -37
- package/dist/templates/trellis/local/index.d.ts +1 -0
- package/dist/templates/trellis/local/index.d.ts.map +1 -1
- package/dist/templates/trellis/local/index.js +1 -0
- package/dist/templates/trellis/local/index.js.map +1 -1
- package/dist/templates/trellis/local/patch_wpelc8.py +162 -38
- package/dist/templates/trellis/local/smoke.py +94 -0
- package/dist/templates/trellis/scripts/common/codebase_retrieval_router.py +2 -2
- package/dist/templates/trellis/scripts/common/cursor_retrieval_env.py +16 -2
- package/dist/templates/trellis/scripts/common/execution_strategy.py +267 -267
- package/dist/templates/trellis/scripts/common/retrieval_agent_instructions.py +26 -7
- package/dist/templates/trellis/scripts/common/semantic_plan_gate.py +18 -4
- package/dist/templates/trellis/scripts/common/smart_search_evidence.py +33 -1
- package/dist/templates/trellis/scripts/task.py +12 -0
- package/dist/utils/codebase-retrieval-router.js +2 -2
- package/dist/utils/codebase-retrieval-router.js.map +1 -1
- package/dist/utils/cursor-retrieval-env.d.ts +2 -0
- package/dist/utils/cursor-retrieval-env.d.ts.map +1 -1
- package/dist/utils/cursor-retrieval-env.js +11 -2
- package/dist/utils/cursor-retrieval-env.js.map +1 -1
- package/dist/utils/mirror-check.d.ts +22 -0
- package/dist/utils/mirror-check.d.ts.map +1 -0
- package/dist/utils/mirror-check.js +90 -0
- package/dist/utils/mirror-check.js.map +1 -0
- package/dist/utils/normalize-text.d.ts +7 -0
- package/dist/utils/normalize-text.d.ts.map +1 -0
- package/dist/utils/normalize-text.js +16 -0
- package/dist/utils/normalize-text.js.map +1 -0
- package/dist/utils/retrieval-agent-instructions.d.ts.map +1 -1
- package/dist/utils/retrieval-agent-instructions.js +14 -7
- package/dist/utils/retrieval-agent-instructions.js.map +1 -1
- package/dist/utils/retrieval-execution-telemetry.d.ts +12 -3
- package/dist/utils/retrieval-execution-telemetry.d.ts.map +1 -1
- package/dist/utils/retrieval-execution-telemetry.js +37 -1
- package/dist/utils/retrieval-execution-telemetry.js.map +1 -1
- package/dist/utils/retrieval-tool-classification.d.ts +2 -0
- package/dist/utils/retrieval-tool-classification.d.ts.map +1 -1
- package/dist/utils/retrieval-tool-classification.js +13 -0
- package/dist/utils/retrieval-tool-classification.js.map +1 -1
- package/dist/utils/semantic-plan-gate.d.ts.map +1 -1
- package/dist/utils/semantic-plan-gate.js +11 -4
- package/dist/utils/semantic-plan-gate.js.map +1 -1
- package/dist/utils/validate-rules.d.ts +21 -0
- package/dist/utils/validate-rules.d.ts.map +1 -0
- package/dist/utils/validate-rules.js +88 -0
- package/dist/utils/validate-rules.js.map +1 -0
- 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++
|
|
1
|
+
# Cursor++ Local Bundle
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
> **Native Cursor users:** safe to ignore or delete this directory unless using **Cursor++ BYOK**.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
7
|
+
## Bundle files
|
|
8
8
|
|
|
9
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
34
|
+
Agent-led setup: run skill **`trellis-cursor2plus-setup`** in Cursor Agent (lists models, writes JSON5, runs patch steps).
|
|
32
35
|
|
|
33
|
-
|
|
34
|
-
2. `python patch_wpelc8.py` → Reload Window only if you had not patched yet or reverted
|
|
36
|
+
## Revert recipe
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
```bash
|
|
39
|
+
cd .trellis/local/cursor2plus
|
|
40
|
+
python patch_wpelc8.py --revert
|
|
41
|
+
```
|
|
37
42
|
|
|
38
|
-
|
|
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
|
-
|
|
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
|
-
|
|
47
|
+
Goal: prove the patch routes **subagent** model independently of the **parent** session model.
|
|
46
48
|
|
|
47
|
-
|
|
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
|
-
##
|
|
57
|
+
## CLI reference
|
|
50
58
|
|
|
51
59
|
```bash
|
|
52
|
-
|
|
53
|
-
python patch_wpelc8.py --
|
|
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
|
-
|
|
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"}
|