@mindfoldhq/trellis 0.5.0-beta.16 → 0.5.0-beta.18

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

@@ -0,0 +1,102 @@
+# Local Spec System
+
+`.trellis/spec/` is the user's project-specific engineering spec library. Trellis is not about making AI memorize conventions; it injects relevant specs or requires the AI to read them at the right time.
+
+## Directory Model
+
+A common single-repository structure:
+
+```text
+.trellis/spec/
+├── backend/
+│   ├── index.md
+│   └── ...
+├── frontend/
+│   ├── index.md
+│   └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+A common monorepo structure:
+
+```text
+.trellis/spec/
+├── cli/
+│   ├── backend/
+│   │   ├── index.md
+│   │   └── ...
+│   └── unit-test/
+│       ├── index.md
+│       └── ...
+├── docs-site/
+│   └── docs/
+│       ├── index.md
+│       └── ...
+└── guides/
+    ├── index.md
+    └── ...
+```
+
+`index.md` is the entry point for each layer. It should list the Pre-Development Checklist and Quality Check. Specific guidelines live in other Markdown files in the same directory.
+
+## Package Configuration
+
+`.trellis/config.yaml` can declare packages:
+
+```yaml
+packages:
+  cli:
+    path: packages/cli
+  docs-site:
+    path: docs-site
+    type: submodule
+default_package: cli
+```
+
+The AI can run:
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+This command lists packages and spec layers for the current project. Use this output as the reference when configuring context JSONL.
+
+## How Specs Enter Tasks
+
+Before a task enters implementation, Phase 1.3 should write relevant specs into `implement.jsonl` / `check.jsonl`:
+
+```jsonl
+{"file": ".trellis/spec/cli/backend/index.md", "reason": "CLI backend conventions"}
+{"file": ".trellis/spec/cli/unit-test/conventions.md", "reason": "Test expectations"}
+```
+
+Sub-agents or platform preludes read these JSONL files and load the referenced specs. On platforms without sub-agent support, the AI should read the relevant specs directly according to the workflow.
+
+## What Specs Should Contain
+
+Specs should contain executable engineering conventions for the project, not generic best practices:
+
+- Where files should live.
+- How error handling should be expressed.
+- Input/output contracts for APIs, hooks, and commands.
+- Patterns that are forbidden.
+- Cases that require tests.
+- Project-specific pitfalls and how to avoid them.
+
+When the AI learns a new rule during implementation or debugging, it should update `.trellis/spec/` rather than only summarizing it in chat.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Add a new spec layer | `.trellis/spec/<package>/<layer>/index.md` and corresponding guideline files. |
+| Change monorepo spec mapping | `packages` / `default_package` / `spec_scope` in `.trellis/config.yaml`. |
+| Change which specs AI reads before implementation | The task's `implement.jsonl`. |
+| Change which specs AI reads during checking | The task's `check.jsonl`. |
+| Change when specs should be updated | Phase 3.3 in `.trellis/workflow.md` and the `trellis-update-spec` skill. |
+
+## Boundaries
+
+`.trellis/spec/` is the user's project specification, not a permanent copy of Trellis built-in templates. The AI should encourage the user to update it according to the actual project code instead of treating Trellis default templates as immutable documents.

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

@@ -0,0 +1,101 @@
+# Local Task System
+
+The Trellis task system is stored entirely under `.trellis/tasks/` in the user project. Each task is a directory containing requirements, context, research, state, and relationship information.
+
+## Task Directory Structure
+
+```text
+.trellis/tasks/
+├── 04-28-example-task/
+│   ├── task.json
+│   ├── prd.md
+│   ├── info.md
+│   ├── implement.jsonl
+│   ├── check.jsonl
+│   └── research/
+└── archive/
+    └── 2026-04/
+```
+
+| File | Purpose |
+| --- | --- |
+| `task.json` | Task metadata: status, assignee, priority, branch, parent/child tasks, and similar fields. |
+| `prd.md` | Requirements document; the most important business context during implementation. |
+| `info.md` | Optional technical design. |
+| `implement.jsonl` | List of spec/research files the implement agent must read first. |
+| `check.jsonl` | List of spec/research files the check agent must read first. |
+| `research/` | Research artifacts. Complex findings should not live only in chat. |
+
+## `task.json`
+
+`task.json` records task status and metadata. Common fields:
+
+| Field | Meaning |
+| --- | --- |
+| `id` / `name` / `title` | Task identity and title. |
+| `status` | Status such as `planning`, `in_progress`, `review`, or `completed`. |
+| `priority` | `P0`, `P1`, `P2`, `P3`. |
+| `creator` / `assignee` | Creator and assignee. |
+| `package` | Target package in a monorepo; may be empty. |
+| `branch` / `base_branch` | Working branch and PR target branch. |
+| `children` / `parent` | Parent/child task relationships. |
+| `commit` / `pr_url` | Commit and PR information after completion. |
+| `meta` | Extension fields. |
+
+The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, `prd.md`, whether JSONL context is configured, and the phase descriptions in `workflow.md`.
+
+## Active Task
+
+The user sees a "current task," but Trellis stores active task state per session.
+
+```text
+.trellis/.runtime/sessions/<context-key>.json
+```
+
+`task.py start` writes the task path into the runtime session file for the current session. `task.py current --source` shows the current task and where it came from. Different AI windows can point to different tasks without overwriting each other.
+
+If the platform or shell environment has no stable session identity, `task.py start` may be unable to set the active task. The AI should read the error, inspect the platform hook/session environment, and not fall back to a shared global pointer.
+
+## JSONL Context
+
+`implement.jsonl` and `check.jsonl` are context manifests for sub-agents to read first.
+
+Format:
+
+```jsonl
+{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend conventions"}
+{"file": ".trellis/tasks/04-28-example/research/api.md", "reason": "API research"}
+```
+
+Rules:
+
+- Include spec and research files.
+- Do not include code files that are about to be modified.
+- Do not treat temporary conclusions in chat as the only context.
+- Seed rows have no `file` field; they only prompt the AI to fill in real entries.
+
+## Common Commands
+
+```bash
+python3 ./.trellis/scripts/task.py create "<title>" --slug <slug>
+python3 ./.trellis/scripts/task.py start <task>
+python3 ./.trellis/scripts/task.py current --source
+python3 ./.trellis/scripts/task.py add-context <task> implement <file> <reason>
+python3 ./.trellis/scripts/task.py validate <task>
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive <task>
+```
+
+When modifying the task system, the AI should prefer script commands to maintain structure. Edit JSON/Markdown directly only when scripts do not cover the need.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change the default task template | `.trellis/scripts/common/task_store.py` and task creation instructions. |
+| Change status semantics | `.trellis/workflow.md`, workflow-state hook logic, and task usage conventions. |
+| Add task lifecycle actions | `hooks.after_*` in `.trellis/config.yaml`. |
+| Change context rules | Phase 1.3 in `.trellis/workflow.md` and related platform agent/hook instructions. |
+| Change archive policy | `.trellis/scripts/common/task_store.py` / `task_utils.py`. |
+
+These are local files in the user project. Do not default to editing Trellis CLI source code unless the user wants to contribute upstream.

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

@@ -0,0 +1,75 @@
+# Local Workflow System
+
+`.trellis/workflow.md` is the Trellis workflow source of truth inside the user project. An AI does not need Trellis source code to understand how the current project should move tasks forward; this file is enough.
+
+## File Responsibilities
+
+`.trellis/workflow.md` has three responsibilities:
+
+1. **Explain workflow phases**: Plan, Execute, Finish.
+2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
+3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
+
+## Current Phase Model
+
+```text
+Phase 1: Plan    -> clarify what to build, produce prd.md and required research
+Phase 2: Execute -> implement against the PRD and specs, then check
+Phase 3: Finish  -> final verification, preserve lessons, and wrap up
+```
+
+Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
+
+## Skill Routing
+
+`workflow.md` separates routing by platform capability:
+
+- Platforms with sub-agent support: dispatch `trellis-implement` by default for implementation and `trellis-check` for checking.
+- Platforms without sub-agent support: the main session reads skills such as `trellis-before-dev`, then executes directly.
+
+When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
+
+## Workflow-State Prompt Blocks
+
+The bottom of `workflow.md` can contain state blocks like this:
+
+```text
+[workflow-state:no_task]
+...
+[/workflow-state:no_task]
+```
+
+Hooks choose the right block based on current task status and inject it into the conversation. Common states include:
+
+| State | Meaning |
+| --- | --- |
+| `no_task` | The current session has no active task. |
+| `planning` | The task is still in requirements, research, or context configuration. |
+| `in_progress` | The task has entered implementation and checking. |
+| `completed` | The task is complete and waiting for wrap-up or archive. |
+
+If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
+
+## Local Modification Patterns
+
+Common changes:
+
+| Goal | Edit point |
+| --- | --- |
+| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
+| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
+| Change the default implementation/check path | Update Phase 2 and skill routing. |
+| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
+| Change platform differences | Update routing descriptions grouped by platform. |
+
+After editing, make the AI reread `.trellis/workflow.md`; do not assume the flow from the old conversation is still valid.
+
+## Relationship To Platform Files
+
+`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
+
+- skills, such as `trellis-brainstorm` and `trellis-check`.
+- commands/prompts/workflows, such as continue and finish-work.
+- hooks, such as session-start or workflow-state injection.
+
+If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.

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

@@ -0,0 +1,71 @@
+# Local Workspace Memory System
+
+`.trellis/workspace/` stores cross-session memory. Its purpose is to let AI and humans understand what happened before across different windows and different days.
+
+## Directory Structure
+
+```text
+.trellis/workspace/
+├── index.md
+└── <developer>/
+    ├── index.md
+    ├── journal-1.md
+    └── journal-2.md
+```
+
+| File | Purpose |
+| --- | --- |
+| `.trellis/.developer` | Current developer identity. |
+| `.trellis/workspace/index.md` | Global workspace overview. |
+| `.trellis/workspace/<developer>/index.md` | Session index for a developer. |
+| `.trellis/workspace/<developer>/journal-N.md` | Session journal. |
+
+## Developer Identity
+
+Run this the first time:
+
+```bash
+python3 ./.trellis/scripts/init_developer.py <name>
+```
+
+This creates `.trellis/.developer` and the corresponding workspace directory. The AI should not change developer identity casually; if the identity is wrong, first confirm who is using the current project.
+
+## Journal
+
+`journal-N.md` records completed or partially completed work from each session. By default, each journal holds about 2000 lines; after that it rotates to the next file.
+
+Common command for recording a session:
+
+```bash
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session title" \
+  --summary "What changed" \
+  --commit "abc1234"
+```
+
+Planning or review work without a commit can also be recorded by using `--no-commit` or an empty commit value.
+
+## Relationship Between Workspace Memory And Tasks
+
+| System | What it stores |
+| --- | --- |
+| `.trellis/tasks/` | Requirements, design, research, and state for a specific task. |
+| `.trellis/workspace/` | Work records across tasks and sessions. |
+| `.trellis/spec/` | Engineering knowledge preserved as long-term conventions. |
+
+If information is only useful for the current task, put it in the task directory.  
+If information describes what happened in the current session, put it in the workspace journal.  
+If information should be followed every time code is written in the future, put it in spec.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change maximum journal lines | `max_journal_lines` in `.trellis/config.yaml`. |
+| Change session auto-commit message | `session_commit_message` in `.trellis/config.yaml`. |
+| Change session content format | `.trellis/scripts/add_session.py`. |
+| Change how workspace is displayed in context | `.trellis/scripts/common/session_context.py`. |
+
+## AI Usage Rules
+
+The AI should not treat workspace as the only source of truth. When resuming a task, read the current task first, then use workspace for background. After a task is complete, record important process notes in workspace; if long-term rules emerged, update spec.

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

@@ -0,0 +1,79 @@
+# Agents
+
+Trellis agent files define specialized roles. Common Trellis agents in a user project are:
+
+- `trellis-research`
+- `trellis-implement`
+- `trellis-check`
+
+File locations and formats differ by platform, but responsibility boundaries should stay consistent.
+
+## Agent Responsibilities
+
+| Agent | Responsibility |
+| --- | --- |
+| `trellis-research` | Investigate the question and write findings into the current task's `research/`. |
+| `trellis-implement` | Implement against `prd.md`, `info.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
+
+| 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.
+
+## 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.
+
+### agent pull
+
+The agent file instructs the agent to read after startup:
+
+- `python3 ./.trellis/scripts/task.py current --source`
+- current task `prd.md`
+- `info.md`
+- `implement.jsonl` or `check.jsonl`
+- spec/research files referenced by JSONL
+
+This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts.
+
+## 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. |
+
+## 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 active task and then find the PRD and JSONL.
+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.
+
+## 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.

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

@@ -0,0 +1,69 @@
+# 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.
+
+## Settings Responsibilities
+
+settings/config files usually register:
+
+- session-start hook: injects a Trellis overview when a new session starts or context resets.
+- workflow-state hook: injects the next-action hint for the current state on each user input.
+- 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:
+
+| 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` | Injects the next-action hint based on active task status. |
+| `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.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| AI should see more/less context in a new session | Platform `session-start` hook. |
+| Per-turn hint policy should change | State blocks in `.trellis/workflow.md` + `inject-workflow-state` hook. |
+| Sub-agent cannot read PRD/spec | `inject-subagent-context` hook or agent prelude. |
+| `task.py current` in shell has no active task | Shell/session bridge hook or platform environment variable configuration. |
+| Disable an automatic injection | The corresponding hook registration in settings/config. |
+
+## 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.
+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.
+
+## Troubleshooting Path
+
+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 current --source` command that the hook depends on.
+4. Check whether active task state exists in `.trellis/.runtime/sessions/`.
+5. Check whether the platform shell passes session identity.

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

@@ -0,0 +1,59 @@
+# 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.
+
+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**: `.claude/`, `.codex/`, `.cursor/`, `.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.
+
+## Platform File Categories
+
+| 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.
+
+Common capabilities:
+
+- 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.
+
+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 active task, PRD, and JSONL context after startup.
+
+To change how sub-agents load context, inspect the agent files themselves.
+
+### 3. Main-Session Workflow
+
+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.
+
+To change behavior, inspect platform workflows/skills/commands and `.trellis/workflow.md`.
+
+## Local Modification Order
+
+When the user asks to customize behavior for a platform, the AI should inspect files in this order:
+
+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.
+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/`.
+
+Do not modify only platform files and forget the shared workflow. Do not modify only `.trellis/workflow.md` and forget that platform entry points may still contain old descriptions.

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

@@ -0,0 +1,74 @@
+# 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.
+
+## Matrix
+
+| Platform | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | `--claude` | `.claude/` | `.claude/skills/` | `.claude/agents/` | `.claude/hooks/` + `.claude/settings.json` |
+| Cursor | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
+| OpenCode | `--opencode` | `.opencode/` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/plugins/` |
+| Codex | `--codex` | `.codex/` | `.agents/skills/` | `.codex/agents/` | `.codex/hooks/` + `.codex/hooks.json` |
+| Kilo | `--kilo` | `.kilocode/` | `.kilocode/skills/` | Usually none | `.kilocode/workflows/` |
+| Kiro | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` |
+| Gemini CLI | `--gemini` | `.gemini/` | `.gemini/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
+| Antigravity | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
+| Windsurf | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` |
+| Qoder | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` |
+| CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
+| GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
+| Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
+| Pi Agent | `--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.
+
+### Main-Session Workflow Platforms
+
+These platforms rely more on workflows/skills to guide the main session:
+
+- Kilo
+- Antigravity
+- Windsurf
+
+When changing behavior, inspect workflows and skills first. Do not assume Trellis sub-agents exist.
+
+### Shared `.agents/skills/`
+
+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.
+
+## 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.
+
+## 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:
+
+- Check the hook that settings registers.
+- Check the script that a command/prompt/workflow 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.