Task Copilot

Task Copilot

tc is the execution record. Use it instead of stuffing long plans or implementation logs into chat.

Command rule

Use --json on commands that support it.

Preferred binary:

tc

Fallback:

./.venv-tc/bin/tc

Core loop

1. retrieve the task
2. do the work
3. store the work product
4. complete the task

Commands:

tc task get <taskId> --json
tc wp store --task <taskId> --type <type> --title "..." --content "..." --json
tc task update <taskId> --status completed --json

Code-Execution Path

Prefer the importable APIs for batches:

python3 - <<'PY'
from tc.api import create_prd, create_task, transaction
from tc.db.connection import get_db, find_db_path

conn = get_db(find_db_path())
try:
    with transaction(conn):
        prd = create_prd(title="Example", conn=conn)
        task = create_task(prd=prd["id"], title="Example task", conn=conn)
finally:
    conn.close()
print(f"PRD-{prd['id']} TASK-{task['id']}")
PY

Use a separate cc.api block for memory or skill batches. Do not import tc.api and cc.api in the same Python block.

QA Metadata

Implementation tasks that require verification should use metadata like:

{"requiresQa": true, "qaStatus": "pending"}

For current tc 2.0.0 work, register a schemaVersion 2 acceptance contract before implementation with tc task contract <id> --file acceptance.json --json. Include observable criteria and source scopes covering implementation, dependencies and relevant authority. Capture tc task evidence-identity <id> before checks, compare a second capture afterwards, and preserve the exact identity in the same task's test work product with observed results for every criterion.

Use one verdict per result. Metadata alone, an artifact marker alone or stale source evidence cannot support approval. Completion also rejects unfinished dependencies. Historical completed records remain historical; pending work needs a current contract and fresh verification.

After QA approval, metadata may index qaStatus, qaWpId and verifiedAt. Inspect with tc task check-qa <id> --json and scripts/copilot-gate.sh --task <id>. In the framework checkout, docs/02-user-guides/04-quality-gates.md contains a complete example; the standalone project plugin does not ship that docs tree.

When no task exists

Create the missing planning records:

tc prd create --title "..." --content "..." --json
tc task create --prd <id> --title "..." --description "..." --json

Initiative boundary

Formal multi-phase initiative knowledge belongs in docs/40-initiatives/NN-slug/: goals, phase designs, decisions, validation evidence, and retrospectives. tc remains authoritative for live task state, dependencies, assignments, work products, and QA status.

Link the initiative README to its PRD and tasks. Do not reproduce a live task board in Markdown.

Work-product guidance

tc wp store requires a task ID. Create a PRD/task first when needed; the current CLI does not provide standalone work-product storage.

Store detailed output when:

• the analysis is long
• decisions should survive the session
• another specialist should consume the result
• the final user response should stay short

Read references/work-product-types.md for type guidance.

For a large work product that benefits from token-free review, use tc wp render <id> --html. The HTML is a rendering of the authoritative work product, not a second source of task state.