From bb28cfa331d3cba9ae9f265f7c448b5bd6b4fa6c Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 29 May 2026 18:44:30 -0500 Subject: feat(workflows): add -spec.org precondition to spec-review and spec-response Both workflows now check that the file under review (or the spec being responded to) ends with -spec.org before proceeding. If it does not, the workflow stops and surfaces the mismatch with the rename suggestion. The suffix is the identifier per Craig's spec-naming convention: every design, decision, or planning document under a project's docs/ directory ends with -spec.org. The .org extension alone is not enough because docs/ holds non-spec org files too (tutorials, frozen inventories, reference material). spec-review.org gained a top-level Precondition section between When to Use and Approach. spec-response.org gained the same Precondition section in the parallel position, with a note that the review-file convention -review.org means a misnamed spec produces a mis-pointed review file too. Inbox source: 2026-05-28-0858-from-home-spec-naming-convention-apply-to-spec.org. Home renamed two docs to the new convention and asked rulesets to update the template workflows so the next startup rsync in every project picks up the guard. --- claude-templates/.ai/workflows/spec-response.org | 16 ++++++++++++++++ claude-templates/.ai/workflows/spec-review.org | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) (limited to 'claude-templates') diff --git a/claude-templates/.ai/workflows/spec-response.org b/claude-templates/.ai/workflows/spec-response.org index 99619cc..c659a0e 100644 --- a/claude-templates/.ai/workflows/spec-response.org +++ b/claude-templates/.ai/workflows/spec-response.org @@ -50,6 +50,22 @@ Trigger when: Not for: drafting a spec from scratch (that's a design conversation), or informal inline comments (handle those conversationally / via the cj-comment flow). +* Precondition: spec filename + +Before Phase 0, verify the spec being responded to ends with =-spec.org=. Every design, decision, or planning document under a project's =docs/= directory carries that suffix as its identifier. The =.org= extension alone is not enough because =docs/= holds non-spec org files too. + +If the spec does not end with =-spec.org=, stop immediately and surface the mismatch: + +#+begin_example +The spec does not end with -spec.org. Either the wrong file was named, or +the file should be renamed first. Spec workflows require the -spec.org suffix as a +guard against pointing the workflow at tutorial, inventory, or setup docs. +#+end_example + +The review file the response consumes follows the convention =-review.org=, so a misnamed spec produces a mis-pointed review file too. Fix the spec name first. + +The user resolves the mismatch and re-invokes the workflow. Do not proceed with the response against a misnamed spec. + * Approach: How We Work Together ** Phase 0: Orient diff --git a/claude-templates/.ai/workflows/spec-review.org b/claude-templates/.ai/workflows/spec-review.org index b4ca437..159202e 100644 --- a/claude-templates/.ai/workflows/spec-review.org +++ b/claude-templates/.ai/workflows/spec-review.org @@ -44,6 +44,22 @@ Trigger when: Run it *early* — design review exists to catch viability problems and costly mistakes before implementation, not after. +* Precondition: spec filename + +Before Phase 1, verify the file under review ends with =-spec.org=. Every design, decision, or planning document under a project's =docs/= directory carries that suffix as its identifier. The =.org= extension alone is not enough because =docs/= holds non-spec org files too (tutorials, frozen inventories, reference material). + +If the file does not end with =-spec.org=, stop immediately and surface the mismatch: + +#+begin_example +The file does not end with -spec.org. Either the wrong file was named, or +the file should be renamed first. Spec workflows require the -spec.org suffix as a +guard against pointing the workflow at tutorial, inventory, or setup docs. +#+end_example + +The user resolves the mismatch (rename the file, or point at a different one) and re-invokes the workflow. Do not proceed with the review against a misnamed file. + +Anywhere the rest of this workflow refers to "the spec," "the spec file," or "the file under review," the path is the =-spec.org= file confirmed here. + * Approach: How We Work Together ** Phase 1: First-pass readiness gate -- cgit v1.2.3