### Local Development Setup and Verification

Source: https://docs.trytrellis.app/contribute/docs

Commands to set up the local development environment, start the dev server, check markdown linting, verify the docs structure, and format files.

```bash
# Install dependencies
pnpm install

# Start local dev server
pnpm dev

# Check markdown lint
pnpm lint:md

# Verify docs structure
pnpm verify

# Format files
pnpm format
```

--------------------------------

### Starting prompt for a new project

Source: https://docs.trytrellis.app/start/install-and-first-task

Example prompt to initiate a new B2B dashboard project and request AI assistance with setup and specifications.

```text
I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.

First, ask for the missing product and tech-stack decisions. Then create a small first task and the minimum specs needed for frontend structure, API shape, error handling, and test strategy.
```

--------------------------------

### Install All Available Skills

Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization

Installs all available skills from the marketplace using npx. This is a broader installation command.

```bash
npx skills add mindfold-ai/marketplace
```

--------------------------------

### Install Frontend Fullchain Optimization Skill

Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization

Installs the specific frontend-fullchain-optimization skill using npx. Ensure you have Node.js and npm installed.

```bash
npx skills add mindfold-ai/marketplace --skill frontend-fullchain-optimization
```

--------------------------------

### Install Trellis CLI

Source: https://docs.trytrellis.app/start/install-and-first-task

Install the Trellis CLI globally via npm and navigate to your project directory to begin setup.

```bash
# Global install (beta channel)
npm install -g @mindfoldhq/trellis@latest

# Navigate to your project directory
cd your-project
```

--------------------------------

### Clone and Install Dependencies

Source: https://docs.trytrellis.app/contribute/docs

Fork the repository on GitHub, clone it locally, and install project dependencies using pnpm.

```bash
# Fork on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/docs.git
cd docs
pnpm install
```

--------------------------------

### Install Trellis globally

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.13

Use this command for a fresh installation of the specified Trellis version.

```bash
npm i -g @mindfoldhq/trellis@0.5.0-beta.13
```

--------------------------------

### Install fresh Trellis version

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.12

Command to perform a fresh installation of the specific beta version.

```bash
npm i -g @mindfoldhq/trellis@0.5.0-beta.12
```

--------------------------------

### Install Trellis beta

Source: https://docs.trytrellis.app/changelog/v0.6.0-beta.0

Commands to install the beta version of Trellis and update the local installation.

```bash
npm install -g @mindfoldhq/trellis@beta
trellis update
```

--------------------------------

### Kubernetes Control Loop Example

Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis

This example demonstrates the power of the Kubernetes control loop in action. It shows how the system automatically detects and recovers from a pod deletion, and adapts to changes in the desired state without manual intervention.

```text
I declare: I want 3 nginx Pods

A Pod gets accidentally deleted → Controller detects 2 ≠ 3 → Auto-creates 1
I modify declaration to 5      → Controller detects 3 ≠ 5 → Auto-creates 2

No manual intervention needed. System auto-detects, auto-recovers, auto-adapts.
```

--------------------------------

### Install Trellis CLI

Source: https://docs.trytrellis.app/skills-market/mem-recall

Install the Trellis CLI globally via npm and verify the installation version.

```bash
npm install -g @mindfoldhq/trellis@beta
trellis --version   # ≥ 0.6.0-beta.0
```

--------------------------------

### Example Curated implement.jsonl

Source: https://docs.trytrellis.app/start/everyday-use

An example of a curated implement.jsonl file after AI review for a monorepo with `dev_type=backend`. It contains spec and research files relevant to the task.

```jsonl
{"file": ".trellis/spec/guides/index.md", "reason": "Shared cross-package thinking guides"}
{"file": ".trellis/spec/cli/backend/index.md", "reason": "Backend dev guide — task touches Python scripts"}
{"file": ".trellis/spec/cli/backend/script-conventions.md", "reason": "Script conventions for the affected files"}
{"file": ".trellis/tasks/.../research/auth-library-comparison.md", "reason": "Library choice rationale"}
```

--------------------------------

### Cross-Session Memory Example

Source: https://docs.trytrellis.app/start/install-and-first-task

An example of how the AI recalls previous session progress upon startup.

```text
AI: "Hi Alice — last session you finished the user login feature (commit abc1234),
     covering the LoginForm component, JWT middleware, and users table.
     What next?"
```

--------------------------------

### Initialize with Official Marketplace Templates

Source: https://docs.trytrellis.app/start/install-and-first-task

Use the 'trellis init' command to start a project. You can either use the interactive picker or specify a template ID directly.

```bash
# Interactive: browse and pick from available templates
trellis init -u your-name

# Non-interactive: specify a template by ID
trellis init -u your-name --template electron-fullstack
```

--------------------------------

### JSONL File Example for Context Injection

Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis

Example of a JSONL file used to specify files and reasons for context injection into an agent.

```jsonl
{"file": ".trellis/spec/backend/index.md", "reason": "Backend guidelines"}
{"file": "src/api/auth.ts", "reason": "Existing auth pattern"}
```

--------------------------------

### Check Available Skills

Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization

A command to list all installed skills, used to verify the installation of frontend-fullchain-optimization.

```bash
What skills do you have access to?
```

--------------------------------

### YAML Configuration for Verification Commands

Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis

Example 'worktree.yaml' file demonstrating how to configure verification commands for the Ralph Loop.

```yaml
verify:
  - pnpm lint
  - pnpm typecheck
```

--------------------------------

### Install mem-recall skill

Source: https://docs.trytrellis.app/skills-market

Install the memory recall skill to enable cross-platform conversation history retrieval.

```bash
npx skills add mindfold-ai/marketplace -s mem-recall
```

--------------------------------

### Initialize Trellis with Versioned Spec Template

Source: https://docs.trytrellis.app/advanced/custom-spec-template-marketplace

Installs a specific version of a spec template from the marketplace registry using a Git ref.

```bash
trellis init --registry gh:myorg/my-spec-marketplace/marketplace#v1 --template web-app
```

--------------------------------

### Component Guidelines Example (Markdown)

Source: https://docs.trytrellis.app/start/everyday-use

An example of writing down conventions for component development, including file structure and coding patterns. This markdown format is suitable for spec files.

```markdown
# Component Guidelines

## File Structure

- One component per file
- Use PascalCase for filenames: `UserProfile.tsx`
- Co-locate styles: `UserProfile.module.css`
- Co-locate tests: `UserProfile.test.tsx`

## Patterns

#### Required

- Functional components + hooks (no class components)
- TypeScript with explicit Props interface
- `export default` for page components, named export for shared

#### Forbidden

- No `any` type in Props
- No inline styles (use CSS Modules)
- No direct DOM manipulation

```

--------------------------------

### Install and Initialize Trellis on Windows

Source: https://docs.trytrellis.app/advanced/appendix-f

Prerequisites include Node.js 18+ and Python 3.9+. Running these commands initializes the project and sets the necessary environment variable for stable path resolution.

```bash
# 1. Install Node.js 18+ and Python 3.9+
# 2. Install Trellis
npm install -g @mindfoldhq/trellis@latest
# 3. Initialize
cd your-project
trellis init -u your-name
```

--------------------------------

### Install Specific Template by ID

Source: https://docs.trytrellis.app/advanced/custom-spec-template-marketplace

When using a marketplace registry, you can specify a particular template to install using the `--template` flag followed by the template's ID.

```bash
trellis init --registry gh:myorg/my-spec-marketplace/marketplace --template web-app
```

--------------------------------

### Install or upgrade Trellis

Source: https://docs.trytrellis.app/changelog/v0.4.0

Commands for performing a fresh installation via npm or upgrading an existing Trellis installation.

```bash
# Fresh install
npm install -g @mindfoldhq/trellis@latest --registry=https://registry.npmjs.org

# Upgrade (existing trellis install)
trellis update
```

--------------------------------

### Install marketplace skills

Source: https://docs.trytrellis.app/skills-market

Use this command to add the marketplace repository to your Trellis project.

```bash
npx skills add mindfold-ai/marketplace
```

--------------------------------

### Add Trellis Meta Skill from Marketplace

Source: https://docs.trytrellis.app/skills-market/trellis-meta

Installs the trellis-meta skill from the marketplace for non-Trellis projects or older installs. This command requires npx.

```bash
npx skills add mindfold-ai/marketplace --skill trellis-meta
```

--------------------------------

### Install Trellis via NPM

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.10

Use this command to install the Trellis package globally via NPM.

```bash
npm install -g @mindfoldhq/trellis@beta
```

--------------------------------

### Initial Trellis Setup Prompt

Source: https://docs.trytrellis.app/start/real-world-scenarios

Use this prompt to initiate a new B2B dashboard project, requesting that the AI gather necessary product and tech-stack decisions before generating initial documentation and specifications.

```text
I am starting a new B2B dashboard from scratch. Help me set up Trellis for the first week of work.

First, ask for the missing product and tech-stack decisions. Then create a small first-task PRD and
the minimum specs needed for frontend structure, API shape, error handling, and tests.
```

--------------------------------

### Start a Trellis Session

Source: https://docs.trytrellis.app/start/everyday-use

Use `/trellis:start` to initiate a development session, especially on platforms that don't auto-inject context. It reads workflow definitions, gathers developer context, and prepares for task classification.

```bash
/trellis:start
```

--------------------------------

### Task JSON Schema Example

Source: https://docs.trytrellis.app/start/everyday-use

This is an example of the task.json structure as written by `task.py create`. Fields are populated over time by various commands.

```json
{
  "id": "02-27-user-login",
  "name": "user-login",
  "title": "Add user login",
  "description": "Implement JWT login flow",
  "status": "planning",
  "dev_type": null,
  "scope": null,
  "package": null,
  "priority": "P1",
  "creator": "alice",
  "assignee": "alice",
  "createdAt": "2026-02-27",
  "completedAt": null,
  "branch": null,
  "base_branch": "main",
  "worktree_path": null,
  "commit": null,
  "pr_url": null,
  "subtasks": [],
  "children": [],
  "parent": null,
  "relatedFiles": [],
  "notes": "",
  "meta": {}
}
```

--------------------------------

### Initialize AI Agent

Source: https://docs.trytrellis.app/blog/ai-collaborative-dev-system

Use the /init-agent command to start an AI session. The AI will read project progress and frontend specifications to understand the context.

```plaintext
Me: /init-agent
```

--------------------------------

### Create spec bootstrap

Source: https://docs.trytrellis.app/advanced/appendix-b

Initializes the spec bootstrap process using the create_bootstrap.py script. This is typically used for first-time setup.

```bash
# Spec bootstrap (first-time)
./.trellis/scripts/create_bootstrap.py
```

--------------------------------

### Complete JSONL Configuration for Fullstack Implementation

Source: https://docs.trytrellis.app/advanced/appendix-d

An example of a complete implement.jsonl file, listing workflow, relevant spec indexes, and task research directories for the trellis-implement sub-agent.

```jsonl
{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}
{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend development guide"}
{"file": ".trellis/spec/frontend/components.md", "reason": "Component conventions"}
{"file": ".trellis/tasks/02-27-user-login/research/", "type": "directory", "reason": "Research outputs for this task"}
```

--------------------------------

### Install Trellis RC version

Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.1

Use this command to install the release candidate version of Trellis via npm.

```bash
npm install -g @mindfoldhq/trellis@rc
```

--------------------------------

### Add Deploy Agent

Source: https://docs.trytrellis.app/skills-market/trellis-meta

Example prompt to instruct AI to add a deploy agent for handling deployment workflows using the trellis-meta skill.

```bash
I want to add a deploy agent to handle deployment workflow
```

--------------------------------

### Invoke init-context with platform flag

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.10

Example of invoking the init-context task with the --platform flag using the {{CLI_FLAG}} placeholder.

```bash
python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
```

--------------------------------

### Basic Configuration Example

Source: https://docs.trytrellis.app/advanced/configuration

This snippet shows a basic configuration for session commit message, maximum journal lines, and session auto-commit.

```yaml
session_commit_message: 'chore: record journal'
max_journal_lines: 2000
session_auto_commit: false
```

--------------------------------

### Initialize Trellis with Claude

Source: https://docs.trytrellis.app/skills-market/trellis-meta

Initializes a Trellis project with the Claude platform. This command automatically installs the trellis-meta skill.

```bash
trellis init --claude
```

--------------------------------

### Initialize project with spec template

Source: https://docs.trytrellis.app/advanced/appendix-f

Use the trellis init command with the -r flag to pull shared rules from a remote git repository when starting a new project.

```bash
trellis init -r git@github.com:your-org/trellis-spec-template.git
```

--------------------------------

### Install trellis-meta skill

Source: https://docs.trytrellis.app/advanced/appendix-f

Use this command to add the trellis-meta skill to your project for workflow customization.

```bash
npx skills add mindfold-ai/marketplace --skill trellis-meta
```

--------------------------------

### Conventional Commit Message Examples

Source: https://docs.trytrellis.app/contribute/docs

Examples of commit messages following the conventional commits specification for documenting changes.

```bash
docs: add Next.js spec template
fix: correct broken link in quickstart
feat: add new skill to marketplace
```

--------------------------------

### Example Short Command: Check Frontend

Source: https://docs.trytrellis.app/blog/ai-collaborative-dev-system

This markdown file defines a prompt for AI to check frontend code against project specifications. It instructs the AI to use git status and consult specific documentation files for validation.

```markdown
Check your own work—does the code you just wrote follow frontend development specs? First use git status to see which files were modified, then go to `.cursor/rules/frontend-structure/index.md` to find the corresponding doc details and check against `.cursor/rules/frontend-structure/doc.md`
...
```

--------------------------------

### Execute task by name

Source: https://docs.trytrellis.app/changelog/v0.3.0-beta.8

Use the task name directly instead of the full path to start a task.

```bash
python3 task.py start my-task
```

--------------------------------

### Hook Output Format Example

Source: https://docs.trytrellis.app/advanced/custom-hooks

This JSON demonstrates the expected output format for a hook, including permission decisions and updated tool inputs.

```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "subagent_type": "trellis-implement",
      "prompt": "modified prompt..."
    }
  }
}
```

--------------------------------

### task.py start error message

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.15

The error message displayed when task.py start is executed without an available session identity.

```text
Error: Cannot set active task without a session identity.
Hint: run inside an AI IDE/session that exposes session identity, or set TRELLIS_CONTEXT_ID before running task.py start.
```

--------------------------------

### api-doc output format example

Source: https://docs.trytrellis.app/advanced/custom-skills

The expected output format for the api-doc skill after processing changes.

```text
Added endpoints:
  POST /api/foo
Modified endpoints:
  PUT /api/bar (request body changed)
Removed endpoints:
  (none)
```

--------------------------------

### Initialize Trellis with Codex

Source: https://docs.trytrellis.app/skills-market/trellis-meta

Initializes a Trellis project with the Codex platform. This command automatically installs the trellis-meta skill.

```bash
trellis init --codex
```

--------------------------------

### Create Electron Project with Vite and TypeScript

Source: https://docs.trytrellis.app/use-cases/open-typeless

Initializes a new Electron project using create-electron-app with the vite-typescript template. It then navigates into the project directory, removes default npm files, sets up a .npmrc for pnpm, and installs dependencies using pnpm.

```bash
npx create-electron-app@latest open-typeless --template=vite-typescript

cd open-typeless

# Remove npm generated files
rm -rf node_modules package-lock.json

# Create .npmrc (required for pnpm + Electron)
cat > .npmrc << 'EOF'
node-linker=hoisted
shamefully-hoist=true
EOF

# Reinstall with pnpm
pnpm install
```

--------------------------------

### Check Trellis Version

Source: https://docs.trytrellis.app/

Verify the installed version of the Trellis CLI.

```bash
trellis --version
```

--------------------------------

### Initialize First-time Project

Source: https://docs.trytrellis.app/start/install-and-first-task

Use this command to create the .trellis/ directory and bootstrap the project specification.

```bash
trellis init -u your-name --claude
```

--------------------------------

### Frontend Development Spec Index Example

Source: https://docs.trytrellis.app/blog/ai-collaborative-dev-system

A sample `index.md` file demonstrating a lightweight navigation table for frontend development specifications. It maps development tasks to specific chapters and line ranges in the detailed `doc.md`.

```markdown
# Frontend Development Spec Index

> **Complete doc**: See `./doc.md` for detailed specifications

This index helps you quickly locate the spec chapters you need. Find the corresponding chapters and line numbers based on the type of feature you're developing.

## Related Workflow Documents

| Document                            | Use Case                      |
| ----------------------------------- | ----------------------------- |
| `../frontend-figma-workflow/doc.md` | Developing from Figma designs |

## Quick Navigation

| Development Task                         | Chapters to Read                           | Line Range |
| ---------------------------------------- | ------------------------------------------ | ---------- |
| **New feature module**                   | Directory structure spec                   | L5-36      |
| **Writing Command Palette**              | Component dev spec > Command Palette       | L876-1425  |
| **Writing Query Hook**                   | Hook dev spec > Query Hook                 | L179-265   |
| **Writing Mutation Hook**                | Hook dev spec > Mutation Hook              | L266-351   |
| **Calling backend API**                  | API calling spec                           | L382-735   |
| **Real-time communication (WebSocket)**  | API calling spec > Real-time               | L419-465   |
| **AI streaming response (SSE)**          | API calling spec > SSE                     | L466-497   |
| **AI Tool Calls handling**               | API calling spec > Tool Calls              | L498-735   |
| **State management**                     | State management spec                      | L736-873   |
| **URL state sync**                       | State management spec > URL/Context        | L738-873   |
| **Writing components**                   | Component dev spec                         | L874-1645  |
| **Accessibility and image optimization** | Component dev spec > Semantic HTML & Image | L1426-1544 |
| **Performance optimization**             | Performance optimization spec              | L1676-1762 |
| **Code quality check**                   | Code quality and formatting spec           | L2140-2317 |
| **Code review**                          | General rules + Checklist                  | L1763-2344 |
```

--------------------------------

### Skill Description Trigger Examples

Source: https://docs.trytrellis.app/advanced/custom-skills

Comparison of effective and ineffective description fields for triggering skills.

```yaml
# Good: describes the trigger
description: |
  Use when the user reports a bug that was just fixed and wants to understand the root cause and prevent recurrence. Runs a 5-dimension analysis.

# Bad: describes the skill's identity
description: |
  The break-loop skill analyzes bugs.
```

--------------------------------

### Initialize with Marketplace Mode

Source: https://docs.trytrellis.app/advanced/custom-spec-template-marketplace

Use this command to initialize a project using a spec template from a marketplace registry. The source path should point to the directory containing `index.json`.

```bash
trellis init --registry gh:myorg/my-spec-marketplace/marketplace
```

--------------------------------

### Start Task Execution

Source: https://docs.trytrellis.app/showcase/terminal-demo

Initiates the execution of the current task, enabling hooks to inject context into agents. This is crucial for agents to access necessary information.

```shell
● Bash
(task.py start ...)
: hooks will inject context into agents
```

--------------------------------

### Add New Workflow Phase

Source: https://docs.trytrellis.app/skills-market/trellis-meta

Example prompt to instruct AI to add a new workflow phase named 'review' using the trellis-meta skill.

```bash
I want to add a new workflow phase called review
```

--------------------------------

### Initialize New Developer or New Machine

Source: https://docs.trytrellis.app/start/install-and-first-task

Use this command when a new developer joins or when working on a new machine to generate an onboarding task.

```bash
trellis init -u their-name
```

--------------------------------

### JSONL Directory Entry Example

Source: https://docs.trytrellis.app/advanced/appendix-d

Specifies a directory to be read by a sub-agent, including its type and a reason. The hook reads up to 20 .md files from the directory.

```jsonl
{
  "file": ".trellis/tasks/02-27-user-login/research/",
  "type": "directory",
  "reason": "Research outputs for this task"
}
```

--------------------------------

### Initiate New AI Session

Source: https://docs.trytrellis.app/showcase/terminal-demo

Starts a new AI session in Trellis. This is the first step in interacting with the AI for development tasks.

```shell
❯ New AI session
```

--------------------------------

### Review Lighthouse Report

Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization

Leverages the frontend-fullchain-optimization skill to analyze a Lighthouse report and suggest a small, high-impact fix. Assumes the skill is installed.

```bash
Review this Lighthouse report with frontend-fullchain-optimization and propose the smallest high-impact fix.
```

--------------------------------

### Activate Task Script

Source: https://docs.trytrellis.app/start/how-it-works

Starts the Trellis task execution. This script changes the task status from 'planning' to 'in_progress'.

```bash
python3 ./.trellis/scripts/task.py start <task-dir>
```

--------------------------------

### JSONL File Entry Example

Source: https://docs.trytrellis.app/advanced/appendix-d

Specifies a single file to be read by a sub-agent, along with a reason for its inclusion. Use spec files or research outputs.

```jsonl
{
  "file": ".trellis/spec/backend/index.md",
  "reason": "Backend development guide"
}
```

--------------------------------

### Prevent manifest overwrite via create-manifest.js

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.12

Example output when attempting to overwrite a manifest for a version already published on npm.

```bash
$ node scripts/create-manifest.js --stdin <<< '{"version": "0.5.0-beta.11", ...}'
✗ Version 0.5.0-beta.11 is already published on npm.
  Its manifest is part of the update contract and must NOT be rewritten.
  If you need to release additional migrations, use the NEXT version number.
```

--------------------------------

### Initialize Platform Configurations

Source: https://docs.trytrellis.app/start/install-and-first-task

Use the init command to configure your developer identity and set up specific AI coding platforms. Each platform must be initialized at least once.

```bash
# Interactive: detects installed platforms and asks which to configure
trellis init -u your-name

# Explicit: configure one or more platforms
trellis init -u your-name --claude
trellis init -u your-name --claude --cursor --opencode
trellis init -u your-name --codex --gemini
trellis init -u your-name --pi
```

--------------------------------

### Pi Agent Markdown configuration

Source: https://docs.trytrellis.app/advanced/custom-agents

Example of a Pi sub-agent definition using YAML frontmatter to specify model, thinking, and fallback configurations.

```markdown
---
name: trellis-review
description: |
  Reviews the current diff and reports correctness issues.
tools: Read, Write, Edit, Bash, Glob, Grep
model: anthropic/claude-sonnet-4
thinking: high
fallbackModels:
  - openai/gpt-5-mini
---

# trellis-review

Review the current diff against the active Trellis task and project specs.
```

--------------------------------

### Starting prompt for Trellis spec generation

Source: https://docs.trytrellis.app/start/real-world-scenarios

Use this prompt to initiate the conversion of repeated PR feedback into concrete, enforceable Trellis specs.

```text
Review the last few PR comments and help me convert repeated engineering feedback into Trellis specs.

Only propose rules that are concrete, enforceable, and tied to actual review comments. For each rule,
show the target spec file and a good/bad example.
```

--------------------------------

### Diagnose Poor LCP

Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization

Uses the frontend-fullchain-optimization skill to diagnose poor LCP and identify the primary fix. Assumes the skill is installed.

```bash
Use frontend-fullchain-optimization to diagnose why this route has poor LCP and tell me what to fix first.
```

--------------------------------

### Starting prompt for SessionStart hook crash

Source: https://docs.trytrellis.app/start/real-world-scenarios

A prompt used to initiate the fix for a SessionStart hook crash caused by Python version mismatches.

```text
Fix the SessionStart hook crash on `str | None`. The user's terminal Python is 3.11, but the hook
subprocess seems to use something older.

Reproduce on a minimal-PATH shell, identify the smallest safe fix, add a way to detect this class
of issue going forward, and then run a break-loop analysis. If the root cause exposes a missing
convention, propose a spec update.
```

--------------------------------

### Initialize with Direct Mode

Source: https://docs.trytrellis.app/advanced/custom-spec-template-marketplace

Use this command for direct mode initialization, where the source path points directly to the desired template directory within a repository. This bypasses the `index.json` lookup.

```bash
trellis init --registry gh:myorg/my-spec-marketplace/marketplace/specs/web-app
```

--------------------------------

### Electron Full-Stack Template Structure

Source: https://docs.trytrellis.app/templates/specs-electron

Illustrates the directory structure of the Electron full-stack template, showing organization for frontend, backend, guides, and shared modules.

```tree
spec/
├── frontend/
│   ├── index.md
│   ├── components.md
│   ├── hooks.md
│   ├── state-management.md
│   ├── ipc-electron.md
│   └── ...
│
├── backend/
│   ├── index.md
│   ├── api-patterns.md
│   ├── database.md
│   ├── error-handling.md
│   └── ...
│
├── guides/
│   ├── cross-layer-thinking-guide.md
│   ├── bug-root-cause-thinking-guide.md
│   └── ...
│
├── shared/
│   ├── typescript.md
│   ├── git-conventions.md
│   └── ...
│
└── README.md
```

--------------------------------

### Trellis Workflow User Input Example

Source: https://docs.trytrellis.app/showcase/terminal-demo

Shows a user's command input within the Trellis AI workflow. This represents a user initiating an action.

```text
❯ /trellis:finish-work
```

--------------------------------

### Minimal Marketplace Index JSON

Source: https://docs.trytrellis.app/advanced/custom-spec-template-marketplace

This is a minimal example of an `index.json` file for a spec template marketplace. It defines the version and an array of available templates, including their ID, type, name, description, path, and tags.

```json
{
  "version": 1,
  "templates": [
    {
      "id": "web-app",
      "type": "spec",
      "name": "Web App",
      "description": "Next.js + oRPC + PostgreSQL conventions",
      "path": "marketplace/specs/web-app",
      "tags": ["nextjs", "orpc", "postgres"]
    }
  ]
}
```

--------------------------------

### AI-driven channel operation prompt

Source: https://docs.trytrellis.app/advanced/channel

Example of a natural language prompt used to instruct the trellis-channel skill to perform a design review.

```text
Use trellis-channel to ask a Codex reviewer to challenge this design.
Give it the PRD and design only, run at least two pressure-test rounds,
then summarize the blockers without changing code.
```

--------------------------------

### PreToolUse Hook Input Example

Source: https://docs.trytrellis.app/advanced/custom-hooks

This JSON shows the input format for a PreToolUse hook, including event name, tool details, and current working directory.

```json
{
  "hook_event_name": "PreToolUse",
  "tool_name": "Task",
  "tool_input": {
    "subagent_type": "trellis-implement",
    "prompt": "..."
  },
  "cwd": "/path/to/project"
}
```

--------------------------------

### Trellis Workflow AI Output Example

Source: https://docs.trytrellis.app/showcase/terminal-demo

Illustrates the AI's output during a workflow, showing tool calls and arguments. This is part of the AI's interaction log.

```text
● Update (platform-integration.md): added Gemini CLI conventions
```

```text
● Bash (task.py archive gemini-cli)
```

```text
● Bash (add_session.py --title "feat: Gemini CLI support" --commit "ec6114a")
```

```text
└ Task archived. Session recorded to journal-4.md.
```

--------------------------------

### Initialize with Custom Registry

Source: https://docs.trytrellis.app/start/install-and-first-task

Pull specifications from custom GitHub, GitLab, or Bitbucket repositories using the '--registry' flag. The format follows 'provider:user/repo[/subdir][#ref]'.

```bash
# Direct download: repo directory becomes .trellis/spec/
trellis init --registry gh:myorg/myrepo/my-team-spec

# Marketplace mode: repo has index.json with multiple templates
trellis init --registry gh:myorg/myrepo/marketplace

# Pick a specific template from a custom marketplace
trellis init --registry gh:myorg/myrepo/marketplace --template my-template

# Specify a branch
trellis init --registry gh:myorg/myrepo/specs#develop

# GitLab or Bitbucket
trellis init --registry gitlab:myorg/myrepo/specs
trellis init --registry bitbucket:myorg/myrepo/specs
```

--------------------------------

### Workflow State Injection Example

Source: https://docs.trytrellis.app/start/how-it-works

This text block illustrates how the current workflow state is resolved and represented. It shows the steps involved in finding the relevant session and task information.

```text
cwd
  -> find .trellis/
  -> resolve session key
  -> read .trellis/.runtime/sessions/<session-key>.json
  -> read .trellis/tasks/<task>/task.json
  -> read task.json.status
```

--------------------------------

### Initialize Qoder CLI

Source: https://docs.trytrellis.app/advanced/multi-platform

Use this command to initialize the Trellis project for the Qoder platform.

```bash
trellis init -u your-name --qoder
```

--------------------------------

### Initialize Oh My Pi platform

Source: https://docs.trytrellis.app/changelog/v0.6.6

Initializes a new Oh My Pi project, creating the necessary directory structure for agents, commands, skills, and extensions.

```bash
trellis init --omp
```

--------------------------------

### Create a new task

Source: https://docs.trytrellis.app/advanced/appendix-b

Creates a new task. If a sub-agent platform is installed, this also seeds `implement.jsonl` or `check.jsonl`. Supports assigning a slug, assignee, and priority.

```bash
task.py create "title" [--slug name] [-a assignee] [-p priority]
```

--------------------------------

### Task archive command input examples

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.16

The task.py archive command now supports bare task names, relative paths, and absolute paths for task-directory lookups.

```bash
python3 .trellis/scripts/task.py archive 04-27-example
```

```bash
python3 .trellis/scripts/task.py archive .trellis/tasks/04-27-example
```

```bash
python3 .trellis/scripts/task.py archive /repo/.trellis/tasks/04-27-example
```

--------------------------------

### Manual Evidence Mode Diagnosis

Source: https://docs.trytrellis.app/skills-market/frontend-fullchain-optimization

Instructs the frontend-fullchain-optimization skill to operate in manual-evidence mode when only DevTools screenshots and metric snapshots are available. Assumes the skill is installed.

```bash
I only have DevTools screenshots and metric snapshots. Use frontend-fullchain-optimization in manual-evidence mode.
```

--------------------------------

### Pi Subagent Configuration Frontmatter

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.17

Example YAML frontmatter used in .pi/agents/*.md files to define model and thinking settings for Pi subagents.

```yaml
---
model: anthropic/claude-sonnet-4
thinking: high
fallbackModels:
  - openai/gpt-5-mini
---
```

--------------------------------

### Workflow State Parsing Example

Source: https://docs.trytrellis.app/start/how-it-works

This text block demonstrates the format used to parse workflow state from `.trellis/workflow.md`. It shows the delimiters for a specific workflow state block.

```text
[workflow-state:STATUS]
...
[/workflow-state:STATUS]
```

--------------------------------

### Initialize Trellis with multiple platforms

Source: https://docs.trytrellis.app/changelog/v0.4.0

Use the init command to enable multiple AI coding platforms simultaneously with a specified username.

```bash
trellis init --codex --gemini --copilot -u your-name
```

--------------------------------

### Starting prompt for refactoring task

Source: https://docs.trytrellis.app/start/real-world-scenarios

Use this prompt to initiate a behavior-preserving refactor task for a specific file. It emphasizes mapping responsibilities and establishing test coverage before making any changes.

```text
Create a behavior-preserving refactor task for src/billing/invoice-service.ts.

First map current responsibilities, callers, side effects, and existing tests. Then propose the safest
sequence. Do not change behavior until we have characterization tests or clear existing coverage for
the important billing paths.
```

--------------------------------

### Initialize DeepSeek Harness with trellis init

Source: https://docs.trytrellis.app/changelog/v0.6.15

Initializes the DeepSeek Harness workflow by writing shared skills to .agents/skills/ and entry skills to .dsh/skills/.

```bash
trellis init --dsh
```

--------------------------------

### Original statusline encoding setup

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.14

The previous implementation for setting UTF-8 encoding on Windows, which caused crashes on Python builds where sys.stdout/stderr do not expose detach().

```python
sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding="utf-8")
sys.stderr = io.TextIOWrapper(sys.stderr.detach(), encoding="utf-8")
```

--------------------------------

### Start task with explicit context ID

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.15

Manual shell command to start a task by providing an explicit context ID via the TRELLIS_CONTEXT_ID environment variable.

```bash
TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/<task>
```

--------------------------------

### Seed row format for implement.jsonl and check.jsonl

Source: https://docs.trytrellis.app/changelog/v0.5.0-beta.12

The seed row format used when initializing jsonl files. It includes an _example key to guide the agent in filling out spec and research entries.

```jsonl
{"_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 when done."}
```

--------------------------------

### Next.js Full-Stack Template Structure

Source: https://docs.trytrellis.app/templates/specs-nextjs

Illustrates the directory structure of the Next.js full-stack template, organizing frontend, backend, guides, shared modules, and specific topic directories.

```tree
spec/
├── frontend/
│   ├── index.md
│   ├── components.md
│   ├── hooks.md
│   ├── state-management.md
│   ├── orpc-usage.md
│   ├── authentication.md
│   ├── ai-sdk-integration.md
│   └── ...
│
├── backend/
│   ├── index.md
│   ├── orpc-usage.md
│   ├── database.md
│   ├── authentication.md
│   ├── performance.md
│   └── ...
│
├── guides/
│   ├── pre-implementation-checklist.md
│   ├── cross-layer-thinking-guide.md
│   └── ...
│
├── shared/
│   ├── typescript.md
│   ├── code-quality.md
│   ├── dependencies.md
│   └── ...
│
├── big-question/
│   ├── postgres-json-jsonb.md
│   ├── sentry-nextintl-conflict.md
│   └── ...
│
└── README.md
```

--------------------------------

### Good Example: TypeScript Component with Props Interface

Source: https://docs.trytrellis.app/start/everyday-use

A 'good' example of a React component written in TypeScript, demonstrating the use of an explicit `UserProfileProps` interface and named export.

```tsx
interface UserProfileProps {
  userId: string;
  onUpdate: (user: User) => void;
}

export function UserProfile({ userId, onUpdate }: UserProfileProps) {
  // ...
}

```

--------------------------------

### Get context information

Source: https://docs.trytrellis.app/advanced/appendix-b

Retrieves context information using the get_context.py script. Options include full context, JSON output, package-specific layers, or record mode for finishing work.

```bash
# Context
./.trellis/scripts/get_context.py                 # Full context
./.trellis/scripts/get_context.py --json          # JSON
./.trellis/scripts/get_context.py --mode packages # Per-package spec layers (monorepo)
./.trellis/scripts/get_context.py --mode record   # For /trellis:finish-work
```

--------------------------------

### Bad Example: TypeScript Component without Props Interface

Source: https://docs.trytrellis.app/start/everyday-use

A 'bad' example of a React component, highlighting the anti-pattern of not using an explicit Props interface and using `export default` for a shared component.

```tsx
// Don't: no Props interface, using any
export default function UserProfile(props: any) {
  // ...
}

```

--------------------------------

### ORM Parallel Single Row Create Example

Source: https://docs.trytrellis.app/start/everyday-use

Even when parallelized with Promise.all, looping single 'create' calls results in N database round-trips and should be avoided in favor of batch methods.

```typescript
await Promise.all(users.map((user) => prisma.user.create({ data: user })));
```

--------------------------------

### Startup Context Script

Source: https://docs.trytrellis.app/advanced/architecture

This Python script is used during the main session startup to load the initial context.

```python
.trellis/scripts/get_context.py
```

--------------------------------

### ORM Single Row Create Loop Example

Source: https://docs.trytrellis.app/start/everyday-use

Avoid looping through records and calling the ORM's single 'create' method for each. This results in N database round-trips and can significantly degrade performance.

```typescript
for (const user of users) {
  await prisma.user.create({ data: user });
}
```

--------------------------------

### Initialize Trellis for OpenCode

Source: https://docs.trytrellis.app/advanced/multi-platform

Run this command to initialize the Trellis environment specifically for the OpenCode platform.

```bash
trellis init -u your-name --opencode
```

--------------------------------

### Initialize with Private Repositories

Source: https://docs.trytrellis.app/start/install-and-first-task

Access private repositories by setting the 'GIGET_AUTH' environment variable with a personal access token.

```bash
GIGET_AUTH=ghp_xxxxx trellis init --registry gh:myorg/private-repo/specs
```

--------------------------------

### Initialize Gemini CLI

Source: https://docs.trytrellis.app/advanced/multi-platform

Use this command to initialize the Trellis project for the Gemini platform.

```bash
trellis init -u your-name --gemini
```

--------------------------------

### Modify trellis-check configuration

Source: https://docs.trytrellis.app/advanced/custom-agents

Example of adding a timeout and tool budget to the trellis-check sub-agent definition.

```markdown
---
name: trellis-check
description: |
  Code quality check expert. Reviews diffs against specs, runs lint/typecheck/test, self-fixes.
tools: Read, Write, Edit, Bash, Glob, Grep
timeout: 600000
---
```

--------------------------------

### Initialize Trellis for Kiro

Source: https://docs.trytrellis.app/advanced/multi-platform

Run this command to initialize the Trellis environment specifically for the Kiro platform.

```bash
trellis init -u your-name --kiro
```

--------------------------------

### Create a New Task

Source: https://docs.trytrellis.app/start/everyday-use

Use this command to create a new task directory with initial files. You can specify a slug, assignee, priority, and description.

```bash
# Create a task
TASK_DIR=$(./.trellis/scripts/task.py create "Add user login" \
  --slug user-login \
  # Directory name suffix (optional, auto-slugifies otherwise)
  --assignee alice \
  # Assignee (optional)
  --priority P1 \
  # Priority: P0/P1/P2/P3 (optional, default P2)
  --description "Implement JWT login")  # Description (optional)

# Created directory: .trellis/tasks/02-27-user-login/
# Created files: task.json, prd.md
# May also create implement.jsonl + check.jsonl on sub-agent-capable platforms

```

--------------------------------

### Create a New Task

Source: https://docs.trytrellis.app/start/how-it-works

Use this command to create a new task directory and initialize its planning state. Ensure you replace '<title>' and '<name>' with appropriate values.

```bash
python3 ./.trellis/scripts/task.py create "<title>" --slug <name>
```

--------------------------------

### Define trellis-test sub-agent

Source: https://docs.trytrellis.app/advanced/custom-agents

Example definition for a new trellis-test sub-agent, including its name, description, tools, and operational flow.

```markdown
---
name: trellis-test
description: |
  Writes comprehensive tests for the current diff. Runs them and reports pass/fail.
tools: Read, Write, Edit, Bash, Glob, Grep
---

# trellis-test

You are the trellis-test sub-agent in the Trellis workflow.

## Responsibilities

1. Analyze the current diff to identify testable units.
2. Write unit tests for new functions and components.
3. Write integration tests for cross-module interactions.
4. Run the test suite and report results.

## Flow

#### Get changes

```bash
git diff --name-only HEAD
```

#### Identify testable code

For each changed file, identify functions or components that need tests.

#### Write tests

Follow the existing test patterns in the repository. Do not invent a new test style.

#### Run tests

```bash
pnpm test
```
```

--------------------------------

### Read deployment configuration files

Source: https://docs.trytrellis.app/advanced/custom-commands

Displays the contents of the deployment configuration and production environment files for verification.

```bash
cat deploy.config.js
cat .env.production
```

--------------------------------

### Add Check Context

Source: https://docs.trytrellis.app/start/everyday-use

Command to add context for verification steps. This ensures relevant guides or specifications are available for checks.

```bash
# Add check context
./.trellis/scripts/task.py add-context "$TASK_DIR" check \
  ".trellis/spec/guides/cross-layer-thinking-guide.md" "Cross-layer verification"
```

--------------------------------

### Configure SessionStart Hook in settings.json

Source: https://docs.trytrellis.app/advanced/custom-hooks

This JSON configuration sets up the `SessionStart` hook to run a Python script for initializing the environment. It specifies a command, a timeout, and a matcher for when the hook should trigger.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.py\"",
            "timeout": 10
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-workflow-state.py\"",
            "timeout": 5
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/inject-subagent-context.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Upgrade Trellis CLI

Source: https://docs.trytrellis.app/advanced/appendix-b

Use this command to upgrade the globally installed Trellis CLI package to the latest version or a specific tag.

```bash
trellis upgrade [--tag <tag>]
```

--------------------------------

### Trellis initialization CLI prompt

Source: https://docs.trytrellis.app/advanced/multi-platform

The interactive menu displayed when running 'trellis init' in a project that has already been initialized.

```text
? Trellis is already initialized. What would you like to do?
❯ Add AI platform(s)
  Set up developer identity on this device
  Full re-initialize
```

--------------------------------

### Kubernetes Control Loop Analogy

Source: https://docs.trytrellis.app/blog/use-k8s-to-know-trellis

This illustrates the core Kubernetes control loop concept. It shows how the controller observes the desired state against the actual state, calculates the difference, and acts to reconcile them, repeating the process.

```text
Desired State          Actual State
(User declares)        (System observes)
      |
      +---> Controller <----+
                |
            Observe → Diff → Act → Repeat
```

--------------------------------

### Initialize Oh My Pi

Source: https://docs.trytrellis.app/advanced/multi-platform

Initializes the Trellis project with Oh My Pi extension support using the --omp flag.

```bash
trellis init -u your-name --omp
```

--------------------------------

### Context Manifests (implement.jsonl)

Source: https://docs.trytrellis.app/start/how-it-works

Defines stable context files for implementation. Use this to list artifacts that should be read before the implementation phase.

```jsonl
{"file": ".trellis/spec/docs-site/docs/style-guide.md", "reason": "Docs writing style"}
{"file": ".trellis/tasks/04-30-example/research/platforms.md", "reason": "Platform behavior research"}
```

--------------------------------

### Initialize GitHub Copilot

Source: https://docs.trytrellis.app/advanced/multi-platform

Use this command to initialize the Trellis project for GitHub Copilot.

```bash
trellis init -u your-name --copilot
```

--------------------------------

### Trellis Workflow Phases

Source: https://docs.trytrellis.app/advanced/architecture

Defines the three main phases of the Trellis contract: Plan, Execute, and Finish. This structure guides the workflow process.

```text
Phase 1: Plan    -> classify the turn, get task-creation consent, write planning artifacts
Phase 2: Execute -> implement, check, and repeat until green
Phase 3: Finish  -> final verification, spec update, work commit, archive
```

--------------------------------

### Initialize Trellis for Cursor

Source: https://docs.trytrellis.app/advanced/multi-platform

Run this command to initialize the Trellis environment specifically for the Cursor platform.

```bash
trellis init -u your-name --cursor
```

--------------------------------

### Initialize CodeBuddy

Source: https://docs.trytrellis.app/advanced/multi-platform

Use this command to initialize the Trellis project for the CodeBuddy platform.

```bash
trellis init -u your-name --codebuddy
```

--------------------------------

### Update Trellis Project Files

Source: https://docs.trytrellis.app/advanced/appendix-b

Syncs the current project's Trellis files with the globally installed CLI. Supports dry-run and migration options.

```bash
trellis update [--dry-run] [--migrate] [...]
```

--------------------------------

### Initialize Droid

Source: https://docs.trytrellis.app/advanced/multi-platform

Use this command to initialize the Trellis project for the Droid platform.

```bash
trellis init -u your-name --droid
```

--------------------------------

### Start Parallel Git Worktree Sessions

Source: https://docs.trytrellis.app/use-cases/open-typeless

Create separate Git worktrees for each parallel development task. Each worktree is associated with a specific feature branch.

```bash
git worktree add ../asr-audio-recorder -b feature/asr-audio-recorder
git worktree add ../asr-volcengine-client -b feature/asr-volcengine-client
git worktree add ../asr-floating-window -b feature/asr-floating-window
```

--------------------------------

### Initialize Trellis

Source: https://docs.trytrellis.app/use-cases/open-typeless

Initializes the Trellis environment within the current project directory.

```bash
trellis init
```

--------------------------------

### Create Task with task.py

Source: https://docs.trytrellis.app/start/everyday-use

Use the `task.py create` command to initiate a new task. This command sets up the task directory, creates a default `prd.md` file, and configures the AI session for the new task. It also handles seeding of `implement.jsonl` and `check.jsonl` for agent-capable platforms.

```python
task.py create
```

--------------------------------

### Default Trellis Spec Directory Structure

Source: https://docs.trytrellis.app/start/everyday-use

This is the default directory structure created by `trellis init`. It includes placeholder templates for frontend, backend, and guides.

```tree
.trellis/spec/
├── frontend/                    # Frontend specs (placeholders)
│   ├── index.md                 #   Index: lists all specs and their status
│   ├── component-guidelines.md  #   Component specs
│   ├── hook-guidelines.md       #   Hook specs
│   ├── state-management.md      #   State management
│   ├── type-safety.md           #   Type safety
│   ├── quality-guidelines.md    #   Quality guidelines
│   └── directory-structure.md   #   Directory structure
│
├── backend/                     # Backend specs (placeholders)
│   ├── index.md
│   ├── database-guidelines.md
│   ├── error-handling.md
│   ├── logging-guidelines.md
│   ├── quality-guidelines.md
│   └── directory-structure.md
│
└── guides/                      # Thinking guides
    ├── index.md
    ├── cross-layer-thinking-guide.md
    └── code-reuse-thinking-guide.md

```

--------------------------------

### Initialize Pi Agent

Source: https://docs.trytrellis.app/advanced/multi-platform

Use this command to initialize the Trellis project for the Pi Agent platform.

```bash
trellis init -u your-name --pi
```

--------------------------------

### Initialize Factory Droid support

Source: https://docs.trytrellis.app/changelog/v0.4.0-rc.1

Run this command to initialize Factory Droid support, which writes 12 Trellis commands to the .factory/commands/trellis/ directory.

```bash
trellis init --droid
```

--------------------------------

### Per-Turn Workflow State File

Source: https://docs.trytrellis.app/advanced/architecture

This Markdown file contains information used for guiding the main session's next actions on a per-turn basis.

```markdown
.trellis/workflow.md
```

--------------------------------

### List task context entries

Source: https://docs.trytrellis.app/advanced/appendix-b

Displays all context entries for a task in the specified directory.

```bash
task.py list-context "$DIR"
```