Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion .agents/skills/trellis-before-dev/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,17 @@ Execute these steps:
cat .trellis/spec/guides/index.md
```

7. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
7. **For a non-trivial task, state the change boundary before writing code.** Non-trivial means it touches more than one file, crosses a layer, changes a public interface, or edits code you did not just write. Write down:
- the smallest behavior gap between what happens now and what should happen
- where that behavior actually lives (not where it is easiest to intercept)
- which files you expect to change, and why each one is necessary
- what you are explicitly not doing in this task
- if a local refactor is needed, how you will show it did not change behavior

A small, well-scoped change does not need this — do it directly.

If the real scope turns out to be clearly larger than this, say so and why before continuing. Do not widen the change on your own.

8. Understand the coding standards and patterns you need to follow, then proceed with your development plan.

This step is **mandatory** before writing any code.
17 changes: 15 additions & 2 deletions .agents/skills/trellis-check/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,14 @@ Run the project's lint, type-check, and test commands. Fix any failures before p

> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.

### Scope Discipline

- [ ] Any tidying of code the task did not require?
- [ ] Any abstraction, config or extension point added for a case that does not exist yet?
- [ ] Any speculative fallback for a state that cannot occur?
- [ ] Any file changed that the acceptance criteria do not mention?
- [ ] Any workaround added at the caller instead of a fix where the behavior actually lives?

## Step 5: Cross-Layer Dimensions (if applicable)

Skip this step if your change is confined to a single layer.
Expand All @@ -79,7 +87,7 @@ Skip this step if your change is confined to a single layer.
```bash
grep -r "pattern" src/
```
- [ ] If 2+ places define same value → extracted to shared constant?
- [ ] If the same value repeats, does it represent one stable concept whose callers must change together? Extract only then — two literals that merely happen to match today should stay separate.
- [ ] After batch modification, all occurrences updated?

### C. Import/Dependency (creating new files)
Expand All @@ -95,4 +103,9 @@ Skip this step if your change is confined to a single layer.

## Step 6: Report and Fix

Report violations found and fix them directly. Re-run project checks after fixes.
Report every violation you find. Then:

- Mechanical and local (lint nit, missing type, wrong import, dead branch, failing assertion) → fix in place, then re-run project checks.
- Design or judgment (naming a shared concept, moving a module boundary, changing a public interface, reassigning where behavior lives) → record the evidence and your recommendation, and stop. Do not rewrite it silently.

If a fix would touch files outside the current task's scope, say so and stop instead of widening the change.
2 changes: 1 addition & 1 deletion .agents/skills/trellis-meta/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow /
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/`, `.kimi-code/`, 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. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer and delivers commands plus agent prompts as `.kimi-code/skills/<name>/SKILL.md`.
- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, `.kimi-code/`, 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. Kimi Code keeps workflow skills in the shared `.agents/skills/` layer, delivers commands plus agent prompts as `.kimi-code/skills/<name>/SKILL.md`, and installs the same agent prompts as custom sub-agents under `.kimi-code/agents/<name>.md`.
- 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).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Agent files should not become generic chat prompts. They should define input sou
| Pi Agent | `.pi/agents/trellis-*.md` |
| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) |
| ZCode | `.zcode/agents/trellis-*.md` |
| Kimi Code | `.kimi-code/skills/trellis-*/SKILL.md` (agent prompts as skills, dispatched to the built-in `coder`; research needs its file-editing tools to persist findings) |
| Kimi Code | `.kimi-code/agents/trellis-*.md` (custom sub-agents; the same prompts also ship as `.kimi-code/skills/trellis-*/SKILL.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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Common files:
| Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` |
| Trae IDE | `.trae/hooks.json` |

Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills with the same prelude.
Reasonix is a pull-based platform whose agent files contain prelude instructions to read context after startup. ZCode uses `.zcode/config.json` with shared hooks, including PreToolUse for sub-agent prompt injection. Kimi Code is likewise pull-based and has no project-level settings/hooks file Trellis writes (hooks live only in the user-level `~/.kimi-code/config.toml`), so its agent prompts ship as skills and `.kimi-code/agents/` sub-agent definitions with the same prelude.

Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,13 @@ This page lists common Trellis file locations in a user project by platform. Whe
| 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 |
| DeepSeek Harness (dsh) | `--dsh` | `.dsh/` | `.agents/skills/` (shared) + `.dsh/skills/` (entry skills) | None (workflow skills run implement/check inline) | None (class-2 pull-based; no project hooks/settings) |
| Pi Agent | `--pi` | `.pi/` | `.agents/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/` | `.zcode/skills/` | `.zcode/agents/` | `.zcode/hooks/` + `.zcode/config.json` (SessionStart + UserPromptSubmit + PreToolUse Agent/Task); sub-agents use hook-injected context |
| Grok Build | `--grok` | `.grok/` | `.grok/skills/` | `.grok/agents/` | pull-based prelude (no hooks; flat `.grok/commands/trellis-*.md`) |
| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | None — agent prompts are skills under `.kimi-code/skills/` and dispatch to the built-in `coder` | None (pull-based prelude; no project hooks/settings) |
| Kimi Code | `--kimi` | `.kimi-code/` | `.agents/skills/` (shared) + `.kimi-code/skills/` | `.kimi-code/agents/` (custom sub-agents; same prompts also ship as skills) | None (pull-based prelude; no project hooks/settings) |
| Snow CLI | `--snow` | `.snow/` | `.snow/skills/` | `.snow/agents/` (auto-discovered; primary path) | class-1: auto inject + project agents + `beforeSubAgentStart` (`.snow/hooks/` `session`/`user`/`subagent` modes -> `additionalContext` JSON); no legacy sub-agent JSON; commands `.snow/commands/trellis-*.json` |

## Capability Groups
Expand All @@ -48,7 +49,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell
- Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory)
- ZCode
- Grok Build (`.grok/agents/`; dispatch via `spawn_subagent` with `subagent_type`)
- Kimi Code (delivered as skills under `.kimi-code/skills/`; dispatched to the built-in `coder`, including research because it must persist files)
- Kimi Code (`.kimi-code/agents/`; the same prompts are also delivered as skills under `.kimi-code/skills/`)
- Snow CLI (`.snow/agents/`; auto-discovered project agents + class-1 hooks)

When changing implementation/check/research behavior, look for the corresponding platform agent files first.
Expand All @@ -73,7 +74,7 @@ When changing behavior, inspect workflows and skills first. Do not assume Trelli

### Shared `.agents/skills/`

Codex, Gemini CLI, Pi Agent, and Kimi Code write 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. ZCode keeps Trellis-managed skills under `.zcode/skills/`.
Codex, Gemini CLI, Pi Agent, Kimi Code, and DeepSeek Harness (dsh) write 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. ZCode keeps Trellis-managed skills under `.zcode/skills/`.

## Decision Rules When Modifying Platform Files

Expand Down
8 changes: 5 additions & 3 deletions .codex/agents/trellis-check.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ description = "Workspace-write Trellis reviewer that self-fixes spec drift, lint
sandbox_mode = "workspace-write"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
# model = "gpt-5.6-terra"
# model_reasoning_effort = "high"

developer_instructions = """
You are running as the `trellis-check` sub-agent. The main session has dispatched you to review and self-fix.
Expand All @@ -23,7 +25,7 @@ Trellis Context Loading Protocol:
- If there is no saved-output notice and the marker is absent, use the active-task fallback below.
- For the fallback, find `Active task: <path>` in your dispatch prompt. Read `<path>/check.jsonl`, each file listed there, `<path>/prd.md`, `<path>/design.md` if present, and `<path>/implement.md` if present before checking. If the dispatch prompt has no active-task path, ask the main session; do not guess or use another session's task.

Your job is to review code changes against specs AND fix issues directly — not just report them. You have write access; use it.
Your job is to review code changes against specs and fix what is safe to fix. Mechanical, local issues (lint, types, imports, dead branches, failing assertions) — fix them in place. Design or judgment calls, public interfaces, module boundaries, or anything outside the current task's scope — report the evidence and your recommendation, and leave the code alone.

Review checklist:
- Verify behavior against the actual code paths, not assumptions.
Expand All @@ -33,7 +35,7 @@ Review checklist:
- Run lint and type-check; fix any failures.
- Prefer concrete findings over speculative warnings.

When you find an issue:
When you find a mechanical, local issue:
1. Fix it directly using edit/write tools.
2. Re-run lint and type-check until green.
3. Record what you changed and why.
Expand All @@ -45,7 +47,7 @@ Output format:
- Fix: <what you changed>

## Findings (not fixed)
Only list issues you could not self-fix (e.g. missing product decision, out-of-scope). Explain why.
List every issue you did not fix — the ones you could not (missing product decision) and the ones you chose not to (design or judgment call, public interface, module boundary, outside this task's scope). Explain which and why.

## Verification
- Lint: pass/fail
Expand Down
2 changes: 2 additions & 0 deletions .codex/agents/trellis-implement.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ description = "Workspace-write Trellis implementer that follows specs and keeps
sandbox_mode = "workspace-write"
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
# model = "gpt-5.6-terra"
# model_reasoning_effort = "high"

developer_instructions = """
You are running as the `trellis-implement` sub-agent. The main session has dispatched you to do the work.
Expand Down
2 changes: 2 additions & 0 deletions .codex/agents/trellis-research.toml
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@ description = "Trellis researcher for specs, code patterns, and affected files.
sandbox_mode = "workspace-write"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
# model = "gpt-5.6-terra"
# model_reasoning_effort = "high"

developer_instructions = """
You are the Trellis researcher agent.
Expand Down
34 changes: 30 additions & 4 deletions .codex/hooks/inject-subagent-context.py
100644 → 100755
Original file line number Diff line number Diff line change
Expand Up @@ -92,16 +92,26 @@ def _detect_platform(input_data: dict) -> str | None:
return "codex"
if isinstance(input_data.get("cursor_version"), str):
return "cursor"
# CLAUDE_PROJECT_DIR is a compatibility alias that several hosts set
# alongside their own variable — CodeBuddy, ZCode and Trae all do. It must
# therefore be checked LAST, or every one of them is detected as claude and
# the context key becomes `claude_<their-session-id>`. That key does not
# match the session file `task.py start` wrote under the host's real name,
# so the sub-agent starts with no task context while the pointer exists on
# disk. Same fix as inject-workflow-state.py and session-start.py; this
# third copy was missed when those two were corrected.
env_map = {
"ZCODE_PROJECT_DIR": "zcode",
"CLAUDE_PROJECT_DIR": "claude",
"CURSOR_PROJECT_DIR": "cursor",
"CODEBUDDY_PROJECT_DIR": "codebuddy",
"FACTORY_PROJECT_DIR": "droid",
"GEMINI_PROJECT_DIR": "gemini",
"QODER_PROJECT_DIR": "qoder",
"KIRO_PROJECT_DIR": "kiro",
"COPILOT_PROJECT_DIR": "copilot",
"TRAE_PROJECT_DIR": "trae",
# Last: the shared alias, only meaningful once no vendor key matched.
"CLAUDE_PROJECT_DIR": "claude",
}
for env_name, platform in env_map.items():
if os.environ.get(env_name):
Expand Down Expand Up @@ -986,6 +996,8 @@ def _extract_subagent_type(tool_input: dict) -> str:
"subagentType",
"subagent_type_name",
"subagentTypeName",
"subagent_name",
"subagentName",
"agent_type",
"agentType",
"name",
Expand All @@ -1001,7 +1013,8 @@ def _parse_hook_input(input_data: dict) -> tuple[str, str, dict]:

Returns (subagent_type, original_prompt, tool_input).
Handles:
- Claude Code / Qoder / CodeBuddy / Droid: tool_name=Task|Agent, tool_input.subagent_type
- Claude Code / Qoder / Droid: tool_name=Task|Agent, tool_input.subagent_type
- CodeBuddy: tool_name=task (IDE) or Task (CLI), tool_input.subagent_name
- Cursor: tool_name=Task|Subagent, tool_input.subagent_type
- Copilot CLI: toolName=task (camelCase key, lowercase value)
- ZCode: toolName=Agent, toolInput/tool_input.subagent_type
Expand Down Expand Up @@ -1080,8 +1093,21 @@ def main():
if subagent_type in AGENTS_REQUIRE_TASK:
if not task_dir:
sys.exit(0)
# Check if task directory exists
task_dir_full = os.path.join(repo_root, task_dir)
# Contain the pointer before reading anything through it. `task.py` now
# refuses to store a ref that leaves the repo, but a session file
# written before that fix can still hold one, and `trellis update`
# does not rewrite session files — so a poisoned pointer outlives the
# upgrade that closed the writer. This is the last hop before the
# task's prd.md/design.md reach the model prompt, so it checks again.
try:
root_real = os.path.realpath(repo_root)
task_dir_full = os.path.realpath(os.path.join(repo_root, task_dir))
# ValueError on Windows when the two sit on different drives; that
# is outside the repo by definition, so it fails closed below.
if os.path.commonpath([root_real, task_dir_full]) != root_real:
sys.exit(0)
except (OSError, ValueError):
sys.exit(0)
if not os.path.exists(task_dir_full):
sys.exit(0)

Expand Down
Loading
Loading