@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.10

package/dist/templates/{codebuddy/commands/trellis → common/skills}/update-spec.md

@@ -1,6 +1,6 @@
 # Update Code-Spec - Capture Executable Contracts
 
-When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents.
+When you learn something valuable (from debugging, implementing, or discussion), use this to update the relevant code-spec documents.
 
 **Timing**: After completing a task, fixing a bug, or discovering a new pattern
 
@@ -40,13 +40,13 @@ For triggered tasks, include all sections below:
 
 | Trigger | Example | Target Spec |
 |---------|---------|-------------|
-| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
-| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section |
-| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
-| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
-| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section |
-| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
-| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
+| **Implemented a feature** | Added a new integration or module | Relevant spec file |
+| **Made a design decision** | Chose extensibility pattern over simplicity | Relevant spec + "Design Decisions" section |
+| **Fixed a bug** | Found a subtle issue with error handling | Relevant spec (e.g., error-handling docs) |
+| **Discovered a pattern** | Found a better way to structure code | Relevant spec file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | Quality guidelines |
+| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item) |
 
 **Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
 
@@ -56,10 +56,7 @@ For triggered tasks, include all sections below:
 
 ```
 .trellis/spec/
-├── backend/           # Backend coding standards
-│   ├── index.md       # Overview and links
-│   └── *.md           # Topic-specific guidelines
-├── frontend/          # Frontend coding standards
+├── <layer>/           # Per-layer coding standards (e.g., backend/, frontend/, api/)
 │   ├── index.md       # Overview and links
 │   └── *.md           # Topic-specific guidelines
 └── guides/            # Thinking checklists (NOT coding specs!)
@@ -71,20 +68,20 @@ For triggered tasks, include all sections below:
 
 | Type | Location | Purpose | Content Style |
 |------|----------|---------|---------------|
-| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
+| **Code-Spec** | `<layer>/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
 | **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
 
 **Decision Rule**: Ask yourself:
 
-- "This is **how to write** the code" → Put in `backend/` or `frontend/`
+- "This is **how to write** the code" → Put in a spec layer directory
 - "This is **what to consider** before writing" → Put in `guides/`
 
 **Example**:
 
 | Learning | Wrong Location | Correct Location |
 |----------|----------------|------------------|
-| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` |
-| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` |
+| "Use API X not API Y for this task" | ❌ `guides/` (too specific for a thinking guide) | ✅ Relevant spec file (concrete convention) |
+| "Remember to check X when doing Y" | ❌ Spec file (too abstract for a spec) | ✅ `guides/` (thinking checklist) |
 
 **Guides should be short checklists that point to specs**, not duplicate the detailed rules.
 
@@ -332,15 +329,15 @@ Before finishing your code-spec update:
 
 ```
 Development Flow:
-  Learn something → /trellis:update-spec → Knowledge captured
+  Learn something → {{CMD_REF:update-spec}} → Knowledge captured
        ↑                                  ↓
-  /trellis:break-loop ←──────────────────── Future sessions benefit
+  {{CMD_REF:break-loop}} ←──────────────────── Future sessions benefit
   (deep bug analysis)
 ```
 
-- `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
-- `/trellis:update-spec` - Actually makes the updates (this command)
-- `/trellis:finish-work` - Reminds you to check if specs need updates
+- `{{CMD_REF:break-loop}}` - Analyzes bugs deeply, often reveals spec updates needed
+- `{{CMD_REF:update-spec}}` - Actually makes the updates
+- `{{CMD_REF:finish-work}}` - Reminds you to check if specs need updates
 
 ---
 

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

@@ -125,30 +125,48 @@ def _get_task_status(trellis_dir: Path) -> str:
     return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
 
 
-def _build_workflow_toc(workflow_path: Path) -> str:
-    """Build a compact section index for workflow.md (lazy-load the full file on demand).
+def _extract_range(content: str, start_header: str, end_header: str) -> str:
+    """Extract lines starting at `## start_header` up to (but excluding) `## end_header`."""
+    lines = content.splitlines()
+    start: "int | None" = None
+    end: int = len(lines)
+    start_match = f"## {start_header}"
+    end_match = f"## {end_header}"
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if start is None and stripped == start_match:
+            start = i
+            continue
+        if start is not None and stripped == end_match:
+            end = i
+            break
+    if start is None:
+        return ""
+    return "\n".join(lines[start:end]).rstrip()
 
-    Replaces full-file injection to keep additionalContext payload small.
-    The full file is accessible via: Read tool on .trellis/workflow.md
-    """
+
+def _build_workflow_toc(workflow_path: Path) -> str:
+    """Inject workflow guide: TOC + Phase Index + Phase 1/2/3 step details."""
     content = read_file(workflow_path)
     if not content:
         return "No workflow.md found"
 
-    toc_lines = [
+    out_lines = [
         "# Development Workflow — Section Index",
         "Full guide: .trellis/workflow.md  (read on demand)",
         "",
+        "## Table of Contents",
     ]
     for line in content.splitlines():
         if line.startswith("## "):
-            toc_lines.append(line)
+            out_lines.append(line)
+    out_lines += ["", "---", ""]
 
-    toc_lines += [
-        "",
-        "To read a section: use the Read tool on .trellis/workflow.md",
-    ]
-    return "\n".join(toc_lines)
+    phases = _extract_range(content, "Phase Index", "Workflow State Breadcrumbs")
+    if phases:
+        out_lines.append(phases)
+
+    return "\n".join(out_lines).rstrip()
 
 
 def main() -> None:
@@ -183,38 +201,56 @@ Read and follow all instructions below carefully.
     output.write("\n</workflow>\n\n")
 
     output.write("<guidelines>\n")
-    output.write("**Note**: The guidelines below are index files — they list available guideline documents and their locations.\n")
-    output.write("During actual development, you MUST read the specific guideline files listed in each index's Pre-Development Checklist.\n\n")
-
+    output.write(
+        "Project spec indexes are listed by path below. Each index contains a "
+        "**Pre-Development Checklist** listing the specific guideline files to "
+        "read before coding.\n\n"
+        "- If you're spawning an implement/check sub-agent, context is injected "
+        "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT "
+        "need to read these indexes yourself.\n"
+        "- If you're editing code directly in the main session, Read the relevant "
+        "index(es) on-demand and follow their Pre-Dev Checklist.\n\n"
+    )
+
+    # guides/ inlined (cross-package thinking, broadly useful)
+    guides_index = trellis_dir / "spec" / "guides" / "index.md"
+    if guides_index.is_file():
+        output.write("## guides (inlined — cross-package thinking guides)\n")
+        output.write(read_file(guides_index))
+        output.write("\n\n")
+
+    # Other indexes — paths only
+    paths: list[str] = []
     spec_dir = trellis_dir / "spec"
     if spec_dir.is_dir():
         for sub in sorted(spec_dir.iterdir()):
             if not sub.is_dir() or sub.name.startswith("."):
                 continue
-
             if sub.name == "guides":
-                index_file = sub / "index.md"
-                if index_file.is_file():
-                    output.write(f"## {sub.name}\n")
-                    output.write(read_file(index_file))
-                    output.write("\n\n")
                 continue
-
             index_file = sub / "index.md"
             if index_file.is_file():
-                output.write(f"## {sub.name}\n")
-                output.write(read_file(index_file))
-                output.write("\n\n")
+                paths.append(f".trellis/spec/{sub.name}/index.md")
             else:
                 for nested in sorted(sub.iterdir()):
                     if not nested.is_dir():
                         continue
                     nested_index = nested / "index.md"
                     if nested_index.is_file():
-                        output.write(f"## {sub.name}/{nested.name}\n")
-                        output.write(read_file(nested_index))
-                        output.write("\n\n")
-
+                        paths.append(
+                            f".trellis/spec/{sub.name}/{nested.name}/index.md"
+                        )
+
+    if paths:
+        output.write("## Available spec indexes (read on demand)\n")
+        for p in paths:
+            output.write(f"- {p}\n")
+        output.write("\n")
+
+    output.write(
+        "Discover more via: "
+        "`python3 ./.trellis/scripts/get_context.py --mode packages`\n"
+    )
     output.write("</guidelines>\n\n")
 
     task_status = _get_task_status(trellis_dir)

package/dist/templates/copilot/hooks.json

@@ -6,6 +6,14 @@
         "command": "{{PYTHON_CMD}} .github/copilot/hooks/session-start.py",
         "timeout": 10
       }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "{{PYTHON_CMD}} .github/copilot/hooks/inject-workflow-state.py",
+        "powershell": "{{PYTHON_CMD}} .github/copilot/hooks/inject-workflow-state.py",
+        "timeoutSec": 5
+      }
     ]
   }
 }

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/cursor/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/cursor/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

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

@@ -0,0 +1,137 @@
+---
+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__*
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session.
+
+---
+
+## Core Responsibilities
+
+1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read)
+2. **External Search** — library docs, API references, best practices (web search)
+3. **Persist** — write each research topic to `{TASK_DIR}/research/<topic>.md`
+4. **Report** — return file paths + one-line summaries to the main agent (not full content)
+
+---
+
+## Workflow
+
+### Step 1: Resolve Current Task
+
+Read `.trellis/.current-task` → task directory (e.g. `.trellis/tasks/04-17-foo/`). If empty or missing, ask the user where to write output; do NOT guess.
+
+Ensure `{TASK_DIR}/research/` exists:
+
+```bash
+mkdir -p <TASK_DIR>/research
+```
+
+### Step 2: Understand Search Request
+
+Classify: internal / external / mixed. Determine scope (global / specific directory) and expected shape (file list / pattern notes / tech comparison).
+
+### Step 3: Execute Search
+
+Run independent searches in parallel (Glob + Grep + web) for efficiency.
+
+### Step 4: Persist Each Topic
+
+For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.
+
+### Step 5: Report to Main Agent
+
+Reply with ONLY:
+
+- List of files written (paths relative to repo root)
+- One-line summary per file
+- Any critical caveats that the main agent needs to know right now
+
+Do NOT paste full research content into the reply. The files are the contract.
+
+---
+
+## Scope Limits (Strict)
+
+### Write ALLOWED
+
+- `{TASK_DIR}/research/*.md` — your own output
+- Creating `{TASK_DIR}/research/` if it doesn't exist (via `mkdir -p`)
+
+### Write FORBIDDEN
+
+- Code files (`src/`, `lib/`, …)
+- Spec files (`.trellis/spec/`) — main agent should use `update-spec` skill instead
+- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.claude/`, `.cursor/`, etc.)
+- Other task directories
+- Any git operation (commit / push / branch / merge)
+
+If the user asks you to edit code, decline and suggest spawning `implement` instead.
+
+---
+
+## File Format
+
+Each `{TASK_DIR}/research/<topic>.md` should follow:
+
+```markdown
+# Research: <topic>
+
+- **Query**: <original query>
+- **Scope**: <internal / external / mixed>
+- **Date**: <YYYY-MM-DD>
+
+## Findings
+
+### Files Found
+
+| File Path | Description |
+|---|---|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Patterns
+
+<describe patterns, cite file:line>
+
+### External References
+
+- [Library X docs](url) — <why relevant, version constraints>
+
+### Related Specs
+
+- `.trellis/spec/xxx.md` — <description>
+
+## Caveats / Not Found
+
+<anything incomplete or uncertain>
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets
+- Persist every topic to its own file
+- Return file paths in your reply, not the full content
+- Mark "not found" explicitly when searches come up empty
+
+### DON'T
+
+- Don't write code or modify files outside `{TASK_DIR}/research/`
+- Don't guess uncertain info
+- Don't paste full research text into the reply (files are the deliverable)
+- Don't propose improvements or critique implementation (that's not your role)

package/dist/templates/cursor/hooks.json

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "{{PYTHON_CMD}} .cursor/hooks/inject-subagent-context.py",
+        "matcher": "Task",
+        "timeout": 30
+      }
+    ],
+    "sessionStart": [
+      {
+        "command": "{{PYTHON_CMD}} .cursor/hooks/session-start.py",
+        "timeout": 10
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "{{PYTHON_CMD}} .cursor/hooks/inject-workflow-state.py",
+        "timeout": 5
+      }
+    ]
+  }
+}