Skip to main content

Specification and planning artifacts policy

Purpose: Avoid treating IDE-local plan directories as the system of record. Make specifications and test/planning intent discoverable in repository documentation with a clear hierarchy and promotion workflow.

Problem: Cursor (and similar) may store plans under a single user-local folder (e.g. ~/.cursor/plans/). That is not in git, not indexed with the repo, and does not scale for architecture visibility or audit.

1. Source-of-truth ladder (highest wins on conflict)​

PriorityArtifactRole
1Kanban task document (docs/project-management/kanban/.../T*.md or embedded task section)Authoritative for task scope, acceptance criteria, deliverables, status, and version anchor when complete.
2Linked FR / BR / UXRAuthoritative for intake intent, acceptance at feature level, and explicit follow-up rows (e.g. FU-1..n).
3ICW package under docs/implementation-cycles/Durable specification, test design, and implementation plan when ICW (or equivalent) is used. Must be linked from the task.
4Architecture / ADR / policy docsCross-cutting rules and decisions (not a substitute for task-level acceptance).
5Automated testsExecutable spec: failing/passing behavior. Names and docstrings should reference task or FR where practical.

Rule: If a Cursor plan and a task doc disagree, update the task doc (and FR if needed), then adjust code/tests. The plan is not the owner of truth.

2. Artifact classes​

Durable (repository)​

  • Must live under docs/ (or other committed paths defined by project policy).

  • ICW canonical output directory is docs/implementation-cycles/ (see packages/frameworks/workflow mgt/workflows/implementation-cycle-workflow/icw-workflow.yaml → output_dir).

  • Naming convention (recommended for new work):

    ICW-E{epic}S{story}T{task}-specification.md
    ICW-E{epic}S{story}T{task}-test-design.md
    ICW-E{epic}S{story}T{task}-implementation-plan.md

    Multi-task batches may use a range suffix already in use in this repo (e.g. ICW-E7S06-T10-T16-*) when one planning package intentionally covers several tasks.

Transient (IDE-only)​

  • Files created only in ~/.cursor/plans/ (or other editor-local stores).
  • Use for: scratchpad, intermediate brainstorming, UI-generated plans.
  • Do not use for: the only copy of acceptance criteria, test design, or implementation steps after work is funded by a task.

3. Workflow: planning → implementation handoff​

  1. Ensure a task exists (Kanban governance: substantive work is task-driven). Note the task id placeholder E{epic}:S{story}:T{task} in the plan title or body.
  2. Draft in Cursor Plan (optional): acceptable for speed.
  3. Promote before or as implementation starts:
    • Copy executable spec statements (IDs, acceptance bullets) into the task doc sections Scope, Acceptance Criteria, Deliverable as appropriate; and/or
    • Create or update the ICW trio under docs/implementation-cycles/ using the naming convention above.
  4. Link bidirectionally:
    • In the task doc, add a Planning artifacts (or References) subsection listing paths to the ICW files (or other docs/ plans).
    • In each ICW file, put the task id and link to the task markdown at the top.
  5. Discard or ignore the IDE-only plan for governance after promotion (do not cite it as SoT in FR/task text).

Agents: When the user says “implement the plan,” read the task doc and linked docs/ files first; treat ~/.cursor/plans/ as optional context if the user attaches it.

4. Discovery and inventory (what we’ve got)​

  • Do not rely on listing a monolithic local plans directory.
  • Do discover specs by:
    • Opening the task from the Story checklist / FR Implementing Task link.
    • Listing or searching docs/implementation-cycles/ICW-*.md (by task id in the filename).
    • Reading FR-067-style triage tables and maintenance notes where applicable.

Optional hygiene (UKW / maintainers): If a story marks ICW as required and tasks lack Planning artifacts links while docs/implementation-cycles/ contains matching ICW-* files, add the links (same session as other kanban updates; release via RW per project rules).

5. Non-goals​

  • This policy does not require every small fix to have a full ICW trio; minimum is task doc + tests where that is the team norm.
  • Replacing Cursor Plans UI is not required; controlling where truth lives is.

6. References​

  • Intake / traceability: FR-075; implementing task E5:S01:T75
  • Kanban task template: packages/frameworks/kanban/templates/TASK_TEMPLATE.md
  • ICW workflow config: packages/frameworks/workflow mgt/workflows/implementation-cycle-workflow/icw-workflow.yaml
  • ICW responsibilities (durable artifacts): packages/frameworks/workflow mgt/workflows/implementation-cycle-workflow/README.md (section Durable planning artifacts)
  • Implementation cycles folder guide: docs/implementation-cycles/README.md
  • Kanban governance: packages/frameworks/kanban/policies/kanban-governance-policy.md (task-driven work)