@blxzer/cursor-trellis 0.1.0 → 0.1.2

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/generated-files.md

@@ -35,15 +35,18 @@ This page only describes files that are visible and editable inside the user pro
 
 ## Platform Directories
 
-Different platforms generate different directories. Common categories:
+On a fresh `trellis init --cursor`, the only platform directory created is `.cursor/`. Trellis previously generated per-platform directories for many AI tools (`.claude/`, `.codex/`, `.opencode/`, etc.); those legacy directories are preserved by `trellis update` but new Trellis behavior ships to `.cursor/` only.
 
-| Category | Example paths | Purpose |
+Common categories inside `.cursor/`:
+
+| Category | Path | Purpose |
 | --- | --- | --- |
-| hooks | `.claude/hooks/`, `.codex/hooks/`, `.cursor/hooks/` | Inject session context, workflow-state, and sub-agent context. |
-| settings | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Tell the platform when to run hooks or plugins. |
-| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
-| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Skills that auto-trigger or can be read by AI. |
-| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Explicit user-invoked command or workflow entry points. |
+| hooks | `.cursor/hooks/` | Hook scripts invoked from `.cursor/hooks.json`. Inject session context, workflow-state, and sub-agent context. |
+| settings/registration | `.cursor/hooks.json` | Registers which scripts run on which Cursor events. |
+| rules | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Per-turn policy prepended before every prompt. |
+| agents | `.cursor/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
+| skills | `.cursor/skills/` | Skills that auto-trigger or can be read by AI. |
+| commands | `.cursor/commands/` | Legacy compatibility-only user-invoked entry points. |
 
 When modifying a platform directory, also confirm whether `.trellis/workflow.md` still describes the same flow.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/overview.md

@@ -5,8 +5,8 @@
 Therefore, when an AI uses this skill, the default customization target is local files inside the user project:
 
 - `.trellis/`: workflow, tasks, specs, memory, scripts, and runtime state.
-- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
-- Shared skill layer: `.agents/skills/`.
+- Platform directory: `.cursor/` — skills, agents, hooks, commands, rules.
+- Shared skill layer: `.agents/skills/` (industry skill-sharing path; kept when present but not extended by new Trellis behavior).
 
 Do not default to guiding the user to fork the Trellis CLI repository. Treat upstream source code as the operating target only when the user explicitly says they want to change Trellis upstream source, publish an npm package, or contribute a PR.
 
@@ -30,7 +30,7 @@ All three layers live inside the user project, so an AI can read and modify them
 | `.trellis/tasks/` | Each task's PRD, technical notes, research files, and JSONL context. |
 | `.trellis/workspace/` | Per-developer journals and cross-session memory. |
 | `.trellis/scripts/` | Local Python runtime used by commands, hooks, and context injection. |
-| `.trellis/.runtime/` | Session-level runtime state, such as the selected task pointer. |
+| `.trellis/.runtime/` | Session-level runtime state, such as the selected task pointer. |
 | `.trellis/.template-hashes.json` | Template hashes for Trellis-managed files, used by update to determine whether local files were modified by the user. |
 
 ## AI Customization Principles
@@ -45,7 +45,7 @@ All three layers live inside the user project, so an AI can read and modify them
 
 - To understand which files exist after init, read `generated-files.md`.
 - To change phases, routing, or next actions, read `workflow.md`.
-- To change the task model, JSONL context, or selected task behavior, read `task-system.md`.
+- To change the task model, JSONL context, or selected task behavior, read `task-system.md`.
 - To change coding convention injection, read `spec-system.md`.
 - To understand journals and cross-session memory, read `workspace-memory.md`.
 - To change hooks or sub-agent context loading, read `context-injection.md`.

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/agents.md

@@ -6,75 +6,64 @@ Trellis agent files define specialized roles. Common Trellis agents in a user pr
 - `trellis-implement`
 - `trellis-check`
 
-File locations and formats differ by platform, but responsibility boundaries should stay consistent.
+Responsibility boundaries should stay consistent regardless of file format.
+
+> Trellis previously shipped agent files in per-platform directories for many AI tools (`.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, etc.). The project has converged on **Cursor-only**. New agent definitions ship into `.cursor/agents/`; legacy agent directories in upgraded projects are preserved but not extended.
 
 ## Agent Responsibilities
 
 | Agent | Responsibility |
 | --- | --- |
-| `trellis-research` | Investigate the question and write findings into the selected task's `research/`. |
+| `trellis-research` | Investigate the question and write findings into the selected task's `research/`. |
 | `trellis-implement` | Implement against `prd.md`, optional `design.md` / `implement.md`, `implement.jsonl`, and related spec/research. |
 | `trellis-check` | Review changes, fix discovered issues, and run necessary checks. |
 
 Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported.
 
-## Common Paths
+## Common Paths (Cursor)
 
 | Platform | Agent path |
 | --- | --- |
-| Claude Code | `.claude/agents/trellis-*.md` |
 | Cursor | `.cursor/agents/trellis-*.md` |
-| OpenCode | `.opencode/agents/trellis-*.md` |
-| Codex | `.codex/agents/trellis-*.toml` |
-| Kiro | `.kiro/agents/trellis-*.json` |
-| Gemini CLI | `.gemini/agents/trellis-*.md` |
-| Qoder | `.qoder/agents/trellis-*.md` |
-| CodeBuddy | `.codebuddy/agents/trellis-*.md` |
-| Factory Droid | `.factory/droids/trellis-*.md` |
-| Pi Agent | `.pi/agents/trellis-*.md` |
-
-GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project.
 
-Main-session workflow platforms such as Kilo, Antigravity, and Windsurf may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session.
+Agent files are dispatched via the Cursor Task tool, opened as Agent sessions, or invoked inline as Skill forms depending on the entry point. See `cursor-subagent-policy.md.txt` for the full entry-point matrix and Method 1–2.6 model dispatch strategy.
 
 ## Two Context Loading Modes
 
 ### hook push
 
-The platform hook injects task context before the agent starts. The agent file itself can focus more on responsibilities and boundaries.
-
-Common on platforms that support agent hooks.
+The Cursor hook (`inject-subagent-context.py`, registered in `.cursor/hooks.json`) injects task context before the agent starts. The agent file itself can focus more on responsibilities and boundaries.
 
 ### agent pull
 
 The agent file instructs the agent to read after startup:
 
-- `python3 ./.trellis/scripts/task.py selected --source`
-- `implement.jsonl` or `check.jsonl`
-- spec/research files referenced by JSONL
-- selected task `prd.md`
+- `python3 ./.trellis/scripts/task.py selected --source`
+- `implement.jsonl` or `check.jsonl`
+- spec/research files referenced by JSONL
+- selected task `prd.md`
 - `design.md` if present
 - `implement.md` if present
 
-This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts.
+This mode fits cases where the hook cannot reliably rewrite the sub-agent prompt or the entry point is an Agent session that bypasses the Task hook path.
 
 ## Local Change Scenarios
 
 | User need | Edit location |
 | --- | --- |
-| Implement agent must follow extra restrictions | The platform's `trellis-implement` agent file. |
-| Check agent must run project-specific commands | `trellis-check` agent file, and `.trellis/spec/` if needed. |
-| Research agent must output a fixed format | `trellis-research` agent file. |
-| Agent cannot read task context | Agent prelude or `inject-subagent-context` hook. |
-| Add a project-specific agent | Platform agent directory + related workflow/command/skill entry point. |
+| Implement agent must follow extra restrictions | `.cursor/agents/trellis-implement.md`. |
+| Check agent must run project-specific commands | `.cursor/agents/trellis-check.md`, and `.trellis/spec/` if needed. |
+| Research agent must output a fixed format | `.cursor/agents/trellis-research.md`. |
+| Agent cannot read task context | Agent prelude in the agent file, or the `inject-subagent-context` hook registration in `.cursor/hooks.json`. |
+| Add a project-specific agent | `.cursor/agents/` + related skill/command entry point that invokes it. |
 
 ## Modification Principles
 
 1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent.
-2. **Specify the read order**. Agents must know to start from the selected task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present.
+2. **Specify the read order**. Agents must know to start from the selected task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present.
 3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues.
-4. **Keep semantics synchronized in multi-platform projects**. If the user configured Claude, Codex, and Cursor together, decide whether changes to one platform's agent also need to be applied to others.
+4. **Treat dogfood + published copies consistently**. `.cursor/agents/trellis-*.md` (dogfooded) and `packages/cli/src/templates/cursor/agents/trellis-*.md` (published template) must stay in sync — see `cross-layer-thinking-guide.md.txt` → Cross-Package Template Consistency.
 
 ## Do Not Default To Editing Upstream Templates
 
-Local AI should default to modifying platform agent files inside the user project. Discuss upstream template source only when the user explicitly wants to contribute the change back to Trellis.
+Local AI should default to modifying agent files inside the user project's `.cursor/agents/`. Discuss upstream template source (`packages/cli/src/templates/cursor/agents/`) only when the user explicitly wants to contribute the change back to Trellis.

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/hooks-and-settings.md

@@ -1,60 +1,49 @@
 # Hooks And Settings
 
-Hooks/settings are the entry layer that connects a platform to Trellis. They decide which scripts, plugins, or extensions a platform runs for which events.
+Hooks/settings are the entry layer that connects Cursor to Trellis. They decide which scripts run on which Cursor events.
 
 ## Settings Responsibilities
 
-settings/config files usually register:
+`.cursor/hooks.json` registers:
 
-- session-start hook: injects a Trellis overview when a new session starts or context resets.
-- workflow-state hook: parses `[workflow-state:STATUS]` blocks from `.trellis/workflow.md` and emits the body matching the selected task `status` on each user input. Parser-only; the script does not embed fallback content.
+- session-start hook: injects a Trellis overview when a new session starts or context resets (note the Cursor `additional_context` bug #158452 — see `cursor-context-injection-guide.md.txt`).
+- workflow-state hook: parses `[workflow-state:STATUS]` blocks from `.trellis/workflow.md` and emits the body matching the selected task `status` on each user input. Parser-only; the script does not embed fallback content.
 - sub-agent context hook: injects task context when implementation/check/research agents start.
 - shell/session bridge: lets shell commands see the same Trellis session identity.
-- platform plugin or extension entry points.
 
-Common files:
+> Trellis previously shipped settings/config files for many platforms (`.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, etc.). The project has converged on **Cursor-only**. New Trellis features ship into `.cursor/hooks.json` + `.cursor/hooks/`.
+
+Whether legacy settings/config files exist in a project depends on which historical `trellis init --<platform>` flags the user previously ran; `trellis update` preserves them.
 
 | Platform | settings/config |
 | --- | --- |
-| Claude Code | `.claude/settings.json` |
 | Cursor | `.cursor/hooks.json` |
-| Codex | `.codex/hooks.json`, `.codex/config.toml` |
-| OpenCode | `.opencode/package.json`, `.opencode/plugins/*` |
-| Kiro | `.kiro/hooks/` + platform config |
-| Gemini CLI | `.gemini/settings.json` |
-| Qoder | `.qoder/settings.json` |
-| CodeBuddy | `.codebuddy/settings.json` |
-| GitHub Copilot | `.github/copilot/hooks.json` |
-| Factory Droid | `.factory/settings.json` |
-| Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` |
-
-Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.
 
 ## Hook Script Types
 
 | Script | Purpose |
 | --- | --- |
 | `session-start.py` | Generates session-start context. |
-| `inject-workflow-state.py` | Parses `[workflow-state:STATUS]` blocks in `.trellis/workflow.md` and emits the body matching the selected task status. Falls back to `Refer to workflow.md for current step.` when no matching block exists. |
+| `inject-workflow-state.py` | Parses `[workflow-state:STATUS]` blocks in `.trellis/workflow.md` and emits the body matching the selected task status. Falls back to `Refer to workflow.md for current step.` when no matching block exists. |
 | `inject-subagent-context.py` | Injects PRD, JSONL context, and related spec/research into sub-agents. |
 | `inject-shell-session-context.py` | Lets shell commands inherit Trellis session identity. |
 
-Not every platform has every hook. Do not copy files from another platform just because a platform lacks a hook; first confirm whether that platform supports the corresponding event.
+Cursor exposes sessionStart, preToolUse on Task/Subagent, beforeShellExecution, and stop events. Confirm against the current Cursor release before wiring a new event name; the available event surface has evolved over time and historical platform documentation may be stale.
 
 ## Local Change Scenarios
 
 | User need | Edit location |
 | --- | --- |
-| AI should see more/less context in a new session | Platform `session-start` hook. |
+| AI should see more/less context in a new session | `.cursor/hooks.json` → `session-start` hook (or `.cursor/rules/*.mdc` for content the model must see every turn — see `cursor-context-injection-guide.md.txt`). |
 | Per-turn hint policy should change | `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The hook parses workflow.md verbatim — no script edit required. |
-| Sub-agent cannot read PRD/spec | `inject-subagent-context` hook or agent prelude. |
-| `task.py selected` in shell has no selected task | Shell/session bridge hook or platform environment variable configuration. |
-| Disable an automatic injection | The corresponding hook registration in settings/config. |
+| Sub-agent cannot read PRD/spec | `inject-subagent-context.py` hook or agent prelude in `.cursor/agents/*.md`. |
+| `task.py selected` in shell has no selected task | `inject-shell-session-context.py` hook or environment-variable configuration. |
+| Disable an automatic injection | The corresponding hook registration in `.cursor/hooks.json`. |
 
 ## Modification Principles
 
-1. **Settings wire things up; hooks define behavior**. If only the hook changes, the platform may never call it. If only settings change, behavior may not change.
-2. **Confirm platform event names first**. Different platforms use different names for SessionStart, UserPromptSubmit, AgentSpawn, shell execution, and similar events.
+1. **Settings wire things up; hooks define behavior**. If only the hook changes, Cursor may never call it. If only settings change, behavior may not change.
+2. **Confirm Cursor event names first**. Cursor's hook event surface has changed between releases; what an older guide calls `UserPromptSubmit` may now be modeled by `beforeSubmitPrompt` instead.
 3. **Hooks read local `.trellis/`, not upstream source**. `.trellis/scripts/` and `.trellis/workflow.md` in the user project are the default targets.
 4. **Errors must be visible**. Hook failures should tell the user what was not injected instead of silently leaving the AI without context.
 
@@ -62,8 +51,8 @@ Not every platform has every hook. Do not copy files from another platform just
 
 If the user says "AI did not read Trellis state":
 
-1. Check whether the platform settings register the hook.
-2. Check whether the hook file exists.
-3. Manually run the `.trellis/scripts/get_context.py` or `task.py selected --source` command that the hook depends on.
-4. Check whether selected task state exists in `.trellis/.runtime/sessions/`.
-5. Check whether the platform shell passes session identity.
+1. Check whether `.cursor/hooks.json` registers the hook.
+2. Check whether the hook file exists under `.cursor/hooks/`.
+3. Manually run the `.trellis/scripts/get_context.py` or `task.py selected --source` command that the hook depends on.
+4. Check whether selected task state exists in `.trellis/.runtime/sessions/`.
+5. Check whether the Cursor shell passes session identity.

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/overview.md

@@ -1,60 +1,44 @@
 # Platform Files Overview
 
-Trellis connects the same local architecture to different AI tools. `.trellis/` stores the shared runtime; platform directories store adapter files that define how each AI tool enters Trellis.
+Trellis connects the same local architecture to **Cursor**. `.trellis/` stores the shared runtime; `.cursor/` stores adapter files that define how Cursor enters Trellis.
 
-When a local AI modifies Trellis, it should distinguish two file categories first:
-
-- **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
-- **Platform files**: first-class `.claude/`, `.codex/`, `.cursor/`; legacy adapter directories such as `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
-
-Platform files do not store business state. They let the corresponding AI tool read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
-
-This fork actively targets Claude Code, Codex, and Cursor as first-class platform surfaces. Other adapter directories may still exist when explicitly selected or already configured, but new workflow/runtime behavior should not assume they are equally verified without a dedicated compatibility pass.
+When a local AI modifies Trellis, it should distinguish two file categories first:
 
-## Platform File Categories
+- **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
+- **Platform files**: `.cursor/` (settings, hooks, agents, skills, commands, rules).
 
-| Category | Common paths | Purpose |
-| --- | --- | --- |
-| settings/config | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Register hooks, plugins, extensions, or platform behavior. |
-| hooks/plugins/extensions | `.claude/hooks/`, `.opencode/plugins/`, `.pi/extensions/` | Inject context at session start, user input, agent startup, shell execution, and similar events. |
-| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check`. |
-| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
-| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Entry points explicitly invoked by the user. |
-
-## Three Platform Integration Modes
-
-### 1. Hook / Extension Driven
-
-These platforms can trigger scripts or plugins on specific events and actively inject Trellis context into AI.
+Platform files do not store business state. They let Cursor read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
 
-Common capabilities:
+> **Historical note**: Trellis previously shipped adapter directories for many AI tools (`.claude/`, `.codex/`, `.opencode/`, etc.). The project has converged on **Cursor-only**. Legacy adapter directories may still exist in upgraded projects (`trellis update` preserves user files), but new framework/runtime behavior targets Cursor exclusively.
 
-- session-start injection of a `.trellis/` overview.
-- workflow-state hints for each user turn.
-- PRD/spec/research injection when sub-agents start.
-- Shell commands inheriting session identity.
+## Platform File Categories (Cursor)
 
-To change "when the AI knows what," inspect hooks/plugins/extensions and settings first.
-
-### 2. Agent Prelude / Pull-Based
-
-Some platforms cannot reliably let hooks rewrite sub-agent prompts, so the agent file itself instructs the agent to read the selected task, PRD, and JSONL context after startup.
+| Category | Common paths | Purpose |
+| --- | --- | --- |
+| settings/config | `.cursor/hooks.json` | Register hooks and platform behavior. |
+| hooks | `.cursor/hooks/` | Inject context at session start, pre-tool-use on Task/Subagent, before-shell-execution, and stop events. |
+| rules | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Per-turn policy prepended before every prompt (e.g. Request Triage, retrieval routing). See `cursor-context-injection-guide.md.txt` for the channel-reliability matrix. |
+| agents | `.cursor/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check` for Task / Agent-session dispatch. |
+| skills | `.cursor/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
+| commands | `.cursor/commands/` | User-invocable `/slash` entry points (e.g. `trellis-continue`, `record-session`). |
 
-To change how sub-agents load context, inspect the agent files themselves.
+## Cursor Integration Mode
 
-### 3. Main-Session Workflow
+Cursor combines three integration styles:
 
-Some platforms do not have Trellis sub-agent or hook capabilities. They rely on workflows/skills/commands to guide the main-session AI to read files, run scripts, and move tasks forward.
+1. **Hook / Extension Driven** — `.cursor/hooks.json` + `.cursor/hooks/` fire on sessionStart, pre-tool-use on Task/Subagent, beforeShellExecution, and stop. Common capabilities: session-start Task Dashboard + Phase Index injection (note the `additional_context` Cursor bug #158452 — use `.cursor/rules` or `AGENTS.md` for must-always-be-visible content), PRD/jsonl injection when sub-agents start, shell commands inheriting session identity.
+2. **Agent Prelude / Pull-Based** — `.cursor/agents/*.md` instruct each custom Task subagent to read the selected task, PRD, and JSONL context after startup (the `<!-- trellis-hook-injected -->` marker confirms injected context).
+3. **Main-Session Workflow** — `.cursor/commands/*.md` and `.cursor/skills/*.md` guide the main-session AI to read files, run scripts, and move tasks forward; `.cursor/rules/*.mdc` enforce per-turn policy.
 
-To change behavior, inspect platform workflows/skills/commands and `.trellis/workflow.md`.
+To change "when the AI knows what," inspect `.cursor/hooks.json` and `.cursor/rules/` first. To change how sub-agents load context, inspect `.cursor/agents/`. To change user-invocable entry points, inspect `.cursor/commands/` and `.cursor/skills/`.
 
 ## Local Modification Order
 
-When the user asks to customize behavior for a platform, the AI should inspect files in this order:
+When the user asks to customize behavior:
 
 1. Read `.trellis/workflow.md` to confirm the shared flow.
-2. Read the target platform's settings/config to see which hooks/agents/skills/commands are registered.
-3. Read the target platform's agents/skills/commands/hooks.
+2. Read `.cursor/hooks.json` to see which hooks are registered.
+3. Read the relevant `.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md`, `.cursor/commands/*.md`, and `.cursor/rules/*.mdc`.
 4. Modify the local file closest to the user's need.
 5. If the change affects the shared flow, synchronize `.trellis/workflow.md` or `.trellis/spec/`.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md

@@ -1,76 +1,45 @@
 # Platform File Map
 
-This page lists common Trellis file locations in a user project by platform. Whether a platform directory exists in an actual project depends on which `trellis init --<platform>` commands the user ran.
-
-This fork's first-class platform surfaces are Claude Code, Codex, and Cursor. Other rows are legacy adapters: keep them working when explicitly configured, but do not treat them as equal targets for new framework/runtime behavior without a compatibility pass.
+This page lists Trellis file locations in a user project on **Cursor**.
 
-## Matrix
-
-| Platform | Tier | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
-| --- | --- | --- | --- | --- | --- | --- |
-| Claude Code | First-class | `--claude` | `.claude/` | `.claude/skills/` | `.claude/agents/` | `.claude/hooks/` + `.claude/settings.json` |
-| Cursor | First-class | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
-| Codex | First-class | `--codex` | `.codex/` | `.agents/skills/` | `.codex/agents/` | `.codex/hooks/` + `.codex/hooks.json` |
-| OpenCode | Legacy adapter | `--opencode` | `.opencode/` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/plugins/` |
-| Kilo | Legacy adapter | `--kilo` | `.kilocode/` | `.kilocode/skills/` | Usually none | `.kilocode/workflows/` |
-| Kiro | Legacy adapter | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` |
-| Gemini CLI | Legacy adapter | `--gemini` | `.gemini/` | `.agents/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
-| Antigravity | Legacy adapter | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
-| Windsurf | Legacy adapter | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` |
-| Qoder | Legacy adapter | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` |
-| CodeBuddy | Legacy adapter | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
-| GitHub Copilot | Legacy adapter | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
-| Factory Droid | Legacy adapter | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
-| Pi Agent | Legacy adapter | `--pi` | `.pi/` | `.pi/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` + `.pi/settings.json` |
-
-## Capability Groups
-
-### Trellis Sub-Agent Support
-
-These platforms usually have `trellis-research`, `trellis-implement`, and `trellis-check` files:
-
-- Claude Code
-- Cursor
-- OpenCode
-- Codex
-- Kiro
-- Gemini CLI
-- Qoder
-- CodeBuddy
-- GitHub Copilot
-- Factory Droid
-- Pi Agent
-
-When changing implementation/check/research behavior, look for the corresponding platform agent files first.
+Trellis originally supported multiple AI platforms (Claude Code, Codex, OpenCode, Kilo, Kiro, Gemini, Antigravity, Windsurf, Qoder, CodeBuddy, GitHub Copilot, Factory Droid, Pi Agent). The project has since converged on **Cursor-only**. Legacy adapter directories may still exist in upgraded projects (`trellis update` preserves user files), but new framework/runtime behavior targets Cursor exclusively.
 
-### Main-Session Workflow Platforms
-
-These platforms rely more on workflows/skills to guide the main session:
-
-- Kilo
-- Antigravity
-- Windsurf
+## Matrix
 
-When changing behavior, inspect workflows and skills first. Do not assume Trellis sub-agents exist.
+| Platform | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
+| --- | --- | --- | --- | --- | --- |
+| Cursor | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
 
-### Shared `.agents/skills/`
+## Capability Reference (Cursor)
 
-Codex writes the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it.
+- **Skills** auto-trigger via the workflow matcher and can be read on demand. They live in `.cursor/skills/`.
+- **Agents** (`trellis-research`, `trellis-implement`, `trellis-check`) live in `.cursor/agents/` and are dispatched via the Task tool or opened as Agent sessions / Skill forms depending on the entry point (see `cursor-subagent-policy.md.txt`).
+- **Commands** (e.g. `record-session`, `trellis-continue`) live in `.cursor/commands/` and are user-invocable via `/slash`.
+- **Hooks** (session start, pre-tool-use on Task/Subagent, before-shell-execution, stop) are registered in `.cursor/hooks.json` and their handler scripts live in `.cursor/hooks/`.
+- **Project rules** (always-applied policy) live in `.cursor/rules/*.mdc`.
 
 ## Decision Rules When Modifying Platform Files
 
-1. User specified a platform: modify only that platform directory unless shared workflow/spec files must also change.
-2. User says "all platforms should do this": synchronize equivalent entry points platform by platform; do not modify only one directory.
-3. User only says "my AI": inspect the configuration directories that actually exist in the project and infer the current AI platform.
-4. User wants project rules: prefer `.trellis/spec/` or a project-local skill.
-5. User wants Trellis behavior: edit `.trellis/workflow.md` plus platform hooks/agents/skills/commands.
+1. User specified a platform other than Cursor: treat as a legacy adapter inspection — preserve existing files but do not extend new behavior there.
+2. User says "all platforms should do this": in Cursor-only world this is equivalent to "modify the Cursor path"; also mirror any dogfooded copy under `.cursor/` in `packages/cli/src/templates/cursor/` if applicable.
+3. User only says "my AI": inspect which directories actually exist in the project; on a fresh `trellis init` only `.cursor/` and `.trellis/` are created.
+4. User wants project rules: prefer `.trellis/spec/` or a project-local skill under `.cursor/skills/`.
+5. User wants Trellis behavior: edit `.trellis/workflow.md` plus `.cursor/hooks.json` / `.cursor/agents/` / `.cursor/skills/` / `.cursor/commands/`.
 
 ## When Paths Differ
 
-Platform ecosystems change, and user projects may already be customized. If this table disagrees with local files, use the actual settings/config in the user project as authoritative:
+Cursor's layout can change between versions, and user projects may already be customized. If this table disagrees with local files, use the actual settings/config in the user project as authoritative:
 
-- Check the hook that settings registers.
-- Check the script that a command/prompt/workflow points to.
+- Check the hook that `.cursor/hooks.json` registers.
+- Check the script that a command/agent points to.
 - Judge behavior by the read rules currently written in the agent file.
 
 Do not delete a custom file just because it is not listed in this path table.
+
+## Legacy Adapter Handling
+
+If a user project still contains legacy platform directories (e.g. `.claude/`, `.codex/`, `.opencode/`):
+
+- `trellis update` preserves them; do not delete on sight.
+- If the user asks to clean them up, suggest removing the unused platform directories after confirming they are not shared with another tool.
+- Do not register new hooks/agents/skills/commands under legacy platform directories. New Trellis features ship to `.cursor/` only.

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/skills-and-commands.md

@@ -1,6 +1,6 @@
 # Skills, Commands, Prompts, And Workflows
 
-Skills and commands are textual entry points for user interaction with Trellis. Different platforms use different names, but their core purpose is the same: tell the AI how to enter the Trellis flow when the user expresses a certain intent.
+Skills and commands are textual entry points for user interaction with Trellis. They tell the AI how to enter the Trellis flow when the user expresses a certain intent.
 
 ## Conceptual Differences
 
@@ -11,6 +11,8 @@ Skills and commands are textual entry points for user interaction with Trellis.
 | prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
 | workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
 
+> Trellis previously shipped per-platform skill/command directories for many AI tools. The project has converged on **Cursor-only**. New skills and commands ship into `.cursor/`; legacy adapter directories in upgraded projects are preserved but not extended.
+
 Trellis has two skill families:
 
 - Workflow skills: `brainstorm`, `before-dev`, `check`, `update-spec`, and `break-loop`.
@@ -22,36 +24,19 @@ Bundled skills are installed as directories and may include nested `agents/`, `e
 
 `trellis-spec-bootstrap` bootstraps project-specific `.trellis/spec/` guidance from the real repository.
 
-`trellis-skill-creator` is the authoring and review guide for Trellis-compatible skills. Use it when creating or improving project-local skills, shared `.agents/skills/`, platform-specific skill directories, or upstream bundled skills. Keep `trellis-meta` focused on architecture and routing.
+`trellis-skill-creator` is the authoring and review guide for Trellis-compatible skills. Use it when creating or improving project-local skills under `.cursor/skills/`, the shared `.agents/skills/` directory (industry skill-sharing, kept but not extended by new Trellis behavior), or upstream bundled skills. Keep `trellis-meta` focused on architecture and routing.
 
 `trellis-micro-grill` is the Trellis clarification adapter. It asks one high-value question at a time and escalates to Lite, Full, or Parent/Child task modes only when durable artifacts or broader risk require it.
 
-`trellis-cursor2plus-setup` guides Cursor++ BYOK users through `trellis-task-models.json5` (primary/fallback per Task role), `patch_wpelc8.py`, and Reload Window. Use after `trellis init` with Cursor or when `providers.json` changes.
+`trellis-cursor2plus-setup` guides Cursor++ BYOK users through `trellis-task-models.json5` (primary/fallback per Task role), `patch_wpelc8.py`, and Reload Window. Use after `trellis init --cursor` or when `providers.json` changes.
 
-## Common Paths
+## Common Paths (Cursor)
 
 | Platform | Common entries |
 | --- | --- |
-| Claude Code | `.claude/skills/`, `.claude/commands/` |
 | Cursor | `.cursor/skills/` (preferred); `.cursor/commands/` is legacy compatibility-only |
-| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
-| Codex | `.agents/skills/`, `.codex/skills/` |
-| Kilo | `.kilocode/skills/`, `.kilocode/workflows/` |
-| Kiro | `.kiro/skills/` |
-| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
-| Antigravity | `.agent/skills/`, `.agent/workflows/` |
-| Windsurf | `.windsurf/skills/`, `.windsurf/workflows/` |
-| Qoder | `.qoder/skills/`, `.qoder/commands/` |
-| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
-| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
-| Factory Droid | `.factory/skills/`, `.factory/commands/` |
-| Pi Agent | `.pi/skills/` |
-
-In a user project, use the files actually generated by init as authoritative.
-On current Cursor, Trellis prefers Agent Skills for manual entrypoints such as
-`trellis-continue` and `trellis-finish-work`; legacy `.cursor/commands` files
-may exist in older projects but should be treated as an explicit compatibility
-surface rather than the default current-platform command surface.
+
+In a user project, use the files actually generated by init as authoritative. On current Cursor, Trellis prefers Agent Skills for manual entrypoints such as `trellis-continue` and `trellis-finish-work`; legacy `.cursor/commands/` files may exist in older projects but should be treated as an explicit compatibility surface rather than the default current-platform command surface.
 
 ## Skill Structure
 
@@ -114,15 +99,14 @@ Do not reintroduce `task.py start`, `task.py current`, or `task.py finish` into
 | --- | --- |
 | Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
 | Change user command behavior | The corresponding command/prompt/workflow file. |
-| Add a project-local skill | Platform skill directory, or shared `.agents/skills/`. |
-| Let multiple platforms share one capability | Write equivalent skills in each platform skill directory, or use the `.agents/skills/` shared layer on platforms that support it. |
-| Change finish/continue entry points | Platform commands/prompts/workflows; on current Cursor, prefer `.cursor/skills/trellis-continue` and `.cursor/skills/trellis-finish-work` over legacy `.cursor/commands`. |
+| Add a project-local skill | `.cursor/skills/` (or `.agents/skills/` only when explicitly sharing with another non-Trellis tool that reads that path). |
+| Change finish/continue entry points | On current Cursor, prefer `.cursor/skills/trellis-continue` and `.cursor/skills/trellis-finish-work` over legacy `.cursor/commands/`. |
 
 ## Modification Principles
 
 1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `trellis-meta` and `trellis-skill-creator`.
 2. **Make trigger descriptions specific**. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
-3. **Keep the same semantics consistent across platforms**. File formats can differ, but behavior descriptions should match.
+3. **Keep behavior descriptions consistent with the shared `.trellis/` runtime**. Format may differ per file type, but semantics should match the shared workflow.
 4. **Put project-specific capabilities in local skills**. Do not put team-private flows into public `trellis-meta`.
 
-If the user only wants local AI to know one more project rule, usually create a project-local skill or update `.trellis/spec/` instead of changing a Trellis built-in workflow skill.
+If the user only wants local AI to know one more project rule, usually create a project-local skill under `.cursor/skills/` or update `.trellis/spec/` instead of changing a Trellis built-in workflow skill.

package/dist/templates/common/bundled-skills/trellis-skill-creator/references/trellis-skill-locations.md

@@ -6,8 +6,8 @@ Choose the target directory before writing content. Local files are authoritativ
 
 | User goal | Default location | Notes |
 | --- | --- | --- |
-| Add a skill for one Trellis project across compatible tools | `.agents/skills/<skill-name>/` | Good default for Codex and tools that read the shared agentskills layer. |
-| Add a skill for one specific platform | Platform skill directory such as `.claude/skills/`, `.cursor/skills/`, `.qoder/skills/`, or `.pi/skills/` | Use when the platform has unique syntax, trigger behavior, or runtime expectations. |
+| Add a skill for one Trellis project on Cursor | `.cursor/skills/<skill-name>/` | Default target — Trellis is Cursor-only. |
+| Add a skill shared across tools that read the agentskills.io convention | `.agents/skills/<skill-name>/` | Use only when explicitly sharing with a non-Trellis tool that reads the shared agentskills layer. New Trellis behavior stays in `.cursor/skills/`. |
 | Change an existing local Trellis skill | The existing skill directory in the user's project | Preserve local customizations and read the current `SKILL.md` first. |
 | Add a public Trellis bundled skill | `packages/cli/src/templates/common/bundled-skills/<skill-name>/` | Only when working in the Trellis source repository. Update tests that assert bundled skill installation and template tracking. |
 | Add a personal cross-project skill | User's configured global skills directory | Requires explicit user approval because it changes global behavior outside the project. |

package/dist/templates/cursor/hooks.json

@@ -14,6 +14,12 @@
         "timeout": 30
       }
     ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "{{PYTHON_CMD}} .cursor/hooks/inject-retrieval-plan.py",
+        "timeout": 15
+      }
+    ],
     "beforeShellExecution": [
       {
         "command": "{{PYTHON_CMD}} .cursor/hooks/inject-shell-session-context.py",