@leanspec/ui 0.2.9-dev.20251205030455 → 0.2.10

package/.next/standalone/packages/ui/dist/standalone/specs/072-ai-agent-first-use-workflow/README.md

@@ -0,0 +1,285 @@
+---
+status: in-progress
+created: '2025-11-13'
+tags:
+  - onboarding
+  - ai-agents
+  - ux
+  - mcp
+priority: high
+created_at: '2025-11-13T08:20:28.110Z'
+updated_at: '2025-11-13T08:21:45.345Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-13T08:21:45.345Z'
+---
+
+# ai-agent-first-use-workflow
+
+> **Status**: ⏳ In progress · **Priority**: High · **Created**: 2025-11-13 · **Tags**: onboarding, ai-agents, ux, mcp
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Problem**: Real users report that AI agents are not following the standard workflow to leverage LeanSpec MCP/CLI tools on their first use. Observed issues:
+
+1. **Skipping Discovery**: Agents don't use discovery commands (`lean-spec board`, `lean-spec list`) to understand project context before creating specs
+2. **Manual Spec Creation**: Agents create spec files manually (e.g., `specs/my-feature.md`) instead of using `lean-spec create`, resulting in:
+   - Missing sequence numbers
+   - Wrong directory structure (flat files vs `NNN-name/README.md`)
+   - Missing/malformed frontmatter
+   - Breaking LeanSpec tooling
+
+**Root Causes**:
+1. Current AGENTS.md buries discovery workflow ~200 lines down in "SDD Workflow"
+2. No explicit instruction to **ALWAYS use `lean-spec create`** instead of manual file creation
+3. CLI/MCP tool usage not emphasized as mandatory, appears optional
+
+**Impact**:
+- Specs created with wrong structure, breaking `lean-spec list`, `board`, etc.
+- Duplicate/conflicting specs from lack of discovery
+- Missing proper metadata and sequence numbers
+- Poor first impression of LeanSpec's AI integration
+- Users need extensive manual corrections
+
+**Goal**: Make the discovery-first workflow unmissable and automatic for AI agents on first use.
+
+## Design
+
+### Problem Analysis
+
+Current AGENTS.md structure (all templates):
+1. **First Principles** (60+ lines) - Great but heavy for first use
+2. **Core Rules** - Generic, no actionable first step
+3. **Essential Commands** - Listed but not emphasized as mandatory first action
+4. **SDD Workflow** - "Discover" is step 1 but appears ~200 lines down
+
+**What AI agents need on FIRST interaction:**
+```
+🚨 CRITICAL FIRST STEPS:
+
+1. DISCOVER project context:
+   - CLI: `lean-spec board` (preferred - shows status + health)
+   - MCP: Use board prompt or list tool
+   
+2. ALWAYS use proper tools to create specs:
+   - CLI: `lean-spec create <name>`
+   - MCP: Use create_spec tool
+   - ❌ NEVER manually create spec files
+   
+Skipping these steps breaks LeanSpec tooling and structure.
+```
+
+### Solution: Add Prominent First-Use Section
+
+Add a new section **immediately after project description**, before everything else:
+
+**Content to add:**
+
+    ## 🚨 First Interaction Protocol
+    
+    **STOP**: Before doing anything, follow these mandatory steps:
+    
+    ### Step 1: Discover Context (REQUIRED)
+    
+    **Using CLI** (recommended):
+    - `lean-spec board` - Best: shows status, health, WIP at a glance
+    - `lean-spec list` - Alternative: see all specs
+    
+    **Using MCP**:
+    - Use the `board` prompt (preferred)
+    - Or use the `list` tool
+    
+    ### Step 2: Always Use Proper Tools (REQUIRED)
+    
+    **To create specs:**
+    - CLI: `lean-spec create <name>`
+    - MCP: Use the create_spec tool
+    
+    ❌ **NEVER manually create spec files** (e.g., `specs/my-feature.md`)
+    ✅ **ALWAYS use the CLI/MCP tools**
+    
+    **Why?**
+    - `lean-spec create` auto-generates sequence numbers
+    - Creates correct directory structure (`NNN-name/README.md`)
+    - Adds proper frontmatter with timestamps
+    - Manual creation breaks tooling (`list`, `board`, `search`)
+    
+    ### Step 3: Update Status as You Work
+    
+    - `lean-spec update <spec> --status in-progress` - Mark started
+    - `lean-spec update <spec> --status complete` - Mark done
+    
+    **Why This Matters**: 
+    - Discovery prevents duplicate work and finds related specs
+    - Using proper tools maintains structure and metadata
+    - Status updates enable project tracking and visibility
+
+### Implementation Strategy
+
+**Phase 1: Update All Templates** (Immediate)
+- Add "First Interaction Protocol" section to all template AGENTS.md files:
+  - `packages/cli/templates/minimal/files/AGENTS.md`
+  - `packages/cli/templates/standard/files/AGENTS.md`
+  - `packages/cli/templates/enterprise/files/AGENTS.md`
+- Position: Right after project description, before Core Rules
+- Use prominent emoji/visual markers (🚨)
+- Keep it short (<150 tokens)
+
+**Phase 2: Update Root AGENTS.md** (Reference implementation)
+- Update `/AGENTS.md` to include this pattern
+- Serves as canonical example
+
+**Phase 3: Update Documentation**
+- Update `docs-site/docs/guide/usage/ai-assisted/agent-configuration.mdx`
+- Add first-use protocol to example templates
+- Update MCP integration guide to emphasize discovery-first
+
+**Phase 4: MCP Server Enhancement** (Optional, future)
+- Add server-side hint when AI makes first call without discovery
+- Track if `board` or `list` was called this session
+- Return gentle reminder if agent tries `create_spec` without discovery first
+- Detect if specs are being manually created (filesystem monitoring)
+
+### Content Guidelines
+
+**Keep it:**
+- ✅ Visual (emojis, formatting)
+- ✅ Actionable (specific commands with examples)
+- ✅ Short (~200 tokens max for expanded version)
+- ✅ At the top (can't miss it)
+- ✅ Explains WHY (prevents duplicates, maintains structure)
+- ✅ Explicit about what NOT to do (❌ don't manually create files)
+
+**Avoid:**
+- ❌ Philosophy (save for later sections)
+- ❌ Lengthy explanations
+- ❌ Buried in other content
+- ❌ Optional/suggested tone (make it mandatory)
+
+## Plan
+
+- [ ] **Phase 1: Update template AGENTS.md files**
+  - [ ] Update `packages/cli/templates/minimal/files/AGENTS.md`
+  - [ ] Update `packages/cli/templates/standard/files/AGENTS.md`
+  - [ ] Update `packages/cli/templates/enterprise/files/AGENTS.md`
+  - [ ] Test with each template via `lean-spec init`
+
+- [ ] **Phase 2: Update root AGENTS.md**
+  - [ ] Add First Interaction Protocol section
+  - [ ] Verify positioning and visibility
+
+- [ ] **Phase 3: Update documentation**
+  - [ ] Update agent-configuration.mdx with first-use emphasis
+  - [ ] Update mcp-integration.mdx to highlight discovery pattern
+  - [ ] Add verification section for first-use behavior
+
+- [ ] **Phase 4: Validation & Testing**
+  - [ ] Test with real AI agents (Copilot, Claude, etc.)
+  - [ ] Verify discovery commands are used before creation
+  - [ ] Collect feedback from test users
+
+## Test
+
+**Success Criteria:**
+
+- [ ] **Visibility Test**: First Interaction Protocol appears in first 100 lines of all AGENTS.md templates
+- [ ] **Discovery Test**: AI agent runs `lean-spec board` (or MCP equivalent) BEFORE creating specs
+- [ ] **Tool Usage Test**: AI agent uses `lean-spec create` instead of manually creating files
+- [ ] **Structure Test**: Created specs have correct structure (`NNN-name/README.md`, proper frontmatter)
+- [ ] **Content Test**: Section includes discovery priority (board > list), tool usage mandate
+- [ ] **Template Test**: All three templates (minimal, standard, enterprise) include the section
+- [ ] **User Feedback**: At least 3 real users confirm agents follow proper workflow
+
+**Testing Protocol:**
+
+1. **Fresh Project Test**:
+   ```bash
+   mkdir test-lean-spec-project
+   cd test-lean-spec-project
+   lean-spec init --template standard
+   # Ask AI agent: "Create a spec for authentication"
+   # Expected: 
+   #   1. Agent runs `lean-spec board` FIRST
+   #   2. Agent uses `lean-spec create authentication`
+   #   3. Spec created at specs/001-authentication/README.md (not specs/authentication.md)
+   ```
+
+2. **MCP Test** (with Copilot/Claude):
+   - Configure MCP for test project
+   - Ask: "Show me the project board"
+   - Expected: Uses MCP board prompt or list tool
+   - Ask: "Create a user profile spec"
+   - Expected: Uses create_spec tool (NOT manual file creation)
+   - Verify: Check `specs/` directory has `NNN-user-profile/README.md` structure
+
+3. **Existing Project Test**:
+   - Project with 5+ existing specs
+   - Ask AI: "Add a rate limiting feature"
+   - Expected: 
+     - Agent runs `lean-spec board` to see context
+     - Agent searches for related specs (`lean-spec search "rate"`)
+     - Agent uses `lean-spec create rate-limiting`
+     - New spec properly numbered (e.g., `006-rate-limiting/`)
+
+4. **Manual Creation Prevention Test**:
+   - Ask AI: "Create a spec for email notifications"
+   - Monitor filesystem
+   - Expected: NO direct file creation in specs/
+   - Expected: Uses `lean-spec create` or MCP create_spec tool
+
+## Notes
+
+### Why This Wasn't Caught Earlier
+
+- LeanSpec dogfoods itself - our AGENTS.md was customized and had implicit context
+- Templates were created for "configured" projects, not first-time use
+- MCP testing focused on tool functionality, not workflow adherence
+- Documentation showed capabilities but didn't enforce discovery-first pattern
+- Testing focused on successful tool calls, not detecting manual file creation
+- No real-world user testing with fresh AI agent interactions
+
+### Alternative Approaches Considered
+
+1. **MCP Server-Side Enforcement**: Have MCP server refuse `create` calls until discovery is done
+   - ❌ Too restrictive, breaks legitimate workflows
+   - ❌ Doesn't help CLI-only users
+   - ✅ Could work as optional "training wheels" mode
+
+2. **Interactive Init Prompt**: During `lean-spec init`, show AI-focused onboarding
+   - ❌ Doesn't help projects initialized before update
+   - ❌ Users might skip or miss it
+   - ✅ Good supplementary approach
+
+3. **System Prompt Enhancement**: Provide starter prompts in docs
+   - ❌ Users don't always read docs
+   - ❌ Varies by AI tool configuration
+   - ✅ Good documentation enhancement
+
+**Decision**: Start with prominent AGENTS.md section (lowest friction, highest impact). Consider others as enhancements.
+
+### Related Work
+
+- `specs/061-ai-assisted-spec-writing` - AI writing guidance (complements this)
+- `specs/034-copilot-slash-commands` - VS Code integration (future commands for discovery)
+- `specs/070-mcp-token-counting-tool` - MCP server enhancements (future server-side hints)
+
+### Open Questions
+
+- Should we add visual indicators (banner, ASCII art) to make section even more prominent?
+- Should MCP server log discovery patterns and warn if skipped?
+- How do we measure success beyond anecdotal user reports?
+- Can we detect manual spec creation and provide helpful error messages?
+- Should `lean-spec validate` check for manually created specs (missing sequence, wrong structure)?
+
+### Key Insight from User Feedback
+
+**Discovery Tool Priority**: `board` > `list` because:
+- `board` shows status, WIP, and project health in one view
+- `list` only shows spec names without context
+- New users get better overview from board
+- Aligns with "see the forest before the trees" principle
+
+**Manual Creation Problem**: More serious than just skipping discovery - agents that manually create files bypass the entire LeanSpec system, breaking tooling and structure.

package/.next/standalone/packages/ui/dist/standalone/specs/073-template-engine-agents-md/README.md

@@ -0,0 +1,323 @@
+---
+status: complete
+created: '2025-11-13'
+tags:
+  - templates
+  - maintainability
+  - dx
+  - refactor
+  - ai-first
+priority: medium
+related:
+  - '025'
+  - '072'
+  - '074'
+  - '078'
+created_at: '2025-11-13T08:35:40.229Z'
+updated_at: '2025-11-13T10:32:28.046Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-13T09:26:58.535Z'
+  - status: complete
+    at: '2025-11-13T09:29:32.737Z'
+  - status: in-progress
+    at: '2025-11-13T09:48:01.526Z'
+  - status: complete
+    at: '2025-11-13T10:32:28.046Z'
+completed_at: '2025-11-13T09:29:32.737Z'
+completed: '2025-11-13'
+---
+
+# template-engine-agents-md
+
+> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-13 · **Tags**: templates, maintainability, dx, refactor, ai-first
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Problem**: Template AGENTS.md files have significant duplication and drift issues:
+
+1. **Duplication**: Core content (First Principles, commands, workflow) duplicated across 3+ templates
+2. **Maintenance Burden**: Single change (like nested code blocks rule) requires updating 4+ files
+3. **Drift Risk**: Templates diverge over time as updates miss some files
+4. **Template System Mismatch**: Current `.lean-spec/templates/` only handles spec files (README.md), not supporting files (AGENTS.md)
+
+**Example**: Just added "nested code blocks" rule to all 4 AGENTS.md files - this is not scalable.
+
+**Current State**:
+- Root `AGENTS.md` (reference implementation)
+- `packages/cli/templates/minimal/files/AGENTS.md`
+- `packages/cli/templates/standard/files/AGENTS.md`
+- `packages/cli/templates/enterprise/files/AGENTS.md`
+- Each ~85-125 lines with 70%+ shared content
+
+**Goal**: Use template engine to generate AGENTS.md from shared components, eliminate duplication, prevent drift.
+
+**Scope**: This spec covers Phase 1 only (AGENTS.md template engine). Phase 2 (sub-spec template system) was split into spec 078.
+
+**Related Specs**:
+- `012-sub-spec-files` (archived) - Original sub-spec design (implemented)
+- `013-custom-spec-templates` (archived) - Template system v1
+- `025-template-config-updates` - Config format updates
+- `072-ai-agent-first-use-workflow` - Current AGENTS.md improvement driving this
+- `074-content-at-creation` - Spec creation with content flags (similar AI-first approach)
+- `078-sub-spec-template-system` - Phase 2 split into separate spec (sub-spec generation)
+
+## Design
+
+### Problem Analysis
+
+**Current AGENTS.md Structure**:
+
+```
+1. Project description (varies)
+2. Core Rules (mostly shared, 1-2 project-specific rules)
+3. Discovery Commands (identical across templates)
+4. Spec Frontmatter (varies by template - minimal/standard/enterprise)
+5. When to Use Specs (similar with minor variations)
+6. Workflow (enterprise has approval, others standard)
+7. Quality Standards (identical)
+```
+
+**Shared (~70%)**: Core Rules, Discovery Commands, Quality Standards, most workflow steps
+**Variable (~30%)**: Project description, frontmatter fields, approval workflow
+
+### Solution: Two-Part Improvement
+
+#### Part 1: Template Engine for AGENTS.md (Immediate)
+
+Use simple template engine (Handlebars or similar) with shared components:
+
+**Structure**:
+```
+packages/cli/templates/
+├── _shared/
+│   ├── agents-components/
+│   │   ├── core-rules.md
+│   │   ├── discovery-commands.md
+│   │   ├── essential-commands.md
+│   │   ├── workflow-standard.md
+│   │   ├── workflow-enterprise.md
+│   │   └── quality-standards.md
+│   └── agents-template.hbs
+├── minimal/
+│   ├── config.json
+│   ├── agents-config.json  # NEW: defines which components + vars
+│   └── files/
+│       └── spec-template.md
+├── standard/
+│   ├── config.json
+│   ├── agents-config.json
+│   └── files/
+│       └── spec-template.md
+└── enterprise/
+    ├── config.json
+    ├── agents-config.json
+    └── files/
+        └── spec-template.md
+```
+
+**agents-config.json** (example for standard):
+```json
+{
+  "project_name": "{project_name}",
+  "description": "Lightweight spec methodology for AI-powered development.",
+  "components": [
+    "core-rules",
+    "discovery-commands",
+    "essential-commands",
+    "frontmatter-standard",
+    "workflow-standard",
+    "quality-standards"
+  ],
+  "customRules": [],
+  "workflowType": "standard"
+}
+```
+
+**Build Process**:
+```bash
+# During package build or on-demand
+npm run build:agents-templates
+# Generates AGENTS.md in each template from shared components
+```
+
+**Benefits**:
+- ✅ Single source of truth for shared content
+- ✅ Easy to update all templates (edit one component file)
+- ✅ Template-specific customization still possible
+- ✅ Prevents drift automatically
+- ✅ Can version control both source and generated files
+
+### Technical Approach
+
+**AGENTS.md Template Engine**:
+- Tool: Handlebars.js (lightweight, widely used)
+- Build script: `scripts/build-agents-templates.ts`
+- Runs during: `pnpm build` or `pnpm build:templates`
+- Generated files committed to repo (easier distribution)
+
+**Note**: Originally this spec included Phase 2 (Sub-Spec Template System) for generating optional sub-spec files. That has been split into spec 078 for clearer separation of concerns
+
+### Alternative Approaches Considered
+
+1. **Runtime Template Composition**: Generate AGENTS.md during `lean-spec init`
+   - ❌ Requires template engine in runtime dependency
+   - ❌ More complex error handling
+   - ✅ Could work but build-time is simpler
+
+2. **Symbolic Links**: Link shared content
+   - ❌ Breaks on Windows
+   - ❌ Confusing in version control
+   - ❌ Doesn't solve the problem
+
+3. **Single AGENTS.md with Conditionals**: One file with template-specific sections
+   - ❌ Becomes unreadable
+   - ❌ Hard to maintain
+   - ❌ Doesn't scale
+
+**Decision**: Build-time generation with Handlebars is the sweet spot - simple, reliable, works everywhere.
+
+## Plan
+
+### Phase 1: AGENTS.md Template Engine
+
+- [x] **Setup Template Infrastructure**
+  - [x] Create `packages/cli/templates/_shared/agents-components/` directory
+  - [x] Extract shared components from existing AGENTS.md files
+  - [x] Create `agents-template.hbs` main template
+  - [x] Add Handlebars dependency to CLI package
+
+- [x] **Create Component Files**
+  - [x] `core-rules-base.md` - 4 shared rules
+  - [x] `discovery-commands.md` - identical across templates
+  - [x] `essential-commands.md` - command reference
+  - [x] `frontmatter-minimal.md` - minimal frontmatter guidance
+  - [x] `frontmatter-standard.md` - standard frontmatter
+  - [x] `frontmatter-enterprise.md` - enterprise frontmatter
+  - [x] `workflow-standard.md` - standard SDD workflow
+  - [x] `workflow-enterprise.md` - enterprise approval workflow
+  - [x] `quality-standards.md` - identical across templates
+
+- [x] **Create Template Configs**
+  - [x] `minimal/agents-config.json`
+  - [x] `standard/agents-config.json`
+  - [x] `enterprise/agents-config.json`
+
+- [x] **Build Script**
+  - [x] Create `scripts/build-agents-templates.ts`
+  - [x] Implement template composition logic
+  - [x] Add validation for generated output
+  - [x] Integrate into `pnpm build` script
+
+- [x] **Validation & Testing**
+  - [x] Verify generated AGENTS.md matches current versions
+  - [x] Test `lean-spec init` with each template
+  - [x] Update CI to fail if generated files out of sync
+  - [ ] Add pre-commit hook to regenerate if source changed (deferred - CI validation sufficient)
+
+**Note**: Phase 2 (Sub-Spec Template System) has been moved to spec 078-sub-spec-template-system
+
+## Test
+
+**Phase 1: AGENTS.md Template Engine**
+
+- [ ] **Component Extraction Test**: Generated AGENTS.md matches current files byte-for-byte
+- [ ] **Build Integration Test**: `pnpm build` successfully generates all templates
+- [ ] **Template Variability Test**: Each template (minimal/standard/enterprise) has correct unique content
+- [ ] **Shared Content Test**: Changes to shared components propagate to all templates
+- [ ] **CI Validation Test**: CI fails if source components changed but generated files not updated
+
+**Test Protocol**:
+```bash
+# 1. Generate templates
+pnpm build:templates
+
+# 2. Compare with current
+diff packages/cli/templates/minimal/files/AGENTS.md packages/cli/templates/minimal/files/AGENTS.md.bak
+
+# 3. Test template selection during init
+lean-spec init --template standard
+# Verify AGENTS.md was copied correctly
+
+# 4. Modify shared component
+echo "\n6. Test rule" >> templates/_shared/agents-components/core-rules-base.md
+pnpm build:templates
+# Verify all AGENTS.md files updated
+```
+
+## Notes
+
+### Why This Matters
+
+**Immediate Pain**: Just added "nested code blocks" rule to 4 files. Next update will be same pain.
+
+**Long-term Impact**: 
+- As LeanSpec grows, AGENTS.md will evolve frequently (new commands, updated workflows, etc.)
+- Every change requires 4-file update currently
+- Risk of inconsistency grows over time
+- Template engine fixes this permanently
+
+### Build vs Runtime Trade-offs
+
+**Build-time generation** (chosen):
+- ✅ No runtime overhead
+- ✅ Simple distribution (generated files in npm package)
+- ✅ Easy to audit (see generated output in git)
+- ✅ No template engine dependency at runtime
+- ⚠️ Must remember to rebuild after editing components
+
+**Runtime generation** (rejected):
+- ✅ Always fresh
+- ❌ Template engine in runtime deps
+- ❌ More complex error handling
+**Decision**: Build-time generation with Handlebars is the sweet spot - simple, reliable, works everywhere.
+
+### Phase 2 Split Decision
+
+**Why split into separate spec (078)?**
+- Phase 1 (AGENTS.md template engine) is complete and independent
+- Phase 2 (sub-spec template system) is a different feature with different scope
+- Cleaner separation allows independent planning and archiving
+- Phase 1 can be archived when appropriate while Phase 2 continues as spec 078
+
+### Related Specs
+
+See Overview section for full list of related specs.
+
+### Open Questions
+
+- Should we also template-ize spec templates (README.md)? Or just AGENTS.md?
+- ~~Do we need a `lean-spec templates validate` command?~~ ✅ Implemented as `pnpm validate:templates`
+- ~~Should CI auto-regenerate and commit, or just fail?~~ ✅ CI fails on drift (regeneration is manual)
+- Can we detect if AGENTS.md was manually edited and warn?
+- ~~Should we support optional sub-specs?~~ ✅ Moved to spec 078
+
+### Success Metrics
+
+- **Maintenance Time**: Adding new rule takes 1 file edit + build (not 4 file edits) ✅ **Achieved**
+- **Consistency**: No drift between templates (verified by tests) ✅ **Achieved** (CI validation in place)
+- **Flexibility**: Easy to create new templates with different combinations ✅ **Achieved**
+
+## Completion Summary
+
+**Status**: Complete ✅
+
+**Completed Work**:
+1. ✅ Template infrastructure created with component-based architecture
+2. ✅ All component files extracted and organized
+3. ✅ Build system integrated (`pnpm build:templates`)
+4. ✅ Validation system implemented (`pnpm validate:templates`)
+5. ✅ CI integration added to prevent drift
+6. ✅ Manual testing completed for all three templates (minimal, standard, enterprise)
+7. ✅ Documentation updated with validation guide
+
+**Benefits Realized**:
+- Single source of truth for shared content
+- Automated validation prevents template drift
+- Easy maintenance: update once, propagates to all templates
+- CI ensures quality and consistency
+
+**Note**: Originally planned Phase 2 (Sub-Spec Template System) has been split into spec 078-sub-spec-template-system for clearer separation of concerns