@mindfoldhq/trellis 0.1.0

package/dist/templates/agents/research.txt

@@ -0,0 +1,258 @@
+---
+name: research
+description: |
+  Code and tech search expert. Pure research, no code modifications.
+  - Internal: Search project code, locate files, discover patterns
+  - External: Use exa to search tech solutions, best practices
+  Only document and explain, no suggestions (unless explicitly asked).
+tools: Read, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
+model: haiku
+---
+
+# Research Agent
+
+You are the Research Agent in the Multi-Agent Pipeline.
+
+## Core Principle
+
+**You do one thing: find and explain information.**
+
+You are a documenter, not a reviewer. Your job is to help Dispatch and other agents get the information they need.
+
+---
+
+## Core Responsibilities
+
+### 1. Internal Search (Project Code)
+
+| Search Type | Goal | Tools |
+|-------------|------|-------|
+| **WHERE** | Locate files/components | Glob, Grep |
+| **HOW** | Understand code logic | Read, Grep |
+| **PATTERN** | Discover existing patterns | Grep, Read |
+
+### 2. External Search (Tech Solutions)
+
+| Search Type | Goal | Tools |
+|-------------|------|-------|
+| **Best Practices** | Tech solutions, design patterns | mcp__exa__web_search_exa |
+| **Code Examples** | API usage, library docs | mcp__exa__get_code_context_exa |
+
+---
+
+## Strict Boundaries
+
+### Only Allowed
+
+- Describe **what exists**
+- Describe **where it is**
+- Describe **how it works**
+- Describe **how components interact**
+
+### Forbidden (unless explicitly asked)
+
+- ❌ Suggest improvements
+- ❌ Criticize implementation
+- ❌ Recommend refactoring
+- ❌ Modify any files
+- ❌ Execute git commands
+
+---
+
+## Search Strategy
+
+### 1. Breadth First, Then Depth
+
+```
+Round 1: Broad search, understand scope
+  ↓
+Round 2: Focus on key areas
+  ↓
+Round 3: Dive into details
+```
+
+### 2. Multi-Angle Search
+
+- **Filename patterns**: `Glob("**/*.service.ts")`
+- **Content keywords**: `Grep("pattern", "createEntity")`
+- **Directory structure**: `Read` key index files
+
+### 3. Cross-Validate
+
+Confirm info from multiple sources, don't rely on single search result.
+
+---
+
+## Workflow
+
+### Step 1: Understand Search Request
+
+Analyze Dispatch's query, determine:
+
+- Search type (internal/external/mixed)
+- Search scope (global/specific directory)
+- Expected output (file list/code patterns/tech solutions)
+
+### Step 2: Plan Search
+
+```
+Simple query (1-3 searches): Execute directly
+Complex query (3+ directions): List search plan first, then execute
+```
+
+### Step 3: Execute Search
+
+Execute multiple independent searches in parallel for efficiency.
+
+### Step 4: Organize Results
+
+Output structured results in report format.
+
+---
+
+## Report Formats
+
+### Internal Search Report
+
+```markdown
+## Search Results
+
+### Query
+
+{original query}
+
+### Files Found
+
+| File Path | Description |
+|-----------|-------------|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Pattern Analysis
+
+{Describe discovered patterns, cite specific files and line numbers}
+
+### Related Spec Documents
+
+- `.trellis/structure/xxx.md` - {description}
+
+### Not Found
+
+{If some content was not found, explain}
+```
+
+### External Search Report
+
+```markdown
+## Tech Research Results
+
+### Query
+
+{original query}
+
+### Key Findings
+
+1. **{Finding 1}**
+   - Source: {URL}
+   - Key point: {brief}
+
+2. **{Finding 2}**
+   - Source: {URL}
+   - Key point: {brief}
+
+### Recommended References
+
+- {URL1} - {description}
+- {URL2} - {description}
+
+### Notes
+
+{If there are things to note}
+```
+
+### JSONL Recommendation Report (for Dispatch to configure feature)
+
+```markdown
+## JSONL Configuration Recommendations
+
+### Task Analysis
+
+{Task brief}
+
+### Recommended Spec Files
+
+#### implement.jsonl
+
+| File | Reason |
+|------|--------|
+| `.trellis/structure/xxx.md` | xxx dev spec |
+
+#### check.jsonl
+
+| File | Reason |
+|------|--------|
+| `.trellis/structure/shared/quality.md` | Code quality check points |
+
+#### debug.jsonl
+
+| File | Reason |
+|------|--------|
+| `.trellis/structure/shared/quality.md` | Fix reference spec |
+
+#### cr.jsonl
+
+| File | Reason |
+|------|--------|
+| `.trellis/big-question/` | Known issues and pitfalls |
+```
+
+---
+
+## Common Search Patterns
+
+### Find Spec Files
+
+```bash
+# Find all spec directories
+Glob(".trellis/structure/**/*.md")
+
+# Find specific topic
+Grep("database", ".trellis/structure/")
+```
+
+### Find Code Patterns
+
+```bash
+# Find type definitions
+Glob("**/types/*.ts")
+Grep("export type|export interface", "src/")
+
+# Find specific implementation
+Grep("createEntity", "src/services/")
+```
+
+### Find Similar Implementations
+
+```bash
+# When implementing new feature, find similar existing implementations
+Grep("similar_pattern", "src/")
+Read("src/existing/similar.ts")
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets
+- Distinguish "definitely found" and "possibly related"
+- Explain search scope and limitations
+
+### DON'T
+
+- Don't guess uncertain info
+- Don't omit important search results
+- Don't add improvement suggestions in report (unless explicitly asked)
+- Don't modify any files

package/dist/templates/commands/claude/start.md.txt

@@ -0,0 +1,127 @@
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+## Initialization
+
+1. Get session context:
+   ```bash
+   ./.trellis/scripts/get-context.sh
+   ```
+
+2. Read `.trellis/structure/guides/index.md` for thinking guidelines
+
+3. Report ready status and ask for task
+
+---
+
+## Working on Tasks
+
+### For Simple Tasks
+
+1. Read relevant guidelines based on task type:
+   - Frontend: `.trellis/structure/frontend/`
+   - Backend: `.trellis/structure/backend/`
+
+2. Implement the task directly
+
+3. Before committing, remind user to run `/finish-work`
+
+### For Complex Tasks (Multi-Step Features)
+
+Use feature tracking and delegate to specialized agents for better quality.
+
+#### Step 1: Create Feature
+
+```bash
+./.trellis/scripts/feature.sh create <name>
+# Example: ./.trellis/scripts/feature.sh create user-auth
+```
+
+#### Step 2: Initialize Context
+
+```bash
+FEATURE_DIR=".trellis/agent-traces/{developer}/features/{feature-name}"
+./.trellis/scripts/feature.sh init-context "$FEATURE_DIR" <type>
+# type: backend | frontend | fullstack
+```
+
+#### Step 3: Add Task-Specific Guidelines
+
+Based on what the task involves, add relevant spec files:
+
+```bash
+# Example: adding database and API guidelines for a backend task
+./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" implement ".trellis/structure/backend/database-guidelines.md"
+./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" implement ".trellis/structure/backend/api-module.md"
+```
+
+Verify with:
+```bash
+./.trellis/scripts/feature.sh list-context "$FEATURE_DIR"
+```
+
+#### Step 4: Document Requirements
+
+Create `prd.md` in the feature directory describing what needs to be done.
+
+For complex tasks, also create `info.md` with technical approach.
+
+#### Step 5: Start Feature
+
+```bash
+./.trellis/scripts/feature.sh start "$FEATURE_DIR"
+```
+
+#### Step 6: Delegate Work
+
+Use specialized agents for implementation:
+
+```
+Task(subagent_type: "implement", prompt: "Implement the feature described in prd.md", model: "sonnet")
+```
+
+After implementation, verify quality:
+
+```
+Task(subagent_type: "check", prompt: "Check code changes and fix any issues", model: "sonnet")
+```
+
+#### Step 7: Complete
+
+1. Verify typecheck and lint pass
+2. Remind user to test
+3. Remind user to commit
+4. **Record session progress**: Ask user to run `/record-agent-flow`
+5. Archive feature (if fully completed):
+   ```bash
+   ./.trellis/scripts/feature.sh archive <feature-name>
+   ```
+
+---
+
+## Session End Reminder
+
+**IMPORTANT**: When a task or session is completed, always remind the user:
+
+> Before ending this session, please run `/record-agent-flow` to record what we accomplished.
+> This helps maintain continuity across sessions.
+
+---
+
+## Quick Reference
+
+| Task Size | Approach |
+|-----------|----------|
+| Small fix / simple change | Implement directly |
+| New feature / multi-file change | Use feature tracking + delegation |
+| Research / exploration | Use research agent |
+
+| Command | Purpose |
+|---------|---------|
+| `feature.sh create <name>` | Create feature directory |
+| `feature.sh start <dir>` | Set as current feature |
+| `feature.sh finish` | Clear current feature |
+| `feature.sh archive <name>` | Archive completed feature |
+| `feature.sh list` | List all features |
+| `/record-agent-flow` | **Record session progress (run at session end)** |

package/dist/templates/commands/common/before-backend-dev.txt

@@ -0,0 +1,13 @@
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/structure/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/structure/backend/database-guidelines.md`
+   - Error handling → `.trellis/structure/backend/error-handling.md`
+   - Logging → `.trellis/structure/backend/logging-guidelines.md`
+   - Type questions → `.trellis/structure/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.

package/dist/templates/commands/common/before-frontend-dev.txt

@@ -0,0 +1,13 @@
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/structure/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/structure/frontend/component-guidelines.md`
+   - Hook work → `.trellis/structure/frontend/hook-guidelines.md`
+   - State management → `.trellis/structure/frontend/state-management.md`
+   - Type questions → `.trellis/structure/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.

package/dist/templates/commands/common/break-loop.txt

@@ -0,0 +1,107 @@
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.trellis/structure/guides/` thinking guides
+- [ ] Update `.trellis/structure/backend/` or `frontend/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check commands if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.

package/dist/templates/commands/common/check-backend.txt

@@ -0,0 +1,13 @@
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/structure/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes → `.trellis/structure/backend/database-guidelines.md`
+   - Error handling → `.trellis/structure/backend/error-handling.md`
+   - Logging changes → `.trellis/structure/backend/logging-guidelines.md`
+   - Type changes → `.trellis/structure/backend/type-safety.md`
+   - Any changes → `.trellis/structure/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found

package/dist/templates/commands/common/check-cross-layer.txt

@@ -0,0 +1,153 @@
+# Cross-Layer Check
+
+Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
+
+> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/structure/guides/pre-implementation-checklist.md) **before** writing code.
+
+---
+
+## Related Documents
+
+| Document | Purpose | Timing |
+|----------|---------|--------|
+| [Pre-Implementation Checklist](.trellis/structure/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
+| [Code Reuse Thinking Guide](.trellis/structure/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
+| **`/check-cross-layer`** (this) | Verification check | **After** implementation |
+
+---
+
+## Execution Steps
+
+### 1. Identify Change Scope
+
+```bash
+git status
+git diff --name-only
+```
+
+### 2. Select Applicable Check Dimensions
+
+Based on your change type, execute relevant checks below:
+
+---
+
+## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
+
+**Trigger**: Changes involve 3 or more layers
+
+| Layer | Identifier |
+|-------|------------|
+| API Route | `routes/`, `api/` |
+| Service | `services/`, `lib/` |
+| Database | `db/`, `schema` |
+| Hook | `hooks/`, `use*.ts` |
+| Component | `components/`, `*.tsx` |
+| Utility | `utils/`, `lib/` |
+
+**Checklist**:
+- [ ] Read flow: Database -> Service -> API -> Hook -> Component
+- [ ] Write flow: Component -> Hook -> API -> Service -> Database
+- [ ] Types correctly passed between layers?
+- [ ] Errors properly propagated to UI?
+- [ ] Loading states handled at each layer?
+
+**Detailed Guide**: `.trellis/structure/guides/cross-layer-thinking-guide.md`
+
+---
+
+## Dimension B: Code Reuse (Required when modifying constants/config)
+
+**Trigger**: 
+- Modifying UI constants (label, icon, color)
+- Modifying any hardcoded value
+- Seeing similar code in multiple places
+- Creating a new utility/helper function
+- Just finished batch modifications across files
+
+**Checklist**:
+- [ ] Search first: How many places define this value?
+  ```bash
+  grep -r "value-to-change" --include="*.ts" --include="*.tsx"
+  ```
+- [ ] If 2+ places define same value -> Should extract to shared constant
+- [ ] After modification, all usage sites updated?
+- [ ] If creating utility: Does similar utility already exist?
+
+**Detailed Guide**: `.trellis/structure/guides/code-reuse-thinking-guide.md`
+
+---
+
+## Dimension B2: New Utility Functions
+
+**Trigger**: About to create a new utility/helper function
+
+**Checklist**:
+- [ ] Search for existing similar utilities first
+  ```bash
+  grep -r "functionNamePattern" --include="*.ts"
+  ```
+- [ ] If similar exists, can you extend it instead?
+- [ ] If creating new, is it in the right location (shared vs domain-specific)?
+
+---
+
+## Dimension B3: After Batch Modifications
+
+**Trigger**: Just modified similar patterns in multiple files
+
+**Checklist**:
+- [ ] Did you check ALL files with similar patterns?
+  ```bash
+  grep -r "patternYouChanged" --include="*.ts" --include="*.tsx"
+  ```
+- [ ] Any files missed that should also be updated?
+- [ ] Should this pattern be abstracted to prevent future duplication?
+
+---
+
+## Dimension C: Import Paths (Required when creating new files)
+
+**Trigger**: Creating new .ts/.tsx files
+
+**Checklist**:
+- [ ] Using correct path aliases?
+- [ ] No circular imports?
+- [ ] Relative vs absolute paths consistent with project convention?
+
+---
+
+## Dimension D: Same-Layer Consistency
+
+**Trigger**: 
+- Modifying display logic in a component
+- Same domain concept used in multiple components
+
+**Checklist**:
+- [ ] Search for other components using same concept
+  ```bash
+  grep -r "ConceptName" --include="*.tsx"
+  ```
+- [ ] Are these components' displays consistent?
+- [ ] Should they share configuration?
+
+---
+
+## Common Issues Quick Reference
+
+| Issue | Root Cause | Prevention |
+|-------|------------|------------|
+| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
+| Data lost at some layer | Didn't check data flow | Trace data source to destination |
+| Type mismatch | Cross-layer types inconsistent | Use shared types |
+| UI inconsistent | Same concept in multiple places | Extract shared constants |
+| Similar utility exists | Didn't search first | Search before creating |
+| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
+
+---
+
+## Output
+
+Report:
+1. Which dimensions your changes involve
+2. Check results for each dimension
+3. Issues found and fix suggestions

package/dist/templates/commands/common/check-frontend.txt

@@ -0,0 +1,13 @@
+Check if the code you just wrote follows the frontend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/structure/frontend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Component changes → `.trellis/structure/frontend/component-guidelines.md`
+   - Hook changes → `.trellis/structure/frontend/hook-guidelines.md`
+   - State changes → `.trellis/structure/frontend/state-management.md`
+   - Type changes → `.trellis/structure/frontend/type-safety.md`
+   - Any changes → `.trellis/structure/frontend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found