@jahanxu/trellis 0.4.1

package/dist/templates/markdown/spec/guides/index.md.txt

@@ -0,0 +1,79 @@
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+---
+
+## Pre-Modification Rule (CRITICAL)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.

package/dist/templates/markdown/workspace-index.md

@@ -0,0 +1,123 @@
+# Workspace Index
+
+> Records of all AI Agent work records across all developers
+
+---
+
+## Overview
+
+This directory tracks records for all developers working with AI Agents on this project.
+
+### File Structure
+
+```
+workspace/
+|-- index.md              # This file - main index
++-- {developer}/          # Per-developer directory
+    |-- index.md          # Personal index with session history
+    |-- tasks/         # Task files
+    |   |-- *.json        # Active tasks
+    |   +-- archive/      # Archived tasks by month
+    +-- journal-N.md     # Journal files (sequential: 1, 2, 3...)
+```
+
+---
+
+## Active Developers
+
+| Developer | Last Active | Sessions | Active File |
+|-----------|-------------|----------|-------------|
+| (none yet) | - | - | - |
+
+---
+
+## Getting Started
+
+### For New Developers
+
+Run the initialization script:
+
+```bash
+python3 ./.trellis/scripts/init_developer.py <your-name>
+```
+
+This will:
+1. Create your identity file (gitignored)
+2. Create your progress directory
+3. Create your personal index
+4. Create initial journal file
+
+### For Returning Developers
+
+1. Get your developer name:
+   ```bash
+   python3 ./.trellis/scripts/get_developer.py
+   ```
+
+2. Read your personal index:
+   ```bash
+   cat .trellis/workspace/$(python3 ./.trellis/scripts/get_developer.py)/index.md
+   ```
+
+---
+
+## Guidelines
+
+### Journal File Rules
+
+- **Max 2000 lines** per journal file
+- When limit is reached, create `journal-{N+1}.md`
+- Update your personal `index.md` when creating new files
+
+### Session Record Format
+
+Each session should include:
+- Summary: One-line description
+- Main Changes: What was modified
+- Git Commits: Commit hashes and messages
+- Next Steps: What to do next
+
+---
+
+## Session Template
+
+Use this template when recording sessions:
+
+```markdown
+## Session {N}: {Title}
+
+**Date**: YYYY-MM-DD
+**Task**: {task-name}
+
+### Summary
+
+{One-line summary}
+
+### Main Changes
+
+- {Change 1}
+- {Change 2}
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `abc1234` | {commit message} |
+
+### Testing
+
+- [OK] {Test result}
+
+### Status
+
+[OK] **Completed** / # **In Progress** / [P] **Blocked**
+
+### Next Steps
+
+- {Next step 1}
+- {Next step 2}
+```
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/worktree.yaml.txt

@@ -0,0 +1,58 @@
+# Worktree Configuration for Multi-Agent Pipeline
+# Used for worktree initialization in multi-agent workflows
+#
+# All paths are relative to project root
+
+#-------------------------------------------------------------------------------
+# Paths
+#-------------------------------------------------------------------------------
+
+# Worktree storage directory (relative to project root)
+# Recommended: keep worktrees outside the main repo to avoid conflicts
+worktree_dir: ../<project-name>-worktrees
+
+#-------------------------------------------------------------------------------
+# Files to Copy
+#-------------------------------------------------------------------------------
+
+# Files to copy to each worktree (each worktree needs independent copy)
+# These files contain sensitive info or need worktree-independent config
+copy:
+  # Environment variables (uncomment and customize as needed)
+  # - .env
+  # - .env.local
+  # Workflow config
+  - .trellis/.developer
+
+#-------------------------------------------------------------------------------
+# Post-Create Hooks
+#-------------------------------------------------------------------------------
+
+# Commands to run after creating worktree
+# Executed in worktree directory, in order, abort on failure
+post_create:
+  # Install dependencies (uncomment based on your package manager)
+  # - npm install
+  # - pnpm install --frozen-lockfile
+  # - yarn install --frozen-lockfile
+  # - pip install -r requirements.txt
+  # - bundle install
+  # - cargo build
+
+#-------------------------------------------------------------------------------
+# Pre-Merge Checks
+#-------------------------------------------------------------------------------
+
+# Pre-merge validation (used by create_pr.py)
+pre_merge:
+  # Type checking (uncomment based on your setup)
+  # - npm run typecheck
+  # - pnpm typecheck
+  # - mypy .
+  # Linting
+  # - npm run lint
+  # - pnpm lint
+  # - ruff check .
+  # Testing
+  # - npm test
+  # - pytest

package/dist/templates/opencode/agents/check.md

@@ -0,0 +1,146 @@
+---
+description: |
+  Code quality check expert. Reviews code changes against specs and self-fixes issues.
+mode: subagent
+permission:
+  read: allow
+  write: allow
+  edit: allow
+  bash: allow
+  glob: allow
+  grep: allow
+  mcp__exa__*: allow
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Context Self-Loading
+
+**If you see "# Check Agent Task" header with pre-loaded context above, skip this section.**
+
+Otherwise, load context yourself:
+
+1. Read `.trellis/.current-task` → get task directory (e.g., `.trellis/tasks/xxx`)
+2. Read `{task_dir}/check.jsonl` (or `spec.jsonl` as fallback)
+3. For each entry in JSONL:
+   - If `path` is a file → Read it
+   - If `path` is a directory → Read all `.md` files in it
+4. Read `{task_dir}/prd.md` for requirements understanding
+5. Read `.opencode/commands/trellis/finish-work.md` for checklist
+
+Then proceed with the workflow below using the loaded context.
+
+---
+
+## 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.
+
+---
+
+## Completion Markers (Ralph Loop)
+
+**CRITICAL**: You are in a loop controlled by the Ralph Loop system.
+The loop will NOT stop until you output ALL required completion markers.
+
+Completion markers are generated from `check.jsonl` in the task directory.
+Each entry's `reason` field becomes a marker: `{REASON}_FINISH`
+
+For example, if check.jsonl contains:
+```json
+{"file": "...", "reason": "TypeCheck"}
+{"file": "...", "reason": "Lint"}
+{"file": "...", "reason": "CodeReview"}
+```
+
+You MUST output these markers when each check passes:
+- `TYPECHECK_FINISH` - After typecheck passes
+- `LINT_FINISH` - After lint passes
+- `CODEREVIEW_FINISH` - After code review passes
+
+If check.jsonl doesn't exist or has no reasons, output: `ALL_CHECKS_FINISH`
+
+**The loop will block you from stopping until all markers are present in your output.**
+
+---
+
+## 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 TYPECHECK_FINISH
+- Lint: Passed LINT_FINISH
+
+### Summary
+
+Checked X files, found Y issues, all fixed.
+ALL_CHECKS_FINISH
+```

package/dist/templates/opencode/agents/debug.md

@@ -0,0 +1,129 @@
+---
+description: |
+  Issue fixing expert. Understands issues, fixes against specs, and verifies fixes. Precise fixes only.
+mode: subagent
+permission:
+  read: allow
+  write: allow
+  edit: allow
+  bash: allow
+  glob: allow
+  grep: allow
+  mcp__exa__*: allow
+---
+# Debug Agent
+
+You are the Debug Agent in the Trellis workflow.
+
+## Context Self-Loading
+
+**If you see "# Debug Agent Task" header with pre-loaded context above, skip this section.**
+
+Otherwise, load context yourself:
+
+1. Read `.trellis/.current-task` → get task directory (e.g., `.trellis/tasks/xxx`)
+2. Read `{task_dir}/debug.jsonl` (or `spec.jsonl` as fallback)
+3. For each entry in JSONL:
+   - If `path` is a file → Read it
+   - If `path` is a directory → Read all `.md` files in it
+4. Read `{task_dir}/codex-review-output.txt` if exists (Codex review results)
+
+Then proceed with the workflow below using the loaded context.
+
+---
+
+## Context
+
+Before debugging, read:
+- `.trellis/spec/` - Development guidelines
+- Error messages or issue descriptions provided
+
+## Core Responsibilities
+
+1. **Understand issues** - Analyze error messages or reported issues
+2. **Fix against specs** - Fix issues following dev specs
+3. **Verify fixes** - Run typecheck to ensure no new issues
+4. **Report results** - Report fix status
+
+---
+
+## Workflow
+
+### Step 1: Understand Issues
+
+Parse the issue, categorize by priority:
+
+- `[P1]` - Must fix (blocking)
+- `[P2]` - Should fix (important)
+- `[P3]` - Optional fix (nice to have)
+
+### Step 2: Research if Needed
+
+If you need additional info:
+
+```bash
+# Check knowledge base
+ls .trellis/big-question/
+```
+
+### Step 3: Fix One by One
+
+For each issue:
+
+1. Locate the exact position
+2. Fix following specs
+3. Run typecheck to verify
+
+### Step 4: Verify
+
+Run project's lint and typecheck commands to verify fixes.
+
+If fix introduces new issues:
+
+1. Revert the fix
+2. Use a more complete solution
+3. Re-verify
+
+---
+
+## Report Format
+
+```markdown
+## Fix Report
+
+### Issues Fixed
+
+1. `[P1]` `<file>:<line>` - <what was fixed>
+2. `[P2]` `<file>:<line>` - <what was fixed>
+
+### Issues Not Fixed
+
+- `<file>:<line>` - <reason why not fixed>
+
+### Verification
+
+- TypeCheck: Pass
+- Lint: Pass
+
+### Summary
+
+Fixed X/Y issues. Z issues require discussion.
+```
+
+---
+
+## Guidelines
+
+### DO
+
+- Precise fixes for reported issues
+- Follow specs
+- Verify each fix
+
+### DON'T
+
+- Don't refactor surrounding code
+- Don't add new features
+- Don't modify unrelated files
+- Don't use non-null assertion (`x!` operator)
+- Don't execute git commit