Task Management Workflow
6.1 Task Lifecycle
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
6.2 task.py 14 Subcommands Explained
Task Creation
# 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
Context Configuration
# 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"
Task Control
# 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"
Task Management
# 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
6.3 task.json Schema
{
"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
6.4 JSONL Context Configuration in Practice
Auto-Generated Default Configuration
task.py init-context generates default JSONL files based on dev_type:
backend type default implement.jsonl:
{"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"}
Adding Custom Context
# 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"
6.5 Plan Agent and Requirements Assessment
The Plan Agent performs strict assessment before accepting requirements, and may reject them. 5 rejection categories:| Rejection Type | Trigger Condition | Example |
|---|---|---|
| Unclear or Vague | No specific outcome defined | ”Make it better”, “Fix the bugs” |
| Incomplete Information | Missing critical implementation details | References unknown systems |
| Out of Scope | Does not belong to this project | Requires modifying external systems |
| Potentially Harmful | Security risk | Intentionally creating backdoors |
| Too Large | Should be split | Requesting 6 features at once |
task.jsonstatus set to"rejected"REJECTED.mdgenerated with reasons and improvement suggestions- Task directory preserved for user review
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