A self-contained local tracker for planning and tracking project work in a repo session — no external service, no cloud, pure local files (Python stdlib only).
When to Use
Use this skill when the user asks the agent to:
- Plan milestones for a project / break work into tracked milestones
- Track milestone progress and mark items done
- Record a promise, decision, or event with original text + timestamp (traceable claims)
- Generate a project status report (markdown)
It is designed for repo-session work: the agent runs local commands and keeps state in a local JSON file.
Three-Tier Milestone Rule (Three-Tier Milestone Rules)
Never invent milestone dates. Every milestone must carry a source tier:
| Tier | source | Meaning | Behavior |
|---|---|---|---|
| 1 | file |
Extracted from a contract/document | Authoritative; note the source document |
| 2 | client |
Stated verbally by stakeholder | Recorded as stated; suggest written confirmation |
| 3 | pending |
No milestone info yet | Flag "ask the client" — never self-plan |
How to Use
All commands run via the bundled script (stdlib only, no install):
python3 scripts/pm_track.py --file .pm.json init "东区改造项目"
python3 scripts/pm_track.py --file .pm.json add-milestone "3月15日竣工验收" --source file --due 2026-03-15 --note "依据合同第四章"
python3 scripts/pm_track.py --file .pm.json add-milestone "甲方口头承诺月底回款" --source client --due 2026-03-31
python3 scripts/pm_track.py --file .pm.json add-milestone "材料进场节点待确认" --source pending
python3 scripts/pm_track.py --file .pm.json add-event "甲方说马上回款" --who 王总 --when "2026-03-10 14:30"
python3 scripts/pm_track.py --file .pm.json status
python3 scripts/pm_track.py --file .pm.json report # markdown report
python3 scripts/pm_track.py --file .pm.json done 1
Commands
| Command | What it does |
|---|---|
init <name> |
Initialize a project tracker file |
add-milestone <title> --source file|client|pending [--due] [--note] |
Add a milestone with a source tier |
add-event <text> [--who] [--when] |
Record an event with original text + timestamp |
done <id> |
Mark a milestone done |
status |
Show all milestones + events + pending warnings |
report |
Print a markdown progress report |
Example
$ python3 scripts/pm_track.py --file .pm.json init "门店装修"
$ python3 scripts/pm_track.py --file .pm.json add-milestone "6月10日完工验收" --source file --due 2026-06-10
$ python3 scripts/pm_track.py --file .pm.json add-milestone "水电改造完成" --source client
$ python3 scripts/pm_track.py --file .pm.json add-event "甲方电话说马上回款" --who 李总
$ python3 scripts/pm_track.py --file .pm.json status
📋 Project: 门店装修
=== 里程碑 (2 open) ===
⬜ #1 [file ] 6月10日完工验收 (due 2026-06-10)
⬜ #2 [client] 水电改造完成
=== 事件记录 (1) ===
• [2026-08-25 15:20] (李总) 甲方电话说马上回款
Data & Portability
- State is stored in a local JSON file (default
.project-tracker.json, or pass--file). - Pure Python 3.8+ stdlib (
argparse,json,datetime) — no pip installs, no network. - Works anywhere the agent has a shell. The JSON file can be committed to the repo or git-ignored.
Templates
A milestone planning checklist and a status report template live in templates/ — copy and adapt.
Pitfalls
- Never invent due dates for
pendingmilestones — the whole point of the three-tier rule is that the agent asks the client instead of guessing. - Store original text, not paraphrases — events keep
textverbatim pluswhen/whoso claims are traceable. reportprints markdown to stdout; pipe to a file (> report.md) to save.