@mindfoldhq/trellis 0.5.0-beta.1 → 0.5.0-beta.10

package/dist/templates/{cursor/agents/implement.md → claude/agents/trellis-implement.md}

@@ -1,9 +1,8 @@
 ---
-name: implement
+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
-model: opus
 ---
 # Implement Agent
 

package/dist/templates/{cursor/agents/research.md → claude/agents/trellis-research.md}

@@ -1,9 +1,8 @@
 ---
-name: research
+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__*
-model: opus
 ---
 # Research Agent
 

package/dist/templates/claude/settings.json

@@ -1,4 +1,7 @@
 {
+  "env": {
+    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
+  },
   "statusLine": {
     "type": "command",
     "command": "{{PYTHON_CMD}} .claude/hooks/statusline.py"

package/dist/templates/{cursor/agents/check.md → codebuddy/agents/trellis-check.md}

@@ -1,9 +1,8 @@
 ---
-name: check
+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
-model: opus
 ---
 # Check Agent
 

package/dist/templates/{claude/agents/implement.md → codebuddy/agents/trellis-implement.md}

@@ -1,9 +1,8 @@
 ---
-name: implement
+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
-model: opus
 ---
 # Implement Agent
 

package/dist/templates/{droid/droids/research.md → codebuddy/agents/trellis-research.md}

@@ -1,9 +1,8 @@
 ---
-name: research
+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__*
-model: opus
 ---
 # Research Agent
 

package/dist/templates/codex/agents/trellis-check.toml

@@ -0,0 +1,38 @@
+name = "trellis-check"
+description = "Workspace-write Trellis reviewer that self-fixes spec drift, lint/type-check failures, and missing tests."
+sandbox_mode = "workspace-write"
+
+developer_instructions = """
+You are the Trellis reviewer agent.
+
+Your job is to review code changes against specs AND fix issues directly — not just report them. You have write access; use it.
+
+Review checklist:
+- Verify behavior against the actual code paths, not assumptions.
+- Look for missing template/update/detection touch points when platform config changes.
+- Check whether tests should be added or updated.
+- Check whether `.trellis/spec/` docs need sync after implementation.
+- Run lint and type-check; fix any failures.
+- Prefer concrete findings over speculative warnings.
+
+When you find an 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.
+
+Output format:
+## Findings (fixed)
+- File: <path>
+- Issue: <what was wrong>
+- 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.
+
+## Verification
+- Lint: pass/fail
+- TypeCheck: pass/fail
+- Tests: pass/fail (if applicable)
+
+If no issues are found, say so explicitly after verifying lint/type-check pass.
+"""

package/dist/templates/codex/agents/{implement.toml → trellis-implement.toml}

@@ -1,4 +1,4 @@
-name = "implement"
+name = "trellis-implement"
 description = "Workspace-write Trellis implementer that follows specs and keeps generated templates in sync."
 sandbox_mode = "workspace-write"
 

package/dist/templates/codex/agents/{research.toml → trellis-research.toml}

@@ -1,4 +1,4 @@
-name = "research"
+name = "trellis-research"
 description = "Trellis researcher for specs, code patterns, and affected files. Writes findings into {TASK_DIR}/research/ — read-only elsewhere."
 sandbox_mode = "workspace-write"
 

package/dist/templates/codex/skills/start/SKILL.md

@@ -247,7 +247,7 @@ Use this output format:
 Initialize default context:
 
 ```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
 # type: backend | frontend | fullstack
 ```
 

package/dist/templates/common/skills/brainstorm.md

@@ -184,18 +184,61 @@ Examples:
 * The user asks for "best practice", "how others do it", "recommendation"
 * The user can't reasonably enumerate options
 
-### Research steps
+### Delegate to `trellis-research` sub-agent (don't research inline)
 
-1. Identify 2–4 comparable tools/patterns
+For each research topic, **spawn a `trellis-research` sub-agent via the Task tool** — don't do WebFetch / WebSearch / `gh api` inline in the main conversation.
+
+Why:
+- The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
+- It persists findings to `{TASK_DIR}/research/<topic>.md` (the contract — see `workflow.md` Phase 1.2)
+- It returns only `{file path, one-line summary}` to the main agent
+- Independent topics can be **parallelized** — spawn multiple sub-agents in one tool call
+
+Agent type: `trellis-research`
+Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
+
+❌ Bad (what you must NOT do):
+```
+Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
+          → WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
+          → Write(research/topic.md)
+```
+→ Pollutes main context with raw HTML/JSON, burns tokens.
+
+✅ Good:
+```
+Main agent: Task(subagent_type="trellis-research",
+                 prompt="Research topic A; persist to research/topic-a.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic B; persist to research/topic-b.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic C; persist to research/topic-c.md")
+→ Reads research/topic-{a,b,c}.md after they finish.
+```
+
+### Research steps (to pass into each sub-agent prompt)
+
+Each `trellis-research` sub-agent should:
+
+1. Identify 2–4 comparable tools/patterns for its topic
 2. Summarize common conventions and why they exist
 3. Map conventions onto our repo constraints
-4. Produce **2–3 feasible approaches** for our project
+4. Write findings to `{TASK_DIR}/research/<topic>.md`
+
+Main agent then reads the persisted files and produces **2–3 feasible approaches** in PRD.
 
 ### Research output format (PRD)
 
-Add a section in PRD (either within Technical Notes or as its own):
+The PRD itself should only reference the persisted research files, not duplicate their content. Add a `## Research References` section pointing at `research/*.md`.
+
+Optionally, add a convergence section with feasible approaches derived from the research:
 
 ```markdown
+## Research References
+
+* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
+* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
+
 ## Research Notes
 
 ### What similar tools do

package/dist/templates/copilot/prompts/start.prompt.md

@@ -54,7 +54,7 @@ cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
 cat .trellis/spec/guides/index.md              # Thinking guides (always read)
 ```
 
-> **Important**: The index files are navigation �?they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
+> **Important**: The index files are navigation �?they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
 > At this step, just read the indexes to understand what's available.
 > When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
 
@@ -72,8 +72,8 @@ When user describes a task, classify it:
 |------|----------|----------|
 | **Question** | User asks about code, architecture, or how something works | Answer directly |
 | **Trivial Fix** | Typo fix, comment update, single-line change | Direct Edit |
-| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm �?Implement |
-| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm �?Task Workflow** |
+| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm �?Implement |
+| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm �?Task Workflow** |
 
 ### Classification Signals
 
@@ -128,7 +128,7 @@ For simple, well-defined tasks:
 
 ## Complex Task - Brainstorm First
 
-For complex or vague tasks, **automatically start the brainstorm process** �?do NOT skip directly to implementation.
+For complex or vague tasks, **automatically start the brainstorm process** �?do NOT skip directly to implementation.
 
 See `/` for the full process. Summary:
 
@@ -167,10 +167,10 @@ See `/` for the full process. Summary:
 
 ```
 From Brainstorm (Complex Task):
-  PRD confirmed �?Research �?Configure Context �?Activate �?Implement �?Check �?Complete
+  PRD confirmed �?Research �?Configure Context �?Activate �?Implement �?Check �?Complete
 
 From Simple Task:
-  Confirm �?Create Task �?Write PRD �?Research �?Configure Context �?Activate �?Implement �?Check �?Complete
+  Confirm �?Create Task �?Write PRD �?Research �?Configure Context �?Activate �?Implement �?Check �?Complete
 ```
 
 **Key principle: Research happens AFTER requirements are clear (PRD exists).**
@@ -248,7 +248,7 @@ Based on the confirmed PRD, call Research Agent to find relevant specs and patte
 
 ```
 Task(
-  subagent_type: "research",
+  subagent_type: "trellis-research",
   prompt: "Analyze the codebase for this task:
 
   Task: <goal from PRD>
@@ -267,8 +267,7 @@ Task(
   - <pattern>: <example file path>
 
   ## Files to Modify
-  - <path>: <what change>",
-  model: "opus"
+  - <path>: <what change>"
 )
 ```
 
@@ -277,7 +276,7 @@ Task(
 Initialize default context:
 
 ```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
 # type: backend | frontend | fullstack
 ```
 
@@ -307,12 +306,11 @@ Call Implement Agent (code-spec context is auto-injected by hook):
 
 ```
 Task(
-  subagent_type: "implement",
+  subagent_type: "trellis-implement",
   prompt: "Implement the task described in prd.md.
 
   Follow all code-spec files that have been injected into your context.
-  Run lint and typecheck before finishing.",
-  model: "opus"
+  Run lint and typecheck before finishing."
 )
 ```
 
@@ -322,12 +320,11 @@ Call Check Agent (code-spec context is auto-injected by hook):
 
 ```
 Task(
-  subagent_type: "check",
+  subagent_type: "trellis-check",
   prompt: "Review all code changes against the code-spec requirements.
 
   Fix any issues you find directly.
-  Ensure lint and typecheck pass.",
-  model: "opus"
+  Ensure lint and typecheck pass."
 )
 ```
 

package/dist/templates/{droid/droids/check.md → cursor/agents/trellis-check.md}

@@ -1,9 +1,8 @@
 ---
-name: check
+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
-model: opus
 ---
 # Check Agent
 

package/dist/templates/{codebuddy/agents/implement.md → cursor/agents/trellis-implement.md}

@@ -1,9 +1,8 @@
 ---
-name: implement
+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
-model: opus
 ---
 # Implement Agent
 

package/dist/templates/{claude/agents/research.md → cursor/agents/trellis-research.md}

@@ -1,9 +1,8 @@
 ---
-name: research
+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__*
-model: opus
 ---
 # Research Agent
 

package/dist/templates/{codebuddy/agents/check.md → droid/droids/trellis-check.md}

@@ -1,9 +1,8 @@
 ---
-name: check
+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
-model: opus
 ---
 # Check Agent
 

package/dist/templates/droid/droids/{implement.md → trellis-implement.md}

@@ -1,9 +1,8 @@
 ---
-name: implement
+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
-model: opus
 ---
 # Implement Agent
 

package/dist/templates/{codebuddy/agents/research.md → droid/droids/trellis-research.md}

@@ -1,9 +1,8 @@
 ---
-name: research
+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__*
-model: opus
 ---
 # Research Agent
 

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

@@ -0,0 +1,94 @@
+---
+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
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Context
+
+Before checking, read:
+- `.trellis/spec/` - Development guidelines
+- 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
+
+## Important
+
+**Fix issues yourself**, don't just report them.
+
+You have write and edit tools, you can modify code directly.
+
+---
+
+## Workflow
+
+### Step 1: Get Changes
+
+```bash
+git diff --name-only  # List changed files
+git diff              # View specific changes
+```
+
+### Step 2: Check Against Specs
+
+Read relevant specs in `.trellis/spec/` to check code:
+
+- Does it follow directory structure conventions
+- Does it follow naming conventions
+- Does it follow code patterns
+- Are there missing types
+- Are there potential bugs
+
+### Step 3: Self-Fix
+
+After finding issues:
+
+1. Fix the issue directly (use edit tool)
+2. Record what was fixed
+3. Continue checking other issues
+
+### Step 4: Run Verification
+
+Run project's lint and typecheck commands to verify changes.
+
+If failed, fix issues and re-run.
+
+---
+
+## Report Format
+
+```markdown
+## Self-Check Complete
+
+### Files Checked
+
+- src/components/Feature.tsx
+- src/hooks/useFeature.ts
+
+### Issues Found and Fixed
+
+1. `<file>:<line>` - <what was fixed>
+2. `<file>:<line>` - <what was fixed>
+
+### Issues Not Fixed
+
+(If there are issues that cannot be self-fixed, list them here with reasons)
+
+### Verification Results
+
+- TypeCheck: Passed
+- Lint: Passed
+
+### Summary
+
+Checked X files, found Y issues, all fixed.
+```

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

@@ -0,0 +1,94 @@
+---
+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
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## Context
+
+Before implementing, read:
+- `.trellis/workflow.md` - Project workflow
+- `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `info.md` - Technical design (if exists)
+
+## Core Responsibilities
+
+1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
+2. **Understand requirements** - Read prd.md and info.md
+3. **Implement features** - Write code following specs and design
+4. **Self-check** - Ensure code quality
+5. **Report results** - Report completion status
+
+## Forbidden Operations
+
+**Do NOT execute these git commands:**
+
+- `git commit`
+- `git push`
+- `git merge`
+
+---
+
+## Workflow
+
+### 1. Understand Specs
+
+Read relevant specs based on task type:
+
+- Spec layers: `.trellis/spec/<package>/<layer>/`
+- Shared guides: `.trellis/spec/guides/`
+
+### 2. Understand Requirements
+
+Read the task's prd.md and info.md:
+
+- What are the core requirements
+- Key points of technical design
+- Which files to modify/create
+
+### 3. Implement Features
+
+- Write code following specs and technical design
+- Follow existing code patterns
+- Only do what's required, no over-engineering
+
+### 4. Verify
+
+Run project's lint and typecheck commands to verify changes.
+
+---
+
+## Report Format
+
+```markdown
+## Implementation Complete
+
+### Files Modified
+
+- `src/components/Feature.tsx` - New component
+- `src/hooks/useFeature.ts` - New hook
+
+### Implementation Summary
+
+1. Created Feature component...
+2. Added useFeature hook...
+
+### Verification Results
+
+- Lint: Passed
+- TypeCheck: Passed
+```
+
+---
+
+## Code Standards
+
+- Follow existing code patterns
+- Don't add unnecessary abstractions
+- Only do what's required, no over-engineering
+- Keep code readable