Project Task Json Manager

Workflow

1. Confirm the target file is the repo-root project-management-data.json, unless the user explicitly points elsewhere.
2. Resolve the helper path as .agents/skills/project-task-json-manager/scripts/manage_tasks.py relative to the repo root. If working from another directory, use the absolute path to the same script.
3. Use find first when the user refers to a task loosely by title, assignee, tag, or status.
4. Use find, add, update, and delete only through manage_tasks.py.
5. If the script is missing, fails unexpectedly, or cannot perform the requested task, stop and report the blocker. Do not fall back to manual JSON edits.
6. After any mutating operation, validate the file with jq empty project-management-data.json.
7. Summarize the specific task changes made, including task IDs.

Commands

Find tasks

Use find to inspect tasks without mutating the file.

python3 .agents/skills/project-task-json-manager/scripts/manage_tasks.py find --text billing
python3 .agents/skills/project-task-json-manager/scripts/manage_tasks.py find --project-id prj-001 --status in-progress
python3 .agents/skills/project-task-json-manager/scripts/manage_tasks.py find --assignee-id usr-002 --tag frontend

Supported filters:

• --id
• --project-id
• --milestone-id
• --assignee-id
• --reporter-id
• --status
• --priority
• --tag
• --text
• --limit

Add tasks

Use add with repeated --set field=value. Do not create tasks by editing JSON directly.

Required fields:

• projectId
• title
• description
• status
• priority
• assigneeId
• reporterId

Behavior:

• Generate the next tsk-### ID automatically.
• Set createdAt automatically when not provided.
• Accept JSON literals for arrays and numbers, so tags='["api","backend"]' and estimateHours=8 work.
• Validate cross-references to projects, users, and milestones.
• Recompute stats.totalTasks, stats.tasksByStatus, stats.completedTasks, and stats.overdueTasks.

Update tasks

Use update --id ... --set field=value to change one task. Do not modify task objects directly in the JSON file.

python3 .agents/skills/project-task-json-manager/scripts/manage_tasks.py update \
  --id tsk-004 \
  --set status=done \
  --set dueDate=2026-04-09 \
  --set tags='["backend","api","billing"]'

Rules:

• Only update fields that belong to the task schema documented in references/task-schema.md.
• Use JSON literals for arrays, booleans, numbers, or null.
• Re-run find --id ... if you need to confirm the current shape before updating.

Delete tasks

Use delete --id ... to remove one task by exact ID. Do not remove task entries manually from JSON.

python3 .agents/skills/project-task-json-manager/scripts/manage_tasks.py delete --id tsk-018

Behavior:

• Remove only the matching task.
• Recompute the task-related stats fields after deletion.
• Do not delete comments or activity automatically; handle those separately only if the user asks.

Notes

• Read references/task-schema.md when you need the exact task fields or valid reference behavior.
• Keep the file path default unless the user requests a different JSON file.
• Treat direct JSON editing as a bug in skill execution, not an acceptable fallback.
• Do not change unrelated top-level sections unless task CRUD requires a stats refresh.