feat: add note mode and workflow config

.claude/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.
+```

.claude/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

.claude/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)

.claude/commands/trellis/continue.md

@@ -0,0 +1,51 @@
+# Continue Current Task
+
+Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
+
+---
+
+## Step 1: Load Current Context
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+Confirms: current task, git state, recent commits.
+
+## Step 2: Load the Phase Index
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode phase
+```
+
+Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+
+## Step 3: Decide Where You Are
+
+Compare the task's `prd.md` + recent activity against the Phase Index:
+
+- No `prd.md` yet, or requirements unclear → **Phase 1: Plan** (start at step 1.0/1.1)
+- `prd.md` exists + context configured, but code not written → **Phase 2: Execute** (step 2.1)
+- Code written, pending final quality gate → **Phase 3: Finish** (step 3.1)
+
+Phase rules (full detail in `.trellis/workflow.md`):
+
+1. Run steps **in order** within a phase — `[required]` steps must not be skipped
+2. `[once]` steps are already done if the output exists (e.g., `prd.md` for 1.1; `implement.jsonl` with curated entries for 1.3) — skip them
+3. You may go back to an earlier phase if discoveries require it
+
+## Step 4: Load the Specific Step
+
+Once you know which step to resume at:
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform claude
+```
+
+Follow the loaded instructions. After each `[required]` step completes, move to the next.
+
+---
+
+## Reference
+
+Full workflow, skill routing table, and the DO-NOT-skip table live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.

.claude/commands/trellis/finish-work.md

@@ -0,0 +1,32 @@
+# Finish Work
+
+Wrap up the current session.
+
+## Step 1: Quality Gate
+
+`trellis-check` should have already run in Phase 3. If not, trigger it now and do not proceed until lint, type-check, tests, and spec compliance pass.
+
+## Step 2: Remind User to Commit
+
+If there are uncommitted changes:
+
+> "Please review the changes and commit when ready."
+
+Do NOT run `git commit` — the human commits after testing.
+
+## Step 3: Record Session (after commit)
+
+Archive finished tasks (judge by work status, not the `status` field):
+
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
+
+Append a session entry (auto-handles journal rotation, line count, index update):
+
+```bash
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
+```

.claude/hooks/inject-subagent-context.py

@@ -0,0 +1,641 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Multi-Platform Sub-Agent Context Injection Hook
+
+Injects task-specific context when sub-agents (implement, check, research) are spawned.
+
+Core Design Philosophy:
+- Hook is responsible for injecting all context, subagent works autonomously with complete info
+- Each agent has a dedicated jsonl file defining its context
+- No resume needed, no segmentation, behavior controlled by code not prompt
+
+Trigger: PreToolUse (before Task tool call)
+
+Context Source: .trellis/.current-task points to task directory
+- implement.jsonl - Implement agent dedicated context
+- check.jsonl     - Check agent dedicated context
+- prd.md          - Requirements document
+- info.md         - Technical design
+- codex-review-output.txt - Code Review results
+"""
+from __future__ import annotations
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+# This fixes UnicodeEncodeError when outputting non-ASCII characters
+if sys.platform.startswith("win"):
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+
+# =============================================================================
+# Path Constants (change here to rename directories)
+# =============================================================================
+
+DIR_WORKFLOW = ".trellis"
+DIR_SPEC = "spec"
+FILE_CURRENT_TASK = ".current-task"
+FILE_TASK_JSON = "task.json"
+
+# =============================================================================
+# Subagent Constants (change here to rename subagent types)
+# =============================================================================
+
+AGENT_IMPLEMENT = "trellis-implement"
+AGENT_CHECK = "trellis-check"
+AGENT_RESEARCH = "trellis-research"
+
+# Agents that require a task directory
+AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK)
+# All supported agents
+AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_RESEARCH)
+
+
+def find_repo_root(start_path: str) -> str | None:
+    """
+    Find git repo root from start_path upwards
+
+    Returns:
+        Repo root path, or None if not found
+    """
+    current = Path(start_path).resolve()
+    while current != current.parent:
+        if (current / ".git").exists():
+            return str(current)
+        current = current.parent
+    return None
+
+
+def get_current_task(repo_root: str) -> str | None:
+    """
+    Read current task directory path from .trellis/.current-task
+
+    Returns:
+        Task directory relative path (relative to repo_root)
+        None if not set
+    """
+    current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK)
+    if not os.path.exists(current_task_file):
+        return None
+
+    try:
+        with open(current_task_file, "r", encoding="utf-8") as f:
+            content = f.read().strip()
+            if not content:
+                return None
+            normalized = content.replace("\\", "/")
+            while normalized.startswith("./"):
+                normalized = normalized[2:]
+            if normalized.startswith("tasks/"):
+                normalized = f".trellis/{normalized}"
+            return normalized
+    except Exception:
+        return None
+
+
+def read_file_content(base_path: str, file_path: str) -> str | None:
+    """Read file content, return None if file doesn't exist"""
+    full_path = os.path.join(base_path, file_path)
+    if os.path.exists(full_path) and os.path.isfile(full_path):
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except Exception:
+            return None
+    return None
+
+
+def read_directory_contents(
+    base_path: str, dir_path: str, max_files: int = 20
+) -> list[tuple[str, str]]:
+    """
+    Read all .md files in a directory
+
+    Args:
+        base_path: Base path (usually repo_root)
+        dir_path: Directory relative path
+        max_files: Max files to read (prevent huge directories)
+
+    Returns:
+        [(file_path, content), ...]
+    """
+    full_path = os.path.join(base_path, dir_path)
+    if not os.path.exists(full_path) or not os.path.isdir(full_path):
+        return []
+
+    results = []
+    try:
+        # Only read .md files, sorted by filename
+        md_files = sorted(
+            [
+                f
+                for f in os.listdir(full_path)
+                if f.endswith(".md") and os.path.isfile(os.path.join(full_path, f))
+            ]
+        )
+
+        for filename in md_files[:max_files]:
+            file_full_path = os.path.join(full_path, filename)
+            relative_path = os.path.join(dir_path, filename)
+            try:
+                with open(file_full_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    results.append((relative_path, content))
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+    return results
+
+
+def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]:
+    """
+    Read all file/directory contents referenced in jsonl file
+
+    Schema:
+        {"file": "path/to/file.md", "reason": "..."}
+        {"file": "path/to/dir/", "type": "directory", "reason": "..."}
+        {"_example": "..."}          # seed row — skipped (no `file` field)
+
+    Rows without a ``file`` field (e.g. the self-describing seed line written
+    by ``task.py create`` before the agent has curated entries) are skipped
+    silently. If the resulting entry list is empty, a stderr warning is
+    emitted so the operator can debug missing context.
+
+    Returns:
+        [(path, content), ...]
+    """
+    full_path = os.path.join(base_path, jsonl_path)
+    if not os.path.exists(full_path):
+        print(
+            f"[inject-subagent-context] WARN: {jsonl_path} not found — "
+            f"sub-agent will receive only prd.md",
+            file=sys.stderr,
+        )
+        return []
+
+    results = []
+    saw_real_entry = False
+    try:
+        with open(full_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    file_path = item.get("file") or item.get("path")
+                    entry_type = item.get("type", "file")
+
+                    if not file_path:
+                        # Seed / comment row — skip silently
+                        continue
+
+                    saw_real_entry = True
+                    if entry_type == "directory":
+                        # Read all .md files in directory
+                        dir_contents = read_directory_contents(base_path, file_path)
+                        results.extend(dir_contents)
+                    else:
+                        # Read single file
+                        content = read_file_content(base_path, file_path)
+                        if content:
+                            results.append((file_path, content))
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    if not saw_real_entry:
+        print(
+            f"[inject-subagent-context] WARN: {jsonl_path} has no curated "
+            f"entries (only seed / empty) — sub-agent will receive only "
+            f"prd.md. See workflow.md Phase 1.3 for curation guidance.",
+            file=sys.stderr,
+        )
+
+    return results
+
+
+
+
+def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
+    """
+    Get context from {agent_type}.jsonl for the specified agent.
+    Only reads implement.jsonl or check.jsonl (the two JSONL files the task system creates).
+    """
+    context_parts = []
+
+    agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
+    for file_path, content in read_jsonl_entries(repo_root, agent_jsonl):
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    return "\n\n".join(context_parts)
+
+
+def get_implement_context(repo_root: str, task_dir: str) -> str:
+    """
+    Complete context for Implement Agent
+
+    Read order:
+    1. All files in implement.jsonl (dev specs)
+    2. prd.md (requirements)
+    3. info.md (technical design)
+    """
+    context_parts = []
+
+    # 1. Read implement.jsonl
+    base_context = get_agent_context(repo_root, task_dir, "implement")
+    if base_context:
+        context_parts.append(base_context)
+
+    # 2. Requirements document
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    # 3. Technical design
+    info_content = read_file_content(repo_root, f"{task_dir}/info.md")
+    if info_content:
+        context_parts.append(
+            f"=== {task_dir}/info.md (Technical Design) ===\n{info_content}"
+        )
+
+    return "\n\n".join(context_parts)
+
+
+def get_check_context(repo_root: str, task_dir: str) -> str:
+    """
+    Context for Check Agent: check.jsonl + prd.md
+    """
+    context_parts = []
+
+    for file_path, content in read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl"):
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    return "\n\n".join(context_parts)
+
+
+def get_finish_context(repo_root: str, task_dir: str) -> str:
+    """
+    Context for Finish phase: reuses check.jsonl + prd.md
+    (Finish is a final check, same context source.)
+    """
+    return get_check_context(repo_root, task_dir)
+
+
+
+def build_implement_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Implement"""
+    return f"""# Implement Agent Task
+
+You are the Implement Agent in the Multi-Agent Pipeline.
+
+## Your Context
+
+All the information you need has been prepared for you:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand specs** - All dev specs are injected above, understand them
+2. **Understand requirements** - Read requirements document and technical design
+3. **Implement feature** - Implement following specs and design
+4. **Self-check** - Ensure code quality against check specs
+
+## Important Constraints
+
+- Do NOT execute git commit, only code modifications
+- Follow all dev specs injected above
+- Report list of modified/created files when done"""
+
+
+def build_check_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Check"""
+    return f"""# Check Agent Task
+
+You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker).
+
+## Your Context
+
+All check specs and dev specs you need:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes
+2. **Check against specs** - Check item by item against specs above
+3. **Self-fix** - Fix issues directly, don't just report
+4. **Run verification** - Run project's lint and typecheck commands
+
+## Important Constraints
+
+- Fix issues yourself, don't just report
+- Must execute complete checklist in check specs
+- Pay special attention to impact radius analysis (L1-L5)"""
+
+
+def build_finish_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Finish (final check before PR)"""
+    return f"""# Finish Agent Task
+
+You are performing the final check before creating a PR.
+
+## Your Context
+
+Finish checklist and requirements:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Review changes** - Run `git diff --name-only` to see all changed files
+2. **Verify requirements** - Check each requirement in prd.md is implemented
+3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions
+   - If new pattern/convention found: read target spec file → update it → update index.md if needed
+   - If infra/cross-layer change: follow the 7-section mandatory template from update-spec.md
+   - If pure code fix with no new patterns: skip this step
+4. **Run final checks** - Execute lint and typecheck
+5. **Confirm ready** - Ensure code is ready for PR
+
+## Important Constraints
+
+- You MAY update spec files when gaps are detected (use update-spec.md as guide)
+- MUST read the target spec file BEFORE editing (avoid duplicating existing content)
+- Do NOT update specs for trivial changes (typos, formatting, obvious fixes)
+- If critical CODE issues found, report them clearly (fix specs, not code)
+- Verify all acceptance criteria in prd.md are met"""
+
+
+
+def get_research_context(repo_root: str, task_dir: str | None) -> str:
+    """
+    Context for Research Agent — project structure overview for spec directories.
+
+    `task_dir` kept for signature parity with get_implement_context / get_check_context
+    so the dispatcher can call them uniformly.
+    """
+    _ = task_dir
+    context_parts = []
+
+    # 1. Project structure overview (dynamically discover spec directories)
+    spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
+    spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC
+
+    # Build spec tree dynamically
+    tree_lines = [f"{spec_path}/"]
+    if spec_root.is_dir():
+        pkg_dirs = sorted(d for d in spec_root.iterdir() if d.is_dir())
+        for i, pkg_dir in enumerate(pkg_dirs):
+            is_last = i == len(pkg_dirs) - 1
+            prefix = "└── " if is_last else "├── "
+            layers = sorted(d.name for d in pkg_dir.iterdir() if d.is_dir())
+            layer_info = f" ({', '.join(layers)})" if layers else ""
+            tree_lines.append(f"{prefix}{pkg_dir.name}/{layer_info}")
+
+    spec_tree = "\n".join(tree_lines)
+
+    project_structure = f"""## Project Spec Directory Structure
+
+```
+{spec_tree}
+```
+
+To get structured package info, run: `python3 ./{DIR_WORKFLOW}/scripts/get_context.py --mode packages`
+
+## Search Tips
+
+- Spec files: `{spec_path}/**/*.md`
+- Code search: Use Glob and Grep tools
+- Tech solutions: Use mcp__exa__web_search_exa or mcp__exa__get_code_context_exa"""
+
+    context_parts.append(project_structure)
+
+    return "\n\n".join(context_parts)
+
+
+def build_research_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Research"""
+    return f"""# Research Agent Task
+
+You are the Research Agent in the Multi-Agent Pipeline (search researcher).
+
+## Core Principle
+
+**You do one thing: find and explain information.**
+
+You are a documenter, not a reviewer.
+
+## Project Info
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand query** - Determine search type (internal/external) and scope
+2. **Plan search** - List search steps for complex queries
+3. **Execute search** - Execute multiple independent searches in parallel
+4. **Organize results** - Output structured report
+
+## Search Tools
+
+| Tool | Purpose |
+|------|---------|
+| Glob | Search by filename pattern |
+| Grep | Search by content |
+| Read | Read file content |
+| mcp__exa__web_search_exa | External web search |
+| mcp__exa__get_code_context_exa | External code/doc search |
+
+## Strict Boundaries
+
+**Only allowed**: Describe what exists, where it is, how it works
+
+**Forbidden** (unless explicitly asked):
+- Suggest improvements
+- Criticize implementation
+- Recommend refactoring
+- Modify any files
+
+## Report Format
+
+Provide structured search results including:
+- List of files found (with paths)
+- Code pattern analysis (if applicable)
+- Related spec documents
+- External references (if any)"""
+
+
+def _parse_hook_input(input_data: dict) -> tuple[str, str, dict]:
+    """Parse hook input across different platform formats.
+
+    Returns (subagent_type, original_prompt, tool_input).
+    Handles:
+    - Claude Code / Qoder / CodeBuddy / Droid: tool_name=Task|Agent, tool_input.subagent_type
+    - Cursor: tool_name=Task, tool_input.subagent_type
+    - Copilot CLI: toolName=task (camelCase key, lowercase value)
+    - Gemini CLI: tool_name IS the agent name (BeforeTool matcher already filtered)
+    - Kiro: agentSpawn hook, agent_name field at top level
+    """
+    tool_input = input_data.get("tool_input", {})
+
+    # Standard format: Task/Agent tool with subagent_type
+    tool_name = input_data.get("tool_name", "") or input_data.get("toolName", "")
+    if tool_name.lower() in ("task", "agent"):
+        return (
+            tool_input.get("subagent_type", ""),
+            tool_input.get("prompt", ""),
+            tool_input,
+        )
+
+    # Kiro: agentSpawn hook passes agent_name at top level
+    agent_name = input_data.get("agent_name", "")
+    if agent_name:
+        return agent_name, tool_input.get("prompt", input_data.get("prompt", "")), tool_input
+
+    # Gemini CLI: BeforeTool where tool_name IS the agent name
+    # (matcher already ensured it's one of our agents)
+    if tool_name in AGENTS_ALL:
+        return tool_name, tool_input.get("prompt", ""), tool_input
+
+    # Copilot CLI: toolName field (camelCase), value might be the agent name
+    tool_name_camel = input_data.get("toolName", "")
+    if tool_name_camel in AGENTS_ALL:
+        return tool_name_camel, input_data.get("toolArgs", ""), tool_input
+
+    return "", "", tool_input
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    subagent_type, original_prompt, tool_input = _parse_hook_input(input_data)
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Only handle subagent types we care about
+    if subagent_type not in AGENTS_ALL:
+        sys.exit(0)
+
+    # Find repo root
+    repo_root = find_repo_root(cwd)
+    if not repo_root:
+        sys.exit(0)
+
+    # Get current task directory (research doesn't require it)
+    task_dir = get_current_task(repo_root)
+
+    # implement/check need task directory
+    if subagent_type in AGENTS_REQUIRE_TASK:
+        if not task_dir:
+            sys.exit(0)
+        # Check if task directory exists
+        task_dir_full = os.path.join(repo_root, task_dir)
+        if not os.path.exists(task_dir_full):
+            sys.exit(0)
+
+    # Check for [finish] marker in prompt (check agent with finish context)
+    is_finish_phase = "[finish]" in original_prompt.lower()
+
+    # Get context and build prompt based on subagent type
+    if subagent_type == AGENT_IMPLEMENT:
+        assert task_dir is not None  # validated above
+        context = get_implement_context(repo_root, task_dir)
+        new_prompt = build_implement_prompt(original_prompt, context)
+    elif subagent_type == AGENT_CHECK:
+        assert task_dir is not None  # validated above
+        if is_finish_phase:
+            # Finish phase: use finish context (lighter, focused on final verification)
+            context = get_finish_context(repo_root, task_dir)
+            new_prompt = build_finish_prompt(original_prompt, context)
+        else:
+            # Regular check phase: use check context (full specs for self-fix loop)
+            context = get_check_context(repo_root, task_dir)
+            new_prompt = build_check_prompt(original_prompt, context)
+    elif subagent_type == AGENT_RESEARCH:
+        # Research can work without task directory
+        context = get_research_context(repo_root, task_dir)
+        new_prompt = build_research_prompt(original_prompt, context)
+    else:
+        sys.exit(0)
+
+    if not context:
+        sys.exit(0)
+
+    # Return updated input — use a multi-format output that covers all platforms.
+    # Most platforms ignore unrecognized fields, so we include multiple formats.
+    # The platform picks whichever fields it understands.
+    updated = {**tool_input, "prompt": new_prompt}
+    output = {
+        # Claude Code / Qoder / CodeBuddy / Droid format
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": updated,
+        },
+        # Cursor format
+        "permission": "allow",
+        "updated_input": updated,
+        # Gemini format
+        "updatedInput": updated,
+    }
+
+    print(json.dumps(output, ensure_ascii=False))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

.claude/hooks/inject-workflow-state.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Trellis UserPromptSubmit hook: inject per-turn workflow breadcrumb.
+
+Runs on every user prompt. Reads the active task (.trellis/.current-task)
+and emits a short <workflow-state> block reminding the main AI what task
+is active and its expected flow. Breadcrumb text is pulled from
+workflow.md [workflow-state:STATUS] tag blocks (single source of truth
+for users who fork the Trellis workflow), with hardcoded fallbacks so
+the hook never breaks when workflow.md is missing or malformed.
+
+Shared across all hook-capable platforms (Claude, Cursor, Codex, Qoder,
+CodeBuddy, Droid, Gemini, Copilot). Kiro is not wired (no per-turn
+hook entry point). Written to each platform's hooks directory via
+writeSharedHooks() at init time.
+
+Silent exit 0 cases (no output):
+  - No .trellis/ directory found (not a Trellis project)
+  - No .current-task file, or it's empty
+  - task.json malformed or missing status
+
+Unknown status (no tag + no hardcoded fallback) emits a generic
+breadcrumb rather than silent-exiting, so custom statuses surface in
+the UI instead of appearing as "randomly broken".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# CWD-robust Trellis root discovery (fixes hook-path-robustness for this hook)
+# ---------------------------------------------------------------------------
+
+def find_trellis_root(start: Path) -> Optional[Path]:
+    """Walk up from start to find directory containing .trellis/.
+
+    Handles CWD drift: subdirectory launches, monorepo packages, etc.
+    Returns None if no .trellis/ found (silent no-op).
+    """
+    cur = start.resolve()
+    while cur != cur.parent:
+        if (cur / ".trellis").is_dir():
+            return cur
+        cur = cur.parent
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Active task discovery
+# ---------------------------------------------------------------------------
+
+def _normalize_task_ref(task_ref: str) -> str:
+    """Normalize .current-task path ref.
+
+    Accepts:
+    - Absolute paths (left as-is)
+    - Windows-style backslashes (converted to forward slash)
+    - Legacy relative refs like "tasks/foo" (prefixed with .trellis/)
+    """
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    if normalized.startswith("tasks/"):
+        normalized = f".trellis/{normalized}"
+    return normalized
+
+
+def get_active_task(root: Path) -> Optional[Tuple[str, str]]:
+    """Return (task_id, status) from the current active task, else None.
+
+    Reads .trellis/.current-task (a path relative to root, e.g.
+    ".trellis/tasks/04-17-foo") then that task's task.json.
+    Normalizes backslashes so Windows paths work on Unix and vice versa.
+    """
+    ref_file = root / ".trellis" / ".current-task"
+    if not ref_file.is_file():
+        return None
+    try:
+        raw = ref_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    task_ref = _normalize_task_ref(raw)
+    if not task_ref:
+        return None
+
+    path_obj = Path(task_ref)
+    task_dir = path_obj if path_obj.is_absolute() else root / path_obj
+    task_json = task_dir / "task.json"
+    if not task_json.is_file():
+        return None
+    try:
+        data = json.loads(task_json.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    task_id = data.get("id") or task_dir.name
+    status = data.get("status", "")
+    if not isinstance(status, str) or not status:
+        return None
+    return task_id, status
+
+
+# ---------------------------------------------------------------------------
+# Breadcrumb loading: parse workflow.md, fall back to hardcoded defaults
+# ---------------------------------------------------------------------------
+
+# Supports STATUS values with letters, digits, underscores, hyphens
+# (so "in-review" / "blocked-by-team" work alongside "in_progress").
+_TAG_RE = re.compile(
+    r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n(.*?)\n\s*\[/workflow-state:\1\]",
+    re.DOTALL,
+)
+
+# Hardcoded defaults for built-in Trellis statuses. Used when workflow.md is
+# missing, malformed, or lacks the tag for this status.
+#
+# `no_task` is a pseudo-status emitted when .current-task is missing — it keeps
+# the Next-Action reminder flowing per-turn even without an active task.
+_FALLBACK_BREADCRUMBS = {
+    "no_task": (
+        "No active task.\n"
+        "Trigger words in the user message that REQUIRE creating a task "
+        "(non-negotiable, do NOT self-exempt): 重构 / 抽成 / 独立 / 分发 / "
+        "拆出来 / 搞一个 / 做成 / 接入 / 集成 / refactor / rewrite / extract / "
+        "productize / publish / build X / design Y.\n"
+        "Task is NOT required ONLY if ALL three hold: (a) zero file writes "
+        "this turn, (b) answer fits in one reply with no multi-round plan, "
+        "(c) no research beyond reading 1-2 repo files.\n"
+        "When in doubt: create task. Over-tasking is cheap; under-tasking "
+        "leaks plans and research into main context.\n"
+        "Flow: load `trellis-brainstorm` skill → it creates the task via "
+        "`python3 ./.trellis/scripts/task.py create` and drives requirements Q&A. "
+        "For research-heavy work (tool comparison, docs, cross-platform survey), "
+        "spawn `trellis-research` sub-agents via Task tool — NEVER do 3+ inline "
+        "WebFetch/WebSearch/`gh api` calls in the main conversation."
+    ),
+    "planning": (
+        "Complete prd.md via trellis-brainstorm skill; then run task.py start.\n"
+        "Research belongs in `{task_dir}/research/*.md`, written by "
+        "`trellis-research` sub-agents. Do NOT inline WebFetch/WebSearch in "
+        "main session — PRD only links to research files."
+    ),
+    "in_progress": (
+        "Flow: trellis-implement → trellis-check → trellis-update-spec → finish\n"
+        "Next required action: inspect conversation history + git status, then "
+        "execute the next uncompleted step in that sequence.\n"
+        "For agent-capable platforms, do NOT edit code in the main session; "
+        "dispatch `trellis-implement` for implementation and dispatch "
+        "`trellis-check` before reporting completion."
+    ),
+    "completed": (
+        "User commits changes; then run task.py archive."
+    ),
+}
+
+
+def load_breadcrumbs(root: Path) -> dict[str, str]:
+    """Parse workflow.md for [workflow-state:STATUS] blocks.
+
+    Returns {status: body_text}. Missing tags fall back to hardcoded
+    defaults so the hook always has something to say for built-in
+    statuses. Custom statuses without tags fall to generic breadcrumb
+    downstream (see build_breadcrumb).
+    """
+    result = dict(_FALLBACK_BREADCRUMBS)
+
+    workflow = root / ".trellis" / "workflow.md"
+    if not workflow.is_file():
+        return result
+    try:
+        content = workflow.read_text(encoding="utf-8")
+    except OSError:
+        return result
+
+    for match in _TAG_RE.finditer(content):
+        status = match.group(1)
+        body = match.group(2).strip()
+        if body:
+            result[status] = body
+    return result
+
+
+def build_breadcrumb(
+    task_id: Optional[str], status: str, templates: dict[str, str]
+) -> str:
+    """Build the <workflow-state>...</workflow-state> block.
+
+    - Known status (in templates or fallback) → detailed template body
+    - Unknown status (no tag + no fallback) → generic "refer to workflow.md"
+    - `no_task` pseudo-status (task_id is None) → header omits task info
+    """
+    body = templates.get(status)
+    if body is None:
+        body = "Refer to workflow.md for current step."
+    header = f"Status: {status}" if task_id is None else f"Task: {task_id} ({status})"
+    return f"<workflow-state>\n{header}\n{body}\n</workflow-state>"
+
+
+# ---------------------------------------------------------------------------
+# Entry
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        data = {}
+
+    cwd_str = data.get("cwd") or os.getcwd()
+    cwd = Path(cwd_str)
+
+    root = find_trellis_root(cwd)
+    if root is None:
+        return 0  # not a Trellis project
+
+    templates = load_breadcrumbs(root)
+    task = get_active_task(root)
+    if task is None:
+        # No active task — still emit a breadcrumb nudging AI toward
+        # trellis-brainstorm + task.py create when user describes real work.
+        breadcrumb = build_breadcrumb(None, "no_task", templates)
+    else:
+        breadcrumb = build_breadcrumb(*task, templates=templates)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": breadcrumb,
+        }
+    }
+    print(json.dumps(output))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.claude/hooks/session-start.py

@@ -0,0 +1,577 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Session Start Hook - Inject structured context
+"""
+from __future__ import annotations
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import subprocess
+import sys
+from io import StringIO
+from pathlib import Path
+
+FIRST_REPLY_NOTICE = """<first-reply-notice>
+On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
+Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
+Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>"""
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+# This fixes UnicodeEncodeError when outputting non-ASCII characters
+if sys.platform.startswith("win"):
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+
+
+def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
+    """Return True iff jsonl has at least one row with a ``file`` field.
+
+    A freshly seeded jsonl only contains a ``{"_example": ...}`` row (no
+    ``file`` key) — that is NOT "ready". Readiness requires at least one
+    curated entry. Matches the contract used by ``inject-subagent-context.py``.
+    """
+    try:
+        for line in jsonl_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(row, dict) and row.get("file"):
+                return True
+    except (OSError, UnicodeDecodeError):
+        return False
+    return False
+
+
+def should_skip_injection() -> bool:
+    """Check if any platform's non-interactive flag is set."""
+    non_interactive_vars = [
+        "CLAUDE_NON_INTERACTIVE",
+        "QODER_NON_INTERACTIVE",
+        "CODEBUDDY_NON_INTERACTIVE",
+        "FACTORY_NON_INTERACTIVE",
+        "CURSOR_NON_INTERACTIVE",
+        "GEMINI_NON_INTERACTIVE",
+        "KIRO_NON_INTERACTIVE",
+        "COPILOT_NON_INTERACTIVE",
+    ]
+    return any(os.environ.get(var) == "1" for var in non_interactive_vars)
+
+
+def read_file(path: Path, fallback: str = "") -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (FileNotFoundError, PermissionError):
+        return fallback
+
+
+def run_script(script_path: Path) -> str:
+    try:
+        if script_path.suffix == ".py":
+            # Add PYTHONIOENCODING to force UTF-8 in subprocess
+            env = os.environ.copy()
+            env["PYTHONIOENCODING"] = "utf-8"
+            cmd = [sys.executable, "-W", "ignore", str(script_path)]
+        else:
+            env = os.environ
+            cmd = [str(script_path)]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            cwd=script_path.parent.parent.parent,
+            env=env,
+        )
+        return result.stdout if result.returncode == 0 else "No context available"
+    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError):
+        return "No context available"
+
+
+def _normalize_task_ref(task_ref: str) -> str:
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith("tasks/"):
+        return f".trellis/{normalized}"
+
+    return normalized
+
+
+def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
+    normalized = _normalize_task_ref(task_ref)
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+    if normalized.startswith(".trellis/"):
+        return trellis_dir.parent / path_obj
+    return trellis_dir / "tasks" / path_obj
+
+
+def _get_task_status(trellis_dir: Path) -> str:
+    """Check current task status and return structured status string with explicit next action.
+
+    Returns a block with three fields:
+    - Status: current state
+    - Task: task identifier (when applicable)
+    - Next-Action: explicit skill/command/tool call the AI should invoke
+    """
+    current_task_file = trellis_dir / ".current-task"
+
+    # Case 1: No active task — waiting for user to describe intent
+    if not current_task_file.is_file() or not current_task_file.read_text(encoding="utf-8").strip():
+        return (
+            "Status: NO ACTIVE TASK\n"
+            "Next-Action: After the user describes their intent, load skill `trellis-brainstorm` "
+            "to clarify requirements and create a task via `python3 ./.trellis/scripts/task.py create`.\n"
+            "Research reminder: for research-heavy tasks (comparing tools, reading external docs, "
+            "cross-platform surveys), spawn `trellis-research` sub-agents via the Task tool — "
+            "they persist findings to `{TASK_DIR}/research/*.md` and keep main context clean. "
+            "Do NOT do 10+ inline WebFetch/WebSearch in the main conversation."
+        )
+
+    task_ref = _normalize_task_ref(current_task_file.read_text(encoding="utf-8").strip())
+
+    # Case 2: Stale pointer — task dir was deleted
+    task_dir = _resolve_task_dir(trellis_dir, task_ref)
+    if not task_dir.is_dir():
+        return (
+            f"Status: STALE POINTER\nTask: {task_ref}\n"
+            f"Next-Action: Run `python3 ./.trellis/scripts/task.py finish` to clear the stale pointer, "
+            "then ask the user what to work on next."
+        )
+
+    # Read task.json
+    task_json_path = task_dir / "task.json"
+    task_data = {}
+    if task_json_path.is_file():
+        try:
+            task_data = json.loads(task_json_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, PermissionError):
+            pass
+
+    task_title = task_data.get("title", task_ref)
+    task_status = task_data.get("status", "unknown")
+
+    # Case 3: Task completed — time to archive
+    if task_status == "completed":
+        return (
+            f"Status: COMPLETED\nTask: {task_title}\n"
+            f"Next-Action: Load skill `trellis-update-spec` to capture learnings, "
+            f"then archive with `python3 ./.trellis/scripts/task.py archive {task_dir.name}`."
+        )
+
+    has_prd = (task_dir / "prd.md").is_file()
+
+    # Case 4: No PRD — still in Plan phase
+    if not has_prd:
+        return (
+            f"Status: PLANNING\nTask: {task_title}\n"
+            "Next-Action: Load skill `trellis-brainstorm` to clarify requirements with the user "
+            "and produce prd.md in the task directory.\n"
+            "Research reminder: when the task needs external research (tool comparison, docs, "
+            "conventions survey), spawn `trellis-research` sub-agents — don't WebFetch/WebSearch "
+            "inline in the main session. Findings go to `{task_dir}/research/*.md`; PRD only links to them."
+        )
+
+    # Case 4b: PRD exists but implement.jsonl has only seed (no curated entries) — Phase 1.3 gate
+    implement_jsonl = task_dir / "implement.jsonl"
+    if implement_jsonl.is_file() and not _has_curated_jsonl_entry(implement_jsonl):
+        return (
+            f"Status: PLANNING (Phase 1.3)\nTask: {task_title}\n"
+            "Next-Action: Curate `implement.jsonl` and `check.jsonl` with the spec + research files "
+            "the Phase 2 sub-agents will need. Only spec paths (`.trellis/spec/**/*.md`) and research "
+            "files (`{TASK_DIR}/research/*.md`) — no code paths. Run "
+            "`python3 ./.trellis/scripts/get_context.py --mode packages` to list available specs, "
+            "then edit the jsonl files or use `python3 ./.trellis/scripts/task.py add-context`. "
+            "See `.trellis/workflow.md` Phase 1.3 for details."
+        )
+
+    # Case 5: PRD + curated jsonl (or agent-less platform with no jsonl) — enter Execute phase
+    return (
+        f"Status: READY\nTask: {task_title}\n"
+        "Next required action: dispatch `trellis-implement` per Phase 2.1. "
+        "For agent-capable platforms, do NOT edit code in the main session. "
+        "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\n"
+        "Sub-agent roster: `trellis-implement` (writes code), `trellis-check` (verifies + self-fixes), "
+        "`trellis-research` (persists findings to `research/*.md` — use when you'd otherwise do "
+        "multiple WebFetch/WebSearch inline)."
+    )
+
+
+def _load_trellis_config(trellis_dir: Path) -> tuple:
+    """Load Trellis config for session-start decisions.
+
+    Returns:
+        (is_mono, packages_dict, spec_scope, task_pkg, default_pkg)
+    """
+    scripts_dir = trellis_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        from common.config import get_default_package, get_packages, get_spec_scope, is_monorepo  # type: ignore[import-not-found]
+        from common.paths import get_current_task  # type: ignore[import-not-found]
+
+        repo_root = trellis_dir.parent
+        is_mono = is_monorepo(repo_root)
+        packages = get_packages(repo_root) or {}
+        scope = get_spec_scope(repo_root)
+
+        # Get active task's package
+        task_pkg = None
+        current = get_current_task(repo_root)
+        if current:
+            task_json = repo_root / current / "task.json"
+            if task_json.is_file():
+                try:
+                    data = json.loads(task_json.read_text(encoding="utf-8"))
+                    if isinstance(data, dict):
+                        tp = data.get("package")
+                        if isinstance(tp, str) and tp:
+                            task_pkg = tp
+                except (json.JSONDecodeError, OSError):
+                    pass
+
+        default_pkg = get_default_package(repo_root)
+        return is_mono, packages, scope, task_pkg, default_pkg
+    except Exception:
+        return False, {}, None, None, None
+
+
+def _check_legacy_spec(trellis_dir: Path, is_mono: bool, packages: dict) -> str | None:
+    """Check for legacy spec directory structure in monorepo.
+
+    Returns warning message if legacy structure detected, None otherwise.
+    """
+    if not is_mono or not packages:
+        return None
+
+    spec_dir = trellis_dir / "spec"
+    if not spec_dir.is_dir():
+        return None
+
+    # Check for legacy flat spec dirs (spec/backend/, spec/frontend/ with index.md)
+    has_legacy = False
+    for legacy_name in ("backend", "frontend"):
+        legacy_dir = spec_dir / legacy_name
+        if legacy_dir.is_dir() and (legacy_dir / "index.md").is_file():
+            has_legacy = True
+            break
+
+    if not has_legacy:
+        return None
+
+    # Check which packages are missing spec/<pkg>/ directory
+    missing = [
+        name for name in sorted(packages.keys())
+        if not (spec_dir / name).is_dir()
+    ]
+
+    if not missing:
+        return None  # All packages have spec dirs
+
+    if len(missing) == len(packages):
+        return (
+            f"[!] Legacy spec structure detected: found `spec/backend/` or `spec/frontend/` "
+            f"but no package-scoped `spec/<package>/` directories.\n"
+            f"Monorepo packages: {', '.join(sorted(packages.keys()))}\n"
+            f"Please reorganize: `spec/backend/` -> `spec/<package>/backend/`"
+        )
+    return (
+        f"[!] Partial spec migration detected: packages {', '.join(missing)} "
+        f"still missing `spec/<pkg>/` directory.\n"
+        f"Please complete migration for all packages."
+    )
+
+
+def _resolve_spec_scope(
+    is_mono: bool,
+    packages: dict,
+    scope,
+    task_pkg: str | None,
+    default_pkg: str | None,
+) -> set | None:
+    """Resolve which packages should have their specs injected.
+
+    Returns:
+        Set of package names to include, or None for full scan.
+    """
+    if not is_mono or not packages:
+        return None  # Single-repo: full scan
+
+    if scope is None:
+        return None  # No scope configured: full scan
+
+    if isinstance(scope, str) and scope == "active_task":
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None  # Fallback to full scan
+
+    if isinstance(scope, list):
+        valid = set()
+        for entry in scope:
+            if entry in packages:
+                valid.add(entry)
+            else:
+                print(
+                    f"Warning: spec_scope contains unknown package: {entry}, ignoring",
+                    file=sys.stderr,
+                )
+
+        if valid:
+            # Warn if active task is out of scope
+            if task_pkg and task_pkg not in valid:
+                print(
+                    f"Warning: active task package '{task_pkg}' is out of configured spec_scope",
+                    file=sys.stderr,
+                )
+            return valid
+
+        # All entries invalid: fallback chain
+        print(
+            "Warning: all spec_scope entries invalid, falling back to task/default/full",
+            file=sys.stderr,
+        )
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None  # Full scan
+
+    return None  # Unknown scope type: full scan
+
+
+def _extract_range(content: str, start_header: str, end_header: str) -> str:
+    """Extract lines starting at `## start_header` up to (but excluding) `## end_header`.
+
+    Both parameters are full header lines WITHOUT the `## ` prefix (e.g. "Phase Index").
+    Returns empty string if start header is not found.
+    End header missing → extracts to end of file.
+    """
+    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()
+
+
+def _build_workflow_overview(workflow_path: Path) -> str:
+    """Inject the workflow guide for the session.
+
+    Contents:
+      1. Section index (all `## ` headings — navigation)
+      2. Phase Index section (rules, skill routing table, anti-rationalization table)
+      3. Phase 1/2/3 step-level details (the actual how-to for each step)
+
+    The meta sections (Core Principles / Trellis System / Workflow State
+    Breadcrumbs) are NOT injected — Core Principles is short prose the AI can
+    Read on demand; Trellis System lists reference commands duplicated in
+    step bodies; Breadcrumbs are consumed by the UserPromptSubmit hook.
+
+    Total budget: Phase Index ~2 KB + Phase 1/2/3 ~7 KB = ~9 KB.
+    """
+    content = read_file(workflow_path)
+    if not content:
+        return "No workflow.md found"
+
+    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("## "):
+            out_lines.append(line)
+    out_lines += ["", "---", ""]
+
+    # Extract Phase Index through the end of Phase 3 (before Breadcrumbs).
+    # Since sections appear in order Phase Index → Phase 1 → Phase 2 → Phase 3
+    # → Workflow State Breadcrumbs, a single range grab captures all four.
+    phases = _extract_range(
+        content, "Phase Index", "Workflow State Breadcrumbs"
+    )
+    if phases:
+        out_lines.append(phases)
+
+    return "\n".join(out_lines).rstrip()
+
+
+def main():
+    if should_skip_injection():
+        sys.exit(0)
+
+    # Try platform-specific env vars, fallback to cwd
+    project_dir_env_vars = [
+        "CLAUDE_PROJECT_DIR",
+        "QODER_PROJECT_DIR",
+        "CODEBUDDY_PROJECT_DIR",
+        "FACTORY_PROJECT_DIR",
+        "CURSOR_PROJECT_DIR",
+        "GEMINI_PROJECT_DIR",
+        "KIRO_PROJECT_DIR",
+        "COPILOT_PROJECT_DIR",
+    ]
+    project_dir = None
+    for var in project_dir_env_vars:
+        val = os.environ.get(var)
+        if val:
+            project_dir = Path(val).resolve()
+            break
+    if project_dir is None:
+        project_dir = Path(".").resolve()
+
+    trellis_dir = project_dir / ".trellis"
+
+    # Load config for scope filtering and legacy detection
+    is_mono, packages, scope_config, task_pkg, default_pkg = _load_trellis_config(trellis_dir)
+    allowed_pkgs = _resolve_spec_scope(is_mono, packages, scope_config, task_pkg, default_pkg)
+
+    output = StringIO()
+
+    output.write("""<session-context>
+You are starting a new session in a Trellis-managed project.
+Read and follow all instructions below carefully.
+</session-context>
+
+""")
+    output.write(FIRST_REPLY_NOTICE)
+    output.write("\n\n")
+
+    # Legacy migration warning
+    legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages)
+    if legacy_warning:
+        output.write(f"<migration-warning>\n{legacy_warning}\n</migration-warning>\n\n")
+
+    output.write("<current-state>\n")
+    context_script = trellis_dir / "scripts" / "get_context.py"
+    output.write(run_script(context_script))
+    output.write("\n</current-state>\n\n")
+
+    output.write("<workflow>\n")
+    output.write(_build_workflow_overview(trellis_dir / "workflow.md"))
+    output.write("\n</workflow>\n\n")
+
+    output.write("<guidelines>\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"
+        "- For agent-capable platforms, do NOT edit code directly in the main "
+        "session; dispatch `trellis-implement` and `trellis-check` so JSONL "
+        "context is loaded by the sub-agents.\n\n"
+    )
+
+    # guides/ is cross-package thinking — always include inline (small, 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 spec indexes — paths only (main agent reads on demand;
+    # sub-agents get their specific specs via jsonl injection)
+    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":
+                continue  # already inlined above
+
+            index_file = sub / "index.md"
+            if index_file.is_file():
+                # Flat spec dir (single-repo layer like spec/backend/)
+                paths.append(f".trellis/spec/{sub.name}/index.md")
+            else:
+                # Nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
+                # Apply scope filter
+                if allowed_pkgs is not None and sub.name not in allowed_pkgs:
+                    continue
+                for nested in sorted(sub.iterdir()):
+                    if not nested.is_dir():
+                        continue
+                    nested_index = nested / "index.md"
+                    if nested_index.is_file():
+                        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")
+
+    # Check task status and inject structured tag
+    task_status = _get_task_status(trellis_dir)
+    output.write(f"<task-status>\n{task_status}\n</task-status>\n\n")
+
+    output.write("""<ready>
+Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
+</ready>""")
+
+    result = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": output.getvalue(),
+        }
+    }
+
+    # Output JSON - stdout is already configured for UTF-8
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+
+
+if __name__ == "__main__":
+    main()

.claude/hooks/statusline.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Trellis StatusLine — project-level status display for Claude Code.
+
+Reads Claude Code session JSON from stdin + Trellis task data from filesystem.
+Outputs 1-2 lines:
+  With active task:  [P1] Task title (status)  +  info line
+  Without task:      info line only
+Info line: model · ctx% · branch · duration · developer · tasks · rate limits
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# Fix: Windows Python defaults to GBK encoding, which corrupts UTF-8
+# characters like the middle dot (·). Wrap stdout/stderr with UTF-8.
+if sys.platform == "win32":
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8", errors="replace")
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (FileNotFoundError, PermissionError, OSError):
+        return ""
+
+
+def _read_json(path: Path) -> dict:
+    text = _read_text(path)
+    if not text:
+        return {}
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+def _normalize_task_ref(task_ref: str) -> str:
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith("tasks/"):
+        return f".trellis/{normalized}"
+
+    return normalized
+
+
+def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
+    normalized = _normalize_task_ref(task_ref)
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+    if normalized.startswith(".trellis/"):
+        return trellis_dir.parent / path_obj
+    return trellis_dir / "tasks" / path_obj
+
+
+def _find_trellis_dir() -> Path | None:
+    """Walk up from cwd to find .trellis/ directory."""
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        candidate = parent / ".trellis"
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def _get_current_task(trellis_dir: Path) -> dict | None:
+    """Load current task info. Returns dict with title/status/priority or None."""
+    task_ref = _normalize_task_ref(_read_text(trellis_dir / ".current-task"))
+    if not task_ref:
+        return None
+
+    # Resolve task directory
+    task_path = _resolve_task_dir(trellis_dir, task_ref)
+    task_data = _read_json(task_path / "task.json")
+    if not task_data:
+        return None
+
+    return {
+        "title": task_data.get("title") or task_data.get("name") or "unknown",
+        "status": task_data.get("status", "unknown"),
+        "priority": task_data.get("priority", "P2"),
+    }
+
+
+def _count_active_tasks(trellis_dir: Path) -> int:
+    """Count non-archived task directories with valid task.json."""
+    tasks_dir = trellis_dir / "tasks"
+    if not tasks_dir.is_dir():
+        return 0
+    count = 0
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name != "archive" and (d / "task.json").is_file():
+            count += 1
+    return count
+
+
+def _get_developer(trellis_dir: Path) -> str:
+    content = _read_text(trellis_dir / ".developer")
+    if not content:
+        return "unknown"
+    for line in content.splitlines():
+        if line.startswith("name="):
+            return line[5:].strip()
+    return content.splitlines()[0].strip() or "unknown"
+
+
+def _get_git_branch() -> str:
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, timeout=3,
+        )
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+
+def _format_ctx_size(size: int) -> str:
+    if size >= 1_000_000:
+        return f"{size // 1_000_000}M"
+    if size >= 1_000:
+        return f"{size // 1_000}K"
+    return str(size)
+
+
+def _format_duration(ms: int) -> str:
+    secs = ms // 1000
+    hours, remainder = divmod(secs, 3600)
+    mins = remainder // 60
+    if hours > 0:
+        return f"{hours}h{mins}m"
+    return f"{mins}m"
+
+
+def main() -> None:
+    # Read Claude Code session JSON from stdin
+    try:
+        cc_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        cc_data = {}
+
+    trellis_dir = _find_trellis_dir()
+    SEP = " \033[90m·\033[0m "
+
+    # --- Trellis data ---
+    task = _get_current_task(trellis_dir) if trellis_dir else None
+    dev = _get_developer(trellis_dir) if trellis_dir else ""
+    task_count = _count_active_tasks(trellis_dir) if trellis_dir else 0
+
+    # --- CC session data ---
+    model = cc_data.get("model", {}).get("display_name", "?")
+    ctx_pct = int(cc_data.get("context_window", {}).get("used_percentage") or 0)
+    ctx_size = _format_ctx_size(cc_data.get("context_window", {}).get("context_window_size") or 0)
+    duration = _format_duration(cc_data.get("cost", {}).get("total_duration_ms") or 0)
+    branch = _get_git_branch()
+
+    # Avoid "Opus 4.6 (1M context) (1M)"
+    if re.search(r"\d+[KMG]\b", model, re.IGNORECASE):
+        model_label = model
+    else:
+        model_label = f"{model} ({ctx_size})"
+
+    # Context % with color
+    if ctx_pct >= 90:
+        ctx_color = "\033[31m"
+    elif ctx_pct >= 70:
+        ctx_color = "\033[33m"
+    else:
+        ctx_color = "\033[32m"
+
+    # Build info line: model · ctx · branch · duration · dev · tasks [· rate limits]
+    parts = [
+        model_label,
+        f"ctx {ctx_color}{ctx_pct}%\033[0m",
+    ]
+    if branch:
+        parts.append(f"\033[35m{branch}\033[0m")
+    parts.append(duration)
+    if dev:
+        parts.append(f"\033[32m{dev}\033[0m")
+    if task_count:
+        parts.append(f"{task_count} task(s)")
+
+    five_hr = cc_data.get("rate_limits", {}).get("five_hour", {}).get("used_percentage")
+    if five_hr is not None:
+        parts.append(f"5h {int(five_hr)}%")
+    seven_day = cc_data.get("rate_limits", {}).get("seven_day", {}).get("used_percentage")
+    if seven_day is not None:
+        parts.append(f"7d {int(seven_day)}%")
+
+    info_line = SEP.join(parts)
+
+    # Output: task line (only if active) + info line
+    if task:
+        print(f"\033[36m[{task['priority']}]\033[0m {task['title']} \033[33m({task['status']})\033[0m")
+    print(info_line)
+
+
+if __name__ == "__main__":
+    main()

.claude/settings.json

@@ -0,0 +1,77 @@
+{
+  "env": {
+    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1"
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "python3 .claude/hooks/statusline.py"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/session-start.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/inject-subagent-context.py",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/inject-subagent-context.py",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 .claude/hooks/inject-workflow-state.py",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  },
+  "enabledPlugins": {}
+}

.claude/skills/trellis-before-dev/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: trellis-before-dev
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
+---
+
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+2. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+5. **Always read shared guides**:
+   ```bash
+   cat .trellis/spec/guides/index.md
+   ```
+
+6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

.claude/skills/trellis-brainstorm/SKILL.md

@@ -0,0 +1,535 @@
+---
+name: trellis-brainstorm
+description: "Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task."
+---
+
+# Brainstorm - Requirements Discovery (AI Coding Enhanced)
+
+Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
+
+* **Task-first** (capture ideas immediately)
+* **Action-before-asking** (reduce low-value questions)
+* **Research-first** for technical choices (avoid asking users to invent options)
+* **Diverge → Converge** (expand thinking, then lock MVP)
+
+---
+
+## When to Use
+
+Triggered from /trellis:start when the user describes a development task, especially when:
+
+* requirements are unclear or evolving
+* there are multiple valid implementation paths
+* trade-offs matter (UX, reliability, maintainability, cost, performance)
+* the user might not know the best options up front
+
+---
+
+## Core Principles (Non-negotiable)
+
+1. **Task-first (capture early)**
+   Always ensure a task exists at the start so the user's ideas are recorded immediately.
+
+2. **Action before asking**
+   If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
+
+3. **One question per message**
+   Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
+
+4. **Prefer concrete options**
+   For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
+
+5. **Research-first for technical choices**
+   If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
+
+6. **Diverge → Converge**
+   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
+
+7. **No meta questions**
+   Do not ask "should I search?" or "can you paste the code so I can continue?"
+   If you need information: search/inspect. If blocked: ask the minimal blocking question.
+
+---
+
+## Step 0: Ensure Task Exists (ALWAYS)
+
+Before any Q&A, ensure a task exists. If none exists, create one immediately.
+
+* Use a **temporary working title** derived from the user's message.
+* It's OK if the title is imperfect — refine later in PRD.
+
+```bash
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
+```
+
+Create/seed `prd.md` immediately with what you know:
+
+```markdown
+# brainstorm: <short goal>
+
+## Goal
+
+<one paragraph: what + why>
+
+## What I already know
+
+* <facts from user message>
+* <facts discovered from repo/docs>
+
+## Assumptions (temporary)
+
+* <assumptions to validate>
+
+## Open Questions
+
+* <ONLY Blocking / Preference questions; keep list short>
+
+## Requirements (evolving)
+
+* <start with what is known>
+
+## Acceptance Criteria (evolving)
+
+* [ ] <testable criterion>
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated (unit/integration where appropriate)
+* Lint / typecheck / CI green
+* Docs/notes updated if behavior changes
+* Rollout/rollback considered if risky
+
+## Out of Scope (explicit)
+
+* <what we will not do in this task>
+
+## Technical Notes
+
+* <files inspected, constraints, links, references>
+* <research notes summary if applicable>
+```
+
+---
+
+## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)
+
+Before asking questions like "what does the code look like?", gather context yourself:
+
+### Repo inspection checklist
+
+* Identify likely modules/files impacted
+* Locate existing patterns (similar features, conventions, error handling style)
+* Check configs, scripts, existing command definitions
+* Note any constraints (runtime, dependency policy, build tooling)
+
+### Documentation checklist
+
+* Look for existing PRDs/specs/templates
+* Look for command usage examples, README, ADRs if any
+
+Write findings into PRD:
+
+* Add to `What I already know`
+* Add constraints/links to `Technical Notes`
+
+---
+
+## Step 2: Classify Complexity (still useful, not gating task creation)
+
+| Complexity   | Criteria                                               | Action                                      |
+| ------------ | ------------------------------------------------------ | ------------------------------------------- |
+| **Trivial**  | Single-line fix, typo, obvious change                  | Skip brainstorm, implement directly         |
+| **Simple**   | Clear goal, 1–2 files, scope well-defined              | Ask 1 confirm question, then implement      |
+| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2–3 high-value questions) |
+| **Complex**  | Vague goal, architectural choices, multiple approaches | Full brainstorm                             |
+
+> Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
+
+---
+
+## Step 3: Question Gate (Ask ONLY high-value questions)
+
+Before asking ANY question, run the following gate:
+
+### Gate A — Can I derive this without the user?
+
+If answer is available via:
+
+* repo inspection (code/config)
+* docs/specs/conventions
+* quick market/OSS research
+
+→ **Do not ask.** Fetch it, summarize, update PRD.
+
+### Gate B — Is this a meta/lazy question?
+
+Examples:
+
+* "Should I search?"
+* "Can you paste the code so I can proceed?"
+* "What does the code look like?" (when repo is available)
+
+→ **Do not ask.** Take action.
+
+### Gate C — What type of question is it?
+
+* **Blocking**: cannot proceed without user input
+* **Preference**: multiple valid choices, depends on product/UX/risk preference
+* **Derivable**: should be answered by inspection/research
+
+→ Only ask **Blocking** or **Preference**.
+
+---
+
+## Step 4: Research-first Mode (Mandatory for technical choices)
+
+### Trigger conditions (any → research-first)
+
+* The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
+* The user asks for "best practice", "how others do it", "recommendation"
+* The user can't reasonably enumerate options
+
+### Delegate to `trellis-research` sub-agent (don't research inline)
+
+For each research topic, **spawn a `trellis-research` sub-agent via the Task tool** — don't do WebFetch / WebSearch / `gh api` inline in the main conversation.
+
+Why:
+- The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
+- It persists findings to `{TASK_DIR}/research/<topic>.md` (the contract — see `workflow.md` Phase 1.2)
+- It returns only `{file path, one-line summary}` to the main agent
+- Independent topics can be **parallelized** — spawn multiple sub-agents in one tool call
+
+Agent type: `trellis-research`
+Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
+
+❌ Bad (what you must NOT do):
+```
+Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
+          → WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
+          → Write(research/topic.md)
+```
+→ Pollutes main context with raw HTML/JSON, burns tokens.
+
+✅ Good:
+```
+Main agent: Task(subagent_type="trellis-research",
+                 prompt="Research topic A; persist to research/topic-a.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic B; persist to research/topic-b.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic C; persist to research/topic-c.md")
+→ Reads research/topic-{a,b,c}.md after they finish.
+```
+
+### Research steps (to pass into each sub-agent prompt)
+
+Each `trellis-research` sub-agent should:
+
+1. Identify 2–4 comparable tools/patterns for its topic
+2. Summarize common conventions and why they exist
+3. Map conventions onto our repo constraints
+4. Write findings to `{TASK_DIR}/research/<topic>.md`
+
+Main agent then reads the persisted files and produces **2–3 feasible approaches** in PRD.
+
+### Research output format (PRD)
+
+The PRD itself should only reference the persisted research files, not duplicate their content. Add a `## Research References` section pointing at `research/*.md`.
+
+Optionally, add a convergence section with feasible approaches derived from the research:
+
+```markdown
+## Research References
+
+* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
+* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
+
+## Research Notes
+
+### What similar tools do
+
+* ...
+* ...
+
+### Constraints from our repo/project
+
+* ...
+
+### Feasible approaches here
+
+**Approach A: <name>** (Recommended)
+
+* How it works:
+* Pros:
+* Cons:
+
+**Approach B: <name>**
+
+* How it works:
+* Pros:
+* Cons:
+
+**Approach C: <name>** (optional)
+
+* ...
+```
+
+Then ask **one** preference question:
+
+* "Which approach do you prefer: A / B / C (or other)?"
+
+---
+
+## Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding
+
+After you can summarize the goal, proactively broaden thinking before converging.
+
+### Expansion categories (keep to 1–2 bullets each)
+
+1. **Future evolution**
+
+   * What might this feature become in 1–3 months?
+   * What extension points are worth preserving now?
+
+2. **Related scenarios**
+
+   * What adjacent commands/flows should remain consistent with this?
+   * Are there parity expectations (create vs update, import vs export, etc.)?
+
+3. **Failure & edge cases**
+
+   * Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
+   * Input validation, security boundaries, permission checks
+
+### Expansion message template (to user)
+
+```markdown
+I understand you want to implement: <current goal>.
+
+Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
+
+1. Future evolution: <1–2 bullets>
+2. Related scenarios: <1–2 bullets>
+3. Failure/edge cases: <1–2 bullets>
+
+For this MVP, which would you like to include (or none)?
+
+1. Current requirement only (minimal viable)
+2. Add <X> (reserve for future extension)
+3. Add <Y> (improve robustness/consistency)
+4. Other: describe your preference
+```
+
+Then update PRD:
+
+* What's in MVP → `Requirements`
+* What's excluded → `Out of Scope`
+
+---
+
+## Step 6: Q&A Loop (CONVERGE)
+
+### Rules
+
+* One question per message
+* Prefer multiple-choice when possible
+* After each user answer:
+
+  * Update PRD immediately
+  * Move answered items from `Open Questions` → `Requirements`
+  * Update `Acceptance Criteria` with testable checkboxes
+  * Clarify `Out of Scope`
+
+### Question priority (recommended)
+
+1. **MVP scope boundary** (what is included/excluded)
+2. **Preference decisions** (after presenting concrete options)
+3. **Failure/edge behavior** (only for MVP-critical paths)
+4. **Success metrics & Acceptance Criteria** (what proves it works)
+
+### Preferred question format (multiple choice)
+
+```markdown
+For <topic>, which approach do you prefer?
+
+1. **Option A** — <what it means + trade-off>
+2. **Option B** — <what it means + trade-off>
+3. **Option C** — <what it means + trade-off>
+4. **Other** — describe your preference
+```
+
+---
+
+## Step 7: Propose Approaches + Record Decisions (Complex tasks)
+
+After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
+
+```markdown
+Based on current information, here are 2–3 feasible approaches:
+
+**Approach A: <name>** (Recommended)
+
+* How:
+* Pros:
+* Cons:
+
+**Approach B: <name>**
+
+* How:
+* Pros:
+* Cons:
+
+Which direction do you prefer?
+```
+
+Record the outcome in PRD as an ADR-lite section:
+
+```markdown
+## Decision (ADR-lite)
+
+**Context**: Why this decision was needed
+**Decision**: Which approach was chosen
+**Consequences**: Trade-offs, risks, potential future improvements
+```
+
+---
+
+## Step 8: Final Confirmation + Implementation Plan
+
+When open questions are resolved, confirm complete requirements with a structured summary:
+
+### Final confirmation format
+
+```markdown
+Here's my understanding of the complete requirements:
+
+**Goal**: <one sentence>
+
+**Requirements**:
+
+* ...
+* ...
+
+**Acceptance Criteria**:
+
+* [ ] ...
+* [ ] ...
+
+**Definition of Done**:
+
+* ...
+
+**Out of Scope**:
+
+* ...
+
+**Technical Approach**:
+<brief summary + key decisions>
+
+**Implementation Plan (small PRs)**:
+
+* PR1: <scaffolding + tests + minimal plumbing>
+* PR2: <core behavior>
+* PR3: <edge cases + docs + cleanup>
+
+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)
+
+`prd.md` should converge to:
+
+```markdown
+# <Task Title>
+
+## Goal
+
+<why + what>
+
+## Requirements
+
+* ...
+
+## Acceptance Criteria
+
+* [ ] ...
+
+## Definition of Done
+
+* ...
+
+## Technical Approach
+
+<key design + decisions>
+
+## Decision (ADR-lite)
+
+Context / Decision / Consequences
+
+## Out of Scope
+
+* ...
+
+## Technical Notes
+
+<constraints, references, files, research notes>
+```
+
+---
+
+## Anti-Patterns (Hard Avoid)
+
+* Asking user for code/context that can be derived from repo
+* Asking user to choose an approach before presenting concrete options
+* Meta questions about whether to research
+* Staying narrowly on the initial request without considering evolution/edges
+* Letting brainstorming drift without updating PRD
+
+---
+
+## Integration with Start Workflow
+
+After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
+
+```text
+Brainstorm
+  Step 0: Create task directory + seed PRD
+  Step 1–7: Discover requirements, research, converge
+  Step 8: Final confirmation → user approves
+  ↓
+Task Workflow Phase 2 (Prepare for Implementation)
+  Code-Spec Depth Check (if applicable)
+  → Research codebase (based on confirmed PRD)
+  → Configure code-spec context (jsonl files)
+  → Activate task
+  ↓
+Task Workflow Phase 3 (Execute)
+  Implement → Check → Complete
+```
+
+The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
+
+---
+
+## Related Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `/trellis:start` | Entry point that triggers brainstorm |
+| `/trellis:finish-work` | After implementation is complete |
+| `/trellis:update-spec` | If new patterns emerge during work |

.claude/skills/trellis-break-loop/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: trellis-break-loop
+description: "Deep bug analysis to break the fix-forget-repeat cycle. Analyzes root cause category, why fixes failed, prevention mechanisms, and captures knowledge into specs. Use after fixing a bug to prevent the same class of bugs."
+---
+
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this 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** | Strict type checking, no escape hatches | 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/spec/guides/` thinking guides
+- [ ] Update relevant `.trellis/spec/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check guidelines 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.
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+
+2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+
+3. **Commit the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**

.claude/skills/trellis-check/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: trellis-check
+description: "Comprehensive quality verification: spec compliance, lint, type-check, tests, cross-layer data flow, code reuse, and consistency checks. Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions."
+---
+
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Applicable Specs
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist
+
+### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+### Test Coverage
+
+- [ ] New function → unit test added?
+- [ ] Bug fix → regression test added?
+- [ ] Changed behavior → existing tests updated?
+
+### Spec Sync
+
+- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report violations found and fix them directly. Re-run project checks after fixes.

.claude/skills/trellis-update-spec/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: trellis-update-spec
+description: "Captures executable contracts and coding conventions into .trellis/spec/ documents. Use when learning something valuable from debugging, implementing, or discussion that should be preserved for future sessions."
+---
+
+# Update Code-Spec - Capture Executable Contracts
+
+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
+
+---
+
+## Code-Spec First Rule (CRITICAL)
+
+In this project, "spec" for implementation work means **code-spec**:
+- Executable contracts (not principle-only text)
+- Concrete signatures, payload fields, env keys, and boundary behavior
+- Testable validation/error behavior
+
+If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+1. Scope / Trigger
+2. Signatures (command/API/DB)
+3. Contracts (request/response/env)
+4. Validation & Error Matrix
+5. Good/Base/Bad Cases
+6. Tests Required (with assertion points)
+7. Wrong vs Correct (at least one pair)
+
+---
+
+## When to Update Code-Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **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.
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── <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!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Code-Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **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 a spec layer directory
+- "This is **what to consider** before writing" → Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "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.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Code-Spec
+
+Before editing, read the current code-spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Contracts**: Add signatures, payload fields, and error behavior
+4. **Show Code**: Add code snippets for key patterns
+5. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the code-spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Mandatory Template for Infra/Cross-Layer Work
+
+```markdown
+## Scenario: <name>
+
+### 1. Scope / Trigger
+- Trigger: <why this requires code-spec depth>
+
+### 2. Signatures
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 7. Wrong vs Correct
+#### Wrong
+...
+#### Correct
+...
+```
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works → Yes, update spec
+   - To maintain or extend the feature → Yes, update spec
+   - To avoid repeating mistakes → Yes, update spec
+   - Purely one-off implementation detail → Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your code-spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Did you include executable signatures/contracts?
+- [ ] Did you include validation and error matrix?
+- [ ] Did you include Good/Base/Bad cases?
+- [ ] Did you include required tests with assertion points?
+- [ ] Is it in the right code-spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → /trellis:update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis: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
+- `/trellis:finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails

.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.
+```

.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

.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)

.cursor/commands/trellis-continue.md

@@ -0,0 +1,51 @@
+# Continue Current Task
+
+Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
+
+---
+
+## Step 1: Load Current Context
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+Confirms: current task, git state, recent commits.
+
+## Step 2: Load the Phase Index
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode phase
+```
+
+Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+
+## Step 3: Decide Where You Are
+
+Compare the task's `prd.md` + recent activity against the Phase Index:
+
+- No `prd.md` yet, or requirements unclear → **Phase 1: Plan** (start at step 1.0/1.1)
+- `prd.md` exists + context configured, but code not written → **Phase 2: Execute** (step 2.1)
+- Code written, pending final quality gate → **Phase 3: Finish** (step 3.1)
+
+Phase rules (full detail in `.trellis/workflow.md`):
+
+1. Run steps **in order** within a phase — `[required]` steps must not be skipped
+2. `[once]` steps are already done if the output exists (e.g., `prd.md` for 1.1; `implement.jsonl` with curated entries for 1.3) — skip them
+3. You may go back to an earlier phase if discoveries require it
+
+## Step 4: Load the Specific Step
+
+Once you know which step to resume at:
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform cursor
+```
+
+Follow the loaded instructions. After each `[required]` step completes, move to the next.
+
+---
+
+## Reference
+
+Full workflow, skill routing table, and the DO-NOT-skip table live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.

.cursor/commands/trellis-finish-work.md

@@ -0,0 +1,32 @@
+# Finish Work
+
+Wrap up the current session.
+
+## Step 1: Quality Gate
+
+`trellis-check` should have already run in Phase 3. If not, trigger it now and do not proceed until lint, type-check, tests, and spec compliance pass.
+
+## Step 2: Remind User to Commit
+
+If there are uncommitted changes:
+
+> "Please review the changes and commit when ready."
+
+Do NOT run `git commit` — the human commits after testing.
+
+## Step 3: Record Session (after commit)
+
+Archive finished tasks (judge by work status, not the `status` field):
+
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
+
+Append a session entry (auto-handles journal rotation, line count, index update):
+
+```bash
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
+```

.cursor/hooks.json

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

.cursor/hooks/inject-subagent-context.py

@@ -0,0 +1,641 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Multi-Platform Sub-Agent Context Injection Hook
+
+Injects task-specific context when sub-agents (implement, check, research) are spawned.
+
+Core Design Philosophy:
+- Hook is responsible for injecting all context, subagent works autonomously with complete info
+- Each agent has a dedicated jsonl file defining its context
+- No resume needed, no segmentation, behavior controlled by code not prompt
+
+Trigger: PreToolUse (before Task tool call)
+
+Context Source: .trellis/.current-task points to task directory
+- implement.jsonl - Implement agent dedicated context
+- check.jsonl     - Check agent dedicated context
+- prd.md          - Requirements document
+- info.md         - Technical design
+- codex-review-output.txt - Code Review results
+"""
+from __future__ import annotations
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+# This fixes UnicodeEncodeError when outputting non-ASCII characters
+if sys.platform.startswith("win"):
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+
+# =============================================================================
+# Path Constants (change here to rename directories)
+# =============================================================================
+
+DIR_WORKFLOW = ".trellis"
+DIR_SPEC = "spec"
+FILE_CURRENT_TASK = ".current-task"
+FILE_TASK_JSON = "task.json"
+
+# =============================================================================
+# Subagent Constants (change here to rename subagent types)
+# =============================================================================
+
+AGENT_IMPLEMENT = "trellis-implement"
+AGENT_CHECK = "trellis-check"
+AGENT_RESEARCH = "trellis-research"
+
+# Agents that require a task directory
+AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK)
+# All supported agents
+AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_RESEARCH)
+
+
+def find_repo_root(start_path: str) -> str | None:
+    """
+    Find git repo root from start_path upwards
+
+    Returns:
+        Repo root path, or None if not found
+    """
+    current = Path(start_path).resolve()
+    while current != current.parent:
+        if (current / ".git").exists():
+            return str(current)
+        current = current.parent
+    return None
+
+
+def get_current_task(repo_root: str) -> str | None:
+    """
+    Read current task directory path from .trellis/.current-task
+
+    Returns:
+        Task directory relative path (relative to repo_root)
+        None if not set
+    """
+    current_task_file = os.path.join(repo_root, DIR_WORKFLOW, FILE_CURRENT_TASK)
+    if not os.path.exists(current_task_file):
+        return None
+
+    try:
+        with open(current_task_file, "r", encoding="utf-8") as f:
+            content = f.read().strip()
+            if not content:
+                return None
+            normalized = content.replace("\\", "/")
+            while normalized.startswith("./"):
+                normalized = normalized[2:]
+            if normalized.startswith("tasks/"):
+                normalized = f".trellis/{normalized}"
+            return normalized
+    except Exception:
+        return None
+
+
+def read_file_content(base_path: str, file_path: str) -> str | None:
+    """Read file content, return None if file doesn't exist"""
+    full_path = os.path.join(base_path, file_path)
+    if os.path.exists(full_path) and os.path.isfile(full_path):
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except Exception:
+            return None
+    return None
+
+
+def read_directory_contents(
+    base_path: str, dir_path: str, max_files: int = 20
+) -> list[tuple[str, str]]:
+    """
+    Read all .md files in a directory
+
+    Args:
+        base_path: Base path (usually repo_root)
+        dir_path: Directory relative path
+        max_files: Max files to read (prevent huge directories)
+
+    Returns:
+        [(file_path, content), ...]
+    """
+    full_path = os.path.join(base_path, dir_path)
+    if not os.path.exists(full_path) or not os.path.isdir(full_path):
+        return []
+
+    results = []
+    try:
+        # Only read .md files, sorted by filename
+        md_files = sorted(
+            [
+                f
+                for f in os.listdir(full_path)
+                if f.endswith(".md") and os.path.isfile(os.path.join(full_path, f))
+            ]
+        )
+
+        for filename in md_files[:max_files]:
+            file_full_path = os.path.join(full_path, filename)
+            relative_path = os.path.join(dir_path, filename)
+            try:
+                with open(file_full_path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    results.append((relative_path, content))
+            except Exception:
+                continue
+    except Exception:
+        pass
+
+    return results
+
+
+def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]:
+    """
+    Read all file/directory contents referenced in jsonl file
+
+    Schema:
+        {"file": "path/to/file.md", "reason": "..."}
+        {"file": "path/to/dir/", "type": "directory", "reason": "..."}
+        {"_example": "..."}          # seed row — skipped (no `file` field)
+
+    Rows without a ``file`` field (e.g. the self-describing seed line written
+    by ``task.py create`` before the agent has curated entries) are skipped
+    silently. If the resulting entry list is empty, a stderr warning is
+    emitted so the operator can debug missing context.
+
+    Returns:
+        [(path, content), ...]
+    """
+    full_path = os.path.join(base_path, jsonl_path)
+    if not os.path.exists(full_path):
+        print(
+            f"[inject-subagent-context] WARN: {jsonl_path} not found — "
+            f"sub-agent will receive only prd.md",
+            file=sys.stderr,
+        )
+        return []
+
+    results = []
+    saw_real_entry = False
+    try:
+        with open(full_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    file_path = item.get("file") or item.get("path")
+                    entry_type = item.get("type", "file")
+
+                    if not file_path:
+                        # Seed / comment row — skip silently
+                        continue
+
+                    saw_real_entry = True
+                    if entry_type == "directory":
+                        # Read all .md files in directory
+                        dir_contents = read_directory_contents(base_path, file_path)
+                        results.extend(dir_contents)
+                    else:
+                        # Read single file
+                        content = read_file_content(base_path, file_path)
+                        if content:
+                            results.append((file_path, content))
+                except json.JSONDecodeError:
+                    continue
+    except Exception:
+        pass
+
+    if not saw_real_entry:
+        print(
+            f"[inject-subagent-context] WARN: {jsonl_path} has no curated "
+            f"entries (only seed / empty) — sub-agent will receive only "
+            f"prd.md. See workflow.md Phase 1.3 for curation guidance.",
+            file=sys.stderr,
+        )
+
+    return results
+
+
+
+
+def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
+    """
+    Get context from {agent_type}.jsonl for the specified agent.
+    Only reads implement.jsonl or check.jsonl (the two JSONL files the task system creates).
+    """
+    context_parts = []
+
+    agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
+    for file_path, content in read_jsonl_entries(repo_root, agent_jsonl):
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    return "\n\n".join(context_parts)
+
+
+def get_implement_context(repo_root: str, task_dir: str) -> str:
+    """
+    Complete context for Implement Agent
+
+    Read order:
+    1. All files in implement.jsonl (dev specs)
+    2. prd.md (requirements)
+    3. info.md (technical design)
+    """
+    context_parts = []
+
+    # 1. Read implement.jsonl
+    base_context = get_agent_context(repo_root, task_dir, "implement")
+    if base_context:
+        context_parts.append(base_context)
+
+    # 2. Requirements document
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    # 3. Technical design
+    info_content = read_file_content(repo_root, f"{task_dir}/info.md")
+    if info_content:
+        context_parts.append(
+            f"=== {task_dir}/info.md (Technical Design) ===\n{info_content}"
+        )
+
+    return "\n\n".join(context_parts)
+
+
+def get_check_context(repo_root: str, task_dir: str) -> str:
+    """
+    Context for Check Agent: check.jsonl + prd.md
+    """
+    context_parts = []
+
+    for file_path, content in read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl"):
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    return "\n\n".join(context_parts)
+
+
+def get_finish_context(repo_root: str, task_dir: str) -> str:
+    """
+    Context for Finish phase: reuses check.jsonl + prd.md
+    (Finish is a final check, same context source.)
+    """
+    return get_check_context(repo_root, task_dir)
+
+
+
+def build_implement_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Implement"""
+    return f"""# Implement Agent Task
+
+You are the Implement Agent in the Multi-Agent Pipeline.
+
+## Your Context
+
+All the information you need has been prepared for you:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand specs** - All dev specs are injected above, understand them
+2. **Understand requirements** - Read requirements document and technical design
+3. **Implement feature** - Implement following specs and design
+4. **Self-check** - Ensure code quality against check specs
+
+## Important Constraints
+
+- Do NOT execute git commit, only code modifications
+- Follow all dev specs injected above
+- Report list of modified/created files when done"""
+
+
+def build_check_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Check"""
+    return f"""# Check Agent Task
+
+You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker).
+
+## Your Context
+
+All check specs and dev specs you need:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes
+2. **Check against specs** - Check item by item against specs above
+3. **Self-fix** - Fix issues directly, don't just report
+4. **Run verification** - Run project's lint and typecheck commands
+
+## Important Constraints
+
+- Fix issues yourself, don't just report
+- Must execute complete checklist in check specs
+- Pay special attention to impact radius analysis (L1-L5)"""
+
+
+def build_finish_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Finish (final check before PR)"""
+    return f"""# Finish Agent Task
+
+You are performing the final check before creating a PR.
+
+## Your Context
+
+Finish checklist and requirements:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Review changes** - Run `git diff --name-only` to see all changed files
+2. **Verify requirements** - Check each requirement in prd.md is implemented
+3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions
+   - If new pattern/convention found: read target spec file → update it → update index.md if needed
+   - If infra/cross-layer change: follow the 7-section mandatory template from update-spec.md
+   - If pure code fix with no new patterns: skip this step
+4. **Run final checks** - Execute lint and typecheck
+5. **Confirm ready** - Ensure code is ready for PR
+
+## Important Constraints
+
+- You MAY update spec files when gaps are detected (use update-spec.md as guide)
+- MUST read the target spec file BEFORE editing (avoid duplicating existing content)
+- Do NOT update specs for trivial changes (typos, formatting, obvious fixes)
+- If critical CODE issues found, report them clearly (fix specs, not code)
+- Verify all acceptance criteria in prd.md are met"""
+
+
+
+def get_research_context(repo_root: str, task_dir: str | None) -> str:
+    """
+    Context for Research Agent — project structure overview for spec directories.
+
+    `task_dir` kept for signature parity with get_implement_context / get_check_context
+    so the dispatcher can call them uniformly.
+    """
+    _ = task_dir
+    context_parts = []
+
+    # 1. Project structure overview (dynamically discover spec directories)
+    spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
+    spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC
+
+    # Build spec tree dynamically
+    tree_lines = [f"{spec_path}/"]
+    if spec_root.is_dir():
+        pkg_dirs = sorted(d for d in spec_root.iterdir() if d.is_dir())
+        for i, pkg_dir in enumerate(pkg_dirs):
+            is_last = i == len(pkg_dirs) - 1
+            prefix = "└── " if is_last else "├── "
+            layers = sorted(d.name for d in pkg_dir.iterdir() if d.is_dir())
+            layer_info = f" ({', '.join(layers)})" if layers else ""
+            tree_lines.append(f"{prefix}{pkg_dir.name}/{layer_info}")
+
+    spec_tree = "\n".join(tree_lines)
+
+    project_structure = f"""## Project Spec Directory Structure
+
+```
+{spec_tree}
+```
+
+To get structured package info, run: `python3 ./{DIR_WORKFLOW}/scripts/get_context.py --mode packages`
+
+## Search Tips
+
+- Spec files: `{spec_path}/**/*.md`
+- Code search: Use Glob and Grep tools
+- Tech solutions: Use mcp__exa__web_search_exa or mcp__exa__get_code_context_exa"""
+
+    context_parts.append(project_structure)
+
+    return "\n\n".join(context_parts)
+
+
+def build_research_prompt(original_prompt: str, context: str) -> str:
+    """Build complete prompt for Research"""
+    return f"""# Research Agent Task
+
+You are the Research Agent in the Multi-Agent Pipeline (search researcher).
+
+## Core Principle
+
+**You do one thing: find and explain information.**
+
+You are a documenter, not a reviewer.
+
+## Project Info
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand query** - Determine search type (internal/external) and scope
+2. **Plan search** - List search steps for complex queries
+3. **Execute search** - Execute multiple independent searches in parallel
+4. **Organize results** - Output structured report
+
+## Search Tools
+
+| Tool | Purpose |
+|------|---------|
+| Glob | Search by filename pattern |
+| Grep | Search by content |
+| Read | Read file content |
+| mcp__exa__web_search_exa | External web search |
+| mcp__exa__get_code_context_exa | External code/doc search |
+
+## Strict Boundaries
+
+**Only allowed**: Describe what exists, where it is, how it works
+
+**Forbidden** (unless explicitly asked):
+- Suggest improvements
+- Criticize implementation
+- Recommend refactoring
+- Modify any files
+
+## Report Format
+
+Provide structured search results including:
+- List of files found (with paths)
+- Code pattern analysis (if applicable)
+- Related spec documents
+- External references (if any)"""
+
+
+def _parse_hook_input(input_data: dict) -> tuple[str, str, dict]:
+    """Parse hook input across different platform formats.
+
+    Returns (subagent_type, original_prompt, tool_input).
+    Handles:
+    - Claude Code / Qoder / CodeBuddy / Droid: tool_name=Task|Agent, tool_input.subagent_type
+    - Cursor: tool_name=Task, tool_input.subagent_type
+    - Copilot CLI: toolName=task (camelCase key, lowercase value)
+    - Gemini CLI: tool_name IS the agent name (BeforeTool matcher already filtered)
+    - Kiro: agentSpawn hook, agent_name field at top level
+    """
+    tool_input = input_data.get("tool_input", {})
+
+    # Standard format: Task/Agent tool with subagent_type
+    tool_name = input_data.get("tool_name", "") or input_data.get("toolName", "")
+    if tool_name.lower() in ("task", "agent"):
+        return (
+            tool_input.get("subagent_type", ""),
+            tool_input.get("prompt", ""),
+            tool_input,
+        )
+
+    # Kiro: agentSpawn hook passes agent_name at top level
+    agent_name = input_data.get("agent_name", "")
+    if agent_name:
+        return agent_name, tool_input.get("prompt", input_data.get("prompt", "")), tool_input
+
+    # Gemini CLI: BeforeTool where tool_name IS the agent name
+    # (matcher already ensured it's one of our agents)
+    if tool_name in AGENTS_ALL:
+        return tool_name, tool_input.get("prompt", ""), tool_input
+
+    # Copilot CLI: toolName field (camelCase), value might be the agent name
+    tool_name_camel = input_data.get("toolName", "")
+    if tool_name_camel in AGENTS_ALL:
+        return tool_name_camel, input_data.get("toolArgs", ""), tool_input
+
+    return "", "", tool_input
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    subagent_type, original_prompt, tool_input = _parse_hook_input(input_data)
+    cwd = input_data.get("cwd", os.getcwd())
+
+    # Only handle subagent types we care about
+    if subagent_type not in AGENTS_ALL:
+        sys.exit(0)
+
+    # Find repo root
+    repo_root = find_repo_root(cwd)
+    if not repo_root:
+        sys.exit(0)
+
+    # Get current task directory (research doesn't require it)
+    task_dir = get_current_task(repo_root)
+
+    # implement/check need task directory
+    if subagent_type in AGENTS_REQUIRE_TASK:
+        if not task_dir:
+            sys.exit(0)
+        # Check if task directory exists
+        task_dir_full = os.path.join(repo_root, task_dir)
+        if not os.path.exists(task_dir_full):
+            sys.exit(0)
+
+    # Check for [finish] marker in prompt (check agent with finish context)
+    is_finish_phase = "[finish]" in original_prompt.lower()
+
+    # Get context and build prompt based on subagent type
+    if subagent_type == AGENT_IMPLEMENT:
+        assert task_dir is not None  # validated above
+        context = get_implement_context(repo_root, task_dir)
+        new_prompt = build_implement_prompt(original_prompt, context)
+    elif subagent_type == AGENT_CHECK:
+        assert task_dir is not None  # validated above
+        if is_finish_phase:
+            # Finish phase: use finish context (lighter, focused on final verification)
+            context = get_finish_context(repo_root, task_dir)
+            new_prompt = build_finish_prompt(original_prompt, context)
+        else:
+            # Regular check phase: use check context (full specs for self-fix loop)
+            context = get_check_context(repo_root, task_dir)
+            new_prompt = build_check_prompt(original_prompt, context)
+    elif subagent_type == AGENT_RESEARCH:
+        # Research can work without task directory
+        context = get_research_context(repo_root, task_dir)
+        new_prompt = build_research_prompt(original_prompt, context)
+    else:
+        sys.exit(0)
+
+    if not context:
+        sys.exit(0)
+
+    # Return updated input — use a multi-format output that covers all platforms.
+    # Most platforms ignore unrecognized fields, so we include multiple formats.
+    # The platform picks whichever fields it understands.
+    updated = {**tool_input, "prompt": new_prompt}
+    output = {
+        # Claude Code / Qoder / CodeBuddy / Droid format
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": updated,
+        },
+        # Cursor format
+        "permission": "allow",
+        "updated_input": updated,
+        # Gemini format
+        "updatedInput": updated,
+    }
+
+    print(json.dumps(output, ensure_ascii=False))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

.cursor/hooks/inject-workflow-state.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Trellis UserPromptSubmit hook: inject per-turn workflow breadcrumb.
+
+Runs on every user prompt. Reads the active task (.trellis/.current-task)
+and emits a short <workflow-state> block reminding the main AI what task
+is active and its expected flow. Breadcrumb text is pulled from
+workflow.md [workflow-state:STATUS] tag blocks (single source of truth
+for users who fork the Trellis workflow), with hardcoded fallbacks so
+the hook never breaks when workflow.md is missing or malformed.
+
+Shared across all hook-capable platforms (Claude, Cursor, Codex, Qoder,
+CodeBuddy, Droid, Gemini, Copilot). Kiro is not wired (no per-turn
+hook entry point). Written to each platform's hooks directory via
+writeSharedHooks() at init time.
+
+Silent exit 0 cases (no output):
+  - No .trellis/ directory found (not a Trellis project)
+  - No .current-task file, or it's empty
+  - task.json malformed or missing status
+
+Unknown status (no tag + no hardcoded fallback) emits a generic
+breadcrumb rather than silent-exiting, so custom statuses surface in
+the UI instead of appearing as "randomly broken".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+# ---------------------------------------------------------------------------
+# CWD-robust Trellis root discovery (fixes hook-path-robustness for this hook)
+# ---------------------------------------------------------------------------
+
+def find_trellis_root(start: Path) -> Optional[Path]:
+    """Walk up from start to find directory containing .trellis/.
+
+    Handles CWD drift: subdirectory launches, monorepo packages, etc.
+    Returns None if no .trellis/ found (silent no-op).
+    """
+    cur = start.resolve()
+    while cur != cur.parent:
+        if (cur / ".trellis").is_dir():
+            return cur
+        cur = cur.parent
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Active task discovery
+# ---------------------------------------------------------------------------
+
+def _normalize_task_ref(task_ref: str) -> str:
+    """Normalize .current-task path ref.
+
+    Accepts:
+    - Absolute paths (left as-is)
+    - Windows-style backslashes (converted to forward slash)
+    - Legacy relative refs like "tasks/foo" (prefixed with .trellis/)
+    """
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+    if normalized.startswith("tasks/"):
+        normalized = f".trellis/{normalized}"
+    return normalized
+
+
+def get_active_task(root: Path) -> Optional[Tuple[str, str]]:
+    """Return (task_id, status) from the current active task, else None.
+
+    Reads .trellis/.current-task (a path relative to root, e.g.
+    ".trellis/tasks/04-17-foo") then that task's task.json.
+    Normalizes backslashes so Windows paths work on Unix and vice versa.
+    """
+    ref_file = root / ".trellis" / ".current-task"
+    if not ref_file.is_file():
+        return None
+    try:
+        raw = ref_file.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    task_ref = _normalize_task_ref(raw)
+    if not task_ref:
+        return None
+
+    path_obj = Path(task_ref)
+    task_dir = path_obj if path_obj.is_absolute() else root / path_obj
+    task_json = task_dir / "task.json"
+    if not task_json.is_file():
+        return None
+    try:
+        data = json.loads(task_json.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+    task_id = data.get("id") or task_dir.name
+    status = data.get("status", "")
+    if not isinstance(status, str) or not status:
+        return None
+    return task_id, status
+
+
+# ---------------------------------------------------------------------------
+# Breadcrumb loading: parse workflow.md, fall back to hardcoded defaults
+# ---------------------------------------------------------------------------
+
+# Supports STATUS values with letters, digits, underscores, hyphens
+# (so "in-review" / "blocked-by-team" work alongside "in_progress").
+_TAG_RE = re.compile(
+    r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n(.*?)\n\s*\[/workflow-state:\1\]",
+    re.DOTALL,
+)
+
+# Hardcoded defaults for built-in Trellis statuses. Used when workflow.md is
+# missing, malformed, or lacks the tag for this status.
+#
+# `no_task` is a pseudo-status emitted when .current-task is missing — it keeps
+# the Next-Action reminder flowing per-turn even without an active task.
+_FALLBACK_BREADCRUMBS = {
+    "no_task": (
+        "No active task.\n"
+        "Trigger words in the user message that REQUIRE creating a task "
+        "(non-negotiable, do NOT self-exempt): 重构 / 抽成 / 独立 / 分发 / "
+        "拆出来 / 搞一个 / 做成 / 接入 / 集成 / refactor / rewrite / extract / "
+        "productize / publish / build X / design Y.\n"
+        "Task is NOT required ONLY if ALL three hold: (a) zero file writes "
+        "this turn, (b) answer fits in one reply with no multi-round plan, "
+        "(c) no research beyond reading 1-2 repo files.\n"
+        "When in doubt: create task. Over-tasking is cheap; under-tasking "
+        "leaks plans and research into main context.\n"
+        "Flow: load `trellis-brainstorm` skill → it creates the task via "
+        "`python3 ./.trellis/scripts/task.py create` and drives requirements Q&A. "
+        "For research-heavy work (tool comparison, docs, cross-platform survey), "
+        "spawn `trellis-research` sub-agents via Task tool — NEVER do 3+ inline "
+        "WebFetch/WebSearch/`gh api` calls in the main conversation."
+    ),
+    "planning": (
+        "Complete prd.md via trellis-brainstorm skill; then run task.py start.\n"
+        "Research belongs in `{task_dir}/research/*.md`, written by "
+        "`trellis-research` sub-agents. Do NOT inline WebFetch/WebSearch in "
+        "main session — PRD only links to research files."
+    ),
+    "in_progress": (
+        "Flow: trellis-implement → trellis-check → trellis-update-spec → finish\n"
+        "Next required action: inspect conversation history + git status, then "
+        "execute the next uncompleted step in that sequence.\n"
+        "For agent-capable platforms, do NOT edit code in the main session; "
+        "dispatch `trellis-implement` for implementation and dispatch "
+        "`trellis-check` before reporting completion."
+    ),
+    "completed": (
+        "User commits changes; then run task.py archive."
+    ),
+}
+
+
+def load_breadcrumbs(root: Path) -> dict[str, str]:
+    """Parse workflow.md for [workflow-state:STATUS] blocks.
+
+    Returns {status: body_text}. Missing tags fall back to hardcoded
+    defaults so the hook always has something to say for built-in
+    statuses. Custom statuses without tags fall to generic breadcrumb
+    downstream (see build_breadcrumb).
+    """
+    result = dict(_FALLBACK_BREADCRUMBS)
+
+    workflow = root / ".trellis" / "workflow.md"
+    if not workflow.is_file():
+        return result
+    try:
+        content = workflow.read_text(encoding="utf-8")
+    except OSError:
+        return result
+
+    for match in _TAG_RE.finditer(content):
+        status = match.group(1)
+        body = match.group(2).strip()
+        if body:
+            result[status] = body
+    return result
+
+
+def build_breadcrumb(
+    task_id: Optional[str], status: str, templates: dict[str, str]
+) -> str:
+    """Build the <workflow-state>...</workflow-state> block.
+
+    - Known status (in templates or fallback) → detailed template body
+    - Unknown status (no tag + no fallback) → generic "refer to workflow.md"
+    - `no_task` pseudo-status (task_id is None) → header omits task info
+    """
+    body = templates.get(status)
+    if body is None:
+        body = "Refer to workflow.md for current step."
+    header = f"Status: {status}" if task_id is None else f"Task: {task_id} ({status})"
+    return f"<workflow-state>\n{header}\n{body}\n</workflow-state>"
+
+
+# ---------------------------------------------------------------------------
+# Entry
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        data = {}
+
+    cwd_str = data.get("cwd") or os.getcwd()
+    cwd = Path(cwd_str)
+
+    root = find_trellis_root(cwd)
+    if root is None:
+        return 0  # not a Trellis project
+
+    templates = load_breadcrumbs(root)
+    task = get_active_task(root)
+    if task is None:
+        # No active task — still emit a breadcrumb nudging AI toward
+        # trellis-brainstorm + task.py create when user describes real work.
+        breadcrumb = build_breadcrumb(None, "no_task", templates)
+    else:
+        breadcrumb = build_breadcrumb(*task, templates=templates)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": breadcrumb,
+        }
+    }
+    print(json.dumps(output))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.cursor/hooks/session-start.py

@@ -0,0 +1,577 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Session Start Hook - Inject structured context
+"""
+from __future__ import annotations
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import json
+import os
+import subprocess
+import sys
+from io import StringIO
+from pathlib import Path
+
+FIRST_REPLY_NOTICE = """<first-reply-notice>
+On the first visible assistant reply in this session, begin with exactly one short Chinese sentence:
+Trellis SessionStart 已注入：workflow、当前任务状态、开发者身份、git 状态、active tasks、spec 索引已加载。
+Then continue directly with the user's request. This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>"""
+
+# IMPORTANT: Force stdout to use UTF-8 on Windows
+# This fixes UnicodeEncodeError when outputting non-ASCII characters
+if sys.platform.startswith("win"):
+    import io as _io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+
+
+
+def _has_curated_jsonl_entry(jsonl_path: Path) -> bool:
+    """Return True iff jsonl has at least one row with a ``file`` field.
+
+    A freshly seeded jsonl only contains a ``{"_example": ...}`` row (no
+    ``file`` key) — that is NOT "ready". Readiness requires at least one
+    curated entry. Matches the contract used by ``inject-subagent-context.py``.
+    """
+    try:
+        for line in jsonl_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(row, dict) and row.get("file"):
+                return True
+    except (OSError, UnicodeDecodeError):
+        return False
+    return False
+
+
+def should_skip_injection() -> bool:
+    """Check if any platform's non-interactive flag is set."""
+    non_interactive_vars = [
+        "CLAUDE_NON_INTERACTIVE",
+        "QODER_NON_INTERACTIVE",
+        "CODEBUDDY_NON_INTERACTIVE",
+        "FACTORY_NON_INTERACTIVE",
+        "CURSOR_NON_INTERACTIVE",
+        "GEMINI_NON_INTERACTIVE",
+        "KIRO_NON_INTERACTIVE",
+        "COPILOT_NON_INTERACTIVE",
+    ]
+    return any(os.environ.get(var) == "1" for var in non_interactive_vars)
+
+
+def read_file(path: Path, fallback: str = "") -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (FileNotFoundError, PermissionError):
+        return fallback
+
+
+def run_script(script_path: Path) -> str:
+    try:
+        if script_path.suffix == ".py":
+            # Add PYTHONIOENCODING to force UTF-8 in subprocess
+            env = os.environ.copy()
+            env["PYTHONIOENCODING"] = "utf-8"
+            cmd = [sys.executable, "-W", "ignore", str(script_path)]
+        else:
+            env = os.environ
+            cmd = [str(script_path)]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            cwd=script_path.parent.parent.parent,
+            env=env,
+        )
+        return result.stdout if result.returncode == 0 else "No context available"
+    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError):
+        return "No context available"
+
+
+def _normalize_task_ref(task_ref: str) -> str:
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith("tasks/"):
+        return f".trellis/{normalized}"
+
+    return normalized
+
+
+def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
+    normalized = _normalize_task_ref(task_ref)
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+    if normalized.startswith(".trellis/"):
+        return trellis_dir.parent / path_obj
+    return trellis_dir / "tasks" / path_obj
+
+
+def _get_task_status(trellis_dir: Path) -> str:
+    """Check current task status and return structured status string with explicit next action.
+
+    Returns a block with three fields:
+    - Status: current state
+    - Task: task identifier (when applicable)
+    - Next-Action: explicit skill/command/tool call the AI should invoke
+    """
+    current_task_file = trellis_dir / ".current-task"
+
+    # Case 1: No active task — waiting for user to describe intent
+    if not current_task_file.is_file() or not current_task_file.read_text(encoding="utf-8").strip():
+        return (
+            "Status: NO ACTIVE TASK\n"
+            "Next-Action: After the user describes their intent, load skill `trellis-brainstorm` "
+            "to clarify requirements and create a task via `python3 ./.trellis/scripts/task.py create`.\n"
+            "Research reminder: for research-heavy tasks (comparing tools, reading external docs, "
+            "cross-platform surveys), spawn `trellis-research` sub-agents via the Task tool — "
+            "they persist findings to `{TASK_DIR}/research/*.md` and keep main context clean. "
+            "Do NOT do 10+ inline WebFetch/WebSearch in the main conversation."
+        )
+
+    task_ref = _normalize_task_ref(current_task_file.read_text(encoding="utf-8").strip())
+
+    # Case 2: Stale pointer — task dir was deleted
+    task_dir = _resolve_task_dir(trellis_dir, task_ref)
+    if not task_dir.is_dir():
+        return (
+            f"Status: STALE POINTER\nTask: {task_ref}\n"
+            f"Next-Action: Run `python3 ./.trellis/scripts/task.py finish` to clear the stale pointer, "
+            "then ask the user what to work on next."
+        )
+
+    # Read task.json
+    task_json_path = task_dir / "task.json"
+    task_data = {}
+    if task_json_path.is_file():
+        try:
+            task_data = json.loads(task_json_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, PermissionError):
+            pass
+
+    task_title = task_data.get("title", task_ref)
+    task_status = task_data.get("status", "unknown")
+
+    # Case 3: Task completed — time to archive
+    if task_status == "completed":
+        return (
+            f"Status: COMPLETED\nTask: {task_title}\n"
+            f"Next-Action: Load skill `trellis-update-spec` to capture learnings, "
+            f"then archive with `python3 ./.trellis/scripts/task.py archive {task_dir.name}`."
+        )
+
+    has_prd = (task_dir / "prd.md").is_file()
+
+    # Case 4: No PRD — still in Plan phase
+    if not has_prd:
+        return (
+            f"Status: PLANNING\nTask: {task_title}\n"
+            "Next-Action: Load skill `trellis-brainstorm` to clarify requirements with the user "
+            "and produce prd.md in the task directory.\n"
+            "Research reminder: when the task needs external research (tool comparison, docs, "
+            "conventions survey), spawn `trellis-research` sub-agents — don't WebFetch/WebSearch "
+            "inline in the main session. Findings go to `{task_dir}/research/*.md`; PRD only links to them."
+        )
+
+    # Case 4b: PRD exists but implement.jsonl has only seed (no curated entries) — Phase 1.3 gate
+    implement_jsonl = task_dir / "implement.jsonl"
+    if implement_jsonl.is_file() and not _has_curated_jsonl_entry(implement_jsonl):
+        return (
+            f"Status: PLANNING (Phase 1.3)\nTask: {task_title}\n"
+            "Next-Action: Curate `implement.jsonl` and `check.jsonl` with the spec + research files "
+            "the Phase 2 sub-agents will need. Only spec paths (`.trellis/spec/**/*.md`) and research "
+            "files (`{TASK_DIR}/research/*.md`) — no code paths. Run "
+            "`python3 ./.trellis/scripts/get_context.py --mode packages` to list available specs, "
+            "then edit the jsonl files or use `python3 ./.trellis/scripts/task.py add-context`. "
+            "See `.trellis/workflow.md` Phase 1.3 for details."
+        )
+
+    # Case 5: PRD + curated jsonl (or agent-less platform with no jsonl) — enter Execute phase
+    return (
+        f"Status: READY\nTask: {task_title}\n"
+        "Next required action: dispatch `trellis-implement` per Phase 2.1. "
+        "For agent-capable platforms, do NOT edit code in the main session. "
+        "After implementation, dispatch `trellis-check` per Phase 2.2 before reporting completion.\n"
+        "Sub-agent roster: `trellis-implement` (writes code), `trellis-check` (verifies + self-fixes), "
+        "`trellis-research` (persists findings to `research/*.md` — use when you'd otherwise do "
+        "multiple WebFetch/WebSearch inline)."
+    )
+
+
+def _load_trellis_config(trellis_dir: Path) -> tuple:
+    """Load Trellis config for session-start decisions.
+
+    Returns:
+        (is_mono, packages_dict, spec_scope, task_pkg, default_pkg)
+    """
+    scripts_dir = trellis_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        from common.config import get_default_package, get_packages, get_spec_scope, is_monorepo  # type: ignore[import-not-found]
+        from common.paths import get_current_task  # type: ignore[import-not-found]
+
+        repo_root = trellis_dir.parent
+        is_mono = is_monorepo(repo_root)
+        packages = get_packages(repo_root) or {}
+        scope = get_spec_scope(repo_root)
+
+        # Get active task's package
+        task_pkg = None
+        current = get_current_task(repo_root)
+        if current:
+            task_json = repo_root / current / "task.json"
+            if task_json.is_file():
+                try:
+                    data = json.loads(task_json.read_text(encoding="utf-8"))
+                    if isinstance(data, dict):
+                        tp = data.get("package")
+                        if isinstance(tp, str) and tp:
+                            task_pkg = tp
+                except (json.JSONDecodeError, OSError):
+                    pass
+
+        default_pkg = get_default_package(repo_root)
+        return is_mono, packages, scope, task_pkg, default_pkg
+    except Exception:
+        return False, {}, None, None, None
+
+
+def _check_legacy_spec(trellis_dir: Path, is_mono: bool, packages: dict) -> str | None:
+    """Check for legacy spec directory structure in monorepo.
+
+    Returns warning message if legacy structure detected, None otherwise.
+    """
+    if not is_mono or not packages:
+        return None
+
+    spec_dir = trellis_dir / "spec"
+    if not spec_dir.is_dir():
+        return None
+
+    # Check for legacy flat spec dirs (spec/backend/, spec/frontend/ with index.md)
+    has_legacy = False
+    for legacy_name in ("backend", "frontend"):
+        legacy_dir = spec_dir / legacy_name
+        if legacy_dir.is_dir() and (legacy_dir / "index.md").is_file():
+            has_legacy = True
+            break
+
+    if not has_legacy:
+        return None
+
+    # Check which packages are missing spec/<pkg>/ directory
+    missing = [
+        name for name in sorted(packages.keys())
+        if not (spec_dir / name).is_dir()
+    ]
+
+    if not missing:
+        return None  # All packages have spec dirs
+
+    if len(missing) == len(packages):
+        return (
+            f"[!] Legacy spec structure detected: found `spec/backend/` or `spec/frontend/` "
+            f"but no package-scoped `spec/<package>/` directories.\n"
+            f"Monorepo packages: {', '.join(sorted(packages.keys()))}\n"
+            f"Please reorganize: `spec/backend/` -> `spec/<package>/backend/`"
+        )
+    return (
+        f"[!] Partial spec migration detected: packages {', '.join(missing)} "
+        f"still missing `spec/<pkg>/` directory.\n"
+        f"Please complete migration for all packages."
+    )
+
+
+def _resolve_spec_scope(
+    is_mono: bool,
+    packages: dict,
+    scope,
+    task_pkg: str | None,
+    default_pkg: str | None,
+) -> set | None:
+    """Resolve which packages should have their specs injected.
+
+    Returns:
+        Set of package names to include, or None for full scan.
+    """
+    if not is_mono or not packages:
+        return None  # Single-repo: full scan
+
+    if scope is None:
+        return None  # No scope configured: full scan
+
+    if isinstance(scope, str) and scope == "active_task":
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None  # Fallback to full scan
+
+    if isinstance(scope, list):
+        valid = set()
+        for entry in scope:
+            if entry in packages:
+                valid.add(entry)
+            else:
+                print(
+                    f"Warning: spec_scope contains unknown package: {entry}, ignoring",
+                    file=sys.stderr,
+                )
+
+        if valid:
+            # Warn if active task is out of scope
+            if task_pkg and task_pkg not in valid:
+                print(
+                    f"Warning: active task package '{task_pkg}' is out of configured spec_scope",
+                    file=sys.stderr,
+                )
+            return valid
+
+        # All entries invalid: fallback chain
+        print(
+            "Warning: all spec_scope entries invalid, falling back to task/default/full",
+            file=sys.stderr,
+        )
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None  # Full scan
+
+    return None  # Unknown scope type: full scan
+
+
+def _extract_range(content: str, start_header: str, end_header: str) -> str:
+    """Extract lines starting at `## start_header` up to (but excluding) `## end_header`.
+
+    Both parameters are full header lines WITHOUT the `## ` prefix (e.g. "Phase Index").
+    Returns empty string if start header is not found.
+    End header missing → extracts to end of file.
+    """
+    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()
+
+
+def _build_workflow_overview(workflow_path: Path) -> str:
+    """Inject the workflow guide for the session.
+
+    Contents:
+      1. Section index (all `## ` headings — navigation)
+      2. Phase Index section (rules, skill routing table, anti-rationalization table)
+      3. Phase 1/2/3 step-level details (the actual how-to for each step)
+
+    The meta sections (Core Principles / Trellis System / Workflow State
+    Breadcrumbs) are NOT injected — Core Principles is short prose the AI can
+    Read on demand; Trellis System lists reference commands duplicated in
+    step bodies; Breadcrumbs are consumed by the UserPromptSubmit hook.
+
+    Total budget: Phase Index ~2 KB + Phase 1/2/3 ~7 KB = ~9 KB.
+    """
+    content = read_file(workflow_path)
+    if not content:
+        return "No workflow.md found"
+
+    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("## "):
+            out_lines.append(line)
+    out_lines += ["", "---", ""]
+
+    # Extract Phase Index through the end of Phase 3 (before Breadcrumbs).
+    # Since sections appear in order Phase Index → Phase 1 → Phase 2 → Phase 3
+    # → Workflow State Breadcrumbs, a single range grab captures all four.
+    phases = _extract_range(
+        content, "Phase Index", "Workflow State Breadcrumbs"
+    )
+    if phases:
+        out_lines.append(phases)
+
+    return "\n".join(out_lines).rstrip()
+
+
+def main():
+    if should_skip_injection():
+        sys.exit(0)
+
+    # Try platform-specific env vars, fallback to cwd
+    project_dir_env_vars = [
+        "CLAUDE_PROJECT_DIR",
+        "QODER_PROJECT_DIR",
+        "CODEBUDDY_PROJECT_DIR",
+        "FACTORY_PROJECT_DIR",
+        "CURSOR_PROJECT_DIR",
+        "GEMINI_PROJECT_DIR",
+        "KIRO_PROJECT_DIR",
+        "COPILOT_PROJECT_DIR",
+    ]
+    project_dir = None
+    for var in project_dir_env_vars:
+        val = os.environ.get(var)
+        if val:
+            project_dir = Path(val).resolve()
+            break
+    if project_dir is None:
+        project_dir = Path(".").resolve()
+
+    trellis_dir = project_dir / ".trellis"
+
+    # Load config for scope filtering and legacy detection
+    is_mono, packages, scope_config, task_pkg, default_pkg = _load_trellis_config(trellis_dir)
+    allowed_pkgs = _resolve_spec_scope(is_mono, packages, scope_config, task_pkg, default_pkg)
+
+    output = StringIO()
+
+    output.write("""<session-context>
+You are starting a new session in a Trellis-managed project.
+Read and follow all instructions below carefully.
+</session-context>
+
+""")
+    output.write(FIRST_REPLY_NOTICE)
+    output.write("\n\n")
+
+    # Legacy migration warning
+    legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages)
+    if legacy_warning:
+        output.write(f"<migration-warning>\n{legacy_warning}\n</migration-warning>\n\n")
+
+    output.write("<current-state>\n")
+    context_script = trellis_dir / "scripts" / "get_context.py"
+    output.write(run_script(context_script))
+    output.write("\n</current-state>\n\n")
+
+    output.write("<workflow>\n")
+    output.write(_build_workflow_overview(trellis_dir / "workflow.md"))
+    output.write("\n</workflow>\n\n")
+
+    output.write("<guidelines>\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"
+        "- For agent-capable platforms, do NOT edit code directly in the main "
+        "session; dispatch `trellis-implement` and `trellis-check` so JSONL "
+        "context is loaded by the sub-agents.\n\n"
+    )
+
+    # guides/ is cross-package thinking — always include inline (small, 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 spec indexes — paths only (main agent reads on demand;
+    # sub-agents get their specific specs via jsonl injection)
+    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":
+                continue  # already inlined above
+
+            index_file = sub / "index.md"
+            if index_file.is_file():
+                # Flat spec dir (single-repo layer like spec/backend/)
+                paths.append(f".trellis/spec/{sub.name}/index.md")
+            else:
+                # Nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
+                # Apply scope filter
+                if allowed_pkgs is not None and sub.name not in allowed_pkgs:
+                    continue
+                for nested in sorted(sub.iterdir()):
+                    if not nested.is_dir():
+                        continue
+                    nested_index = nested / "index.md"
+                    if nested_index.is_file():
+                        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")
+
+    # Check task status and inject structured tag
+    task_status = _get_task_status(trellis_dir)
+    output.write(f"<task-status>\n{task_status}\n</task-status>\n\n")
+
+    output.write("""<ready>
+Context loaded. Workflow index, project state, and guidelines are already injected above — do NOT re-read them.
+When the user sends the first message, follow <task-status> and the workflow guide.
+If a task is READY, execute its Next required action without asking whether to continue.
+</ready>""")
+
+    result = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": output.getvalue(),
+        }
+    }
+
+    # Output JSON - stdout is already configured for UTF-8
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+
+
+if __name__ == "__main__":
+    main()

.cursor/hooks/statusline.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Trellis StatusLine — project-level status display for Claude Code.
+
+Reads Claude Code session JSON from stdin + Trellis task data from filesystem.
+Outputs 1-2 lines:
+  With active task:  [P1] Task title (status)  +  info line
+  Without task:      info line only
+Info line: model · ctx% · branch · duration · developer · tasks · rate limits
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# Fix: Windows Python defaults to GBK encoding, which corrupts UTF-8
+# characters like the middle dot (·). Wrap stdout/stderr with UTF-8.
+if sys.platform == "win32":
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8", errors="replace")
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (FileNotFoundError, PermissionError, OSError):
+        return ""
+
+
+def _read_json(path: Path) -> dict:
+    text = _read_text(path)
+    if not text:
+        return {}
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+def _normalize_task_ref(task_ref: str) -> str:
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith("tasks/"):
+        return f".trellis/{normalized}"
+
+    return normalized
+
+
+def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
+    normalized = _normalize_task_ref(task_ref)
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+    if normalized.startswith(".trellis/"):
+        return trellis_dir.parent / path_obj
+    return trellis_dir / "tasks" / path_obj
+
+
+def _find_trellis_dir() -> Path | None:
+    """Walk up from cwd to find .trellis/ directory."""
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        candidate = parent / ".trellis"
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def _get_current_task(trellis_dir: Path) -> dict | None:
+    """Load current task info. Returns dict with title/status/priority or None."""
+    task_ref = _normalize_task_ref(_read_text(trellis_dir / ".current-task"))
+    if not task_ref:
+        return None
+
+    # Resolve task directory
+    task_path = _resolve_task_dir(trellis_dir, task_ref)
+    task_data = _read_json(task_path / "task.json")
+    if not task_data:
+        return None
+
+    return {
+        "title": task_data.get("title") or task_data.get("name") or "unknown",
+        "status": task_data.get("status", "unknown"),
+        "priority": task_data.get("priority", "P2"),
+    }
+
+
+def _count_active_tasks(trellis_dir: Path) -> int:
+    """Count non-archived task directories with valid task.json."""
+    tasks_dir = trellis_dir / "tasks"
+    if not tasks_dir.is_dir():
+        return 0
+    count = 0
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name != "archive" and (d / "task.json").is_file():
+            count += 1
+    return count
+
+
+def _get_developer(trellis_dir: Path) -> str:
+    content = _read_text(trellis_dir / ".developer")
+    if not content:
+        return "unknown"
+    for line in content.splitlines():
+        if line.startswith("name="):
+            return line[5:].strip()
+    return content.splitlines()[0].strip() or "unknown"
+
+
+def _get_git_branch() -> str:
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, timeout=3,
+        )
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+
+def _format_ctx_size(size: int) -> str:
+    if size >= 1_000_000:
+        return f"{size // 1_000_000}M"
+    if size >= 1_000:
+        return f"{size // 1_000}K"
+    return str(size)
+
+
+def _format_duration(ms: int) -> str:
+    secs = ms // 1000
+    hours, remainder = divmod(secs, 3600)
+    mins = remainder // 60
+    if hours > 0:
+        return f"{hours}h{mins}m"
+    return f"{mins}m"
+
+
+def main() -> None:
+    # Read Claude Code session JSON from stdin
+    try:
+        cc_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        cc_data = {}
+
+    trellis_dir = _find_trellis_dir()
+    SEP = " \033[90m·\033[0m "
+
+    # --- Trellis data ---
+    task = _get_current_task(trellis_dir) if trellis_dir else None
+    dev = _get_developer(trellis_dir) if trellis_dir else ""
+    task_count = _count_active_tasks(trellis_dir) if trellis_dir else 0
+
+    # --- CC session data ---
+    model = cc_data.get("model", {}).get("display_name", "?")
+    ctx_pct = int(cc_data.get("context_window", {}).get("used_percentage") or 0)
+    ctx_size = _format_ctx_size(cc_data.get("context_window", {}).get("context_window_size") or 0)
+    duration = _format_duration(cc_data.get("cost", {}).get("total_duration_ms") or 0)
+    branch = _get_git_branch()
+
+    # Avoid "Opus 4.6 (1M context) (1M)"
+    if re.search(r"\d+[KMG]\b", model, re.IGNORECASE):
+        model_label = model
+    else:
+        model_label = f"{model} ({ctx_size})"
+
+    # Context % with color
+    if ctx_pct >= 90:
+        ctx_color = "\033[31m"
+    elif ctx_pct >= 70:
+        ctx_color = "\033[33m"
+    else:
+        ctx_color = "\033[32m"
+
+    # Build info line: model · ctx · branch · duration · dev · tasks [· rate limits]
+    parts = [
+        model_label,
+        f"ctx {ctx_color}{ctx_pct}%\033[0m",
+    ]
+    if branch:
+        parts.append(f"\033[35m{branch}\033[0m")
+    parts.append(duration)
+    if dev:
+        parts.append(f"\033[32m{dev}\033[0m")
+    if task_count:
+        parts.append(f"{task_count} task(s)")
+
+    five_hr = cc_data.get("rate_limits", {}).get("five_hour", {}).get("used_percentage")
+    if five_hr is not None:
+        parts.append(f"5h {int(five_hr)}%")
+    seven_day = cc_data.get("rate_limits", {}).get("seven_day", {}).get("used_percentage")
+    if seven_day is not None:
+        parts.append(f"7d {int(seven_day)}%")
+
+    info_line = SEP.join(parts)
+
+    # Output: task line (only if active) + info line
+    if task:
+        print(f"\033[36m[{task['priority']}]\033[0m {task['title']} \033[33m({task['status']})\033[0m")
+    print(info_line)
+
+
+if __name__ == "__main__":
+    main()

.cursor/skills/trellis-before-dev/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: trellis-before-dev
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
+---
+
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+2. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+5. **Always read shared guides**:
+   ```bash
+   cat .trellis/spec/guides/index.md
+   ```
+
+6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

.cursor/skills/trellis-brainstorm/SKILL.md

@@ -0,0 +1,535 @@
+---
+name: trellis-brainstorm
+description: "Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task."
+---
+
+# Brainstorm - Requirements Discovery (AI Coding Enhanced)
+
+Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
+
+* **Task-first** (capture ideas immediately)
+* **Action-before-asking** (reduce low-value questions)
+* **Research-first** for technical choices (avoid asking users to invent options)
+* **Diverge → Converge** (expand thinking, then lock MVP)
+
+---
+
+## When to Use
+
+Triggered from /trellis-start when the user describes a development task, especially when:
+
+* requirements are unclear or evolving
+* there are multiple valid implementation paths
+* trade-offs matter (UX, reliability, maintainability, cost, performance)
+* the user might not know the best options up front
+
+---
+
+## Core Principles (Non-negotiable)
+
+1. **Task-first (capture early)**
+   Always ensure a task exists at the start so the user's ideas are recorded immediately.
+
+2. **Action before asking**
+   If you can derive the answer from repo code, docs, configs, conventions, or quick research — do that first.
+
+3. **One question per message**
+   Never overwhelm the user with a list of questions. Ask one, update PRD, repeat.
+
+4. **Prefer concrete options**
+   For preference/decision questions, present 2–3 feasible, specific approaches with trade-offs.
+
+5. **Research-first for technical choices**
+   If the decision depends on industry conventions / similar tools / established patterns, do research first, then propose options.
+
+6. **Diverge → Converge**
+   After initial understanding, proactively consider future evolution, related scenarios, and failure/edge cases — then converge to an MVP with explicit out-of-scope.
+
+7. **No meta questions**
+   Do not ask "should I search?" or "can you paste the code so I can continue?"
+   If you need information: search/inspect. If blocked: ask the minimal blocking question.
+
+---
+
+## Step 0: Ensure Task Exists (ALWAYS)
+
+Before any Q&A, ensure a task exists. If none exists, create one immediately.
+
+* Use a **temporary working title** derived from the user's message.
+* It's OK if the title is imperfect — refine later in PRD.
+
+```bash
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
+```
+
+Create/seed `prd.md` immediately with what you know:
+
+```markdown
+# brainstorm: <short goal>
+
+## Goal
+
+<one paragraph: what + why>
+
+## What I already know
+
+* <facts from user message>
+* <facts discovered from repo/docs>
+
+## Assumptions (temporary)
+
+* <assumptions to validate>
+
+## Open Questions
+
+* <ONLY Blocking / Preference questions; keep list short>
+
+## Requirements (evolving)
+
+* <start with what is known>
+
+## Acceptance Criteria (evolving)
+
+* [ ] <testable criterion>
+
+## Definition of Done (team quality bar)
+
+* Tests added/updated (unit/integration where appropriate)
+* Lint / typecheck / CI green
+* Docs/notes updated if behavior changes
+* Rollout/rollback considered if risky
+
+## Out of Scope (explicit)
+
+* <what we will not do in this task>
+
+## Technical Notes
+
+* <files inspected, constraints, links, references>
+* <research notes summary if applicable>
+```
+
+---
+
+## Step 1: Auto-Context (DO THIS BEFORE ASKING QUESTIONS)
+
+Before asking questions like "what does the code look like?", gather context yourself:
+
+### Repo inspection checklist
+
+* Identify likely modules/files impacted
+* Locate existing patterns (similar features, conventions, error handling style)
+* Check configs, scripts, existing command definitions
+* Note any constraints (runtime, dependency policy, build tooling)
+
+### Documentation checklist
+
+* Look for existing PRDs/specs/templates
+* Look for command usage examples, README, ADRs if any
+
+Write findings into PRD:
+
+* Add to `What I already know`
+* Add constraints/links to `Technical Notes`
+
+---
+
+## Step 2: Classify Complexity (still useful, not gating task creation)
+
+| Complexity   | Criteria                                               | Action                                      |
+| ------------ | ------------------------------------------------------ | ------------------------------------------- |
+| **Trivial**  | Single-line fix, typo, obvious change                  | Skip brainstorm, implement directly         |
+| **Simple**   | Clear goal, 1–2 files, scope well-defined              | Ask 1 confirm question, then implement      |
+| **Moderate** | Multiple files, some ambiguity                         | Light brainstorm (2–3 high-value questions) |
+| **Complex**  | Vague goal, architectural choices, multiple approaches | Full brainstorm                             |
+
+> Note: Task already exists from Step 0. Classification only affects depth of brainstorming.
+
+---
+
+## Step 3: Question Gate (Ask ONLY high-value questions)
+
+Before asking ANY question, run the following gate:
+
+### Gate A — Can I derive this without the user?
+
+If answer is available via:
+
+* repo inspection (code/config)
+* docs/specs/conventions
+* quick market/OSS research
+
+→ **Do not ask.** Fetch it, summarize, update PRD.
+
+### Gate B — Is this a meta/lazy question?
+
+Examples:
+
+* "Should I search?"
+* "Can you paste the code so I can proceed?"
+* "What does the code look like?" (when repo is available)
+
+→ **Do not ask.** Take action.
+
+### Gate C — What type of question is it?
+
+* **Blocking**: cannot proceed without user input
+* **Preference**: multiple valid choices, depends on product/UX/risk preference
+* **Derivable**: should be answered by inspection/research
+
+→ Only ask **Blocking** or **Preference**.
+
+---
+
+## Step 4: Research-first Mode (Mandatory for technical choices)
+
+### Trigger conditions (any → research-first)
+
+* The task involves selecting an approach, library, protocol, framework, template system, plugin mechanism, or CLI UX convention
+* The user asks for "best practice", "how others do it", "recommendation"
+* The user can't reasonably enumerate options
+
+### Delegate to `trellis-research` sub-agent (don't research inline)
+
+For each research topic, **spawn a `trellis-research` sub-agent via the Task tool** — don't do WebFetch / WebSearch / `gh api` inline in the main conversation.
+
+Why:
+- The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
+- It persists findings to `{TASK_DIR}/research/<topic>.md` (the contract — see `workflow.md` Phase 1.2)
+- It returns only `{file path, one-line summary}` to the main agent
+- Independent topics can be **parallelized** — spawn multiple sub-agents in one tool call
+
+Agent type: `trellis-research`
+Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
+
+❌ Bad (what you must NOT do):
+```
+Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
+          → WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
+          → Write(research/topic.md)
+```
+→ Pollutes main context with raw HTML/JSON, burns tokens.
+
+✅ Good:
+```
+Main agent: Task(subagent_type="trellis-research",
+                 prompt="Research topic A; persist to research/topic-a.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic B; persist to research/topic-b.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic C; persist to research/topic-c.md")
+→ Reads research/topic-{a,b,c}.md after they finish.
+```
+
+### Research steps (to pass into each sub-agent prompt)
+
+Each `trellis-research` sub-agent should:
+
+1. Identify 2–4 comparable tools/patterns for its topic
+2. Summarize common conventions and why they exist
+3. Map conventions onto our repo constraints
+4. Write findings to `{TASK_DIR}/research/<topic>.md`
+
+Main agent then reads the persisted files and produces **2–3 feasible approaches** in PRD.
+
+### Research output format (PRD)
+
+The PRD itself should only reference the persisted research files, not duplicate their content. Add a `## Research References` section pointing at `research/*.md`.
+
+Optionally, add a convergence section with feasible approaches derived from the research:
+
+```markdown
+## Research References
+
+* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
+* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
+
+## Research Notes
+
+### What similar tools do
+
+* ...
+* ...
+
+### Constraints from our repo/project
+
+* ...
+
+### Feasible approaches here
+
+**Approach A: <name>** (Recommended)
+
+* How it works:
+* Pros:
+* Cons:
+
+**Approach B: <name>**
+
+* How it works:
+* Pros:
+* Cons:
+
+**Approach C: <name>** (optional)
+
+* ...
+```
+
+Then ask **one** preference question:
+
+* "Which approach do you prefer: A / B / C (or other)?"
+
+---
+
+## Step 5: Expansion Sweep (DIVERGE) — Required after initial understanding
+
+After you can summarize the goal, proactively broaden thinking before converging.
+
+### Expansion categories (keep to 1–2 bullets each)
+
+1. **Future evolution**
+
+   * What might this feature become in 1–3 months?
+   * What extension points are worth preserving now?
+
+2. **Related scenarios**
+
+   * What adjacent commands/flows should remain consistent with this?
+   * Are there parity expectations (create vs update, import vs export, etc.)?
+
+3. **Failure & edge cases**
+
+   * Conflicts, offline/network failure, retries, idempotency, compatibility, rollback
+   * Input validation, security boundaries, permission checks
+
+### Expansion message template (to user)
+
+```markdown
+I understand you want to implement: <current goal>.
+
+Before diving into design, let me quickly diverge to consider three categories (to avoid rework later):
+
+1. Future evolution: <1–2 bullets>
+2. Related scenarios: <1–2 bullets>
+3. Failure/edge cases: <1–2 bullets>
+
+For this MVP, which would you like to include (or none)?
+
+1. Current requirement only (minimal viable)
+2. Add <X> (reserve for future extension)
+3. Add <Y> (improve robustness/consistency)
+4. Other: describe your preference
+```
+
+Then update PRD:
+
+* What's in MVP → `Requirements`
+* What's excluded → `Out of Scope`
+
+---
+
+## Step 6: Q&A Loop (CONVERGE)
+
+### Rules
+
+* One question per message
+* Prefer multiple-choice when possible
+* After each user answer:
+
+  * Update PRD immediately
+  * Move answered items from `Open Questions` → `Requirements`
+  * Update `Acceptance Criteria` with testable checkboxes
+  * Clarify `Out of Scope`
+
+### Question priority (recommended)
+
+1. **MVP scope boundary** (what is included/excluded)
+2. **Preference decisions** (after presenting concrete options)
+3. **Failure/edge behavior** (only for MVP-critical paths)
+4. **Success metrics & Acceptance Criteria** (what proves it works)
+
+### Preferred question format (multiple choice)
+
+```markdown
+For <topic>, which approach do you prefer?
+
+1. **Option A** — <what it means + trade-off>
+2. **Option B** — <what it means + trade-off>
+3. **Option C** — <what it means + trade-off>
+4. **Other** — describe your preference
+```
+
+---
+
+## Step 7: Propose Approaches + Record Decisions (Complex tasks)
+
+After requirements are clear enough, propose 2–3 approaches (if not already done via research-first):
+
+```markdown
+Based on current information, here are 2–3 feasible approaches:
+
+**Approach A: <name>** (Recommended)
+
+* How:
+* Pros:
+* Cons:
+
+**Approach B: <name>**
+
+* How:
+* Pros:
+* Cons:
+
+Which direction do you prefer?
+```
+
+Record the outcome in PRD as an ADR-lite section:
+
+```markdown
+## Decision (ADR-lite)
+
+**Context**: Why this decision was needed
+**Decision**: Which approach was chosen
+**Consequences**: Trade-offs, risks, potential future improvements
+```
+
+---
+
+## Step 8: Final Confirmation + Implementation Plan
+
+When open questions are resolved, confirm complete requirements with a structured summary:
+
+### Final confirmation format
+
+```markdown
+Here's my understanding of the complete requirements:
+
+**Goal**: <one sentence>
+
+**Requirements**:
+
+* ...
+* ...
+
+**Acceptance Criteria**:
+
+* [ ] ...
+* [ ] ...
+
+**Definition of Done**:
+
+* ...
+
+**Out of Scope**:
+
+* ...
+
+**Technical Approach**:
+<brief summary + key decisions>
+
+**Implementation Plan (small PRs)**:
+
+* PR1: <scaffolding + tests + minimal plumbing>
+* PR2: <core behavior>
+* PR3: <edge cases + docs + cleanup>
+
+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)
+
+`prd.md` should converge to:
+
+```markdown
+# <Task Title>
+
+## Goal
+
+<why + what>
+
+## Requirements
+
+* ...
+
+## Acceptance Criteria
+
+* [ ] ...
+
+## Definition of Done
+
+* ...
+
+## Technical Approach
+
+<key design + decisions>
+
+## Decision (ADR-lite)
+
+Context / Decision / Consequences
+
+## Out of Scope
+
+* ...
+
+## Technical Notes
+
+<constraints, references, files, research notes>
+```
+
+---
+
+## Anti-Patterns (Hard Avoid)
+
+* Asking user for code/context that can be derived from repo
+* Asking user to choose an approach before presenting concrete options
+* Meta questions about whether to research
+* Staying narrowly on the initial request without considering evolution/edges
+* Letting brainstorming drift without updating PRD
+
+---
+
+## Integration with Start Workflow
+
+After brainstorm completes (Step 8 confirmation approved), the flow continues to the Task Workflow's **Phase 2: Prepare for Implementation**:
+
+```text
+Brainstorm
+  Step 0: Create task directory + seed PRD
+  Step 1–7: Discover requirements, research, converge
+  Step 8: Final confirmation → user approves
+  ↓
+Task Workflow Phase 2 (Prepare for Implementation)
+  Code-Spec Depth Check (if applicable)
+  → Research codebase (based on confirmed PRD)
+  → Configure code-spec context (jsonl files)
+  → Activate task
+  ↓
+Task Workflow Phase 3 (Execute)
+  Implement → Check → Complete
+```
+
+The task directory and PRD already exist from brainstorm, so Phase 1 of the Task Workflow is skipped entirely.
+
+---
+
+## Related Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `/trellis-start` | Entry point that triggers brainstorm |
+| `/trellis-finish-work` | After implementation is complete |
+| `/trellis-update-spec` | If new patterns emerge during work |

.cursor/skills/trellis-break-loop/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: trellis-break-loop
+description: "Deep bug analysis to break the fix-forget-repeat cycle. Analyzes root cause category, why fixes failed, prevention mechanisms, and captures knowledge into specs. Use after fixing a bug to prevent the same class of bugs."
+---
+
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this 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** | Strict type checking, no escape hatches | 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/spec/guides/` thinking guides
+- [ ] Update relevant `.trellis/spec/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check guidelines 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.
+
+---
+
+## After Analysis: Immediate Actions
+
+**IMPORTANT**: After completing the analysis above, you MUST immediately:
+
+1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files:
+   - If it's a cross-platform issue → update `cross-platform-thinking-guide.md`
+   - If it's a cross-layer issue → update `cross-layer-thinking-guide.md`
+   - If it's a code reuse issue → update `code-reuse-thinking-guide.md`
+   - If it's domain-specific → update `backend/*.md` or `frontend/*.md`
+
+2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/`
+
+3. **Commit the spec updates** - This is the primary output, not just the analysis text
+
+> **The analysis is worthless if it stays in chat. The value is in the updated specs.**

.cursor/skills/trellis-check/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: trellis-check
+description: "Comprehensive quality verification: spec compliance, lint, type-check, tests, cross-layer data flow, code reuse, and consistency checks. Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions."
+---
+
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Applicable Specs
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist
+
+### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+### Test Coverage
+
+- [ ] New function → unit test added?
+- [ ] Bug fix → regression test added?
+- [ ] Changed behavior → existing tests updated?
+
+### Spec Sync
+
+- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report violations found and fix them directly. Re-run project checks after fixes.

.cursor/skills/trellis-update-spec/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: trellis-update-spec
+description: "Captures executable contracts and coding conventions into .trellis/spec/ documents. Use when learning something valuable from debugging, implementing, or discussion that should be preserved for future sessions."
+---
+
+# Update Code-Spec - Capture Executable Contracts
+
+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
+
+---
+
+## Code-Spec First Rule (CRITICAL)
+
+In this project, "spec" for implementation work means **code-spec**:
+- Executable contracts (not principle-only text)
+- Concrete signatures, payload fields, env keys, and boundary behavior
+- Testable validation/error behavior
+
+If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+1. Scope / Trigger
+2. Signatures (command/API/DB)
+3. Contracts (request/response/env)
+4. Validation & Error Matrix
+5. Good/Base/Bad Cases
+6. Tests Required (with assertion points)
+7. Wrong vs Correct (at least one pair)
+
+---
+
+## When to Update Code-Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **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.
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── <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!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Code-Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **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 a spec layer directory
+- "This is **what to consider** before writing" → Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "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.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Code-Spec
+
+Before editing, read the current code-spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Contracts**: Add signatures, payload fields, and error behavior
+4. **Show Code**: Add code snippets for key patterns
+5. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the code-spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Mandatory Template for Infra/Cross-Layer Work
+
+```markdown
+## Scenario: <name>
+
+### 1. Scope / Trigger
+- Trigger: <why this requires code-spec depth>
+
+### 2. Signatures
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 7. Wrong vs Correct
+#### Wrong
+...
+#### Correct
+...
+```
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works → Yes, update spec
+   - To maintain or extend the feature → Yes, update spec
+   - To avoid repeating mistakes → Yes, update spec
+   - Purely one-off implementation detail → Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your code-spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Did you include executable signatures/contracts?
+- [ ] Did you include validation and error matrix?
+- [ ] Did you include Good/Base/Bad cases?
+- [ ] Did you include required tests with assertion points?
+- [ ] Is it in the right code-spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → /trellis-update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis-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
+- `/trellis-finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails

.trellis/.gitignore

@@ -0,0 +1,29 @@
+# Developer identity (local only)
+.developer
+
+# Current task pointer (each dev works on different task)
+.current-task
+
+# Ralph Loop state file
+.ralph-state.json
+
+# Agent runtime files
+.agents/
+.agent-log
+.session-id
+
+# Task directory runtime files
+.plan-log
+
+# Atomic update temp files
+*.tmp
+
+# Update backup directories
+.backup-*
+
+# Conflict resolution temp files
+*.new
+
+# Python cache
+**/__pycache__/
+**/*.pyc

.trellis/.template-hashes.json

@@ -0,0 +1,58 @@
+{
+  ".trellis/config.yaml": "c3c4af7d82c09a1638f63c1f560119507735b060a4780ef7e6d0cdef447c215d",
+  ".trellis/scripts/__init__.py": "1242be5b972094c2e141aecbe81a4efd478f6534e3d5e28306374e6a18fcf46c",
+  ".trellis/scripts/add_session.py": "a97a6c88ff7def8045a5dffa5c698a823392d7f73c1641e8a0c08db0168bd913",
+  ".trellis/scripts/common/__init__.py": "a8afa14ebe662723f96e4f5757c15359d76adf4cb5c52327c94dbe854bd1ab01",
+  ".trellis/scripts/common/cli_adapter.py": "b10763292c8eb56affe7e3921ebf0dfaaceb148b3052fc9a01716589a5d4a6e9",
+  ".trellis/scripts/common/config.py": "671a3591f97b75ec19f25814d2ee3f7e9b38e048f6f67442519fe0715c454eeb",
+  ".trellis/scripts/common/developer.py": "f5f833123abe68890171b4da825a324216d24913f6b5ad9245afc556424ffd7b",
+  ".trellis/scripts/common/git.py": "e14817be7de122d3a106f509c2825aeb9669d962ba73ba241642d2931cfdf1d6",
+  ".trellis/scripts/common/git_context.py": "7533c08335791e50c3a6f9d551d5b1af0bdaa2a0a746721cb3e1a2140f4d9683",
+  ".trellis/scripts/common/io.py": "6480b181f2bc505323b28ed7a66963d7b7edc96251e83b4c8e7a45907cc721c8",
+  ".trellis/scripts/common/log.py": "471df6895cfac80f995edebbf9974f6b7440634b7a688f28b8331c868bc0f3cf",
+  ".trellis/scripts/common/packages_context.py": "efe158d7c99c2268851d0216fbb08de22836e418a8dbeb73575b8cc249eed7b7",
+  ".trellis/scripts/common/paths.py": "36f72bdc09e4f0db53250346a4744ff3699c634ea71380eed5b467095f3d946b",
+  ".trellis/scripts/common/session_context.py": "2389eff1a66b172783fcb714a79385114d9b29746133a3e0db732c3b5cb23898",
+  ".trellis/scripts/common/task_context.py": "1c16a7fa82d363010d0d0ebdc038296ae1552bf6e90214787d707f49567bc159",
+  ".trellis/scripts/common/task_queue.py": "0be61f713462b1fe4574927c82fc4704e678afe72dcb9813543aedf2f9e9e0c5",
+  ".trellis/scripts/common/task_store.py": "57fff744bce501ee2a0d25ac096301cb4288e02627197a513a00cd0a5cddb78d",
+  ".trellis/scripts/common/task_utils.py": "f5ef4af87ba3e11d8b19630c0c96d009de1811fc9be56c2027a9c96e21ed103e",
+  ".trellis/scripts/common/tasks.py": "eeefae693dadec54c8945394e288e90ed1e8f79545dfb2d4934a431496f5229d",
+  ".trellis/scripts/common/types.py": "9962081cc2608fb9d1deb32c6880e336f62cdca6b338e7ae813304701e155ee9",
+  ".trellis/scripts/common/workflow_phase.py": "b5736dab0587d78cfe25059435495e7631eeab1d03ea62c3db1a493dae19e553",
+  ".trellis/scripts/get_context.py": "ca5bf9e90bdb1d75d3de182b95f820f9d108ab28793d29097b24fd71315adcf5",
+  ".trellis/scripts/get_developer.py": "84c27076323c3e0f2c9c8ed16e8aa865e225d902a187c37e20ee1a46e7142d8f",
+  ".trellis/scripts/hooks/linear_sync.py": "e09cc4ce4699aada908808718698f33f705a3edf55c4dcf8f777ad892f80ca79",
+  ".trellis/scripts/init_developer.py": "f9e6c0d882406e81c8cd6b1c5abb204b0befc0069ff89cf650cd536a80f8c60e",
+  ".trellis/scripts/task.py": "402e3a097b455e0880e5c61de2b1326da3a85da5d231cf4c2598376a7b6e0687",
+  ".trellis/workflow.md": "3328b94491e79b1c2cc278f26b3dacd384cb874284ee9ae145146efa2588326f",
+  ".claude/agents/trellis-check.md": "bfef8b996ae19a23fc8a71b63cd0e5d1cbc9f37fb6e879c2cbb3724448872e70",
+  ".claude/agents/trellis-implement.md": "f2e9f4cf54a3a2a554688b88627dcb946610c92ea9d9af6cf0bab64d132f3b8e",
+  ".claude/agents/trellis-research.md": "c367aa32c0c67d7d978a3cd5191c3c2462f7ddfcc9644419a3ef2b0b16bac0b5",
+  ".claude/commands/trellis/continue.md": "6b1fd1c7f04b53ebe69ea97375d9156eeea7ebac94cf6eb70846cad484ee04da",
+  ".claude/commands/trellis/finish-work.md": "692970dd868a60e757a3a43fbcd4821683201f5971b9f5878a59be7e635aa5c6",
+  ".claude/hooks/inject-subagent-context.py": "bf37525bc45f1427c01077f34db4ab9477559dbdba46e7464924062cfc477034",
+  ".claude/hooks/inject-workflow-state.py": "281939a51a62467a5dd73947fdec7143d0e936b4b64b5224ce0484186eb5b018",
+  ".claude/hooks/session-start.py": "26b52ad72259316aa5adc8068d0df2a002273d5eda659ac3c71f3f5ecd9ebd08",
+  ".claude/hooks/statusline.py": "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+  ".claude/settings.json": "824db605f1c2cc72668f04304217a787646545958abe5caf837f05845f13ed1b",
+  ".claude/settings.local.json": "d0e7a7b62d0b17718ade7f0f78746c683bbfebde336c9120dca486575d543269",
+  ".claude/skills/trellis-before-dev/SKILL.md": "208ad3fd5131fa0da603d4bc354a29826967397f5aeef483fa0564113df13e9e",
+  ".claude/skills/trellis-brainstorm/SKILL.md": "8b4e740c8f02ba6febfc7330b7255ec206e3fb8855f863e9811afda55836446e",
+  ".claude/skills/trellis-break-loop/SKILL.md": "35afb53fef42cd494e566f1ef170dbf442ec2be7e19931f28a14079b4dda753f",
+  ".claude/skills/trellis-check/SKILL.md": "a3f17aef687aa3b475d12ee64c3293e5491bb7474336be2c0f9ec22042f13b6e",
+  ".cursor/agents/trellis-check.md": "bfef8b996ae19a23fc8a71b63cd0e5d1cbc9f37fb6e879c2cbb3724448872e70",
+  ".cursor/agents/trellis-implement.md": "f2e9f4cf54a3a2a554688b88627dcb946610c92ea9d9af6cf0bab64d132f3b8e",
+  ".cursor/agents/trellis-research.md": "c367aa32c0c67d7d978a3cd5191c3c2462f7ddfcc9644419a3ef2b0b16bac0b5",
+  ".cursor/commands/trellis-continue.md": "0faf3a6a8df5cd87632ef960768899bd1054b333fe095810c825a93bcbae7ef3",
+  ".cursor/commands/trellis-finish-work.md": "692970dd868a60e757a3a43fbcd4821683201f5971b9f5878a59be7e635aa5c6",
+  ".cursor/hooks/inject-subagent-context.py": "bf37525bc45f1427c01077f34db4ab9477559dbdba46e7464924062cfc477034",
+  ".cursor/hooks/inject-workflow-state.py": "281939a51a62467a5dd73947fdec7143d0e936b4b64b5224ce0484186eb5b018",
+  ".cursor/hooks/session-start.py": "26b52ad72259316aa5adc8068d0df2a002273d5eda659ac3c71f3f5ecd9ebd08",
+  ".cursor/hooks/statusline.py": "87c01ee786ca9e1f25b591f0ed67564cd430586d57516d5b6fc57c34b6e7a3ec",
+  ".cursor/hooks.json": "f0e9ff8531789b56bbc1b8a4b20fd3701acb0d94d34667fba64eef28ecfcc1f3",
+  ".cursor/skills/trellis-before-dev/SKILL.md": "208ad3fd5131fa0da603d4bc354a29826967397f5aeef483fa0564113df13e9e",
+  ".cursor/skills/trellis-brainstorm/SKILL.md": "0764303ecff8b584da0b6f525a41e1446f30faa20a1cea432a08c44df30b060b",
+  ".cursor/skills/trellis-break-loop/SKILL.md": "35afb53fef42cd494e566f1ef170dbf442ec2be7e19931f28a14079b4dda753f",
+  ".cursor/skills/trellis-check/SKILL.md": "a3f17aef687aa3b475d12ee64c3293e5491bb7474336be2c0f9ec22042f13b6e"
+}

.trellis/.version

@@ -0,0 +1 @@
+0.5.0-beta.14

.trellis/config.yaml

@@ -0,0 +1,59 @@
+# Trellis Configuration
+# Project-level settings for the Trellis workflow system
+#
+# All values have sensible defaults. Only override what you need.
+
+#-------------------------------------------------------------------------------
+# Session Recording
+#-------------------------------------------------------------------------------
+
+# Commit message used when auto-committing journal/index changes
+# after running add_session.py
+session_commit_message: "chore: record journal"
+
+# Maximum lines per journal file before rotating to a new one
+max_journal_lines: 2000
+
+#-------------------------------------------------------------------------------
+# Task Lifecycle Hooks
+#-------------------------------------------------------------------------------
+
+# Shell commands to run after task lifecycle events.
+# Each hook receives TASK_JSON_PATH environment variable pointing to task.json.
+# Hook failures print a warning but do not block the main operation.
+#
+# hooks:
+#   after_create:
+#     - "echo 'Task created'"
+#   after_start:
+#     - "echo 'Task started'"
+#   after_finish:
+#     - "echo 'Task finished'"
+#   after_archive:
+#     - "echo 'Task archived'"
+
+#-------------------------------------------------------------------------------
+# Monorepo / Packages
+#-------------------------------------------------------------------------------
+
+# Declare packages for monorepo projects.
+# Trellis auto-detects workspaces during `trellis init`, but you can also
+# configure them manually here.
+#
+# packages:
+#   frontend:
+#     path: packages/frontend
+#   backend:
+#     path: packages/backend
+#   docs:
+#     path: docs-site
+#     type: submodule
+#   # For polyrepo / meta-repo layouts (independent .git in each subdir),
+#   # mark the package with `git: true`. The runtime treats it as an
+#   # independent repository for things like git-context display.
+#   webapp:
+#     path: ./webapp
+#     git: true
+
+# Default package used when --package is not specified.
+# default_package: frontend

.trellis/scripts/__init__.py

@@ -0,0 +1,5 @@
+"""
+Trellis Python Scripts
+
+This module provides Python implementations of Trellis workflow scripts.
+"""

.trellis/scripts/add_session.py

@@ -0,0 +1,521 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Add a new session to journal file and update index.md.
+
+Usage:
+    python3 add_session.py --title "Title" --commit "hash" --summary "Summary" [--package cli]
+    python3 add_session.py --title "Title" --branch "feat/my-branch"
+
+    # Pipe detailed content via stdin (use --stdin to opt in):
+    cat << 'EOF' | python3 add_session.py --stdin --title "Title" --summary "Summary"
+    <session content here>
+    EOF
+
+Branch resolution order:
+    1. --branch CLI arg (explicit)
+    2. task.json branch field (from active task)
+    3. git branch --show-current (auto-detect)
+    4. None (omitted gracefully)
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from common.paths import (
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_current_task,
+    get_developer,
+    get_workspace_dir,
+)
+from common.developer import ensure_developer
+from common.git import run_git
+from common.tasks import load_task
+from common.config import (
+    get_packages,
+    get_session_commit_message,
+    get_max_journal_lines,
+    is_monorepo,
+    resolve_package,
+    validate_package,
+)
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def get_latest_journal_info(dev_dir: Path) -> tuple[Path | None, int, int]:
+    """Get latest journal file info.
+
+    Returns:
+        Tuple of (file_path, file_number, line_count).
+    """
+    latest_file: Path | None = None
+    latest_num = -1
+
+    for f in dev_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
+        if not f.is_file():
+            continue
+
+        match = re.search(r"(\d+)$", f.stem)
+        if match:
+            num = int(match.group(1))
+            if num > latest_num:
+                latest_num = num
+                latest_file = f
+
+    if latest_file:
+        lines = len(latest_file.read_text(encoding="utf-8").splitlines())
+        return latest_file, latest_num, lines
+
+    return None, 0, 0
+
+
+def get_current_session(index_file: Path) -> int:
+    """Get current session number from index.md."""
+    if not index_file.is_file():
+        return 0
+
+    content = index_file.read_text(encoding="utf-8")
+    for line in content.splitlines():
+        if "Total Sessions" in line:
+            match = re.search(r":\s*(\d+)", line)
+            if match:
+                return int(match.group(1))
+    return 0
+
+
+def _extract_journal_num(filename: str) -> int:
+    """Extract journal number from filename for sorting."""
+    match = re.search(r"(\d+)", filename)
+    return int(match.group(1)) if match else 0
+
+
+def count_journal_files(dev_dir: Path, active_num: int) -> str:
+    """Count journal files and return table rows."""
+    active_file = f"{FILE_JOURNAL_PREFIX}{active_num}.md"
+    result_lines = []
+
+    files = sorted(
+        [f for f in dev_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md") if f.is_file()],
+        key=lambda f: _extract_journal_num(f.stem),
+        reverse=True
+    )
+
+    for f in files:
+        filename = f.name
+        lines = len(f.read_text(encoding="utf-8").splitlines())
+        status = "Active" if filename == active_file else "Archived"
+        result_lines.append(f"| `{filename}` | ~{lines} | {status} |")
+
+    return "\n".join(result_lines)
+
+
+def create_new_journal_file(
+    dev_dir: Path, num: int, developer: str, today: str, max_lines: int = 2000,
+) -> Path:
+    """Create a new journal file."""
+    prev_num = num - 1
+    new_file = dev_dir / f"{FILE_JOURNAL_PREFIX}{num}.md"
+
+    content = f"""# Journal - {developer} (Part {num})
+
+> Continuation from `{FILE_JOURNAL_PREFIX}{prev_num}.md` (archived at ~{max_lines} lines)
+> Started: {today}
+
+---
+
+"""
+    new_file.write_text(content, encoding="utf-8")
+    return new_file
+
+
+def generate_session_content(
+    session_num: int,
+    title: str,
+    commit: str,
+    summary: str,
+    extra_content: str,
+    today: str,
+    package: str | None = None,
+    branch: str | None = None,
+) -> str:
+    """Generate session content."""
+    if commit and commit != "-":
+        commit_table = """| Hash | Message |
+|------|---------|"""
+        for c in commit.split(","):
+            c = c.strip()
+            commit_table += f"\n| `{c}` | (see git log) |"
+    else:
+        commit_table = "(No commits - planning session)"
+
+    package_line = f"\n**Package**: {package}" if package else ""
+    branch_line = f"\n**Branch**: `{branch}`" if branch else ""
+
+    return f"""
+
+## Session {session_num}: {title}
+
+**Date**: {today}
+**Task**: {title}{package_line}{branch_line}
+
+### Summary
+
+{summary}
+
+### Main Changes
+
+{extra_content}
+
+### Git Commits
+
+{commit_table}
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+"""
+
+
+def update_index(
+    index_file: Path,
+    dev_dir: Path,
+    title: str,
+    commit: str,
+    new_session: int,
+    active_file: str,
+    today: str,
+    branch: str | None = None,
+) -> bool:
+    """Update index.md with new session info."""
+    # Format commit for display
+    commit_display = "-"
+    if commit and commit != "-":
+        commit_display = re.sub(r"([a-f0-9]{7,})", r"`\1`", commit.replace(",", ", "))
+
+    # Get file number from active_file name
+    match = re.search(r"(\d+)", active_file)
+    active_num = int(match.group(1)) if match else 0
+    files_table = count_journal_files(dev_dir, active_num)
+
+    print(f"Updating index.md for session {new_session}...")
+    print(f"  Title: {title}")
+    print(f"  Commit: {commit_display}")
+    print(f"  Active File: {active_file}")
+    print()
+
+    content = index_file.read_text(encoding="utf-8")
+
+    if "@@@auto:current-status" not in content:
+        print("Error: Markers not found in index.md. Please ensure markers exist.", file=sys.stderr)
+        return False
+
+    # Process sections
+    lines = content.splitlines()
+    new_lines = []
+
+    in_current_status = False
+    in_active_documents = False
+    in_session_history = False
+    header_written = False
+
+    for line in lines:
+        if "@@@auto:current-status" in line:
+            new_lines.append(line)
+            in_current_status = True
+            new_lines.append(f"- **Active File**: `{active_file}`")
+            new_lines.append(f"- **Total Sessions**: {new_session}")
+            new_lines.append(f"- **Last Active**: {today}")
+            continue
+
+        if "@@@/auto:current-status" in line:
+            in_current_status = False
+            new_lines.append(line)
+            continue
+
+        if "@@@auto:active-documents" in line:
+            new_lines.append(line)
+            in_active_documents = True
+            new_lines.append("| File | Lines | Status |")
+            new_lines.append("|------|-------|--------|")
+            new_lines.append(files_table)
+            continue
+
+        if "@@@/auto:active-documents" in line:
+            in_active_documents = False
+            new_lines.append(line)
+            continue
+
+        if "@@@auto:session-history" in line:
+            new_lines.append(line)
+            in_session_history = True
+            header_written = False
+            continue
+
+        if "@@@/auto:session-history" in line:
+            in_session_history = False
+            new_lines.append(line)
+            continue
+
+        if in_current_status:
+            continue
+
+        if in_active_documents:
+            continue
+
+        if in_session_history:
+            # Migrate old 4/6-column headers to 5-column Branch-only history.
+            if re.match(
+                r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*Base Branch\s*\|\s*$",
+                line,
+            ):
+                new_lines.append("| # | Date | Title | Commits | Branch |")
+                continue
+            if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*$", line):
+                new_lines.append("| # | Date | Title | Commits | Branch |")
+                continue
+            if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*$", line):
+                new_lines.append("| # | Date | Title | Commits | Branch |")
+                continue
+            if re.match(r"^\|[-| ]+\|\s*$", line) and not header_written:
+                new_lines.append("|---|------|-------|---------|--------|")
+                new_lines.append(f"| {new_session} | {today} | {title} | {commit_display} | `{branch or '-'}` |")
+                header_written = True
+                continue
+            new_lines.append(line)
+            continue
+
+        new_lines.append(line)
+
+    index_file.write_text("\n".join(new_lines), encoding="utf-8")
+    print("[OK] Updated index.md successfully!")
+    return True
+
+
+# =============================================================================
+# Main Function
+# =============================================================================
+
+def _auto_commit_workspace(repo_root: Path) -> None:
+    """Stage .trellis/workspace and .trellis/tasks, then commit with a configured message."""
+    commit_msg = get_session_commit_message(repo_root)
+    add_result = subprocess.run(
+        ["git", "add", "-A", ".trellis/workspace", ".trellis/tasks"],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+    )
+    if add_result.returncode != 0:
+        print(f"[WARN] git add failed (exit {add_result.returncode}): {add_result.stderr.strip()}", file=sys.stderr)
+        print("[WARN] Please commit .trellis/ changes manually: git add .trellis && git commit", file=sys.stderr)
+        return
+    # Check if there are staged changes
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--quiet", "--", ".trellis/workspace", ".trellis/tasks"],
+        cwd=repo_root,
+    )
+    if result.returncode == 0:
+        print("[OK] No workspace changes to commit.", file=sys.stderr)
+        return
+    commit_result = subprocess.run(
+        ["git", "commit", "-m", commit_msg],
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+    )
+    if commit_result.returncode == 0:
+        print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
+    else:
+        print(f"[WARN] Auto-commit failed: {commit_result.stderr.strip()}", file=sys.stderr)
+
+
+def add_session(
+    title: str,
+    commit: str = "-",
+    summary: str = "(Add summary)",
+    extra_content: str = "(Add details)",
+    auto_commit: bool = True,
+    package: str | None = None,
+    branch: str | None = None,
+) -> int:
+    """Add a new session."""
+    repo_root = get_repo_root()
+    ensure_developer(repo_root)
+
+    developer = get_developer(repo_root)
+    if not developer:
+        print("Error: Developer not initialized", file=sys.stderr)
+        return 1
+
+    dev_dir = get_workspace_dir(repo_root)
+    if not dev_dir:
+        print("Error: Workspace directory not found", file=sys.stderr)
+        return 1
+
+    max_lines = get_max_journal_lines(repo_root)
+
+    index_file = dev_dir / "index.md"
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    journal_file, current_num, current_lines = get_latest_journal_info(dev_dir)
+    current_session = get_current_session(index_file)
+    new_session = current_session + 1
+
+    session_content = generate_session_content(
+        new_session, title, commit, summary, extra_content, today, package,
+        branch,
+    )
+    content_lines = len(session_content.splitlines())
+
+    print("========================================", file=sys.stderr)
+    print("ADD SESSION", file=sys.stderr)
+    print("========================================", file=sys.stderr)
+    print("", file=sys.stderr)
+    print(f"Session: {new_session}", file=sys.stderr)
+    print(f"Title: {title}", file=sys.stderr)
+    print(f"Commit: {commit}", file=sys.stderr)
+    print("", file=sys.stderr)
+    print(f"Current journal file: {FILE_JOURNAL_PREFIX}{current_num}.md", file=sys.stderr)
+    print(f"Current lines: {current_lines}", file=sys.stderr)
+    print(f"New content lines: {content_lines}", file=sys.stderr)
+    print(f"Total after append: {current_lines + content_lines}", file=sys.stderr)
+    print("", file=sys.stderr)
+
+    target_file = journal_file
+    target_num = current_num
+
+    if current_lines + content_lines > max_lines:
+        target_num = current_num + 1
+        print(f"[!] Exceeds {max_lines} lines, creating {FILE_JOURNAL_PREFIX}{target_num}.md", file=sys.stderr)
+        target_file = create_new_journal_file(dev_dir, target_num, developer, today, max_lines)
+        print(f"Created: {target_file}", file=sys.stderr)
+
+    # Append session content
+    if target_file:
+        with target_file.open("a", encoding="utf-8") as f:
+            f.write(session_content)
+        print(f"[OK] Appended session to {target_file.name}", file=sys.stderr)
+
+    print("", file=sys.stderr)
+
+    # Update index.md
+    active_file = f"{FILE_JOURNAL_PREFIX}{target_num}.md"
+    if not update_index(
+        index_file,
+        dev_dir,
+        title,
+        commit,
+        new_session,
+        active_file,
+        today,
+        branch,
+    ):
+        return 1
+
+    print("", file=sys.stderr)
+    print("========================================", file=sys.stderr)
+    print(f"[OK] Session {new_session} added successfully!", file=sys.stderr)
+    print("========================================", file=sys.stderr)
+    print("", file=sys.stderr)
+    print("Files updated:", file=sys.stderr)
+    print(f"  - {target_file.name if target_file else 'journal'}", file=sys.stderr)
+    print("  - index.md", file=sys.stderr)
+
+    # Auto-commit workspace changes
+    if auto_commit:
+        print("", file=sys.stderr)
+        _auto_commit_workspace(repo_root)
+
+    return 0
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="Add a new session to journal file and update index.md"
+    )
+    parser.add_argument("--title", required=True, help="Session title")
+    parser.add_argument("--commit", default="-", help="Comma-separated commit hashes")
+    parser.add_argument("--summary", default="(Add summary)", help="Brief summary")
+    parser.add_argument("--content-file", help="Path to file with detailed content")
+    parser.add_argument("--package", help="Package name tag (e.g., cli, docs-site)")
+    parser.add_argument("--branch", help="Branch name (auto-detected if omitted)")
+    parser.add_argument("--no-commit", action="store_true",
+                        help="Skip auto-commit of workspace changes")
+    parser.add_argument("--stdin", action="store_true",
+                        help="Read extra content from stdin (explicit opt-in)")
+
+    args = parser.parse_args()
+
+    extra_content = "(Add details)"
+    if args.content_file:
+        content_path = Path(args.content_file)
+        if content_path.is_file():
+            extra_content = content_path.read_text(encoding="utf-8")
+    elif args.stdin:
+        extra_content = sys.stdin.read()
+
+    # Load active task once — shared by package and branch resolution
+    repo_root = get_repo_root()
+    current = get_current_task(repo_root)
+    task_data = load_task(repo_root / current) if current else None
+
+    package = args.package
+    if package:
+        # CLI source: fail-fast in monorepo, ignore in single-repo
+        if not is_monorepo(repo_root):
+            print("Warning: --package ignored in single-repo project", file=sys.stderr)
+            package = None
+        elif not validate_package(package, repo_root):
+            packages = get_packages(repo_root)
+            available = ", ".join(sorted(packages.keys())) if packages else "(none)"
+            print(f"Error: unknown package '{package}'. Available: {available}", file=sys.stderr)
+            return 1
+    else:
+        # Inferred: active task's task.json.package → default_package → None
+        task_package = task_data.package if task_data else None
+        package = resolve_package(task_package, repo_root)
+
+    # Resolve branch: CLI → task.json → git auto-detect → None
+    branch = args.branch
+
+    if not branch:
+        if task_data and task_data.raw.get("branch"):
+            branch = task_data.raw["branch"]
+        else:
+            _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+            detected = branch_out.strip()
+            if detected:
+                branch = detected
+
+    return add_session(
+        args.title, args.commit, args.summary, extra_content,
+        auto_commit=not args.no_commit,
+        package=package,
+        branch=branch,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.trellis/scripts/common/__init__.py

@@ -0,0 +1,84 @@
+"""
+Common utilities for Trellis workflow scripts.
+
+This module provides shared functionality used by other Trellis scripts.
+"""
+
+import io
+import sys
+
+# =============================================================================
+# Windows Encoding Fix (MUST be at top, before any other output)
+# =============================================================================
+# On Windows, stdout defaults to the system code page (often GBK/CP936).
+# This causes UnicodeEncodeError when printing non-ASCII characters.
+#
+# Any script that imports from common will automatically get this fix.
+# =============================================================================
+
+
+def _configure_stream(stream: object) -> object:
+    """Configure a stream for UTF-8 encoding on Windows."""
+    # Try reconfigure() first (Python 3.7+, more reliable)
+    if hasattr(stream, "reconfigure"):
+        stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+        return stream
+    # Fallback: detach and rewrap with TextIOWrapper
+    elif hasattr(stream, "detach"):
+        return io.TextIOWrapper(
+            stream.detach(),  # type: ignore[union-attr]
+            encoding="utf-8",
+            errors="replace",
+        )
+    return stream
+
+
+if sys.platform == "win32":
+    sys.stdout = _configure_stream(sys.stdout)  # type: ignore[assignment]
+    sys.stderr = _configure_stream(sys.stderr)  # type: ignore[assignment]
+    sys.stdin = _configure_stream(sys.stdin)  # type: ignore[assignment]
+
+
+def configure_encoding() -> None:
+    """
+    Configure stdout/stderr/stdin for UTF-8 encoding on Windows.
+
+    This is automatically called when importing from common,
+    but can be called manually for scripts that don't import common.
+
+    Safe to call multiple times.
+    """
+    global sys
+    if sys.platform == "win32":
+        sys.stdout = _configure_stream(sys.stdout)  # type: ignore[assignment]
+        sys.stderr = _configure_stream(sys.stderr)  # type: ignore[assignment]
+        sys.stdin = _configure_stream(sys.stdin)  # type: ignore[assignment]
+
+
+from .paths import (
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    DIR_TASKS,
+    DIR_ARCHIVE,
+    DIR_SPEC,
+    DIR_SCRIPTS,
+    FILE_DEVELOPER,
+    FILE_CURRENT_TASK,
+    FILE_TASK_JSON,
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    check_developer,
+    get_tasks_dir,
+    get_workspace_dir,
+    get_active_journal_file,
+    count_lines,
+    get_current_task,
+    get_current_task_abs,
+    normalize_task_ref,
+    resolve_task_ref,
+    set_current_task,
+    clear_current_task,
+    has_current_task,
+    generate_task_date_prefix,
+)

.trellis/scripts/common/cli_adapter.py

@@ -0,0 +1,776 @@
+"""
+CLI Adapter for Multi-Platform Support.
+
+Abstracts differences between Claude Code, OpenCode, Cursor, iFlow, Codex, Kilo, Kiro Code, Gemini CLI, Antigravity, Windsurf, Qoder, CodeBuddy, GitHub Copilot, and Factory Droid interfaces.
+
+Supported platforms:
+- claude: Claude Code (default)
+- opencode: OpenCode
+- cursor: Cursor IDE
+- iflow: iFlow CLI
+- codex: Codex CLI (skills-based)
+- kilo: Kilo CLI
+- kiro: Kiro Code (skills-based)
+- gemini: Gemini CLI
+- antigravity: Antigravity (workflow-based)
+- windsurf: Windsurf (workflow-based)
+- qoder: Qoder
+- codebuddy: CodeBuddy
+- copilot: GitHub Copilot (VS Code)
+- droid: Factory Droid (commands-based)
+
+Usage:
+    from common.cli_adapter import CLIAdapter
+
+    adapter = CLIAdapter("opencode")
+    cmd = adapter.build_run_command(
+        agent="dispatch",
+        session_id="abc123",
+        prompt="Start the pipeline"
+    )
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar, Literal
+
+Platform = Literal[
+    "claude",
+    "opencode",
+    "cursor",
+    "iflow",
+    "codex",
+    "kilo",
+    "kiro",
+    "gemini",
+    "antigravity",
+    "windsurf",
+    "qoder",
+    "codebuddy",
+    "copilot",
+    "droid",
+]
+
+
+@dataclass
+class CLIAdapter:
+    """Adapter for different AI coding CLI tools."""
+
+    platform: Platform
+
+    # =========================================================================
+    # Agent Name Mapping
+    # =========================================================================
+
+    # OpenCode has built-in agents that cannot be overridden
+    # See: https://github.com/sst/opencode/issues/4271
+    # Note: Class-level constant, not a dataclass field
+    _AGENT_NAME_MAP: ClassVar[dict[Platform, dict[str, str]]] = {
+        "claude": {},  # No mapping needed
+        "opencode": {
+            "plan": "trellis-plan",  # 'plan' is built-in in OpenCode
+        },
+    }
+
+    def get_agent_name(self, agent: str) -> str:
+        """Get platform-specific agent name.
+
+        Args:
+            agent: Original agent name (e.g., 'plan', 'dispatch')
+
+        Returns:
+            Platform-specific agent name (e.g., 'trellis-plan' for OpenCode)
+        """
+        mapping = self._AGENT_NAME_MAP.get(self.platform, {})
+        return mapping.get(agent, agent)
+
+    # =========================================================================
+    # Agent Path
+    # =========================================================================
+
+    @property
+    def config_dir_name(self) -> str:
+        """Get platform-specific config directory name.
+
+        Returns:
+            Directory name ('.claude', '.opencode', '.cursor', '.iflow', '.codex', '.kilocode', '.kiro', '.gemini', '.agent', '.windsurf', '.qoder', or '.codebuddy')
+        """
+        if self.platform == "opencode":
+            return ".opencode"
+        elif self.platform == "cursor":
+            return ".cursor"
+        elif self.platform == "iflow":
+            return ".iflow"
+        elif self.platform == "codex":
+            return ".codex"
+        elif self.platform == "kilo":
+            return ".kilocode"
+        elif self.platform == "kiro":
+            return ".kiro"
+        elif self.platform == "gemini":
+            return ".gemini"
+        elif self.platform == "antigravity":
+            return ".agent"
+        elif self.platform == "windsurf":
+            return ".windsurf"
+        elif self.platform == "qoder":
+            return ".qoder"
+        elif self.platform == "codebuddy":
+            return ".codebuddy"
+        elif self.platform == "copilot":
+            return ".github/copilot"
+        elif self.platform == "droid":
+            return ".factory"
+        else:
+            return ".claude"
+
+    def get_config_dir(self, project_root: Path) -> Path:
+        """Get platform-specific config directory.
+
+        Args:
+            project_root: Project root directory
+
+        Returns:
+            Path to config directory (.claude, .opencode, .cursor, .iflow, .codex, .kilocode, .kiro, .gemini, .agent, .windsurf, .qoder, or .codebuddy)
+        """
+        return project_root / self.config_dir_name
+
+    def get_agent_path(self, agent: str, project_root: Path) -> Path:
+        """Get path to agent definition file.
+
+        Args:
+            agent: Agent name (original, before mapping)
+            project_root: Project root directory
+
+        Returns:
+            Path to agent definition file (.md for most platforms, .toml for Codex)
+        """
+        mapped_name = self.get_agent_name(agent)
+        if self.platform == "codex":
+            return self.get_config_dir(project_root) / "agents" / f"{mapped_name}.toml"
+        return self.get_config_dir(project_root) / "agents" / f"{mapped_name}.md"
+
+    def get_commands_path(self, project_root: Path, *parts: str) -> Path:
+        """Get path to commands directory or specific command file.
+
+        Args:
+            project_root: Project root directory
+            *parts: Additional path parts (e.g., 'trellis', 'finish-work.md')
+
+        Returns:
+            Path to commands directory or file
+
+        Note:
+            Cursor uses prefix naming: .cursor/commands/trellis-<name>.md
+            Antigravity uses workflow directory: .agent/workflows/<name>.md
+            Windsurf uses workflow directory: .windsurf/workflows/trellis-<name>.md
+            Copilot uses prompt files: .github/prompts/<name>.prompt.md
+            Claude/OpenCode use subdirectory: .claude/commands/trellis/<name>.md
+        """
+        if self.platform == "windsurf":
+            workflow_dir = self.get_config_dir(project_root) / "workflows"
+            if not parts:
+                return workflow_dir
+            if len(parts) >= 2 and parts[0] == "trellis":
+                filename = parts[-1]
+                return workflow_dir / f"trellis-{filename}"
+            return workflow_dir / Path(*parts)
+
+        if self.platform in ("antigravity", "kilo"):
+            workflow_dir = self.get_config_dir(project_root) / "workflows"
+            if not parts:
+                return workflow_dir
+            if len(parts) >= 2 and parts[0] == "trellis":
+                filename = parts[-1]
+                return workflow_dir / filename
+            return workflow_dir / Path(*parts)
+
+        if self.platform == "copilot":
+            prompts_dir = project_root / ".github" / "prompts"
+            if not parts:
+                return prompts_dir
+            if len(parts) >= 2 and parts[0] == "trellis":
+                filename = parts[-1]
+                if filename.endswith(".md"):
+                    filename = filename[:-3]
+                return prompts_dir / f"{filename}.prompt.md"
+            return prompts_dir / Path(*parts)
+
+        if not parts:
+            return self.get_config_dir(project_root) / "commands"
+
+        # Cursor uses prefix naming instead of subdirectory
+        if self.platform == "cursor" and len(parts) >= 2 and parts[0] == "trellis":
+            # Convert trellis/<name>.md to trellis-<name>.md
+            filename = parts[-1]
+            return (
+                self.get_config_dir(project_root) / "commands" / f"trellis-{filename}"
+            )
+
+        return self.get_config_dir(project_root) / "commands" / Path(*parts)
+
+    def get_trellis_command_path(self, name: str) -> str:
+        """Get relative path to a trellis command file.
+
+        Args:
+            name: Command name without extension (e.g., 'finish-work', 'check')
+
+        Returns:
+            Relative path string for use in JSONL entries
+
+        Note:
+            Cursor: .cursor/commands/trellis-<name>.md
+            Codex: .agents/skills/trellis-<name>/SKILL.md
+            Kiro: .kiro/skills/trellis-<name>/SKILL.md
+            Gemini: .gemini/commands/trellis/<name>.toml
+            Antigravity: .agent/workflows/<name>.md
+            Windsurf: .windsurf/workflows/trellis-<name>.md
+            Others: .{platform}/commands/trellis/<name>.md
+        """
+        if self.platform == "cursor":
+            return f".cursor/commands/trellis-{name}.md"
+        elif self.platform == "codex":
+            # 0.5.0-beta.0 renamed all skill dirs to add the `trellis-` prefix
+            # (see that release's manifest for the 60+ rename entries).
+            return f".agents/skills/trellis-{name}/SKILL.md"
+        elif self.platform == "kiro":
+            return f".kiro/skills/trellis-{name}/SKILL.md"
+        elif self.platform == "gemini":
+            return f".gemini/commands/trellis/{name}.toml"
+        elif self.platform == "antigravity":
+            return f".agent/workflows/{name}.md"
+        elif self.platform == "windsurf":
+            return f".windsurf/workflows/trellis-{name}.md"
+        elif self.platform == "kilo":
+            return f".kilocode/workflows/{name}.md"
+        elif self.platform == "copilot":
+            return f".github/prompts/{name}.prompt.md"
+        elif self.platform == "droid":
+            return f".factory/commands/trellis/{name}.md"
+        else:
+            return f"{self.config_dir_name}/commands/trellis/{name}.md"
+
+    # =========================================================================
+    # Environment Variables
+    # =========================================================================
+
+    def get_non_interactive_env(self) -> dict[str, str]:
+        """Get environment variables for non-interactive mode.
+
+        Returns:
+            Dict of environment variables to set
+        """
+        if self.platform == "opencode":
+            return {"OPENCODE_NON_INTERACTIVE": "1"}
+        elif self.platform == "iflow":
+            return {"IFLOW_NON_INTERACTIVE": "1"}
+        elif self.platform == "codex":
+            return {"CODEX_NON_INTERACTIVE": "1"}
+        elif self.platform == "kiro":
+            return {"KIRO_NON_INTERACTIVE": "1"}
+        elif self.platform == "gemini":
+            return {}  # Gemini CLI doesn't have a non-interactive env var
+        elif self.platform == "antigravity":
+            return {}
+        elif self.platform == "windsurf":
+            return {}
+        elif self.platform == "qoder":
+            return {}
+        elif self.platform == "codebuddy":
+            return {}
+        elif self.platform == "copilot":
+            return {}
+        elif self.platform == "droid":
+            return {}
+        else:
+            return {"CLAUDE_NON_INTERACTIVE": "1"}
+
+    # =========================================================================
+    # CLI Command Building
+    # =========================================================================
+
+    def build_run_command(
+        self,
+        agent: str,
+        prompt: str,
+        session_id: str | None = None,
+        skip_permissions: bool = True,
+        verbose: bool = True,
+        json_output: bool = True,
+    ) -> list[str]:
+        """Build CLI command for running an agent.
+
+        Args:
+            agent: Agent name (will be mapped if needed)
+            prompt: Prompt to send to the agent
+            session_id: Optional session ID (Claude Code only for creation)
+            skip_permissions: Whether to skip permission prompts
+            verbose: Whether to enable verbose output
+            json_output: Whether to use JSON output format
+
+        Returns:
+            List of command arguments
+        """
+        mapped_agent = self.get_agent_name(agent)
+
+        if self.platform == "opencode":
+            cmd = ["opencode", "run"]
+            cmd.extend(["--agent", mapped_agent])
+
+            # Note: OpenCode 'run' mode is non-interactive by default
+            # No equivalent to Claude Code's --dangerously-skip-permissions
+            # See: https://github.com/anomalyco/opencode/issues/9070
+
+            if json_output:
+                cmd.extend(["--format", "json"])
+
+            if verbose:
+                cmd.extend(["--log-level", "DEBUG", "--print-logs"])
+
+            # Note: OpenCode doesn't support --session-id on creation
+            # Session ID must be extracted from logs after startup
+
+            cmd.append(prompt)
+
+        elif self.platform == "iflow":
+            cmd = ["iflow", "-y", "-p"]
+            cmd.append(f"${mapped_agent} {prompt}")
+        elif self.platform == "codex":
+            cmd = ["codex", "exec"]
+            cmd.append(prompt)
+        elif self.platform == "kiro":
+            cmd = ["kiro", "run", prompt]
+        elif self.platform == "gemini":
+            cmd = ["gemini"]
+            cmd.append(prompt)
+        elif self.platform == "antigravity":
+            raise ValueError(
+                "Antigravity workflows are UI slash commands; CLI agent run is not supported."
+            )
+        elif self.platform == "windsurf":
+            raise ValueError(
+                "Windsurf workflows are UI slash commands; CLI agent run is not supported."
+            )
+        elif self.platform == "qoder":
+            cmd = ["qodercli", "-p", prompt]
+        elif self.platform == "codebuddy":
+            raise ValueError(
+                "CodeBuddy does not support non-interactive mode (no CLI agent)"
+            )
+        elif self.platform == "copilot":
+            raise ValueError(
+                "GitHub Copilot is IDE-only; CLI agent run is not supported."
+            )
+        elif self.platform == "droid":
+            raise ValueError(
+                "Factory Droid CLI agent run is not yet supported."
+            )
+
+        else:  # claude
+            cmd = ["claude", "-p"]
+            cmd.extend(["--agent", mapped_agent])
+
+            if session_id:
+                cmd.extend(["--session-id", session_id])
+
+            if skip_permissions:
+                cmd.append("--dangerously-skip-permissions")
+
+            if json_output:
+                cmd.extend(["--output-format", "stream-json"])
+
+            if verbose:
+                cmd.append("--verbose")
+
+            cmd.append(prompt)
+
+        return cmd
+
+    def build_resume_command(self, session_id: str) -> list[str]:
+        """Build CLI command for resuming a session.
+
+        Args:
+            session_id: Session ID to resume (ignored for iFlow)
+
+        Returns:
+            List of command arguments
+        """
+        if self.platform == "opencode":
+            return ["opencode", "run", "--session", session_id]
+        elif self.platform == "iflow":
+            # iFlow uses -c to continue most recent conversation
+            # session_id is ignored as iFlow doesn't support session IDs
+            return ["iflow", "-c"]
+        elif self.platform == "codex":
+            return ["codex", "resume", session_id]
+        elif self.platform == "kiro":
+            return ["kiro", "resume", session_id]
+        elif self.platform == "gemini":
+            return ["gemini", "--resume", session_id]
+        elif self.platform == "antigravity":
+            raise ValueError(
+                "Antigravity workflows are UI slash commands; CLI resume is not supported."
+            )
+        elif self.platform == "windsurf":
+            raise ValueError(
+                "Windsurf workflows are UI slash commands; CLI resume is not supported."
+            )
+        elif self.platform == "qoder":
+            return ["qodercli", "--resume", session_id]
+        elif self.platform == "codebuddy":
+            raise ValueError(
+                "CodeBuddy does not support non-interactive mode (no CLI agent)"
+            )
+        elif self.platform == "copilot":
+            raise ValueError(
+                "GitHub Copilot is IDE-only; CLI resume is not supported."
+            )
+        elif self.platform == "droid":
+            raise ValueError(
+                "Factory Droid CLI resume is not yet supported."
+            )
+        else:
+            return ["claude", "--resume", session_id]
+
+    def get_resume_command_str(self, session_id: str, cwd: str | None = None) -> str:
+        """Get human-readable resume command string.
+
+        Args:
+            session_id: Session ID to resume
+            cwd: Optional working directory to cd into
+
+        Returns:
+            Command string for display
+        """
+        cmd = self.build_resume_command(session_id)
+        cmd_str = " ".join(cmd)
+
+        if cwd:
+            return f"cd {cwd} && {cmd_str}"
+        return cmd_str
+
+    # =========================================================================
+    # Platform Detection Helpers
+    # =========================================================================
+
+    @property
+    def is_opencode(self) -> bool:
+        """Check if platform is OpenCode."""
+        return self.platform == "opencode"
+
+    @property
+    def is_claude(self) -> bool:
+        """Check if platform is Claude Code."""
+        return self.platform == "claude"
+
+    @property
+    def is_cursor(self) -> bool:
+        """Check if platform is Cursor."""
+        return self.platform == "cursor"
+
+    @property
+    def is_iflow(self) -> bool:
+        """Check if platform is iFlow CLI."""
+        return self.platform == "iflow"
+
+    @property
+    def cli_name(self) -> str:
+        """Get CLI executable name.
+
+        Note: Cursor doesn't have a CLI tool, returns None-like value.
+        """
+        if self.is_opencode:
+            return "opencode"
+        elif self.is_cursor:
+            return "cursor"  # Note: Cursor is IDE-only, no CLI
+        elif self.platform == "iflow":
+            return "iflow"
+        elif self.platform == "kiro":
+            return "kiro"
+        elif self.platform == "gemini":
+            return "gemini"
+        elif self.platform == "antigravity":
+            return "agy"
+        elif self.platform == "windsurf":
+            return "windsurf"
+        elif self.platform == "qoder":
+            return "qodercli"
+        elif self.platform == "codebuddy":
+            return "codebuddy"
+        elif self.platform == "copilot":
+            return "copilot"
+        elif self.platform == "droid":
+            return "droid"
+        else:
+            return "claude"
+
+    @property
+    def supports_cli_agents(self) -> bool:
+        """Check if platform supports running agents via CLI.
+
+        Claude Code, OpenCode, iFlow, and Codex support CLI agent execution.
+        Cursor is IDE-only and doesn't support CLI agents.
+        """
+        return self.platform in ("claude", "opencode", "iflow", "codex")
+
+    @property
+    def requires_agent_definition_file(self) -> bool:
+        """Check if platform requires an agent definition file (.md/.toml) to run.
+
+        Claude Code, OpenCode, iFlow: require agent .md files (--agent flag).
+        Codex: auto-discovers agents from .codex/agents/*.toml, no --agent flag.
+        """
+        return self.platform in ("claude", "opencode", "iflow")
+
+    # =========================================================================
+    # Session ID Handling
+    # =========================================================================
+
+    @property
+    def supports_session_id_on_create(self) -> bool:
+        """Check if platform supports specifying session ID on creation.
+
+        Claude Code: Yes (--session-id)
+        OpenCode: No (auto-generated, extract from logs)
+        iFlow: No (no session ID support)
+        """
+        return self.platform == "claude"
+
+    def extract_session_id_from_log(self, log_content: str) -> str | None:
+        """Extract session ID from log output (OpenCode only).
+
+        OpenCode generates session IDs in format: ses_xxx
+
+        Args:
+            log_content: Log file content
+
+        Returns:
+            Session ID if found, None otherwise
+        """
+        import re
+
+        # OpenCode session ID pattern
+        match = re.search(r"ses_[a-zA-Z0-9]+", log_content)
+        if match:
+            return match.group(0)
+        return None
+
+
+# =============================================================================
+# Factory Function
+# =============================================================================
+
+
+def get_cli_adapter(platform: str = "claude") -> CLIAdapter:
+    """Get CLI adapter for the specified platform.
+
+    Args:
+        platform: Platform name ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'windsurf', 'qoder', or 'codebuddy')
+
+    Returns:
+        CLIAdapter instance
+
+    Raises:
+        ValueError: If platform is not supported
+    """
+    if platform not in (
+        "claude",
+        "opencode",
+        "cursor",
+        "iflow",
+        "codex",
+        "kilo",
+        "kiro",
+        "gemini",
+        "antigravity",
+        "windsurf",
+        "qoder",
+        "codebuddy",
+        "copilot",
+        "droid",
+    ):
+        raise ValueError(
+            f"Unsupported platform: {platform} (must be 'claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'windsurf', 'qoder', 'codebuddy', 'copilot', or 'droid')"
+        )
+
+    return CLIAdapter(platform=platform)  # type: ignore
+
+
+_ALL_PLATFORM_CONFIG_DIRS = (
+    ".claude",
+    ".cursor",
+    ".iflow",
+    ".opencode",
+    ".codex",
+    ".kilocode",
+    ".kiro",
+    ".gemini",
+    ".agent",
+    ".windsurf",
+    ".qoder",
+    ".codebuddy",
+    ".github/copilot",
+    ".factory",
+)
+"""Platform-specific config directory names used by detect_platform exclusion
+checks. `.agents/skills/` is NOT listed here: it is a shared cross-platform
+layer (written by Codex, also consumed by Amp/Cline/Warp/etc. via the
+agentskills.io standard), not a single-platform signal. Its presence must not
+block detection of Kiro, Antigravity, Windsurf, or other platforms."""
+
+
+def _has_other_platform_dir(project_root: Path, exclude: set[str]) -> bool:
+    """Check if any platform config dir exists besides those in *exclude*."""
+    return any(
+        (project_root / d).is_dir()
+        for d in _ALL_PLATFORM_CONFIG_DIRS
+        if d not in exclude
+    )
+
+
+def detect_platform(project_root: Path) -> Platform:
+    """Auto-detect platform based on existing config directories.
+
+    Detection order:
+    1. TRELLIS_PLATFORM environment variable (if set)
+    2. .opencode directory exists → opencode
+    3. .iflow directory exists → iflow
+    4. .cursor directory exists (without .claude) → cursor
+    5. .codex exists and no other platform dirs → codex
+    6. .kilocode directory exists → kilo
+    7. .kiro/skills exists and no other platform dirs → kiro
+    8. .gemini directory exists → gemini
+    9. .agent/workflows exists and no other platform dirs → antigravity
+    10. .windsurf/workflows exists and no other platform dirs → windsurf
+    11. .codebuddy directory exists → codebuddy
+    12. .qoder directory exists → qoder
+    13. Default → claude
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        Detected platform ('claude', 'opencode', 'cursor', 'iflow', 'codex', 'kilo', 'kiro', 'gemini', 'antigravity', 'windsurf', 'qoder', 'codebuddy', or default 'claude')
+    """
+    import os
+
+    # Check environment variable first
+    env_platform = os.environ.get("TRELLIS_PLATFORM", "").lower()
+    if env_platform in (
+        "claude",
+        "opencode",
+        "cursor",
+        "iflow",
+        "codex",
+        "kilo",
+        "kiro",
+        "gemini",
+        "antigravity",
+        "windsurf",
+        "qoder",
+        "codebuddy",
+        "copilot",
+        "droid",
+    ):
+        return env_platform  # type: ignore
+
+    # Check for .opencode directory (OpenCode-specific)
+    if (project_root / ".opencode").is_dir():
+        return "opencode"
+
+    # Check for .iflow directory (iFlow-specific)
+    if (project_root / ".iflow").is_dir():
+        return "iflow"
+
+    # Check for .cursor directory (Cursor-specific)
+    # Only detect as cursor if .claude doesn't exist (to avoid confusion)
+    if (project_root / ".cursor").is_dir() and not (project_root / ".claude").is_dir():
+        return "cursor"
+
+    # Check for .gemini directory (Gemini CLI-specific)
+    if (project_root / ".gemini").is_dir():
+        return "gemini"
+
+    # Check for .codex directory (Codex-specific)
+    # .agents/skills/ alone does NOT trigger codex detection (it's a shared standard)
+    if (project_root / ".codex").is_dir() and not _has_other_platform_dir(
+        project_root, {".codex", ".agents"}
+    ):
+        return "codex"
+
+    # Check for .kilocode directory (Kilo-specific)
+    if (project_root / ".kilocode").is_dir():
+        return "kilo"
+
+    # Check for Kiro skills directory only when no other platform config exists
+    if (project_root / ".kiro" / "skills").is_dir() and not _has_other_platform_dir(
+        project_root, {".kiro"}
+    ):
+        return "kiro"
+
+    # Check for Antigravity workflow directory only when no other platform config exists
+    if (
+        project_root / ".agent" / "workflows"
+    ).is_dir() and not _has_other_platform_dir(
+        project_root, {".agent", ".gemini"}
+    ):
+        return "antigravity"
+
+    # Check for Windsurf workflow directory only when no other platform config exists
+    if (
+        project_root / ".windsurf" / "workflows"
+    ).is_dir() and not _has_other_platform_dir(
+        project_root, {".windsurf"}
+    ):
+        return "windsurf"
+
+    # Check for .codebuddy directory (CodeBuddy-specific)
+    if (project_root / ".codebuddy").is_dir():
+        return "codebuddy"
+
+    # Check for .qoder directory (Qoder-specific)
+    if (project_root / ".qoder").is_dir():
+        return "qoder"
+
+    # Check for .github/copilot directory (GitHub Copilot-specific)
+    if (project_root / ".github" / "copilot").is_dir():
+        return "copilot"
+
+    # Check for .factory directory (Factory Droid-specific)
+    if (project_root / ".factory").is_dir():
+        return "droid"
+
+    # Fallback: checkout only has the Codex shared-skills layer
+    # (.agents/skills/trellis-* dirs) and no explicit platform config dir.
+    # Happens on fresh clones where .codex/ is gitignored/absent but the
+    # shared skills were committed to git. Must guard against the case
+    # where .claude/ or any other platform dir also exists — .agents/skills/
+    # can legitimately coexist with any platform as a shared consumption
+    # layer for Amp/Cline/Warp/etc.
+    agents_skills = project_root / ".agents" / "skills"
+    if agents_skills.is_dir() and not _has_other_platform_dir(
+        project_root, set()
+    ):
+        try:
+            for entry in agents_skills.iterdir():
+                if entry.is_dir() and entry.name.startswith("trellis-"):
+                    return "codex"
+        except OSError:
+            pass
+
+    return "claude"
+
+
+def get_cli_adapter_auto(project_root: Path) -> CLIAdapter:
+    """Get CLI adapter with auto-detected platform.
+
+    Args:
+        project_root: Project root directory
+
+    Returns:
+        CLIAdapter instance for detected platform
+    """
+    platform = detect_platform(project_root)
+    return CLIAdapter(platform=platform)

.trellis/scripts/common/config.py

@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""
+Trellis configuration reader.
+
+Reads settings from .trellis/config.yaml with sensible defaults.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, get_repo_root
+
+
+# =============================================================================
+# YAML Simple Parser (no dependencies)
+# =============================================================================
+
+
+def _unquote(s: str) -> str:
+    """Remove exactly one layer of matching surrounding quotes.
+
+    Unlike str.strip('"'), this only removes the outermost pair,
+    preserving any nested quotes inside the value.
+
+    Examples:
+        _unquote('"hello"')        -> 'hello'
+        _unquote("'hello'")        -> 'hello'
+        _unquote('"echo \\'hi\\'"')  -> "echo 'hi'"
+        _unquote('hello')          -> 'hello'
+        _unquote('"hello\\'')       -> '"hello\\''  (mismatched, unchanged)
+    """
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ('"', "'"):
+        return s[1:-1]
+    return s
+
+
+def parse_simple_yaml(content: str) -> dict:
+    """Parse simple YAML with nested dict support (no dependencies).
+
+    Supports:
+        - key: value (string)
+        - key: (followed by list items)
+            - item1
+            - item2
+        - key: (followed by nested dict)
+            nested_key: value
+            nested_key2:
+              - item
+
+    Uses indentation to detect nesting (2+ spaces deeper = child).
+
+    Args:
+        content: YAML content string.
+
+    Returns:
+        Parsed dict (values can be str, list[str], or dict).
+    """
+    lines = content.splitlines()
+    result: dict = {}
+    _parse_yaml_block(lines, 0, 0, result)
+    return result
+
+
+def _parse_yaml_block(
+    lines: list[str], start: int, min_indent: int, target: dict
+) -> int:
+    """Parse a YAML block into target dict, returning next line index."""
+    i = start
+    current_list: list | None = None
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+
+        # Skip empty lines and comments
+        if not stripped or stripped.startswith("#"):
+            i += 1
+            continue
+
+        # Calculate indentation
+        indent = len(line) - len(line.lstrip())
+
+        # If dedented past our block, we're done
+        if indent < min_indent:
+            break
+
+        if stripped.startswith("- "):
+            if current_list is not None:
+                current_list.append(_unquote(stripped[2:].strip()))
+            i += 1
+        elif ":" in stripped:
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = _unquote(value.strip())
+            current_list = None
+
+            if value:
+                # key: value
+                target[key] = value
+                i += 1
+            else:
+                # key: (no value) — peek ahead to determine list vs nested dict
+                next_i, next_line = _next_content_line(lines, i + 1)
+                if next_i >= len(lines):
+                    target[key] = {}
+                    i = next_i
+                elif next_line.strip().startswith("- "):
+                    # It's a list
+                    current_list = []
+                    target[key] = current_list
+                    i += 1
+                else:
+                    next_indent = len(next_line) - len(next_line.lstrip())
+                    if next_indent > indent:
+                        # It's a nested dict
+                        nested: dict = {}
+                        target[key] = nested
+                        i = _parse_yaml_block(lines, i + 1, next_indent, nested)
+                    else:
+                        # Empty value, same or less indent follows
+                        target[key] = {}
+                        i += 1
+        else:
+            i += 1
+
+    return i
+
+
+def _next_content_line(lines: list[str], start: int) -> tuple[int, str]:
+    """Find the next non-empty, non-comment line."""
+    i = start
+    while i < len(lines):
+        stripped = lines[i].strip()
+        if stripped and not stripped.startswith("#"):
+            return i, lines[i]
+        i += 1
+    return i, ""
+
+
+# Defaults
+DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
+DEFAULT_MAX_JOURNAL_LINES = 2000
+
+CONFIG_FILE = "config.yaml"
+
+
+def _is_true_config_value(value: object) -> bool:
+    """Return True when a config value represents an enabled flag."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() == "true"
+    return False
+
+
+def _get_config_path(repo_root: Path | None = None) -> Path:
+    """Get path to config.yaml."""
+    root = repo_root or get_repo_root()
+    return root / DIR_WORKFLOW / CONFIG_FILE
+
+
+def _load_config(repo_root: Path | None = None) -> dict:
+    """Load and parse config.yaml. Returns empty dict on any error."""
+    config_file = _get_config_path(repo_root)
+    try:
+        content = config_file.read_text(encoding="utf-8")
+        return parse_simple_yaml(content)
+    except (OSError, IOError):
+        return {}
+
+
+def get_session_commit_message(repo_root: Path | None = None) -> str:
+    """Get the commit message for auto-committing session records."""
+    config = _load_config(repo_root)
+    return config.get("session_commit_message", DEFAULT_SESSION_COMMIT_MESSAGE)
+
+
+def get_max_journal_lines(repo_root: Path | None = None) -> int:
+    """Get the maximum lines per journal file."""
+    config = _load_config(repo_root)
+    value = config.get("max_journal_lines", DEFAULT_MAX_JOURNAL_LINES)
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        return DEFAULT_MAX_JOURNAL_LINES
+
+
+def get_hooks(event: str, repo_root: Path | None = None) -> list[str]:
+    """Get hook commands for a lifecycle event.
+
+    Args:
+        event: Event name (e.g. "after_create", "after_archive").
+        repo_root: Repository root path.
+
+    Returns:
+        List of shell commands to execute, empty if none configured.
+    """
+    config = _load_config(repo_root)
+    hooks = config.get("hooks")
+    if not isinstance(hooks, dict):
+        return []
+    commands = hooks.get(event)
+    if isinstance(commands, list):
+        return [str(c) for c in commands]
+    return []
+
+
+# =============================================================================
+# Monorepo / Packages
+# =============================================================================
+
+
+def get_packages(repo_root: Path | None = None) -> dict[str, dict] | None:
+    """Get monorepo package declarations.
+
+    Returns:
+        Dict mapping package name to its config (path, type, etc.),
+        or None if not configured (single-repo mode).
+
+    Example return:
+        {"cli": {"path": "packages/cli"}, "docs-site": {"path": "docs-site", "type": "submodule"}}
+    """
+    config = _load_config(repo_root)
+    packages = config.get("packages")
+    if not isinstance(packages, dict):
+        return None
+    # Ensure each value is a dict (filter out scalar entries)
+    filtered = {k: v for k, v in packages.items() if isinstance(v, dict)}
+    if not filtered:
+        return None
+    return filtered
+
+
+def get_default_package(repo_root: Path | None = None) -> str | None:
+    """Get the default package name from config.
+
+    Returns:
+        Package name string, or None if not configured.
+    """
+    config = _load_config(repo_root)
+    value = config.get("default_package")
+    return str(value) if value else None
+
+
+def get_submodule_packages(repo_root: Path | None = None) -> dict[str, str]:
+    """Get packages that are git submodules.
+
+    Returns:
+        Dict mapping package name to its path for submodule-type packages.
+        Empty dict if none configured.
+
+    Example return:
+        {"docs-site": "docs-site"}
+    """
+    packages = get_packages(repo_root)
+    if packages is None:
+        return {}
+    return {
+        name: cfg.get("path", name)
+        for name, cfg in packages.items()
+        if cfg.get("type") == "submodule"
+    }
+
+
+def get_git_packages(repo_root: Path | None = None) -> dict[str, str]:
+    """Get packages that have their own independent git repository.
+
+    These are sub-directories with their own .git (not submodules),
+    marked with ``git: true`` in config.yaml.
+
+    Returns:
+        Dict mapping package name to its path for git-repo packages.
+        Empty dict if none configured.
+
+    Example config::
+
+        packages:
+          backend:
+            path: iqs
+            git: true
+
+    Example return::
+
+        {"backend": "iqs"}
+    """
+    packages = get_packages(repo_root)
+    if packages is None:
+        return {}
+    return {
+        name: cfg.get("path", name)
+        for name, cfg in packages.items()
+        if _is_true_config_value(cfg.get("git"))
+    }
+
+
+def is_monorepo(repo_root: Path | None = None) -> bool:
+    """Check if the project is configured as a monorepo (has packages in config)."""
+    return get_packages(repo_root) is not None
+
+
+def get_spec_base(package: str | None = None, repo_root: Path | None = None) -> str:
+    """Get the spec directory base path relative to .trellis/.
+
+    Single-repo: returns "spec"
+    Monorepo with package: returns "spec/<package>"
+    Monorepo without package: returns "spec" (caller should specify package)
+    """
+    if package and is_monorepo(repo_root):
+        return f"spec/{package}"
+    return "spec"
+
+
+def validate_package(package: str, repo_root: Path | None = None) -> bool:
+    """Check if a package name is valid in this project.
+
+    Single-repo (no packages configured): always returns True.
+    Monorepo: returns True only if package exists in config.yaml packages.
+    """
+    packages = get_packages(repo_root)
+    if packages is None:
+        return True  # Single-repo, no validation needed
+    return package in packages
+
+
+def resolve_package(
+    task_package: str | None = None,
+    repo_root: Path | None = None,
+) -> str | None:
+    """Resolve package from inferred sources with validation.
+
+    Checks in order: task_package → default_package.
+    Invalid inferred values print a warning to stderr and are skipped.
+
+    Returns:
+        Resolved package name, or None if no valid package found.
+
+    Note:
+        CLI --package should be validated separately by the caller
+        (fail-fast with available packages list on error).
+    """
+    packages = get_packages(repo_root)
+    if packages is None:
+        return None  # Single-repo, no package needed
+
+    # Try task_package (guard against non-string values from malformed JSON)
+    if task_package and isinstance(task_package, str):
+        if task_package in packages:
+            return task_package
+        print(
+            f"Warning: task.json package '{task_package}' not found in config, skipping",
+            file=sys.stderr,
+        )
+
+    # Try default_package
+    default = get_default_package(repo_root)
+    if default:
+        if default in packages:
+            return default
+        print(
+            f"Warning: default_package '{default}' not found in config, skipping",
+            file=sys.stderr,
+        )
+
+    return None
+
+
+def get_spec_scope(repo_root: Path | None = None) -> list[str] | str | None:
+    """Get session.spec_scope configuration.
+
+    Returns:
+        list[str]: Package names to include in spec scanning.
+        str: "active_task" to use current task's package.
+        None: No scope configured (scan all packages).
+    """
+    config = _load_config(repo_root)
+    session = config.get("session")
+    if not isinstance(session, dict):
+        return None
+
+    scope = session.get("spec_scope")
+    if scope is None:
+        return None
+    if isinstance(scope, str):
+        return scope  # e.g. "active_task"
+    if isinstance(scope, list):
+        return [str(s) for s in scope]
+    return None

.trellis/scripts/common/developer.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Developer management utilities.
+
+Provides:
+    init_developer     - Initialize developer
+    ensure_developer   - Ensure developer is initialized (exit if not)
+    show_developer_info - Show developer information
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import (
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    DIR_TASKS,
+    FILE_DEVELOPER,
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    check_developer,
+)
+
+
+# =============================================================================
+# Developer Initialization
+# =============================================================================
+
+def init_developer(name: str, repo_root: Path | None = None) -> bool:
+    """Initialize developer.
+
+    Creates:
+        - .trellis/.developer file with developer info
+        - .trellis/workspace/<name>/ directory structure
+        - Initial journal file and index.md
+
+    Args:
+        name: Developer name.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success, False on error.
+    """
+    if not name:
+        print("Error: developer name is required", file=sys.stderr)
+        return False
+
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+    workspace_dir = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / name
+
+    # Create .developer file
+    initialized_at = datetime.now().isoformat()
+    try:
+        dev_file.write_text(
+            f"name={name}\ninitialized_at={initialized_at}\n",
+            encoding="utf-8"
+        )
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create .developer file: {e}", file=sys.stderr)
+        return False
+
+    # Create workspace directory structure
+    try:
+        workspace_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create workspace directory: {e}", file=sys.stderr)
+        return False
+
+    # Create initial journal file
+    journal_file = workspace_dir / f"{FILE_JOURNAL_PREFIX}1.md"
+    if not journal_file.exists():
+        today = datetime.now().strftime("%Y-%m-%d")
+        journal_content = f"""# Journal - {name} (Part 1)
+
+> AI development session journal
+> Started: {today}
+
+---
+
+"""
+        try:
+            journal_file.write_text(journal_content, encoding="utf-8")
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create journal file: {e}", file=sys.stderr)
+            return False
+
+    # Create index.md with markers for auto-update
+    index_file = workspace_dir / "index.md"
+    if not index_file.exists():
+        index_content = f"""# Workspace Index - {name}
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 0
+- **Last Active**: -
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~0 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits | Branch |
+|---|------|-------|---------|--------|
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to journal files
+- New journal file created when current exceeds 2000 lines
+- Use `add_session.py` to record sessions
+"""
+        try:
+            index_file.write_text(index_content, encoding="utf-8")
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create index.md: {e}", file=sys.stderr)
+            return False
+
+    print(f"Developer initialized: {name}")
+    print(f"  .developer file: {dev_file}")
+    print(f"  Workspace dir: {workspace_dir}")
+
+    return True
+
+
+def ensure_developer(repo_root: Path | None = None) -> None:
+    """Ensure developer is initialized, exit if not.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    if not check_developer(repo_root):
+        print("Error: Developer not initialized.", file=sys.stderr)
+        print(f"Run: python3 ./{DIR_WORKFLOW}/scripts/init_developer.py <your-name>", file=sys.stderr)
+        sys.exit(1)
+
+
+def show_developer_info(repo_root: Path | None = None) -> None:
+    """Show developer information.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+
+    if not developer:
+        print("Developer: (not initialized)")
+    else:
+        print(f"Developer: {developer}")
+        print(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
+        print(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    show_developer_info()

.trellis/scripts/common/git.py

@@ -0,0 +1,31 @@
+"""
+Git command execution utility.
+
+Single source of truth for running git commands across all Trellis scripts.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def run_git(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
+    """Run a git command and return (returncode, stdout, stderr).
+
+    Uses UTF-8 encoding with -c i18n.logOutputEncoding=UTF-8 to ensure
+    consistent output across all platforms (Windows, macOS, Linux).
+    """
+    try:
+        git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
+        result = subprocess.run(
+            git_args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return result.returncode, result.stdout, result.stderr
+    except Exception as e:
+        return 1, "", str(e)

.trellis/scripts/common/git_context.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Git and Session Context utilities.
+
+Entry shim — delegates to session_context and packages_context.
+
+Provides:
+    output_json - Output context in JSON format
+    output_text - Output context in text format
+"""
+
+from __future__ import annotations
+
+import json
+
+from .git import run_git
+from .session_context import (
+    get_context_json,
+    get_context_text,
+    get_context_record_json,
+    get_context_text_record,
+    output_json,
+    output_text,
+)
+from .packages_context import (
+    get_context_packages_text,
+    get_context_packages_json,
+)
+from .workflow_phase import (
+    filter_platform,
+    get_phase_index,
+    get_step,
+)
+
+# Backward-compatible alias — external modules import this name
+_run_git_command = run_git
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> None:
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Get Session Context for AI Agent")
+    parser.add_argument(
+        "--json",
+        "-j",
+        action="store_true",
+        help="Output in JSON format (works with any --mode)",
+    )
+    parser.add_argument(
+        "--mode",
+        "-m",
+        choices=["default", "record", "packages", "phase"],
+        default="default",
+        help="Output mode: default (full context), record (for record-session), packages (package info only), phase (workflow step extraction)",
+    )
+    parser.add_argument(
+        "--step",
+        help="Step id for --mode phase, e.g. 1.1, 2.2. Omit to get the Phase Index.",
+    )
+    parser.add_argument(
+        "--platform",
+        help="Platform name for --mode phase, e.g. cursor, claude-code. Filters platform-tagged blocks.",
+    )
+
+    args = parser.parse_args()
+
+    if args.mode == "record":
+        if args.json:
+            print(json.dumps(get_context_record_json(), indent=2, ensure_ascii=False))
+        else:
+            print(get_context_text_record())
+    elif args.mode == "packages":
+        if args.json:
+            print(json.dumps(get_context_packages_json(), indent=2, ensure_ascii=False))
+        else:
+            print(get_context_packages_text())
+    elif args.mode == "phase":
+        content = get_step(args.step) if args.step else get_phase_index()
+        if not content.strip():
+            if args.step:
+                parser.exit(2, f"Step not found: {args.step}\n")
+            else:
+                parser.exit(2, "Phase Index section not found in workflow.md\n")
+        if args.platform:
+            content = filter_platform(content, args.platform)
+        print(content, end="")
+    else:
+        if args.json:
+            output_json()
+        else:
+            output_text()
+
+
+if __name__ == "__main__":
+    main()

.trellis/scripts/common/io.py

@@ -0,0 +1,37 @@
+"""
+JSON file I/O utilities.
+
+Provides read_json and write_json as the single source of truth
+for JSON file operations across all Trellis scripts.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def read_json(path: Path) -> dict | None:
+    """Read and parse a JSON file.
+
+    Returns None if the file doesn't exist, is invalid JSON, or can't be read.
+    """
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def write_json(path: Path, data: dict) -> bool:
+    """Write dict to JSON file with pretty formatting.
+
+    Returns True on success, False on error.
+    """
+    try:
+        path.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        return True
+    except (OSError, IOError):
+        return False

.trellis/scripts/common/log.py

@@ -0,0 +1,45 @@
+"""
+Terminal output utilities: colors and structured logging.
+
+Single source of truth for Colors and log_* functions
+used across all Trellis scripts.
+"""
+
+from __future__ import annotations
+
+
+class Colors:
+    """ANSI color codes for terminal output."""
+
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    DIM = "\033[2m"
+    NC = "\033[0m"  # No Color / Reset
+
+
+def colored(text: str, color: str) -> str:
+    """Apply ANSI color to text."""
+    return f"{color}{text}{Colors.NC}"
+
+
+def log_info(msg: str) -> None:
+    """Print info-level message with [INFO] prefix."""
+    print(f"{Colors.BLUE}[INFO]{Colors.NC} {msg}")
+
+
+def log_success(msg: str) -> None:
+    """Print success message with [SUCCESS] prefix."""
+    print(f"{Colors.GREEN}[SUCCESS]{Colors.NC} {msg}")
+
+
+def log_warn(msg: str) -> None:
+    """Print warning message with [WARN] prefix."""
+    print(f"{Colors.YELLOW}[WARN]{Colors.NC} {msg}")
+
+
+def log_error(msg: str) -> None:
+    """Print error message with [ERROR] prefix."""
+    print(f"{Colors.RED}[ERROR]{Colors.NC} {msg}")

.trellis/scripts/common/packages_context.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+Package discovery and context output.
+
+Provides:
+    get_packages_info           - Get structured package info
+    get_packages_section        - Build PACKAGES text section
+    get_context_packages_text   - Full packages text output (--mode packages)
+    get_context_packages_json   - Full packages JSON output (--mode packages --json)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import _is_true_config_value, get_default_package, get_packages, get_spec_scope
+from .paths import (
+    DIR_SPEC,
+    DIR_WORKFLOW,
+    get_current_task,
+    get_repo_root,
+)
+from .tasks import load_task
+
+
+# =============================================================================
+# Internal Helpers
+# =============================================================================
+
+def _scan_spec_layers(spec_dir: Path, package: str | None = None) -> list[str]:
+    """Scan spec directory for available layers (subdirectories).
+
+    For monorepo: scans spec/<package>/
+    For single-repo: scans spec/
+    """
+    target = spec_dir / package if package else spec_dir
+    if not target.is_dir():
+        return []
+    return sorted(
+        d.name for d in target.iterdir() if d.is_dir() and d.name != "guides"
+    )
+
+
+def _get_active_task_package(repo_root: Path) -> str | None:
+    """Get the package field from the active task's task.json."""
+    current = get_current_task(repo_root)
+    if not current:
+        return None
+    ct = load_task(repo_root / current)
+    return ct.package if ct and ct.package else None
+
+
+def _resolve_scope_set(
+    packages: dict,
+    spec_scope,
+    task_pkg: str | None,
+    default_pkg: str | None,
+) -> set | None:
+    """Resolve spec_scope to a set of allowed package names, or None for full scan."""
+    if not packages:
+        return None
+
+    if spec_scope is None:
+        return None
+
+    if isinstance(spec_scope, str) and spec_scope == "active_task":
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None
+
+    if isinstance(spec_scope, list):
+        valid = {e for e in spec_scope if e in packages}
+        if valid:
+            return valid
+        # All invalid: fallback
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None
+
+    return None
+
+
+# =============================================================================
+# Public Functions
+# =============================================================================
+
+def get_packages_info(repo_root: Path) -> list[dict]:
+    """Get structured package info for monorepo projects.
+
+    Returns list of dicts with keys: name, path, type, default, specLayers,
+    isSubmodule, isGitRepo.
+    Returns empty list for single-repo projects.
+    """
+    packages = get_packages(repo_root)
+    if not packages:
+        return []
+
+    default_pkg = get_default_package(repo_root)
+    spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+    result = []
+
+    for pkg_name, pkg_config in packages.items():
+        pkg_path = pkg_config.get("path", pkg_name) if isinstance(pkg_config, dict) else str(pkg_config)
+        pkg_type = pkg_config.get("type", "local") if isinstance(pkg_config, dict) else "local"
+        pkg_git = pkg_config.get("git", False) if isinstance(pkg_config, dict) else False
+        layers = _scan_spec_layers(spec_dir, pkg_name)
+
+        result.append({
+            "name": pkg_name,
+            "path": pkg_path,
+            "type": pkg_type,
+            "default": pkg_name == default_pkg,
+            "specLayers": layers,
+            "isSubmodule": pkg_type == "submodule",
+            "isGitRepo": _is_true_config_value(pkg_git),
+        })
+
+    return result
+
+
+def get_packages_section(repo_root: Path) -> str:
+    """Build the PACKAGES section for text output."""
+    spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+    pkg_info = get_packages_info(repo_root)
+
+    lines: list[str] = []
+    lines.append("## PACKAGES")
+
+    if not pkg_info:
+        lines.append("(single-repo mode)")
+        layers = _scan_spec_layers(spec_dir)
+        if layers:
+            lines.append(f"Spec layers: {', '.join(layers)}")
+        return "\n".join(lines)
+
+    default_pkg = get_default_package(repo_root)
+
+    for pkg in pkg_info:
+        layers_str = f"  [{', '.join(pkg['specLayers'])}]" if pkg["specLayers"] else ""
+        submodule_tag = "  (submodule)" if pkg["isSubmodule"] else ""
+        git_repo_tag = "  (git repo)" if pkg["isGitRepo"] else ""
+        default_tag = "  *" if pkg["default"] else ""
+        lines.append(
+            f"- {pkg['name']:<16} {pkg['path']:<20}{layers_str}{submodule_tag}{git_repo_tag}{default_tag}"
+        )
+
+    if default_pkg:
+        lines.append(f"Default package: {default_pkg}")
+
+    return "\n".join(lines)
+
+
+def get_context_packages_text(repo_root: Path | None = None) -> str:
+    """Get packages context as formatted text (for --mode packages)."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    pkg_info = get_packages_info(repo_root)
+    lines: list[str] = []
+
+    if not pkg_info:
+        spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+        lines.append("Single-repo project (no packages configured)")
+        lines.append("")
+        layers = _scan_spec_layers(spec_dir)
+        if layers:
+            lines.append(f"Spec layers: {', '.join(layers)}")
+        return "\n".join(lines)
+
+    # Resolve scope for annotations
+    packages_dict = get_packages(repo_root) or {}
+    default_pkg = get_default_package(repo_root)
+    spec_scope = get_spec_scope(repo_root)
+    task_pkg = _get_active_task_package(repo_root)
+    scope_set = _resolve_scope_set(packages_dict, spec_scope, task_pkg, default_pkg)
+
+    lines.append("## PACKAGES")
+    lines.append("")
+    for pkg in pkg_info:
+        default_tag = " (default)" if pkg["default"] else ""
+        type_tag = f" [{pkg['type']}]" if pkg["type"] != "local" else ""
+        git_tag = " [git repo]" if pkg["isGitRepo"] else ""
+
+        # Scope annotation
+        scope_tag = ""
+        if scope_set is not None and pkg["name"] not in scope_set:
+            scope_tag = " (out of scope)"
+
+        lines.append(f"### {pkg['name']}{default_tag}{type_tag}{git_tag}{scope_tag}")
+        lines.append(f"Path: {pkg['path']}")
+        if pkg["specLayers"]:
+            lines.append(f"Spec layers: {', '.join(pkg['specLayers'])}")
+            for layer in pkg["specLayers"]:
+                lines.append(f"  - .trellis/spec/{pkg['name']}/{layer}/index.md")
+        else:
+            lines.append("Spec: not configured")
+        lines.append("")
+
+    # Also show shared guides
+    guides_dir = repo_root / DIR_WORKFLOW / DIR_SPEC / "guides"
+    if guides_dir.is_dir():
+        lines.append("### Shared Guides (always included)")
+        lines.append("Path: .trellis/spec/guides/index.md")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def get_context_packages_json(repo_root: Path | None = None) -> dict:
+    """Get packages context as a dictionary (for --mode packages --json)."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    pkg_info = get_packages_info(repo_root)
+
+    if not pkg_info:
+        spec_dir = repo_root / DIR_WORKFLOW / DIR_SPEC
+        layers = _scan_spec_layers(spec_dir)
+        return {
+            "mode": "single-repo",
+            "specLayers": layers,
+        }
+
+    default_pkg = get_default_package(repo_root)
+    spec_scope = get_spec_scope(repo_root)
+    task_pkg = _get_active_task_package(repo_root)
+
+    return {
+        "mode": "monorepo",
+        "packages": pkg_info,
+        "defaultPackage": default_pkg,
+        "specScope": spec_scope,
+        "activeTaskPackage": task_pkg,
+    }

.trellis/scripts/common/paths.py

@@ -0,0 +1,444 @@
+#!/usr/bin/env python3
+"""
+Common path utilities for Trellis workflow.
+
+Provides:
+    get_repo_root          - Get repository root directory
+    get_developer          - Get developer name
+    get_workspace_dir      - Get developer workspace directory
+    get_tasks_dir          - Get tasks directory
+    get_active_journal_file - Get current journal file
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+# =============================================================================
+# Path Constants (change here to rename directories)
+# =============================================================================
+
+# Directory names
+DIR_WORKFLOW = ".trellis"
+DIR_WORKSPACE = "workspace"
+DIR_TASKS = "tasks"
+DIR_ARCHIVE = "archive"
+DIR_SPEC = "spec"
+DIR_SCRIPTS = "scripts"
+
+# File names
+FILE_DEVELOPER = ".developer"
+FILE_CURRENT_TASK = ".current-task"
+FILE_TASK_JSON = "task.json"
+FILE_JOURNAL_PREFIX = "journal-"
+
+
+# =============================================================================
+# Repository Root
+# =============================================================================
+
+def get_repo_root(start_path: Path | None = None) -> Path:
+    """Find the nearest directory containing .trellis/ folder.
+
+    This handles nested git repos correctly (e.g., test project inside another repo).
+
+    Args:
+        start_path: Starting directory to search from. Defaults to current directory.
+
+    Returns:
+        Path to repository root, or current directory if no .trellis/ found.
+    """
+    current = (start_path or Path.cwd()).resolve()
+
+    while current != current.parent:
+        if (current / DIR_WORKFLOW).is_dir():
+            return current
+        current = current.parent
+
+    # Fallback to current directory if no .trellis/ found
+    return Path.cwd().resolve()
+
+
+# =============================================================================
+# Developer
+# =============================================================================
+
+def get_developer(repo_root: Path | None = None) -> str | None:
+    """Get developer name from .developer file.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Developer name or None if not initialized.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+
+    if not dev_file.is_file():
+        return None
+
+    try:
+        content = dev_file.read_text(encoding="utf-8")
+        for line in content.splitlines():
+            if line.startswith("name="):
+                return line.split("=", 1)[1].strip()
+    except (OSError, IOError):
+        pass
+
+    return None
+
+
+def check_developer(repo_root: Path | None = None) -> bool:
+    """Check if developer is initialized.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if developer is initialized.
+    """
+    return get_developer(repo_root) is not None
+
+
+# =============================================================================
+# Tasks Directory
+# =============================================================================
+
+def get_tasks_dir(repo_root: Path | None = None) -> Path:
+    """Get tasks directory path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to tasks directory.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / DIR_WORKFLOW / DIR_TASKS
+
+
+# =============================================================================
+# Workspace Directory
+# =============================================================================
+
+def get_workspace_dir(repo_root: Path | None = None) -> Path | None:
+    """Get developer workspace directory.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to workspace directory or None if developer not set.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    if developer:
+        return repo_root / DIR_WORKFLOW / DIR_WORKSPACE / developer
+    return None
+
+
+# =============================================================================
+# Journal File
+# =============================================================================
+
+def get_active_journal_file(repo_root: Path | None = None) -> Path | None:
+    """Get the current active journal file.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to active journal file or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    workspace_dir = get_workspace_dir(repo_root)
+    if workspace_dir is None or not workspace_dir.is_dir():
+        return None
+
+    latest: Path | None = None
+    highest = 0
+
+    for f in workspace_dir.glob(f"{FILE_JOURNAL_PREFIX}*.md"):
+        if not f.is_file():
+            continue
+
+        # Extract number from filename
+        name = f.stem  # e.g., "journal-1"
+        match = re.search(r"(\d+)$", name)
+        if match:
+            num = int(match.group(1))
+            if num > highest:
+                highest = num
+                latest = f
+
+    return latest
+
+
+def count_lines(file_path: Path) -> int:
+    """Count lines in a file.
+
+    Args:
+        file_path: Path to file.
+
+    Returns:
+        Number of lines, or 0 if file doesn't exist.
+    """
+    if not file_path.is_file():
+        return 0
+
+    try:
+        return len(file_path.read_text(encoding="utf-8").splitlines())
+    except (OSError, IOError):
+        return 0
+
+
+# =============================================================================
+# Current Task Management
+# =============================================================================
+
+def _get_current_task_file(repo_root: Path | None = None) -> Path:
+    """Get .current-task file path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to .current-task file.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    return repo_root / DIR_WORKFLOW / FILE_CURRENT_TASK
+
+
+def normalize_task_ref(task_ref: str) -> str:
+    """Normalize a task ref for stable storage in .current-task.
+
+    Stored refs should prefer repo-relative POSIX paths like
+    `.trellis/tasks/03-27-my-task`, even on Windows. Absolute paths are preserved
+    unless they can later be converted back to repo-relative form by callers.
+    """
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith(f"{DIR_TASKS}/"):
+        return f"{DIR_WORKFLOW}/{normalized}"
+
+    return normalized
+
+
+def resolve_task_ref(task_ref: str, repo_root: Path | None = None) -> Path | None:
+    """Resolve a task ref from .current-task to an absolute task directory path."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    normalized = normalize_task_ref(task_ref)
+    if not normalized:
+        return None
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+
+    if normalized.startswith(f"{DIR_WORKFLOW}/"):
+        return repo_root / path_obj
+
+    return repo_root / DIR_WORKFLOW / DIR_TASKS / path_obj
+
+
+def get_current_task(repo_root: Path | None = None) -> str | None:
+    """Get current task directory path (relative to repo_root).
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Relative path to current task directory or None.
+    """
+    current_file = _get_current_task_file(repo_root)
+
+    if not current_file.is_file():
+        return None
+
+    try:
+        content = current_file.read_text(encoding="utf-8").strip()
+        return normalize_task_ref(content) if content else None
+    except (OSError, IOError):
+        return None
+
+
+def get_current_task_abs(repo_root: Path | None = None) -> Path | None:
+    """Get current task directory absolute path.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Absolute path to current task directory or None.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    relative = get_current_task(repo_root)
+    if relative:
+        return resolve_task_ref(relative, repo_root)
+    return None
+
+
+def set_current_task(task_path: str, repo_root: Path | None = None) -> bool:
+    """Set current task.
+
+    Args:
+        task_path: Task directory path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success, False on error.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    normalized = normalize_task_ref(task_path)
+    if not normalized:
+        return False
+
+    # Verify task directory exists
+    full_path = resolve_task_ref(normalized, repo_root)
+    if full_path is None or not full_path.is_dir():
+        return False
+
+    try:
+        normalized = full_path.relative_to(repo_root).as_posix()
+    except ValueError:
+        normalized = str(full_path)
+
+    current_file = _get_current_task_file(repo_root)
+
+    try:
+        current_file.write_text(normalized, encoding="utf-8")
+        return True
+    except (OSError, IOError):
+        return False
+
+
+def clear_current_task(repo_root: Path | None = None) -> bool:
+    """Clear current task.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success.
+    """
+    current_file = _get_current_task_file(repo_root)
+
+    try:
+        if current_file.is_file():
+            current_file.unlink()
+        return True
+    except (OSError, IOError):
+        return False
+
+
+def has_current_task(repo_root: Path | None = None) -> bool:
+    """Check if has current task.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if current task is set.
+    """
+    return get_current_task(repo_root) is not None
+
+
+# =============================================================================
+# Task ID Generation
+# =============================================================================
+
+def generate_task_date_prefix() -> str:
+    """Generate task ID based on date (MM-DD format).
+
+    Returns:
+        Date prefix string (e.g., "01-21").
+    """
+    return datetime.now().strftime("%m-%d")
+
+
+# =============================================================================
+# Monorepo / Package Paths
+# =============================================================================
+
+
+def get_spec_dir(package: str | None = None, repo_root: Path | None = None) -> Path:
+    """Get the spec directory path.
+
+    Single-repo: .trellis/spec
+    Monorepo with package: .trellis/spec/<package>
+
+    Uses lazy import to avoid circular dependency with config.py.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    from .config import get_spec_base
+
+    base = get_spec_base(package, repo_root)
+    return repo_root / DIR_WORKFLOW / base
+
+
+def get_package_path(package: str, repo_root: Path | None = None) -> Path | None:
+    """Get a package's source directory absolute path from config.
+
+    Returns:
+        Absolute path to the package directory, or None if not found.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    from .config import get_packages
+
+    packages = get_packages(repo_root)
+    if not packages or package not in packages:
+        return None
+
+    info = packages[package]
+    if isinstance(info, dict):
+        rel_path = info.get("path", package)
+    else:
+        rel_path = str(info)
+
+    return repo_root / rel_path
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    print(f"Repository root: {repo}")
+    print(f"Developer: {get_developer(repo)}")
+    print(f"Tasks dir: {get_tasks_dir(repo)}")
+    print(f"Workspace dir: {get_workspace_dir(repo)}")
+    print(f"Journal file: {get_active_journal_file(repo)}")
+    print(f"Current task: {get_current_task(repo)}")

.trellis/scripts/common/session_context.py

@@ -0,0 +1,562 @@
+#!/usr/bin/env python3
+"""
+Session context generation (default + record modes).
+
+Provides:
+    get_context_json          - JSON output for default mode
+    get_context_text          - Text output for default mode
+    get_context_record_json   - JSON for record mode
+    get_context_text_record   - Text for record mode
+    output_json               - Print JSON
+    output_text               - Print text
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .config import get_git_packages
+from .git import run_git
+from .packages_context import get_packages_section
+from .tasks import iter_active_tasks, load_task, get_all_statuses, children_progress
+from .paths import (
+    DIR_SCRIPTS,
+    DIR_SPEC,
+    DIR_TASKS,
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    count_lines,
+    get_active_journal_file,
+    get_current_task,
+    get_developer,
+    get_repo_root,
+    get_tasks_dir,
+)
+
+
+# =============================================================================
+# Helpers
+# =============================================================================
+
+def _collect_package_git_info(repo_root: Path) -> list[dict]:
+    """Collect git status and recent commits for packages with independent git repos.
+
+    Only packages marked with ``git: true`` in config.yaml are included.
+
+    Returns:
+        List of dicts with keys: name, path, branch, isClean,
+        uncommittedChanges, recentCommits.
+        Empty list if no git-repo packages are configured.
+    """
+    git_pkgs = get_git_packages(repo_root)
+    if not git_pkgs:
+        return []
+
+    result = []
+    for pkg_name, pkg_path in git_pkgs.items():
+        pkg_dir = repo_root / pkg_path
+        if not (pkg_dir / ".git").exists():
+            continue
+
+        _, branch_out, _ = run_git(["branch", "--show-current"], cwd=pkg_dir)
+        branch = branch_out.strip() or "unknown"
+
+        _, status_out, _ = run_git(["status", "--porcelain"], cwd=pkg_dir)
+        changes = len([l for l in status_out.splitlines() if l.strip()])
+
+        _, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=pkg_dir)
+        commits = []
+        for line in log_out.splitlines():
+            if line.strip():
+                parts = line.split(" ", 1)
+                if len(parts) >= 2:
+                    commits.append({"hash": parts[0], "message": parts[1]})
+                elif len(parts) == 1:
+                    commits.append({"hash": parts[0], "message": ""})
+
+        result.append({
+            "name": pkg_name,
+            "path": pkg_path,
+            "branch": branch,
+            "isClean": changes == 0,
+            "uncommittedChanges": changes,
+            "recentCommits": commits,
+        })
+
+    return result
+
+
+def _append_package_git_context(lines: list[str], package_git_info: list[dict]) -> None:
+    """Append Git status and recent commits for package repositories."""
+    for pkg in package_git_info:
+        lines.append(f"## GIT STATUS ({pkg['name']}: {pkg['path']})")
+        lines.append(f"Branch: {pkg['branch']}")
+        if pkg["isClean"]:
+            lines.append("Working directory: Clean")
+        else:
+            lines.append(
+                f"Working directory: {pkg['uncommittedChanges']} uncommitted change(s)"
+            )
+        lines.append("")
+        lines.append(f"## RECENT COMMITS ({pkg['name']}: {pkg['path']})")
+        if pkg["recentCommits"]:
+            for commit in pkg["recentCommits"]:
+                lines.append(f"{commit['hash']} {commit['message']}")
+        else:
+            lines.append("(no commits)")
+        lines.append("")
+
+
+# =============================================================================
+# JSON Output
+# =============================================================================
+
+def get_context_json(repo_root: Path | None = None) -> dict:
+    """Get context as a dictionary.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Context dictionary.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    tasks_dir = get_tasks_dir(repo_root)
+    journal_file = get_active_journal_file(repo_root)
+
+    journal_lines = 0
+    journal_relative = ""
+    if journal_file and developer:
+        journal_lines = count_lines(journal_file)
+        journal_relative = (
+            f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{journal_file.name}"
+        )
+
+    # Git info
+    _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+
+    _, status_out, _ = run_git(["status", "--porcelain"], cwd=repo_root)
+    git_status_count = len([line for line in status_out.splitlines() if line.strip()])
+    is_clean = git_status_count == 0
+
+    # Recent commits
+    _, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=repo_root)
+    commits = []
+    for line in log_out.splitlines():
+        if line.strip():
+            parts = line.split(" ", 1)
+            if len(parts) >= 2:
+                commits.append({"hash": parts[0], "message": parts[1]})
+            elif len(parts) == 1:
+                commits.append({"hash": parts[0], "message": ""})
+
+    # Tasks
+    tasks = [
+        {
+            "dir": t.dir_name,
+            "name": t.name,
+            "status": t.status,
+            "children": list(t.children),
+            "parent": t.parent,
+        }
+        for t in iter_active_tasks(tasks_dir)
+    ]
+
+    # Package git repos (independent sub-repositories)
+    pkg_git_info = _collect_package_git_info(repo_root)
+
+    result = {
+        "developer": developer or "",
+        "git": {
+            "branch": branch,
+            "isClean": is_clean,
+            "uncommittedChanges": git_status_count,
+            "recentCommits": commits,
+        },
+        "tasks": {
+            "active": tasks,
+            "directory": f"{DIR_WORKFLOW}/{DIR_TASKS}",
+        },
+        "journal": {
+            "file": journal_relative,
+            "lines": journal_lines,
+            "nearLimit": journal_lines > 1800,
+        },
+    }
+
+    if pkg_git_info:
+        result["packageGit"] = pkg_git_info
+
+    return result
+
+
+def output_json(repo_root: Path | None = None) -> None:
+    """Output context in JSON format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    context = get_context_json(repo_root)
+    print(json.dumps(context, indent=2, ensure_ascii=False))
+
+
+# =============================================================================
+# Text Output
+# =============================================================================
+
+def get_context_text(repo_root: Path | None = None) -> str:
+    """Get context as formatted text.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Formatted text output.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    lines = []
+    lines.append("========================================")
+    lines.append("SESSION CONTEXT")
+    lines.append("========================================")
+    lines.append("")
+
+    developer = get_developer(repo_root)
+
+    # Developer section
+    lines.append("## DEVELOPER")
+    if not developer:
+        lines.append(
+            f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
+        )
+        return "\n".join(lines)
+
+    lines.append(f"Name: {developer}")
+    lines.append("")
+
+    # Git status
+    lines.append("## GIT STATUS")
+    _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+    lines.append(f"Branch: {branch}")
+
+    _, status_out, _ = run_git(["status", "--porcelain"], cwd=repo_root)
+    status_lines = [line for line in status_out.splitlines() if line.strip()]
+    status_count = len(status_lines)
+
+    if status_count == 0:
+        lines.append("Working directory: Clean")
+    else:
+        lines.append(f"Working directory: {status_count} uncommitted change(s)")
+        lines.append("")
+        lines.append("Changes:")
+        _, short_out, _ = run_git(["status", "--short"], cwd=repo_root)
+        for line in short_out.splitlines()[:10]:
+            lines.append(line)
+    lines.append("")
+
+    # Recent commits
+    lines.append("## RECENT COMMITS")
+    _, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=repo_root)
+    if log_out.strip():
+        for line in log_out.splitlines():
+            lines.append(line)
+    else:
+        lines.append("(no commits)")
+    lines.append("")
+
+    # Package git repos — independent sub-repositories
+    _append_package_git_context(lines, _collect_package_git_info(repo_root))
+
+    # Current task
+    lines.append("## CURRENT TASK")
+    current_task = get_current_task(repo_root)
+    if current_task:
+        current_task_dir = repo_root / current_task
+        lines.append(f"Path: {current_task}")
+
+        ct = load_task(current_task_dir)
+        if ct:
+            lines.append(f"Name: {ct.name}")
+            lines.append(f"Status: {ct.status}")
+            lines.append(f"Created: {ct.raw.get('createdAt', 'unknown')}")
+            if ct.description:
+                lines.append(f"Description: {ct.description}")
+
+        # Check for prd.md
+        prd_file = current_task_dir / "prd.md"
+        if prd_file.is_file():
+            lines.append("")
+            lines.append("[!] This task has prd.md - read it for task details")
+    else:
+        lines.append("(none)")
+    lines.append("")
+
+    # Active tasks
+    lines.append("## ACTIVE TASKS")
+    tasks_dir = get_tasks_dir(repo_root)
+    task_count = 0
+
+    # Collect all task data for hierarchy display
+    all_tasks = {t.dir_name: t for t in iter_active_tasks(tasks_dir)}
+    all_statuses = {name: t.status for name, t in all_tasks.items()}
+
+    def _print_task_tree(name: str, indent: int = 0) -> None:
+        nonlocal task_count
+        t = all_tasks[name]
+        progress = children_progress(t.children, all_statuses)
+        prefix = "  " * indent
+        lines.append(f"{prefix}- {name}/ ({t.status}){progress} @{t.assignee or '-'}")
+        task_count += 1
+        for child in t.children:
+            if child in all_tasks:
+                _print_task_tree(child, indent + 1)
+
+    for dir_name in sorted(all_tasks.keys()):
+        if not all_tasks[dir_name].parent:
+            _print_task_tree(dir_name)
+
+    if task_count == 0:
+        lines.append("(no active tasks)")
+    lines.append(f"Total: {task_count} active task(s)")
+    lines.append("")
+
+    # My tasks
+    lines.append("## MY TASKS (Assigned to me)")
+    my_task_count = 0
+
+    for t in all_tasks.values():
+        if t.assignee == developer and t.status != "done":
+            progress = children_progress(t.children, all_statuses)
+            lines.append(f"- [{t.priority}] {t.title} ({t.status}){progress}")
+            my_task_count += 1
+
+    if my_task_count == 0:
+        lines.append("(no tasks assigned to you)")
+    lines.append("")
+
+    # Journal file
+    lines.append("## JOURNAL FILE")
+    journal_file = get_active_journal_file(repo_root)
+    if journal_file:
+        journal_lines = count_lines(journal_file)
+        relative = f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{journal_file.name}"
+        lines.append(f"Active file: {relative}")
+        lines.append(f"Line count: {journal_lines} / 2000")
+        if journal_lines > 1800:
+            lines.append("[!] WARNING: Approaching 2000 line limit!")
+    else:
+        lines.append("No journal file found")
+    lines.append("")
+
+    # Packages
+    packages_text = get_packages_section(repo_root)
+    if packages_text:
+        lines.append(packages_text)
+        lines.append("")
+
+    # Paths
+    lines.append("## PATHS")
+    lines.append(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
+    lines.append(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
+    lines.append(f"Spec: {DIR_WORKFLOW}/{DIR_SPEC}/")
+    lines.append("")
+
+    lines.append("========================================")
+
+    return "\n".join(lines)
+
+
+# =============================================================================
+# Record Mode
+# =============================================================================
+
+def get_context_record_json(repo_root: Path | None = None) -> dict:
+    """Get record-mode context as a dictionary.
+
+    Focused on: my active tasks, git status, current task.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    tasks_dir = get_tasks_dir(repo_root)
+
+    # Git info
+    _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+
+    _, status_out, _ = run_git(["status", "--porcelain"], cwd=repo_root)
+    git_status_count = len([line for line in status_out.splitlines() if line.strip()])
+
+    _, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=repo_root)
+    commits = []
+    for line in log_out.splitlines():
+        if line.strip():
+            parts = line.split(" ", 1)
+            if len(parts) >= 2:
+                commits.append({"hash": parts[0], "message": parts[1]})
+
+    # My tasks (single pass — collect statuses and filter by assignee)
+    all_tasks_list = list(iter_active_tasks(tasks_dir))
+    all_statuses = {t.dir_name: t.status for t in all_tasks_list}
+
+    my_tasks = []
+    for t in all_tasks_list:
+        if t.assignee == developer:
+            done = sum(
+                1 for c in t.children
+                if all_statuses.get(c) in ("completed", "done")
+            )
+            my_tasks.append({
+                "dir": t.dir_name,
+                "title": t.title,
+                "status": t.status,
+                "priority": t.priority,
+                "children": list(t.children),
+                "childrenDone": done,
+                "parent": t.parent,
+                "meta": t.meta,
+            })
+
+    # Current task
+    current_task_info = None
+    current_task = get_current_task(repo_root)
+    if current_task:
+        ct = load_task(repo_root / current_task)
+        if ct:
+            current_task_info = {
+                "path": current_task,
+                "name": ct.name,
+                "status": ct.status,
+            }
+
+    # Package git repos
+    pkg_git_info = _collect_package_git_info(repo_root)
+
+    result = {
+        "developer": developer or "",
+        "git": {
+            "branch": branch,
+            "isClean": git_status_count == 0,
+            "uncommittedChanges": git_status_count,
+            "recentCommits": commits,
+        },
+        "myTasks": my_tasks,
+        "currentTask": current_task_info,
+    }
+
+    if pkg_git_info:
+        result["packageGit"] = pkg_git_info
+
+    return result
+
+
+def get_context_text_record(repo_root: Path | None = None) -> str:
+    """Get context as formatted text for record-session mode.
+
+    Focused output: MY ACTIVE TASKS first (with [!!!] emphasis),
+    then GIT STATUS, RECENT COMMITS, CURRENT TASK.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    lines: list[str] = []
+    lines.append("========================================")
+    lines.append("SESSION CONTEXT (RECORD MODE)")
+    lines.append("========================================")
+    lines.append("")
+
+    developer = get_developer(repo_root)
+    if not developer:
+        lines.append(
+            f"ERROR: Not initialized. Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <name>"
+        )
+        return "\n".join(lines)
+
+    # MY ACTIVE TASKS — first and prominent
+    lines.append(f"## [!!!] MY ACTIVE TASKS (Assigned to {developer})")
+    lines.append("[!] Review whether any should be archived before recording this session.")
+    lines.append("")
+
+    tasks_dir = get_tasks_dir(repo_root)
+    my_task_count = 0
+
+    # Single pass — collect all tasks and filter by assignee
+    all_statuses = get_all_statuses(tasks_dir)
+
+    for t in iter_active_tasks(tasks_dir):
+        if t.assignee == developer:
+            progress = children_progress(t.children, all_statuses)
+            lines.append(f"- [{t.priority}] {t.title} ({t.status}){progress} — {t.dir_name}")
+            my_task_count += 1
+
+    if my_task_count == 0:
+        lines.append("(no active tasks assigned to you)")
+    lines.append("")
+
+    # GIT STATUS
+    lines.append("## GIT STATUS")
+    _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    branch = branch_out.strip() or "unknown"
+    lines.append(f"Branch: {branch}")
+
+    _, status_out, _ = run_git(["status", "--porcelain"], cwd=repo_root)
+    status_lines = [line for line in status_out.splitlines() if line.strip()]
+    status_count = len(status_lines)
+
+    if status_count == 0:
+        lines.append("Working directory: Clean")
+    else:
+        lines.append(f"Working directory: {status_count} uncommitted change(s)")
+        lines.append("")
+        lines.append("Changes:")
+        _, short_out, _ = run_git(["status", "--short"], cwd=repo_root)
+        for line in short_out.splitlines()[:10]:
+            lines.append(line)
+    lines.append("")
+
+    # RECENT COMMITS
+    lines.append("## RECENT COMMITS")
+    _, log_out, _ = run_git(["log", "--oneline", "-5"], cwd=repo_root)
+    if log_out.strip():
+        for line in log_out.splitlines():
+            lines.append(line)
+    else:
+        lines.append("(no commits)")
+    lines.append("")
+
+    # Package git repos — independent sub-repositories
+    _append_package_git_context(lines, _collect_package_git_info(repo_root))
+
+    # CURRENT TASK
+    lines.append("## CURRENT TASK")
+    current_task = get_current_task(repo_root)
+    if current_task:
+        lines.append(f"Path: {current_task}")
+        ct = load_task(repo_root / current_task)
+        if ct:
+            lines.append(f"Name: {ct.name}")
+            lines.append(f"Status: {ct.status}")
+    else:
+        lines.append("(none)")
+    lines.append("")
+
+    lines.append("========================================")
+
+    return "\n".join(lines)
+
+
+def output_text(repo_root: Path | None = None) -> None:
+    """Output context in text format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    print(get_context_text(repo_root))

.trellis/scripts/common/task_context.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""
+Task JSONL context management.
+
+Provides:
+    cmd_add_context   - Add entry to JSONL context file
+    cmd_validate      - Validate JSONL context files
+    cmd_list_context  - List JSONL context entries
+
+Note:
+    ``cmd_init_context`` was removed in v0.5.0-beta.12. JSONL context files
+    are now seeded at ``task.py create`` time with a self-describing
+    ``_example`` line; the AI agent curates real entries during Phase 1.3 of
+    the workflow. See ``.trellis/workflow.md`` Phase 1.3 for the current
+    instructions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .log import Colors, colored
+from .paths import get_repo_root
+from .task_utils import resolve_task_dir
+
+
+# =============================================================================
+# Command: add-context
+# =============================================================================
+
+def cmd_add_context(args: argparse.Namespace) -> int:
+    """Add entry to JSONL context file."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    jsonl_name = args.file
+    path = args.path
+    reason = args.reason or "Added manually"
+
+    if not target_dir.is_dir():
+        print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
+        return 1
+
+    # Support shorthand
+    if not jsonl_name.endswith(".jsonl"):
+        jsonl_name = f"{jsonl_name}.jsonl"
+
+    jsonl_file = target_dir / jsonl_name
+    full_path = repo_root / path
+
+    entry_type = "file"
+    if full_path.is_dir():
+        entry_type = "directory"
+        if not path.endswith("/"):
+            path = f"{path}/"
+    elif not full_path.is_file():
+        print(colored(f"Error: Path not found: {path}", Colors.RED))
+        return 1
+
+    # Check if already exists
+    if jsonl_file.is_file():
+        content = jsonl_file.read_text(encoding="utf-8")
+        if f'"{path}"' in content:
+            print(colored(f"Warning: Entry already exists for {path}", Colors.YELLOW))
+            return 0
+
+    # Add entry
+    entry: dict
+    if entry_type == "directory":
+        entry = {"file": path, "type": "directory", "reason": reason}
+    else:
+        entry = {"file": path, "reason": reason}
+
+    with jsonl_file.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    print(colored(f"Added {entry_type}: {path}", Colors.GREEN))
+    return 0
+
+
+# =============================================================================
+# Command: validate
+# =============================================================================
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Validate JSONL context files."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    if not target_dir.is_dir():
+        print(colored("Error: task directory required", Colors.RED))
+        return 1
+
+    print(colored("=== Validating Context Files ===", Colors.BLUE))
+    print(f"Target dir: {target_dir}")
+    print()
+
+    total_errors = 0
+    for jsonl_name in ["implement.jsonl", "check.jsonl"]:
+        jsonl_file = target_dir / jsonl_name
+        errors = _validate_jsonl(jsonl_file, repo_root)
+        total_errors += errors
+
+    print()
+    if total_errors == 0:
+        print(colored("✓ All validations passed", Colors.GREEN))
+        return 0
+    else:
+        print(colored(f"✗ Validation failed ({total_errors} errors)", Colors.RED))
+        return 1
+
+
+def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
+    """Validate a single JSONL file.
+
+    Seed rows (no ``file`` field — typically ``{"_example": "..."}``) are
+    skipped silently; they are self-describing comments, not real entries.
+    """
+    file_name = jsonl_file.name
+    errors = 0
+
+    if not jsonl_file.is_file():
+        print(f"  {colored(f'{file_name}: not found (skipped)', Colors.YELLOW)}")
+        return 0
+
+    line_num = 0
+    real_entries = 0
+    for line in jsonl_file.read_text(encoding="utf-8").splitlines():
+        line_num += 1
+        if not line.strip():
+            continue
+
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            print(f"  {colored(f'{file_name}:{line_num}: Invalid JSON', Colors.RED)}")
+            errors += 1
+            continue
+
+        file_path = data.get("file")
+        entry_type = data.get("type", "file")
+
+        if not file_path:
+            # Seed / comment row — skip silently
+            continue
+
+        real_entries += 1
+        full_path = repo_root / file_path
+        if entry_type == "directory":
+            if not full_path.is_dir():
+                print(f"  {colored(f'{file_name}:{line_num}: Directory not found: {file_path}', Colors.RED)}")
+                errors += 1
+        else:
+            if not full_path.is_file():
+                print(f"  {colored(f'{file_name}:{line_num}: File not found: {file_path}', Colors.RED)}")
+                errors += 1
+
+    if errors == 0:
+        print(f"  {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")
+    else:
+        print(f"  {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
+
+    return errors
+
+
+# =============================================================================
+# Command: list-context
+# =============================================================================
+
+def cmd_list_context(args: argparse.Namespace) -> int:
+    """List JSONL context entries."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    if not target_dir.is_dir():
+        print(colored("Error: task directory required", Colors.RED))
+        return 1
+
+    print(colored("=== Context Files ===", Colors.BLUE))
+    print()
+
+    for jsonl_name in ["implement.jsonl", "check.jsonl"]:
+        jsonl_file = target_dir / jsonl_name
+        if not jsonl_file.is_file():
+            continue
+
+        print(colored(f"[{jsonl_name}]", Colors.CYAN))
+
+        count = 0
+        seed_only = True
+        for line in jsonl_file.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+
+            try:
+                data = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            file_path = data.get("file")
+            if not file_path:
+                # Seed / comment row — don't count as a real entry
+                continue
+            seed_only = False
+
+            count += 1
+            entry_type = data.get("type", "file")
+            reason = data.get("reason", "-")
+
+            if entry_type == "directory":
+                print(f"  {colored(f'{count}.', Colors.GREEN)} [DIR] {file_path}")
+            else:
+                print(f"  {colored(f'{count}.', Colors.GREEN)} {file_path}")
+            print(f"     {colored('→', Colors.YELLOW)} {reason}")
+
+        if seed_only:
+            print(f"  {colored('(no curated entries yet — only seed row)', Colors.YELLOW)}")
+
+        print()
+
+    return 0

.trellis/scripts/common/task_queue.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""
+Task queue utility functions.
+
+Provides:
+    list_tasks_by_status   - List tasks by status
+    list_pending_tasks     - List tasks with pending status
+    list_tasks_by_assignee - List tasks by assignee
+    list_my_tasks          - List tasks assigned to current developer
+    get_task_stats         - Get P0/P1/P2/P3 counts
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .paths import (
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+)
+from .tasks import iter_active_tasks
+
+
+# =============================================================================
+# Internal helper
+# =============================================================================
+
+def _task_to_dict(t) -> dict:
+    """Convert TaskInfo to the dict format callers expect."""
+    return {
+        "priority": t.priority,
+        "id": t.raw.get("id", ""),
+        "title": t.title,
+        "status": t.status,
+        "assignee": t.assignee or "-",
+        "dir": t.dir_name,
+        "children": list(t.children),
+        "parent": t.parent,
+    }
+
+
+# =============================================================================
+# Public Functions
+# =============================================================================
+
+def list_tasks_by_status(
+    filter_status: str | None = None,
+    repo_root: Path | None = None
+) -> list[dict]:
+    """List tasks by status.
+
+    Args:
+        filter_status: Optional status filter.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts with keys: priority, id, title, status, assignee.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    results = []
+
+    for t in iter_active_tasks(tasks_dir):
+        if filter_status and t.status != filter_status:
+            continue
+        results.append(_task_to_dict(t))
+
+    return results
+
+
+def list_pending_tasks(repo_root: Path | None = None) -> list[dict]:
+    """List pending tasks.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts.
+    """
+    return list_tasks_by_status("planning", repo_root)
+
+
+def list_tasks_by_assignee(
+    assignee: str,
+    filter_status: str | None = None,
+    repo_root: Path | None = None
+) -> list[dict]:
+    """List tasks assigned to a specific developer.
+
+    Args:
+        assignee: Developer name.
+        filter_status: Optional status filter.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    results = []
+
+    for t in iter_active_tasks(tasks_dir):
+        if (t.assignee or "-") != assignee:
+            continue
+        if filter_status and t.status != filter_status:
+            continue
+        results.append(_task_to_dict(t))
+
+    return results
+
+
+def list_my_tasks(
+    filter_status: str | None = None,
+    repo_root: Path | None = None
+) -> list[dict]:
+    """List tasks assigned to current developer.
+
+    Args:
+        filter_status: Optional status filter.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        List of task info dicts.
+
+    Raises:
+        ValueError: If developer not set.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+    if not developer:
+        raise ValueError("Developer not set")
+
+    return list_tasks_by_assignee(developer, filter_status, repo_root)
+
+
+def get_task_stats(repo_root: Path | None = None) -> dict[str, int]:
+    """Get task statistics.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with keys: P0, P1, P2, P3, Total.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    stats = {"P0": 0, "P1": 0, "P2": 0, "P3": 0, "Total": 0}
+
+    for t in iter_active_tasks(tasks_dir):
+        if t.priority in stats:
+            stats[t.priority] += 1
+        stats["Total"] += 1
+
+    return stats
+
+
+def format_task_stats(stats: dict[str, int]) -> str:
+    """Format task stats as string.
+
+    Args:
+        stats: Stats dict from get_task_stats.
+
+    Returns:
+        Formatted string like "P0:0 P1:1 P2:2 P3:0 Total:3".
+    """
+    return f"P0:{stats['P0']} P1:{stats['P1']} P2:{stats['P2']} P3:{stats['P3']} Total:{stats['Total']}"
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    stats = get_task_stats()
+    print(format_task_stats(stats))
+    print()
+    print("Pending tasks:")
+    for task in list_pending_tasks():
+        print(f"  {task['priority']}|{task['id']}|{task['title']}|{task['status']}|{task['assignee']}")

.trellis/scripts/common/task_store.py

@@ -0,0 +1,598 @@
+#!/usr/bin/env python3
+"""
+Task CRUD operations.
+
+Provides:
+    ensure_tasks_dir   - Ensure tasks directory exists
+    cmd_create         - Create a new task
+    cmd_archive        - Archive completed task
+    cmd_set_branch     - Set git branch for task
+    cmd_set_base_branch - Set PR target branch
+    cmd_set_scope      - Set scope for PR title
+    cmd_add_subtask    - Link child task to parent
+    cmd_remove_subtask - Unlink child task from parent
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .config import (
+    get_packages,
+    is_monorepo,
+    resolve_package,
+    validate_package,
+)
+from .git import run_git
+from .io import read_json, write_json
+from .log import Colors, colored
+from .paths import (
+    DIR_ARCHIVE,
+    DIR_TASKS,
+    DIR_WORKFLOW,
+    FILE_TASK_JSON,
+    clear_current_task,
+    generate_task_date_prefix,
+    get_current_task,
+    get_developer,
+    get_repo_root,
+    get_tasks_dir,
+)
+from .task_utils import (
+    archive_task_complete,
+    find_task_by_name,
+    resolve_task_dir,
+    run_task_hooks,
+)
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def _slugify(title: str) -> str:
+    """Convert title to slug (only works with ASCII)."""
+    result = title.lower()
+    result = re.sub(r"[^a-z0-9]", "-", result)
+    result = re.sub(r"-+", "-", result)
+    result = result.strip("-")
+    return result
+
+
+def ensure_tasks_dir(repo_root: Path) -> Path:
+    """Ensure tasks directory exists."""
+    tasks_dir = get_tasks_dir(repo_root)
+    archive_dir = tasks_dir / "archive"
+
+    if not tasks_dir.exists():
+        tasks_dir.mkdir(parents=True)
+        print(colored(f"Created tasks directory: {tasks_dir}", Colors.GREEN), file=sys.stderr)
+
+    if not archive_dir.exists():
+        archive_dir.mkdir(parents=True)
+
+    return tasks_dir
+
+
+# =============================================================================
+# Sub-agent platform detection + JSONL seeding
+# =============================================================================
+
+# Config directories of platforms that consume implement.jsonl / check.jsonl.
+# Keep in sync with src/types/ai-tools.ts AI_TOOLS entries — these are the
+# platforms listed in workflow.md's "agent-capable" Skill Routing block
+# (Class-1 hook-inject + Class-2 pull-based preludes). Kilo / Antigravity /
+# Windsurf are NOT in this list: they do not consume JSONL.
+_SUBAGENT_CONFIG_DIRS: tuple[str, ...] = (
+    ".claude",
+    ".cursor",
+    ".codex",
+    ".kiro",
+    ".gemini",
+    ".opencode",
+    ".qoder",
+    ".codebuddy",
+    ".factory",   # Factory Droid
+    ".github/copilot",
+)
+
+_SEED_EXAMPLE = (
+    "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. "
+    "Put spec/research files only — no code paths. "
+    "Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. "
+    "Delete this line once real entries are added."
+)
+
+
+def _has_subagent_platform(repo_root: Path) -> bool:
+    """Return True if any sub-agent-capable platform is configured.
+
+    Detected by probing well-known config directories at the repo root. Used
+    only to decide whether ``task.py create`` should seed empty
+    ``implement.jsonl`` / ``check.jsonl`` files.
+    """
+    for config_dir in _SUBAGENT_CONFIG_DIRS:
+        if (repo_root / config_dir).is_dir():
+            return True
+    return False
+
+
+def _write_seed_jsonl(path: Path) -> None:
+    """Write a one-line seed JSONL file with a self-describing ``_example``.
+
+    The seed row has no ``file`` field, so downstream consumers (hooks +
+    preludes) that iterate entries via ``item.get("file")`` naturally skip
+    it. The row exists purely as an in-file prompt for the AI curator.
+    """
+    seed = {"_example": _SEED_EXAMPLE}
+    path.write_text(json.dumps(seed, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+# =============================================================================
+# Command: create
+# =============================================================================
+
+def cmd_create(args: argparse.Namespace) -> int:
+    """Create a new task."""
+    repo_root = get_repo_root()
+
+    if not args.title:
+        print(colored("Error: title is required", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Validate --package (CLI source: fail-fast)
+    package: str | None = getattr(args, "package", None)
+    if not is_monorepo(repo_root):
+        # Single-repo: ignore --package, no package prefix
+        if package:
+            print(colored(f"Warning: --package ignored in single-repo project", Colors.YELLOW), file=sys.stderr)
+        package = None
+    elif package:
+        if not validate_package(package, repo_root):
+            packages = get_packages(repo_root)
+            available = ", ".join(sorted(packages.keys())) if packages else "(none)"
+            print(colored(f"Error: unknown package '{package}'. Available: {available}", Colors.RED), file=sys.stderr)
+            return 1
+    else:
+        # Inferred: default_package → None (no task.json yet for create)
+        package = resolve_package(repo_root=repo_root)
+
+    # Default assignee to current developer
+    assignee = args.assignee
+    if not assignee:
+        assignee = get_developer(repo_root)
+        if not assignee:
+            print(colored("Error: No developer set. Run init_developer.py first or use --assignee", Colors.RED), file=sys.stderr)
+            return 1
+
+    ensure_tasks_dir(repo_root)
+
+    # Get current developer as creator
+    creator = get_developer(repo_root) or assignee
+
+    # Generate slug if not provided
+    slug = args.slug or _slugify(args.title)
+    if not slug:
+        print(colored("Error: could not generate slug from title", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Create task directory with MM-DD-slug format
+    tasks_dir = get_tasks_dir(repo_root)
+    date_prefix = generate_task_date_prefix()
+    dir_name = f"{date_prefix}-{slug}"
+    task_dir = tasks_dir / dir_name
+    task_json_path = task_dir / FILE_TASK_JSON
+
+    if task_dir.exists():
+        print(colored(f"Warning: Task directory already exists: {dir_name}", Colors.YELLOW), file=sys.stderr)
+    else:
+        task_dir.mkdir(parents=True)
+
+    today = datetime.now().strftime("%Y-%m-%d")
+
+    # Record current branch as base_branch (PR target)
+    _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    current_branch = branch_out.strip() or "main"
+
+    task_data = {
+        "id": slug,
+        "name": slug,
+        "title": args.title,
+        "description": args.description or "",
+        "status": "planning",
+        "dev_type": None,
+        "scope": None,
+        "package": package,
+        "priority": args.priority,
+        "creator": creator,
+        "assignee": assignee,
+        "createdAt": today,
+        "completedAt": None,
+        "branch": None,
+        "base_branch": current_branch,
+        "worktree_path": None,
+        "commit": None,
+        "pr_url": None,
+        "subtasks": [],
+        "children": [],
+        "parent": None,
+        "relatedFiles": [],
+        "notes": "",
+        "meta": {},
+    }
+
+    write_json(task_json_path, task_data)
+
+    # Seed implement.jsonl / check.jsonl for sub-agent-capable platforms.
+    # Agent curates real entries in Phase 1.3 (see .trellis/workflow.md).
+    # Agent-less platforms (Kilo / Antigravity / Windsurf) skip this — they
+    # load specs via the trellis-before-dev skill instead of JSONL.
+    seeded_jsonl = False
+    if _has_subagent_platform(repo_root):
+        for jsonl_name in ("implement.jsonl", "check.jsonl"):
+            jsonl_path = task_dir / jsonl_name
+            if not jsonl_path.exists():
+                _write_seed_jsonl(jsonl_path)
+        seeded_jsonl = True
+
+    # Handle --parent: establish bidirectional link
+    if args.parent:
+        parent_dir = resolve_task_dir(args.parent, repo_root)
+        parent_json_path = parent_dir / FILE_TASK_JSON
+        if not parent_json_path.is_file():
+            print(colored(f"Warning: Parent task.json not found: {args.parent}", Colors.YELLOW), file=sys.stderr)
+        else:
+            parent_data = read_json(parent_json_path)
+            if parent_data:
+                # Add child to parent's children list
+                parent_children = parent_data.get("children", [])
+                if dir_name not in parent_children:
+                    parent_children.append(dir_name)
+                    parent_data["children"] = parent_children
+                    write_json(parent_json_path, parent_data)
+
+                # Set parent in child's task.json
+                task_data["parent"] = parent_dir.name
+                write_json(task_json_path, task_data)
+
+                print(colored(f"Linked as child of: {parent_dir.name}", Colors.GREEN), file=sys.stderr)
+
+    print(colored(f"Created task: {dir_name}", Colors.GREEN), file=sys.stderr)
+    print("", file=sys.stderr)
+    print(colored("Next steps:", Colors.BLUE), file=sys.stderr)
+    print("  1. Create prd.md with requirements", file=sys.stderr)
+    if seeded_jsonl:
+        print(
+            "  2. Curate implement.jsonl / check.jsonl (spec + research files only — "
+            "see .trellis/workflow.md Phase 1.3)",
+            file=sys.stderr,
+        )
+        print("  3. Run: python3 task.py start <dir>", file=sys.stderr)
+    else:
+        print("  2. Run: python3 task.py start <dir>", file=sys.stderr)
+    print("", file=sys.stderr)
+
+    # Output relative path for script chaining
+    print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}")
+
+    run_task_hooks("after_create", task_json_path, repo_root)
+    return 0
+
+
+# =============================================================================
+# Command: archive
+# =============================================================================
+
+def cmd_archive(args: argparse.Namespace) -> int:
+    """Archive completed task."""
+    repo_root = get_repo_root()
+    task_name = args.name
+
+    if not task_name:
+        print(colored("Error: Task name is required", Colors.RED), file=sys.stderr)
+        return 1
+
+    tasks_dir = get_tasks_dir(repo_root)
+
+    # Find task directory
+    task_dir = find_task_by_name(task_name, tasks_dir)
+
+    if not task_dir or not task_dir.is_dir():
+        print(colored(f"Error: Task not found: {task_name}", Colors.RED), file=sys.stderr)
+        print("Active tasks:", file=sys.stderr)
+        # Import lazily to avoid circular dependency
+        from .tasks import iter_active_tasks
+        for t in iter_active_tasks(tasks_dir):
+            print(f"  - {t.dir_name}/", file=sys.stderr)
+        return 1
+
+    dir_name = task_dir.name
+    task_json_path = task_dir / FILE_TASK_JSON
+
+    # Update status before archiving
+    today = datetime.now().strftime("%Y-%m-%d")
+    if task_json_path.is_file():
+        data = read_json(task_json_path)
+        if data:
+            data["status"] = "completed"
+            data["completedAt"] = today
+            write_json(task_json_path, data)
+
+            # Handle subtask relationships on archive
+            task_parent = data.get("parent")
+            task_children = data.get("children", [])
+
+            # If this is a child, remove from parent's children list
+            if task_parent:
+                parent_dir = find_task_by_name(task_parent, tasks_dir)
+                if parent_dir:
+                    parent_json = parent_dir / FILE_TASK_JSON
+                    if parent_json.is_file():
+                        parent_data = read_json(parent_json)
+                        if parent_data:
+                            parent_children = parent_data.get("children", [])
+                            if dir_name in parent_children:
+                                parent_children.remove(dir_name)
+                                parent_data["children"] = parent_children
+                                write_json(parent_json, parent_data)
+
+            # If this is a parent, clear parent field in all children
+            if task_children:
+                for child_name in task_children:
+                    child_dir_path = find_task_by_name(child_name, tasks_dir)
+                    if child_dir_path:
+                        child_json = child_dir_path / FILE_TASK_JSON
+                        if child_json.is_file():
+                            child_data = read_json(child_json)
+                            if child_data:
+                                child_data["parent"] = None
+                                write_json(child_json, child_data)
+
+    # Clear if current task
+    current = get_current_task(repo_root)
+    if current and dir_name in current:
+        clear_current_task(repo_root)
+
+    # Archive
+    result = archive_task_complete(task_dir, repo_root)
+    if "archived_to" in result:
+        archive_dest = Path(result["archived_to"])
+        year_month = archive_dest.parent.name
+        print(colored(f"Archived: {dir_name} -> archive/{year_month}/", Colors.GREEN), file=sys.stderr)
+
+        # Auto-commit unless --no-commit
+        if not getattr(args, "no_commit", False):
+            _auto_commit_archive(dir_name, repo_root)
+
+        # Return the archive path
+        print(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}/{year_month}/{dir_name}")
+
+        # Run hooks with the archived path
+        archived_json = archive_dest / FILE_TASK_JSON
+        run_task_hooks("after_archive", archived_json, repo_root)
+        return 0
+
+    return 1
+
+
+def _auto_commit_archive(task_name: str, repo_root: Path) -> None:
+    """Stage .trellis/tasks/ changes and commit after archive."""
+    tasks_rel = f"{DIR_WORKFLOW}/{DIR_TASKS}"
+    run_git(["add", "-A", tasks_rel], cwd=repo_root)
+
+    # Check if there are staged changes
+    rc, _, _ = run_git(
+        ["diff", "--cached", "--quiet", "--", tasks_rel], cwd=repo_root
+    )
+    if rc == 0:
+        print("[OK] No task changes to commit.", file=sys.stderr)
+        return
+
+    commit_msg = f"chore(task): archive {task_name}"
+    rc, _, err = run_git(["commit", "-m", commit_msg], cwd=repo_root)
+    if rc == 0:
+        print(f"[OK] Auto-committed: {commit_msg}", file=sys.stderr)
+    else:
+        print(f"[WARN] Auto-commit failed: {err.strip()}", file=sys.stderr)
+
+
+# =============================================================================
+# Command: add-subtask
+# =============================================================================
+
+def cmd_add_subtask(args: argparse.Namespace) -> int:
+    """Link a child task to a parent task."""
+    repo_root = get_repo_root()
+
+    parent_dir = resolve_task_dir(args.parent_dir, repo_root)
+    child_dir = resolve_task_dir(args.child_dir, repo_root)
+
+    parent_json_path = parent_dir / FILE_TASK_JSON
+    child_json_path = child_dir / FILE_TASK_JSON
+
+    if not parent_json_path.is_file():
+        print(colored(f"Error: Parent task.json not found: {args.parent_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    if not child_json_path.is_file():
+        print(colored(f"Error: Child task.json not found: {args.child_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    parent_data = read_json(parent_json_path)
+    child_data = read_json(child_json_path)
+
+    if not parent_data or not child_data:
+        print(colored("Error: Failed to read task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Check if child already has a parent
+    existing_parent = child_data.get("parent")
+    if existing_parent:
+        print(colored(f"Error: Child task already has a parent: {existing_parent}", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Add child to parent's children list
+    parent_children = parent_data.get("children", [])
+    child_dir_name = child_dir.name
+    if child_dir_name not in parent_children:
+        parent_children.append(child_dir_name)
+        parent_data["children"] = parent_children
+
+    # Set parent in child's task.json
+    child_data["parent"] = parent_dir.name
+
+    # Write both
+    write_json(parent_json_path, parent_data)
+    write_json(child_json_path, child_data)
+
+    print(colored(f"Linked: {child_dir.name} -> {parent_dir.name}", Colors.GREEN), file=sys.stderr)
+    return 0
+
+
+# =============================================================================
+# Command: remove-subtask
+# =============================================================================
+
+def cmd_remove_subtask(args: argparse.Namespace) -> int:
+    """Unlink a child task from a parent task."""
+    repo_root = get_repo_root()
+
+    parent_dir = resolve_task_dir(args.parent_dir, repo_root)
+    child_dir = resolve_task_dir(args.child_dir, repo_root)
+
+    parent_json_path = parent_dir / FILE_TASK_JSON
+    child_json_path = child_dir / FILE_TASK_JSON
+
+    if not parent_json_path.is_file():
+        print(colored(f"Error: Parent task.json not found: {args.parent_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    if not child_json_path.is_file():
+        print(colored(f"Error: Child task.json not found: {args.child_dir}", Colors.RED), file=sys.stderr)
+        return 1
+
+    parent_data = read_json(parent_json_path)
+    child_data = read_json(child_json_path)
+
+    if not parent_data or not child_data:
+        print(colored("Error: Failed to read task.json", Colors.RED), file=sys.stderr)
+        return 1
+
+    # Remove child from parent's children list
+    parent_children = parent_data.get("children", [])
+    child_dir_name = child_dir.name
+    if child_dir_name in parent_children:
+        parent_children.remove(child_dir_name)
+        parent_data["children"] = parent_children
+
+    # Clear parent in child's task.json
+    child_data["parent"] = None
+
+    # Write both
+    write_json(parent_json_path, parent_data)
+    write_json(child_json_path, child_data)
+
+    print(colored(f"Unlinked: {child_dir.name} from {parent_dir.name}", Colors.GREEN), file=sys.stderr)
+    return 0
+
+
+# =============================================================================
+# Command: set-branch
+# =============================================================================
+
+def cmd_set_branch(args: argparse.Namespace) -> int:
+    """Set git branch for task."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+    branch = args.branch
+
+    if not branch:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py set-branch <task-dir> <branch-name>")
+        return 1
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
+        return 1
+
+    data = read_json(task_json)
+    if not data:
+        return 1
+
+    data["branch"] = branch
+    write_json(task_json, data)
+
+    print(colored(f"✓ Branch set to: {branch}", Colors.GREEN))
+    return 0
+
+
+# =============================================================================
+# Command: set-base-branch
+# =============================================================================
+
+def cmd_set_base_branch(args: argparse.Namespace) -> int:
+    """Set the base branch (PR target) for task."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+    base_branch = args.base_branch
+
+    if not base_branch:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py set-base-branch <task-dir> <base-branch>")
+        print("Example: python3 task.py set-base-branch <dir> develop")
+        print()
+        print("This sets the target branch for PR (the branch your feature will merge into).")
+        return 1
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
+        return 1
+
+    data = read_json(task_json)
+    if not data:
+        return 1
+
+    data["base_branch"] = base_branch
+    write_json(task_json, data)
+
+    print(colored(f"✓ Base branch set to: {base_branch}", Colors.GREEN))
+    print(f"  PR will target: {base_branch}")
+    return 0
+
+
+# =============================================================================
+# Command: set-scope
+# =============================================================================
+
+def cmd_set_scope(args: argparse.Namespace) -> int:
+    """Set scope for PR title."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+    scope = args.scope
+
+    if not scope:
+        print(colored("Error: Missing arguments", Colors.RED))
+        print("Usage: python3 task.py set-scope <task-dir> <scope>")
+        return 1
+
+    task_json = target_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        print(colored(f"Error: task.json not found at {target_dir}", Colors.RED))
+        return 1
+
+    data = read_json(task_json)
+    if not data:
+        return 1
+
+    data["scope"] = scope
+    write_json(task_json, data)
+
+    print(colored(f"✓ Scope set to: {scope}", Colors.GREEN))
+    return 0

.trellis/scripts/common/task_utils.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""
+Task utility functions.
+
+Provides:
+    is_safe_task_path   - Validate task path is safe to operate on
+    find_task_by_name   - Find task directory by name
+    resolve_task_dir    - Resolve task directory from name, relative, or absolute path
+    archive_task_dir    - Archive task to monthly directory
+    run_task_hooks      - Run lifecycle hooks for task events
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import get_repo_root, get_tasks_dir
+
+
+# =============================================================================
+# Path Safety
+# =============================================================================
+
+def is_safe_task_path(task_path: str, repo_root: Path | None = None) -> bool:
+    """Check if a relative task path is safe to operate on.
+
+    Args:
+        task_path: Task path (relative to repo_root).
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True if safe, False if dangerous.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    normalized = task_path.replace("\\", "/")
+
+    # Check empty or null
+    if not normalized or normalized == "null":
+        print("Error: empty or null task path", file=sys.stderr)
+        return False
+
+    # Reject absolute paths
+    if Path(task_path).is_absolute():
+        print(f"Error: absolute path not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Reject ".", "..", paths starting with "./" or "../", or containing ".."
+    if normalized in (".", "..") or normalized.startswith("./") or normalized.startswith("../") or ".." in normalized:
+        print(f"Error: path traversal not allowed: {task_path}", file=sys.stderr)
+        return False
+
+    # Final check: ensure resolved path is not the repo root
+    abs_path = repo_root / Path(normalized)
+    if abs_path.exists():
+        try:
+            resolved = abs_path.resolve()
+            root_resolved = repo_root.resolve()
+            if resolved == root_resolved:
+                print(f"Error: path resolves to repo root: {task_path}", file=sys.stderr)
+                return False
+        except (OSError, IOError):
+            pass
+
+    return True
+
+
+# =============================================================================
+# Task Lookup
+# =============================================================================
+
+def find_task_by_name(task_name: str, tasks_dir: Path) -> Path | None:
+    """Find task directory by name (exact or suffix match).
+
+    Args:
+        task_name: Task name to find.
+        tasks_dir: Tasks directory path.
+
+    Returns:
+        Absolute path to task directory, or None if not found.
+    """
+    if not task_name or not tasks_dir or not tasks_dir.is_dir():
+        return None
+
+    # Try exact match first
+    exact_match = tasks_dir / task_name
+    if exact_match.is_dir():
+        return exact_match
+
+    # Try suffix match (e.g., "my-task" matches "01-21-my-task")
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name.endswith(f"-{task_name}"):
+            return d
+
+    return None
+
+
+# =============================================================================
+# Archive Operations
+# =============================================================================
+
+def archive_task_dir(task_dir_abs: Path, repo_root: Path | None = None) -> Path | None:
+    """Archive a task directory to archive/{YYYY-MM}/.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Path to archived directory, or None on error.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return None
+
+    # Get tasks directory (parent of the task)
+    tasks_dir = task_dir_abs.parent
+    archive_dir = tasks_dir / "archive"
+    year_month = datetime.now().strftime("%Y-%m")
+    month_dir = archive_dir / year_month
+
+    # Create archive directory
+    try:
+        month_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create archive directory: {e}", file=sys.stderr)
+        return None
+
+    # Move task to archive
+    task_name = task_dir_abs.name
+    dest = month_dir / task_name
+
+    try:
+        shutil.move(str(task_dir_abs), str(dest))
+    except (OSError, IOError, shutil.Error) as e:
+        print(f"Error: Failed to move task to archive: {e}", file=sys.stderr)
+        return None
+
+    return dest
+
+
+def archive_task_complete(
+    task_dir_abs: Path,
+    repo_root: Path | None = None
+) -> dict[str, str]:
+    """Complete archive workflow: archive directory.
+
+    Args:
+        task_dir_abs: Absolute path to task directory.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        Dict with archive result info.
+    """
+    if not task_dir_abs.is_dir():
+        print(f"Error: task directory not found: {task_dir_abs}", file=sys.stderr)
+        return {}
+
+    archive_dest = archive_task_dir(task_dir_abs, repo_root)
+    if archive_dest:
+        return {"archived_to": str(archive_dest)}
+
+    return {}
+
+
+# =============================================================================
+# Task Directory Resolution
+# =============================================================================
+
+def resolve_task_dir(target_dir: str, repo_root: Path) -> Path:
+    """Resolve task directory to absolute path.
+
+    Supports:
+    - Absolute path: /path/to/task
+    - Relative path: .trellis/tasks/01-31-my-task
+    - Task name: my-task (uses find_task_by_name for lookup)
+
+    Args:
+        target_dir: Task directory specification.
+        repo_root: Repository root path.
+
+    Returns:
+        Resolved absolute path.
+    """
+    if not target_dir:
+        return Path()
+
+    normalized = target_dir.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    # Absolute path
+    if Path(target_dir).is_absolute():
+        return Path(target_dir)
+
+    # Relative path (contains path separator or starts with .trellis)
+    if "/" in normalized or normalized.startswith(".trellis"):
+        return repo_root / Path(normalized)
+
+    # Task name - try to find in tasks directory
+    tasks_dir = get_tasks_dir(repo_root)
+    found = find_task_by_name(target_dir, tasks_dir)
+    if found:
+        return found
+
+    # Fallback to treating as relative path
+    return repo_root / Path(normalized)
+
+
+# =============================================================================
+# Lifecycle Hooks
+# =============================================================================
+
+def run_task_hooks(event: str, task_json_path: Path, repo_root: Path) -> None:
+    """Run lifecycle hooks for a task event.
+
+    Args:
+        event: Event name (e.g. "after_create").
+        task_json_path: Absolute path to the task's task.json.
+        repo_root: Repository root for cwd and config lookup.
+    """
+    import os
+    import subprocess
+
+    from .config import get_hooks
+    from .log import Colors, colored
+
+    commands = get_hooks(event, repo_root)
+    if not commands:
+        return
+
+    env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
+
+    for cmd in commands:
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=repo_root,
+                env=env,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if result.returncode != 0:
+                print(
+                    colored(f"[WARN] Hook failed ({event}): {cmd}", Colors.YELLOW),
+                    file=sys.stderr,
+                )
+                if result.stderr.strip():
+                    print(f"  {result.stderr.strip()}", file=sys.stderr)
+        except Exception as e:
+            print(
+                colored(f"[WARN] Hook error ({event}): {cmd} — {e}", Colors.YELLOW),
+                file=sys.stderr,
+            )
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    repo = get_repo_root()
+    tasks = get_tasks_dir(repo)
+
+    print(f"Tasks dir: {tasks}")
+    print(f"is_safe_task_path('.trellis/tasks/test'): {is_safe_task_path('.trellis/tasks/test', repo)}")
+    print(f"is_safe_task_path('../test'): {is_safe_task_path('../test', repo)}")

.trellis/scripts/common/tasks.py

@@ -0,0 +1,109 @@
+"""
+Task data access layer.
+
+Single source of truth for loading and iterating task directories.
+Replaces scattered task.json parsing across 9+ files.
+
+Provides:
+    load_task          — Load a single task by directory path
+    iter_active_tasks  — Iterate all non-archived tasks (sorted)
+    get_all_statuses   — Get {dir_name: status} map for children progress
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from .io import read_json
+from .paths import FILE_TASK_JSON
+from .types import TaskInfo
+
+
+def load_task(task_dir: Path) -> TaskInfo | None:
+    """Load task from a directory containing task.json.
+
+    Args:
+        task_dir: Absolute path to the task directory.
+
+    Returns:
+        TaskInfo if task.json exists and is valid, None otherwise.
+    """
+    task_json = task_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        return None
+
+    data = read_json(task_json)
+    if not data:
+        return None
+
+    return TaskInfo(
+        dir_name=task_dir.name,
+        directory=task_dir,
+        title=data.get("title") or data.get("name") or "unknown",
+        status=data.get("status", "unknown"),
+        assignee=data.get("assignee", ""),
+        priority=data.get("priority", "P2"),
+        children=tuple(data.get("children", [])),
+        parent=data.get("parent"),
+        package=data.get("package"),
+        raw=data,
+    )
+
+
+def iter_active_tasks(tasks_dir: Path) -> Iterator[TaskInfo]:
+    """Iterate all active (non-archived) tasks, sorted by directory name.
+
+    Skips the "archive" directory and directories without valid task.json.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Yields:
+        TaskInfo for each valid task.
+    """
+    if not tasks_dir.is_dir():
+        return
+
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir() or d.name == "archive":
+            continue
+        info = load_task(d)
+        if info is not None:
+            yield info
+
+
+def get_all_statuses(tasks_dir: Path) -> dict[str, str]:
+    """Get a {dir_name: status} mapping for all active tasks.
+
+    Useful for computing children progress without loading full TaskInfo.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Returns:
+        Dict mapping directory names to status strings.
+    """
+    return {t.dir_name: t.status for t in iter_active_tasks(tasks_dir)}
+
+
+def children_progress(
+    children: tuple[str, ...] | list[str],
+    all_statuses: dict[str, str],
+) -> str:
+    """Format children progress string like " [2/3 done]".
+
+    Args:
+        children: List of child directory names.
+        all_statuses: Status map from get_all_statuses().
+
+    Returns:
+        Formatted string, or "" if no children.
+    """
+    if not children:
+        return ""
+    done = sum(
+        1 for c in children
+        if all_statuses.get(c) in ("completed", "done")
+    )
+    return f" [{done}/{len(children)} done]"

.trellis/scripts/common/types.py

@@ -0,0 +1,110 @@
+"""
+Core type definitions for Trellis task data.
+
+Provides:
+    TaskData     — TypedDict for task.json shape (read-path type hints only)
+    TaskInfo     — Frozen dataclass for loaded task (the public API type)
+    AgentRecord  — TypedDict for registry.json agent entries
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict
+
+
+# =============================================================================
+# task.json shape (TypedDict — used only for read-path type hints)
+# =============================================================================
+
+class TaskData(TypedDict, total=False):
+    """Shape of task.json on disk.
+
+    Used only for type annotations when reading task.json.
+    Writes must use the original dict to avoid losing unknown fields.
+    """
+
+    id: str
+    name: str
+    title: str
+    description: str
+    status: str
+    dev_type: str
+    scope: str | None
+    package: str | None
+    priority: str
+    creator: str
+    assignee: str
+    createdAt: str
+    completedAt: str | None
+    branch: str | None
+    base_branch: str | None
+    worktree_path: str | None
+    commit: str | None
+    pr_url: str | None
+    subtasks: list[str]
+    children: list[str]
+    parent: str | None
+    relatedFiles: list[str]
+    notes: str
+    meta: dict
+
+
+# =============================================================================
+# Loaded task object (frozen dataclass — the public API type)
+# =============================================================================
+
+@dataclass(frozen=True)
+class TaskInfo:
+    """Immutable view of a loaded task.
+
+    Created by load_task() / iter_active_tasks().
+    Contains the commonly accessed fields; the original dict
+    is preserved in `raw` for write-back and uncommon field access.
+    """
+
+    dir_name: str
+    directory: Path
+    title: str
+    status: str
+    assignee: str
+    priority: str
+    children: tuple[str, ...]
+    parent: str | None
+    package: str | None
+    raw: dict  # original dict — use for writes and uncommon fields
+
+    @property
+    def name(self) -> str:
+        """Task name (id or name field)."""
+        return self.raw.get("name") or self.raw.get("id") or self.dir_name
+
+    @property
+    def description(self) -> str:
+        return self.raw.get("description", "")
+
+    @property
+    def branch(self) -> str | None:
+        return self.raw.get("branch")
+
+    @property
+    def meta(self) -> dict:
+        return self.raw.get("meta", {})
+
+
+# =============================================================================
+# registry.json agent entry
+# =============================================================================
+
+class AgentRecord(TypedDict, total=False):
+    """Shape of an agent entry in registry.json."""
+
+    id: str
+    pid: int
+    task_dir: str
+    worktree_path: str
+    branch: str
+    platform: str
+    started_at: str
+    status: str

.trellis/scripts/common/workflow_phase.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Workflow Phase Extraction.
+
+Extracts step-level content from .trellis/workflow.md and optionally filters
+platform-specific blocks.
+
+Platform marker syntax in workflow.md:
+
+    [Claude Code, Cursor, ...]
+    agent-capable content
+    [/Claude Code, Cursor, ...]
+
+Provides:
+    get_phase_index   - Extract the Phase Index section (no --step)
+    get_step          - Extract a single step (#### X.X) section
+    filter_platform   - Strip platform blocks that don't include the given name
+"""
+
+from __future__ import annotations
+
+import re
+
+from .paths import DIR_WORKFLOW, get_repo_root
+
+
+def _workflow_md_path():
+    return get_repo_root() / DIR_WORKFLOW / "workflow.md"
+
+# Match a line that *is* a platform marker: "[A, B, C]" or "[/A, B, C]"
+_MARKER_RE = re.compile(r"^\[(/?)([A-Za-z][^\[\]]*)\]\s*$")
+
+# Step heading: "#### 1.0 Title" or "#### 1.0 ..."
+_STEP_HEADING_RE = re.compile(r"^####\s+(\d+\.\d+)\b.*$")
+
+# Phase Index starts here; Phase 1/2/3 step bodies follow; ends at Breadcrumbs.
+_PHASE_INDEX_HEADING = "## Phase Index"
+
+
+def _read_workflow() -> str:
+    path = _workflow_md_path()
+    if not path.exists():
+        raise FileNotFoundError(f"workflow.md not found: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def _parse_marker(line: str) -> tuple[bool, list[str]] | None:
+    """Parse a platform marker line.
+
+    Returns:
+        (is_closing, [platform_names]) if line is a marker, else None.
+    """
+    m = _MARKER_RE.match(line)
+    if not m:
+        return None
+    is_closing = m.group(1) == "/"
+    names = [p.strip() for p in m.group(2).split(",") if p.strip()]
+    return is_closing, names
+
+
+def get_phase_index() -> str:
+    """Return Phase Index + Phase 1/2/3 step bodies from workflow.md.
+
+    Matches what the SessionStart hook injects into the `<workflow>` block:
+    starts at `## Phase Index`, continues through `## Phase 1: Plan`,
+    `## Phase 2: Execute`, `## Phase 3: Finish`, stops at
+    `## Workflow State Breadcrumbs` (consumed by UserPromptSubmit hook).
+    """
+    text = _read_workflow()
+    lines = text.splitlines()
+
+    start: int | None = None
+    end: int | None = None
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if start is None and stripped == _PHASE_INDEX_HEADING:
+            start = i
+            continue
+        if start is not None and stripped == "## Workflow State Breadcrumbs":
+            end = i
+            break
+
+    if start is None:
+        return ""
+    if end is None:
+        end = len(lines)
+    return "\n".join(lines[start:end]).rstrip() + "\n"
+
+
+def get_step(step_id: str) -> str:
+    """Return the `#### X.X` section matching step_id (header + body).
+
+    Body ends at the next `####` or `---` or `##` heading (whichever comes first).
+    """
+    text = _read_workflow()
+    lines = text.splitlines()
+
+    start: int | None = None
+    for i, line in enumerate(lines):
+        m = _STEP_HEADING_RE.match(line)
+        if m and m.group(1) == step_id:
+            start = i
+            break
+    if start is None:
+        return ""
+
+    end: int = len(lines)
+    for j in range(start + 1, len(lines)):
+        line = lines[j]
+        if line.startswith("#### "):
+            end = j
+            break
+        if line.startswith("## "):
+            end = j
+            break
+        # Horizontal rule at column 0
+        if line.strip() == "---":
+            end = j
+            break
+
+    return "\n".join(lines[start:end]).rstrip() + "\n"
+
+
+def _platform_matches(platform: str, block_names: list[str]) -> bool:
+    """Case-insensitive fuzzy match: accept 'cursor', 'Cursor', 'claude-code', 'Claude Code'."""
+    needle = platform.lower().replace("-", "").replace("_", "").replace(" ", "")
+    for name in block_names:
+        hay = name.lower().replace("-", "").replace("_", "").replace(" ", "")
+        if needle == hay:
+            return True
+    return False
+
+
+def filter_platform(content: str, platform: str) -> str:
+    """Keep lines outside any `[...]` block + lines inside blocks that include platform.
+
+    Marker lines themselves are dropped from the output.
+    """
+    lines = content.splitlines()
+    out: list[str] = []
+
+    in_block = False
+    keep_block = False
+
+    for line in lines:
+        marker = _parse_marker(line)
+        if marker is not None:
+            is_closing, names = marker
+            if not is_closing:
+                in_block = True
+                keep_block = _platform_matches(platform, names)
+            else:
+                in_block = False
+                keep_block = False
+            continue  # drop the marker line itself
+
+        if in_block:
+            if keep_block:
+                out.append(line)
+            continue
+        out.append(line)
+
+    # Collapse runs of 3+ blank lines that may arise from dropped markers
+    collapsed: list[str] = []
+    blank_run = 0
+    for line in out:
+        if line.strip() == "":
+            blank_run += 1
+            if blank_run <= 2:
+                collapsed.append(line)
+        else:
+            blank_run = 0
+            collapsed.append(line)
+
+    return "\n".join(collapsed).rstrip() + "\n"

.trellis/scripts/get_context.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""
+Get Session Context for AI Agent.
+
+Usage:
+    python3 get_context.py           Output context in text format
+    python3 get_context.py --json    Output context in JSON format
+"""
+
+from __future__ import annotations
+
+from common.git_context import main
+
+
+if __name__ == "__main__":
+    main()

.trellis/scripts/get_developer.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Get current developer name.
+
+This is a wrapper that uses common/paths.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import get_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    developer = get_developer()
+    if developer:
+        print(developer)
+    else:
+        print("Developer not initialized", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

.trellis/scripts/hooks/linear_sync.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Linear sync hook for Trellis task lifecycle.
+
+Syncs task events to Linear via the `linearis` CLI.
+
+Usage (called automatically by task.py hooks):
+    python3 .trellis/scripts/hooks/linear_sync.py create
+    python3 .trellis/scripts/hooks/linear_sync.py start
+    python3 .trellis/scripts/hooks/linear_sync.py archive
+
+Manual usage:
+    TASK_JSON_PATH=.trellis/tasks/<name>/task.json python3 .trellis/scripts/hooks/linear_sync.py sync
+
+Environment:
+    TASK_JSON_PATH  - Absolute path to task.json (set by task.py)
+
+Configuration:
+    .trellis/hooks.local.json  - Local config (gitignored), example:
+    {
+      "linear": {
+        "team": "TEAM_KEY",
+        "project": "Project Name",
+        "assignees": {
+          "dev-name": "linear-user-id"
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+# Trellis priority → Linear priority (1=Urgent, 2=High, 3=Medium, 4=Low)
+PRIORITY_MAP = {"P0": 1, "P1": 2, "P2": 3, "P3": 4}
+
+# Linear status names (must match your team's workflow)
+STATUS_IN_PROGRESS = "In Progress"
+STATUS_DONE = "Done"
+
+
+def _load_config() -> dict:
+    """Load local hook config from .trellis/hooks.local.json."""
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    if task_json_path:
+        # Walk up from task.json to find .trellis/
+        trellis_dir = Path(task_json_path).parent.parent.parent
+    else:
+        trellis_dir = Path(".trellis")
+
+    config_path = trellis_dir / "hooks.local.json"
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+CONFIG = _load_config()
+LINEAR_CFG = CONFIG.get("linear", {})
+
+TEAM = LINEAR_CFG.get("team", "")
+PROJECT = LINEAR_CFG.get("project", "")
+ASSIGNEE_MAP = LINEAR_CFG.get("assignees", {})
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _read_task() -> tuple[dict, str]:
+    path = os.environ.get("TASK_JSON_PATH", "")
+    if not path:
+        print("TASK_JSON_PATH not set", file=sys.stderr)
+        sys.exit(1)
+    with open(path, encoding="utf-8") as f:
+        return json.load(f), path
+
+
+def _write_task(data: dict, path: str) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def _linearis(*args: str) -> dict | None:
+    result = subprocess.run(
+        ["linearis", *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        print(f"linearis error: {result.stderr.strip()}", file=sys.stderr)
+        sys.exit(1)
+    stdout = result.stdout.strip()
+    if stdout:
+        return json.loads(stdout)
+    return None
+
+
+def _get_linear_issue(task: dict) -> str | None:
+    meta = task.get("meta")
+    if isinstance(meta, dict):
+        return meta.get("linear_issue")
+    return None
+
+
+# ─── Actions ──────────────────────────────────────────────────────────────────
+
+
+def cmd_create() -> None:
+    if not TEAM:
+        print("No linear.team configured in hooks.local.json", file=sys.stderr)
+        sys.exit(1)
+
+    task, path = _read_task()
+
+    # Skip if already linked
+    if _get_linear_issue(task):
+        print(f"Already linked: {_get_linear_issue(task)}")
+        return
+
+    title = task.get("title") or task.get("name") or "Untitled"
+    args = ["issues", "create", title, "--team", TEAM]
+
+    # Map priority
+    priority = PRIORITY_MAP.get(task.get("priority", ""), 0)
+    if priority:
+        args.extend(["-p", str(priority)])
+
+    # Set project
+    if PROJECT:
+        args.extend(["--project", PROJECT])
+
+    # Assign to Linear user
+    assignee = task.get("assignee", "")
+    linear_user_id = ASSIGNEE_MAP.get(assignee)
+    if linear_user_id:
+        args.extend(["--assignee", linear_user_id])
+
+    # Link to parent's Linear issue if available
+    parent_issue = _resolve_parent_linear_issue(task)
+    if parent_issue:
+        args.extend(["--parent-ticket", parent_issue])
+
+    result = _linearis(*args)
+    if result and "identifier" in result:
+        if not isinstance(task.get("meta"), dict):
+            task["meta"] = {}
+        task["meta"]["linear_issue"] = result["identifier"]
+        _write_task(task, path)
+        print(f"Created Linear issue: {result['identifier']}")
+
+
+def cmd_start() -> None:
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        return
+    _linearis("issues", "update", issue, "-s", STATUS_IN_PROGRESS)
+    print(f"Updated {issue} -> {STATUS_IN_PROGRESS}")
+    cmd_sync()
+
+
+def cmd_archive() -> None:
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        return
+    _linearis("issues", "update", issue, "-s", STATUS_DONE)
+    print(f"Updated {issue} -> {STATUS_DONE}")
+
+
+def cmd_sync() -> None:
+    """Sync prd.md content to Linear issue description."""
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        print("No linear_issue in meta, run create first", file=sys.stderr)
+        sys.exit(1)
+
+    # Find prd.md next to task.json
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    prd_path = Path(task_json_path).parent / "prd.md"
+    if not prd_path.is_file():
+        print(f"No prd.md found at {prd_path}", file=sys.stderr)
+        sys.exit(1)
+
+    description = prd_path.read_text(encoding="utf-8").strip()
+    _linearis("issues", "update", issue, "-d", description)
+    print(f"Synced prd.md to {issue} description")
+
+
+# ─── Parent Issue Resolution ─────────────────────────────────────────────────
+
+
+def _resolve_parent_linear_issue(task: dict) -> str | None:
+    """Find parent task's Linear issue identifier."""
+    parent_name = task.get("parent")
+    if not parent_name:
+        return None
+
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    if not task_json_path:
+        return None
+
+    current_task_dir = Path(task_json_path).parent
+    tasks_dir = current_task_dir.parent
+    parent_json = tasks_dir / parent_name / "task.json"
+
+    if parent_json.exists():
+        try:
+            with open(parent_json, encoding="utf-8") as f:
+                parent_task = json.load(f)
+            return _get_linear_issue(parent_task)
+        except (json.JSONDecodeError, OSError):
+            pass
+    return None
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    action = sys.argv[1] if len(sys.argv) > 1 else ""
+    actions = {
+        "create": cmd_create,
+        "start": cmd_start,
+        "archive": cmd_archive,
+        "sync": cmd_sync,
+    }
+    fn = actions.get(action)
+    if fn:
+        fn()
+    else:
+        print(f"Unknown action: {action}", file=sys.stderr)
+        print(f"Valid actions: {', '.join(actions)}", file=sys.stderr)
+        sys.exit(1)

.trellis/scripts/init_developer.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Initialize developer for workflow.
+
+Usage:
+    python3 init_developer.py <developer-name>
+
+This creates:
+    - .trellis/.developer file with developer info
+    - .trellis/workspace/<name>/ directory structure
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import (
+    DIR_WORKFLOW,
+    FILE_DEVELOPER,
+    get_developer,
+)
+from common.developer import init_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <developer-name>")
+        print()
+        print("Example:")
+        print(f"  {sys.argv[0]} john")
+        sys.exit(1)
+
+    name = sys.argv[1]
+
+    # Check if already initialized
+    existing = get_developer()
+    if existing:
+        print(f"Developer already initialized: {existing}")
+        print()
+        print(f"To reinitialize, remove {DIR_WORKFLOW}/{FILE_DEVELOPER} first")
+        sys.exit(0)
+
+    if init_developer(name):
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

.trellis/scripts/task.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Task Management Script.
+
+Usage:
+    python3 task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>]
+    python3 task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
+    python3 task.py validate <dir>              # Validate jsonl files
+    python3 task.py list-context <dir>          # List jsonl entries
+    python3 task.py start <dir>                 # Set as current task
+    python3 task.py finish                      # Clear current task
+    python3 task.py set-branch <dir> <branch>   # Set git branch
+    python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
+    python3 task.py set-scope <dir> <scope>     # Set scope for PR title
+    python3 task.py archive <task-name>         # Archive completed task
+    python3 task.py list                        # List active tasks
+    python3 task.py list-archive [month]        # List archived tasks
+    python3 task.py add-subtask <parent-dir> <child-dir>     # Link child to parent
+    python3 task.py remove-subtask <parent-dir> <child-dir>  # Unlink child from parent
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from common.log import Colors, colored
+from common.paths import (
+    DIR_WORKFLOW,
+    DIR_TASKS,
+    FILE_TASK_JSON,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+    get_current_task,
+    set_current_task,
+    clear_current_task,
+)
+from common.io import read_json, write_json
+from common.task_utils import resolve_task_dir, run_task_hooks
+from common.tasks import iter_active_tasks, children_progress
+
+# Import command handlers from split modules (also re-exports for plan.py compatibility)
+from common.task_store import (
+    cmd_create,
+    cmd_archive,
+    cmd_set_branch,
+    cmd_set_base_branch,
+    cmd_set_scope,
+    cmd_add_subtask,
+    cmd_remove_subtask,
+)
+from common.task_context import (
+    cmd_add_context,
+    cmd_validate,
+    cmd_list_context,
+)
+
+
+# =============================================================================
+# Command: start / finish
+# =============================================================================
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """Set current task."""
+    repo_root = get_repo_root()
+    task_input = args.dir
+
+    if not task_input:
+        print(colored("Error: task directory or name required", Colors.RED))
+        return 1
+
+    # Resolve task directory (supports task name, relative path, or absolute path)
+    full_path = resolve_task_dir(task_input, repo_root)
+
+    if not full_path.is_dir():
+        print(colored(f"Error: Task not found: {task_input}", Colors.RED))
+        print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.trellis/tasks/01-31-my-task')")
+        return 1
+
+    # Convert to relative path for storage
+    try:
+        task_dir = full_path.relative_to(repo_root).as_posix()
+    except ValueError:
+        task_dir = str(full_path)
+
+    if set_current_task(task_dir, repo_root):
+        print(colored(f"✓ Current task set to: {task_dir}", Colors.GREEN))
+
+        task_json_path = full_path / FILE_TASK_JSON
+        if task_json_path.is_file():
+            data = read_json(task_json_path)
+            if data and data.get("status") == "planning":
+                data["status"] = "in_progress"
+                if write_json(task_json_path, data):
+                    print(colored("✓ Status: planning → in_progress", Colors.GREEN))
+
+        print()
+        print(colored("The hook will now inject context from this task's jsonl files.", Colors.BLUE))
+
+        run_task_hooks("after_start", task_json_path, repo_root)
+        return 0
+    else:
+        print(colored("Error: Failed to set current task", Colors.RED))
+        return 1
+
+
+def cmd_finish(args: argparse.Namespace) -> int:
+    """Clear current task."""
+    _ = args  # signature required by argparse dispatcher
+    repo_root = get_repo_root()
+    current = get_current_task(repo_root)
+
+    if not current:
+        print(colored("No current task set", Colors.YELLOW))
+        return 0
+
+    # Resolve task.json path before clearing
+    task_json_path = repo_root / current / FILE_TASK_JSON
+
+    clear_current_task(repo_root)
+    print(colored(f"✓ Cleared current task (was: {current})", Colors.GREEN))
+
+    if task_json_path.is_file():
+        run_task_hooks("after_finish", task_json_path, repo_root)
+    return 0
+
+
+# =============================================================================
+# Command: list
+# =============================================================================
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """List active tasks."""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    current_task = get_current_task(repo_root)
+    developer = get_developer(repo_root)
+    filter_mine = args.mine
+    filter_status = args.status
+
+    if filter_mine:
+        if not developer:
+            print(colored("Error: No developer set. Run init_developer.py first", Colors.RED), file=sys.stderr)
+            return 1
+        print(colored(f"My tasks (assignee: {developer}):", Colors.BLUE))
+    else:
+        print(colored("All active tasks:", Colors.BLUE))
+    print()
+
+    # Single pass: collect all tasks via shared iterator
+    all_tasks = {t.dir_name: t for t in iter_active_tasks(tasks_dir)}
+    all_statuses = {name: t.status for name, t in all_tasks.items()}
+
+    # Display tasks hierarchically
+    count = 0
+
+    def _print_task(dir_name: str, indent: int = 0) -> None:
+        nonlocal count
+        t = all_tasks[dir_name]
+
+        # Apply --mine filter
+        if filter_mine and (t.assignee or "-") != developer:
+            return
+
+        # Apply --status filter
+        if filter_status and t.status != filter_status:
+            return
+
+        relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
+        marker = ""
+        if relative_path == current_task:
+            marker = f" {colored('<- current', Colors.GREEN)}"
+
+        # Children progress
+        progress = children_progress(t.children, all_statuses)
+
+        # Package tag
+        pkg_tag = f" @{t.package}" if t.package else ""
+
+        prefix = "  " * indent + "  - "
+
+        if filter_mine:
+            print(f"{prefix}{dir_name}/ ({t.status}){pkg_tag}{progress}{marker}")
+        else:
+            print(f"{prefix}{dir_name}/ ({t.status}){pkg_tag}{progress} [{colored(t.assignee or '-', Colors.CYAN)}]{marker}")
+        count += 1
+
+        # Print children indented
+        for child_name in t.children:
+            if child_name in all_tasks:
+                _print_task(child_name, indent + 1)
+
+    # Display only top-level tasks (those without a parent)
+    for dir_name in sorted(all_tasks.keys()):
+        if not all_tasks[dir_name].parent:
+            _print_task(dir_name)
+
+    if count == 0:
+        if filter_mine:
+            print("  (no tasks assigned to you)")
+        else:
+            print("  (no active tasks)")
+
+    print()
+    print(f"Total: {count} task(s)")
+    return 0
+
+
+# =============================================================================
+# Command: list-archive
+# =============================================================================
+
+def cmd_list_archive(args: argparse.Namespace) -> int:
+    """List archived tasks."""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    archive_dir = tasks_dir / "archive"
+    month = args.month
+
+    print(colored("Archived tasks:", Colors.BLUE))
+    print()
+
+    if month:
+        month_dir = archive_dir / month
+        if month_dir.is_dir():
+            print(f"[{month}]")
+            for d in sorted(month_dir.iterdir()):
+                if d.is_dir():
+                    print(f"  - {d.name}/")
+        else:
+            print(f"  No archives for {month}")
+    else:
+        if archive_dir.is_dir():
+            for month_dir in sorted(archive_dir.iterdir()):
+                if month_dir.is_dir():
+                    month_name = month_dir.name
+                    count = sum(1 for d in month_dir.iterdir() if d.is_dir())
+                    print(f"[{month_name}] - {count} task(s)")
+
+    return 0
+
+
+# =============================================================================
+# Help
+# =============================================================================
+
+def show_usage() -> None:
+    """Show usage help."""
+    print("""Task Management Script
+
+Usage:
+  python3 task.py create <title>                     Create new task directory
+  python3 task.py create <title> --package <pkg>     Create task for a specific package
+  python3 task.py create <title> --parent <dir>      Create task as child of parent
+  python3 task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
+  python3 task.py validate <dir>                     Validate jsonl files
+  python3 task.py list-context <dir>                 List jsonl entries
+  python3 task.py start <dir>                        Set as current task
+  python3 task.py finish                             Clear current task
+  python3 task.py set-branch <dir> <branch>          Set git branch
+  python3 task.py set-base-branch <dir> <branch>     Set PR target branch
+  python3 task.py set-scope <dir> <scope>            Set scope for PR title
+  python3 task.py archive <task-name>                Archive completed task
+  python3 task.py add-subtask <parent> <child>       Link child task to parent
+  python3 task.py remove-subtask <parent> <child>    Unlink child from parent
+  python3 task.py list [--mine] [--status <status>]  List tasks
+  python3 task.py list-archive [YYYY-MM]             List archived tasks
+
+Monorepo options:
+  --package <pkg>      Package name (validated against config.yaml packages)
+
+List options:
+  --mine, -m           Show only tasks assigned to current developer
+  --status, -s <s>     Filter by status (planning, in_progress, review, completed)
+
+Examples:
+  python3 task.py create "Add login feature" --slug add-login
+  python3 task.py create "Add login feature" --slug add-login --package cli
+  python3 task.py create "Child task" --slug child --parent .trellis/tasks/01-21-parent
+  python3 task.py add-context <dir> implement .trellis/spec/cli/backend/auth.md "Auth guidelines"
+  python3 task.py set-branch <dir> task/add-login
+  python3 task.py start .trellis/tasks/01-21-add-login
+  python3 task.py finish
+  python3 task.py archive add-login
+  python3 task.py add-subtask parent-task child-task  # Link existing tasks
+  python3 task.py remove-subtask parent-task child-task
+  python3 task.py list                               # List all active tasks
+  python3 task.py list --mine                        # List my tasks only
+  python3 task.py list --mine --status in_progress   # List my in-progress tasks
+""")
+
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+def main() -> int:
+    """CLI entry point."""
+    # Deprecation guard: `init-context` was removed in v0.5.0-beta.12.
+    # Detect early so argparse doesn't mask the real reason with a generic
+    # "invalid choice" error.
+    if len(sys.argv) >= 2 and sys.argv[1] == "init-context":
+        print(
+            colored(
+                "Error: `task.py init-context` was removed in v0.5.0-beta.12.",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        print(
+            "implement.jsonl / check.jsonl are now seeded on `task.py create` for",
+            file=sys.stderr,
+        )
+        print(
+            "sub-agent-capable platforms and curated by the AI during Phase 1.3.",
+            file=sys.stderr,
+        )
+        print("See .trellis/workflow.md Phase 1.3 or run:", file=sys.stderr)
+        print(
+            "  python3 ./.trellis/scripts/get_context.py --mode phase --step 1.3",
+            file=sys.stderr,
+        )
+        print(
+            "Use `task.py add-context <dir> implement|check <path> <reason>` to append entries.",
+            file=sys.stderr,
+        )
+        return 2
+
+    parser = argparse.ArgumentParser(
+        description="Task Management Script",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # create
+    p_create = subparsers.add_parser("create", help="Create new task")
+    p_create.add_argument("title", help="Task title")
+    p_create.add_argument("--slug", "-s", help="Task slug")
+    p_create.add_argument("--assignee", "-a", help="Assignee developer")
+    p_create.add_argument("--priority", "-p", default="P2", help="Priority (P0-P3)")
+    p_create.add_argument("--description", "-d", help="Task description")
+    p_create.add_argument("--parent", help="Parent task directory (establishes subtask link)")
+    p_create.add_argument("--package", help="Package name for monorepo projects")
+
+    # add-context
+    p_add = subparsers.add_parser("add-context", help="Add context entry")
+    p_add.add_argument("dir", help="Task directory")
+    p_add.add_argument("file", help="JSONL file (implement|check)")
+    p_add.add_argument("path", help="File path to add")
+    p_add.add_argument("reason", nargs="?", help="Reason for adding")
+
+    # validate
+    p_validate = subparsers.add_parser("validate", help="Validate context files")
+    p_validate.add_argument("dir", help="Task directory")
+
+    # list-context
+    p_listctx = subparsers.add_parser("list-context", help="List context entries")
+    p_listctx.add_argument("dir", help="Task directory")
+
+    # start
+    p_start = subparsers.add_parser("start", help="Set current task")
+    p_start.add_argument("dir", help="Task directory")
+
+    # finish
+    subparsers.add_parser("finish", help="Clear current task")
+
+    # set-branch
+    p_branch = subparsers.add_parser("set-branch", help="Set git branch")
+    p_branch.add_argument("dir", help="Task directory")
+    p_branch.add_argument("branch", help="Branch name")
+
+    # set-base-branch
+    p_base = subparsers.add_parser("set-base-branch", help="Set PR target branch")
+    p_base.add_argument("dir", help="Task directory")
+    p_base.add_argument("base_branch", help="Base branch name (PR target)")
+
+    # set-scope
+    p_scope = subparsers.add_parser("set-scope", help="Set scope")
+    p_scope.add_argument("dir", help="Task directory")
+    p_scope.add_argument("scope", help="Scope name")
+
+    # archive
+    p_archive = subparsers.add_parser("archive", help="Archive task")
+    p_archive.add_argument("name", help="Task name")
+    p_archive.add_argument("--no-commit", action="store_true", help="Skip auto git commit after archive")
+
+    # list
+    p_list = subparsers.add_parser("list", help="List tasks")
+    p_list.add_argument("--mine", "-m", action="store_true", help="My tasks only")
+    p_list.add_argument("--status", "-s", help="Filter by status")
+
+    # add-subtask
+    p_addsub = subparsers.add_parser("add-subtask", help="Link child task to parent")
+    p_addsub.add_argument("parent_dir", help="Parent task directory")
+    p_addsub.add_argument("child_dir", help="Child task directory")
+
+    # remove-subtask
+    p_rmsub = subparsers.add_parser("remove-subtask", help="Unlink child task from parent")
+    p_rmsub.add_argument("parent_dir", help="Parent task directory")
+    p_rmsub.add_argument("child_dir", help="Child task directory")
+
+    # list-archive
+    p_listarch = subparsers.add_parser("list-archive", help="List archived tasks")
+    p_listarch.add_argument("month", nargs="?", help="Month (YYYY-MM)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        show_usage()
+        return 1
+
+    commands = {
+        "create": cmd_create,
+        "add-context": cmd_add_context,
+        "validate": cmd_validate,
+        "list-context": cmd_list_context,
+        "start": cmd_start,
+        "finish": cmd_finish,
+        "set-branch": cmd_set_branch,
+        "set-base-branch": cmd_set_base_branch,
+        "set-scope": cmd_set_scope,
+        "archive": cmd_archive,
+        "add-subtask": cmd_add_subtask,
+        "remove-subtask": cmd_remove_subtask,
+        "list": cmd_list,
+        "list-archive": cmd_list_archive,
+    }
+
+    if args.command in commands:
+        return commands[args.command](args)
+    else:
+        show_usage()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.trellis/spec/backend/database-guidelines.md

@@ -0,0 +1,51 @@
+# Database Guidelines
+
+> Database patterns and conventions for this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's database conventions here.
+
+Questions to answer:
+- What ORM/query library do you use?
+- How are migrations managed?
+- What are the naming conventions for tables/columns?
+- How do you handle transactions?
+-->
+
+(To be filled by the team)
+
+---
+
+## Query Patterns
+
+<!-- How should queries be written? Batch operations? -->
+
+(To be filled by the team)
+
+---
+
+## Migrations
+
+<!-- How to create and run migrations -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Table names, column names, index names -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Database-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/backend/directory-structure.md

@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How backend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's backend directory structure here.
+
+Questions to answer:
+- How are modules/packages organized?
+- Where does business logic live?
+- Where are API endpoints defined?
+- How are utilities and helpers organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features/modules be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)

.trellis/spec/backend/error-handling.md

@@ -0,0 +1,51 @@
+# Error Handling
+
+> How errors are handled in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's error handling conventions here.
+
+Questions to answer:
+- What error types do you define?
+- How are errors propagated?
+- How are errors logged?
+- How are errors returned to clients?
+-->
+
+(To be filled by the team)
+
+---
+
+## Error Types
+
+<!-- Custom error classes/types -->
+
+(To be filled by the team)
+
+---
+
+## Error Handling Patterns
+
+<!-- Try-catch patterns, error propagation -->
+
+(To be filled by the team)
+
+---
+
+## API Error Responses
+
+<!-- Standard error response format -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Error handling mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/backend/index.md

@@ -0,0 +1,38 @@
+# Backend Development Guidelines
+
+> Best practices for backend development in this project.
+
+---
+
+## Overview
+
+This directory contains guidelines for backend development. Fill in each file with your project's specific conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
+| [Database Guidelines](./database-guidelines.md) | ORM patterns, queries, migrations | To fill |
+| [Error Handling](./error-handling.md) | Error types, handling strategies | To fill |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
+| [Logging Guidelines](./logging-guidelines.md) | Structured logging, log levels | To fill |
+
+---
+
+## How to Fill These Guidelines
+
+For each guideline file:
+
+1. Document your project's **actual conventions** (not ideals)
+2. Include **code examples** from your codebase
+3. List **forbidden patterns** and why
+4. Add **common mistakes** your team has made
+
+The goal is to help AI assistants and new team members understand how YOUR project works.
+
+---
+
+**Language**: All documentation should be written in **English**.

.trellis/spec/backend/logging-guidelines.md

@@ -0,0 +1,51 @@
+# Logging Guidelines
+
+> How logging is done in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's logging conventions here.
+
+Questions to answer:
+- What logging library do you use?
+- What are the log levels and when to use each?
+- What should be logged?
+- What should NOT be logged (PII, secrets)?
+-->
+
+(To be filled by the team)
+
+---
+
+## Log Levels
+
+<!-- When to use each level: debug, info, warn, error -->
+
+(To be filled by the team)
+
+---
+
+## Structured Logging
+
+<!-- Log format, required fields -->
+
+(To be filled by the team)
+
+---
+
+## What to Log
+
+<!-- Important events to log -->
+
+(To be filled by the team)
+
+---
+
+## What NOT to Log
+
+<!-- Sensitive data, PII, secrets -->
+
+(To be filled by the team)

.trellis/spec/backend/quality-guidelines.md

@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for backend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

.trellis/spec/frontend/component-guidelines.md

@@ -0,0 +1,59 @@
+# Component Guidelines
+
+> How components are built in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's component conventions here.
+
+Questions to answer:
+- What component patterns do you use?
+- How are props defined?
+- How do you handle composition?
+- What accessibility standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Component Structure
+
+<!-- Standard structure of a component file -->
+
+(To be filled by the team)
+
+---
+
+## Props Conventions
+
+<!-- How props should be defined and typed -->
+
+(To be filled by the team)
+
+---
+
+## Styling Patterns
+
+<!-- How styles are applied (CSS modules, styled-components, Tailwind, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Accessibility
+
+<!-- A11y requirements and patterns -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Component-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/directory-structure.md

@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How frontend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's frontend directory structure here.
+
+Questions to answer:
+- Where do components live?
+- How are features/modules organized?
+- Where are shared utilities?
+- How are assets organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)

.trellis/spec/frontend/hook-guidelines.md

@@ -0,0 +1,51 @@
+# Hook Guidelines
+
+> How hooks are used in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's hook conventions here.
+
+Questions to answer:
+- What custom hooks do you have?
+- How do you handle data fetching?
+- What are the naming conventions?
+- How do you share stateful logic?
+-->
+
+(To be filled by the team)
+
+---
+
+## Custom Hook Patterns
+
+<!-- How to create and structure custom hooks -->
+
+(To be filled by the team)
+
+---
+
+## Data Fetching
+
+<!-- How data fetching is handled (React Query, SWR, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Hook naming rules (use*, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Hook-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/index.md

@@ -0,0 +1,39 @@
+# Frontend Development Guidelines
+
+> Best practices for frontend development in this project.
+
+---
+
+## Overview
+
+This directory contains guidelines for frontend development. Fill in each file with your project's specific conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
+| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
+| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
+| [State Management](./state-management.md) | Local state, global state, server state | To fill |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
+| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
+
+---
+
+## How to Fill These Guidelines
+
+For each guideline file:
+
+1. Document your project's **actual conventions** (not ideals)
+2. Include **code examples** from your codebase
+3. List **forbidden patterns** and why
+4. Add **common mistakes** your team has made
+
+The goal is to help AI assistants and new team members understand how YOUR project works.
+
+---
+
+**Language**: All documentation should be written in **English**.

.trellis/spec/frontend/quality-guidelines.md

@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for frontend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

.trellis/spec/frontend/state-management.md

@@ -0,0 +1,51 @@
+# State Management
+
+> How state is managed in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's state management conventions here.
+
+Questions to answer:
+- What state management solution do you use?
+- How is local vs global state decided?
+- How do you handle server state?
+- What are the patterns for derived state?
+-->
+
+(To be filled by the team)
+
+---
+
+## State Categories
+
+<!-- Local state, global state, server state, URL state -->
+
+(To be filled by the team)
+
+---
+
+## When to Use Global State
+
+<!-- Criteria for promoting state to global -->
+
+(To be filled by the team)
+
+---
+
+## Server State
+
+<!-- How server data is cached and synchronized -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- State management mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/frontend/type-safety.md

@@ -0,0 +1,51 @@
+# Type Safety
+
+> Type safety patterns in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's type safety conventions here.
+
+Questions to answer:
+- What type system do you use?
+- How are types organized?
+- What validation library do you use?
+- How do you handle type inference?
+-->
+
+(To be filled by the team)
+
+---
+
+## Type Organization
+
+<!-- Where types are defined, shared types vs local types -->
+
+(To be filled by the team)
+
+---
+
+## Validation
+
+<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Patterns
+
+<!-- Type utilities, generics, type guards -->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- any, type assertions, etc. -->
+
+(To be filled by the team)

.trellis/spec/guides/code-reuse-thinking-guide.md

@@ -0,0 +1,105 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Stop and think before creating new code - does it already exist?
+
+---
+
+## The Problem
+
+**Duplicated code is the #1 source of inconsistency bugs.**
+
+When you copy-paste or rewrite existing logic:
+- Bug fixes don't propagate
+- Behavior diverges over time
+- Codebase becomes harder to understand
+
+---
+
+## Before Writing New Code
+
+### Step 1: Search First
+
+```bash
+# Search for similar function names
+grep -r "functionName" .
+
+# Search for similar logic
+grep -r "keyword" .
+```
+
+### Step 2: Ask These Questions
+
+| Question | If Yes... |
+|----------|-----------|
+| Does a similar function exist? | Use or extend it |
+| Is this pattern used elsewhere? | Follow the existing pattern |
+| Could this be a shared utility? | Create it in the right place |
+| Am I copying code from another file? | **STOP** - extract to shared |
+
+---
+
+## Common Duplication Patterns
+
+### Pattern 1: Copy-Paste Functions
+
+**Bad**: Copying a validation function to another file
+
+**Good**: Extract to shared utilities, import where needed
+
+### Pattern 2: Similar Components
+
+**Bad**: Creating a new component that's 80% similar to existing
+
+**Good**: Extend existing component with props/variants
+
+### Pattern 3: Repeated Constants
+
+**Bad**: Defining the same constant in multiple files
+
+**Good**: Single source of truth, import everywhere
+
+---
+
+## When to Abstract
+
+**Abstract when**:
+- Same code appears 3+ times
+- Logic is complex enough to have bugs
+- Multiple people might need this
+
+**Don't abstract when**:
+- Only used once
+- Trivial one-liner
+- Abstraction would be more complex than duplication
+
+---
+
+## After Batch Modifications
+
+When you've made similar changes to multiple files:
+
+1. **Review**: Did you catch all instances?
+2. **Search**: Run grep to find any missed
+3. **Consider**: Should this be abstracted?
+
+---
+
+## Gotcha: Asymmetric Mechanisms Producing Same Output
+
+**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
+
+**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
+
+**Prevention checklist**:
+- [ ] When migrating directory structures, search for ALL code paths that reference the old structure
+- [ ] If one path is auto-derived (glob/copy) and another is manually listed, the manual one needs updating
+- [ ] Add a regression test that compares outputs from both mechanisms
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure

.trellis/spec/guides/cross-layer-thinking-guide.md

@@ -0,0 +1,94 @@
+# Cross-Layer Thinking Guide
+
+> **Purpose**: Think through data flow across layers before implementing.
+
+---
+
+## The Problem
+
+**Most bugs happen at layer boundaries**, not within layers.
+
+Common cross-layer bugs:
+- API returns format A, frontend expects format B
+- Database stores X, service transforms to Y, but loses data
+- Multiple layers implement the same logic differently
+
+---
+
+## Before Implementing Cross-Layer Features
+
+### Step 1: Map the Data Flow
+
+Draw out how data moves:
+
+```
+Source → Transform → Store → Retrieve → Transform → Display
+```
+
+For each arrow, ask:
+- What format is the data in?
+- What could go wrong?
+- Who is responsible for validation?
+
+### Step 2: Identify Boundaries
+
+| Boundary | Common Issues |
+|----------|---------------|
+| API ↔ Service | Type mismatches, missing fields |
+| Service ↔ Database | Format conversions, null handling |
+| Backend ↔ Frontend | Serialization, date formats |
+| Component ↔ Component | Props shape changes |
+
+### Step 3: Define Contracts
+
+For each boundary:
+- What is the exact input format?
+- What is the exact output format?
+- What errors can occur?
+
+---
+
+## Common Cross-Layer Mistakes
+
+### Mistake 1: Implicit Format Assumptions
+
+**Bad**: Assuming date format without checking
+
+**Good**: Explicit format conversion at boundaries
+
+### Mistake 2: Scattered Validation
+
+**Bad**: Validating the same thing in multiple layers
+
+**Good**: Validate once at the entry point
+
+### Mistake 3: Leaky Abstractions
+
+**Bad**: Component knows about database schema
+
+**Good**: Each layer only knows its neighbors
+
+---
+
+## Checklist for Cross-Layer Features
+
+Before implementation:
+- [ ] Mapped the complete data flow
+- [ ] Identified all layer boundaries
+- [ ] Defined format at each boundary
+- [ ] Decided where validation happens
+
+After implementation:
+- [ ] Tested with edge cases (null, empty, invalid)
+- [ ] Verified error handling at each boundary
+- [ ] Checked data survives round-trip
+
+---
+
+## When to Create Flow Documentation
+
+Create detailed flow docs when:
+- Feature spans 3+ layers
+- Multiple teams are involved
+- Data format is complex
+- Feature has caused bugs before

.trellis/spec/guides/index.md

@@ -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.

.trellis/tasks/00-bootstrap-guidelines/prd.md

@@ -0,0 +1,139 @@
+# Bootstrap Task: Fill Project Development Guidelines
+
+**You (the AI) are running this task. The developer does not read this file.**
+
+The developer just ran `trellis init` on this project for the first time.
+`.trellis/` now exists with empty spec scaffolding, and this task has been
+set as their current task. They'll open their AI tool, run `/trellis:continue`,
+and you'll land here.
+
+**Your job**: help them populate `.trellis/spec/` with the team's real
+coding conventions. Every future AI session — this project's
+`trellis-implement` and `trellis-check` sub-agents — auto-loads spec files
+listed in per-task jsonl manifests. Empty spec = sub-agents write generic
+code. Real spec = sub-agents match the team's actual patterns.
+
+Don't dump instructions. Open with a short greeting, figure out if the repo
+has any existing convention docs (CLAUDE.md, .cursorrules, etc.), and drive
+the rest conversationally.
+
+---
+
+## Status (update the checkboxes as you complete each item)
+
+- [ ] Fill backend guidelines
+- [ ] Fill frontend guidelines
+- [ ] Add code examples
+
+---
+
+## Spec files to populate
+
+
+### Backend guidelines
+
+| File | What to document |
+|------|------------------|
+| `.trellis/spec/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
+| `.trellis/spec/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
+| `.trellis/spec/backend/error-handling.md` | How errors are caught, logged, and returned |
+| `.trellis/spec/backend/logging-guidelines.md` | Log levels, format, what to log |
+| `.trellis/spec/backend/quality-guidelines.md` | Code review standards, testing requirements |
+
+
+### Frontend guidelines
+
+| File | What to document |
+|------|------------------|
+| `.trellis/spec/frontend/directory-structure.md` | Component/page/hook organization |
+| `.trellis/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
+| `.trellis/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
+| `.trellis/spec/frontend/state-management.md` | State library, patterns, what goes where |
+| `.trellis/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
+| `.trellis/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
+
+
+### Thinking guides (already populated)
+
+`.trellis/spec/guides/` contains general thinking guides pre-filled with
+best practices. Customize only if something clearly doesn't fit this project.
+
+---
+
+## How to fill the spec
+
+### Step 1: Import from existing convention files first (preferred)
+
+Search the repo for existing convention docs. If any exist, read them and
+extract the relevant rules into the matching `.trellis/spec/` files —
+usually much faster than documenting from scratch.
+
+| File / Directory | Tool |
+|------|------|
+| `CLAUDE.md` / `CLAUDE.local.md` | Claude Code |
+| `AGENTS.md` | Codex / Claude Code / agent-compatible tools |
+| `.cursorrules` | Cursor |
+| `.cursor/rules/*.mdc` | Cursor (rules directory) |
+| `.windsurfrules` | Windsurf |
+| `.clinerules` | Cline |
+| `.roomodes` | Roo Code |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `.vscode/settings.json` → `github.copilot.chat.codeGeneration.instructions` | VS Code Copilot |
+| `CONVENTIONS.md` / `.aider.conf.yml` | aider |
+| `CONTRIBUTING.md` | General project conventions |
+| `.editorconfig` | Editor formatting rules |
+
+### Step 2: Analyze the codebase for anything not covered by existing docs
+
+Scan real code to discover patterns. Before writing each spec file:
+- Find 2-3 real examples of each pattern in the codebase.
+- Reference real file paths (not hypothetical ones).
+- Document anti-patterns the team clearly avoids.
+
+### Step 3: Document reality, not ideals
+
+**Critical**: write what the code *actually does*, not what it should do.
+Sub-agents match the spec, so aspirational patterns that don't exist in the
+codebase will cause sub-agents to write code that looks out of place.
+
+If the team has known tech debt, document the current state — improvement
+is a separate conversation, not a bootstrap concern.
+
+---
+
+## Quick explainer of the runtime (share when they ask "why do we need spec at all")
+
+- Every AI coding task spawns two sub-agents: `trellis-implement` (writes
+  code) and `trellis-check` (verifies quality).
+- Each task has `implement.jsonl` / `check.jsonl` manifests listing which
+  spec files to load.
+- The platform hook auto-injects those spec files + the task's `prd.md`
+  into every sub-agent prompt, so the sub-agent codes/reviews per team
+  conventions without anyone pasting them manually.
+- Source of truth: `.trellis/spec/`. That's why filling it well now pays
+  off forever.
+
+---
+
+## Completion
+
+When the developer confirms the checklist items above are done with real
+examples (not placeholders), guide them to run:
+
+```bash
+python3 ./.trellis/scripts/task.py finish
+python3 ./.trellis/scripts/task.py archive 00-bootstrap-guidelines
+```
+
+After archive, every new developer who joins this project will get a
+`00-join-<slug>` onboarding task instead of this bootstrap task.
+
+---
+
+## Suggested opening line
+
+"Welcome to Trellis! Your init just set me up to help you fill the project
+spec — a one-time setup so every future AI session follows the team's
+conventions instead of writing generic code. Before we start, do you have
+any existing convention docs (CLAUDE.md, .cursorrules, CONTRIBUTING.md,
+etc.) I can pull from, or should I scan the codebase from scratch?"

.trellis/tasks/00-bootstrap-guidelines/task.json

@@ -0,0 +1,29 @@
+{
+  "id": "00-bootstrap-guidelines",
+  "name": "00-bootstrap-guidelines",
+  "title": "Bootstrap Guidelines",
+  "description": "Fill in project development guidelines for AI agents",
+  "status": "in_progress",
+  "dev_type": "docs",
+  "scope": null,
+  "package": null,
+  "priority": "P1",
+  "creator": "shiyue",
+  "assignee": "shiyue",
+  "createdAt": "2026-04-24",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": null,
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [
+    ".trellis/spec/backend/",
+    ".trellis/spec/frontend/"
+  ],
+  "notes": "First-time setup task created by trellis init (fullstack project)",
+  "meta": {}
+}

.trellis/workflow.md

@@ -0,0 +1,480 @@
+# Development Workflow
+
+---
+
+## Core Principles
+
+1. **Plan before code** — figure out what to do before you start
+2. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory
+3. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't
+4. **Incremental development** — one task at a time
+5. **Capture learnings** — after each task, review and write new knowledge back to spec
+
+---
+
+## Trellis System
+
+### Developer Identity
+
+On first use, initialize your identity:
+
+```bash
+python3 ./.trellis/scripts/init_developer.py <your-name>
+```
+
+Creates `.trellis/.developer` (gitignored) + `.trellis/workspace/<your-name>/`.
+
+### Spec System
+
+`.trellis/spec/` holds coding guidelines organized by package and layer.
+
+- `.trellis/spec/<package>/<layer>/index.md` — entry point with **Pre-Development Checklist** + **Quality Check**. Actual guidelines live in the `.md` files it points to.
+- `.trellis/spec/guides/index.md` — cross-package thinking guides.
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages   # list packages / layers
+```
+
+**When to update spec**: new pattern/convention found · bug-fix prevention to codify · new technical decision.
+
+### Task System
+
+Every task has its own directory under `.trellis/tasks/{MM-DD-name}/` holding `prd.md`, `implement.jsonl`, `check.jsonl`, `task.json`, optional `research/`, `info.md`.
+
+```bash
+# Task lifecycle
+python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>] [--parent <dir>]
+python3 ./.trellis/scripts/task.py start <name>          # set as current (writes .current-task, triggers after_start hooks)
+python3 ./.trellis/scripts/task.py finish                # clear current task (triggers after_finish hooks)
+python3 ./.trellis/scripts/task.py archive <name>        # move to archive/{year-month}/
+python3 ./.trellis/scripts/task.py list [--mine] [--status <s>]
+python3 ./.trellis/scripts/task.py list-archive
+
+# Code-spec context (injected into implement/check agents via JSONL).
+# `implement.jsonl` / `check.jsonl` are seeded on `task create` for sub-agent-capable
+# platforms; the AI curates real spec + research entries during Phase 1.3.
+python3 ./.trellis/scripts/task.py add-context <name> <action> <file> <reason>
+python3 ./.trellis/scripts/task.py list-context <name> [action]
+python3 ./.trellis/scripts/task.py validate <name>
+
+# Task metadata
+python3 ./.trellis/scripts/task.py set-branch <name> <branch>
+python3 ./.trellis/scripts/task.py set-base-branch <name> <branch>    # PR target
+python3 ./.trellis/scripts/task.py set-scope <name> <scope>
+
+# Hierarchy (parent/child)
+python3 ./.trellis/scripts/task.py add-subtask <parent> <child>
+python3 ./.trellis/scripts/task.py remove-subtask <parent> <child>
+
+# PR creation
+python3 ./.trellis/scripts/task.py create-pr [name] [--dry-run]
+```
+
+> Run `python3 ./.trellis/scripts/task.py --help` to see the authoritative, up-to-date list.
+
+**Current-task mechanism**: `task.py start` writes the task path into `.trellis/.current-task`. Hook-capable platforms auto-inject this at session start, so the AI knows what you're working on without being told.
+
+### Workspace System
+
+Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`.
+
+- `journal-N.md` — session log. **Max 2000 lines per file**; a new `journal-(N+1).md` is auto-created when exceeded.
+- `index.md` — personal index (total sessions, last active).
+
+```bash
+python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary"
+```
+
+### Context Script
+
+```bash
+python3 ./.trellis/scripts/get_context.py                            # full session context
+python3 ./.trellis/scripts/get_context.py --mode packages            # available packages + spec layers
+python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed guide for a workflow step
+```
+
+---
+
+## Phase Index
+
+```
+Phase 1: Plan    → figure out what to do (brainstorm + research → prd.md)
+Phase 2: Execute → write code and pass quality checks
+Phase 3: Finish  → distill lessons + wrap-up
+```
+
+### Phase 1: Plan
+- 1.0 Create task `[required · once]`
+- 1.1 Requirement exploration `[required · repeatable]`
+- 1.2 Research `[optional · repeatable]`
+- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid
+- 1.4 Completion criteria
+
+### Phase 2: Execute
+- 2.1 Implement `[required · repeatable]`
+- 2.2 Quality check `[required · repeatable]`
+- 2.3 Rollback `[on demand]`
+
+### Phase 3: Finish
+- 3.1 Quality verification `[required · repeatable]`
+- 3.2 Debug retrospective `[on demand]`
+- 3.3 Spec update `[required · once]`
+- 3.4 Wrap-up reminder
+
+### Rules
+
+1. Identify which Phase you're in, then continue from the next step there
+2. Run steps in order inside each Phase; `[required]` steps can't be skipped
+3. Phases can roll back (e.g., Execute reveals a prd defect → return to Plan to fix, then re-enter Execute)
+4. Steps tagged `[once]` are skipped if already done; don't re-run
+
+### Skill Routing
+
+When a user request matches one of these intents, load the corresponding skill (or dispatch the corresponding sub-agent) first — do not skip skills.
+
+[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+| User intent | Route |
+|---|---|
+| Wants a new feature / requirement unclear | `trellis-brainstorm` |
+| About to write code / start implementing | Dispatch the `trellis-implement` sub-agent per Phase 2.1 |
+| Finished writing / want to verify | Dispatch the `trellis-check` sub-agent per Phase 2.2 |
+| Stuck / fixed same bug several times | `trellis-break-loop` |
+| Spec needs update | `trellis-update-spec` |
+
+**Why `trellis-before-dev` is NOT in this table:** you are not the one writing code — the `trellis-implement` sub-agent is. Sub-agent platforms get spec context via `implement.jsonl` injection / prelude, not via the main thread loading `trellis-before-dev`.
+
+[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+[Kilo, Antigravity, Windsurf]
+
+| User intent | Skill |
+|---|---|
+| Wants a new feature / requirement unclear | `trellis-brainstorm` |
+| About to write code / start implementing | `trellis-before-dev` (then implement directly in the main session) |
+| Finished writing / want to verify | `trellis-check` |
+| Stuck / fixed same bug several times | `trellis-break-loop` |
+| Spec needs update | `trellis-update-spec` |
+
+[/Kilo, Antigravity, Windsurf]
+
+### DO NOT skip skills
+
+[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+| What you're thinking | Why it's wrong |
+|---|---|
+| "This is simple, I'll just code it in the main thread" | Dispatching `trellis-implement` is the cheap path; skipping it tempts you to write code in the main thread and lose spec context — sub-agents get `implement.jsonl` injected, you don't |
+| "I already thought it through in plan mode" | Plan-mode output lives in memory — sub-agents can't see it; must be persisted to prd.md |
+| "I already know the spec" | The spec may have been updated since you last read it; the sub-agent gets the fresh copy, you may not |
+| "Code first, check later" | `trellis-check` surfaces issues you won't notice yourself; earlier is cheaper |
+
+[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+[Kilo, Antigravity, Windsurf]
+
+| What you're thinking | Why it's wrong |
+|---|---|
+| "This is simple, just code it" | Simple tasks often grow complex; `trellis-before-dev` takes under a minute and loads the spec context you'll need |
+| "I already thought it through in plan mode" | Plan-mode output lives in memory — must be persisted to prd.md before code |
+| "I already know the spec" | The spec may have been updated since you last read it; read again |
+| "Code first, check later" | `trellis-check` surfaces issues you won't notice yourself; earlier is cheaper |
+
+[/Kilo, Antigravity, Windsurf]
+
+### Loading Step Detail
+
+At each step, run this to fetch detailed guidance:
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode phase --step <step>
+# e.g. python3 ./.trellis/scripts/get_context.py --mode phase --step 1.1
+```
+
+---
+
+## Phase 1: Plan
+
+Goal: figure out what to build, produce a clear requirements doc and the context needed to implement it.
+
+#### 1.0 Create task `[required · once]`
+
+Create the task directory and set it as current:
+
+```bash
+python3 ./.trellis/scripts/task.py create "<task title>" --slug <name>
+python3 ./.trellis/scripts/task.py start <task-dir>
+```
+
+Skip when: `.trellis/.current-task` already points to a task.
+
+#### 1.1 Requirement exploration `[required · repeatable]`
+
+Load the `trellis-brainstorm` skill and explore requirements interactively with the user per the skill's guidance.
+
+The brainstorm skill will guide you to:
+- Ask one question at a time
+- Prefer researching over asking the user
+- Prefer offering options over open-ended questions
+- Update `prd.md` immediately after each user answer
+
+Return to this step whenever requirements change and revise `prd.md`.
+
+#### 1.2 Research `[optional · repeatable]`
+
+Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
+
+[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+Spawn the research sub-agent:
+
+- **Agent type**: `trellis-research`
+- **Task description**: Research <specific question>
+- **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
+
+[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+[Kilo, Antigravity, Windsurf]
+
+Do the research in the main session directly and write findings into `{TASK_DIR}/research/`.
+
+[/Kilo, Antigravity, Windsurf]
+
+**Research artifact conventions**:
+- One file per research topic (e.g. `research/auth-library-comparison.md`)
+- Record third-party library usage examples, API references, version constraints in files
+- Note relevant spec file paths you discovered for later reference
+
+Brainstorm and research can interleave freely — pause to research a technical question, then return to talk with the user.
+
+**Key principle**: Research output must be written to files, not left only in the chat. Conversations get compacted; files don't.
+
+#### 1.3 Configure context `[required · once]`
+
+[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
+
+**Location**: `{TASK_DIR}/implement.jsonl` and `{TASK_DIR}/check.jsonl` (already exist).
+
+**Format**: one JSON object per line — `{"file": "<path>", "reason": "<why>"}`. Paths are repo-root relative.
+
+**What to put in**:
+- **Spec files** — `.trellis/spec/<package>/<layer>/index.md` and any specific guideline files (`error-handling.md`, `conventions.md`, etc.) relevant to this task
+- **Research files** — `{TASK_DIR}/research/*.md` that the sub-agent will need to consult
+
+**What NOT to put in**:
+- Code files (`src/**`, `packages/**/*.ts`, etc.) — those are read by the sub-agent during implementation, not pre-registered here
+- Files you're about to modify — same reason
+
+**Split between the two files**:
+- `implement.jsonl` → specs + research the implement sub-agent needs to write code correctly
+- `check.jsonl` → specs for the check sub-agent (quality guidelines, check conventions, same research if needed)
+
+**How to discover relevant specs**:
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+Lists every package + its spec layers with paths. Pick the entries that match this task's domain.
+
+**How to append entries**:
+
+Either edit the jsonl file directly in your editor, or use:
+
+```bash
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
+```
+
+Delete the seed `_example` line once real entries exist (optional — it's skipped automatically by consumers).
+
+Skip when: `implement.jsonl` has agent-curated entries (the seed row alone doesn't count).
+
+[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+[Kilo, Antigravity, Windsurf]
+
+Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
+
+[/Kilo, Antigravity, Windsurf]
+
+#### 1.4 Completion criteria
+
+| Condition | Required |
+|------|:---:|
+| `prd.md` exists | ✅ |
+| User confirms requirements | ✅ |
+| `research/` has artifacts (complex tasks) | recommended |
+| `info.md` technical design (complex tasks) | optional |
+
+[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+| `implement.jsonl` has agent-curated entries (not just the seed row) | ✅ |
+
+[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+---
+
+## Phase 2: Execute
+
+Goal: turn the prd into code that passes quality checks.
+
+#### 2.1 Implement `[required · repeatable]`
+
+[Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+Spawn the implement sub-agent:
+
+- **Agent type**: `trellis-implement`
+- **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
+
+The platform hook/plugin auto-handles:
+- Reads `implement.jsonl` and injects the referenced spec files into the agent prompt
+- Injects prd.md content
+
+[/Claude Code, Cursor, OpenCode, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+[Codex]
+
+Spawn the implement sub-agent:
+
+- **Agent type**: `trellis-implement`
+- **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
+
+The Codex sub-agent definition auto-handles the context load requirement:
+- Reads `.trellis/.current-task`, `prd.md`, and `info.md` if present
+- Reads `implement.jsonl` and requires the agent to load each referenced spec file before coding
+
+[/Codex]
+
+[Kiro]
+
+Spawn the implement sub-agent:
+
+- **Agent type**: `trellis-implement`
+- **Task description**: Implement the requirements per prd.md, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
+
+The platform prelude auto-handles the context load requirement:
+- Reads `implement.jsonl` and injects the referenced spec files into the agent prompt
+- Injects prd.md content
+
+[/Kiro]
+
+[Kilo, Antigravity, Windsurf]
+
+1. Load the `trellis-before-dev` skill to read project guidelines
+2. Read `{TASK_DIR}/prd.md` for requirements
+3. Consult materials under `{TASK_DIR}/research/`
+4. Implement the code per requirements
+5. Run project lint and type-check
+
+[/Kilo, Antigravity, Windsurf]
+
+#### 2.2 Quality check `[required · repeatable]`
+
+[Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+Spawn the check sub-agent:
+
+- **Agent type**: `trellis-check`
+- **Task description**: Review all code changes against spec and prd; fix any findings directly; ensure lint and type-check pass
+
+The check agent's job:
+- Review code changes against specs
+- Auto-fix issues it finds
+- Run lint and typecheck to verify
+
+[/Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid]
+
+[Kilo, Antigravity, Windsurf]
+
+Load the `trellis-check` skill and verify the code per its guidance:
+- Spec compliance
+- lint / type-check / tests
+- Cross-layer consistency (when changes span layers)
+
+If issues are found → fix → re-check, until green.
+
+[/Kilo, Antigravity, Windsurf]
+
+#### 2.3 Rollback `[on demand]`
+
+- `check` reveals a prd defect → return to Phase 1, fix `prd.md`, then redo 2.1
+- Implementation went wrong → revert code, redo 2.1
+- Need more research → research (same as Phase 1.2), write findings into `research/`
+
+---
+
+## Phase 3: Finish
+
+Goal: ensure code quality, capture lessons, record the work.
+
+#### 3.1 Quality verification `[required · repeatable]`
+
+Load the `trellis-check` skill and do a final verification:
+- Spec compliance
+- lint / type-check / tests
+- Cross-layer consistency (when changes span layers)
+
+If issues are found → fix → re-check, until green.
+
+#### 3.2 Debug retrospective `[on demand]`
+
+If this task involved repeated debugging (the same issue was fixed multiple times), load the `trellis-break-loop` skill to:
+- Classify the root cause
+- Explain why earlier fixes failed
+- Propose prevention
+
+The goal is to capture debugging lessons so the same class of issue doesn't recur.
+
+#### 3.3 Spec update `[required · once]`
+
+Load the `trellis-update-spec` skill and review whether this task produced new knowledge worth recording:
+- Newly discovered patterns or conventions
+- Pitfalls you hit
+- New technical decisions
+
+Update the docs under `.trellis/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment.
+
+#### 3.4 Wrap-up reminder
+
+After the above, remind the user they can run `/finish-work` to wrap up (archive the task, record the session).
+
+---
+
+## Workflow State Breadcrumbs
+
+<!-- Injected per-turn by UserPromptSubmit hook (inject-workflow-state.py).
+     Edit the text inside each [workflow-state:STATUS]...[/workflow-state:STATUS]
+     block to customize per-task-status flow reminders. Users who fork the
+     Trellis workflow only need to edit this file, not the hook script.
+
+     Tag STATUS matches task.json.status. Default statuses: planning /
+     in_progress / completed. Add custom status blocks as needed (hyphens
+     and underscores allowed). Hook falls back to built-in defaults when
+     a status has no tag block. -->
+
+[workflow-state:no_task]
+No active task.
+Trigger words in the user message that REQUIRE creating a task (non-negotiable, do NOT self-exempt): 重构 / 抽成 / 独立 / 分发 / 拆出来 / 搞一个 / 做成 / 接入 / 集成 / refactor / rewrite / extract / productize / publish / build X / design Y.
+Task is NOT required ONLY if ALL three hold: (a) zero file writes this turn, (b) answer fits in one reply with no multi-round plan, (c) no research beyond reading 1-2 repo files.
+When in doubt: create task. Over-tasking is cheap; under-tasking leaks plans and research into main context.
+Flow: load `trellis-brainstorm` skill → it creates the task via `python3 ./.trellis/scripts/task.py create` and drives requirements Q&A. For research-heavy work (tool comparison, docs, cross-platform survey), spawn `trellis-research` sub-agents via Task tool — NEVER do 3+ inline WebFetch/WebSearch/`gh api` calls in the main conversation.
+[/workflow-state:no_task]
+
+[workflow-state:planning]
+Complete prd.md via trellis-brainstorm skill; then run task.py start.
+Research belongs in `{task_dir}/research/*.md`, written by `trellis-research` sub-agents. Do NOT inline WebFetch/WebSearch in main session — PRD only links to research files.
+[/workflow-state:planning]
+
+[workflow-state:in_progress]
+Flow: trellis-implement → trellis-check → trellis-update-spec → finish
+Next required action: inspect conversation history + git status, then execute the next uncompleted step in that sequence.
+For agent-capable platforms, do NOT edit code in the main session; dispatch `trellis-implement` for implementation and dispatch `trellis-check` before reporting completion.
+[/workflow-state:in_progress]
+
+[workflow-state:completed]
+User commits changes; then run task.py archive.
+[/workflow-state:completed]

.trellis/workspace/index.md

@@ -0,0 +1,125 @@
+# 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
+- Branch: Which branch the work was done on
+- 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}
+**Branch**: `{branch-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**.

.trellis/workspace/shiyue/index.md

@@ -0,0 +1,40 @@
+# Workspace Index - shiyue
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 0
+- **Last Active**: -
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~0 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits | Branch |
+|---|------|-------|---------|--------|
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to journal files
+- New journal file created when current exceeds 2000 lines
+- Use `add_session.py` to record sessions

.trellis/workspace/shiyue/journal-1.md

@@ -0,0 +1,6 @@
+# Journal - shiyue (Part 1)
+
+> AI development session journal
+> Started: 2026-04-24
+
+---

AGENTS.md

@@ -0,0 +1,22 @@
+<!-- TRELLIS:START -->
+# Trellis Instructions
+
+These instructions are for AI assistants working in this project.
+
+Use the `/trellis:start` command when starting a new session to:
+- Initialize your developer identity
+- Understand current project context
+- Read relevant guidelines
+
+Use `@/.trellis/` to learn:
+- Development workflow (`workflow.md`)
+- Project structure guidelines (`spec/`)
+- Developer workspace (`workspace/`)
+
+If you're using Codex, project-scoped helpers may also live in:
+- `.agents/skills/` for reusable Trellis skills
+- `.codex/agents/` for optional custom subagents
+
+Keep this managed block so 'trellis update' can refresh the instructions.
+
+<!-- TRELLIS:END -->

README.md

@@ -55,11 +55,10 @@ https://github.com/ZgDaniel/cc-web 给我装！
 ```bash
 git clone https://github.com/ZgDaniel/cc-web.git
 cd cc-web
-cp .env.example .env    # 可选，不设密码则首次启动自动生成
 ./start.sh
 ```
 
-`start.sh` 会检查 Node.js/npm 环境，自动安装 PM2（如未安装），安装项目依赖，并以 `ccweb` 为默认应用名启动或重启服务。
+`start.sh` 会检查 Node.js/npm 环境，自动创建 `.env`（如不存在），引导输入初始登录密码，自动安装 PM2（如未安装），安装项目依赖，并以 `ccweb` 为默认应用名启动或重启服务。
 
 如只想前台临时运行，也可以手动执行：
 
@@ -202,13 +201,16 @@ tail -f logs/process.log | jq .
 ```bash
 git clone https://github.com/ZgDaniel/cc-web.git
 cd cc-web
-cp .env.example .env    # 可选，不设密码则首次启动自动生成
 ./start.sh
 ```
 
 脚本默认执行以下动作：
 
 - 检查 Node.js >= 18 与 npm
+- 自动创建 `.env`（如不存在），并补齐默认 `PORT=8002`
+- 首次部署时引导输入 `CC_WEB_PASSWORD`，写入 `.env` 后由服务迁移到 `config/auth.json`
+- 如果已存在 `config/auth.json`，跳过初始密码设置，避免覆盖已修改的密码
+- 检查 Claude / Codex CLI 是否可用；未安装时仅提示，不阻塞 Web 服务启动
 - 检查 PM2，未安装时自动执行 `npm install -g pm2`
 - 使用 `npm ci` 安装项目依赖（无 `package-lock.json` 时退回 `npm install`）
 - 使用 PM2 启动或重启 `server.js`，默认应用名为 `ccweb`

config/banned_ips.json

@@ -0,0 +1 @@
+[]

lib/agent-runtime.js

@@ -217,7 +217,26 @@ function createAgentRuntime(deps) {
     return JSON.stringify(truncateObj(item, 1200));
   }
 
-  function ensureCodexToolCall(entry, item) {
+  function sendRuntime(entry, sessionId, payload) {
+    wsSend(entry.ws, { ...payload, sessionId });
+  }
+
+  function appendCodexAgentText(entry, text) {
+    const nextText = String(text || '');
+    if (!nextText) return '';
+
+    const currentText = entry.fullText || '';
+    const hasExistingText = /\S/.test(currentText);
+    const hasParagraphBoundary = /\n\s*\n\s*$/.test(currentText) || /^\s*\n\s*\n/.test(nextText);
+    const separator = hasExistingText && !hasParagraphBoundary
+      ? (/\n\s*$/.test(currentText) ? '\n' : '\n\n')
+      : '';
+    const chunk = separator + nextText;
+    entry.fullText += chunk;
+    return chunk;
+  }
+
+  function ensureCodexToolCall(entry, item, sessionId) {
     let tc = entry.toolCalls.find((t) => t.id === item.id);
     if (tc) {
       tc.name = codexToolName(item);
@@ -235,7 +254,7 @@ function createAgentRuntime(deps) {
       done: false,
     };
     entry.toolCalls.push(tc);
-    wsSend(entry.ws, {
+    sendRuntime(entry, sessionId, {
       type: 'tool_start',
       name: tc.name,
       toolUseId: item.id,
@@ -267,12 +286,12 @@ function createAgentRuntime(deps) {
         for (const block of content) {
           if (block.type === 'text' && block.text) {
             entry.fullText += block.text;
-            wsSend(entry.ws, { type: 'text_delta', text: block.text });
+            sendRuntime(entry, sessionId, { type: 'text_delta', text: block.text });
           } else if (block.type === 'tool_use') {
             const toolInput = sanitizeToolInput(block.name, block.input);
             const tc = { name: block.name, id: block.id, input: toolInput, done: false };
             entry.toolCalls.push(tc);
-            wsSend(entry.ws, { type: 'tool_start', name: block.name, toolUseId: block.id, input: tc.input });
+            sendRuntime(entry, sessionId, { type: 'tool_start', name: block.name, toolUseId: block.id, input: tc.input });
           } else if (block.type === 'tool_result') {
             const resultText = typeof block.content === 'string'
               ? block.content
@@ -284,7 +303,7 @@ function createAgentRuntime(deps) {
               tc.done = true;
               tc.result = resultText.slice(0, 2000);
             }
-            wsSend(entry.ws, { type: 'tool_end', toolUseId: block.tool_use_id, result: resultText.slice(0, 2000) });
+            sendRuntime(entry, sessionId, { type: 'tool_end', toolUseId: block.tool_use_id, result: resultText.slice(0, 2000) });
           }
         }
 
@@ -307,7 +326,7 @@ function createAgentRuntime(deps) {
         }
         entry.lastCost = event.total_cost_usd || null;
         if (entry.ws && event.total_cost_usd !== undefined) {
-          wsSend(entry.ws, { type: 'cost', costUsd: session?.totalCost || 0 });
+          sendRuntime(entry, sessionId, { type: 'cost', costUsd: session?.totalCost || 0 });
         }
         break;
       }
@@ -331,19 +350,19 @@ function createAgentRuntime(deps) {
       case 'item.started': {
         const item = event.item;
         if (!item || !item.id || item.type === 'agent_message') break;
-        ensureCodexToolCall(entry, item);
+        ensureCodexToolCall(entry, item, sessionId);
         break;
       }
 
       case 'item.updated': {
         const item = event.item;
         if (!item || !item.id || item.type === 'agent_message') break;
-        const tc = ensureCodexToolCall(entry, item);
+        const tc = ensureCodexToolCall(entry, item, sessionId);
         const resultText = codexToolResult(item).slice(0, 2000);
         tc.done = false;
         tc.result = resultText;
 
-        wsSend(entry.ws, {
+        sendRuntime(entry, sessionId, {
           type: 'tool_update',
           toolUseId: item.id,
           name: tc.name,
@@ -369,21 +388,21 @@ function createAgentRuntime(deps) {
               if (!entry.contentBlocks) entry.contentBlocks = [];
               entry.contentBlocks.push(...parsedContent);
               const textOnly = parsedContent.filter(b => b.type === 'text').map(b => b.text || '').join('');
-              entry.fullText += textOnly;
+              appendCodexAgentText(entry, textOnly);
-              wsSend(entry.ws, { type: 'content_blocks', blocks: parsedContent });
+              sendRuntime(entry, sessionId, { type: 'content_blocks', blocks: parsedContent });
             } else {
-              entry.fullText += item.text;
+              const textChunk = appendCodexAgentText(entry, item.text);
-              wsSend(entry.ws, { type: 'text_delta', text: item.text });
+              sendRuntime(entry, sessionId, { type: 'text_delta', text: textChunk });
             }
           }
           break;
         }
-        const tc = ensureCodexToolCall(entry, item);
+        const tc = ensureCodexToolCall(entry, item, sessionId);
         const resultText = codexToolResult(item).slice(0, 2000);
         tc.done = true;
         tc.result = resultText;
 
-        wsSend(entry.ws, {
+        sendRuntime(entry, sessionId, {
           type: 'tool_end',
           toolUseId: item.id,
           result: resultText,
@@ -404,7 +423,7 @@ function createAgentRuntime(deps) {
             outputTokens: (session.totalUsage?.outputTokens || 0) + (usage.output_tokens || 0),
           };
           saveSession(session);
-          wsSend(entry.ws, { type: 'usage', totalUsage: session.totalUsage });
+          sendRuntime(entry, sessionId, { type: 'usage', totalUsage: session.totalUsage });
         }
         break;
       }
@@ -418,7 +437,7 @@ function createAgentRuntime(deps) {
       case 'error':
         if (event.message) {
           if (/^Reconnecting\.\.\./.test(event.message)) {
-            wsSend(entry.ws, { type: 'system_message', message: event.message });
+            sendRuntime(entry, sessionId, { type: 'system_message', message: event.message });
           } else {
             entry.lastError = event.message;
           }

public/app.js

@@ -83,6 +83,7 @@
   let reconnectTimer = null;
   let pendingText = '';
   let renderTimer = null;
+  let generatingSessionId = null;
   let activeToolCalls = new Map();
   let activeTodoCallTargets = new Map();
   let toolDomSeq = 0;
@@ -109,6 +110,9 @@
   let pendingNewSessionRequest = null;
   let skipDeleteConfirm = localStorage.getItem('cc-web-skip-delete-confirm') === '1';
   let pendingInitialSessionLoad = false;
+  let noteMode = false;
+  let noteDraftSeq = 0;
+  const pendingNotesByTarget = new Map();
 
   // --- DOM ---
   const $ = (sel) => document.querySelector(sel);
@@ -142,10 +146,12 @@
   const messagesDiv = $('#messages');
   const msgInput = $('#msg-input');
   const inputWrapper = msgInput.closest('.input-wrapper');
+  const noteModeBtn = $('#note-mode-btn');
   const sendBtn = $('#send-btn');
   const abortBtn = $('#abort-btn');
   const cmdMenu = $('#cmd-menu');
   const modeSelect = $('#mode-select');
+  const defaultMsgInputPlaceholder = msgInput.getAttribute('placeholder') || '输入消息… 输入 / 查看指令';
 
   // --- Viewport height fix for mobile browsers ---
   function setVH() {
@@ -164,6 +170,238 @@
     return AGENT_LABELS[agent] ? agent : DEFAULT_AGENT;
   }
 
+  function getDraftNoteKey(agent = currentAgent) {
+    return `draft:${normalizeAgent(agent)}`;
+  }
+
+  function getCurrentNoteKey(agent = currentAgent) {
+    return currentSessionId || getDraftNoteKey(agent);
+  }
+
+  function getNotesForKey(key, create = true) {
+    if (!key) return [];
+    if (!pendingNotesByTarget.has(key)) {
+      if (!create) return [];
+      pendingNotesByTarget.set(key, []);
+    }
+    return pendingNotesByTarget.get(key);
+  }
+
+  function getCurrentNotes(create = true) {
+    return getNotesForKey(getCurrentNoteKey(), create);
+  }
+
+  function cleanupNoteKey(key) {
+    const notes = pendingNotesByTarget.get(key);
+    if (!notes || notes.length === 0) pendingNotesByTarget.delete(key);
+  }
+
+  function migratePendingNotesToSession(sessionId, agent = currentAgent) {
+    if (!sessionId) return;
+    const draftKey = getDraftNoteKey(agent);
+    const draftNotes = pendingNotesByTarget.get(draftKey);
+    if (!draftNotes || draftNotes.length === 0) return;
+    const sessionNotes = getNotesForKey(sessionId, true);
+    sessionNotes.push(...draftNotes);
+    pendingNotesByTarget.delete(draftKey);
+  }
+
+  function updateNoteModeUI() {
+    const active = !!noteMode;
+    if (noteModeBtn) {
+      noteModeBtn.classList.toggle('active', active);
+      noteModeBtn.setAttribute('aria-pressed', active ? 'true' : 'false');
+      noteModeBtn.title = active ? '关闭笔记模式' : '笔记模式';
+      noteModeBtn.setAttribute('aria-label', active ? '关闭笔记模式' : '笔记模式');
+    }
+    if (inputWrapper) inputWrapper.classList.toggle('note-mode-active', active);
+    if (sendBtn) {
+      sendBtn.classList.toggle('note-send', active);
+      sendBtn.title = active ? '记录笔记' : '发送';
+      sendBtn.hidden = isGenerating ? !active : false;
+    }
+    if (msgInput) {
+      msgInput.placeholder = active ? '记录笔记，稍后从气泡发送…' : defaultMsgInputPlaceholder;
+    }
+    if (active) hideCmdMenu();
+  }
+
+  function createNoteActionButton(action, label, title = label) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = `note-action ${action}`;
+    button.textContent = label;
+    button.title = title;
+    button.dataset.noteAction = action;
+    return button;
+  }
+
+  function createPendingNoteElement(note) {
+    const div = document.createElement('div');
+    div.className = 'msg note';
+    div.dataset.noteId = note.id;
+
+    const avatar = document.createElement('div');
+    avatar.className = 'msg-avatar note-avatar';
+    avatar.textContent = 'N';
+
+    const bubble = document.createElement('div');
+    bubble.className = 'msg-bubble note-bubble';
+
+    const meta = document.createElement('div');
+    meta.className = 'note-meta';
+    meta.textContent = '笔记 · 待发送';
+
+    const text = document.createElement('div');
+    text.className = 'note-text';
+    text.textContent = note.text;
+
+    const actions = document.createElement('div');
+    actions.className = 'note-actions';
+    const editBtn = createNoteActionButton('edit', '修改');
+    const deleteBtn = createNoteActionButton('delete', '删除');
+    const sendNoteBtn = createNoteActionButton('send', '发送', '发送这条笔记');
+    editBtn.addEventListener('click', () => beginEditPendingNote(note.id));
+    deleteBtn.addEventListener('click', () => removePendingNote(note.id));
+    sendNoteBtn.addEventListener('click', () => sendPendingNote(note.id));
+    actions.append(editBtn, deleteBtn, sendNoteBtn);
+
+    bubble.append(meta, text, actions);
+    div.append(avatar, bubble);
+    return div;
+  }
+
+  function renderPendingNotes(options = {}) {
+    messagesDiv.querySelectorAll('.msg.note').forEach((node) => node.remove());
+    const notes = getCurrentNotes(false);
+    if (!notes || notes.length === 0) {
+      updateScrollbar();
+      return;
+    }
+
+    const welcome = messagesDiv.querySelector('.welcome-msg');
+    if (welcome) welcome.remove();
+
+    const frag = document.createDocumentFragment();
+    notes.forEach((note) => frag.appendChild(createPendingNoteElement(note)));
+    messagesDiv.appendChild(frag);
+    if (options.scroll !== false) {
+      scrollToBottom();
+    } else {
+      updateScrollbar();
+    }
+  }
+
+  function findPendingNote(noteId) {
+    const key = getCurrentNoteKey();
+    const notes = getNotesForKey(key, false);
+    const index = notes.findIndex((note) => note.id === noteId);
+    if (index === -1) return null;
+    return { key, notes, index, note: notes[index] };
+  }
+
+  function dropPendingNote(noteId) {
+    const found = findPendingNote(noteId);
+    if (!found) return null;
+    const [note] = found.notes.splice(found.index, 1);
+    cleanupNoteKey(found.key);
+    return note;
+  }
+
+  function addPendingNoteFromInput(text) {
+    const content = String(text || '').trim();
+    if (!content) return false;
+    const note = {
+      id: `note-${Date.now().toString(36)}-${++noteDraftSeq}`,
+      text: content,
+      createdAt: Date.now(),
+    };
+    getCurrentNotes(true).push(note);
+    renderPendingNotes();
+    return true;
+  }
+
+  function removePendingNote(noteId) {
+    if (!dropPendingNote(noteId)) return;
+    renderPendingNotes({ scroll: false });
+  }
+
+  function resizeNoteEditor(editor) {
+    editor.style.height = 'auto';
+    editor.style.height = Math.min(editor.scrollHeight, 180) + 'px';
+  }
+
+  function beginEditPendingNote(noteId) {
+    const found = findPendingNote(noteId);
+    if (!found) return;
+    const noteEl = messagesDiv.querySelector(`.msg.note[data-note-id="${noteId}"]`);
+    const bubble = noteEl?.querySelector('.note-bubble');
+    if (!bubble) return;
+
+    bubble.classList.add('editing');
+    bubble.innerHTML = '';
+
+    const meta = document.createElement('div');
+    meta.className = 'note-meta';
+    meta.textContent = '修改笔记';
+
+    const editor = document.createElement('textarea');
+    editor.className = 'note-edit-input';
+    editor.value = found.note.text;
+    editor.rows = 3;
+
+    const actions = document.createElement('div');
+    actions.className = 'note-actions';
+    const saveBtn = createNoteActionButton('save', '保存');
+    const cancelBtn = createNoteActionButton('cancel', '取消');
+
+    const save = () => {
+      const next = editor.value.trim();
+      if (!next) {
+        appendError('笔记内容不能为空。');
+        editor.focus();
+        return;
+      }
+      found.note.text = next;
+      renderPendingNotes();
+    };
+
+    saveBtn.addEventListener('click', save);
+    cancelBtn.addEventListener('click', () => renderPendingNotes({ scroll: false }));
+    editor.addEventListener('input', () => resizeNoteEditor(editor));
+    editor.addEventListener('keydown', (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+        e.preventDefault();
+        save();
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        renderPendingNotes({ scroll: false });
+      }
+    });
+
+    actions.append(saveBtn, cancelBtn);
+    bubble.append(meta, editor, actions);
+    requestAnimationFrame(() => {
+      resizeNoteEditor(editor);
+      editor.focus();
+      editor.select();
+    });
+  }
+
+  function sendPendingNote(noteId) {
+    if (isGenerating || isBlockingSessionLoad()) {
+      appendError('当前回复还在生成，稍后再发送笔记。');
+      return;
+    }
+    const note = dropPendingNote(noteId);
+    if (!note) return;
+    const text = String(note.text || '').trim();
+    renderPendingNotes({ scroll: false });
+    if (!text) return;
+    submitUserMessage(text);
+  }
+
   function normalizeTheme(theme) {
     return THEME_OPTIONS.some((item) => item.value === theme) ? theme : 'washi';
   }
@@ -1182,12 +1420,40 @@
     if (cached?.promise) return cached.promise;
 
     const promise = (async () => {
+      const fetchAttachment = async () => {
         await ensureAuthenticatedWs();
         if (!authToken) {
           throw new Error('登录状态已失效，请刷新页面后重新登录再预览图片。');
         }
-      const url = `/api/attachments/${encodeURIComponent(id)}?token=${encodeURIComponent(authToken)}`;
+        return fetch(`/api/attachments/${encodeURIComponent(id)}`, {
-      attachmentPreviewCache.set(id, { url, objectUrl: false });
+          cache: 'no-store',
+          headers: {
+            Authorization: `Bearer ${authToken}`,
+          },
+        });
+      };
+
+      let response = await fetchAttachment();
+      if (response.status === 401 && localStorage.getItem('cc-web-pw')) {
+        authToken = null;
+        localStorage.removeItem('cc-web-token');
+        response = await fetchAttachment();
+      }
+      if (response.status === 401) {
+        throw new Error('登录状态已失效，请刷新页面后重新登录再预览图片。');
+      }
+      if (response.status === 404) {
+        throw new Error('图片不存在或已过期');
+      }
+      if (!response.ok) {
+        throw new Error('图片预览失败');
+      }
+      const blob = await response.blob();
+      if (!blob || blob.size === 0) {
+        throw new Error('图片预览失败');
+      }
+      const url = URL.createObjectURL(blob);
+      attachmentPreviewCache.set(id, { url, objectUrl: true });
       return url;
     })().catch((err) => {
       attachmentPreviewCache.delete(id);
@@ -1296,18 +1562,20 @@
         getAttachmentPreviewUrl(attachment)
           .then((url) => {
             if (!node.isConnected) return;
-            imgEl.src = url;
             imgEl.onload = () => {
               if (!node.isConnected) return;
               imgEl.hidden = false;
               placeholderEl.hidden = true;
+              node.classList.remove('is-error');
               node.classList.add('is-loaded');
             };
             imgEl.onerror = () => {
               if (!node.isConnected) return;
               placeholderEl.textContent = '图片加载失败';
+              node.classList.remove('is-loaded');
               node.classList.add('is-error');
             };
+            imgEl.src = url;
           })
           .catch((err) => {
             if (!node.isConnected) return;
@@ -1542,6 +1810,7 @@
           if (getLastSessionForAgent(currentAgent) === session.id) {
             localStorage.removeItem(getAgentSessionStorageKey(currentAgent));
           }
+          pendingNotesByTarget.delete(session.id);
           invalidateSessionCache(session.id);
           send({ type: 'delete_session', sessionId: session.id });
           if (session.id === currentSessionId) {
@@ -1641,7 +1910,9 @@
     currentCwd = null;
     currentModel = currentAgent === 'claude' ? 'opus' : '';
     isGenerating = false;
+    generatingSessionId = null;
     pendingText = '';
+    window.pendingContentBlocks = [];
     pendingAttachments = [];
     uploadingAttachments = [];
     activeToolCalls.clear();
@@ -1653,20 +1924,24 @@
     messagesDiv.innerHTML = buildWelcomeMarkup(currentAgent);
     setStatsDisplay(null);
     renderPendingAttachments();
+    renderPendingNotes({ scroll: false });
     highlightActiveSession();
   }
 
   function applySessionSnapshot(snapshot, options = {}) {
     if (!snapshot) return;
+    const snapshotAgent = normalizeAgent(snapshot.agent);
     if (fileBrowserState && (fileBrowserState.sessionId !== snapshot.sessionId || (snapshot.cwd && fileBrowserState.rootPath !== snapshot.cwd))) {
       closeFileBrowser();
     }
     const preserveStreaming = !!(options.preserveStreaming && isGenerating && snapshot.sessionId === currentSessionId && snapshot.isRunning);
     if (isGenerating && !preserveStreaming) {
       isGenerating = false;
+      generatingSessionId = null;
       sendBtn.hidden = false;
       abortBtn.hidden = true;
       pendingText = '';
+      window.pendingContentBlocks = [];
       activeToolCalls.clear();
       activeTodoCallTargets.clear();
     }
@@ -1674,7 +1949,8 @@
     loadedHistorySessionId = snapshot.sessionId;
     setLastSessionForAgent(snapshot.agent, currentSessionId);
     chatTitle.textContent = snapshot.title || '新会话';
-    setCurrentAgent(snapshot.agent);
+    setCurrentAgent(snapshotAgent);
+    migratePendingNotesToSession(snapshot.sessionId, snapshotAgent);
     setCurrentSessionRunningState(snapshot.isRunning);
     setStatsDisplay(snapshot);
     currentCwd = snapshot.cwd || null;
@@ -1687,6 +1963,8 @@
     currentModel = snapshot.model || '';
     if (!preserveStreaming) {
       renderMessages(snapshot.messages || [], { immediate: !!options.immediate });
+    } else {
+      generatingSessionId = snapshot.sessionId;
     }
     highlightActiveSession();
     renderSessionList();
@@ -1980,6 +2258,19 @@
   }
 
   // --- Server Message Handler ---
+  function isCurrentSessionEvent(msg) {
+    return !msg.sessionId || msg.sessionId === currentSessionId;
+  }
+
+  function ensureGeneratingForEvent(msg) {
+    if (!isCurrentSessionEvent(msg)) return false;
+    const targetSessionId = msg.sessionId || currentSessionId || null;
+    if (!isGenerating || generatingSessionId !== targetSessionId || !document.getElementById('streaming-msg')) {
+      return startGenerating(targetSessionId);
+    }
+    return true;
+  }
+
   function handleServerMessage(msg) {
     switch (msg.type) {
       case 'auth_result':
@@ -2086,13 +2377,13 @@
         break;
 
       case 'text_delta':
-        if (!isGenerating) startGenerating();
+        if (!ensureGeneratingForEvent(msg)) break;
         pendingText += msg.text;
         scheduleRender();
         break;
 
       case 'content_blocks':
-        if (!isGenerating) startGenerating();
+        if (!ensureGeneratingForEvent(msg)) break;
         if (Array.isArray(msg.blocks)) {
           if (!window.pendingContentBlocks) window.pendingContentBlocks = [];
           window.pendingContentBlocks.push(...msg.blocks);
@@ -2101,13 +2392,13 @@
         break;
 
       case 'tool_start':
-        if (!isGenerating) startGenerating();
+        if (!ensureGeneratingForEvent(msg)) break;
         activeToolCalls.set(msg.toolUseId, { name: msg.name, input: msg.input, kind: msg.kind || null, meta: msg.meta || null, done: false });
         appendToolCall(msg.toolUseId, msg.name, msg.input, false, msg.kind || null, msg.meta || null);
         break;
 
       case 'tool_update':
-        if (!isGenerating) startGenerating();
+        if (!ensureGeneratingForEvent(msg)) break;
         if (!activeToolCalls.has(msg.toolUseId)) {
           activeToolCalls.set(msg.toolUseId, {
             name: msg.name,
@@ -2128,6 +2419,7 @@
         break;
 
       case 'tool_end':
+        if (!isCurrentSessionEvent(msg)) break;
         if (activeToolCalls.has(msg.toolUseId)) {
           activeToolCalls.get(msg.toolUseId).done = true;
           if (msg.kind) activeToolCalls.get(msg.toolUseId).kind = msg.kind;
@@ -2138,6 +2430,7 @@
         break;
 
       case 'cost':
+        if (!isCurrentSessionEvent(msg)) break;
         costDisplay.textContent = `$${msg.costUsd.toFixed(4)}`;
         if (currentSessionId) {
           updateCachedSession(currentSessionId, (snapshot) => { snapshot.totalCost = msg.costUsd; });
@@ -2145,6 +2438,7 @@
         break;
 
       case 'usage':
+        if (!isCurrentSessionEvent(msg)) break;
         if (msg.totalUsage) {
           const cacheText = msg.totalUsage.cachedInputTokens ? ` · cache ${msg.totalUsage.cachedInputTokens}` : '';
           costDisplay.textContent = `in ${msg.totalUsage.inputTokens} · out ${msg.totalUsage.outputTokens}${cacheText}`;
@@ -2155,10 +2449,17 @@
         break;
 
       case 'done':
+        if (!isCurrentSessionEvent(msg)) {
+          if (msg.sessionId) {
+            updateCachedSession(msg.sessionId, (snapshot) => { snapshot.isRunning = false; });
+          }
+          break;
+        }
         finishGenerating(msg.sessionId);
         break;
 
       case 'system_message':
+        if (!isCurrentSessionEvent(msg)) break;
         appendSystemMessage(msg.message);
         break;
 
@@ -2183,10 +2484,11 @@
         break;
 
       case 'resume_generating':
+        if (!isCurrentSessionEvent(msg)) break;
         // Server has an active process for this session — resume streaming
         setCurrentSessionRunningState(true);
         if (!isGenerating || !document.getElementById('streaming-msg')) {
-          startGenerating();
+          startGenerating(msg.sessionId || currentSessionId);
         } else {
           sendBtn.hidden = true;
           abortBtn.hidden = false;
@@ -2218,6 +2520,7 @@
         break;
 
       case 'error':
+        if (!isCurrentSessionEvent(msg)) break;
         if (msg.code === 'new_session_cwd_missing' && pendingNewSessionRequest?.cwd) {
           const request = pendingNewSessionRequest;
           pendingNewSessionRequest = null;
@@ -2323,8 +2626,11 @@
   }
 
   // --- Generating State ---
-  function startGenerating() {
+  function startGenerating(sessionId = currentSessionId) {
+    const targetSessionId = sessionId || currentSessionId || null;
+    if (targetSessionId && currentSessionId && targetSessionId !== currentSessionId) return false;
     isGenerating = true;
+    generatingSessionId = targetSessionId;
     setCurrentSessionRunningState(true);
     pendingText = '';
     window.pendingContentBlocks = [];
@@ -2334,6 +2640,7 @@
     hasGrouped = false;
     sendBtn.hidden = true;
     abortBtn.hidden = false;
+    updateNoteModeUI();
     // 不禁用输入框，允许用户继续输入（但无法发送）
 
     const welcome = messagesDiv.querySelector('.welcome-msg');
@@ -2341,6 +2648,7 @@
 
     const msgEl = createMsgElement('assistant', '');
     msgEl.id = 'streaming-msg';
+    if (targetSessionId) msgEl.dataset.sessionId = targetSessionId;
     // 流式消息 bubble 拆为 .msg-text 和 .msg-tools 两个子容器
     const bubble = msgEl.querySelector('.msg-bubble');
     bubble.innerHTML = '';
@@ -2353,12 +2661,16 @@
     bubble.appendChild(toolsDiv);
     messagesDiv.appendChild(msgEl);
     scrollToBottom();
+    return true;
   }
 
   function finishGenerating(sessionId) {
+    if (sessionId && currentSessionId && sessionId !== currentSessionId) return;
     isGenerating = false;
+    generatingSessionId = null;
     sendBtn.hidden = false;
     abortBtn.hidden = true;
+    updateNoteModeUI();
     setCurrentSessionRunningState(false);
     msgInput.focus();
 
@@ -2400,12 +2712,15 @@
       streamEl.removeAttribute('id');
     }
 
-    if (sessionId) currentSessionId = sessionId;
+    if (sessionId) {
+      migratePendingNotesToSession(sessionId, currentAgent);
+    }
     pendingText = '';
     activeToolCalls.clear();
     activeTodoCallTargets.clear();
     toolGroupCount = 0;
     hasGrouped = false;
+    renderPendingNotes();
   }
 
   // --- Rendering ---
@@ -2789,12 +3104,15 @@
     messagesDiv.innerHTML = '';
     if (messages.length === 0) {
       messagesDiv.innerHTML = buildWelcomeMarkup(currentAgent);
+      renderPendingNotes({ scroll: false });
+      scrollToBottom();
       return;
     }
     if (options.immediate) {
       const frag = document.createDocumentFragment();
       messages.forEach((message) => frag.appendChild(buildMsgElement(message)));
       messagesDiv.appendChild(frag);
+      renderPendingNotes({ scroll: false });
       scrollToBottom();
       return;
     }
@@ -2816,6 +3134,7 @@
     const frag0 = document.createDocumentFragment();
     for (let i = batches[0][0]; i < batches[0][1]; i++) frag0.appendChild(buildMsgElement(messages[i]));
     messagesDiv.appendChild(frag0);
+    renderPendingNotes({ scroll: false });
     scrollToBottom();
 
     // Render remaining batches asynchronously, prepending each
@@ -3819,8 +4138,33 @@
   }
 
   // --- Send Message ---
+  function submitUserMessage(text, attachments = []) {
+    const welcome = messagesDiv.querySelector('.welcome-msg');
+    if (welcome) welcome.remove();
+    messagesDiv.appendChild(createMsgElement('user', text, attachments));
+    scrollToBottom();
+
+    send({ type: 'message', text, attachments, sessionId: currentSessionId, mode: currentMode, agent: currentAgent });
+    startGenerating();
+  }
+
   function sendMessage() {
     const text = msgInput.value.trim();
+    if (noteMode) {
+      if ((!text && pendingAttachments.length === 0) || isBlockingSessionLoad()) return;
+      hideCmdMenu();
+      hideOptionPicker();
+      if (pendingAttachments.length > 0) {
+        appendError('笔记模式暂不支持附带图片，请先移除图片。');
+        return;
+      }
+      if (addPendingNoteFromInput(text)) {
+        msgInput.value = '';
+        autoResize();
+      }
+      return;
+    }
+
     if ((!text && pendingAttachments.length === 0) || isGenerating || isBlockingSessionLoad()) return;
     hideCmdMenu();
     hideOptionPicker();
@@ -3852,18 +4196,12 @@
     }
 
     // Regular message
-    const welcome = messagesDiv.querySelector('.welcome-msg');
-    if (welcome) welcome.remove();
     const attachments = pendingAttachments.map((attachment) => ({ ...attachment }));
-    messagesDiv.appendChild(createMsgElement('user', text, attachments));
+    submitUserMessage(text, attachments);
-    scrollToBottom();
-
-    send({ type: 'message', text, attachments, sessionId: currentSessionId, mode: currentMode, agent: currentAgent });
     msgInput.value = '';
     pendingAttachments = [];
     renderPendingAttachments();
     autoResize();
-    startGenerating();
   }
 
   function autoResize() {
@@ -3947,6 +4285,13 @@
     }
   });
   sendBtn.addEventListener('click', sendMessage);
+  if (noteModeBtn) {
+    noteModeBtn.addEventListener('click', () => {
+      noteMode = !noteMode;
+      updateNoteModeUI();
+      msgInput.focus();
+    });
+  }
   abortBtn.addEventListener('click', () => send({ type: 'abort' }));
   if (attachBtn && imageUploadInput) {
     attachBtn.addEventListener('click', () => imageUploadInput.click());
@@ -3987,7 +4332,7 @@
     autoResize();
     const val = msgInput.value;
     // Show slash command menu
-    if (val.startsWith('/') && !val.includes('\n')) {
+    if (!noteMode && val.startsWith('/') && !val.includes('\n')) {
       showCmdMenu(val);
     } else {
       hideCmdMenu();
@@ -5583,6 +5928,7 @@
   // --- Init ---
   applyTheme(currentTheme);
   setCurrentAgent(currentAgent);
+  updateNoteModeUI();
   renderSessionList();
   connect();
   window.addEventListener('resize', updateCwdBadge);

public/index.html

@@ -101,6 +101,13 @@
             </svg>
           </button>
           <textarea id="msg-input" rows="1" placeholder="输入消息… 输入 / 查看指令" autocomplete="off"></textarea>
+          <button id="note-mode-btn" class="note-mode-btn" title="笔记模式" aria-label="笔记模式" aria-pressed="false" type="button">
+            <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M12 20h9"></path>
+              <path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z"></path>
+              <path d="m15 5 3 3"></path>
+            </svg>
+          </button>
           <button id="send-btn" class="send-btn" title="发送">
             <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
               <line x1="22" y1="2" x2="11" y2="13"></line><polygon points="22 2 15 22 11 13 2 9 22 2"></polygon>

public/style.css

@@ -21,6 +21,11 @@
   --success: #5d8a54;              /* 抹茶 matcha */
   --danger: #c0553a;
   --info: #5b7ea1;                 /* 縹色 blue-gray */
+  --note-accent: #5b7ea1;
+  --note-accent-hover: #486b8f;
+  --note-bg: rgba(91, 126, 161, 0.1);
+  --note-bg-strong: rgba(91, 126, 161, 0.16);
+  --note-border: rgba(91, 126, 161, 0.24);
   --scrollbar-thumb: #c9baa9;
   --scrollbar-track: transparent;
   --sidebar-width: 280px;
@@ -62,6 +67,11 @@ html[data-theme='coolvibe'] {
   --success: #2e8a61;
   --danger: #d65567;
   --info: #1976a4;
+  --note-accent: #2e8a61;
+  --note-accent-hover: #226547;
+  --note-bg: rgba(46, 138, 97, 0.1);
+  --note-bg-strong: rgba(46, 138, 97, 0.16);
+  --note-border: rgba(46, 138, 97, 0.24);
   --scrollbar-thumb: #a7c4ce;
   --font-ui: 'Chivo Mono', ui-monospace, monospace;
   --page-background:
@@ -328,6 +338,11 @@ html[data-theme='editorial'] {
   --success: #4d7b57;
   --danger: #c05c42;
   --info: #4f6f87;
+  --note-accent: #4f6f87;
+  --note-accent-hover: #3d596f;
+  --note-bg: rgba(79, 111, 135, 0.1);
+  --note-bg-strong: rgba(79, 111, 135, 0.16);
+  --note-border: rgba(79, 111, 135, 0.24);
   --scrollbar-thumb: #bba995;
   --font-ui: 'Avenir Next', 'Segoe UI', 'PingFang SC', sans-serif;
   --page-background:
@@ -1259,6 +1274,98 @@ body.session-loading-active {
   border-bottom-left-radius: 4px;
   color: var(--text-primary);
 }
+.msg.note {
+  align-self: flex-end;
+  flex-direction: row-reverse;
+  max-width: min(680px, 85%);
+}
+.msg.note .note-avatar {
+  background: var(--note-accent);
+  color: #fff;
+}
+.msg.note .note-bubble {
+  background:
+    linear-gradient(180deg, rgba(255, 255, 255, 0.72), transparent),
+    var(--note-bg);
+  border: 1px solid var(--note-border);
+  border-bottom-right-radius: 4px;
+  color: var(--text-primary);
+  box-shadow: 0 10px 22px rgba(45, 31, 20, 0.05);
+}
+.note-meta {
+  margin-bottom: 6px;
+  color: var(--note-accent);
+  font-size: 11px;
+  font-weight: 800;
+  line-height: 1.2;
+}
+.note-text {
+  white-space: pre-wrap;
+}
+.note-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 6px;
+  margin-top: 10px;
+}
+.note-action {
+  appearance: none;
+  min-height: 30px;
+  padding: 0 10px;
+  border: 1px solid var(--note-border);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.58);
+  color: var(--text-secondary);
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 700;
+  line-height: 1;
+  transition: background 0.15s, border-color 0.15s, color 0.15s, transform 0.1s;
+}
+.note-action:hover {
+  background: var(--note-bg-strong);
+  border-color: var(--note-accent);
+  color: var(--note-accent);
+}
+.note-action:active {
+  transform: scale(0.96);
+}
+.note-action.send,
+.note-action.save {
+  background: var(--note-accent);
+  border-color: transparent;
+  color: #fff;
+}
+.note-action.send:hover,
+.note-action.save:hover {
+  background: var(--note-accent-hover);
+  color: #fff;
+}
+.note-action.delete:hover {
+  background: rgba(192, 85, 58, 0.1);
+  border-color: rgba(192, 85, 58, 0.24);
+  color: var(--danger);
+}
+.note-edit-input {
+  width: min(460px, 100%);
+  min-width: 260px;
+  max-width: 100%;
+  border: 1px solid var(--note-border);
+  border-radius: 10px;
+  outline: none;
+  background: rgba(255, 255, 255, 0.76);
+  color: var(--text-primary);
+  font: inherit;
+  line-height: 1.5;
+  padding: 9px 10px;
+  resize: none;
+}
+.note-edit-input:focus {
+  border-color: var(--note-accent);
+  box-shadow: 0 0 0 3px var(--note-bg);
+}
 
 /* System messages */
 .msg.system {
@@ -1844,6 +1951,10 @@ body.session-loading-active {
   border-color: var(--info);
   box-shadow: 0 0 0 3px rgba(91, 126, 161, 0.12);
 }
+.input-wrapper.note-mode-active {
+  border-color: var(--note-border);
+  box-shadow: 0 0 0 3px var(--note-bg);
+}
 .attach-btn {
   appearance: none;
   width: 40px;
@@ -1865,7 +1976,42 @@ body.session-loading-active {
   background: rgba(192, 85, 58, 0.08);
   border-color: rgba(192, 85, 58, 0.12);
 }
-.attach-btn:disabled {
+.note-mode-btn {
+  appearance: none;
+  width: 36px;
+  height: 36px;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  background: var(--note-accent);
+  color: #fff;
+  cursor: pointer;
+  padding: 0;
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.15s, color 0.15s, border-color 0.15s, transform 0.1s;
+}
+.note-mode-btn:hover {
+  background: var(--note-accent-hover);
+  color: #fff;
+  border-color: transparent;
+}
+.note-mode-btn:active {
+  transform: scale(0.92);
+}
+.note-mode-btn.active {
+  background: var(--note-accent-hover);
+  border-color: transparent;
+  color: #fff;
+  box-shadow: 0 8px 18px var(--note-bg-strong);
+}
+.note-mode-btn.active:hover {
+  background: var(--note-accent-hover);
+  color: #fff;
+}
+.attach-btn:disabled,
+.note-mode-btn:disabled {
   opacity: 0.45;
   cursor: default;
 }
@@ -1904,6 +2050,13 @@ body.session-loading-active {
   color: #fff;
 }
 .send-btn:hover { background: var(--accent-hover); }
+.send-btn.note-send {
+  background: var(--note-accent);
+  color: #fff;
+}
+.send-btn.note-send:hover {
+  background: var(--note-accent-hover);
+}
 .send-btn:disabled { opacity: 0.4; cursor: not-allowed; }
 .abort-btn {
   background: var(--danger);
@@ -2024,8 +2177,13 @@ body.session-loading-active {
   .msg.assistant .msg-bubble { border-bottom-left-radius: 4px; }
   .code-block-wrapper pre code { font-size: 12px; }
   .input-wrapper { padding: 6px 10px; border-radius: 12px; }
-  .attach-btn { width: 38px; height: 38px; border-radius: 11px; }
+  .attach-btn { width: 34px; height: 34px; border-radius: 10px; }
+  .note-mode-btn { width: 34px; height: 34px; border-radius: 10px; }
   .send-btn, .abort-btn { width: 34px; height: 34px; }
+  .msg.note { max-width: 92%; }
+  .note-actions { gap: 5px; }
+  .note-action { min-height: 28px; padding: 0 8px; }
+  .note-edit-input { min-width: 0; }
   .new-chat-btn,
   .new-chat-arrow { min-height: 44px; }
   .new-chat-arrow { width: 48px; }

scripts/mock-codex.js

@@ -14,6 +14,10 @@ function readStdin() {
   });
 }
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 (async function main() {
   const args = process.argv.slice(2);
   // cc-web can place `resume` after other `codex exec` options (e.g. --json, -s).
@@ -83,6 +87,10 @@ function readStdin() {
     process.exit(1);
   }
 
+  if (input === 'slow cross-session prompt') {
+    await sleep(800);
+  }
+
   const responseText = input === '/compact'
     ? 'Codex compact finished.'
     : isInitPrompt

scripts/regression.js

@@ -414,6 +414,21 @@ async function main() {
     assert(cwdSuggestions.defaultPath === homeDir, 'CWD suggestions should expose HOME as default path');
     assert(Array.isArray(cwdSuggestions.paths) && cwdSuggestions.paths.includes(codexInitCwd), 'CWD suggestions should include recently used session directories');
 
+    const crossTalkCwd = path.join(tempRoot, 'codex-cross-talk');
+    mkdirp(crossTalkCwd);
+    ws.send(JSON.stringify({ type: 'new_session', agent: 'codex', cwd: crossTalkCwd, mode: 'yolo' }));
+    const crossTalkSession = await nextMessage(messages, ws, (msg) => msg.type === 'session_info' && msg.agent === 'codex' && msg.cwd === crossTalkCwd);
+    ws.send(JSON.stringify({ type: 'message', text: 'slow cross-session prompt', sessionId: crossTalkSession.sessionId, mode: 'yolo', agent: 'codex' }));
+    await nextMessage(messages, ws, (msg) => msg.type === 'session_list' && msg.sessions.some((s) => s.id === crossTalkSession.sessionId && s.isRunning));
+    ws.send(JSON.stringify({ type: 'new_session', agent: 'codex', mode: 'yolo' }));
+    await nextMessage(messages, ws, (msg) => msg.type === 'session_info' && msg.agent === 'codex' && msg.title === 'New Chat' && msg.sessionId !== crossTalkSession.sessionId);
+    await nextMessage(messages, ws, (msg) => msg.type === 'background_done' && msg.sessionId === crossTalkSession.sessionId, 8000);
+    const leakedCrossTalk = messages.find((msg) => (
+      ['text_delta', 'content_blocks', 'tool_start', 'tool_update', 'tool_end', 'usage', 'cost', 'done', 'system_message', 'error'].includes(msg.type) &&
+      msg.sessionId === crossTalkSession.sessionId
+    ));
+    assert(!leakedCrossTalk, `Running session leaked stream event into new session: ${leakedCrossTalk ? JSON.stringify(leakedCrossTalk) : ''}`);
+
     ws.send(JSON.stringify({ type: 'message', text: '/init', sessionId: codexSession.sessionId, mode: 'plan', agent: 'codex' }));
     const codexInitStart = await nextMessage(messages, ws, (msg) => msg.type === 'system_message' && /AGENTS\.md/.test(msg.message || ''));
     assert(/AGENTS\.md/.test(codexInitStart.message || ''), 'Codex /init should announce AGENTS.md generation');

server.js

@@ -881,6 +881,16 @@ function safeFilename(name) {
     .slice(0, 120) || 'image';
 }
 
+function contentDispositionInline(filename) {
+  const raw = safeFilename(filename || 'image');
+  const fallback = raw
+    .replace(/[^\x20-\x7E]/g, '_')
+    .replace(/["\\;]/g, '_')
+    .trim()
+    .slice(0, 120) || 'image';
+  return `inline; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(raw)}`;
+}
+
 function extFromMime(mime) {
   switch (mime) {
     case 'image/png': return '.png';
@@ -1839,26 +1849,26 @@ function handleProcessComplete(sessionId, exitCode, signal) {
       if (autoRetryRequested) {
         if (contextLimitExceeded) {
           pendingCompactRetries.delete(sessionId);
-          wsSend(entry.ws, { type: 'system_message', message: '已尝试执行 /compact，但仍未成功解除上下文超限。请手动缩小输入范围后重试。' });
+          wsSend(entry.ws, { type: 'system_message', sessionId, message: '已尝试执行 /compact，但仍未成功解除上下文超限。请手动缩小输入范围后重试。' });
         } else {
-          wsSend(entry.ws, { type: 'system_message', message: compactDoneMessage(entry.agent || 'claude') });
+          wsSend(entry.ws, { type: 'system_message', sessionId, message: compactDoneMessage(entry.agent || 'claude') });
-          wsSend(entry.ws, { type: 'system_message', message: compactAutoResumeMessage(entry.agent || 'claude') });
+          wsSend(entry.ws, { type: 'system_message', sessionId, message: compactAutoResumeMessage(entry.agent || 'claude') });
           shouldReturnForFollowup = true;
         }
       } else {
-        wsSend(entry.ws, { type: 'system_message', message: compactDoneMessage(entry.agent || 'claude') });
+        wsSend(entry.ws, { type: 'system_message', sessionId, message: compactDoneMessage(entry.agent || 'claude') });
       }
     }
 
     if (contextLimitExceeded && !pendingSlash && session && getRuntimeSessionId(session)) {
       pendingCompactRetries.set(sessionId, { text: pendingRetry?.text || '', mode: pendingRetry?.mode || session.permissionMode || 'yolo', reason: 'auto' });
-      wsSend(entry.ws, { type: 'system_message', message: compactAutoStartMessage(entry.agent || 'claude') });
+      wsSend(entry.ws, { type: 'system_message', sessionId, message: compactAutoStartMessage(entry.agent || 'claude') });
       shouldAutoCompact = true;
     }
 
     if (completionError && !entry.errorSent && !shouldAutoCompact) {
       entry.errorSent = true;
-      wsSend(entry.ws, { type: 'error', message: completionError });
+      wsSend(entry.ws, { type: 'error', sessionId, message: completionError });
     }
 
     wsSend(entry.ws, { type: 'done', sessionId, costUsd: entry.lastCost || null });
@@ -2100,7 +2110,7 @@ const server = http.createServer((req, res) => {
         res.writeHead(200, {
           'Content-Type': meta.mime || 'application/octet-stream',
           'Content-Length': stat.size,
-          'Content-Disposition': `inline; filename="${(meta.filename || 'image').replace(/"/g, '\\"')}"`,
+          'Content-Disposition': contentDispositionInline(meta.filename || 'image'),
           'Cache-Control': 'private, no-store, max-age=0',
         });
         fs.createReadStream(meta.path).pipe(res);
@@ -2765,6 +2775,9 @@ function handleNewSession(ws, msg) {
     cwd: resolvedCwd,
   };
   saveSession(session);
+  for (const [, entry] of activeProcesses) {
+    if (entry.ws === ws) entry.ws = null;
+  }
   wsSessionMap.set(ws, id);
   wsSend(ws, {
     type: 'session_info',

start.sh

@@ -7,6 +7,8 @@ ENTRY_FILE="${CC_WEB_ENTRY:-server.js}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 APP_DIR="${SCRIPT_DIR}"
 ENTRY_PATH="${APP_DIR}/${ENTRY_FILE}"
+ENV_FILE="${APP_DIR}/.env"
+ENV_EXAMPLE_FILE="${APP_DIR}/.env.example"
 
 log() {
   printf '[cc-web pm2] %s\n' "$*"
@@ -25,6 +27,193 @@ ensure_command() {
   fi
 }
 
+get_env_value() {
+  local key="$1"
+  [[ -f "${ENV_FILE}" ]] || return 0
+
+  awk -v key="${key}" '
+    $0 ~ /^[[:space:]]*#/ { next }
+    {
+      line = $0
+      sub(/^[[:space:]]*/, "", line)
+      if (index(line, key "=") == 1) {
+        sub(/^[^=]*=/, "", line)
+        print line
+        exit
+      }
+    }
+  ' "${ENV_FILE}"
+}
+
+set_env_value() {
+  local key="$1"
+  local value="$2"
+  local tmp_file
+  tmp_file="$(mktemp)"
+
+  if [[ -f "${ENV_FILE}" ]]; then
+    awk -v key="${key}" -v value="${value}" '
+      BEGIN { updated = 0 }
+      {
+        line = $0
+        sub(/^[[:space:]]*/, "", line)
+        if (index(line, key "=") == 1) {
+          print key "=" value
+          updated = 1
+          next
+        }
+        print
+      }
+      END {
+        if (!updated) print key "=" value
+      }
+    ' "${ENV_FILE}" > "${tmp_file}"
+  else
+    printf '%s=%s\n' "${key}" "${value}" > "${tmp_file}"
+  fi
+
+  mv "${tmp_file}" "${ENV_FILE}"
+  chmod 600 "${ENV_FILE}"
+}
+
+validate_password() {
+  local password="$1"
+  local types=0
+
+  if [[ "${#password}" -lt 8 ]]; then
+    printf '密码长度至少 8 位\n'
+    return 1
+  fi
+
+  [[ "${password}" =~ [a-z] ]] && types=$((types + 1))
+  [[ "${password}" =~ [A-Z] ]] && types=$((types + 1))
+  [[ "${password}" =~ [0-9] ]] && types=$((types + 1))
+  [[ "${password}" =~ [^a-zA-Z0-9] ]] && types=$((types + 1))
+
+  if [[ "${types}" -lt 2 ]]; then
+    printf '密码需包含至少 2 种字符类型（大写/小写/数字/特殊字符）\n'
+    return 1
+  fi
+
+  return 0
+}
+
+resolve_config_dir() {
+  local configured
+  configured="${CC_WEB_CONFIG_DIR:-$(get_env_value CC_WEB_CONFIG_DIR)}"
+
+  if [[ -n "${configured}" ]]; then
+    if [[ "${configured}" = /* ]]; then
+      printf '%s\n' "${configured}"
+    else
+      printf '%s/%s\n' "${APP_DIR}" "${configured}"
+    fi
+    return
+  fi
+
+  printf '%s/config\n' "${APP_DIR}"
+}
+
+ensure_env_file() {
+  if [[ -f "${ENV_FILE}" ]]; then
+    log "检测到 .env 配置文件"
+    chmod 600 "${ENV_FILE}"
+    return
+  fi
+
+  if [[ -f "${ENV_EXAMPLE_FILE}" ]]; then
+    cp "${ENV_EXAMPLE_FILE}" "${ENV_FILE}"
+    chmod 600 "${ENV_FILE}"
+    log "已从 .env.example 创建 .env"
+  else
+    : > "${ENV_FILE}"
+    chmod 600 "${ENV_FILE}"
+    log "已创建空 .env"
+  fi
+}
+
+ensure_port_config() {
+  local port
+  port="$(get_env_value PORT)"
+
+  if [[ -z "${port}" ]]; then
+    set_env_value PORT "8002"
+    log "未配置 PORT，已写入默认端口 8002"
+    return
+  fi
+
+  log "服务端口: ${port}"
+}
+
+ensure_initial_password() {
+  local config_dir auth_file env_password password confirm message
+
+  config_dir="$(resolve_config_dir)"
+  auth_file="${config_dir}/auth.json"
+
+  if [[ -f "${auth_file}" ]]; then
+    log "检测到已有登录配置: ${auth_file}，跳过初始密码设置"
+    return
+  fi
+
+  env_password="$(get_env_value CC_WEB_PASSWORD)"
+  if [[ -n "${env_password}" && "${env_password}" != "changeme" ]]; then
+    log "检测到 .env 已配置 CC_WEB_PASSWORD，首次启动时会迁移到 auth.json"
+    return
+  fi
+
+  if [[ ! -t 0 ]]; then
+    fail "首次启动缺少初始密码。请在 .env 中设置 CC_WEB_PASSWORD，或在交互终端执行 ./start.sh。"
+  fi
+
+  log "首次启动需要设置 Web 登录初始密码"
+  while true; do
+    read -r -s -p "请输入初始密码: " password
+    printf '\n'
+    read -r -s -p "请再次输入初始密码: " confirm
+    printf '\n'
+
+    if [[ "${password}" != "${confirm}" ]]; then
+      log "两次输入不一致，请重新输入"
+      continue
+    fi
+
+    if ! message="$(validate_password "${password}")"; then
+      log "${message}"
+      continue
+    fi
+
+    set_env_value CC_WEB_PASSWORD "${password}"
+    log "初始密码已写入 .env；服务首次启动后会迁移到 config/auth.json"
+    break
+  done
+}
+
+check_agent_cli() {
+  local key="$1"
+  local default_cmd="$2"
+  local label="$3"
+  local configured
+
+  configured="$(get_env_value "${key}")"
+  configured="${configured:-${default_cmd}}"
+
+  if command -v "${configured}" >/dev/null 2>&1; then
+    log "${label} CLI: $(command -v "${configured}")"
+    return
+  fi
+
+  log "未检测到 ${label} CLI (${configured})；服务可启动，但对应 Agent 功能需要安装并登录后才能使用"
+}
+
+check_runtime_config() {
+  ensure_env_file
+  ensure_port_config
+  ensure_initial_password
+  check_agent_cli CLAUDE_PATH claude "Claude"
+  check_agent_cli CODEX_PATH codex "Codex"
+}
+
 install_pm2() {
   if command -v pm2 >/dev/null 2>&1; then
     log "PM2 已安装: $(command -v pm2)"
@@ -93,6 +282,7 @@ main() {
     fail "Node.js 版本过低，当前为 $(node -v)，要求 >= 18。"
   fi
 
+  check_runtime_config
   install_pm2
   install_dependencies
   start_or_restart_app

test-todo.html

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Todo List Test</title>
+  <link rel="stylesheet" href="/style.css">
+</head>
+<body>
+  <div id="messages" style="max-width: 800px; margin: 50px auto;"></div>
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+  <script>
+    // 从 app.js 复制的函数
+    function escapeHtml(text) {
+      const div = document.createElement('div');
+      div.textContent = text;
+      return div.innerHTML;
+    }
+
+    function renderMarkdown(text) {
+      if (!text) return '<div class="typing-indicator"><span></span><span></span><span></span></div>';
+      try { return marked.parse(text); }
+      catch { return escapeHtml(text); }
+    }
+
+    function createTodoListElement(block) {
+      const container = document.createElement('div');
+      container.className = 'todo-list-container';
+      container.dataset.todoId = block.id || '';
+
+      const list = document.createElement('ul');
+      list.className = 'todo-list';
+
+      if (Array.isArray(block.items)) {
+        block.items.forEach((item, index) => {
+          const li = document.createElement('li');
+          li.className = 'todo-item' + (item.completed ? ' completed' : '');
+
+          const checkbox = document.createElement('input');
+          checkbox.type = 'checkbox';
+          checkbox.className = 'todo-checkbox';
+          checkbox.checked = item.completed || false;
+          checkbox.dataset.index = index;
+
+          const label = document.createElement('span');
+          label.className = 'todo-text';
+          label.textContent = item.text || '';
+
+          li.appendChild(checkbox);
+          li.appendChild(label);
+          list.appendChild(li);
+        });
+      }
+
+      container.appendChild(list);
+      return container;
+    }
+
+    function renderAssistantContent(bubble, content) {
+      if (!content) return;
+
+      if (typeof content === 'string') {
+        bubble.innerHTML = renderMarkdown(content);
+        return;
+      }
+
+      if (Array.isArray(content)) {
+        content.forEach(block => {
+          if (block.type === 'text') {
+            const textDiv = document.createElement('div');
+            textDiv.innerHTML = renderMarkdown(block.text || '');
+            bubble.appendChild(textDiv);
+          } else if (block.type === 'todo_list') {
+            bubble.appendChild(createTodoListElement(block));
+          }
+        });
+        return;
+      }
+
+      bubble.innerHTML = renderMarkdown(String(content));
+    }
+
+    // 测试数据
+    const testContent = [
+      {
+        type: "text",
+        text: "这是一个任务列表示例："
+      },
+      {
+        id: "item_1",
+        type: "todo_list",
+        items: [
+          { text: "阅读 todo-list-csv skill 并确认仓库现状", completed: false },
+          { text: "梳理前后端改动点与交互入口", completed: false },
+          { text: "实现后端目录浏览与文本预览接口", completed: false },
+          { text: "实现前端文件浏览弹层与交互", completed: false },
+          { text: "补充移动端样式与可用性细节", completed: false },
+          { text: "自查代码并给出验证说明", completed: false }
+        ]
+      }
+    ];
+
+    // 渲染测试
+    const messagesDiv = document.getElementById('messages');
+    const bubble = document.createElement('div');
+    bubble.className = 'msg-bubble';
+    renderAssistantContent(bubble, testContent);
+    messagesDiv.appendChild(bubble);
+  </script>
+</body>
+</html>