@mindfoldhq/trellis 0.3.4 → 0.3.6

package/dist/templates/markdown/spec/backend/directory-structure.md

@@ -0,0 +1,292 @@
+# Directory Structure
+
+> How backend/CLI code is organized in this project.
+
+---
+
+## Overview
+
+This project is a **TypeScript CLI tool** using ES modules. The source code follows a **dogfooding architecture** - Trellis uses its own configuration files (`.cursor/`, `.claude/`, `.trellis/`) as templates for new projects.
+
+---
+
+## Directory Layout
+
+```
+src/
+├── cli/                 # CLI entry point and argument parsing
+│   └── index.ts         # Main CLI entry (Commander.js setup)
+├── commands/            # Command implementations
+│   └── init.ts          # Each command in its own file
+├── configurators/       # Configuration generators
+│   ├── index.ts         # Platform registry (PLATFORM_FUNCTIONS, derived helpers)
+│   ├── shared.ts        # Shared utilities (resolvePlaceholders)
+│   ├── claude.ts        # Claude Code configurator
+│   ├── cursor.ts        # Cursor configurator
+│   ├── iflow.ts         # iFlow CLI configurator
+│   ├── opencode.ts      # OpenCode configurator
+│   └── workflow.ts      # Creates .trellis/ structure
+├── constants/           # Shared constants and paths
+│   └── paths.ts         # Path constants (centralized)
+├── templates/           # Template utilities and generic templates
+│   ├── markdown/        # Generic markdown templates
+│   │   ├── spec/        # Spec templates (*.md.txt)
+│   │   ├── init-agent.md    # Project root file template
+│   │   ├── agents.md        # Project root file template
+│   │   ├── worktree.yaml.txt # Generic worktree config
+│   │   └── index.ts     # Template exports
+│   └── extract.ts       # Template extraction utilities
+├── types/               # TypeScript type definitions
+│   └── ai-tools.ts      # AI tool types and registry
+├── utils/               # Shared utility functions
+│   ├── compare-versions.ts # Semver comparison with prerelease support
+│   ├── file-writer.ts   # File writing with conflict handling
+│   ├── project-detector.ts # Project type detection
+│   ├── template-fetcher.ts # Remote template download from GitHub
+│   └── template-hash.ts # Template hash tracking for update detection
+└── index.ts             # Package entry point (exports public API)
+```
+
+### Dogfooding Directories (Project Root)
+
+These directories are copied to `dist/` during build and used as templates:
+
+```
+.cursor/                 # Cursor configuration (dogfooded)
+├── commands/            # Slash commands for Cursor
+│   ├── start.md
+│   ├── finish-work.md
+│   └── ...
+
+.claude/                 # Claude Code configuration (dogfooded)
+├── commands/            # Slash commands
+├── agents/              # Multi-agent pipeline agents
+├── hooks/               # Context injection hooks
+└── settings.json        # Hook configuration
+
+.trellis/                # Trellis workflow (partially dogfooded)
+├── scripts/             # Python scripts (dogfooded)
+│   ├── common/          # Shared utilities (paths.py, developer.py, etc.)
+│   ├── multi_agent/     # Pipeline scripts (start.py, status.py, etc.)
+│   ├── hooks/           # Lifecycle hook scripts (project-specific, NOT dogfooded)
+│   └── *.py             # Main scripts (task.py, get_context.py, etc.)
+├── workspace/           # Developer progress tracking
+│   └── index.md         # Index template (dogfooded)
+├── spec/                # Project guidelines (NOT dogfooded)
+│   ├── backend/         # Backend development docs
+│   ├── frontend/        # Frontend development docs
+│   └── guides/          # Thinking guides
+├── workflow.md          # Workflow documentation (dogfooded)
+├── worktree.yaml        # Worktree config (Trellis-specific)
+└── .gitignore           # Git ignore rules (dogfooded)
+```
+
+---
+
+## Dogfooding Architecture
+
+### What is Dogfooded
+
+Files that are copied directly from Trellis project to user projects:
+
+| Source | Destination | Description |
+|--------|-------------|-------------|
+| `.cursor/` | `.cursor/` | Entire directory copied |
+| `.claude/` | `.claude/` | Entire directory copied |
+| `.trellis/scripts/` | `.trellis/scripts/` | All scripts copied |
+| `.trellis/workflow.md` | `.trellis/workflow.md` | Direct copy |
+| `.trellis/.gitignore` | `.trellis/.gitignore` | Direct copy |
+| `.trellis/workspace/index.md` | `.trellis/workspace/index.md` | Direct copy |
+
+### What is NOT Dogfooded
+
+Files that use generic templates (in `src/templates/`):
+
+| Template Source | Destination | Reason |
+|----------------|-------------|--------|
+| `src/templates/markdown/spec/**/*.md.txt` | `.trellis/spec/**/*.md` | User fills with project-specific content |
+| `src/templates/markdown/worktree.yaml.txt` | `.trellis/worktree.yaml` | Language-agnostic template |
+| `src/templates/markdown/init-agent.md` | `init-agent.md` | Project root file |
+| `src/templates/markdown/agents.md` | `AGENTS.md` | Project root file |
+
+### Build Process
+
+```bash
+# scripts/copy-templates.js copies dogfooding sources to dist/
+pnpm build
+
+# Result:
+dist/
+├── .cursor/           # From project root .cursor/
+├── .claude/           # From project root .claude/
+├── .trellis/          # From project root .trellis/ (filtered)
+│   ├── scripts/       # All scripts
+│   ├── workspace/
+│   │   └── index.md   # Only index.md, no developer subdirs
+│   ├── workflow.md
+│   ├── worktree.yaml
+│   └── .gitignore
+└── templates/         # From src/templates/ (no .ts files)
+    └── markdown/
+        └── spec/      # Generic templates
+```
+
+---
+
+## Module Organization
+
+### Layer Responsibilities
+
+| Layer | Directory | Responsibility |
+|-------|-----------|----------------|
+| CLI | `cli/` | Parse arguments, display help, call commands |
+| Commands | `commands/` | Implement CLI commands, orchestrate actions |
+| Configurators | `configurators/` | Copy/generate configuration for tools |
+| Templates | `templates/` | Extract template content, provide utilities |
+| Types | `types/` | TypeScript type definitions |
+| Utils | `utils/` | Reusable utility functions |
+| Constants | `constants/` | Shared constants (paths, names) |
+
+### Configurator Pattern
+
+Configurators use `cpSync` for direct directory copy (dogfooding):
+
+```typescript
+// configurators/cursor.ts
+export async function configureCursor(cwd: string): Promise<void> {
+  const sourcePath = getCursorSourcePath(); // dist/.cursor/ or .cursor/
+  const destPath = path.join(cwd, ".cursor");
+  cpSync(sourcePath, destPath, { recursive: true });
+}
+```
+
+### Template Extraction
+
+`extract.ts` provides utilities for reading dogfooded files:
+
+```typescript
+// Get path to .trellis/ (works in dev and production)
+getTrellisSourcePath(): string
+
+// Read file from .trellis/
+readTrellisFile(relativePath: string): string
+
+// Copy directory from .trellis/ with executable scripts
+copyTrellisDir(srcRelativePath: string, destPath: string, options?: { executable?: boolean }): void
+```
+
+---
+
+## Naming Conventions
+
+### Files and Directories
+
+| Convention | Example | Usage |
+|------------|---------|-------|
+| `kebab-case` | `file-writer.ts` | All TypeScript files |
+| `kebab-case` | `multi-agent/` | All directories |
+| `*.ts` | `init.ts` | TypeScript source files |
+| `*.md.txt` | `index.md.txt` | Template files for markdown |
+| `*.yaml.txt` | `worktree.yaml.txt` | Template files for yaml |
+
+### Why `.txt` Extension for Templates
+
+Templates use `.txt` extension to:
+- Prevent IDE markdown preview from rendering templates
+- Make clear these are template sources, not actual docs
+- Avoid confusion with actual markdown files
+
+---
+
+## DO / DON'T
+
+### DO
+
+- Dogfood from project's own config files when possible
+- Use `cpSync` for copying entire directories
+- Keep generic templates in `src/templates/markdown/`
+- Use `.md.txt` or `.yaml.txt` for template files
+- Update dogfooding sources (`.cursor/`, `.claude/`, `.trellis/scripts/`) when making changes
+- Always use `python3` explicitly when documenting script invocation (Windows compatibility)
+
+### DON'T
+
+- Don't hardcode file lists - copy entire directories instead
+- Don't duplicate content between templates and dogfooding sources
+- Don't put project-specific content in generic templates
+- Don't use dogfooding for spec/ (users fill these in)
+
+---
+
+## Design Decisions
+
+### Remote Template Download (giget)
+
+**Context**: Need to download GitHub subdirectories for remote template support.
+
+**Options Considered**:
+1. `degit` / `tiged` - Simple, but no programmatic API
+2. `giget` - TypeScript native, has programmatic API, used by Nuxt/UnJS
+3. Manual GitHub API - Too complex
+
+**Decision**: Use `giget` because:
+- TypeScript native with programmatic API
+- Supports GitHub subdirectory: `gh:user/repo/path/to/subdir`
+- Built-in caching for offline support
+- Actively maintained by UnJS ecosystem
+
+**Example**:
+```typescript
+import { downloadTemplate } from "giget";
+
+await downloadTemplate("gh:mindfold-ai/docs/marketplace/specs/electron-fullstack", {
+  dir: destDir,
+  preferOffline: true,
+});
+```
+
+### Directory Conflict Strategy (skip/overwrite/append)
+
+**Context**: When downloading remote templates, target directory may already exist.
+
+**Decision**: Three strategies with `skip` as default:
+- `skip` - Don't download if directory exists (safe default)
+- `overwrite` - Delete existing, download fresh
+- `append` - Only copy files that don't exist (merge)
+
+**Why**: giget doesn't support append natively, so we:
+1. Download to temp directory
+2. Walk and copy missing files only
+3. Clean up temp directory
+
+**Example**:
+```typescript
+// append strategy implementation
+const tempDir = path.join(os.tmpdir(), `trellis-template-${Date.now()}`);
+await downloadTemplate(source, { dir: tempDir });
+await copyMissing(tempDir, destDir);  // Only copy non-existing files
+await fs.promises.rm(tempDir, { recursive: true });
+```
+
+### Extensible Template Type Mapping
+
+**Context**: Currently only `spec` templates, but future needs `skill`, `command`, `full` types.
+
+**Decision**: Use type field + mapping table for extensibility:
+
+```typescript
+const INSTALL_PATHS: Record<string, string> = {
+  spec: ".trellis/spec",
+  skill: ".claude/skills",
+  command: ".claude/commands",
+  full: ".",  // Entire project root
+};
+
+// Usage: auto-detect install path from template type
+const destDir = INSTALL_PATHS[template.type] || INSTALL_PATHS.spec;
+```
+
+**Extensibility**: To add new template type:
+1. Add entry to `INSTALL_PATHS`
+2. Add templates to `index.json` with new type
+3. No code changes needed for download logic

package/dist/templates/markdown/spec/backend/script-conventions.md

@@ -23,8 +23,11 @@ All workflow scripts are written in **Python 3.10+** for cross-platform compatib
 │   ├── task_utils.py     # Task helper functions
 │   ├── phase.py          # Multi-agent phase tracking
 │   ├── registry.py       # Agent registry management
-│   ├── worktree.py       # Git worktree utilities
+│   ├── config.py         # Config reader (config.yaml, hooks)
+│   ├── worktree.py       # Git worktree utilities + YAML parser
 │   └── git_context.py    # Git/session context
+├── hooks/                # Lifecycle hook scripts (project-specific)
+│   └── linear_sync.py    # Example: sync tasks to Linear
 ├── multi_agent/          # Multi-agent pipeline scripts
 │   ├── __init__.py
 │   ├── start.py          # Start worktree agent
@@ -81,10 +84,19 @@ Task Management Script.
 
 Usage:
     python3 task.py create "<title>" [--slug <name>]
-    python3 task.py list [--mine] [--status <status>]
+    python3 task.py init-context <dir> <dev_type>
+    python3 task.py add-context <dir> <file> <reason>
+    python3 task.py validate <dir>
+    python3 task.py list-context <dir>
     python3 task.py start <dir>
     python3 task.py finish
+    python3 task.py set-branch <dir> <branch>
+    python3 task.py set-base-branch <dir> <branch>
+    python3 task.py set-scope <dir> <scope>
+    python3 task.py create-pr [dir] [--dry-run]
     python3 task.py archive <task-name>
+    python3 task.py list [--mine] [--status <status>]
+    python3 task.py list-archive [YYYY-MM]
 """
 
 from __future__ import annotations
@@ -202,11 +214,13 @@ def run_command(
 
 ## Cross-Platform Compatibility
 
-### CRITICAL: Windows stdout Encoding
+### CRITICAL: Windows stdio Encoding (stdout + stdin)
 
-On Windows, Python's stdout defaults to the system code page (e.g., GBK/CP936 in China, CP1252 in Western locales). This causes `UnicodeEncodeError` when printing non-ASCII characters.
+On Windows, Python's stdout AND stdin default to the system code page (e.g., GBK/CP936 in China, CP1252 in Western locales). This causes:
+- `UnicodeEncodeError` when **printing** non-ASCII characters (stdout)
+- `UnicodeDecodeError` when **reading piped** UTF-8 content (stdin), e.g. Chinese text via `cat << EOF | python3 script.py`
 
-**The Problem Chain**:
+**The Problem Chain (stdout)**:
 
 ```
 Windows code page = GBK (936)
@@ -220,60 +234,64 @@ json.dumps(ensure_ascii=False) → print()
 GBK cannot encode \ufffd → UnicodeEncodeError: 'gbk' codec can't encode character
 ```
 
-**Root Cause**: Even if you set `PYTHONIOENCODING` in subprocess calls, the **parent process's stdout** still uses the system code page. The error occurs when `print()` tries to write to stdout.
-
----
+**The Problem Chain (stdin)**:
 
-#### GOOD: Use `sys.stdout.reconfigure()` (Python 3.7+)
+```
+AI agent pipes UTF-8 content via heredoc: cat << 'EOF' | python3 add_session.py ...
+    ↓
+Python stdin defaults to GBK encoding (PowerShell default code page)
+    ↓
+sys.stdin.read() decodes bytes as GBK, not UTF-8
+    ↓
+Chinese text garbled or UnicodeDecodeError
+```
 
-```python
-import sys
+**Root Cause**: Even if you set `PYTHONIOENCODING` in subprocess calls, the **parent process's stdio** still uses the system code page.
 
-# MUST be at the top of the script, before any print() calls
-if sys.platform == "win32":
-    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
-```
+---
 
-**Why this works**: `reconfigure()` modifies the existing stream **in-place**, changing its encoding settings directly. This affects all subsequent writes to stdout.
+#### GOOD: Centralize encoding fix in `common/__init__.py`
 
-**Best Practice**: Add this to `common/__init__.py` so all scripts that `from common import ...` automatically get the fix:
+All stdio encoding is handled in one place. Scripts that `from common import ...` automatically get the fix:
 
 ```python
 # common/__init__.py
+import io
 import sys
 
-if sys.platform == "win32":
-    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+def _configure_stream(stream):
+    """Configure a stream for UTF-8 encoding on Windows."""
+    if hasattr(stream, "reconfigure"):
+        stream.reconfigure(encoding="utf-8", errors="replace")
+        return stream
+    elif hasattr(stream, "detach"):
+        return io.TextIOWrapper(stream.detach(), encoding="utf-8", errors="replace")
+    return stream
 
-# ... rest of exports
+if sys.platform == "win32":
+    sys.stdout = _configure_stream(sys.stdout)
+    sys.stderr = _configure_stream(sys.stderr)
+    sys.stdin = _configure_stream(sys.stdin)    # Don't forget stdin!
 ```
 
 ---
 
-#### BAD: Do NOT use `io.TextIOWrapper`
+#### DON'T: Inline encoding code in individual scripts
 
 ```python
-# BAD - This does NOT reliably fix the encoding issue!
+# BAD - Duplicated in every script, easy to forget stdin
 import sys
-import io
-
 if sys.platform == "win32":
-    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    # Forgot stdin! Piped Chinese text will break.
 ```
 
-**Why this fails**:
+**Why this is bad**:
+1. **Easy to forget streams**: stdout was fixed but stdin was missed in multiple scripts, causing real user bugs
+2. **Duplicated code**: Same logic copy-pasted across `add_session.py`, `git_context.py`, etc.
+3. **Inconsistent coverage**: Some scripts fix stdout only, others fix stdout+stderr, none fixed stdin
 
-1. **Creates a new wrapper, doesn't fix the underlying issue**: `TextIOWrapper` wraps `sys.stdout.buffer`, but the original stdout object and its encoding settings may still interfere in some code paths.
-
-2. **Loses original stdout properties**: The new wrapper may not preserve all attributes of the original `sys.stdout` (like `isatty()`, line buffering behavior).
-
-3. **Race condition with buffering**: If any output was buffered before the replacement, it may still be encoded with the old encoding.
-
-4. **Not idempotent**: Calling this multiple times creates nested wrappers, while `reconfigure()` is safe to call multiple times.
-
-**Real-world failure case**: Users reported that `io.TextIOWrapper` did not fix the `UnicodeEncodeError` on Windows, while `sys.stdout.reconfigure()` worked immediately.
+**Real-world failure**: Users on Windows reported garbled Chinese text when using `cat << EOF | python3 add_session.py`. Root cause: stdin was never reconfigured to UTF-8.
 
 ---
 
@@ -281,7 +299,8 @@ if sys.platform == "win32":
 
 | Method | Works? | Reason |
 |--------|--------|--------|
-| `sys.stdout.reconfigure(encoding="utf-8")` | ✅ Yes | Modifies stream in-place |
+| `common/__init__.py` centralized fix | ✅ Yes | All streams, all scripts, one place |
+| `sys.stdout.reconfigure(encoding="utf-8")` | ⚠️ Partial | Only stdout; easy to forget stdin/stderr |
 | `io.TextIOWrapper(sys.stdout.buffer, ...)` | ❌ No | Creates wrapper, doesn't fix underlying encoding |
 | `PYTHONIOENCODING=utf-8` env var | ⚠️ Partial | Only works if set **before** Python starts |
 
@@ -320,6 +339,169 @@ path = ".trellis/scripts/task.py"
 
 ---
 
+## Task Lifecycle Hooks
+
+### Scope / Trigger
+
+Task lifecycle events (`after_create`, `after_start`, `after_finish`, `after_archive`) execute user-defined shell commands configured in `config.yaml`.
+
+### Signatures
+
+```python
+# config.py — read hook commands from config
+def get_hooks(event: str, repo_root: Path | None = None) -> list[str]
+
+# task.py — execute hooks (never blocks main operation)
+def _run_hooks(event: str, task_json_path: Path, repo_root: Path) -> None
+```
+
+### Contracts
+
+**Config format** (`config.yaml`):
+```yaml
+hooks:
+  after_create:
+    - "python3 .trellis/scripts/hooks/my_hook.py create"
+  after_start:
+    - "python3 .trellis/scripts/hooks/my_hook.py start"
+  after_archive:
+    - "python3 .trellis/scripts/hooks/my_hook.py archive"
+```
+
+**Environment variables passed to hooks**:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `TASK_JSON_PATH` | Absolute path string | Path to the task's `task.json` |
+
+- `cwd` is set to `repo_root`
+- Hooks inherit the parent process environment + `TASK_JSON_PATH`
+
+### Subprocess Execution
+
+```python
+import os
+import subprocess
+
+env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
+
+result = subprocess.run(
+    cmd,
+    shell=True,
+    cwd=repo_root,
+    env=env,
+    capture_output=True,
+    text=True,
+    encoding="utf-8",    # REQUIRED: cross-platform
+    errors="replace",    # REQUIRED: cross-platform
+)
+```
+
+### Validation & Error Matrix
+
+| Condition | Behavior |
+|-----------|----------|
+| No `hooks` key in config | No-op (empty list) |
+| `hooks` is not a dict | No-op (empty list) |
+| Event key missing | No-op (empty list) |
+| Hook command exits non-zero | `[WARN]` to stderr, continues to next hook |
+| Hook command throws exception | `[WARN]` to stderr, continues to next hook |
+| `linearis` not installed | Hook fails with warning, task operation succeeds |
+
+### Wrong vs Correct
+
+#### Wrong — blocking on hook failure
+```python
+result = subprocess.run(cmd, shell=True, check=True)  # Raises on failure!
+```
+
+#### Correct — warn and continue
+```python
+try:
+    result = subprocess.run(cmd, shell=True, ...)
+    if result.returncode != 0:
+        print(f"[WARN] Hook failed: {cmd}", file=sys.stderr)
+except Exception as e:
+    print(f"[WARN] Hook error: {cmd} — {e}", file=sys.stderr)
+```
+
+### Hook Script Pattern
+
+Hook scripts that need project-specific config (API keys, user IDs) should:
+1. Store config in a **gitignored** local file (e.g., `.trellis/hooks.local.json`)
+2. Read config at startup, fail with clear message if missing
+3. Keep the script itself committable (no hardcoded secrets)
+
+```python
+# .trellis/scripts/hooks/my_hook.py — committable, no secrets
+CONFIG = _load_config()  # reads from .trellis/hooks.local.json (gitignored)
+TEAM = CONFIG.get("linear", {}).get("team", "")
+```
+
+---
+
+## Auto-Commit Pattern
+
+Scripts that modify `.trellis/` tracked files should auto-commit their changes to keep the workspace clean. Use a `--no-commit` flag for opt-out.
+
+### Convention: Auto-Commit After Mutation
+
+```python
+def _auto_commit(scope: str, message: str, repo_root: Path) -> None:
+    """Stage and commit changes in a specific .trellis/ subdirectory."""
+    subprocess.run(["git", "add", "-A", scope], cwd=repo_root, capture_output=True)
+    # Check if there are staged changes
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--quiet", "--", scope],
+        cwd=repo_root,
+    )
+    if result.returncode == 0:
+        print("[OK] No changes to commit.", file=sys.stderr)
+        return
+    commit_result = subprocess.run(
+        ["git", "commit", "-m", message],
+        cwd=repo_root, capture_output=True, text=True,
+    )
+    if commit_result.returncode == 0:
+        print(f"[OK] Auto-committed: {message}", file=sys.stderr)
+    else:
+        print(f"[WARN] Auto-commit failed: {commit_result.stderr.strip()}", file=sys.stderr)
+```
+
+**Scripts using this pattern**:
+- `add_session.py` — commits `.trellis/workspace` + `.trellis/tasks` after recording a session
+- `task.py archive` — commits `.trellis/tasks` after archiving a task
+
+**Always add `--no-commit` flag** for scripts that auto-commit, so users can opt out.
+
+---
+
+## CLI Mode Extension Pattern
+
+### Design Decision: `--mode` for Context-Dependent Output
+
+When a script needs different output for different use cases, use `--mode` (not separate scripts or additional flags).
+
+**Example**: `get_context.py` serves two modes:
+- `--mode default` — full session context (DEVELOPER, GIT STATUS, RECENT COMMITS, CURRENT TASK, ACTIVE TASKS, MY TASKS, JOURNAL, PATHS)
+- `--mode record` — focused output for record-session (MY ACTIVE TASKS first with emphasis, GIT STATUS, RECENT COMMITS, CURRENT TASK)
+
+```python
+parser.add_argument(
+    "--mode", "-m",
+    choices=["default", "record"],
+    default="default",
+    help="Output mode: default (full context) or record (for record-session)",
+)
+```
+
+**When to add a new mode** (not a new script):
+- Output is a subset/reordering of the same data
+- The underlying data sources are shared
+- The difference is in presentation, not in data fetching
+
+---
+
 ## Error Handling
 
 ### Exit Codes

package/dist/templates/opencode/commands/trellis/brainstorm.md

@@ -387,6 +387,19 @@ Here's my understanding of the complete requirements:
 Does this look correct? If yes, I'll proceed with implementation.
 ```
 
+### Subtask Decomposition (Complex Tasks)
+
+For complex tasks with multiple independent work items, create subtasks:
+
+```bash
+# Create child tasks
+CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
+CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
+
+# Or link existing tasks
+python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
+```
+
 ---
 
 ## PRD Target Structure (final)

package/dist/templates/opencode/commands/trellis/record-session.md

@@ -12,7 +12,10 @@
 python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-[!] If MY ACTIVE TASKS shows any completed tasks, archive them FIRST:
+[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
+- Code committed? → Archive it (don't wait for PR)
+- All acceptance criteria met? → Archive it
+- Don't skip archiving just because `status` still says `planning` or `in_progress`
 
 ```bash
 python3 ./.trellis/scripts/task.py archive <task-name>

package/dist/templates/opencode/commands/trellis/start.md

@@ -93,6 +93,10 @@ See `/trellis:brainstorm` for the full process. Summary:
 5. **Confirm final requirements** - Get explicit approval
 6. **Proceed to Task Workflow** - With clear requirements in PRD
 
+> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
+> consider creating subtasks using `--parent` flag or `add-subtask` command.
+> See `/trellis:brainstorm` Step 8 for details.
+
 ---
 
 ## Task Workflow (Development Tasks)

package/dist/templates/qoder/skills/brainstorm/SKILL.md

@@ -392,6 +392,19 @@ Here's my understanding of the complete requirements:
 Does this look correct? If yes, I'll proceed with implementation.
 ```
 
+### Subtask Decomposition (Complex Tasks)
+
+For complex tasks with multiple independent work items, create subtasks:
+
+```bash
+# Create child tasks
+CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
+CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
+
+# Or link existing tasks
+python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
+```
+
 ---
 
 ## PRD Target Structure (final)