Task Management Workflow

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