docs: add Trellis planning and project specs
This commit is contained in:
85
.cursor/skills/trellis-meta/SKILL.md
Normal file
85
.cursor/skills/trellis-meta/SKILL.md
Normal file
@@ -0,0 +1,85 @@
|
||||
---
|
||||
name: trellis-meta
|
||||
description: "Understand and customize the local Trellis architecture inside a user project. Use when modifying .trellis plus platform hooks, settings, agents, skills, commands, prompts, workflows, the channel runtime (trellis channel), bundled runtime agents under .trellis/agents/, selectable workflow templates, registry-backed spec refresh, cross-session memory (trellis mem) generated by trellis init, or AI-facing bundled skills (trellis-channel, trellis-session-insight, trellis-spec-bootstrap) and bundled-skill auto-dispatch flow."
|
||||
---
|
||||
|
||||
# Trellis Meta
|
||||
|
||||
This skill is for local Trellis users who have already run `trellis init` in a project. After reading it, an AI should understand the Trellis architecture, operating model, and customization entry points inside that user project, then modify the generated `.trellis/` and platform directory files according to the user's request.
|
||||
|
||||
Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: `trellis channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.trellis/channels/<project>/<channel>/events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.trellis/agents/{check,implement}.md` runtime definitions. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code, Codex, and Pi Agent JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@mindfoldhq/trellis` (CLI) and `@mindfoldhq/trellis-core` (SDK with `/channel`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.
|
||||
|
||||
The default operating scope is local files in the user project:
|
||||
|
||||
- `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state.
|
||||
- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills/<name>/SKILL.md`; subagent skills carry `runAs: subagent` frontmatter.
|
||||
- Shared skill layer: `.agents/skills/`.
|
||||
- User-owned channel store outside the project tree: `~/.trellis/channels/<project>/<channel>/events.jsonl`.
|
||||
- Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line).
|
||||
|
||||
Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@mindfoldhq/trellis` and `@mindfoldhq/trellis-core` ship as published packages sharing one version and one git tag per release.
|
||||
|
||||
## How To Use
|
||||
|
||||
1. Read `references/local-architecture/overview.md` first to establish the local Trellis system model.
|
||||
2. If the request involves a specific AI tool, read `references/platform-files/platform-map.md` and the relevant platform file notes.
|
||||
3. If the request involves multi-agent dispatch or channel workers, read `references/local-architecture/multi-agent-channel.md` and the bundled `.trellis/agents/` files.
|
||||
4. If the user wants to change behavior, read `references/customize-local/overview.md`, then open the specific customization topic.
|
||||
5. Before editing, read the actual files in the user project and treat local content as authoritative.
|
||||
|
||||
## References
|
||||
|
||||
### Local Architecture
|
||||
|
||||
- `references/local-architecture/overview.md`: The layered local Trellis architecture (workflow / persistence / platform / channel runtime) and customization principles.
|
||||
- `references/local-architecture/generated-files.md`: Files generated by `trellis init` and their customization boundaries, including `.trellis/agents/`.
|
||||
- `references/local-architecture/workflow.md`: Phases, routing, workflow-state blocks, and selectable workflow templates (`native`, `tdd`, `channel-driven-subagent-dispatch`, marketplace) in `.trellis/workflow.md`.
|
||||
- `references/local-architecture/task-system.md`: Task directories, active task, JSONL context, parent/child task trees, and task runtime.
|
||||
- `references/local-architecture/spec-system.md`: How `.trellis/spec/` is organized, injected, and refreshed from a `registry.spec` source.
|
||||
- `references/local-architecture/workspace-memory.md`: `.trellis/workspace/` journals plus `trellis mem` cross-session recall and the `@mindfoldhq/trellis-core/mem` SDK.
|
||||
- `references/local-architecture/context-injection.md`: Hooks, sub-agent preludes, and channel-runtime worker inbox routing.
|
||||
- `references/local-architecture/multi-agent-channel.md`: `trellis channel` subcommands, project-scoped event store, forum/thread channels, worker OOM guard, durable idempotency, and bundled `.trellis/agents/` runtime agents.
|
||||
- `references/local-architecture/bundled-skills.md`: Auto-dispatched bundled skills (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`) and how `getBundledSkillTemplates()` ships them to every platform skill root.
|
||||
|
||||
### Platform Files
|
||||
|
||||
- `references/platform-files/overview.md`: How shared `.trellis/` files relate to platform directories and the four platform integration modes (hook-driven, agent prelude, main-session workflow, channel runtime).
|
||||
- `references/platform-files/platform-map.md`: Platform directories and paths for skills, agents, hooks, and extensions across all 15 supported platforms including Reasonix and Pi's native `trellis_subagent` extension.
|
||||
- `references/platform-files/hooks-and-settings.md`: How settings/config files, hooks, plugins, and extensions connect to Trellis; covers `channel.worker_guard.*` and `codex.dispatch_mode`.
|
||||
- `references/platform-files/agents.md`: Per-platform `trellis-research` / `trellis-implement` / `trellis-check` sub-agent files plus bundled `.trellis/agents/{check,implement}.md` for the channel runtime.
|
||||
- `references/platform-files/skills-and-commands.md`: Differences between skills, commands, prompts, and workflows, plus how to change them.
|
||||
|
||||
### Local Customization
|
||||
|
||||
- `references/customize-local/overview.md`: Choose the right local customization entry point for the user's request.
|
||||
- `references/customize-local/change-workflow.md`: Change phases, routing, next actions, workflow-state, and the selected workflow template.
|
||||
- `references/customize-local/change-task-lifecycle.md`: Change task creation, status, archive behavior, parent/child links, archive slug collision handling, and lifecycle hooks.
|
||||
- `references/customize-local/change-context-loading.md`: Change how tasks, specs, journals, hook context, channel inbox messages, and `trellis mem` recall are loaded.
|
||||
- `references/customize-local/change-hooks.md`: Change platform hooks, settings, task lifecycle hooks (`hooks.after_*`), and shell session bridges.
|
||||
- `references/customize-local/change-agents.md`: Change research, implement, and check agent behavior across platform sub-agents, bundled channel runtime agents, and the Codex `dispatch_mode` toggle.
|
||||
- `references/customize-local/change-skills-or-commands.md`: Add or modify local skills, commands, prompts, and workflows; covers upstream bundled-skill auto-dispatch.
|
||||
- `references/customize-local/change-spec-structure.md`: Adjust the project spec structure under `.trellis/spec/`, including registry-backed sources.
|
||||
- `references/customize-local/add-project-local-conventions.md`: Put team rules into project-local specs or local skills.
|
||||
|
||||
## Current Rules
|
||||
|
||||
- `.trellis/workflow.md` is the local workflow source of truth; its initial content was selected from a workflow template (built-in `native`, `tdd`, `channel-driven-subagent-dispatch`, or a marketplace template) at `trellis init` time and can be re-selected via `trellis workflow --template <id>`. Missing `.trellis/agents/<name>.md` files referenced by the active template trigger a non-blocking stderr warning pointing at `trellis update`.
|
||||
- `.trellis/config.yaml` is the project-level Trellis configuration entry point. It hosts task lifecycle hooks (`hooks.after_create` / `after_start` / `after_finish` / `after_archive`), journal shape (`session_commit_message` / `max_journal_lines` / `session_auto_commit`), channel worker guard (`channel.worker_guard.idle_timeout` / `max_live_workers`), Codex dispatch mode (`codex.dispatch_mode: inline | sub-agent`), and the spec registry block (`registry.spec.source` + `registry.spec.template`).
|
||||
- `.trellis/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `trellis update`; local edits surface as "modified by user" conflicts in `.trellis/.template-hashes.json`.
|
||||
- `.trellis/tasks/` stores task PRDs, design notes, implement plans, research files, and JSONL context. Tasks form parent/child trees: `task.py create --parent <slug>`, `task.py add-subtask <parent> <child>`, `task.py remove-subtask <parent> <child>`, and `task.py list-context <task>`. `task.py create` rejects a slug already present in `.trellis/tasks/archive/**`.
|
||||
- `.trellis/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` and is recovered via `trellis mem search|extract|context`. The bundled `trellis-session-insight` skill teaches when to reach for `mem`.
|
||||
- `.trellis/agents/{check,implement}.md` are bundled, platform-agnostic channel runtime agent definitions loaded by `trellis channel spawn --agent <name>`. Editable; `trellis update` backfills missing ones. Editing the per-platform `trellis-implement.md` / `trellis-check.md` does **not** change channel-runtime worker behavior.
|
||||
- `~/.trellis/channels/<project>/<channel>/events.jsonl` is the channel runtime event log per project per channel. User-owned, file-locked sequence numbering, durable `idempotencyKey` support; never under `.trellis/`.
|
||||
- Bundled multi-file skills (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) are auto-dispatched to every platform skill root by `getBundledSkillTemplates()` in `packages/cli/src/templates/common/index.ts`. Dropping a new directory under `packages/cli/src/templates/common/bundled-skills/` (upstream) ships it to every platform on the next `trellis update`.
|
||||
- Platform settings/config files decide which hooks, agents, skills, commands, prompts, and workflows actually run. Reasonix has no settings file — behavior is encoded inside skill frontmatter.
|
||||
- `.trellis/.template-hashes.json` and `.trellis/.runtime/` are management/runtime state files. Confirm necessity before editing them.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not treat Trellis upstream source code as the default target for local customization.
|
||||
- Do not modify the global npm install directory or `node_modules/@mindfoldhq/trellis` or `node_modules/@mindfoldhq/trellis-core` to implement project needs; both packages ship in lockstep.
|
||||
- Do not overwrite user-modified local files with default templates; check `.trellis/.template-hashes.json` first and prefer `.new` sidecar files over destructive overwrites.
|
||||
- Do not put team-private project rules into any public bundled skill (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`); put project rules in `.trellis/spec/`, a project-local skill, the current task, or the workspace journal — `trellis update` will overwrite anything inside a bundled skill directory.
|
||||
- Do not hand-edit `~/.trellis/channels/<project>/<channel>/events.jsonl`; sequence numbers are assigned under a file lock and replay-safe writes go through the `trellis channel` CLI or the `@mindfoldhq/trellis-core/channel` SDK.
|
||||
- Do not edit `.claude/agents/trellis-implement.md` (or any other per-platform sub-agent file) when the goal is to change channel runtime worker behavior — edit `.trellis/agents/<name>.md` instead.
|
||||
- Do not describe removed or never-shipped mechanisms as current Trellis behavior; cross-check against the local `.trellis/config.yaml` and the installed CLI's `trellis --help` before claiming a knob exists.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Add Project-Local Conventions
|
||||
|
||||
Often the user does not need to change Trellis mechanics; they need local AI to understand their team's conventions. In that case, prefer `.trellis/spec/` or a project-local skill instead of editing `trellis-meta`.
|
||||
|
||||
## Where To Put Things
|
||||
|
||||
| Content type | Location |
|
||||
| --- | --- |
|
||||
| Rules code must follow | `.trellis/spec/<layer>/` |
|
||||
| Cross-layer thinking methods | `.trellis/spec/guides/` |
|
||||
| AI capability for a project-specific flow | Platform-local skill |
|
||||
| One-off task material | `.trellis/tasks/<task>/` |
|
||||
| Session summary | `.trellis/workspace/<developer>/journal-N.md` |
|
||||
|
||||
## Create A Project-Local Skill
|
||||
|
||||
If the user wants AI to know "how this project customizes Trellis," create a local skill:
|
||||
|
||||
```text
|
||||
.claude/skills/trellis-local/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```md
|
||||
---
|
||||
name: trellis-local
|
||||
description: "Project-local Trellis customizations for this repository. Use when changing this project's Trellis workflow, hooks, local agents, or team-specific conventions."
|
||||
---
|
||||
|
||||
# Trellis Local
|
||||
|
||||
## Local Scope
|
||||
|
||||
This skill documents this repository's Trellis customizations only.
|
||||
|
||||
## Custom Workflow Rules
|
||||
|
||||
- ...
|
||||
|
||||
## Local Hook Changes
|
||||
|
||||
- ...
|
||||
|
||||
## Local Agent Changes
|
||||
|
||||
- ...
|
||||
```
|
||||
|
||||
For multi-platform projects, place equivalent versions in other platform skill directories, or use `.agents/skills/` for platforms that support the shared layer.
|
||||
|
||||
## Write To `.trellis/spec/`
|
||||
|
||||
If the content is a coding convention, write it to spec. Examples:
|
||||
|
||||
```text
|
||||
.trellis/spec/backend/error-handling.md
|
||||
.trellis/spec/frontend/components.md
|
||||
.trellis/spec/guides/cross-platform-thinking-guide.md
|
||||
```
|
||||
|
||||
After writing it, update the corresponding `index.md` so AI can find the new rule from the entry point.
|
||||
|
||||
## Make The Current Task Use New Conventions
|
||||
|
||||
After writing a spec, add it to the current task context:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/backend/error-handling.md" "Error handling conventions"
|
||||
python3 ./.trellis/scripts/task.py add-context <task> check ".trellis/spec/backend/error-handling.md" "Review error handling"
|
||||
```
|
||||
|
||||
## Do Not Store Project-Private Rules In `trellis-meta`
|
||||
|
||||
`trellis-meta` is a public skill for understanding Trellis architecture and local customization entry points. Put project-private content in:
|
||||
|
||||
- `.trellis/spec/`
|
||||
- a project-local skill
|
||||
- the current task
|
||||
- workspace journal
|
||||
|
||||
This prevents future updates to Trellis's built-in `trellis-meta` from overwriting the team's own conventions.
|
||||
@@ -0,0 +1,56 @@
|
||||
# Change Local Agents
|
||||
|
||||
When the user wants to change `trellis-research`, `trellis-implement`, or `trellis-check` behavior, edit platform agent files in the user project.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. Target platform agent directory
|
||||
2. `.trellis/workflow.md` Phase 2 / research routing
|
||||
3. Current task `prd.md`
|
||||
4. Current task `implement.jsonl` / `check.jsonl`
|
||||
5. Relevant hook or agent prelude
|
||||
|
||||
## Common Paths
|
||||
|
||||
| Platform | 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` |
|
||||
| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) |
|
||||
| ZCode | `.zcode/cli/agents/trellis-*.md` |
|
||||
|
||||
Use the actual paths in the user project as authoritative.
|
||||
|
||||
## Common Needs
|
||||
|
||||
| Need | Which agent to edit |
|
||||
| --- | --- |
|
||||
| Research must write files, not only reply in chat | `trellis-research` |
|
||||
| Certain local specs must be read before implementation | `trellis-implement` + `implement.jsonl` configuration rules |
|
||||
| Specific commands must run during checking | `trellis-check` |
|
||||
| Agent must not modify certain directories | The corresponding agent's write boundary instructions |
|
||||
| Agent output format must be fixed | The corresponding agent's final/reporting instructions |
|
||||
|
||||
## Modification Principles
|
||||
|
||||
1. **Preserve role boundaries**: research investigates and persists; implement writes implementation; check reviews and fixes.
|
||||
2. **Do not hard-code project specs into agents**: long-term specs belong in `.trellis/spec/`; agents are responsible for reading them.
|
||||
3. **Make read order explicit**: active task -> PRD -> info -> JSONL -> spec/research.
|
||||
4. **Make write boundaries explicit**: which directories may be written and which may not.
|
||||
5. **Synchronize across platforms**: when the user configured multiple platforms, decide whether to change only the current platform or all platform agents.
|
||||
|
||||
## Agent Pull Platforms
|
||||
|
||||
If an agent file contains a prelude for "read task/context after startup," do not remove those steps when editing. Otherwise the agent will work only from chat context and bypass Trellis's core mechanism.
|
||||
|
||||
## Hook Push Platforms
|
||||
|
||||
If context is injected by a hook, the agent file should still retain responsibility boundaries. Do not remove PRD/spec requirements from the agent just because a hook injects context.
|
||||
@@ -0,0 +1,84 @@
|
||||
# Change Local Context Loading
|
||||
|
||||
Context loading determines when AI reads workflow, task, spec, research, workspace, and git status. Read this page when the user says "AI does not know the current task," "the agent did not read specs," or "there is too much/too little context."
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. `.trellis/workflow.md`
|
||||
2. `.trellis/scripts/get_context.py`
|
||||
3. `.trellis/scripts/common/session_context.py`
|
||||
4. `.trellis/scripts/common/task_context.py`
|
||||
5. `.trellis/scripts/common/active_task.py`
|
||||
6. Current platform hooks or agent files
|
||||
7. The current task's `implement.jsonl` / `check.jsonl`
|
||||
|
||||
## Context Sources
|
||||
|
||||
| Source | Purpose |
|
||||
| --- | --- |
|
||||
| `.trellis/workflow.md` | Workflow and next-action hints. |
|
||||
| `.trellis/tasks/<task>/prd.md` | Current task requirements. |
|
||||
| `.trellis/tasks/<task>/design.md` | Complex task technical design. |
|
||||
| `.trellis/tasks/<task>/implement.md` | Complex task execution plan. |
|
||||
| `.trellis/tasks/<task>/implement.jsonl` | Spec/research to read before implementation. |
|
||||
| `.trellis/tasks/<task>/check.jsonl` | Spec/research to read during checking. |
|
||||
| `.trellis/spec/` | Project specs. |
|
||||
| `.trellis/workspace/` | Session records. |
|
||||
| git status | Current working tree changes. |
|
||||
|
||||
## Common Needs And Edit Points
|
||||
|
||||
| Need | Edit point |
|
||||
| --- | --- |
|
||||
| Inject more/less information in new sessions | `session_context.py` or the platform `session-start` hook. |
|
||||
| Change hints on each user input | `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The `inject-workflow-state` hook is parser-only and reads the block verbatim. |
|
||||
| Agent did not read specs | Task JSONL, agent prelude, `inject-subagent-context` hook. |
|
||||
| Active task is lost | `active_task.py` and platform session identity propagation. |
|
||||
| Change JSONL validation rules | `task_context.py`. |
|
||||
|
||||
## JSONL Rules
|
||||
|
||||
`implement.jsonl` / `check.jsonl` are the key context loading interface:
|
||||
|
||||
```jsonl
|
||||
{"file": ".trellis/spec/backend/index.md", "reason": "Backend conventions"}
|
||||
{"file": ".trellis/tasks/04-28-x/research/api.md", "reason": "API research"}
|
||||
```
|
||||
|
||||
Include only spec/research files. Do not put code files that will be modified into these manifests; agents read code files themselves during implementation.
|
||||
|
||||
## Change Session Context
|
||||
|
||||
If the user wants every new session to see more project state, edit:
|
||||
|
||||
- `.trellis/scripts/common/session_context.py`
|
||||
- the corresponding platform `session-start` hook
|
||||
|
||||
Context cannot grow without bound. Prefer injecting indexes and paths so the AI can read detailed files on demand.
|
||||
|
||||
## Change Sub-Agent Context
|
||||
|
||||
First determine which mode the platform uses:
|
||||
|
||||
- hook push: edit the `inject-subagent-context` hook.
|
||||
- agent pull: edit the read steps in the corresponding `trellis-implement` / `trellis-check` agent file.
|
||||
|
||||
In both modes, make sure the agent ultimately reads:
|
||||
|
||||
1. active task
|
||||
2. the corresponding JSONL
|
||||
3. spec/research referenced by the JSONL
|
||||
4. `prd.md`
|
||||
5. `design.md` if present
|
||||
6. `implement.md` if present
|
||||
|
||||
## Troubleshooting Order
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
python3 ./.trellis/scripts/task.py list-context <task>
|
||||
python3 ./.trellis/scripts/task.py validate <task>
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
Confirm the task and JSONL are correct before editing hooks/agents.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Change Local Hooks
|
||||
|
||||
Hooks are the automation layer that connects a platform to Trellis. When the user wants to change "when context is injected," "how shell commands inherit a session," or "which files are read before an agent starts," hooks are usually the edit point.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. Target platform settings/config, such as `.claude/settings.json`, `.codex/hooks.json`, `.cursor/hooks.json`, `.trae/hooks.json`
|
||||
2. Target platform hooks directory
|
||||
3. `.trellis/scripts/common/active_task.py`
|
||||
4. `.trellis/scripts/common/session_context.py`
|
||||
5. `.trellis/workflow.md`
|
||||
|
||||
## Common Hook Types
|
||||
|
||||
| Hook | Purpose |
|
||||
| --- | --- |
|
||||
| session-start | Injects a Trellis overview when a session starts, clears, or compacts. |
|
||||
| workflow-state | Injects a state hint on each user input. |
|
||||
| sub-agent context | Injects PRD/spec/research before an agent starts. |
|
||||
| shell session bridge | Lets `task.py` commands in shell see the same session identity. |
|
||||
|
||||
## Modification Steps
|
||||
|
||||
1. Find the hook registration in settings/config.
|
||||
2. Confirm the registered script path exists.
|
||||
3. Read the hook script and identify inputs, outputs, and called `.trellis/scripts/`.
|
||||
4. Modify hook behavior.
|
||||
5. If the hook depends on workflow content, synchronize `.trellis/workflow.md`.
|
||||
|
||||
## Example: Change New-Session Injection Content
|
||||
|
||||
First find the session-start hook:
|
||||
|
||||
```text
|
||||
.claude/settings.json
|
||||
.claude/hooks/session-start.py
|
||||
```
|
||||
|
||||
If the hook ultimately calls `.trellis/scripts/get_context.py` or `session_context.py`, editing the local script is usually more robust than hard-coding content in the hook.
|
||||
|
||||
## Example: Agent Did Not Read JSONL
|
||||
|
||||
First confirm:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py current --source
|
||||
python3 ./.trellis/scripts/task.py validate <task>
|
||||
```
|
||||
|
||||
If the task and JSONL are correct, determine whether the platform uses hook push or agent pull. For hook push, edit `inject-subagent-context`; for agent pull, edit the agent file.
|
||||
|
||||
## Notes
|
||||
|
||||
- Settings handle registration, hook scripts handle behavior; inspect both together.
|
||||
- Different platforms support different hook events. Do not directly copy another platform's settings.
|
||||
- Hooks should read project-local `.trellis/`; they should not depend on Trellis upstream source paths.
|
||||
- Hook failures should produce visible errors so AI does not silently lose context.
|
||||
@@ -0,0 +1,123 @@
|
||||
# Change Local Skills, Commands, Prompts, And Workflows
|
||||
|
||||
When the user wants to change AI entry points, auto-trigger rules, or explicit command behavior, edit skills, commands, prompts, or workflows in local platform directories.
|
||||
|
||||
Before editing, classify the skill you are about to touch:
|
||||
|
||||
- **Bundled upstream skill** — `trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`. Source of truth lives in the Trellis CLI repo under `packages/cli/src/templates/common/bundled-skills/<name>/`; auto-dispatched to every platform's skill root by `getBundledSkillTemplates()` on `trellis init` / `trellis update`. Local edits here are tracked by `.trellis/.template-hashes.json` and will be flagged on the next update.
|
||||
- **Project-local skill** — anything else under `.{platform}/skills/`. Owned by the user; not refreshed by `trellis update`.
|
||||
|
||||
The remainder of this file uses "skill" for the local file; the override and conflict rules differ between the two cases.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. `.trellis/workflow.md`
|
||||
2. Target platform skill/command/prompt/workflow directory
|
||||
3. Related agent or hook files
|
||||
4. Whether project rules already exist in `.trellis/spec/`
|
||||
5. `.trellis/.template-hashes.json` — confirms whether the skill you are about to edit is upstream-owned (entry present) or project-local (entry absent)
|
||||
|
||||
## Which Entry Type To Choose
|
||||
|
||||
| Goal | Recommendation |
|
||||
| --- | --- |
|
||||
| AI should automatically know a capability | Add or modify a skill. |
|
||||
| User wants to trigger manually with a command | Add or modify a command/prompt/workflow. |
|
||||
| Team project conventions | Prefer `.trellis/spec/` or a project-local skill — never a bundled skill directory. |
|
||||
| Tweak a bundled skill (`trellis-meta` et al.) for the user's own project | Create a project-local sibling skill (different name) that overrides intent, or edit `.trellis/spec/`. Edits inside the bundled skill directory survive only until the next `trellis update` and will need a "keep" choice each time. |
|
||||
| Contribute the change back upstream | Edit `packages/cli/src/templates/common/bundled-skills/<name>/` in the Trellis CLI repo, not the deployed copy. |
|
||||
| Change Trellis flow semantics | Synchronize `.trellis/workflow.md`. |
|
||||
|
||||
## Modify A Skill
|
||||
|
||||
A skill is usually:
|
||||
|
||||
```text
|
||||
<skill-name>/
|
||||
├── SKILL.md
|
||||
└── references/
|
||||
```
|
||||
|
||||
`SKILL.md` should be short and responsible for triggering/routing. Put long content in `references/` so AI can read it on demand.
|
||||
|
||||
The frontmatter description should specify when to use the skill. Example:
|
||||
|
||||
```yaml
|
||||
description: "Use when customizing this project's deployment workflow and release checklist."
|
||||
```
|
||||
|
||||
Do not write vague descriptions such as "helpful project skill"; they can trigger incorrectly.
|
||||
|
||||
### Bundled vs. Project-Local
|
||||
|
||||
The same directory shape is used by two very different ownership models:
|
||||
|
||||
| Aspect | Bundled (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) | Project-local |
|
||||
| --- | --- | --- |
|
||||
| Source of truth | `packages/cli/src/templates/common/bundled-skills/<name>/` in Trellis CLI repo | Inside the user project itself |
|
||||
| Dispatch | Auto-dispatched to every platform skill root by `getBundledSkillTemplates()` (`packages/cli/src/templates/common/index.ts`) on `trellis init` / `trellis update` | Created by the user (or another skill) and never moved |
|
||||
| Hash tracking | Every file recorded in `.trellis/.template-hashes.json`; conflict prompt on update | Not tracked |
|
||||
| Editing locally | Allowed but will be marked "modified by user" on next update | Free editing |
|
||||
| The right way to customize | Add a *new* project-local skill with a *different* name that supplements (or supersedes) the bundled one | Edit the file directly |
|
||||
|
||||
If the goal is "make my project's AI behave differently when discussing release notes," the answer is almost always a project-local skill, not surgery on `trellis-meta/`.
|
||||
|
||||
## Modify A Command/Prompt/Workflow
|
||||
|
||||
Explicit entry points should state:
|
||||
|
||||
- How the user triggers it.
|
||||
- Which `.trellis/` files to read.
|
||||
- Which scripts to run.
|
||||
- How to report after completion.
|
||||
|
||||
If a command only repeats workflow rules, prefer making it reference/read `.trellis/workflow.md` instead of maintaining a second copy of the flow.
|
||||
|
||||
## Common Paths
|
||||
|
||||
| Platform | Entry directories |
|
||||
| --- | --- |
|
||||
| Claude Code | `.claude/skills/`, `.claude/commands/` |
|
||||
| Cursor | `.cursor/skills/`, `.cursor/commands/` |
|
||||
| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
|
||||
| Codex | `.agents/skills/`, `.codex/skills/` |
|
||||
| Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
|
||||
| Kiro | `.kiro/skills/` |
|
||||
| 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/` |
|
||||
| Reasonix | `.reasonix/skills/` (no separate commands dir; slash commands built into the platform) |
|
||||
| ZCode | `.agents/skills/`, `.zcode/commands/` |
|
||||
| Kilo / Antigravity / Devin | workflows + skills |
|
||||
|
||||
Every directory above is a deploy target for the four bundled skills. Each platform receives a full copy on `trellis init` and refresh on `trellis update`; nothing has to be wired by hand.
|
||||
|
||||
## Add A Project-Local Skill
|
||||
|
||||
If the user wants to document team-private customizations, create a project-local skill — never put project-private content into a bundled skill directory, since `trellis update` will overwrite it.
|
||||
|
||||
```text
|
||||
.claude/skills/project-trellis-local/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
For multi-platform projects, add equivalent versions in each platform skill directory, or use `.agents/skills/` on platforms that support the shared layer (Codex, Gemini CLI).
|
||||
|
||||
Pick a name that does **not** collide with the bundled set:
|
||||
|
||||
- `trellis-meta`
|
||||
- `trellis-spec-bootstrap`
|
||||
- `trellis-session-insight`
|
||||
- `trellis-channel`
|
||||
|
||||
A reused name causes `getBundledSkillTemplates()` to overwrite the project-local copy on the next update. A common convention is to prefix the project name: `acme-trellis-deploy`, `acme-trellis-onboarding`.
|
||||
|
||||
## Notes
|
||||
|
||||
- Do not mix every platform's syntax into one file.
|
||||
- Do not change only one platform entry point while claiming all platforms are supported.
|
||||
- Do not hide long-term engineering conventions inside a command; write them to `.trellis/spec/`.
|
||||
- Do not hand-edit files inside `trellis-meta/`, `trellis-spec-bootstrap/`, `trellis-session-insight/`, or `trellis-channel/` under any `.{platform}/skills/` directory expecting the change to persist — they are bundled and refreshed by `trellis update`. Either contribute upstream or add a project-local skill that complements them.
|
||||
- After `trellis update` reports a "modified by you" conflict on a bundled skill file, choose **keep** only if you accept maintaining the divergence by hand; otherwise accept the overwrite and re-apply the intent as a project-local skill.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Change Local Spec Structure
|
||||
|
||||
When the user wants to change the engineering conventions AI follows, add new spec layers, or adjust monorepo package mapping, edit `.trellis/spec/` and `.trellis/config.yaml`.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. `.trellis/config.yaml`
|
||||
2. `.trellis/spec/`
|
||||
3. `.trellis/workflow.md` planning artifact guidance and Phase 3.3
|
||||
4. Current task `implement.jsonl` / `check.jsonl`
|
||||
|
||||
## Common Needs
|
||||
|
||||
| Need | Edit location |
|
||||
| --- | --- |
|
||||
| Add backend/frontend/docs/test spec layer | `.trellis/spec/<layer>/` or `.trellis/spec/<package>/<layer>/` |
|
||||
| Add shared thinking guides | `.trellis/spec/guides/` |
|
||||
| Adjust monorepo packages | `packages` in `.trellis/config.yaml` |
|
||||
| Change default package | `default_package` in `.trellis/config.yaml` |
|
||||
| Control spec scanning scope | `spec_scope` in `.trellis/config.yaml` |
|
||||
| Make a task read a new spec | Task `implement.jsonl` / `check.jsonl` |
|
||||
|
||||
## Add A Spec Layer
|
||||
|
||||
Single-repository example:
|
||||
|
||||
```text
|
||||
.trellis/spec/security/
|
||||
├── index.md
|
||||
└── auth.md
|
||||
```
|
||||
|
||||
Monorepo example:
|
||||
|
||||
```text
|
||||
.trellis/spec/webapp/security/
|
||||
├── index.md
|
||||
└── auth.md
|
||||
```
|
||||
|
||||
`index.md` should include:
|
||||
|
||||
- What code this layer applies to.
|
||||
- Pre-Development Checklist.
|
||||
- Quality Check.
|
||||
- Links to specific guideline files.
|
||||
|
||||
## Update Context
|
||||
|
||||
Adding a spec does not mean every task automatically reads it. The current task must reference it in JSONL:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py add-context <task> implement ".trellis/spec/webapp/security/index.md" "Security conventions"
|
||||
python3 ./.trellis/scripts/task.py add-context <task> check ".trellis/spec/webapp/security/index.md" "Security review rules"
|
||||
```
|
||||
|
||||
## Change Monorepo Packages
|
||||
|
||||
Example `.trellis/config.yaml`:
|
||||
|
||||
```yaml
|
||||
packages:
|
||||
webapp:
|
||||
path: apps/web
|
||||
api:
|
||||
path: apps/api
|
||||
default_package: webapp
|
||||
```
|
||||
|
||||
After editing, run:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/get_context.py --mode packages
|
||||
```
|
||||
|
||||
Use this output to confirm AI can see the correct packages and spec layers.
|
||||
|
||||
## Notes
|
||||
|
||||
- Specs are user project conventions and can be changed according to project needs.
|
||||
- Do not put temporary task information into specs; put temporary information in the task.
|
||||
- Do not put long-term conventions only in agents or commands; preserve them in specs.
|
||||
- After changing spec structure, check whether existing task JSONL files still point to files that exist.
|
||||
@@ -0,0 +1,90 @@
|
||||
# Change Local Task Lifecycle
|
||||
|
||||
Task lifecycle includes creation, start, context configuration, finish, archive, parent/child tasks, and lifecycle hooks. The default customization targets are `.trellis/tasks/`, `.trellis/config.yaml`, and `.trellis/scripts/`.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. `.trellis/workflow.md`
|
||||
2. `.trellis/config.yaml`
|
||||
3. `.trellis/scripts/task.py`
|
||||
4. `.trellis/scripts/common/task_store.py`
|
||||
5. `.trellis/scripts/common/task_utils.py`
|
||||
6. The current task's `.trellis/tasks/<task>/task.json`
|
||||
|
||||
## Common Needs And Edit Points
|
||||
|
||||
| Need | Edit point |
|
||||
| --- | --- |
|
||||
| Automatically sync an external system after task creation | `hooks.after_create` in `.trellis/config.yaml`. |
|
||||
| Automatically update status after task start | `hooks.after_start` in `.trellis/config.yaml`. |
|
||||
| Run a script after task finish | `hooks.after_finish` in `.trellis/config.yaml`. |
|
||||
| Clean external resources after archive | `hooks.after_archive` in `.trellis/config.yaml`. |
|
||||
| Change default task fields | `.trellis/scripts/common/task_store.py`. |
|
||||
| Change task parsing/search | `.trellis/scripts/common/task_utils.py`. |
|
||||
| Change active task behavior | `.trellis/scripts/common/active_task.py`. |
|
||||
|
||||
## lifecycle hooks
|
||||
|
||||
`.trellis/config.yaml` supports:
|
||||
|
||||
```yaml
|
||||
hooks:
|
||||
after_create:
|
||||
- "python3 .trellis/scripts/hooks/my_sync.py create"
|
||||
after_start:
|
||||
- "python3 .trellis/scripts/hooks/my_sync.py start"
|
||||
after_finish:
|
||||
- "python3 .trellis/scripts/hooks/my_sync.py finish"
|
||||
after_archive:
|
||||
- "python3 .trellis/scripts/hooks/my_sync.py archive"
|
||||
```
|
||||
|
||||
Hook commands receive the `TASK_JSON_PATH` environment variable, pointing to the current task's `task.json`. Hook failures should usually warn, but not block the main task operation.
|
||||
|
||||
## Change Task Fields
|
||||
|
||||
If the user wants to add project-local fields, prefer putting them under `meta` in `task.json` to avoid breaking existing scripts' assumptions about standard fields.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
"meta": {
|
||||
"linearIssue": "ENG-123",
|
||||
"risk": "high"
|
||||
}
|
||||
```
|
||||
|
||||
If standard fields really need to change, inspect every local script that reads `task.json`.
|
||||
|
||||
## Change Active Task
|
||||
|
||||
Active task is session-level state stored in `.trellis/.runtime/sessions/`. Do not fall back to a global `.current-task` model. If the user wants to change active task behavior, edit:
|
||||
|
||||
- `.trellis/scripts/common/active_task.py`
|
||||
- platform hooks or shell session bridges
|
||||
- active task descriptions in `.trellis/workflow.md`
|
||||
|
||||
### `task.py create` Sets the Active Pointer
|
||||
|
||||
`cmd_create` in `.trellis/scripts/common/task_store.py` calls `set_active_task` best-effort right after writing the new task directory. The behavior:
|
||||
|
||||
- When the calling shell carries session identity (`TRELLIS_CONTEXT_ID` env var, or any platform-specific session env that `resolve_context_key` recognizes — see `active_task.py:_ENV_SESSION_KEYS`), the per-session pointer at `.trellis/.runtime/sessions/<context_key>.json` is rewritten to point at the new task. The task's `status=planning` and `[workflow-state:planning]` fires on the very next `UserPromptSubmit`.
|
||||
- When session identity is unavailable (raw CLI invocation outside an AI session, or a platform that doesn't propagate identity to shell), the task directory is still created and `status=planning` is still written, but the active pointer is left untouched. The user can attach the task later with `task.py start <dir>` once they're back in an AI session.
|
||||
|
||||
This makes `[workflow-state:planning]` the live breadcrumb during the brainstorm and JSONL curation work that follows `task.py create`. The pre-R7 behavior left the breadcrumb stuck on `no_task` until `task.py start`, so the planning block was effectively dead text.
|
||||
|
||||
If you fork `task.py` to add a new creation path (e.g. an external import that bypasses `cmd_create`), audit whether your path also calls `set_active_task`. Without that call, your created tasks will not surface as active. The full status writer table is in `.trellis/spec/cli/backend/workflow-state-contract.md`.
|
||||
|
||||
## Modification Steps
|
||||
|
||||
1. Confirm the current task with `python3 ./.trellis/scripts/task.py current --source`.
|
||||
2. Read the current task's `task.json` and confirm status and fields.
|
||||
3. For configuration needs, edit `.trellis/config.yaml` first.
|
||||
4. For script behavior needs, then edit `.trellis/scripts/`.
|
||||
5. If the AI flow changed, synchronize `.trellis/workflow.md`.
|
||||
|
||||
## Do Not
|
||||
|
||||
- Do not directly edit `.trellis/.runtime/sessions/` to "fix" business state.
|
||||
- Do not hard-code project-private fields into scripts; prefer `meta`.
|
||||
- Do not default to asking the user to fork Trellis CLI.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Change Local Workflow
|
||||
|
||||
When the user wants to change Trellis phases, next-action hints, whether to create tasks, whether to use sub-agents, or when to check/wrap up, edit `.trellis/workflow.md` first.
|
||||
|
||||
## Read These Files First
|
||||
|
||||
1. `.trellis/workflow.md`
|
||||
2. Entry files for the current platform, such as skills/commands/prompts/workflows
|
||||
3. The current task's `task.json` and `prd.md`
|
||||
|
||||
## Common Needs And Edit Points
|
||||
|
||||
| Need | Edit point |
|
||||
| --- | --- |
|
||||
| Change phase names or phase order | `Phase Index` and the corresponding Phase sections. |
|
||||
| Change whether to create a task when there is no task | `[workflow-state:no_task]` state block. |
|
||||
| Change the next step during planning | Phase 1 and `[workflow-state:planning]`. |
|
||||
| Change whether an agent is required during in_progress | Phase 2 and `[workflow-state:in_progress]`. |
|
||||
| Change wrap-up after completion | Phase 3 and `[workflow-state:completed]`. |
|
||||
| Change which skill a user intent triggers | `Skill Routing` table. |
|
||||
|
||||
## Modification Steps
|
||||
|
||||
1. Find the relevant section in `.trellis/workflow.md`.
|
||||
2. When changing rules, keep explicit trigger conditions and next actions.
|
||||
3. If adding or renaming a skill/agent, synchronize the corresponding files in platform directories.
|
||||
4. Workflow-state changes only need an edit to the `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The hook is parser-only — it reads whatever you put in the block. Keep the opening and closing tags' STATUS strings identical (`[workflow-state:foo]…[/workflow-state:foo]`); mismatched STATUS pairs are silently dropped.
|
||||
5. Make the AI reread `.trellis/workflow.md`; do not keep using rules from the old conversation.
|
||||
|
||||
## Example: Relax Task Creation Requirements
|
||||
|
||||
To change when task creation can be skipped, usually edit `[workflow-state:no_task]`:
|
||||
|
||||
```md
|
||||
[workflow-state:no_task]
|
||||
Task is not required when the answer is a one-reply explanation, no files are changed, and no research is needed.
|
||||
[/workflow-state:no_task]
|
||||
```
|
||||
|
||||
If the formal Phase 1 flow also needs to change, synchronize the Phase 1 section.
|
||||
|
||||
## Example: One Platform Does Not Use Sub-Agents
|
||||
|
||||
If the user wants only one platform to avoid sub-agents, first confirm whether that platform has a separate group in the workflow. Then change Phase 2 routing for that platform group instead of deleting all `trellis-implement` / `trellis-check` instructions across platforms.
|
||||
|
||||
## `/trellis:continue` Route Table
|
||||
|
||||
`/trellis:continue` resumes a task by deciding which phase step to load next. The decision combines `task.json.status` with the presence of artifacts inside the task directory. The mapping is fixed in the command itself; forks that add custom statuses must extend both the workflow.md tag block and this table.
|
||||
|
||||
| `status` | Artifact state | Resume at |
|
||||
| --- | --- | --- |
|
||||
| `planning` | `prd.md` missing | Phase 1.1 (load `trellis-brainstorm`) |
|
||||
| `planning` | lightweight task with `prd.md` complete | ask for start review, then run `task.py start` |
|
||||
| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts |
|
||||
| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | ask for start review, then run `task.py start` |
|
||||
| `in_progress` | no implementation in conversation history | Phase 2.1 (`trellis-implement`) |
|
||||
| `in_progress` | implementation done, no `trellis-check` run | Phase 2.2 (`trellis-check`) |
|
||||
| `in_progress` | check passed | Phase 3.3 (spec update) → 3.4 (commit) |
|
||||
| `completed` | task is still in active tree | Phase 3.5 (run `/trellis:finish-work` to archive) |
|
||||
|
||||
When you add a custom status (e.g. `in-review`), add a `[workflow-state:in-review]` block in `.trellis/workflow.md` for the per-turn breadcrumb AND extend this route table — usually by editing the `/trellis:continue` command file (`.{platform}/commands/trellis/continue.md` or equivalent) to add a row that decides where to resume from. Without the route entry, `/trellis:continue` will fall through to a default branch and the user will not land on the step you intended.
|
||||
|
||||
## Notes
|
||||
|
||||
`.trellis/workflow.md` is the local project workflow, not an immutable template. The user can adapt it to team habits. After editing it, platform entry files may still contain old descriptions, so inspect them too.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Local Customization Overview
|
||||
|
||||
This directory is for local AI working in a user project where Trellis was installed through npm and `trellis init` has already been run. The AI should modify generated `.trellis/` and platform directories inside the project, not Trellis CLI upstream source code.
|
||||
|
||||
## First Determine What The User Actually Wants To Change
|
||||
|
||||
| User wording | Read first |
|
||||
| --- | --- |
|
||||
| "Change the Trellis flow / phases / next prompt" | `change-workflow.md` |
|
||||
| "Change task creation, status, archive, or hooks" | `change-task-lifecycle.md` |
|
||||
| "AI did not read context / change injected content" | `change-context-loading.md` |
|
||||
| "A platform hook is not behaving as expected" | `change-hooks.md` |
|
||||
| "Change implement/check/research agent behavior" | `change-agents.md` |
|
||||
| "Add a skill/command/workflow/prompt" | `change-skills-or-commands.md` |
|
||||
| "Adjust the project spec structure" | `change-spec-structure.md` |
|
||||
| "Add team conventions and local notes" | `add-project-local-conventions.md` |
|
||||
|
||||
## General Operation Order
|
||||
|
||||
1. **Confirm platform and directories**: inspect which directories exist, such as `.claude/`, `.codex/`, `.cursor/`, `.zcode/`.
|
||||
2. **Confirm the current active task**: run `python3 ./.trellis/scripts/task.py current --source`.
|
||||
3. **Read the local source of truth**: prefer `.trellis/workflow.md`, `.trellis/config.yaml`, and relevant platform files.
|
||||
4. **Modify narrowly**: edit only files related to the user's request.
|
||||
5. **Synchronize semantics**: if a shared flow changes, check whether platform entry points also need changes; if a platform entry changes, check whether `.trellis/workflow.md` still agrees.
|
||||
|
||||
## Local File Priority
|
||||
|
||||
| Layer | Files |
|
||||
| --- | --- |
|
||||
| Workflow | `.trellis/workflow.md` |
|
||||
| Project configuration | `.trellis/config.yaml` |
|
||||
| Task material | `.trellis/tasks/<task>/` |
|
||||
| Project specs | `.trellis/spec/` |
|
||||
| Runtime scripts | `.trellis/scripts/` |
|
||||
| Platform integration | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.zcode/`, and similar directories |
|
||||
| Shared skill | `.agents/skills/` |
|
||||
|
||||
## Things Not To Do By Default
|
||||
|
||||
- Do not edit the global npm install directory.
|
||||
- Do not edit `node_modules/@mindfoldhq/trellis`.
|
||||
- Do not assume the user has the Trellis GitHub repository.
|
||||
- Do not overwrite local files already modified by the user with default templates.
|
||||
- Do not put team project rules into public `trellis-meta`; project rules belong in `.trellis/spec/` or a local skill.
|
||||
|
||||
## When To Inspect Upstream Source
|
||||
|
||||
Switch to an upstream source-code perspective only when the user explicitly expresses one of these goals:
|
||||
|
||||
- "I want to open a PR to Trellis"
|
||||
- "I want to change npm package publish contents"
|
||||
- "I want to fork Trellis"
|
||||
- "I want to modify the generation logic for `trellis init/update`"
|
||||
|
||||
Otherwise, default to modifying local Trellis files inside the user project.
|
||||
@@ -0,0 +1,146 @@
|
||||
# Bundled Skills
|
||||
|
||||
"Bundled skills" are multi-file built-in skills shipped inside the Trellis CLI npm package. Unlike marketplace skills (which a user installs separately into their own `.claude/skills/` or other platform skill root), bundled skills are written automatically into every supported platform's skill root by `trellis init` and kept in sync by `trellis update`. They are part of Trellis itself, not third-party content.
|
||||
|
||||
A bundled skill is a directory under `packages/cli/src/templates/common/bundled-skills/<skill>/` that already contains its own `SKILL.md` (with YAML frontmatter) plus optional `references/`, assets, or other supporting files. Trellis copies the whole directory tree as-is into each platform's skill root, so references stay lazy-loadable instead of being flattened into one oversized `SKILL.md`.
|
||||
|
||||
## What Counts As Bundled (vs. Adjacent Concepts)
|
||||
|
||||
| Source path | Type | How it ships |
|
||||
| --- | --- | --- |
|
||||
| `templates/common/bundled-skills/<name>/` | Bundled skill (multi-file) | Whole directory copied to every platform skill root |
|
||||
| `templates/common/skills/<name>.md` | Single-file workflow skill | Wrapped with frontmatter, written as `<root>/<name>/SKILL.md` |
|
||||
| `templates/common/commands/<name>.md` | Slash command / prompt | Written to each platform's command directory (`.claude/commands/trellis/`, `.cursor/commands/trellis-*.md`, `.gemini/commands/trellis/*.toml`, etc.) |
|
||||
| `templates/<platform>/skills/` | Platform-specific skill | Written only into that platform's directory (e.g. `.codex/skills/`) |
|
||||
| User skills under `.claude/skills/<my-skill>/` etc. | Marketplace or user-authored | Not managed by Trellis at all |
|
||||
|
||||
The Trellis CLI never touches anything that is not produced by one of its own template loaders. Anything a user drops into a platform skill root by hand is left alone.
|
||||
|
||||
## Current Bundled Skills (v0.6.0)
|
||||
|
||||
The set is discovered at runtime by listing directories under `templates/common/bundled-skills/`:
|
||||
|
||||
| Skill | Purpose |
|
||||
| --- | --- |
|
||||
| `trellis-meta` | This skill. Explains the local Trellis architecture and customization entry points to an AI working inside a user project. |
|
||||
| `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex / Pi Agent conversation logs. |
|
||||
| `trellis-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.trellis/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
|
||||
| `trellis-channel` | Capability skill teaching an AI when to reach for `trellis channel` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
|
||||
|
||||
The list is discovered at runtime, so adding a new directory under `bundled-skills/` is the only step required to register a new skill (see "Adding a New Bundled Skill" below).
|
||||
|
||||
## Where Bundled Skills Land Per Platform
|
||||
|
||||
Each platform configurator calls `writeSkills(<root>, <workflowSkills>, resolveBundledSkills(ctx))` during `trellis init`. `resolveBundledSkills` reads every directory under `templates/common/bundled-skills/`, resolves placeholders, and returns a flat list of `{relativePath, content}` entries. `writeSkills` then mirrors them under the platform's skill root.
|
||||
|
||||
| Platform | Bundled skill root | Notes |
|
||||
| --- | --- | --- |
|
||||
| Claude Code | `.claude/skills/<skill>/` | `configureClaude` |
|
||||
| Cursor | `.cursor/skills/<skill>/` | `configureCursor` |
|
||||
| Codex | `.agents/skills/<skill>/` | `configureCodex` writes the shared `.agents/skills/` root, which Gemini CLI 0.40+ also reads |
|
||||
| Gemini CLI | `.agents/skills/<skill>/` | Same shared root as Codex; the two configurators are required to produce byte-identical output |
|
||||
| Kiro | `.kiro/skills/<skill>/` | `configureKiro` (skills-based platform — no commands) |
|
||||
| Qoder | `.qoder/skills/<skill>/` | `configureQoder` |
|
||||
| Codebuddy | `.codebuddy/skills/<skill>/` | `configureCodebuddy` |
|
||||
| Copilot | `.github/skills/<skill>/` | `configureCopilot` |
|
||||
| Droid | `.factory/skills/<skill>/` | `configureDroid` |
|
||||
| Antigravity | `.agent/skills/<skill>/` | `configureAntigravity` |
|
||||
| Devin | `.devin/skills/<skill>/` | `configureDevin` |
|
||||
| Kilo | `.kilocode/skills/<skill>/` | `configureKilo` |
|
||||
| OpenCode | (handled by `collectOpenCodeTemplates`) | Uses the same `resolveBundledSkills(ctx)` output |
|
||||
| Pi, Reasonix | (their own collectors) | Same `resolveBundledSkills(ctx)` output |
|
||||
|
||||
Two paths exercise the same data:
|
||||
|
||||
1. `configureX(cwd)` writes files during `trellis init`.
|
||||
2. `collectPlatformTemplates(platformId)` (in `configurators/index.ts`) returns a `Map<filePath, content>` that `trellis update` uses to detect drift and to populate `.trellis/.template-hashes.json`. Both must produce byte-identical output, so they both call `resolveBundledSkills(ctx)` and `collectSkillTemplates(root, …, resolveBundledSkills(ctx))`.
|
||||
|
||||
## Dispatch Wiring (Code Path)
|
||||
|
||||
The mechanism that auto-dispatches bundled skills to platform skill roots lives in two files:
|
||||
|
||||
1. `packages/cli/src/templates/common/index.ts`
|
||||
- `listDirectories("bundled-skills")` enumerates the on-disk skills.
|
||||
- `listBundledSkillFiles(skillDir)` walks each skill's directory recursively and returns `{relativePath, content}` for every file.
|
||||
- `getBundledSkillTemplates()` returns the cached `CommonBundledSkill[]`.
|
||||
|
||||
2. `packages/cli/src/configurators/shared.ts`
|
||||
- `resolveBundledSkills(ctx)` flattens that list into `ResolvedSkillFile[]` with `<skill>/<relativePath>` paths and resolved placeholders.
|
||||
- `writeSkills(skillsRoot, workflowSkills, bundledSkills)` writes both workflow skills and bundled skill files under `skillsRoot`.
|
||||
- `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns the same shape as a `Map<filePath, content>` for the update / hash pipeline.
|
||||
|
||||
Every platform configurator that supports skills imports both helpers (see `claude.ts`, `cursor.ts`, `codex.ts`, `gemini.ts`, `kiro.ts`, `qoder.ts`, `codebuddy.ts`, `copilot.ts`, `droid.ts`, `antigravity.ts`, `devin.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `trellis update` tracking stays consistent.
|
||||
|
||||
## Adding a New Bundled Skill
|
||||
|
||||
The shape and dispatch wiring are already generic, so adding a skill requires only file changes plus distribution verification.
|
||||
|
||||
1. **Create the directory tree.**
|
||||
|
||||
```
|
||||
packages/cli/src/templates/common/bundled-skills/<my-skill>/
|
||||
SKILL.md # YAML frontmatter + body
|
||||
references/ # optional
|
||||
<topic>.md
|
||||
assets/ # optional (anything readable as utf-8)
|
||||
```
|
||||
|
||||
2. **Write a valid `SKILL.md` header.** The frontmatter must include at minimum:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <my-skill>
|
||||
description: "When the AI should reach for this skill. Triggering phrases go here."
|
||||
---
|
||||
```
|
||||
|
||||
The `description` is what each platform's auto-trigger mechanism matches against, so it should describe the user-intent triggers, not the skill's internals.
|
||||
|
||||
3. **Use placeholders where appropriate.** Bundled skill content runs through `resolvePlaceholders(file.content, ctx)`. Any `{{platform_name}}`, `{{python_cmd}}`, etc. token supported by `resolvePlaceholders` will be substituted per platform.
|
||||
|
||||
4. **No dispatch wiring is required.** `listDirectories("bundled-skills")` discovers the new directory automatically, so all platforms receive it on the next `trellis init` or `trellis update`.
|
||||
|
||||
5. **Verify the distribution path** before shipping. Skipping any of these steps has historically caused features to be documented as bundled while the published npm tarball was missing the files:
|
||||
|
||||
- Source files exist on the branch being tagged.
|
||||
- `pnpm --filter @mindfoldhq/trellis build` copies the asset into `dist/templates/common/bundled-skills/<skill>/`.
|
||||
- `npm pack --dry-run --json` includes the expected `dist/**` paths.
|
||||
- In a fresh temp project, `trellis init` writes `.claude/skills/<skill>/SKILL.md`, `.agents/skills/<skill>/SKILL.md`, etc.
|
||||
- `.trellis/.template-hashes.json` lists the generated files.
|
||||
- `trellis update --dry-run` in that temp project reports "Already up to date!".
|
||||
|
||||
6. **Add a migration manifest entry** if the skill is added in a release that other projects will upgrade into. Without an explicit manifest entry the file will land via the standard "missing file" branch of `trellis update`, but a manifest makes the change visible in the changelog.
|
||||
|
||||
## Overriding a Bundled Skill Locally
|
||||
|
||||
There is no formal "project-local skill" mechanism (e.g. `.trellis/skills/`). Bundled skills are platform-rooted, so any override is platform-rooted too.
|
||||
|
||||
The supported pattern relies on the existing template-hash diff in `trellis update`:
|
||||
|
||||
1. Edit the local file directly. Example: `.claude/skills/trellis-meta/SKILL.md`.
|
||||
2. The file's hash now diverges from the entry in `.trellis/.template-hashes.json`.
|
||||
3. The next `trellis update` detects the user modification and leaves the file untouched (Trellis never overwrites user-modified files without an explicit `--force`).
|
||||
|
||||
Caveats:
|
||||
|
||||
- The override only applies to the one platform whose directory you edited. To override the same skill across, for example, Claude Code and Codex, you must edit both `.claude/skills/<name>/` and `.agents/skills/<name>/`.
|
||||
- A future `trellis update --force` will overwrite local edits. Keep the override under version control so it can be reapplied if needed.
|
||||
- Marketplace skills installed under the same platform skill root with a different folder name (e.g. `.claude/skills/my-custom-meta/`) are untouched by Trellis and are the cleaner option when the goal is to add behavior, not to mutate the bundled skill.
|
||||
- Team-private conventions belong in `.trellis/spec/` or in a separate marketplace-style local skill, not in modifications to `trellis-meta` itself. See `customize-local/add-project-local-conventions.md`.
|
||||
|
||||
## Removing a Bundled Skill From a Project
|
||||
|
||||
There is no per-project opt-out flag for bundled skills. Two options:
|
||||
|
||||
1. **Delete the directory in each platform skill root.** `trellis update` will see the file missing, compare against `.template-hashes.json`, and treat the deletion the same as any other user modification — it will not silently re-create the directory unless `--force` is passed.
|
||||
|
||||
2. **Pin a Trellis version that did not ship the skill.** The bundled-skill set is determined at build time, so installing an older release of the CLI is the only way to permanently exclude a skill that the current release ships.
|
||||
|
||||
A third option — globally disabling all bundled skills — is not supported. The dispatch is unconditional in every configurator. Adding such a flag would require changing `PLATFORM_FUNCTIONS` in `configurators/index.ts` and every `configureX` function.
|
||||
|
||||
## Operating Rules
|
||||
|
||||
- Treat `templates/common/bundled-skills/` as the single source of truth for what bundled skills exist. Do not hand-maintain platform-by-platform skill lists.
|
||||
- Do not add platform-specific logic inside a bundled `SKILL.md`. If a behavior is platform-specific, put it in `templates/<platform>/skills/` instead.
|
||||
- Do not couple bundled skills to a specific CLI binary (e.g. `trellis mem`) without surfacing the dependency in the skill's description and references — users on older releases may not have the command.
|
||||
- Do not store project-private content in a bundled skill. Bundled skills are public, shipped to every user; project rules belong in `.trellis/spec/` or a local skill.
|
||||
@@ -0,0 +1,68 @@
|
||||
# Local Context Injection System
|
||||
|
||||
Trellis context injection aims to make AI read the right files at the right time instead of relying on model memory. In a user project, injection is implemented by `.trellis/` scripts together with platform hooks, agents, and skills.
|
||||
|
||||
## Injected Context Types
|
||||
|
||||
| Type | Source | Purpose |
|
||||
| --- | --- | --- |
|
||||
| session context | `.trellis/scripts/get_context.py` | Current developer, git status, active task, active tasks, journal, packages. |
|
||||
| workflow context | `.trellis/workflow.md` | Current Trellis flow and next action. |
|
||||
| spec context | `.trellis/spec/` + task JSONL | Specs that must be followed during implementation/checking. |
|
||||
| task context | `.trellis/tasks/<task>/prd.md`, `design.md`, `implement.md`, `research/` | Current task requirements, design, execution plan, and research. |
|
||||
| platform context | Platform hooks/settings/agents | Lets different AI tools read the files above through their own mechanisms. |
|
||||
|
||||
## session-start
|
||||
|
||||
Platforms with session-start support inject a Trellis overview when a session starts, clears, compacts, or receives a similar event. Injected content usually includes:
|
||||
|
||||
- workflow summary.
|
||||
- current task status.
|
||||
- active tasks.
|
||||
- spec index paths.
|
||||
- developer identity and git status.
|
||||
|
||||
If the user feels the AI does not know the current task in a new session, first check whether the platform's session-start hook or equivalent mechanism is installed and running.
|
||||
|
||||
## workflow-state
|
||||
|
||||
workflow-state is a lightweight hint injected around each user turn. Based on current task status, it selects a block from `.trellis/workflow.md`, such as `no_task`, `planning`, `in_progress`, or `completed`.
|
||||
|
||||
If the user wants to change "what the AI should do next in a given state," edit the corresponding state block in `.trellis/workflow.md` first.
|
||||
|
||||
## sub-agent context
|
||||
|
||||
Implement and check agents need task context. Trellis has two loading modes:
|
||||
|
||||
1. **hook push**: a platform hook injects jsonl-referenced files plus `prd.md`, `design.md` if present, and `implement.md` if present before the agent starts.
|
||||
2. **agent pull**: the agent definition instructs the agent to read the active task, jsonl context, and task artifacts after startup.
|
||||
|
||||
In both modes, JSONL files in the task directory are the manifest for spec/research context. Task artifacts are read separately in this order: `prd.md` -> `design.md if present` -> `implement.md if present`.
|
||||
|
||||
## JSONL Reading Rules
|
||||
|
||||
`implement.jsonl` and `check.jsonl` contain one JSON object per line:
|
||||
|
||||
```jsonl
|
||||
{"file": ".trellis/spec/backend/index.md", "reason": "Backend rules"}
|
||||
```
|
||||
|
||||
Readers should skip seed rows without a `file` field. When configuring JSONL, the AI should include only spec/research files, not pre-register code files that will be modified.
|
||||
|
||||
## Active Task And Context Key
|
||||
|
||||
Active task state lives in `.trellis/.runtime/sessions/` and is isolated per session. Hooks try to resolve the context key from platform events, environment variables, transcript paths, or `TRELLIS_CONTEXT_ID`.
|
||||
|
||||
If shell commands cannot see the same context key, `task.py current --source` may report no active task. In that case, check whether the platform passes session identity into the shell instead of hand-writing a global current-task file.
|
||||
|
||||
## Local Customization Points
|
||||
|
||||
| Need | Edit location |
|
||||
| --- | --- |
|
||||
| Change session-start injected content | The platform's `session-start` hook or plugin file. |
|
||||
| Change per-turn workflow-state rules | `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The platform workflow-state hook parses these blocks verbatim and embeds no fallback text. |
|
||||
| Change how sub-agents read context | Platform agent definitions, the `inject-subagent-context` hook, or agent preludes. |
|
||||
| Change JSONL validation/display | `.trellis/scripts/common/task_context.py`. |
|
||||
| Change active task resolution | `.trellis/scripts/common/active_task.py`. |
|
||||
|
||||
When modifying context injection, verify two things: new sessions can see the correct task, and sub-agents can see the correct task artifacts/spec/research.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Local Files Generated After Init
|
||||
|
||||
`trellis init` writes the Trellis runtime into the user project. Later, `trellis update` tries to update Trellis-managed template files, but it uses `.trellis/.template-hashes.json` to determine which files have already been modified by the user.
|
||||
|
||||
This page only describes files that are visible and editable inside the user project.
|
||||
|
||||
## `.trellis/`
|
||||
|
||||
```text
|
||||
.trellis/
|
||||
├── workflow.md
|
||||
├── config.yaml
|
||||
├── .developer
|
||||
├── .version
|
||||
├── .template-hashes.json
|
||||
├── .runtime/
|
||||
├── scripts/
|
||||
├── spec/
|
||||
├── tasks/
|
||||
└── workspace/
|
||||
```
|
||||
|
||||
| Path | Usually editable? | Notes |
|
||||
| --- | --- | --- |
|
||||
| `.trellis/workflow.md` | Yes | Local workflow documentation and AI routing rules. |
|
||||
| `.trellis/config.yaml` | Yes | Project configuration, hooks, packages, journal line limits, and related settings. |
|
||||
| `.trellis/spec/` | Yes | Project specs, intended to be updated regularly by users and AI. |
|
||||
| `.trellis/tasks/` | Yes | Task material and research artifacts, maintained by the task workflow. |
|
||||
| `.trellis/workspace/` | Yes | Session records, usually written by `add_session.py`. |
|
||||
| `.trellis/scripts/` | Carefully | Local runtime. It can be customized, but only after understanding the call chain. |
|
||||
| `.trellis/.runtime/` | No | Runtime state, usually written automatically by hooks/scripts. |
|
||||
| `.trellis/.developer` | Carefully | Current developer identity. |
|
||||
| `.trellis/.version` | No | Trellis version record used by update/migration logic. |
|
||||
| `.trellis/.template-hashes.json` | No | Template hash record. Do not hand-write business rules here. |
|
||||
|
||||
## Platform Directories
|
||||
|
||||
Different platforms generate different directories. Common categories:
|
||||
|
||||
| Category | Example paths | 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`, `.trae/hooks.json` | Tell the platform when to run hooks or plugins. |
|
||||
| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, `.zcode/cli/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/`, `.devin/workflows/`, `.zcode/commands/` | Explicit user-invoked command or workflow entry points. |
|
||||
|
||||
When modifying a platform directory, also confirm whether `.trellis/workflow.md` still describes the same flow.
|
||||
|
||||
## Meaning Of Template Hashes
|
||||
|
||||
`.trellis/.template-hashes.json` records the content hash from the last time Trellis wrote a template file. `trellis update` uses it to distinguish three cases:
|
||||
|
||||
| Case | Update behavior |
|
||||
| --- | --- |
|
||||
| File was not modified by the user | It can be updated automatically. |
|
||||
| File was modified by the user | Prompt the user to overwrite, keep, or generate `.new`. |
|
||||
| File is no longer a current template | It may be deleted, renamed, or preserved according to migration rules. |
|
||||
|
||||
When an AI customizes local Trellis files, it does not need to maintain hashes manually. It is normal for Trellis update to recognize the result as "modified by the user."
|
||||
|
||||
## Local Customization Boundaries
|
||||
|
||||
Editable by default:
|
||||
|
||||
- `.trellis/workflow.md`
|
||||
- `.trellis/config.yaml`
|
||||
- `.trellis/spec/**`
|
||||
- `.trellis/scripts/**`
|
||||
- Platform hooks, settings, agents, skills, commands, prompts, and workflows
|
||||
|
||||
Do not edit by default:
|
||||
|
||||
- Global npm install directory
|
||||
- `node_modules/@mindfoldhq/trellis`
|
||||
- Trellis GitHub repository source code
|
||||
- Concrete state files under `.trellis/.runtime/**`
|
||||
- Hash contents inside `.trellis/.template-hashes.json`
|
||||
|
||||
Switch to the Trellis CLI source-code perspective only when the user explicitly wants to contribute upstream.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Local Multi-Agent Channel Runtime
|
||||
|
||||
`trellis channel` is the local multi-agent collaboration runtime shipped with the Trellis CLI. It lets the main AI session spawn peer workers (Claude Code, Codex, or any agent definition under `.trellis/agents/`), exchange durable messages through an event log, and coordinate review or brainstorm loops without hand-stitching shell pipelines.
|
||||
|
||||
This reference covers how channels are wired into the user project so an AI customizing the project knows what to edit. For runtime usage (commands, forum/thread patterns, worker spawn flags), defer to the bundled `trellis-channel` capability skill.
|
||||
|
||||
## Local System Model
|
||||
|
||||
The channel runtime spans three local surfaces:
|
||||
|
||||
1. **Storage layer** in the user's home directory: durable event logs and worker state files.
|
||||
2. **Agent definitions** inside the project at `.trellis/agents/`: platform-agnostic role cards consumed by `trellis channel spawn --agent <name>`.
|
||||
3. **Project configuration** in `.trellis/config.yaml`: worker guard thresholds and other channel knobs.
|
||||
|
||||
## Core Paths
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `~/.trellis/channels/<project>/<channel>/events.jsonl` | Per-channel append-only event log. Sequence-locked, replay-safe. |
|
||||
| `~/.trellis/channels/<project>/<channel>/<channel>.lock` | Channel-level write lock. |
|
||||
| `~/.trellis/channels/<project>/<channel>/<worker>.spawnlock` | Per-worker spawn lock used by the OOM guard. |
|
||||
| `~/.trellis/channels/<project>/<channel>/.seq` | Sequence sidecar for ordered event assignment. |
|
||||
| `~/.trellis/channels/_global/<channel>/...` | Channels created with `--scope global`. The project bucket is replaced by a shared key. |
|
||||
| `.trellis/agents/check.md` | Default Check Agent role definition consumed by `--agent check`. |
|
||||
| `.trellis/agents/implement.md` | Default Implement Agent role definition consumed by `--agent implement`. |
|
||||
| `.trellis/config.yaml` (`channel.*` block) | Worker guard thresholds and channel defaults. |
|
||||
|
||||
The project bucket name is derived from the absolute project path (slashes flattened, non-alphanumerics replaced with `-`), matching Claude Code's `~/.claude/projects/<sanitized-cwd>/` convention. Override with `TRELLIS_CHANNEL_ROOT` (root directory) or `TRELLIS_CHANNEL_PROJECT` (bucket name) for testing or sandboxing.
|
||||
|
||||
## When To Reach For The Channel Runtime
|
||||
|
||||
Channels are heavier than a single Bash call or a one-shot sub-agent dispatch. Use them only when at least one of these conditions holds:
|
||||
|
||||
- The work needs **two or more agents to converse** through more than one turn (cross-AI brainstorm, peer review, dispatcher + worker).
|
||||
- A worker should run as a **peer process** that the main session can interrupt, watch progress on, or wait for asynchronously.
|
||||
- The conversation must be **durable and inspectable** later (forum/thread channels, issue boards, decision trails).
|
||||
- Multiple workers must **share an event log** so each can see what the others reported.
|
||||
|
||||
Prefer cheaper primitives when:
|
||||
|
||||
- A single-shot Bash command or single Agent tool call is enough -> do that directly.
|
||||
- The user just needs a static review against a file -> read the file and reply inline.
|
||||
- The need is "remember what we discussed last week" -> use `trellis mem` instead of a channel.
|
||||
|
||||
## Customization Points
|
||||
|
||||
| Need | Edit location |
|
||||
| --- | --- |
|
||||
| Change default channel worker idle timeout | `channel.worker_guard.idle_timeout` in `.trellis/config.yaml`. Accepts `5m`, `30s`, etc. Set `0` to disable idle cleanup. |
|
||||
| Change live worker budget | `channel.worker_guard.max_live_workers` in `.trellis/config.yaml`. Set `0` to disable the spawn-time budget check. |
|
||||
| Override worker guard per spawn | Pass `--idle-timeout` / `--max-live-workers` on `trellis channel spawn`, or set `TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT` / `TRELLIS_CHANNEL_MAX_LIVE_WORKERS` in the environment. |
|
||||
| Change what the default Check or Implement worker does | Edit `.trellis/agents/check.md` or `.trellis/agents/implement.md`. These are platform-agnostic role cards; the channel runtime injects them when `--agent check|implement` is passed. |
|
||||
| Add a new role card | Drop `<name>.md` into `.trellis/agents/`. `trellis channel spawn --agent <name>` will pick it up. |
|
||||
| Relocate channel storage (CI sandbox, ephemeral runs) | Set `TRELLIS_CHANNEL_ROOT=/path/to/dir`. Channel events move with it; existing channels stay at the old root. |
|
||||
| Switch storage scope | Pass `--scope project` (default) or `--scope global` on every channel subcommand. The bucket directory changes; nothing else does. |
|
||||
|
||||
Precedence for the worker guard is: CLI flag > environment variable > `.trellis/config.yaml` > built-in default. Built-in defaults are `idle_timeout: 5m` and `max_live_workers: 6`.
|
||||
|
||||
## Relationship To Other Local Layers
|
||||
|
||||
- **Workflow layer**: workflows that use channel dispatch (such as `channel-driven-subagent-dispatch`) instruct the main agent to call `trellis channel spawn --agent check` or `--agent implement` instead of a platform sub-agent. If `.trellis/agents/check.md` or `implement.md` is missing, `trellis workflow --template <id>` prints a non-blocking warning at install time. Restore them with `trellis update` if they are deleted by accident.
|
||||
- **Task layer**: channel workers do not own task state. The supervising main session passes the active task path through the worker inbox; the worker resolves task artifacts from disk.
|
||||
- **Spec layer**: workers read `.trellis/spec/` the same way the main session does. Channel runtime does not bypass spec context loading.
|
||||
- **Platform integration layer**: channel runtime is platform-neutral. It does not depend on `.claude/`, `.codex/`, or any other platform directory. The adapters that normalize provider output (Claude `stream-json`, Codex `app-server`) live inside the Trellis CLI binary, not in the project.
|
||||
- **Platform sub-agent files vs. channel workers**: editing `.claude/agents/trellis-implement.md` (and its peers in other platform `.X/agents/` directories) does NOT change channel-runtime worker behavior — channel workers load `.trellis/agents/<name>.md`. The platform-specific agent files are for direct sub-agent dispatch from the main AI session, not for channel-spawned workers. See `platform-files/agents.md` for the per-platform agent surface, and the `trellis-meta/SKILL.md` rule that codifies this split.
|
||||
|
||||
## Runtime Usage
|
||||
|
||||
For command syntax, forum/thread patterns, worker handles, progress inspection, and the `--kind done` / `--kind turn_finished` dispatcher wait pattern, load the bundled `trellis-channel` skill (auto-installed under each platform's skills directory after `trellis init` / `trellis update`). This reference only covers the local file layout and customization knobs; it does not duplicate command syntax that may change between releases.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Local Trellis Architecture Overview
|
||||
|
||||
`trellis-meta` is for user projects that have already run `trellis init`. The user's machine usually has only the npm-installed `trellis` command plus the Trellis files generated inside the project; it may not have the Trellis CLI source code.
|
||||
|
||||
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/`, `.devin/`, `.reasonix/`, `.zcode/`, and similar directories.
|
||||
- Shared skill layer: `.agents/skills/`.
|
||||
|
||||
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.
|
||||
|
||||
## Local System Model
|
||||
|
||||
Trellis provides three layers inside a user project:
|
||||
|
||||
1. **Workflow layer**: `.trellis/workflow.md` defines phases, routing, next actions, and prompt blocks.
|
||||
2. **Persistence layer**: `.trellis/tasks/`, `.trellis/spec/`, and `.trellis/workspace/` store tasks, specs, and session memory.
|
||||
3. **Platform integration layer**: hooks, settings, agents, skills, commands, prompts, and workflows in platform directories connect the Trellis workflow to different AI tools.
|
||||
|
||||
All three layers live inside the user project, so an AI can read and modify them directly.
|
||||
|
||||
## Core Paths
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `.trellis/workflow.md` | Workflow phases, skill routing, and workflow-state prompt blocks. |
|
||||
| `.trellis/config.yaml` | Project configuration, task lifecycle hooks, monorepo package configuration, and journal configuration. |
|
||||
| `.trellis/spec/` | The user's project-specific coding conventions and thinking guides. |
|
||||
| `.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 current 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
|
||||
|
||||
1. **Find the local source of truth first**: Do not edit from memory. Read `.trellis/workflow.md`, `.trellis/config.yaml`, the relevant platform directory, and related task files first.
|
||||
2. **Edit the user project, not the npm package cache**: Modify generated files inside the project, not `node_modules` or the global npm install directory.
|
||||
3. **Keep platform files aligned with `.trellis/`**: If workflow routing changes, also check whether platform skills or commands still describe the same flow.
|
||||
4. **Put project-specific rules in `.trellis/spec/` or a local skill**: Do not put team conventions into `trellis-meta`.
|
||||
5. **Preserve user changes**: If a file was already modified locally, work from the current content instead of overwriting it with a default template.
|
||||
|
||||
## How To Use This Directory
|
||||
|
||||
- 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 active 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`.
|
||||
@@ -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, planning may write relevant specs into `implement.jsonl` / `check.jsonl` when the task needs spec or research context beyond the task artifacts:
|
||||
|
||||
```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.
|
||||
@@ -0,0 +1,130 @@
|
||||
# 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
|
||||
│ ├── design.md
|
||||
│ ├── implement.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, constraints, and acceptance criteria. Lightweight tasks may be PRD-only. |
|
||||
| `design.md` | Technical design for complex tasks: boundaries, contracts, data flow, compatibility, tradeoffs. |
|
||||
| `implement.md` | Execution plan for complex tasks: ordered checklist, validation commands, review gates, rollback points. |
|
||||
| `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. |
|
||||
|
||||
## Parent / Child Task Trees
|
||||
|
||||
Parent/child task relationships are for work structure. A parent task groups related deliverables under one source requirement set; it is not a dependency scheduler and does not replace the child task's own planning artifacts.
|
||||
|
||||
Use a parent task when a request has multiple independently verifiable deliverables. The parent owns:
|
||||
|
||||
- Source requirements and user-facing scope.
|
||||
- The map of child tasks and their responsibility boundaries.
|
||||
- Cross-child acceptance criteria and final integration review.
|
||||
|
||||
Use child tasks for deliverables that can move through planning, implementation, check, and archive independently. If one child depends on another, write that dependency in the child `prd.md` / `implement.md`; do not rely on tree position to imply ordering.
|
||||
|
||||
Create new children with:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py create "<child title>" --slug <child-slug> --parent <parent-dir>
|
||||
```
|
||||
|
||||
Link or unlink existing tasks with:
|
||||
|
||||
```bash
|
||||
python3 ./.trellis/scripts/task.py add-subtask <parent-dir> <child-dir>
|
||||
python3 ./.trellis/scripts/task.py remove-subtask <parent-dir> <child-dir>
|
||||
```
|
||||
|
||||
`children` on the parent is a historical list. When a child is archived, Trellis keeps that child name in the parent so progress like `[2/3 done]` remains meaningful after completed children move to `archive/`.
|
||||
|
||||
The AI should not treat phase numbers as task status. Task progress is mainly determined by `status`, artifact presence (`prd.md`, optional `design.md` / `implement.md`), whether JSONL context is configured for sub-agent mode, 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. They do not replace `implement.md`; `implement.md` is the human-readable execution plan.
|
||||
|
||||
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 | Planning artifact guidance 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,82 @@
|
||||
# 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`, 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
|
||||
|
||||
| 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` |
|
||||
| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) |
|
||||
| ZCode | `.zcode/cli/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 Devin 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`
|
||||
- `implement.jsonl` or `check.jsonl`
|
||||
- spec/research files referenced by JSONL
|
||||
- current task `prd.md`
|
||||
- `design.md` if present
|
||||
- `implement.md` if present
|
||||
|
||||
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, 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.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,72 @@
|
||||
# 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: parses `[workflow-state:STATUS]` blocks from `.trellis/workflow.md` and emits the body matching the current 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:
|
||||
|
||||
| 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/` |
|
||||
| Trae IDE | `.trae/hooks.json` |
|
||||
|
||||
Reasonix and ZCode are pull-based platforms that do not use hooks or settings files; their agent files contain prelude instructions to read context after startup.
|
||||
|
||||
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 current 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.
|
||||
|
||||
## 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 | `[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 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.
|
||||
@@ -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/`, `.trae/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, 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`, `.trae/hooks.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/`, `.devin/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.
|
||||
@@ -0,0 +1,88 @@
|
||||
# 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/` | `.agents/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
|
||||
| Antigravity | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
|
||||
| Devin | `--devin` | `.devin/` | `.devin/skills/` | Usually none | `.devin/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/` (native `trellis_subagent` tool) + `.pi/settings.json` |
|
||||
| Trae IDE | `--trae` | `.trae/` | `.trae/skills/` | `.trae/agents/` | `.trae/hooks/` + `.trae/hooks.json` |
|
||||
| Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None |
|
||||
| ZCode | `--zcode` | `.zcode/` | `.agents/skills/` | `.zcode/cli/agents/` | pull-based prelude (no hooks) |
|
||||
|
||||
## 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
|
||||
- Trae IDE
|
||||
- Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory)
|
||||
- ZCode
|
||||
|
||||
When changing implementation/check/research behavior, look for the corresponding platform agent files first.
|
||||
|
||||
### Native Trellis Sub-Agent Tool
|
||||
|
||||
Some platforms expose a first-class tool that the host runtime understands. The model calls it like any other tool and the host renders progress cards, validates the agent name against `.<platform>/agents/`, and enforces dispatch modes.
|
||||
|
||||
- Pi Agent — `trellis_subagent` tool, defined in `.pi/extensions/trellis/index.ts`. Supports `single` / `parallel` / `chain` dispatch modes and emits live `trellis-subagent-progress` events.
|
||||
|
||||
When changing sub-agent dispatch behavior on these platforms, edit the extension file, **not** the agent markdown — the agent markdown defines responsibilities, but the host extension owns dispatch, validation, and progress rendering.
|
||||
|
||||
### Main-Session Workflow Platforms
|
||||
|
||||
These platforms rely more on workflows/skills to guide the main session:
|
||||
|
||||
- Kilo
|
||||
- Antigravity
|
||||
- Devin
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,85 @@
|
||||
# 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.
|
||||
|
||||
## Conceptual Differences
|
||||
|
||||
| Type | Trigger mode | Best for |
|
||||
| --- | --- | --- |
|
||||
| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
|
||||
| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
|
||||
| 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 workflow skills usually share one semantic set: brainstorm, before-dev, check, update-spec, break-loop. Multi-file built-in skills such as `trellis-meta` use layered references.
|
||||
|
||||
## Common Paths
|
||||
|
||||
| Platform | Common entries |
|
||||
| --- | --- |
|
||||
| Claude Code | `.claude/skills/`, `.claude/commands/` |
|
||||
| Cursor | `.cursor/skills/`, `.cursor/commands/` |
|
||||
| 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/` |
|
||||
| Devin | `.devin/skills/`, `.devin/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/` |
|
||||
| Reasonix | `.reasonix/skills/` |
|
||||
| ZCode | `.agents/skills/`, `.zcode/commands/` |
|
||||
|
||||
In a user project, use the files actually generated by init as authoritative.
|
||||
|
||||
## Skill Structure
|
||||
|
||||
A common skill is a directory:
|
||||
|
||||
```text
|
||||
trellis-meta/
|
||||
├── SKILL.md
|
||||
└── references/
|
||||
```
|
||||
|
||||
`SKILL.md` should tell the AI:
|
||||
|
||||
- When to use this skill.
|
||||
- Which reference to read first for the current task.
|
||||
- What not to do.
|
||||
|
||||
References hold longer explanations so the entry file does not contain everything.
|
||||
|
||||
## Command/Prompt/Workflow Structure
|
||||
|
||||
Commands, prompts, and workflows are usually single files. Their content should include:
|
||||
|
||||
- When to use it.
|
||||
- Which `.trellis/` files to read.
|
||||
- Which scripts to run.
|
||||
- How to report after completion.
|
||||
|
||||
They should not store task state; task state belongs in `.trellis/tasks/` and `.trellis/.runtime/`.
|
||||
|
||||
## Local Change Scenarios
|
||||
|
||||
| User need | Edit location |
|
||||
| --- | --- |
|
||||
| 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. |
|
||||
|
||||
## Modification Principles
|
||||
|
||||
1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `trellis-meta`.
|
||||
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.
|
||||
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.
|
||||
Reference in New Issue
Block a user