plan-task-standards

name	plan-task-standards
description	Self-contained CatHerder method and standards for plans and tasks: planning vs execution, execution loop, prompt precedence, persistence; plus prompt/spec/implementation/review/follow-up files, frontmatter, statuses, timestamps, the open-questions gate, and validation. Use when planning, creating, reviewing, executing, or validating planNNN folders, or fixing plan/task format drift.

Plan & Task Standards

CatHerder standards for plan folders and task files.

This file is a router. Read only the section for your job, then open the one reference it points to. You do not need to read everything.

Find Your Job

You are about to…	Roles	Read
Understand the CatHerder method (always)	any	references/method.md
Write a prompt or spec (intent)	planner, product-manager	references/role-planner.md
Turn a spec into an implementation with tasks	planner, architect, lead-dev	references/role-planner.md
Execute one task	lead-dev, senior-dev, junior-dev	references/role-executor.md
Review a spec/implementation, or verify a task	qa, architect, planner, senior-dev	references/role-reviewer.md
Validate or fix file format/drift	any	run the validator (below)

The full rule set is references/plan-task-spec-2026-05.md; open it only when a role file points you there.

This skill is self-contained. If the project has .instructions/catherder.project.instructions.md, read it and follow its guidance (identity, phase, git workflow, build/test).

Plan Folder Files

planNNN-short-description/
  planNNN-prompt.md           # original request (optional)
  planNNN-spec.md             # intent: what & why
  planNNN-implementation.md   # executable plan + tasks
  planNNN-post-followup.md    # post-completion tracking (optional)
  data/  tasks/  review/

Lifecycle: prompt → spec → implementation → (review) → completed → (follow-up).

Quick Rules (all roles)

• Status and timestamps live in frontmatter. name is not used.
• Spec frontmatter type: plan-spec, status draft/ready.
• Implementation frontmatter type: plan-implementation, status active/completed/abandoned.
• Task frontmatter type: task; status: not-started, in-progress, blocked, implemented, reviewed, completed.
• Timestamps: YYYY-MM-DDTHH:MM:SS+HH:MM (no Z, no date-only).
• Spec uses numbered sections ## 0.–## 7.; implementation uses ## 0.–## 3..
• Open-questions gate: do not create the implementation while any spec open question is unresolved.
• Implementation ## 1. Tasks is a status table, never checkboxes. Acceptance Criteria still uses checkboxes.
• A task is completed only after verification passed and review accepted.
• Older planNNN-draft.md/planNNN.md names are accepted with warnings.

Scripts

Script	Purpose	Usage	Exit Codes
scripts/validate.sh	Run the validator via the workspace venv. Report-only.	bash scripts/validate.sh path/to/planNNN-…	0=clean 1=issues 2=usage
scripts/validate.py	Validate structure, frontmatter, status, timestamps, task table, open-questions gate. Emits JSON.	python scripts/validate.py path/to/planNNN-…	0=clean 1=issues 2=usage/config

validate.py needs python-frontmatter>=1.1.0.

References Map

• Method (behavioural rules): references/method.md
• Roles (start here): references/role-planner.md, references/role-executor.md, references/role-reviewer.md
• Canonical rules + status lifecycle: references/plan-task-spec-2026-05.md
• Templates: PROMPT_TEMPLATE.md, SPEC_TEMPLATE.md, IMPLEMENTATION_TEMPLATE.md, TASK_TEMPLATE.md, REVIEW_TEMPLATE.md, FOLLOWUP_TEMPLATE.md (all under references/)
• Validator rulebook: references/validation-rules-2026-05.md
• Trigger/non-trigger prompts: references/test-prompts-2026-05.md
• Project adoption: references/AGENTS_EXAMPLE.md

Project Process Rules

This skill is self-contained for the CatHerder method and plan/task format. Project-specific rules (identity, phase, git workflow, build/test) live in .instructions/catherder.project.instructions.md. If that file is present, read and follow it; it may add constraints but must not override this skill's method. New projects adopt the skill via references/AGENTS_EXAMPLE.md.

Scope

• In scope: plan folder layout, prompt/spec/implementation/review/follow-up format, lifecycle, frontmatter, status values, timestamps, the open-questions gate, structural validation.
• Out of scope: skill file format (see skill-file-standards), AGENTS.md standards, and project source-code conventions.