Everyday Use

./.trellis/scripts/multi-agent/plan.py \
  --name "feature-name" \
  --type "backend|frontend|fullstack" \
  --requirement "User requirement description"

./.trellis/scripts/multi-agent/start.py "$TASK_DIR"

./.trellis/scripts/multi-agent/status.py                  # Overview
./.trellis/scripts/multi-agent/status.py --log <name>     # View logs
./.trellis/scripts/multi-agent/status.py --watch <name>   # Live monitoring
./.trellis/scripts/multi-agent/cleanup.py <branch>        # Clean up worktree

./.trellis/scripts/add-session.py \
  --title "Session Title" \
  --commit "hash1,hash2" \
  --summary "What was accomplished in this session"

create → init-context → add-context → start → implement/check → finish → archive
  │           │              │           │          │               │         │
  │           │              │           │          │               │         │
  ▼           ▼              ▼           ▼          ▼               ▼         ▼
Create      Init JSONL     Add context  Set as     Development/   Clear     Archive to
directory   config files   entries      current    check cycle    current   archive/
task.json                               task ptr                  task

# 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 file: task.json

# Initialize JSONL config
./.trellis/scripts/task.py init-context "$TASK_DIR" backend
# dev_type: backend | frontend | fullstack | test | docs
# Optional: --platform cursor (default claude)

# Add extra context entries
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/auth.ts" "Existing auth patterns"
# Target: implement | check | debug (shorthand, auto-appends .jsonl)
# Automatically detects whether it's a file or directory

# Validate all JSONL-referenced files exist
./.trellis/scripts/task.py validate "$TASK_DIR"

# View all JSONL entries
./.trellis/scripts/task.py list-context "$TASK_DIR"

# Set as current task (Hook reads this pointer for injection)
./.trellis/scripts/task.py start "$TASK_DIR"

# Clear current task (no arguments needed, auto-reads .current-task)
./.trellis/scripts/task.py finish

# Set Git branch name
./.trellis/scripts/task.py set-branch "$TASK_DIR" "feature/user-login"

# Set PR target branch
./.trellis/scripts/task.py set-base-branch "$TASK_DIR" "main"

# Set scope (used in commit messages: feat(scope): ...)
./.trellis/scripts/task.py set-scope "$TASK_DIR" "auth"

# List active tasks
./.trellis/scripts/task.py list
./.trellis/scripts/task.py list --mine        # Only show your own
./.trellis/scripts/task.py list --status review  # Filter by status

# Archive completed tasks
./.trellis/scripts/task.py archive user-login
# Moves to archive/2026-02/

# List archived tasks
./.trellis/scripts/task.py list-archive
./.trellis/scripts/task.py list-archive 2026-02  # Filter by month

# Create PR (delegates to multi-agent/create-pr.py)
./.trellis/scripts/task.py create-pr

{
  "id": "02-27-user-login",
  "name": "user-login",
  "title": "Add user login",
  "description": "Implement JWT login flow",
  "status": "in_progress",
  "dev_type": "backend",
  "scope": "auth",
  "priority": "P1",
  "creator": "alice",
  "assignee": "alice",
  "createdAt": "2026-02-27T10:00:00Z",
  "completedAt": null,
  "branch": "feature/user-login",
  "base_branch": "main",
  "worktree_path": null,
  "current_phase": 1,
  "next_action": [
    { "phase": 1, "action": "implement" },
    { "phase": 2, "action": "check" },
    { "phase": 3, "action": "finish" },
    { "phase": 4, "action": "create-pr" }
  ],
  "commit": null,
  "pr_url": null,
  "subtasks": [],
  "relatedFiles": [],
  "notes": ""
}

planning → in_progress → review → completed
       ↘ rejected

{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
{"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": ".claude/commands/trellis/finish-work.md", "reason": "Finish work checklist"}
{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
{"file": ".claude/commands/trellis/check.md", "reason": "Backend check spec"}

# Add existing code as reference (file)
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/user.ts" "Existing user service patterns"

# Add an entire directory (auto-reads all .md files)
./.trellis/scripts/task.py add-context "$TASK_DIR" implement \
  "src/services/" "Existing service patterns"

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

Input: "Add user authentication, authorization, password reset,
        2FA, OAuth integration, and audit logging"

=== PLAN REJECTED ===

Reason: Too Large / Should Be Split

Details:
This requirement bundles 6 distinct features:
1. User authentication (login/logout)
2. Authorization (roles/permissions)
3. Password reset flow
4. Two-factor authentication
5. OAuth integration
6. Audit logging

Suggestions:
- Start with basic authentication first
- Create separate features for each capability

my-monorepo/
├── packages/
│   ├── api/
│   ├── web/
│   └── shared/
└── .trellis/
    ├── spec/
    │   ├── api/         # API package conventions
    │   │   ├── backend/index.md
    │   │   └── ...
    │   ├── web/         # Web package conventions
    │   │   ├── frontend/index.md
    │   │   └── ...
    │   ├── shared/      # Shared package conventions
    │   └── guides/      # Shared thinking guides
    └── tasks/...

# Explicit
python3 ./.trellis/scripts/task.py create "Add login endpoint" \
  --slug add-login \
  --package api

# Directory: .trellis/tasks/MM-DD-add-login/ (task.json.package = "api")

python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" backend --package api
# Populates implement.jsonl with .trellis/spec/api/backend/* entries only

hooks:
  after_create:
    - 'python3 .trellis/scripts/hooks/linear_sync.py create'
  after_start:
    - 'python3 .trellis/scripts/hooks/linear_sync.py start'
  after_finish:
    - "echo 'Task finished'"
  after_archive:
    - 'python3 .trellis/scripts/hooks/linear_sync.py archive'

{
  "linear": {
    "team": "ENG",
    "project": "My Project",
    "assignees": {
      "alice": "linear-user-id-for-alice"
    }
  }
}

.trellis/spec/
├── frontend/                    # Frontend specs
│   ├── 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
│   ├── 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

# See how existing code is organized
ls src/components/     # Component structure
ls src/services/       # Service structure

# 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

### Good Example

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

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

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

**Step 4**: Update index.md status

```markdown
| Guideline | File | Status |
|-----------|------|--------|
| Component Guidelines | component-guidelines.md | **Filled** |
| Hook Guidelines | hook-guidelines.md | To fill |

### Database Query Pattern

**Always use parameterized queries** to prevent SQL injection.

```sql
-- Good
SELECT * FROM users WHERE id = $1

-- Bad
SELECT * FROM users WHERE id = '${userId}'

**Bad specs** (too vague, no code, no reasoning):

```markdown
### Database
- Use good query patterns
- Be careful with SQL
- Follow best practices

### Variable Naming
- All boolean variables must start with `is` or `has`
- All arrays must end with `List`
- All functions must be less than 20 lines
- All files must be less than 200 lines

Develop → Discover pattern/issue → Manually update Spec file → git push
                                                                   ↓
  Entire team benefits ← Hook auto-injects ← Next session auto-loads ← git pull

# 1. Start parallel mode
/parallel

# 2. Describe requirements
"I need to develop three features in parallel:
1. User profile page
2. Email notification system
3. Data export feature"

# 3. AI automatically creates a worktree for each feature and starts Agents

# 4. Monitor progress
./.trellis/scripts/multi-agent/status.py
# Task 1: user-profile     ✅ Complete (PR #123)
# Task 2: email-notify     🔄 In Progress (Check phase)
# Task 3: data-export      🔄 In Progress (Implement phase)

# 5. Review and merge PRs

# 6. Clean up worktrees
./.trellis/scripts/multi-agent/cleanup.py user-profile

# ✅ Database Layer: comments table created
# ✅ API Layer: POST /api/comments endpoint
# ✅ UI Layer: CommentForm component
# ✅ Data Flow: UI → API → DB ✓

# 6. Test, commit, record

# Alice develops and documents specs (Claude Code example, Cursor uses /start)
trellis init -u alice
/start
# ... develop authentication system ...
# Manually write auth best practices into specs
git add .trellis/spec/
git commit -m "docs: add auth guidelines"
git push

# Bob pulls and automatically benefits
git pull
trellis init -u bob
/start
"Add permission management"
# AI auto-reads Alice's auth guidelines
# Bob's code automatically follows Alice's specs

# 1. Start
/start

# 2. Fix the bug
"Users can't log in under certain conditions"

# 3. AI debugs and fixes...

# 4. Deep analysis
/break-loop

# AI output:
# Root Cause: B - Cross-layer Contract Violation
#   Token format sent by frontend doesn't match backend expectations
#
# Prevention:
#   - Update spec: define token format contract
#   - Add type constraint: shared Token interface
#   - Add test: token format validation

# 5. Manually update specs
# Write token format contract into .trellis/spec/ files

# Discover a pattern
# AI discovers during development: all API errors should return a uniform format
# { error: string, code: number, details?: any }

# Manually update specs
# Write this pattern into .trellis/spec/backend/error-handling.md

# Next time anyone does API development
# Hook auto-injects error-handling.md
# AI automatically follows the uniform error format
# → All API errors are consistently formatted

# 1. Create project
mkdir my-app && cd my-app
git init

# 2. Install Trellis
npm install -g @mindfoldhq/trellis@latest
trellis init -u your-name

# 3. trellis init has auto-created the bootstrap guide task (00-bootstrap-guidelines)
/start
# AI auto-detects the bootstrap task, analyzes your codebase, and helps fill in specs

# 4. Manually supplement core specs
# Edit .trellis/spec/backend/index.md, etc.
# Write down your tech stack choices, coding conventions, directory structure

# 5. Start developing
/start
"Set up the project foundation"