@leanspec/ui 0.2.4 → 0.2.5-dev.20251118143726

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

@@ -1,287 +0,0 @@
----
-status: planned
-created: '2025-11-13'
-tags:
-  - onboarding
-  - ai-agents
-  - ux
-  - mcp
-priority: high
-created_at: '2025-11-13T08:20:28.110Z'
-updated_at: '2025-11-17T08:18:44.417Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-13T08:21:45.345Z'
-  - status: planned
-    at: '2025-11-17T08:18:44.417Z'
----
-
-# ai-agent-first-use-workflow
-
-> **Status**: 🗓️ Planned · **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/dist/standalone/specs/073-template-engine-agents-md/README.md

@@ -1,323 +0,0 @@
----
-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