Start here

Build your first p-track workflow

Create durable project memory in a repository, make one plan active, start its first task, and leave enough context to resume in a later terminal or agent session.

Create your first project

Start in the repository you want p-track to remember. Replace the example path and goal with your own:

cd /path/to/your-repository
ptrack init --goal "Ship the widget service"

Without an explicit --root, ptrack init uses the Git repository root when it can find one, or the current directory otherwise. It creates or refreshes the project there.

By default, initialization also installs or refreshes p-track's managed agent guide in the repository instruction files while preserving content outside its managed section. Use ptrack init --no-guide only when you intentionally do not want that guide written.

After initialization, project discovery walks upward from your current directory but stops at the nearest Git boundary. Run commands inside the intended repository so p-track cannot select project state from outside that boundary.

Create and activate your first plan

A plan groups related tasks. Add one, note the numeric ID printed by the command, and activate that exact plan:

ptrack plan add "Build the storage layer"
ptrack plan use 1

Replace 1 with the plan ID that ptrack plan add prints. Adding a plan does not make it active; ptrack plan use <id> is a separate, explicit step. plan add also creates the plan's final Integrate and verify against goal task (skip it with --no-verify-task); in a new project that task is #1.

Add and start your first task

With the plan active, add concrete tasks. Note each printed ID, then start one task:

ptrack task add "Define storage buckets"
ptrack task add "Document the storage format" --plan 1
ptrack task start 2
ptrack task show 2

Replace 2 with the task ID that ptrack task add prints; in a new project the first task you add is #2, because the plan's integration task took #1. ptrack next hands out that integration task only after the plan's other work is done. When task add has no --plan flag, it requires an active plan and adds the task there; pass --plan <id> to target a different plan without changing the active one.

One task is in progress at a time. While a started task is unfinished, task start, task add, and plan add are refused. Finish the task, or park it with ptrack task hold <id> <reason> or ptrack task block <id> [reason]; a held or blocked task no longer counts as in progress.

Use ptrack task show <id> to review the task and its attached context. After the work and its relevant checks are complete, mark it done with a summary of what changed and where it is wired in. The task also needs a linked commit: put #2 in the commit message with the hook installed (ptrack hook install), or record one with ptrack commit record.

ptrack task done 2 --summary "Storage buckets defined in store.rs and used by the loader"

Resume and orient

At the start of a later session, return to the repository and restore the current edge without dumping the entire project:

cd /path/to/your-repository
ptrack context
ptrack next

ptrack context prints a bounded resume digest: the goal, rolling summary, active plan, blockers, open issues, recent decisions, and inventory. ptrack next identifies the single most-actionable task in the active plan.

Drill into only the selected plan or task when you need more detail:

ptrack plan show 1
ptrack task show 1

These orientation commands are read-only. When you make a durable product or architectural decision during the work, attach a concise note to the relevant plan or task so the next session can recover it. When another agent or supported tool will take over, follow the cross-agent transfer workflow.

Workflow at a glance