specweave 0.3.12 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "0.3.12",
+  "version": "0.3.13",
   "description": "Replace vibe coding with spec-driven development. Smart workflow: /specweave inc auto-closes previous, /specweave build auto-resumes, /specweave progress shows status. PM-led planning, 10 agents, 35+ skills. spec-weave.com",
   "type": "module",
   "main": "dist/index.js",

package/src/skills/increment-planner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: increment-planner
-description: Creates comprehensive implementation plans for SpecWeave increments (aka features - both terms are interchangeable). This skill should be used when planning new increments/features, creating specifications, or organizing implementation work. Activates for: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature.
+description: Creates comprehensive implementation plans for SpecWeave increments (aka features - both terms are interchangeable). This skill should be used when planning new increments/features, creating specifications, or organizing implementation work. Activates for: increment planning, feature planning, implementation plan, create increment, create feature, plan increment, plan feature, organize work, break down increment, break down feature, new product, build project, MVP, SaaS, app development, product description, tech stack planning, feature list.
 ---
 
 # Increment Planner Skill

package/src/skills/project-kickstarter/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: project-kickstarter
+description: Proactively detects product/project descriptions and guides users through SpecWeave increment planning. Activates when user provides product name, features, tech stack, timeline, or problem description. Keywords: project, product, SaaS, app, MVP, build, new project, features, tech stack, core functionality, monetization, timeline, I want to build, let's build, quick build, core features.
+---
+
+# Project Kickstarter - Generic Pattern-Based Auto-Detection
+
+## Purpose
+
+The project-kickstarter skill is a **generic, pattern-based detection system** that:
+- ✅ Works for ANY product/project (not hardcoded for specific products)
+- ✅ Detects structural patterns (features list, tech stack, timeline, etc.)
+- ✅ Integrates with specweave-detector to check SpecWeave context
+- ✅ Routes to appropriate SpecWeave workflow automatically
+
+**Not product-specific!** This skill recognizes the STRUCTURE of product descriptions, not specific products.
+
+## When to Activate
+
+**CRITICAL CONTEXT**: When working in a **SpecWeave-initialized project** (`.specweave/` directory exists), ANY product/feature description MUST be interpreted as "create an increment for this."
+
+This skill activates when:
+
+1. **User is in SpecWeave project** (.specweave/ directory exists) AND
+2. **Message contains 3+ of these signals**:
+   - **Project Name/Description**: "Project: RosterSync", "I want to build X"
+   - **Features List**: Bullet points or numbered list of features (3+ items)
+   - **Tech Stack**: Languages, frameworks, databases, platforms mentioned
+   - **Timeline/Scope**: "MVP", "2 weeks", "Phase 1", "Quick build"
+   - **Problem Statement**: "For teams...", "Helps users...", "Solves..."
+   - **Business Model**: "Freemium", "$X/mo", "B2B", "Consumer"
+
+**Key Insight**: If user is in a SpecWeave folder and describes a product, they're implicitly asking "create a SpecWeave increment for this."
+
+## Pattern Recognition
+
+**SpecWeave Context Multiplier**: When `.specweave/` exists, apply +2 confidence boost to signal count.
+
+### High Confidence (5-6 signals OR 3-4 signals + SpecWeave context) → Auto-Route
+
+**Example 1: In SpecWeave project**
+```
+Working directory: /project-with-specweave/ (.specweave/ exists)
+
+User: "Project: RosterSync - Team scheduling SaaS
+Core features: roster management, availability calendar, scheduling
+Tech stack: .NET 8, Next.js 14+, PostgreSQL
+MVP time: 2-3 weeks
+Monetization: Freemium ($10/mo)"
+
+Detected signals: ✅ Name, ✅ Features, ✅ Tech, ✅ Timeline, ✅ Business (5 signals)
+SpecWeave context: ✅ +2 bonus
+Adjusted confidence: 5 + 2 = 7/6 = 100% → AUTO-ROUTE to increment planning
+```
+
+**Example 2: In SpecWeave project (fewer signals still triggers)**
+```
+Working directory: /project-with-specweave/ (.specweave/ exists)
+
+User: "I want to build a task manager with React and Node.js"
+
+Detected signals: ✅ Intent ("build"), ✅ Type ("task manager"), ✅ Tech stack (3 signals)
+SpecWeave context: ✅ +2 bonus
+Adjusted confidence: 3 + 2 = 5/6 = 83% → AUTO-ROUTE to increment planning
+```
+
+### Medium Confidence (3-4 signals, no SpecWeave context) → Clarify Then Route
+```
+Working directory: /regular-project/ (no .specweave/)
+
+User: "I want to build a task manager with React and Node.js"
+
+Detected signals: ✅ Intent ("build"), ✅ Type ("task manager"), ✅ Tech stack
+SpecWeave context: ❌ No bonus
+Confidence: 3/6 = 50% → ASK 1-2 clarifying questions, THEN route
+```
+
+### Low Confidence (<3 signals) → Don't Activate
+```
+User: "What do you think about using PostgreSQL?"
+
+Detected signals: ✅ Tech mention
+Confidence: 1/6 = 17% → Regular conversation (not product planning)
+```
+
+## Workflow
+
+### Step 1: Detect Pattern
+Scan user message for the 6 signals above.
+
+### Step 2: Calculate Confidence
+- 5-6 signals = High (>80%)
+- 3-4 signals = Medium (50-80%)
+- 0-2 signals = Low (<50%)
+
+### Step 3: Route Based on Confidence
+
+**High Confidence:**
+```
+"I see you're describing [ProjectName] - a [type] project with [key features].
+
+SpecWeave works best when we start with a proper increment plan. I'm going to:
+1. Clarify any ambiguities (1-2 questions max)
+2. Create a SpecWeave increment with complete specs
+
+Let's start: [Ask 1 clarifying question if needed, otherwise proceed]"
+
+[Automatically invoke /specweave.inc or spec-driven-brainstorming]
+```
+
+**Medium Confidence:**
+```
+"It looks like you're planning a new project. To help you best, I need to understand:
+1. [Ask about missing signals: features? timeline? tech stack?]
+
+Once I have these details, I'll guide you through SpecWeave's increment planning process."
+
+[Wait for response, then route to increment-planner or spec-driven-brainstorming]
+```
+
+**Low Confidence:**
+Don't activate. Let other skills handle it.
+
+### Step 4: Hand Off
+
+Based on clarity of requirements:
+
+- **Clear requirements** (detailed features, tech stack known) → `/specweave.inc` directly
+- **Unclear requirements** (vague features, tech stack uncertain) → `spec-driven-brainstorming` first
+
+## Examples
+
+### Example 1: Auto-Route (High Confidence)
+
+**User:**
+```
+Project: RosterSync - Team scheduling & availability management SaaS
+Quick build for sports teams, esports orgs, or any team-based groups to manage player/member availability, practice schedules, and lineup confirmations.
+Core features:
+- Team roster management
+- Availability calendar (who's available when)
+- Event/practice scheduling with auto-notifications
+- Simple lineup builder
+- Basic analytics on attendance patterns
+
+Tech stack:
+- .NET 8 Web API (backend)
+- Next.js 14+ (frontend with App Router)
+- PostgreSQL (local dev, easy cloud migration)
+- Auth: .NET Identity or simple JWT
+
+MVP time: 2-3 weeks
+Monetization: Freemium (5 teams free, $10/mo for unlimited)
+```
+
+**project-kickstarter detects:**
+- ✅ Name: "RosterSync"
+- ✅ Features: 5 core features listed
+- ✅ Tech stack: .NET 8, Next.js 14+, PostgreSQL
+- ✅ Timeline: "2-3 weeks"
+- ✅ Problem: "sports teams, esports orgs"
+- ✅ Business model: "Freemium ($10/mo)"
+
+**Confidence:** 6/6 = 100% → **AUTO-ROUTE**
+
+**Response:**
+```
+Perfect! I can see you have a well-defined product concept for RosterSync - a team scheduling SaaS.
+
+SpecWeave works by creating a complete increment specification first (spec.md, plan.md, tasks.md, tests.md), then implementing incrementally.
+
+I'm going to use SpecWeave's increment planning process to:
+1. Create the product specification (WHAT & WHY)
+2. Design the technical architecture (HOW)
+3. Break down implementation tasks (STEPS)
+4. Define test strategy
+
+Since you've provided the tech stack (.NET 8 + Next.js 14+), I'll structure this as a full-stack increment.
+
+Creating increment now with /specweave.inc...
+
+[Invokes /specweave.inc "RosterSync team scheduling SaaS"]
+```
+
+### Example 2: Clarify Then Route (Medium Confidence)
+
+**User:**
+```
+I want to build a price tracking system that monitors crypto prices in real-time
+```
+
+**project-kickstarter detects:**
+- ✅ Intent: "I want to build"
+- ✅ Type: "price tracking system"
+- ✅ Domain: "crypto prices"
+- ❌ Features: Not specified
+- ❌ Tech stack: Not specified
+- ❌ Timeline: Not specified
+
+**Confidence:** 3/6 = 50% → **CLARIFY THEN ROUTE**
+
+**Response:**
+```
+Great! A real-time crypto price tracking system is a solid project.
+
+To help you plan this properly, I need a bit more context:
+
+1. **Features:** Beyond real-time price monitoring, what should it do?
+   - Just display prices, or also alerts/notifications?
+   - Historical data tracking?
+   - Portfolio tracking?
+   - Price predictions/analysis?
+
+2. **Tech Stack:** Do you have a preferred stack, or should I recommend one?
+   - Frontend: React, Next.js, Vue, or other?
+   - Backend: Node.js, Python, .NET, or other?
+   - Database: PostgreSQL, MongoDB, Redis?
+
+3. **Timeline/Scope:** Is this a quick MVP or a production-ready system?
+
+Please share what you have in mind, and I'll create a complete SpecWeave increment plan for you.
+```
+
+### Example 3: Don't Activate (Low Confidence)
+
+**User:**
+```
+What do you think about using PostgreSQL vs MongoDB for this project?
+```
+
+**project-kickstarter detects:**
+- ✅ Tech mention: "PostgreSQL", "MongoDB"
+- ❌ Project name: Not mentioned
+- ❌ Features: Not mentioned
+- ❌ Timeline: Not mentioned
+- ❌ Problem: Not mentioned
+- ❌ Business: Not mentioned
+
+**Confidence:** 1/6 = 17% → **DON'T ACTIVATE**
+
+This is a technical question, not a project description. Let other skills or general conversation handle it.
+
+## Integration Architecture
+
+**Workflow**:
+```
+User message → specweave-detector (checks .specweave/ exists)
+                    ↓
+              project-kickstarter (pattern detection)
+                    ↓
+         [3+ signals detected?]
+                    ↓ YES
+         [Calculate confidence with SpecWeave context bonus]
+                    ↓
+         [Route to /specweave.inc or spec-driven-brainstorming]
+```
+
+**Calls:**
+- `specweave-detector` - Checks if .specweave/ directory exists (SpecWeave context)
+- `/specweave.inc` - For clear requirements (high confidence)
+- `spec-driven-brainstorming` - For unclear requirements (medium confidence)
+- `increment-planner` - Directly if enough detail provided
+
+**Called By:**
+- Automatically when pattern detected in SpecWeave folder
+- `skill-router` when routing ambiguous "build X" requests
+
+**Key Design**:
+- ✅ Generic pattern matching (not product-specific)
+- ✅ Context-aware (SpecWeave folder = higher confidence)
+- ✅ Confidence-based routing (no false positives)
+- ✅ User can opt-out with explicit instructions
+
+## Opt-Out Mechanism
+
+Users can override auto-routing with explicit instructions:
+- "Just brainstorm first" → Uses spec-driven-brainstorming
+- "Don't plan yet" → Regular conversation
+- "Quick discussion" → No automatic routing
+- "Let's explore ideas first" → spec-driven-brainstorming
+
+## Success Criteria
+
+- ✅ Users with product descriptions are automatically guided to increment planning
+- ✅ No "I forgot to use /specweave.inc" scenarios
+- ✅ Confidence >80% routes immediately (no friction)
+- ✅ Confidence 50-80% clarifies then routes (1-2 questions max)
+- ✅ Confidence <50% doesn't activate (avoids false positives)
+- ✅ Users can opt out with explicit instructions
+
+## Related Skills
+
+- **spec-driven-brainstorming**: For unclear requirements needing exploration
+- **increment-planner**: Creates the actual increment structure
+- **skill-router**: Routes ambiguous requests to appropriate skills
+
+---
+
+This skill solves the "I described my product but SpecWeave didn't help me plan it" problem by proactively detecting project descriptions and routing to increment planning.

package/src/skills/project-kickstarter/test-cases/test-1-high-confidence-full-product.yaml

@@ -0,0 +1,52 @@
+name: High Confidence - Full Product Description
+description: Complete product description with all signals should trigger auto-routing
+context:
+  working_directory: /project-with-specweave
+  specweave_initialized: true
+  specweave_directory_exists: true
+
+user_input: |
+  Project: RosterSync - Team scheduling & availability management SaaS
+  Quick build for sports teams, esports orgs, or any team-based groups to manage player/member availability, practice schedules, and lineup confirmations.
+
+  Core features:
+  - Team roster management
+  - Availability calendar (who's available when)
+  - Event/practice scheduling with auto-notifications
+  - Simple lineup builder
+  - Basic analytics on attendance patterns
+
+  Tech stack:
+  - .NET 8 Web API (backend)
+  - Next.js 14+ (frontend with App Router)
+  - PostgreSQL (local dev, easy cloud migration)
+  - Auth: .NET Identity or simple JWT
+
+  MVP time: 2-3 weeks
+  Monetization: Freemium (5 teams free, $10/mo for unlimited)
+
+expected_signals:
+  project_name: RosterSync
+  features_count: 5
+  tech_stack_mentioned: true
+  timeline_mentioned: true
+  problem_statement: sports teams, esports orgs
+  business_model: Freemium
+
+expected_confidence: high
+expected_adjusted_confidence: 100% # 5 signals + 2 SpecWeave bonus = 7/6
+expected_action: auto_route_to_increment_planning
+expected_command: /specweave.inc
+
+assistant_should:
+  - Acknowledge the product description
+  - Recognize it's a well-defined concept
+  - Explain SpecWeave's increment-first approach
+  - Automatically invoke /specweave.inc
+  - NOT ask unnecessary clarifying questions
+
+assistant_should_not:
+  - Ignore the product description
+  - Wait for explicit /inc command
+  - Ask about basic details already provided
+  - Treat it as a general conversation

package/src/skills/project-kickstarter/test-cases/test-2-medium-confidence-partial.yaml

@@ -0,0 +1,34 @@
+name: Medium Confidence - Partial Information
+description: Partial product description should trigger clarifying questions then routing
+context:
+  working_directory: /project-with-specweave
+  specweave_initialized: true
+  specweave_directory_exists: true
+
+user_input: |
+  I want to build a task management system with real-time collaboration.
+  Tech stack: React and Node.js
+
+expected_signals:
+  project_name: task management system
+  features_count: 1 # only "real-time collaboration" mentioned
+  tech_stack_mentioned: true
+  timeline_mentioned: false
+  problem_statement: false
+  business_model: false
+
+expected_confidence: medium
+expected_adjusted_confidence: 83% # 3 signals + 2 SpecWeave bonus = 5/6
+expected_action: auto_route_to_increment_planning # still high enough with bonus
+expected_command: /specweave.inc
+
+assistant_should:
+  - Recognize the intent to build something
+  - Note the tech stack is clear
+  - May ask 1-2 clarifying questions about features/timeline
+  - Route to /specweave.inc or spec-driven-brainstorming
+
+assistant_should_not:
+  - Treat as general conversation
+  - Ask excessive clarifying questions (max 1-2)
+  - Wait for explicit command

package/src/skills/project-kickstarter/test-cases/test-3-low-confidence-technical-question.yaml

@@ -0,0 +1,34 @@
+name: Low Confidence - Technical Question (Should Not Activate)
+description: Technical questions should NOT trigger project-kickstarter
+context:
+  working_directory: /project-with-specweave
+  specweave_initialized: true
+  specweave_directory_exists: true
+
+user_input: |
+  What do you think about using PostgreSQL vs MongoDB for this project?
+
+expected_signals:
+  project_name: false
+  features_count: 0
+  tech_stack_mentioned: true # PostgreSQL, MongoDB
+  timeline_mentioned: false
+  problem_statement: false
+  business_model: false
+
+expected_confidence: low
+expected_adjusted_confidence: 50% # 1 signal + 2 SpecWeave bonus = 3/6
+expected_action: do_not_activate
+expected_command: none
+
+assistant_should:
+  - Answer the technical question
+  - Provide database comparison
+  - NOT assume this is a project description
+  - NOT route to increment planning
+
+assistant_should_not:
+  - Activate project-kickstarter
+  - Ask about project details
+  - Invoke /specweave.inc
+  - Treat as product description

package/src/skills/project-kickstarter/test-cases/test-4-opt-out-explicit.yaml

@@ -0,0 +1,41 @@
+name: Opt-Out - Explicit User Override
+description: User can override auto-routing with explicit instructions
+context:
+  working_directory: /project-with-specweave
+  specweave_initialized: true
+  specweave_directory_exists: true
+
+user_input: |
+  Just brainstorm first, don't plan yet.
+
+  Project: TaskMaster - AI-powered task prioritization SaaS
+  Core features:
+  - Smart task prioritization using ML
+  - Calendar integration
+  - Team collaboration
+  Tech stack: Python FastAPI + React + PostgreSQL
+  MVP: 3 weeks
+
+expected_signals:
+  project_name: TaskMaster
+  features_count: 3
+  tech_stack_mentioned: true
+  timeline_mentioned: true
+  problem_statement: true # AI-powered task prioritization
+  business_model: false
+
+expected_confidence: high # but user opted out
+expected_adjusted_confidence: 100% # 5 signals + 2 bonus
+expected_action: respect_opt_out
+expected_command: spec-driven-brainstorming # not /specweave.inc
+
+assistant_should:
+  - Recognize the opt-out instruction ("just brainstorm first")
+  - Use spec-driven-brainstorming instead
+  - Ask exploratory questions
+  - NOT automatically create increment
+
+assistant_should_not:
+  - Ignore the opt-out instruction
+  - Automatically invoke /specweave.inc
+  - Force increment creation

package/src/skills/skill-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-router
-description: Intelligent routing system that parses ambiguous user requests and routes them to appropriate SpecWeave skills with >90% accuracy. Acts as the "traffic controller" for all skill invocations. Activates when user intent is unclear or when multiple skills could handle a request. Keywords: route, clarify, ambiguous, which skill, help me decide.
+description: Intelligent routing system that parses ambiguous user requests and routes them to appropriate SpecWeave skills with >90% accuracy. Acts as the "traffic controller" for all skill invocations. Activates when user intent is unclear or when multiple skills could handle a request. Also activates proactively when detecting product description patterns (name + features + tech stack + timeline) in SpecWeave folders. Keywords: route, clarify, ambiguous, which skill, help me decide, product description, new project, feature list, tech stack, build this.
 ---
 
 # Skill Router - Intelligent Request Routing

package/src/skills/spec-driven-brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-driven-brainstorming
-description: Refines rough ideas into spec-ready designs through structured Socratic questioning, alternative exploration, and incremental validation. Use BEFORE creating increments - transforms vague concepts into clear requirements. Activates for: brainstorm, explore idea, refine concept, design thinking, what should I build, help me think through, ultrathink design, deep thinking, architecture exploration.
+description: Refines rough ideas into spec-ready designs through structured Socratic questioning, alternative exploration, and incremental validation. Use BEFORE creating increments - transforms vague concepts into clear requirements. Activates for: brainstorm, explore idea, refine concept, design thinking, what should I build, help me think through, ultrathink, ultrathink on, think through this, deep thinking, architecture exploration, analyze this idea, evaluate approach, explore options.
 ---
 
 # Spec-Driven Brainstorming

package/src/skills/specweave-detector/SKILL.md

@@ -1,11 +1,17 @@
 ---
 name: specweave-detector
-description: Documentation skill that explains SpecWeave v0.1.9 smart workflow slash commands. SpecWeave uses EXPLICIT slash commands only - no auto-activation! Use /inc (Plan Increment) or /increment to start. Smart features auto-resume (/do), auto-close (/inc), progress tracking (/progress). Commands /inc, /do, /progress, /validate, /done, /list-increments, /sync-docs, /sync-github. All commands listed in .claude/commands/. Keywords slash commands, /inc, /increment, /do, /progress, /validate, /done, specweave commands, smart workflow, v0.1.9.
+description: Detects SpecWeave context (.specweave/ directory exists) and provides workflow documentation. v0.3.8+ features PROACTIVE auto-detection - when in SpecWeave folder, product descriptions automatically trigger increment planning. Explicit slash commands still work (/inc, /do, /progress, /validate, /done, /sync-docs, /sync-github). Keywords slash commands, /inc, /increment, /do, /progress, /validate, /done, specweave commands, smart workflow, auto-detection, specweave folder.
 ---
 
-# SpecWeave v0.1.9 - Smart Workflow Slash Commands
+# SpecWeave v0.3.8+ - Smart Workflow with Auto-Detection
 
-**CRITICAL**: SpecWeave uses **EXPLICIT SLASH COMMANDS ONLY** - no auto-activation, no proactive detection!
+**NEW in v0.3.8**: SpecWeave now features **PROACTIVE AUTO-DETECTION**!
+
+When working in a SpecWeave-initialized project (.specweave/ directory exists), product descriptions automatically trigger increment planning.
+
+**Two ways to use SpecWeave**:
+1. ✅ **Auto-detection** (NEW): Describe your product → SpecWeave creates increment automatically
+2. ✅ **Explicit commands**: Type `/inc "feature"` → Works as before
 
 ## How SpecWeave Works (v0.1.9)
 

package/src/templates/CLAUDE.md.template

@@ -43,6 +43,65 @@ This project uses **SpecWeave** - a specification-first AI development framework
 
 ---
 
+## 🧠 Automatic Intent Detection (NEW in v0.3.8+)
+
+**SpecWeave now detects when you're describing a product/project and automatically helps you plan it!**
+
+### How It Works
+
+When working in a SpecWeave-initialized project (`.specweave/` exists), SpecWeave recognizes product descriptions by detecting these patterns:
+
+**Signals that trigger auto-detection:**
+1. ✅ **Project Name/Description** - "Project: RosterSync", "I want to build X"
+2. ✅ **Features List** - Bullet points or numbered list of features (3+ items)
+3. ✅ **Tech Stack** - Languages, frameworks, databases mentioned
+4. ✅ **Timeline/Scope** - "MVP", "2 weeks", "Phase 1", "Quick build"
+5. ✅ **Problem Statement** - "For teams...", "Helps users...", "Solves..."
+6. ✅ **Business Model** - "Freemium", "$X/mo", "B2B", "Consumer"
+
+**Confidence Levels:**
+- **High (5-6 signals + SpecWeave folder)**: Auto-route to `/specweave.inc` immediately
+- **Medium (3-4 signals + SpecWeave folder)**: Ask 1-2 clarifying questions, then route
+- **Low (<3 signals)**: Regular conversation (no auto-routing)
+
+### Example: Automatic Detection
+
+```
+You: Project: RosterSync - Team scheduling SaaS
+Core features:
+- Team roster management
+- Availability calendar
+- Event scheduling with notifications
+- Lineup builder
+Tech stack: .NET 8, Next.js 14+, PostgreSQL
+MVP: 2-3 weeks
+Monetization: Freemium ($10/mo)
+
+SpecWeave detects: ✅ Name ✅ Features ✅ Tech ✅ Timeline ✅ Problem ✅ Business
+→ Automatically recognizes this as a product description
+→ Guides you through increment planning
+→ Invokes /specweave.inc automatically
+
+No need to remember to type /inc!
+```
+
+### Opt-Out Options
+
+You can override automatic routing with explicit instructions:
+- **"Just brainstorm first"** → Uses spec-driven-brainstorming instead
+- **"Don't plan yet"** → Regular conversation
+- **"Quick discussion"** → No automatic routing
+- **"Let's explore ideas first"** → Exploratory mode
+
+### Two Ways to Use SpecWeave
+
+1. ✅ **Automatic** (NEW): Describe your product → SpecWeave detects it → Plans automatically
+2. ✅ **Explicit** (Classic): Type `/inc "feature"` → Works as before
+
+Both approaches work perfectly - use whichever feels more natural!
+
+---
+
 ## 🚨 CRITICAL: File Organization Rules
 
 **Keep project root CLEAN!** All AI-generated files MUST go into increment folders.