eryao/.opencode/commands/trellis/start.md

Start Session

Initialize your AI development session and begin working on tasks.

---

Operation Types

Marker	Meaning	Executor
[AI]	Bash scripts or Task calls executed by AI	You (AI)
[USER]	Slash commands executed by user	User

---

Initialization [AI]

Step 1: Understand Development Workflow

First, read the workflow guide to understand the development process:

cat .trellis/workflow.md

Follow the instructions in workflow.md - it contains:

• Core principles (Read Before Write, Follow Standards, etc.)
• File system structure
• Development process
• Best practices

Step 2: Get Current Context

python3 ./.trellis/scripts/get_context.py

This shows: developer identity, git status, current task (if any), active tasks.

Step 3: Read Guidelines Index

cat .trellis/spec/frontend/index.md  # Frontend guidelines
cat .trellis/spec/backend/index.md   # Backend guidelines
cat .trellis/spec/guides/index.md    # Thinking guides

Important

: The index files are navigation — they list the actual guideline files (e.g., error-handling.md, conventions.md, mock-strategies.md). At this step, just read the indexes to understand what's available. When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.

Step 4: Report and Ask

Report what you learned and ask: "What would you like to work on?"

---

Task Classification

When user describes a task, classify it:

Type	Criteria	Workflow
Question	User asks about code, architecture, or how something works	Answer directly
Trivial Fix	Typo fix, comment update, single-line change, < 5 minutes	Direct Edit
Simple Task	Clear goal, 1-2 files, well-defined scope	Quick confirm → Task Workflow
Complex Task	Vague goal, multiple files, architectural decisions	Brainstorm → Task Workflow

Decision Rule

If in doubt, use Brainstorm + Task Workflow.

Task Workflow ensures code-spec context is injected to agents, resulting in higher quality code. The overhead is minimal, but the benefit is significant.

---

Question / Trivial Fix

For questions or trivial fixes, work directly:

1. Answer question or make the fix
2. If code was changed, remind user to run /trellis:finish-work

---

Complex Task - Brainstorm First

For complex or vague tasks, automatically start the brainstorm process — do NOT skip directly to implementation.

See /trellis:brainstorm for the full process. Summary:

1. Acknowledge and classify - State your understanding
2. Create task directory - Track evolving requirements in prd.md
3. Ask questions one at a time - Update PRD after each answer
4. Propose approaches - For architectural decisions
5. Confirm final requirements - Get explicit approval
6. Proceed to Task Workflow - With clear requirements in PRD

Subtask Decomposition: If brainstorm reveals multiple independent work items, consider creating subtasks using --parent flag or add-subtask command. See /trellis:brainstorm Step 8 for details.

---

Task Workflow (Development Tasks)

Why this workflow?

• Research Agent analyzes what code-spec files are needed
• Code-spec files are configured in jsonl files
• Implement Agent receives code-spec context via Hook injection
• Check Agent verifies against code-spec requirements
• Result: Code that follows project conventions automatically

Overview: Two Entry Points

From Brainstorm (Complex Task):
  PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete

From Simple Task:
  Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete

Key principle: Research happens AFTER requirements are clear (PRD exists).

---

Phase 1: Establish Requirements

Path A: From Brainstorm (skip to Phase 2)

PRD and task directory already exist from brainstorm. Skip directly to Phase 2.

Path B: From Simple Task

Step 1: Confirm Understanding [AI]

Quick confirm:

• What is the goal?
• What type of development? (frontend / backend / fullstack)
• Any specific requirements or constraints?

Step 2: Create Task Directory [AI]

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)

Step 3: Write PRD [AI]

Create prd.md in the task directory with:

# <Task Title>

## Goal
<What we're trying to achieve>

## Requirements
- <Requirement 1>
- <Requirement 2>

## Acceptance Criteria
- [ ] <Criterion 1>
- [ ] <Criterion 2>

## Technical Notes
<Any technical decisions or constraints>

---

Phase 2: Prepare for Implementation (shared)

Both paths converge here. PRD and task directory must exist before proceeding.

Step 4: Code-Spec Depth Check [AI]

If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.

Trigger this requirement when the change includes any of:

• New or changed command/API signatures
• Database schema or migration changes
• Infra integrations (storage, queue, cache, secrets, env contracts)
• Cross-layer payload transformations

Must-have before proceeding:

• Target code-spec files to update are identified
• Concrete contract is defined (signature, fields, env keys)
• Validation and error matrix is defined
• At least one Good/Base/Bad case is defined

Step 5: Research the Codebase [AI]

Based on the confirmed PRD, call Research Agent to find relevant specs and patterns:

Task(
  subagent_type: "research",
  prompt: "Analyze the codebase for this task:

  Task: <goal from PRD>
  Type: <frontend/backend/fullstack>

  Please find:
  1. Relevant code-spec files in .trellis/spec/
  2. Existing code patterns to follow (find 2-3 examples)
  3. Files that will likely need modification

  Output:
  ## Relevant Code-Specs
  - <path>: <why it's relevant>

  ## Code Patterns Found
  - <pattern>: <example file path>

  ## Files to Modify
  - <path>: <what change>",
  model: "opus"
)

Step 6: Configure Context [AI]

Initialize default context:

python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
# type: backend | frontend | fullstack

Add code-spec files found by Research Agent:

# For each relevant code-spec and code pattern:
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"

Step 7: Activate Task [AI]

python3 ./.trellis/scripts/task.py start "$TASK_DIR"

This sets .current-task so hooks can inject context.

---

Phase 3: Execute (shared)

Step 8: Implement [AI]

Call Implement Agent (code-spec context is auto-injected by hook):

Task(
  subagent_type: "implement",
  prompt: "Implement the task described in prd.md.

  Follow all code-spec files that have been injected into your context.
  Run lint and typecheck before finishing.",
  model: "opus"
)

Step 9: Check Quality [AI]

Call Check Agent (code-spec context is auto-injected by hook):

Task(
  subagent_type: "check",
  prompt: "Review all code changes against the code-spec requirements.

  Fix any issues you find directly.
  Ensure lint and typecheck pass.",
  model: "opus"
)

Step 10: Complete [AI]

1. Verify lint and typecheck pass
2. Report what was implemented
3. Remind user to:
   • Test the changes
   • Commit when ready
   • Run /trellis:record-session to record this session

---

Continuing Existing Task

If get_context.py shows a current task:

1. Read the task's prd.md to understand the goal
2. Check task.json for current status and phase
3. Ask user: "Continue working on ?"

If yes, resume from the appropriate step (usually Step 7 or 8).

---

Commands Reference

User Commands [USER]

Command	When to Use
/trellis:start	Begin a session (this command)
/trellis:brainstorm	Clarify vague requirements (called from start)
/trellis:parallel	Complex tasks needing isolated worktree
/trellis:finish-work	Before committing changes
/trellis:record-session	After completing a task

AI Scripts [AI]

Script	Purpose
python3 ./.trellis/scripts/get_context.py	Get session context
python3 ./.trellis/scripts/task.py create	Create task directory
python3 ./.trellis/scripts/task.py init-context	Initialize jsonl files
python3 ./.trellis/scripts/task.py add-context	Add code-spec/context file to jsonl
python3 ./.trellis/scripts/task.py start	Set current task
python3 ./.trellis/scripts/task.py finish	Clear current task
python3 ./.trellis/scripts/task.py archive	Archive completed task

Sub Agents [AI]

Agent	Purpose	Hook Injection
research	Analyze codebase	No (reads directly)
implement	Write code	Yes (implement.jsonl)
check	Review & fix	Yes (check.jsonl)
debug	Fix specific issues	Yes (debug.jsonl)

---

Key Principle

Code-spec context is injected, not remembered.

The Task Workflow ensures agents receive relevant code-spec context automatically. This is more reliable than hoping the AI "remembers" conventions.