@jahanxu/trellis 0.4.1

package/dist/templates/trellis/spec/roles/pm/prd-template.md

@@ -0,0 +1,124 @@
+# PRD Template - 产品需求文档模板
+
+> 复制此模板到任务目录，填写各章节内容
+
+---
+
+# [功能名称] PRD
+
+## 1. 功能概述
+
+**一句话概述**：[用一句话说明这个功能是什么]
+
+**背景**：[为什么要做这个功能，解决什么问题]
+
+**目标用户**：[谁会使用这个功能]
+
+---
+
+## 2. 用户故事
+
+### 主要用户故事
+
+**US-1**: 作为 [角色]，我想要 [功能]，以便 [价值/目标]
+
+**验收标准**：
+- [ ] [可测试的标准1]
+- [ ] [可测试的标准2]
+
+**US-2**: [重复上述格式]
+
+### 边缘场景
+
+**US-Edge-1**: [边缘场景描述]
+
+---
+
+## 3. 功能需求
+
+### 3.1 核心功能
+
+**F1**: [功能点1]
+- 描述：[详细描述]
+- 优先级：P0/P1/P2
+- 交互要点：[关键交互说明]
+
+**F2**: [功能点2]
+
+### 3.2 辅助功能
+
+[次要功能列表]
+
+---
+
+## 4. 验收标准
+
+### 功能性验收
+
+- [ ] [核心功能可用]
+- [ ] [边缘场景正常]
+- [ ] [错误处理完善]
+
+### 用户体验验收
+
+- [ ] [加载时间 < X秒]
+- [ ] [交互流畅]
+- [ ] [错误提示友好]
+
+---
+
+## 5. 非功能需求
+
+### 性能要求
+- 响应时间：[X秒内]
+- 并发支持：[X用户]
+
+### 兼容性要求
+- 浏览器：[Chrome 90+, Safari 14+, ...]
+- 设备：[桌面端, 移动端, ...]
+
+### 安全要求
+- [数据加密要求]
+- [权限控制要求]
+
+---
+
+## 6. 数据埋点（可选）
+
+### 事件埋点
+
+| 事件名 | 触发时机 | 参数 |
+|--------|---------|------|
+| [event_name] | [触发条件] | [参数列表] |
+
+---
+
+## 7. 上线计划
+
+### 里程碑
+
+- [ ] PRD完成 - [日期]
+- [ ] 原型完成 - [日期]
+- [ ] 开发完成 - [日期]
+- [ ] 测试完成 - [日期]
+- [ ] 上线 - [日期]
+
+### 回滚计划
+
+[如果上线失败，如何回滚]
+
+---
+
+## 8. 附录
+
+### 竞品参考
+- [竞品A]: [链接]
+- [竞品B]: [链接]
+
+### 设计资源
+- Figma: [链接]
+- 图片素材: [路径]
+
+### 技术资源
+- API文档: [链接]
+- 技术方案: [链接]

package/dist/templates/trellis/workflow.md

@@ -0,0 +1,416 @@
+# Development Workflow
+
+> Based on [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+
+---
+
+## Table of Contents
+
+1. [Quick Start (Do This First)](#quick-start-do-this-first)
+2. [Workflow Overview](#workflow-overview)
+3. [Session Start Process](#session-start-process)
+4. [Development Process](#development-process)
+5. [Session End](#session-end)
+6. [File Descriptions](#file-descriptions)
+7. [Best Practices](#best-practices)
+
+---
+
+## Quick Start (Do This First)
+
+### Step 0: Initialize Developer Identity (First Time Only)
+
+> **Multi-developer support**: Each developer/Agent needs to initialize their identity first
+
+```bash
+# Check if already initialized
+python3 ./.trellis/scripts/get_developer.py
+
+# If not initialized, run:
+python3 ./.trellis/scripts/init_developer.py <your-name>
+# Example: python3 ./.trellis/scripts/init_developer.py cursor-agent
+```
+
+This creates:
+- `.trellis/.developer` - Your identity file (gitignored, not committed)
+- `.trellis/workspace/<your-name>/` - Your personal workspace directory
+
+**Naming suggestions**:
+- Human developers: Use your name, e.g., `john-doe`
+- Cursor AI: `cursor-agent` or `cursor-<task>`
+- Claude Code: `claude-agent` or `claude-<task>`
+- iFlow cli: `iflow-agent` or `iflow-<task>`
+
+### Step 1: Understand Current Context
+
+```bash
+# Get full context in one command
+python3 ./.trellis/scripts/get_context.py
+
+# Or check manually:
+python3 ./.trellis/scripts/get_developer.py      # Your identity
+python3 ./.trellis/scripts/task.py list          # Active tasks
+git status && git log --oneline -10              # Git state
+```
+
+### Step 2: Read Project Guidelines [MANDATORY]
+
+**CRITICAL**: Read guidelines before writing any code:
+
+```bash
+# Read frontend guidelines index (if applicable)
+cat .trellis/spec/frontend/index.md
+
+# Read backend guidelines index (if applicable)
+cat .trellis/spec/backend/index.md
+```
+
+**Why read both?**
+- Understand the full project architecture
+- Know coding standards for the entire codebase
+- See how frontend and backend interact
+- Learn the overall code quality requirements
+
+### Step 3: Before Coding - Read Specific Guidelines (Required)
+
+Based on your task, read the **detailed** guidelines:
+
+**Frontend Task**:
+```bash
+cat .trellis/spec/frontend/hook-guidelines.md      # For hooks
+cat .trellis/spec/frontend/component-guidelines.md # For components
+cat .trellis/spec/frontend/type-safety.md          # For types
+```
+
+**Backend Task**:
+```bash
+cat .trellis/spec/backend/database-guidelines.md   # For DB operations
+cat .trellis/spec/backend/type-safety.md           # For types
+cat .trellis/spec/backend/logging-guidelines.md    # For logging
+```
+
+---
+
+## Workflow Overview
+
+### Core Principles
+
+1. **Read Before Write** - Understand context before starting
+2. **Follow Standards** - [!] **MUST read `.trellis/spec/` guidelines before coding**
+3. **Incremental Development** - Complete one task at a time
+4. **Record Promptly** - Update tracking files immediately after completion
+5. **Document Limits** - [!] **Max 2000 lines per journal document**
+
+### File System
+
+```
+.trellis/
+|-- .developer           # Developer identity (gitignored)
+|-- scripts/
+|   |-- __init__.py          # Python package init
+|   |-- common/              # Shared utilities (Python)
+|   |   |-- __init__.py
+|   |   |-- paths.py         # Path utilities
+|   |   |-- developer.py     # Developer management
+|   |   +-- git_context.py   # Git context implementation
+|   |-- multi_agent/         # Multi-agent pipeline scripts
+|   |   |-- __init__.py
+|   |   |-- start.py         # Start worktree agent
+|   |   |-- status.py        # Monitor agent status
+|   |   |-- create_pr.py     # Create PR
+|   |   +-- cleanup.py       # Cleanup worktree
+|   |-- init_developer.py    # Initialize developer identity
+|   |-- get_developer.py     # Get current developer name
+|   |-- task.py              # Manage tasks
+|   |-- get_context.py       # Get session context
+|   +-- add_session.py       # One-click session recording
+|-- workspace/           # Developer workspaces
+|   |-- index.md         # Workspace index + Session template
+|   +-- {developer}/     # Per-developer directories
+|       |-- index.md     # Personal index (with @@@auto markers)
+|       +-- journal-N.md # Journal files (sequential numbering)
+|-- tasks/               # Task tracking
+|   +-- {MM}-{DD}-{name}/
+|       +-- task.json
+|-- spec/                # [!] MUST READ before coding
+|   |-- frontend/        # Frontend guidelines (if applicable)
+|   |   |-- index.md               # Start here - guidelines index
+|   |   +-- *.md                   # Topic-specific docs
+|   |-- backend/         # Backend guidelines (if applicable)
+|   |   |-- index.md               # Start here - guidelines index
+|   |   +-- *.md                   # Topic-specific docs
+|   +-- guides/          # Thinking guides
+|       |-- index.md                      # Guides index
+|       |-- cross-layer-thinking-guide.md # Pre-implementation checklist
+|       +-- *.md                          # Other guides
++-- workflow.md             # This document
+```
+
+---
+
+## Session Start Process
+
+### Step 1: Get Session Context
+
+Use the unified context script:
+
+```bash
+# Get all context in one command
+python3 ./.trellis/scripts/get_context.py
+
+# Or get JSON format
+python3 ./.trellis/scripts/get_context.py --json
+```
+
+### Step 2: Read Development Guidelines [!] REQUIRED
+
+**[!] CRITICAL: MUST read guidelines before writing any code**
+
+Based on what you'll develop, read the corresponding guidelines:
+
+**Frontend Development** (if applicable):
+```bash
+# Read index first, then specific docs based on task
+cat .trellis/spec/frontend/index.md
+```
+
+**Backend Development** (if applicable):
+```bash
+# Read index first, then specific docs based on task
+cat .trellis/spec/backend/index.md
+```
+
+**Cross-Layer Features**:
+```bash
+# For features spanning multiple layers
+cat .trellis/spec/guides/cross-layer-thinking-guide.md
+```
+
+### Step 3: Select Task to Develop
+
+Use the task management script:
+
+```bash
+# List active tasks
+python3 ./.trellis/scripts/task.py list
+
+# Create new task (creates directory with task.json)
+python3 ./.trellis/scripts/task.py create "<title>" --slug <task-name>
+```
+
+---
+
+## Development Process
+
+### Task Development Flow
+
+```
+1. Create or select task
+   --> python3 ./.trellis/scripts/task.py create "<title>" --slug <name> or list
+
+2. Write code according to guidelines
+   --> Read .trellis/spec/ docs relevant to your task
+   --> For cross-layer: read .trellis/spec/guides/
+
+3. Self-test
+   --> Run project's lint/test commands (see spec docs)
+   --> Manual feature testing
+
+4. Commit code
+   --> git add <files>
+   --> git commit -m "type(scope): description"
+       Format: feat/fix/docs/refactor/test/chore
+
+5. Record session (one command)
+   --> python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+```
+
+### Code Quality Checklist
+
+**Must pass before commit**:
+- [OK] Lint checks pass (project-specific command)
+- [OK] Type checks pass (if applicable)
+- [OK] Manual feature testing passes
+
+**Project-specific checks**:
+- See `.trellis/spec/frontend/quality-guidelines.md` for frontend
+- See `.trellis/spec/backend/quality-guidelines.md` for backend
+
+---
+
+## Session End
+
+### One-Click Session Recording
+
+After code is committed, use:
+
+```bash
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "abc1234" \
+  --summary "Brief summary"
+```
+
+This automatically:
+1. Detects current journal file
+2. Creates new file if 2000-line limit exceeded
+3. Appends session content
+4. Updates index.md (sessions count, history table)
+
+### Pre-end Checklist
+
+Use `/trellis:finish-work` command to run through:
+1. [OK] All code committed, commit message follows convention
+2. [OK] Session recorded via `add_session.py`
+3. [OK] No lint/test errors
+4. [OK] Working directory clean (or WIP noted)
+5. [OK] Spec docs updated if needed
+
+---
+
+## File Descriptions
+
+### 1. workspace/ - Developer Workspaces
+
+**Purpose**: Record each AI Agent session's work content
+
+**Structure** (Multi-developer support):
+```
+workspace/
+|-- index.md              # Main index (Active Developers table)
++-- {developer}/          # Per-developer directory
+    |-- index.md          # Personal index (with @@@auto markers)
+    +-- journal-N.md      # Journal files (sequential: 1, 2, 3...)
+```
+
+**When to update**:
+- [OK] End of each session
+- [OK] Complete important task
+- [OK] Fix important bug
+
+### 2. spec/ - Development Guidelines
+
+**Purpose**: Documented standards for consistent development
+
+**Structure** (Multi-doc format):
+```
+spec/
+|-- frontend/           # Frontend docs (if applicable)
+|   |-- index.md        # Start here
+|   +-- *.md            # Topic-specific docs
+|-- backend/            # Backend docs (if applicable)
+|   |-- index.md        # Start here
+|   +-- *.md            # Topic-specific docs
++-- guides/             # Thinking guides
+    |-- index.md        # Start here
+    +-- *.md            # Guide-specific docs
+```
+
+**When to update**:
+- [OK] New pattern discovered
+- [OK] Bug fixed that reveals missing guidance
+- [OK] New convention established
+
+### 3. Tasks - Task Tracking
+
+Each task is a directory containing `task.json`:
+
+```
+tasks/
+|-- 01-21-my-task/
+|   +-- task.json
++-- archive/
+    +-- 2026-01/
+        +-- 01-15-old-task/
+            +-- task.json
+```
+
+**Commands**:
+```bash
+python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]   # Create task directory
+python3 ./.trellis/scripts/task.py archive <name>  # Archive to archive/{year-month}/
+python3 ./.trellis/scripts/task.py list            # List active tasks
+python3 ./.trellis/scripts/task.py list-archive    # List archived tasks
+```
+
+---
+
+## Best Practices
+
+### [OK] DO - Should Do
+
+1. **Before session start**:
+   - Run `python3 ./.trellis/scripts/get_context.py` for full context
+   - [!] **MUST read** relevant `.trellis/spec/` docs
+
+2. **During development**:
+   - [!] **Follow** `.trellis/spec/` guidelines
+   - For cross-layer features, use `/trellis:check-cross-layer`
+   - Develop only one task at a time
+   - Run lint and tests frequently
+
+3. **After development complete**:
+   - Use `/trellis:finish-work` for completion checklist
+   - After fix bug, use `/trellis:break-loop` for deep analysis
+   - Human commits after testing passes
+   - Use `add_session.py` to record progress
+
+### [X] DON'T - Should Not Do
+
+1. [!] **Don't** skip reading `.trellis/spec/` guidelines
+2. [!] **Don't** let journal single file exceed 2000 lines
+3. **Don't** develop multiple unrelated tasks simultaneously
+4. **Don't** commit code with lint/test errors
+5. **Don't** forget to update spec docs after learning something
+6. [!] **Don't** execute `git commit` - AI should not commit code
+
+---
+
+## Quick Reference
+
+### Must-read Before Development
+
+| Task Type | Must-read Document |
+|-----------|-------------------|
+| Frontend work | `frontend/index.md` → relevant docs |
+| Backend work | `backend/index.md` → relevant docs |
+| Cross-Layer Feature | `guides/cross-layer-thinking-guide.md` |
+
+### Commit Convention
+
+```bash
+git commit -m "type(scope): description"
+```
+
+**Type**: feat, fix, docs, refactor, test, chore
+**Scope**: Module name (e.g., auth, api, ui)
+
+### Common Commands
+
+```bash
+# Session management
+python3 ./.trellis/scripts/get_context.py    # Get full context
+python3 ./.trellis/scripts/add_session.py    # Record session
+
+# Task management
+python3 ./.trellis/scripts/task.py list      # List tasks
+python3 ./.trellis/scripts/task.py create "<title>" # Create task
+
+# Slash commands
+/trellis:finish-work          # Pre-commit checklist
+/trellis:break-loop           # Post-debug analysis
+/trellis:check-cross-layer    # Cross-layer verification
+```
+
+---
+
+## Summary
+
+Following this workflow ensures:
+- [OK] Continuity across multiple sessions
+- [OK] Consistent code quality
+- [OK] Trackable progress
+- [OK] Knowledge accumulation in spec docs
+- [OK] Transparent team collaboration
+
+**Core Philosophy**: Read before write, follow standards, record promptly, capture learnings

package/dist/templates/trellis/worktree.yaml

@@ -0,0 +1,47 @@
+# 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)
+worktree_dir: ../trellis-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
+
+#-------------------------------------------------------------------------------
+# Check Agent Verification (Ralph Loop)
+#-------------------------------------------------------------------------------
+
+# Commands to verify code quality before allowing check agent to finish
+# If configured, Ralph Loop will run these commands - all must pass to allow completion
+# If not configured or empty, trusts agent's completion markers
+verify:
+  # - pnpm lint
+  # - pnpm typecheck

package/dist/types/ai-tools.d.ts

@@ -0,0 +1,56 @@
+/**
+ * AI Tool Types and Registry
+ *
+ * Defines supported AI coding tools and which command templates they can use.
+ */
+/**
+ * Supported AI coding tools
+ */
+export type AITool = "claude-code" | "cursor" | "opencode" | "iflow" | "codex" | "kilo" | "kiro" | "gemini" | "antigravity";
+/**
+ * Template directory categories
+ */
+export type TemplateDir = "common" | "claude" | "cursor" | "opencode" | "iflow" | "codex" | "kilo" | "kiro" | "gemini" | "antigravity";
+/**
+ * CLI flag names for platform selection (e.g., --claude, --cursor, --kilo, --kiro, --gemini, --antigravity)
+ * Must match keys in InitOptions (src/commands/init.ts)
+ */
+export type CliFlag = "claude" | "cursor" | "opencode" | "iflow" | "codex" | "kilo" | "kiro" | "gemini" | "antigravity";
+/**
+ * Configuration for an AI tool
+ */
+export interface AIToolConfig {
+    /** Display name of the tool */
+    name: string;
+    /** Command template directory names to include */
+    templateDirs: TemplateDir[];
+    /** Config directory name in the project root (e.g., ".claude") */
+    configDir: string;
+    /** CLI flag name for --flag options (e.g., "claude" for --claude) */
+    cliFlag: CliFlag;
+    /** Whether this tool is checked by default in interactive init prompt */
+    defaultChecked: boolean;
+    /** Whether this tool uses Python hooks (affects Windows encoding detection) */
+    hasPythonHooks: boolean;
+}
+/**
+ * Registry of all supported AI tools and their configurations.
+ * This is the single source of truth for platform data.
+ *
+ * When adding a new platform, add an entry here and create:
+ * 1. src/configurators/{platform}.ts — configure function
+ * 2. src/templates/{platform}/ — template files
+ * 3. Register in src/configurators/index.ts — PLATFORM_FUNCTIONS
+ * 4. Add CLI flag in src/cli/index.ts
+ * 5. Add to InitOptions in src/commands/init.ts
+ */
+export declare const AI_TOOLS: Record<AITool, AIToolConfig>;
+/**
+ * Get the configuration for a specific AI tool
+ */
+export declare function getToolConfig(tool: AITool): AIToolConfig;
+/**
+ * Get template directories for a specific tool
+ */
+export declare function getTemplateDirs(tool: AITool): TemplateDir[];
+//# sourceMappingURL=ai-tools.d.ts.map

package/dist/types/ai-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-tools.d.ts","sourceRoot":"","sources":["../../src/types/ai-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GACd,aAAa,GACb,QAAQ,GACR,UAAU,GACV,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,CAAC;AAElB;;;GAGG;AACH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;IACxB,+EAA+E;IAC/E,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAyEjD,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAExD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAE3D"}