diff --git a/README.md b/README.md index d080cc3..c1e7c68 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,12 @@ Legacy `tmux-agent-state` hook commands are migrated to the neutral --- +## Shared conventions + +- [Canonical plan naming convention](docs/plan-naming-convention.md) — portable hierarchy and overflow rules for planning artifacts shared across repositories. + +--- + ## Requirements Required: diff --git a/docs/plan-naming-convention.md b/docs/plan-naming-convention.md new file mode 100644 index 0000000..9611aff --- /dev/null +++ b/docs/plan-naming-convention.md @@ -0,0 +1,47 @@ +# Canonical plan naming convention + +This document is the portable, versioned source of truth for naming planning artifacts across repositories. + +## Normative hierarchy + +```text +Plan → Session → Module → Task +``` + +Spanish repositories use the equivalent labels: + +```text +Plan → Sesión → Módulo → Tarea +``` + +- **Plan (`P`)**: a durable product or technical outcome with its own identity. +- **Session (`S.`)**: the reviewable delivery boundary normally associated with one pull request. +- **Module (`M..`)**: files or concerns that must change together inside a Session. +- **Task (`T...`)**: an atomic, verifiable action. + +Time is an estimate (`est:`), never a hierarchy boundary. A Session is not defined as “1–3 hours” or as work completed in one sitting. + +## Overflow rule + +A Session should normally fit in one pull request. If its reviewed scope exceeds one PR, either: + +1. split the scope into multiple Sessions; or +2. preserve the same Session and deliver its Modules through chained PRs. + +In the second case, every chained PR must name the parent Session and the Modules it delivers. The chain is delivery mechanics, not an additional planning level. + +## Reserved planning vocabulary + +Do not introduce `WU`, `Work Unit`, `phase`, `fase`, `slice`, `bloque`, `paquete`, `stage`, `milestone`, or `track` as planning levels. + +Valid exceptions: + +- `slice` may remain when it is an actual Control Tower domain entity or describes chained-PR mechanics; +- `work unit` may remain when it describes mechanical grouping of commits; +- schemas, IDs, fields, routes, filenames, product entities, and immutable historical evidence are not renamed merely because they contain one of these words. + +Historical documents may retain legacy vocabulary only when they are clearly marked **ARCHIVED / NON-ACTIONABLE** and do not act as current planning authority. Active documents must use the canonical hierarchy. + +## Portable references + +Repositories should link to this versioned document rather than relying on machine-specific paths such as `/home//...` or `~/.claude/...` as their only source.