jamesaphoenix/tx-workflow

tx Workflow

Picking Up a Task

1. Run tx ready --limit 1 --json to get the next unblocked task
2. Run tx show <id> to see full details, dependencies, and context
3. Run tx memory context <id> to get relevant learnings for the task

Working on a Task

1. Understand the task requirements from tx show
2. Check for relevant learnings with tx memory context <id> or tx memory recall <file-path>
3. If related tasks share context, set it once with tx group-context set <id> "<shared context>"
4. If PRD docs are in scope, prefer ears_requirements and validate with tx doc lint-ears <doc-name-or-yaml-path>
5. Implement the changes
6. Add or update integration tests for critical flows (happy path + failure path)
7. If telemetry code changed, verify OTEL remains non-blocking (noop/configured/exporter-failure paths)
8. Record anything you learned: tx memory add "what you discovered"

Completing a Task

1. Run targeted tests for changed files before completion (bunx --bun vitest run <paths>)
2. Run tx done <id> to mark the task complete
3. This automatically unblocks any tasks that depended on this one
4. Check tx ready to see if new tasks became available

Creating Sub-tasks

If a task is too large, break it down:

tx add "Sub-task title" --parent <parent-id> --description "Details"

Managing Dependencies

# Task B can't start until Task A is done
tx dep block <task-B-id> <task-A-id>

# Remove a dependency
tx dep unblock <task-B-id> <task-A-id>

Recording Learnings

# General learning
tx memory add "Effect.try catch handler puts errors in the error channel, not success"

# File-specific learning
tx memory learn "src/auth/*.ts" "Auth tokens expire after 24h, refresh logic is in token-service.ts"

# Recall learnings for a file
tx memory recall src/auth/token-service.ts