@leeovery/claude-technical-workflows 2.0.23 → 2.0.25

package/commands/start-feature.md

@@ -74,7 +74,7 @@ Work from the inline context provided above.
 
 ## Notes
 
-- The specification skill will synthesize the inline context, present it for validation, and build the specification
+- The specification skill contains instructions for synthesizing the inline context, presenting it for validation, and building the specification
 - Output is a standard specification file at `docs/workflow/specification/{topic}.md`
 - From there, the user can proceed to `/workflow:start-planning` as normal
 - This path skips formal discussion documentation - use the full workflow for complex features that need debate captured

package/commands/workflow:start-discussion.md

@@ -300,40 +300,34 @@ What would you like to focus on in this session?
 
 Wait for response before proceeding.
 
-## Step 5: Invoke Discussion Skill
+## Step 5: Invoke the Skill
 
-Begin the discussion session with appropriate context based on the path taken.
+After completing the steps above, this command's purpose is fulfilled.
 
-**If from research:**
+Invoke the [technical-discussion](../skills/technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+
+**Example handoff (from research):**
 ```
 Discussion session for: {topic}
 Output: docs/workflow/discussion/{topic}.md
 
-## Research Reference
+Research reference:
 Source: docs/workflow/research/{filename}.md (lines {start}-{end})
 Summary: {the 1-2 sentence summary from Step 3A}
 
-Begin discussion using the technical-discussion skill.
+Invoke the technical-discussion skill.
 ```
 
-**If continuing or fresh:**
+**Example handoff (continuing or fresh):**
 ```
 Discussion session for: {topic}
 Source: {existing discussion | fresh}
 Output: docs/workflow/discussion/{topic}.md
 
-Begin discussion using the technical-discussion skill.
+Invoke the technical-discussion skill.
 ```
 
-**Setup:**
-- Ensure discussion directory exists: `docs/workflow/discussion/`
-- If new: Create file using the template structure
-- If continuing: Work with existing file
-- Commit frequently at natural discussion breaks
-
 ## Notes
 
 - Ask questions clearly and wait for responses before proceeding
 - Discussion captures WHAT and WHY - don't jump to specifications or implementation
-- The goal is to work through edge cases, debates, and decisions before planning
-- Commit the discussion document frequently during the session

package/commands/workflow:start-implementation.md

@@ -127,7 +127,7 @@ Proceeding with environment setup...
 
 ## Step 4: Check Environment Setup
 
-> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. The technical-implementation skill will handle execution when invoked.
+> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. Execution instructions are in the technical-implementation skill.
 
 After the user selects a plan:
 
@@ -157,31 +157,25 @@ If they choose a specific phase or task, ask them to specify which one.
 
 > **Note:** Do NOT verify that the phase or task exists. Accept the user's answer and pass it to the skill. Validation happens during the implementation phase.
 
-## Step 6: Invoke Implementation Skill
+## Step 6: Invoke the Skill
 
-Invoke the **technical-implementation** skill for this conversation.
+After completing the steps above, this command's purpose is fulfilled.
 
-Pass to the technical-implementation skill:
-- Plan: `docs/workflow/planning/{topic}.md`
-- Format: (from frontmatter)
-- Scope: (all phases | specific phase | specific task | next-available)
-- Dependencies: (all satisfied - verified in Step 3)
-- Environment setup: (completed | not needed)
+Invoke the [technical-implementation](../skills/technical-implementation/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```
 Implementation session for: {topic}
 Plan: docs/workflow/planning/{topic}.md
 Format: {format}
-Scope: All phases
+Scope: {all phases | specific phase | specific task | next-available}
 
 Dependencies: All satisfied ✓
-Environment setup: Completed (or: Not needed)
+Environment setup: {completed | not needed}
 
-Begin implementation using the technical-implementation skill.
+Invoke the technical-implementation skill.
 ```
 
 ## Notes
 
 - Ask questions clearly and wait for responses before proceeding
-- Execute environment setup before starting implementation

package/commands/workflow:start-planning.md

@@ -39,12 +39,18 @@ Scan the codebase for specifications and plans:
    - Run `ls docs/workflow/specification/` to list specification files
    - Each file is named `{topic}.md`
 
-2. **Check specification status**: For each specification file
-   - Run `head -20 docs/workflow/specification/{topic}.md` to read the frontmatter and extract the `status:` field
+2. **Check specification metadata**: For each specification file
+   - Run `head -20 docs/workflow/specification/{topic}.md` to read the frontmatter
+   - Extract the `status:` field (Building specification | Complete)
+   - Extract the `type:` field (feature | cross-cutting) - if not present, default to `feature`
    - Do NOT use bash loops - run separate `head` commands for each topic
 
-3. **Check for existing plans**: Look in `docs/workflow/planning/`
-   - Identify specifications that don't have corresponding plans
+3. **Categorize specifications**:
+   - **Feature specifications** (`type: feature` or unspecified): Candidates for planning
+   - **Cross-cutting specifications** (`type: cross-cutting`): Reference context only - do NOT offer for planning
+
+4. **Check for existing plans**: Look in `docs/workflow/planning/`
+   - Identify feature specifications that don't have corresponding plans
 
 ## Step 2: Check Prerequisites
 
@@ -60,22 +66,29 @@ Stop here and wait for the user to acknowledge.
 
 ## Step 3: Present Options to User
 
-Show what you found using a list like below:
+Show what you found, separating feature specs (planning targets) from cross-cutting specs (reference context):
 
 ```
-📂 Specifications found:
+📂 Feature Specifications (planning targets):
   ⚠️ {topic-1} - Building specification - not ready for planning
   ✅ {topic-2} - Complete - ready for planning
   ✅ {topic-3} - Complete - plan exists
 
-Which specification would you like to create a plan for?
+📚 Cross-Cutting Specifications (reference context):
+  ✅ {caching-strategy} - Complete - will inform planning
+  ✅ {rate-limiting} - Complete - will inform planning
+
+Which feature specification would you like to create a plan for?
 ```
 
-**Important:** Only completed specifications should proceed to planning. If a specification is still being built, advise the user to complete the specification phase first.
+**Important:**
+- Only completed **feature** specifications should proceed to planning
+- **Cross-cutting** specifications are NOT planning targets - they inform feature plans
+- If a specification is still being built, advise the user to complete the specification phase first
 
-**Auto-select:** If exactly one specification exists, automatically select it and proceed to Step 4. Inform the user which specification was selected. Do not ask for confirmation.
+**Auto-select:** If exactly one completed feature specification exists, automatically select it and proceed to Step 4. Inform the user which specification was selected. Do not ask for confirmation.
 
-Ask: **Which specification would you like to plan?**
+Ask: **Which feature specification would you like to plan?**
 
 ## Step 4: Choose Output Destination
 
@@ -88,24 +101,46 @@ Load **[output-formats.md](../skills/technical-planning/references/output-format
 - Any additional context or priorities to consider?
 - Any constraints since the specification was completed?
 
-## Step 6: Invoke Planning Skill
+## Step 5b: Surface Cross-Cutting Context
+
+If any **completed cross-cutting specifications** exist, surface them as reference context for planning:
+
+1. **List applicable cross-cutting specs**:
+   - Read each cross-cutting specification
+   - Identify which ones are relevant to the feature being planned
+   - Relevance is determined by topic overlap (e.g., caching strategy applies if the feature involves data retrieval or API calls)
+
+2. **Summarize for handoff**:
+   ```
+   Cross-cutting specifications to reference:
+   - caching-strategy.md: [brief summary of key decisions]
+   - rate-limiting.md: [brief summary of key decisions]
+   ```
+
+These specifications contain validated architectural decisions that should inform the plan. The planning skill will incorporate these as a "Cross-Cutting References" section in the plan.
+
+**If no cross-cutting specifications exist**: Skip this step.
+
+## Step 6: Invoke the Skill
+
+After completing the steps above, this command's purpose is fulfilled.
 
-Pass to the technical-planning skill with:
-- Specification path
-- Output format chosen
-- Additional context gathered
+Invoke the [technical-planning](../skills/technical-planning/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```
 Planning session for: {topic}
 Specification: docs/workflow/specification/{topic}.md
 Output format: {format}
+Additional context: {summary of user's answers from Step 5}
+Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
 
-Begin planning using the technical-planning skill.
+Invoke the technical-planning skill.
 ```
 
 ## Notes
 
 - Ask questions clearly and wait for responses before proceeding
-- The specification is the sole source of truth for planning - do not reference discussions
-- Commit the plan files when complete
+- The feature specification is the primary source of truth for planning
+- Cross-cutting specifications provide supplementary context for architectural decisions
+- Do not reference discussions - only specifications

package/commands/workflow:start-research.md

@@ -21,7 +21,9 @@ This is **Phase 1** of the six-phase workflow:
 
 ---
 
-Then ask these questions to kickstart the exploration:
+## Instructions
+
+Ask these questions to gather context:
 
 1. **What's on your mind?**
    - What idea or topic do you want to explore?
@@ -35,4 +37,10 @@ Then ask these questions to kickstart the exploration:
    - Technical feasibility? Market landscape? Business model?
    - Or just talk it through and see where it goes?
 
-Ask these questions clearly and wait for responses before proceeding. The skill handles everything else.
+Ask these questions clearly and wait for responses before proceeding.
+
+## Invoke the Skill
+
+After completing the steps above, this command's purpose is fulfilled.
+
+Invoke the [technical-research](../skills/technical-research/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.

package/commands/workflow:start-review.md

@@ -86,13 +86,11 @@ Check if a specification exists:
 2. **If exists**: Note the path for context
 3. **If missing**: Proceed without - the plan is the primary review artifact
 
-## Step 6: Invoke Review Skill
+## Step 6: Invoke the Skill
 
-Pass to the technical-review skill:
-- Plan: `docs/workflow/planning/{topic}.md`
-- Format: (from frontmatter)
-- Specification: `docs/workflow/specification/{topic}.md` (if exists)
-- Implementation scope: (files/directories to review)
+After completing the steps above, this command's purpose is fulfilled.
+
+Invoke the [technical-review](../skills/technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```
@@ -102,11 +100,10 @@ Format: {format}
 Specification: docs/workflow/specification/{topic}.md (or: Not available)
 Scope: {implementation scope}
 
-Begin review using the technical-review skill.
+Invoke the technical-review skill.
 ```
 
 ## Notes
 
 - Ask questions clearly and wait for responses before proceeding
 - Review produces feedback (approve, request changes, or comments) - it does NOT fix code
-- Verify ALL plan tasks, don't sample

package/commands/workflow:start-specification.md

@@ -82,25 +82,23 @@ Ask:
 - Any constraints or changes since the discussion concluded?
 - Are there any existing partial plans or related documentation I should review?
 
-## Step 5: Invoke Specification Skill
+## Step 5: Invoke the Skill
 
-Pass to the technical-specification skill:
-- Source: `docs/workflow/discussion/{topic}.md`
-- Output: `docs/workflow/specification/{topic}.md`
-- Additional context gathered
+After completing the steps above, this command's purpose is fulfilled.
+
+Invoke the [technical-specification](../skills/technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 
 **Example handoff:**
 ```
 Specification session for: {topic}
 Source: docs/workflow/discussion/{topic}.md
 Output: docs/workflow/specification/{topic}.md
+Additional context: {summary of user's answers from Step 4}
 
-Begin specification using the technical-specification skill.
-Reference: specification-guide.md
+Invoke the technical-specification skill.
 ```
 
 ## Notes
 
 - Ask questions clearly and wait for responses before proceeding
 - The specification phase validates and refines discussion content into a standalone document
-- Commit the specification files frequently during the session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.23",
+  "version": "2.0.25",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/technical-discussion/references/meeting-assistant.md

@@ -21,8 +21,8 @@ You're an AI - do both. Engage fully while documenting. Don't dumb down.
 
 1. **Discuss** - Participate
 2. **Document** - Capture
-3. **Plan** - ❌ Not this skill's job
-4. **Implement** - ❌ Not this skill's job
+3. **Plan** - ❌ Not covered here
+4. **Implement** - ❌ Not covered here
 
 Stop after documentation. No plans, implementation steps, or code.
 

package/skills/technical-implementation/SKILL.md

@@ -115,7 +115,7 @@ Follow project-specific coding skills in `.claude/skills/` for:
 - Architecture conventions
 - Testing conventions
 
-This skill provides the implementation **process**. Project skills provide the **style**.
+This skill contains the implementation **process**. Project skills contain the **style**.
 
 ## Handling Problems
 

package/skills/technical-planning/SKILL.md

@@ -22,9 +22,20 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 - **Specification content** (required) - The validated decisions and requirements to plan from
 - **Topic name** (optional) - Will derive from specification if not provided
 - **Output format preference** (optional) - Will ask if not specified
+- **Cross-cutting references** (optional) - List of cross-cutting specifications that inform this plan
 
 **If missing:** Will ask user for specification location or content.
 
+### Cross-Cutting References
+
+If cross-cutting specifications are provided (e.g., caching strategy, rate limiting policy), incorporate their decisions into the plan:
+
+1. **Include a "Cross-Cutting References" section** in the plan linking to these specifications
+2. **Apply their patterns** when designing phases and tasks (e.g., if caching strategy says "cache API responses for 5 minutes", include that in relevant tasks)
+3. **Note where patterns apply** - when a task implements a cross-cutting pattern, reference it
+
+Cross-cutting specifications are architectural decisions that inform HOW features are built. They don't have their own implementation plans - instead, their patterns are applied within feature plans.
+
 ## Source Material
 
 **The specification is your sole input.** Everything you need should be in the specification - do not request details from prior source material. If information is missing, ask for clarification on the specification itself.

package/skills/technical-planning/references/output-backlog-md.md

@@ -88,6 +88,17 @@ Tasks are organized with labels/priorities:
 
 [Summary of key decisions from specification]
 
+## Cross-Cutting References
+
+Architectural decisions from cross-cutting specifications that inform this plan:
+
+| Specification | Key Decisions | Applies To |
+|---------------|---------------|------------|
+| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+
+*Remove this section if no cross-cutting specifications apply.*
+
 ## External Dependencies
 
 [Dependencies on other topics - copy from specification's Dependencies section]

package/skills/technical-planning/references/output-beads.md

@@ -269,6 +269,17 @@ This plan is managed via Beads. Tasks are stored in `.beads/` and tracked as a d
 
 [Summary of key decisions from specification]
 
+## Cross-Cutting References
+
+Architectural decisions from cross-cutting specifications that inform this plan:
+
+| Specification | Key Decisions | Applies To |
+|---------------|---------------|------------|
+| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+
+*Remove this section if no cross-cutting specifications apply.*
+
 ## Phase Overview
 
 | Phase | Goal | Epic ID |

package/skills/technical-planning/references/output-linear.md

@@ -179,6 +179,17 @@ This plan is managed in Linear. The source of truth for tasks and progress is th
 
 [Summary of key decisions from specification - for quick reference]
 
+## Cross-Cutting References
+
+Architectural decisions from cross-cutting specifications that inform this plan:
+
+| Specification | Key Decisions | Applies To |
+|---------------|---------------|------------|
+| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
+| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
+
+*Remove this section if no cross-cutting specifications apply.*
+
 ## External Dependencies
 
 [Dependencies on other topics - copy from specification's Dependencies section]

package/skills/technical-planning/references/output-local-markdown.md

@@ -54,6 +54,17 @@ format: local-markdown
 - Decision 1: Rationale
 - Decision 2: Rationale
 
+## Cross-Cutting References
+
+Architectural decisions from cross-cutting specifications that inform this plan:
+
+| Specification | Key Decisions | Applies To |
+|---------------|---------------|------------|
+| [Caching Strategy](../specification/caching-strategy.md) | Cache API responses for 5 min; use Redis | Tasks involving API calls |
+| [Rate Limiting](../specification/rate-limiting.md) | 100 req/min per user; sliding window | User-facing endpoints |
+
+*Remove this section if no cross-cutting specifications apply.*
+
 ## Architecture
 
 - Components

package/skills/technical-specification/SKILL.md

@@ -36,6 +36,30 @@ Either way: Transform unvalidated reference material into a specification that's
 
 **When complete**: User signs off on the specification.
 
+## CRITICAL: You Do NOT Create or Update the Specification Autonomously
+
+**This is a collaborative, interactive process. You MUST wait for explicit user approval before writing ANYTHING to the specification file.**
+
+❌ **NEVER:**
+- Create the specification document and then ask the user to review it
+- Write multiple sections and present them for review afterward
+- Assume silence or moving on means approval
+- Make "minor" amendments without explicit approval
+- Batch up content and log it all at once
+
+✅ **ALWAYS:**
+- Present ONE topic at a time
+- **STOP and WAIT** for the user to explicitly approve before writing
+- Treat each write operation as requiring its own explicit approval
+
+**What counts as approval:** "Log it" (the standard choice you present) or equivalent: "Yes", "Approved", "Add it", "That's good".
+
+**What does NOT count as approval:** Silence, you presenting choices, the user asking a follow-up question, the user saying "What's next?", or any response that isn't explicit confirmation.
+
+If you are uncertain whether the user approved, **ASK**: "Would you like me to log it, or do you want to adjust something?"
+
+---
+
 ## What You Do
 
 1. **Extract exhaustively**: For each topic, re-scan ALL source material. Search for keywords and related terms. Information is often scattered - collect it all before synthesizing. Include only what we're building (not discarded alternatives).
@@ -46,18 +70,32 @@ Either way: Transform unvalidated reference material into a specification that's
 
 4. **Present**: Synthesize and present content to the user in the format it would appear in the specification.
 
-5. **Log**: Only when approved, write content verbatim to the specification.
+5. **STOP AND WAIT**: Do not proceed until the user explicitly approves. This is not optional.
+
+6. **Log**: Only after explicit approval, write content verbatim to the specification.
 
-6. **Final review**: After all topics and dependencies are documented, perform a comprehensive review of ALL source material against the specification. Flag any potentially missed content to the user - but only from the sources, never fabricated. User confirms before any additions.
+7. **Final review**: After all topics and dependencies are documented, perform a comprehensive review of ALL source material against the specification. Flag any potentially missed content to the user - but only from the sources, never fabricated. User confirms before any additions.
 
 The specification is the **golden document** - planning uses only this. If information doesn't make it into the specification, it won't be built. No references back to source material.
 
 ## Critical Rules
 
-**Present before logging**: Never write content to the specification until the user has seen and approved it.
+**STOP AND WAIT FOR APPROVAL**: You MUST NOT write to the specification until the user has explicitly approved. Presenting content is NOT approval. Presenting choices is NOT approval. You must receive explicit confirmation (e.g., "Log it") before ANY write operation. If uncertain, ASK.
 
 **Log verbatim**: When approved, write exactly what was presented - no silent modifications.
 
 **Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
 
 **Trust nothing without validation**: Synthesize and present, but never assume source material is correct.
+
+---
+
+## Self-Check: Are You Following the Rules?
+
+Before ANY write operation to the specification, ask yourself:
+
+1. **Did I present this specific content to the user?** If no → STOP. Present it first.
+2. **Did the user explicitly approve it?** (Not "did I ask if it's good" - did THEY say yes?) If no → STOP. Wait for approval.
+3. **Am I writing exactly what was approved?** If adding/changing anything → STOP. Present the changes first.
+
+> **If you have written to the specification file without going through steps 1-2-3 above, you have violated the workflow.** The user must approve every piece of content before it's logged. There are no exceptions.

package/skills/technical-specification/references/specification-guide.md

@@ -29,6 +29,16 @@ Before starting any topic, identify ALL available reference material:
 
 **Treat all source material as untrusted input**, regardless of where it came from. Your job is to synthesize and present - the user validates.
 
+## CRITICAL: This is an Interactive Process
+
+**You MUST NOT create or update the specification without explicit user approval for each piece of content.**
+
+This is a collaborative dialogue, not an autonomous task. The user validates every piece before it's logged.
+
+> **CHECKPOINT**: If you are about to write to the specification file and haven't received explicit approval (e.g., "Log it") for this specific content, **STOP**. You are violating the workflow. Go back and present the choices first.
+
+---
+
 ## The Workflow
 
 Work through the specification **topic by topic**:
@@ -62,11 +72,19 @@ For each topic or subtopic, perform exhaustive extraction:
 ### 2. Synthesize and Present
 Present your understanding to the user **in the format it would appear in the specification**:
 
-> "Here's what I understand about [topic] based on the reference material. This is how I'd write it into the specification:
+> "Here's what I understand about [topic] based on the reference material. This is exactly what I'll write into the specification:
 >
 > [content as it would appear]
->
-> Does this capture it? Anything to adjust, remove, or add?"
+
+Then present two explicit choices:
+
+> **To proceed, choose one:**
+> - **"Log it"** - I'll add the above to the specification **verbatim** (exactly as shown, no modifications)
+> - **"Adjust"** - Tell me which part to change and what you want it to say instead
+
+**Do not paraphrase these choices.** Present them exactly as written so users always know what to expect.
+
+> **CHECKPOINT**: After presenting, you MUST STOP and wait for the user's response. Do NOT proceed to logging. Do NOT present the next topic. WAIT.
 
 ### 3. Discuss and Refine
 Work through the content together:
@@ -78,22 +96,46 @@ Work through the content together:
 
 This is a **human-level conversation**, not form-filling. The user brings context from across the project that may not be in the reference material - decisions from other topics, implications from later work, or knowledge that can't all fit in context.
 
-### 4. Log When Approved
-Only when the user approves ("yes, log it", "that's good", etc.) do you write it to the specification - **verbatim** as presented and approved.
+### 4. STOP - Wait for Explicit Approval
+
+**DO NOT PROCEED TO LOGGING WITHOUT EXPLICIT USER APPROVAL.**
+
+**What counts as approval:**
+- **"Log it"** - the standard confirmation you present as a choice
+- Or equivalent explicit confirmation: "Yes", "Approved", "Add it", "That's good"
+
+**What does NOT count as approval:**
+- Silence
+- You presenting choices (that's you asking, not them approving)
+- The user asking a follow-up question
+- The user saying "What's next?" or "Continue"
+- The user making a minor comment without explicit approval
+- ANY response that isn't explicit confirmation
 
-### 5. Repeat
+**If you are uncertain, ASK:** "Would you like me to log it, or do you want to adjust something?"
+
+> **CHECKPOINT**: If you are about to write to the specification and the user's last message was not explicit approval, **STOP**. You are violating the workflow. Present the choices again.
+
+### 5. Log When Approved
+Only after receiving explicit approval do you write to the specification - **verbatim** as presented and approved. No silent modifications.
+
+### 6. Repeat
 Move to the next topic.
 
 ## Context Resurfacing
 
 When you discover information that affects **already-logged topics**, resurface them. Even mid-discussion - interrupt, flag what you found, and discuss whether it changes anything.
 
-If it does: summarize what's changing in the chat, then re-present the full updated topic. The summary is for discussion only - the specification just gets the clean replacement. Standard workflow applies: user approves before you update.
+If it does: summarize what's changing in the chat, then re-present the full updated topic. The summary is for discussion only - the specification just gets the clean replacement. **Standard workflow applies: user approves before you update.**
+
+> **CHECKPOINT**: Even when resurfacing content, you MUST NOT update the specification until the user explicitly approves the change. Present the updated version, wait for approval, then update.
 
 This is encouraged. Better to resurface and confirm "already covered" than let something slip past.
 
 ## The Specification Document
 
+> **CHECKPOINT**: You should NOT be creating or writing to this file unless you have explicit user approval for specific content. If you're about to create this file with content you haven't presented and had approved, **STOP**. That violates the workflow.
+
 Create `docs/workflow/specification/{topic}.md`
 
 This is a single file per topic. Structure is **flexible** - organize around phases and subject matter, not rigid sections. This is a working document.
@@ -104,6 +146,7 @@ Suggested skeleton:
 # Specification: [Topic Name]
 
 **Status**: Building specification
+**Type**: feature | cross-cutting
 **Last Updated**: YYYY-MM-DD *(use today's actual date)*
 
 ---
@@ -119,11 +162,80 @@ Suggested skeleton:
 [Optional - capture in-progress discussion if needed]
 ```
 
+## Specification Types
+
+The `Type` field distinguishes between specifications that result in standalone implementation work versus those that inform how other work is done.
+
+### Feature Specifications (`type: feature`)
+
+Feature specifications describe something to **build** - a concrete piece of functionality with its own implementation plan.
+
+**Examples:**
+- User authentication system
+- Order processing pipeline
+- Notification service
+- Dashboard analytics
+
+**Characteristics:**
+- Results in a dedicated implementation plan
+- Has concrete deliverables (code, APIs, UI)
+- Can be planned with phases, tasks, and acceptance criteria
+- Progress is measurable ("the feature is done")
+
+**This is the default type.** If not specified, assume `feature`.
+
+### Cross-Cutting Specifications (`type: cross-cutting`)
+
+Cross-cutting specifications describe **patterns, policies, or architectural decisions** that inform how features are built. They don't result in standalone implementation - instead, they're referenced by feature specifications and plans.
+
+**Examples:**
+- Caching strategy
+- Rate limiting policy
+- Error handling conventions
+- Logging and observability standards
+- API versioning approach
+- Security patterns
+
+**Characteristics:**
+- Does NOT result in a dedicated implementation plan
+- Defines "how to do things" rather than "what to build"
+- Referenced by multiple feature specifications
+- Implementation happens within features that apply these patterns
+- No standalone "done" state - the patterns are applied across features
+
+### Why This Matters
+
+Cross-cutting specifications go through the same Research → Discussion → Specification phases. The decisions are just as important to validate and document. The difference is what happens after:
+
+- **Feature specs** → Planning → Implementation → Review
+- **Cross-cutting specs** → Referenced by feature plans → Applied during feature implementation
+
+When planning a feature, the planning process surfaces relevant cross-cutting specifications as context. This ensures that a "user authentication" plan incorporates the validated caching strategy and error handling conventions.
+
+### Determining the Type
+
+Ask: **"Is there a standalone thing to build, or does this inform how we build other things?"**
+
+| Question | Feature | Cross-Cutting |
+|----------|---------|---------------|
+| Can you demo it when done? | Yes - "here's the login page" | No - it's invisible infrastructure |
+| Does it have its own UI/API/data? | Yes | No - lives within other features |
+| Can you plan phases and tasks for it? | Yes | Tasks would be "apply X to feature Y" |
+| Is it used by one feature or many? | Usually one | By definition, multiple |
+
+**Edge cases:**
+- A "caching service" that provides shared caching infrastructure → **Feature** (you're building something)
+- "How we use caching across the app" → **Cross-cutting** (policy/pattern)
+- Authentication system → **Feature**
+- Authentication patterns and security requirements → **Cross-cutting**
+
 ## Critical Rules
 
-**Exhaustive extraction is non-negotiable**: Before presenting any topic, re-scan source material. Search for keywords. Collect scattered information. The specification is the golden document - planning uses only this. If you miss something, it doesn't get built.
+**EXPLICIT APPROVAL REQUIRED FOR EVERY WRITE**: You MUST NOT write to the specification until the user has explicitly approved. "Presenting" is not approval. "Asking a question" is not approval. You need explicit confirmation. If uncertain, ASK. This rule is non-negotiable.
 
-**Present before logging**: Never write content to the specification until the user has seen and approved it.
+> **CHECKPOINT**: Before ANY write operation, ask yourself: "Did the user explicitly approve this specific content?" If the answer is no or uncertain, STOP and ask.
+
+**Exhaustive extraction is non-negotiable**: Before presenting any topic, re-scan source material. Search for keywords. Collect scattered information. The specification is the golden document - planning uses only this. If you miss something, it doesn't get built.
 
 **Log verbatim**: When approved, write exactly what was presented - no silent modifications.
 
@@ -232,7 +344,11 @@ After documenting dependencies, perform a **final comprehensive review** of the
    - Error handling, validation rules, or boundary conditions
    - Integration points or data flows mentioned but not elaborated
 
-4. **Flag what you find** - When you discover potentially missed content, present it to the user. There are two cases:
+4. **Flag what you find** - When you discover potentially missed content, present it to the user. **Do NOT add it to the specification without explicit approval.**
+
+   > **CHECKPOINT**: If you found missed content and are about to add it to the specification without presenting it first and receiving explicit approval, **STOP**. Every addition requires the present → approve → log cycle, even during final review.
+
+   There are two cases:
 
    **Enhancing an existing topic** - Details that belong in an already-documented section:
 
@@ -296,7 +412,74 @@ When you've:
 
 ## Completion
 
+### Step 1: Determine Specification Type
+
+Before asking for sign-off, assess whether this is a **feature** or **cross-cutting** specification:
+
+**Feature specification** - Something to build:
+- Has concrete deliverables (code, APIs, UI)
+- Can be planned with phases, tasks, acceptance criteria
+- Results in a standalone implementation
+
+**Cross-cutting specification** - Patterns/policies that inform other work:
+- Defines "how to do things" rather than "what to build"
+- Will be referenced by multiple feature specifications
+- Implementation happens within features that apply these patterns
+
+Present your assessment to the user:
+
+> "This specification appears to be a **[feature/cross-cutting]** specification.
+>
+> [Brief rationale - e.g., "It defines a caching strategy that will inform how multiple features handle data retrieval, rather than being a standalone piece of functionality to build."]
+>
+> - **Feature specs** proceed to planning and implementation
+> - **Cross-cutting specs** are referenced by feature plans but don't have their own implementation plan
+>
+> Does this assessment seem correct?"
+
+Wait for user confirmation before proceeding.
+
+### Step 2: Sign-Off
+
+Once the type is confirmed, ask for final sign-off:
+
+> "The specification is ready for sign-off:
+> - **Type**: [feature/cross-cutting]
+> - **Status**: Complete
+>
+> [If feature]: This specification can proceed to planning
+> [If cross-cutting]: This specification will be surfaced as reference context when planning features
+>
+> Ready to mark as complete?"
+
+### Step 3: Update Frontmatter
+
+After user confirms, update the specification frontmatter:
+
+```markdown
+# Specification: [Topic Name]
+
+**Status**: Complete
+**Type**: [feature/cross-cutting]
+**Last Updated**: YYYY-MM-DD
+```
+
 Specification is complete when:
 - All topics/phases have validated content
+- Type has been determined and confirmed
 - User confirms the specification is complete
 - No blocking gaps remain
+
+---
+
+## Self-Check: Have You Followed the Rules?
+
+Before ANY write operation to the specification file, verify:
+
+| Question | If No... |
+|----------|----------|
+| Did I present this specific content to the user? | **STOP**. Present it first. |
+| Did the user explicitly approve? (e.g., "Log it") | **STOP**. Wait for approval or ask. |
+| Am I writing exactly what was approved, with no additions? | **STOP**. Present any changes first. |
+
+> **FINAL CHECK**: If you have written to the specification file and cannot answer "yes" to all three questions above for that content, you have violated the workflow. Every piece of content requires explicit user approval before logging.