@leeovery/claude-technical-workflows 2.0.24 → 2.0.25

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,6 +101,26 @@ 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 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.
@@ -100,6 +133,7 @@ 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"}
 
 Invoke the technical-planning skill.
 ```
@@ -107,4 +141,6 @@ 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
+- 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/package.json

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

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/references/specification-guide.md

@@ -146,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)*
 
 ---
@@ -161,6 +162,73 @@ 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
 
 **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.
@@ -344,8 +412,61 @@ 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