@mindfoldhq/trellis 0.6.0-beta.9 → 0.6.0-rc.0

package/dist/templates/common/bundled-skills/trellis-session-insight/references/triggering-patterns.md

@@ -0,0 +1,93 @@
+# Triggering Patterns
+
+Verbatim user phrasings that should make an AI reach for `trellis mem`. Calibrate instinct against these — if a user message hits one of these patterns and you do not reach for `mem`, you probably missed an obvious recall.
+
+Patterns are grouped by the *intent* behind the phrasing, not the surface words. The same intent shows up in different languages and registers.
+
+## Past-solution recall
+
+The user is asking "how did we (or I) solve this before". Past dialogue holds the answer; the codebase shows the result but not the reasoning.
+
+- "How did we solve this last time?"
+- "What did we end up doing about X?"
+- "We dealt with this once already, didn't we?"
+- "上次怎么解的?"
+- "之前是怎么搞定 X 的?"
+- "我记得以前修过类似的"
+
+Reach: `trellis mem search "<symptom keyword>" --global --limit 10`, then `context` into the hit that looks closest.
+
+## Decision retrieval
+
+The user is referencing a decision that lives in old dialogue, not in any committed file. Look in brainstorm windows.
+
+- "What was the decision on X?"
+- "Did we decide to use Postgres or SQLite?"
+- "The rationale for choosing X over Y was…?"
+- "我们当时为啥选了 X 而不是 Y?"
+- "关于 X 我们之前是怎么定的?"
+- "之前讨论过 X 的方案吗?"
+
+Reach: `trellis mem search "<decision keyword>"` to find the session, then `extract <id> --phase brainstorm` to recover the discussion.
+
+## Cross-session continuation
+
+The user resumed work after a gap and the context is implicit.
+
+- "Where were we?"
+- "Continue from last time."
+- "Pick up where we left off."
+- "继续上次的"
+- "我们上次做到哪了"
+- "接着昨天那个任务"
+
+Reach: `trellis mem list --task <current-task-dir>` to find the most recent sessions tied to the active task, then `extract` the last one.
+
+## Familiar-bug debugging
+
+The current bug feels like one already seen. Past sessions probably hold the resolution path.
+
+- "I feel like I've hit this before."
+- "Doesn't this look like that bug from last month?"
+- "Same kind of timeout I had in X."
+- "这个错好像之前见过"
+- "这个 bug 是不是上次那个?"
+- "怎么又是这个 error?"
+
+Reach: `trellis mem search "<error message fragment>" --global`. Anchor on a short, distinctive token from the actual error string.
+
+## Self-pattern spotting
+
+The user is asking whether they keep repeating the same kind of mistake or decision.
+
+- "Do I always make this mistake?"
+- "How often have I run into X?"
+- "Is this a recurring thing for me?"
+- "我每次都踩这个坑吗?"
+- "我老犯这个错?"
+- "这类问题之前出现过几次?"
+
+Reach: `trellis mem search "<topic>" --global --limit 50` and scan the dates / projects in the listing. Optionally `extract` two or three for comparison.
+
+## Finish-work retrospective (on demand)
+
+The user explicitly wants to look back at this task — not as a forced step, only when they ask.
+
+- "Summarize what we did in this task."
+- "What were the key decisions / surprises?"
+- "Write up the lessons from this round."
+- "总结一下这次的经验"
+- "记一下这次踩的坑"
+- "复盘下这个任务"
+
+Reach: identify the current task's session id (from `.trellis/.runtime/sessions/*.json` or `mem list --task <task-dir>`), then `extract <id> --phase brainstorm` and `--phase implement`. Present a summary — surface concrete file:line citations where possible. Whether to also write the summary somewhere (PRD, spec, notes file) is the user's call; offer, don't auto-write.
+
+## Anti-patterns: do NOT reach for `mem` here
+
+- "What does this function do?" → read the file.
+- "Why is this test failing?" → read the test output and the file.
+- "What's the right pattern for X in our codebase?" → grep / read spec files.
+- "What's the latest npm version of Y?" → call `npm view`.
+- "Fix this bug." → debug. Reach for `mem` only if you suspect prior context exists; otherwise it is noise.
+
+The bar stays: would a senior teammate ask "didn't we already talk about this?" before answering? If yes, reach for `mem`. If no, don't.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: trellis-spec-bootstrap
+description: "Bootstrap project-specific Trellis coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .trellis/spec guidelines, analyzing a codebase with GitNexus, ABCoder, or source inspection, decomposing package/layer spec work, and writing real codebase-backed spec docs without placeholder text."
+---
+
+# Trellis Spec Bootstrap
+
+Use this skill to create or refresh `.trellis/spec/` guidelines from the real codebase. One capable agent owns the full loop: analyze the repository, choose the spec boundaries, write the docs, and verify the result. The workflow does not depend on a specific host, CLI, or agent brand.
+
+## Workflow
+
+1. Confirm Trellis is initialized and inspect the current `.trellis/spec/` tree.
+2. Analyze the repository architecture with the best available tools: GitNexus, ABCoder, language tooling, and direct source reads.
+3. Decompose the spec work by package and layer only when that reflects the actual codebase.
+4. Fill or reshape the spec files with concrete patterns, file paths, examples, and anti-patterns from the project.
+5. Verify that the final specs are internally consistent and contain no template placeholders.
+
+## Reference Routing
+
+| Need | Read |
+|------|------|
+| Repository architecture analysis | [references/repository-analysis.md](references/repository-analysis.md) |
+| Spec work decomposition and task planning | [references/spec-task-planning.md](references/spec-task-planning.md) |
+| Writing high-signal Trellis spec files | [references/spec-writing.md](references/spec-writing.md) |
+| GitNexus and ABCoder MCP setup | [references/mcp-setup.md](references/mcp-setup.md) |
+
+## Operating Rules
+
+- Treat templates as starting points, not contracts. Delete, rename, split, or add spec files when the repository calls for it.
+- Prefer source-backed rules over generic advice. Every important recommendation should point at a real file or repeated local pattern.
+- Keep execution single-owner by default. Optional helper agents are an implementation detail, not a requirement or user-visible dependency.
+- Do not write platform-specific instructions unless the target project already standardizes on that platform.
+- Do not leave placeholder text, empty headings, or copied boilerplate in `.trellis/spec/`.
+
+## Done Criteria
+
+- `.trellis/spec/` describes the project as it exists now.
+- Each relevant package or layer has practical coding guidance with real examples.
+- Non-applicable template sections are removed.
+- `index.md` files match the final spec file set.
+- Any required setup or analysis assumptions are documented in the relevant spec or task notes.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/mcp-setup.md

@@ -0,0 +1,90 @@
+# MCP Setup
+
+GitNexus and ABCoder are recommended when bootstrapping Trellis specs because they expose architecture and AST context to the agent. They are tool choices, not platform requirements. Configure them through whatever MCP mechanism your agent host provides.
+
+## GitNexus
+
+GitNexus builds a code knowledge graph from the repository. Use it for module boundaries, execution flows, dependency relationships, blast radius, and graph queries.
+
+### Install and Index
+
+```bash
+# Run from the repository root.
+npx gitnexus analyze
+
+# Check index status.
+npx gitnexus status
+
+# Re-index after code changes when the analysis is stale.
+npx gitnexus analyze
+```
+
+The index is written to `.gitnexus/`. Keep embeddings only if the project already uses them; otherwise a normal index is enough for spec bootstrapping.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+npx -y gitnexus mcp
+```
+
+### Useful Tools
+
+| Tool | Purpose |
+|------|---------|
+| `gitnexus_query` | Find execution flows and functional areas by concept |
+| `gitnexus_context` | Inspect callers, callees, references, and process participation for a symbol |
+| `gitnexus_impact` | Understand blast radius before changing a symbol |
+| `gitnexus_detect_changes` | Check changed symbols and affected flows before finishing |
+| `gitnexus_cypher` | Run direct graph queries |
+| `gitnexus_list_repos` | List indexed repositories |
+
+## ABCoder
+
+ABCoder parses code into UniAST and gives precise package, file, and node-level structure. Use it for signatures, type shapes, implementations, dependencies, and reverse references.
+
+### Install
+
+```bash
+go install github.com/cloudwego/abcoder@latest
+abcoder --help
+```
+
+### Parse Repositories
+
+```bash
+abcoder parse /absolute/path/to/package \
+  --lang typescript \
+  --name package-name \
+  --output ~/abcoder-asts
+```
+
+For monorepos, parse each package with a stable `--name` so task notes can reference the same repository names.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+abcoder mcp ~/abcoder-asts
+```
+
+### Useful Tools
+
+| Tool | Layer | Purpose |
+|------|-------|---------|
+| `list_repos` | 1 | List parsed repositories |
+| `get_repo_structure` | 2 | Inspect packages and files |
+| `get_package_structure` | 3 | Inspect nodes within a package |
+| `get_file_structure` | 3 | Inspect functions, classes, types, and signatures in a file |
+| `get_ast_node` | 4 | Retrieve code, dependencies, references, and implementations |
+
+## Verification
+
+After configuration, verify from the agent host that both MCP servers are visible. Then run one simple query against each server before starting the spec writing pass.
+
+```bash
+ls .gitnexus/meta.json
+ls ~/abcoder-asts/*.json
+```

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/repository-analysis.md

@@ -0,0 +1,59 @@
+# Repository Analysis
+
+The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.
+
+## Analysis Order
+
+1. Read the existing `.trellis/spec/` tree and note which files are templates, outdated, or already project-specific.
+2. Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
+3. Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
+4. Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
+5. Read representative source and test files directly before turning any finding into a spec rule.
+
+## What To Capture
+
+| Area | Questions |
+|------|-----------|
+| Package boundaries | What does each package own? What imports cross boundaries? |
+| Runtime layers | Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling? |
+| Core abstractions | Which types, services, stores, commands, routes, or adapters define the system shape? |
+| Data flow | Where does user input enter, how is it validated, and where does state persist? |
+| Error handling | How are failures represented, logged, surfaced, and tested? |
+| Configuration | Where do defaults, environment config, generated files, and templates live? |
+| Tests | Which test styles are trusted examples for new work? |
+
+## GitNexus Usage
+
+Start broad, then inspect specific symbols:
+
+```text
+gitnexus_query({query: "CLI command execution flow"})
+gitnexus_query({query: "template generation and migration"})
+gitnexus_context({name: "SymbolName"})
+gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})
+```
+
+Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.
+
+## ABCoder Usage
+
+Use ABCoder when the spec needs exact code shapes:
+
+```text
+list_repos()
+get_repo_structure({repo_name: "package-name"})
+get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
+get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})
+```
+
+ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.
+
+## Analysis Notes
+
+Keep short notes while analyzing. The notes should include:
+
+- Package or layer name.
+- Files that define the local pattern.
+- Rules the spec should teach.
+- Anti-patterns found in old code, comments, tests, or migration paths.
+- Spec files that should be created, deleted, renamed, or merged.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/spec-task-planning.md

@@ -0,0 +1,61 @@
+# Spec Task Planning
+
+Use a single agent as the default execution model. The agent may create Trellis tasks for traceability, but the skill should not require a specific platform, CLI, or parallel worker model.
+
+## Decomposition
+
+Create spec work units around real ownership boundaries:
+
+- One package when a package has its own conventions.
+- One layer when the same package has distinct frontend, backend, CLI, worker, or shared-library rules.
+- One cross-cutting guide when a pattern spans packages and is not owned by one layer.
+
+Avoid artificial decomposition. A small library usually needs one focused spec pass, not several tasks.
+
+## Task Shape
+
+When a Trellis task is useful, write a concise PRD with these sections:
+
+```markdown
+# Fill <package-or-layer> Trellis Specs
+
+## Goal
+Write project-specific `.trellis/spec/` guidance for <scope>.
+
+## Scope
+- Spec directory:
+- Source directories to inspect:
+- Tests to inspect:
+- Out of scope:
+
+## Architecture Context
+Summarize the concrete findings from repository analysis.
+
+## Files To Create Or Update
+- `.trellis/spec/.../index.md`
+- `.trellis/spec/.../<topic>.md`
+
+## Rules
+- Adapt the spec file set to the real codebase.
+- Use real source examples with file paths.
+- Remove template-only sections that do not apply.
+- Do not modify product source code unless the task explicitly asks for it.
+
+## Acceptance Criteria
+- [ ] Specs contain concrete examples and anti-patterns from the repository.
+- [ ] No placeholder text remains.
+- [ ] Index files match the final spec files.
+- [ ] Claims are backed by source files, tests, or project docs.
+```
+
+## Optional Helper Agents
+
+If the host supports subagents, helpers can inspect independent packages or run verification. They are optional. The main agent still owns integration and final quality.
+
+Helper tasks must have clear ownership:
+
+- Read-only research tasks may inspect any source needed for the assigned scope.
+- Write tasks should own disjoint spec directories.
+- Verification tasks should check placeholder removal, broken links, and consistency.
+
+Do not encode helper-agent names, vendor-specific commands, or platform-specific routing in the skill. Put only the required work and acceptance criteria in the task.

package/dist/templates/common/bundled-skills/trellis-spec-bootstrap/references/spec-writing.md

@@ -0,0 +1,70 @@
+# Spec Writing
+
+Trellis specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.
+
+## Write From Evidence
+
+Each important rule should be backed by one of these:
+
+- A source file that demonstrates the preferred pattern.
+- A test file that shows expected behavior.
+- A project document that defines the convention.
+- A repeated pattern across multiple files.
+
+Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.
+
+## File Structure
+
+Keep the spec tree aligned with the project:
+
+- Keep `index.md` as the navigation file for the spec directory.
+- Split topics when developers would look for them independently.
+- Merge topics when separate files would repeat the same rule.
+- Delete template files that do not apply.
+- Add new files for important local patterns the template missed.
+
+## Content Standards
+
+Good spec sections include:
+
+- When the rule applies.
+- The local pattern to follow.
+- The source or test files that prove the pattern.
+- Common mistakes or anti-patterns.
+- Verification commands or checks when they are specific and reliable.
+
+Avoid:
+
+- Placeholder prose.
+- Generic framework advice.
+- Tool instructions that only work in one agent host.
+- Long copied code blocks.
+- Rules based on a single accidental implementation detail.
+
+## Example Shape
+
+```markdown
+## Command Handlers
+
+Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:
+
+- Parse CLI flags at the command boundary.
+- Convert raw inputs into typed task options before invoking core logic.
+- Keep filesystem writes in the command or service layer, not in template helpers.
+
+Reference files:
+- `packages/cli/src/commands/example.ts`
+- `packages/cli/test/commands/example.test.ts`
+
+Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.
+```
+
+## Final Pass
+
+Before finishing:
+
+```bash
+grep -R "To be filled\\|TODO: fill\\|placeholder" .trellis/spec
+```
+
+Also check links, index files, and whether any spec still describes a template rather than this repository.

package/dist/templates/copilot/hooks/session-start.py

@@ -17,6 +17,30 @@ breadcrumbs remain available as a per-turn complement.
 
 from __future__ import annotations
 
+import sys
+
+# Force UTF-8 on stdin/stdout/stderr on Windows. Default codepage there is
+# cp936 / cp1252 / etc. — non-ASCII content (Chinese task names, prd snippets)
+# both in stdin (hook payload from host CLI) and stdout (our emitted blocks)
+# raises UnicodeDecodeError / UnicodeEncodeError. Equivalent to `python -X utf8`
+# but applied per-stream so we don't depend on host CLI's command wiring.
+if sys.platform.startswith("win"):
+    import io as _io
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            except Exception:
+                pass
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
+            except Exception:
+                pass
+
 import json
 import os
 import re

package/dist/templates/cursor/agents/trellis-check.md

@@ -1,7 +1,7 @@
 ---
 name: trellis-check
 description: Trellis quality check agent. Use this exact agent for Trellis task verification, check.jsonl context injection, and self-fixing code review. Do not use generic/default/generalPurpose agents for Trellis checks.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Check Agent
 
@@ -26,14 +26,18 @@ Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -52,10 +56,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

package/dist/templates/cursor/agents/trellis-implement.md

@@ -1,7 +1,7 @@
 ---
 name: trellis-implement
 description: Trellis implementation agent. Use this exact agent for Trellis task implementation, implement.jsonl context injection, and hook-injection tests. Do not use generic/default/generalPurpose agents for Trellis implementation. No git commit allowed.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Implement Agent
 

package/dist/templates/cursor/agents/trellis-research.md

@@ -1,7 +1,7 @@
 ---
 name: trellis-research
 description: Trellis research agent. Use this exact agent for Trellis task research and research/ persistence. Do not use generic/default/generalPurpose agents for Trellis research.
-tools: Read, Write, Glob, Grep, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+tools: Read, Write, Glob, Grep, Bash, Skill, mcp__*
 ---
 # Research Agent
 

package/dist/templates/cursor/hooks.json

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

package/dist/templates/droid/droids/trellis-check.md

@@ -2,7 +2,7 @@
 name: trellis-check
 description: |
   Code quality check expert. Reviews code changes against specs and self-fixes issues.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Check Agent
 
@@ -19,14 +19,18 @@ Look for the `<!-- trellis-hook-injected -->` marker in your input above.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -45,10 +49,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

package/dist/templates/droid/droids/trellis-implement.md

@@ -2,7 +2,7 @@
 name: trellis-implement
 description: |
   Code implementation expert. Understands specs and requirements, then implements features. No git commit allowed.
-tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 # Implement Agent
 

package/dist/templates/droid/droids/trellis-research.md

@@ -2,7 +2,7 @@
 name: trellis-research
 description: |
   Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory.
-tools: Read, Write, Glob, Grep, Bash, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
+tools: Read, Write, Glob, Grep, Bash, Skill, mcp__*
 ---
 # Research Agent
 

package/dist/templates/gemini/agents/trellis-check.md

@@ -19,14 +19,18 @@ You are already the `trellis-check` sub-agent that the main session dispatched.
 
 Before checking, read:
 - `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` - Technical design (if exists)
+- Task `implement.md` - Execution plan (if exists)
 - Pre-commit checklist for quality standards
 
 ## Core Responsibilities
 
 1. **Get code changes** - Use git diff to get uncommitted code
-2. **Check against specs** - Verify code follows guidelines
-3. **Self-fix** - Fix issues yourself, not just report them
-4. **Run verification** - typecheck and lint
+2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present
+3. **Check against specs** - Verify code follows guidelines
+4. **Self-fix** - Fix issues yourself, not just report them
+5. **Run verification** - typecheck and lint
 
 ## Important
 
@@ -45,10 +49,12 @@ git diff --name-only  # List changed files
 git diff              # View specific changes
 ```
 
-### Step 2: Check Against Specs
+### Step 2: Check Against Specs and Task Artifacts
 
-Read relevant specs in `.trellis/spec/` to check code:
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:
 
+- Does it satisfy the task requirements
+- Does it follow the technical design and implementation plan when present
 - Does it follow directory structure conventions
 - Does it follow naming conventions
 - Does it follow code patterns

package/dist/templates/kiro/agents/trellis-check.json

@@ -1,7 +1,7 @@
 {
   "name": "trellis-check",
   "description": "Code quality check expert. Reviews code changes against specs and self-fixes issues.",
-  "prompt": "# Check Agent\n\nYou are the Check Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.\n\n- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: task artifacts, spec, and research files have already been auto-loaded for you above. Proceed with the check work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/check.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.\n\n## Context\n\nBefore checking, read:\n- `.trellis/spec/` - Development guidelines\n- Pre-commit checklist for quality standards\n\n## Core Responsibilities\n\n1. **Get code changes** - Use git diff to get uncommitted code\n2. **Check against specs** - Verify code follows guidelines\n3. **Self-fix** - Fix issues yourself, not just report them\n4. **Run verification** - typecheck and lint\n\n## Important\n\n**Fix issues yourself**, don't just report them.\n\nYou have write and edit tools, you can modify code directly.\n\n---\n\n## Workflow\n\n### Step 1: Get Changes\n\n```bash\ngit diff --name-only  # List changed files\ngit diff              # View specific changes\n```\n\n### Step 2: Check Against Specs\n\nRead relevant specs in `.trellis/spec/` to check code:\n\n- Does it follow directory structure conventions\n- Does it follow naming conventions\n- Does it follow code patterns\n- Are there missing types\n- Are there potential bugs\n\n### Step 3: Self-Fix\n\nAfter finding issues:\n\n1. Fix the issue directly (use edit tool)\n2. Record what was fixed\n3. Continue checking other issues\n\n### Step 4: Run Verification\n\nRun project's lint and typecheck commands to verify changes.\n\nIf failed, fix issues and re-run.\n\n---\n\n## Report Format\n\n```markdown\n## Self-Check Complete\n\n### Files Checked\n\n- src/components/Feature.tsx\n- src/hooks/useFeature.ts\n\n### Issues Found and Fixed\n\n1. `<file>:<line>` - <what was fixed>\n2. `<file>:<line>` - <what was fixed>\n\n### Issues Not Fixed\n\n(If there are issues that cannot be self-fixed, list them here with reasons)\n\n### Verification Results\n\n- TypeCheck: Passed\n- Lint: Passed\n\n### Summary\n\nChecked X files, found Y issues, all fixed.\n```",
+  "prompt": "# Check Agent\n\nYou are the Check Agent in the Trellis workflow.\n\n## Recursion Guard\n\nYou are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.\n\n- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.\n- If SessionStart context, workflow-state breadcrumbs, or workflow.md say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.\n- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.\n\n## Trellis Context Loading Protocol\n\nLook for the `<!-- trellis-hook-injected -->` marker in your input above.\n\n- **If the marker is present**: task artifacts, spec, and research files have already been auto-loaded for you above. Proceed with the check work directly.\n- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: <path>`, then Read `<task-path>/check.jsonl`, each listed file, `<task-path>/prd.md`, `<task-path>/design.md` if present, and `<task-path>/implement.md` if present before doing the work.\n\n## Context\n\nBefore checking, read:\n- `.trellis/spec/` - Development guidelines\n- Task `prd.md` - Requirements document\n- Task `design.md` - Technical design (if exists)\n- Task `implement.md` - Execution plan (if exists)\n- Pre-commit checklist for quality standards\n\n## Core Responsibilities\n\n1. **Get code changes** - Use git diff to get uncommitted code\n2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present\n3. **Check against specs** - Verify code follows guidelines\n4. **Self-fix** - Fix issues yourself, not just report them\n5. **Run verification** - typecheck and lint\n\n## Important\n\n**Fix issues yourself**, don't just report them.\n\nYou have write and edit tools, you can modify code directly.\n\n---\n\n## Workflow\n\n### Step 1: Get Changes\n\n```bash\ngit diff --name-only  # List changed files\ngit diff              # View specific changes\n```\n\n### Step 2: Check Against Specs and Task Artifacts\n\nRead the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code:\n\n- Does it satisfy the task requirements\n- Does it follow the technical design and implementation plan when present\n- Does it follow directory structure conventions\n- Does it follow naming conventions\n- Does it follow code patterns\n- Are there missing types\n- Are there potential bugs\n\n### Step 3: Self-Fix\n\nAfter finding issues:\n\n1. Fix the issue directly (use edit tool)\n2. Record what was fixed\n3. Continue checking other issues\n\n### Step 4: Run Verification\n\nRun project's lint and typecheck commands to verify changes.\n\nIf failed, fix issues and re-run.\n\n---\n\n## Report Format\n\n```markdown\n## Self-Check Complete\n\n### Files Checked\n\n- src/components/Feature.tsx\n- src/hooks/useFeature.ts\n\n### Issues Found and Fixed\n\n1. `<file>:<line>` - <what was fixed>\n2. `<file>:<line>` - <what was fixed>\n\n### Issues Not Fixed\n\n(If there are issues that cannot be self-fixed, list them here with reasons)\n\n### Verification Results\n\n- TypeCheck: Passed\n- Lint: Passed\n\n### Summary\n\nChecked X files, found Y issues, all fixed.\n```",
   "tools": [
     "read",
     "write",