@leanspec/ui 0.2.5 → 0.2.6-dev.20251125010539

package/.next/standalone/packages/ui/dist/standalone/specs/078-sub-spec-template-system/README.md

@@ -1,303 +0,0 @@
----
-status: planned
-created: '2025-11-13'
-tags:
-  - templates
-  - cli
-  - dx
-  - ai-first
-  - sub-specs
-priority: medium
-created_at: '2025-11-13T13:31:48.324Z'
-related:
-  - 073-template-engine-agents-md
-  - 012-sub-spec-files
-updated_at: '2025-11-13T13:35:14.763Z'
----
-
-# sub-spec-template-system
-
-> **Status**: 🗓️ Planned · **Priority**: Medium · **Created**: 2025-11-13 · **Tags**: templates, cli, dx, ai-first, sub-specs
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-**Problem**: Current `.lean-spec/templates/` system only generates main spec file (README.md), but specs often need sub-files like DESIGN.md, TESTING.md, IMPLEMENTATION.md, etc.
-
-**Current Limitations**:
-- Template system generates only README.md
-- Users manually create sub-spec files after initial creation
-- No support for optional vs required sub-specs
-- AI agents and automation tools need programmatic sub-spec creation
-
-**Goal**: Enable template system to generate optional sub-spec files using:
-- Declarative flags (`--design`, `--testing`) for AI/automation
-- File conventions (`.opt`, `.req`) for template authors
-- Interactive mode (`--with-subs`) for human users (opt-in)
-
-**Origin**: Split from spec 073 Phase 2 (AGENTS.md template engine complete, sub-spec system separate concern)
-
-## Design
-
-### Proposed Template Structure
-
-```
-.lean-spec/
-└── templates/
-    ├── default/
-    │   ├── README.md         # Main spec template (always generated)
-    │   ├── DESIGN.md.opt     # Optional sub-spec
-    │   └── TESTING.md.opt    # Optional sub-spec
-    └── api/
-        ├── README.md
-        ├── API.md.req        # Required sub-spec (always included)
-        └── SCHEMAS.md.opt    # Optional sub-spec
-```
-
-### File Conventions
-
-- **`{name}.md`** - Always generated (main spec)
-- **`{name}.md.opt`** - Optional, generated only if requested via flag or prompt
-- **`{name}.md.req`** - Required, always generated for this template
-
-### Usage Patterns (AI-First Design)
-
-**Primary Interface: Explicit Flags** (optimized for AI agents)
-```bash
-# Generate with specific sub-specs
-lean-spec create my-feature --design --testing
-# → Creates README.md + DESIGN.md + TESTING.md
-
-# No flags = README.md only (default)
-lean-spec create simple-fix
-```
-
-**Secondary Interface: Interactive Mode** (opt-in for humans)
-```bash
-lean-spec create my-feature --with-subs
-# Prompts user to select which optional sub-specs to include
-? Include optional sub-specs? (space to select)
-  [ ] DESIGN.md
-  [x] TESTING.md
-  [ ] IMPLEMENTATION.md
-```
-
-**Rationale**: AI agents use CLI programmatically and can't handle interactive prompts. Flags provide declarative, non-blocking interface.
-
-### Config Schema Enhancement
-
-```json
-{
-  "templates": {
-    "default": {
-      "main": "README.md",
-      "optional": ["DESIGN.md", "TESTING.md", "IMPLEMENTATION.md"],
-      "required": [],
-      "flags": {
-        "--design": "DESIGN.md",
-        "--testing": "TESTING.md",
-        "--implementation": "IMPLEMENTATION.md"
-      }
-    },
-    "api": {
-      "main": "README.md",
-      "optional": ["SCHEMAS.md"],
-      "required": ["API.md"],
-      "flags": {
-        "--schemas": "SCHEMAS.md"
-      }
-    }
-  }
-}
-```
-
-### Technical Implementation
-
-**Extend `packages/cli/src/commands/creator.ts`**:
-1. Parse sub-spec flags from command line
-2. Detect `.opt` and `.req` files in template directory
-3. Filter files based on flags and conventions
-4. Apply variable substitution to all generated files
-5. Fall back to interactive mode if `--with-subs` flag present
-
-**Template Resolution Logic**:
-```typescript
-// Pseudo-code
-function resolveTemplateFiles(templateDir, flags, interactive) {
-  const files = [];
-  
-  // Always include main file
-  files.push('README.md');
-  
-  // Add required sub-specs
-  files.push(...glob('*.req').map(f => f.replace('.req', '')));
-  
-  // Add optional sub-specs based on flags
-  if (flags.design) files.push('DESIGN.md');
-  if (flags.testing) files.push('TESTING.md');
-  
-  // Or prompt if interactive mode
-  if (interactive) {
-    const selected = await promptForSubSpecs(glob('*.opt'));
-    files.push(...selected);
-  }
-  
-  return files;
-}
-```
-
-## Plan
-
-### Phase 1: Design & Planning
-- [ ] Define `.opt` / `.req` file convention spec
-- [ ] Design config schema for template metadata and flag mappings
-- [ ] Design flag-based interface (primary) + interactive mode (opt-in)
-- [ ] Document sub-spec template authoring guide
-
-### Phase 2: Core Implementation
-- [ ] Extend `creator.ts` to handle sub-spec templates
-- [ ] Implement file discovery (`.opt`, `.req` conventions)
-- [ ] Add explicit sub-spec flags (`--design`, `--testing`, `--implementation`)
-- [ ] Implement file filtering logic based on flags
-- [ ] Update template resolution and variable substitution
-
-### Phase 3: Interactive Mode
-- [ ] Add `--with-subs` flag for interactive mode
-- [ ] Implement interactive prompt for sub-spec selection
-- [ ] Handle multi-select UI for optional sub-specs
-
-### Phase 4: Template Updates
-- [ ] Create example templates with sub-specs
-- [ ] Update existing templates with `.opt` convention
-- [ ] Add template metadata to config.json files
-- [ ] Update default template with common sub-specs
-
-### Phase 5: Documentation & Testing
-- [ ] Update CLI documentation for sub-spec flags
-- [ ] Create sub-spec template authoring guide
-- [ ] Update AGENTS.md with new commands
-- [ ] Add integration tests for all scenarios
-- [ ] Test AI agent workflows
-
-## Test
-
-### Test Scenarios
-
-**Basic Sub-Spec Generation**:
-- [ ] `lean-spec create feat --design` generates README.md + DESIGN.md
-- [ ] `lean-spec create feat --design --testing` generates README.md + DESIGN.md + TESTING.md
-- [ ] `lean-spec create feat` (no flags) generates only README.md
-
-**Interactive Mode**:
-- [ ] `lean-spec create feat --with-subs` shows interactive prompt
-- [ ] Multi-select allows choosing multiple optional sub-specs
-- [ ] Selected sub-specs are generated correctly
-
-**Required Sub-Specs**:
-- [ ] Templates with `.req` files always generate those files
-- [ ] Required files included even without flags
-- [ ] Example: API template always includes API.md
-
-**Variable Substitution**:
-- [ ] Variables work correctly in sub-spec templates
-- [ ] Spec name, date, and custom variables populated
-- [ ] Frontmatter generated correctly in sub-specs
-
-**Edge Cases**:
-- [ ] Invalid flag ignored gracefully
-- [ ] Template without sub-specs works as before
-- [ ] Mixed `.opt` and `.req` files handled correctly
-
-### AI Agent Test Protocol
-
-```bash
-# AI agent determines feature needs DESIGN + TESTING
-# Should invoke: 
-lean-spec create feature --design --testing
-
-# Not this (requires interaction):
-lean-spec create feature --with-subs
-```
-
-### Success Criteria
-- [ ] AI agents can create specs with sub-specs programmatically
-- [ ] No breaking changes to existing `lean-spec create` behavior
-- [ ] Interactive mode provides good UX for human users
-- [ ] Template authors can easily add sub-spec support
-
-## Notes
-
-### Why AI-First Design?
-
-In AI-human co-op spec writing mode:
-- **AI agents primarily use the CLI**, not humans
-- **Interactive prompts block automation** - AI can't respond to prompts effectively
-- **Flags are declarative** - AI can determine needed sub-specs and invoke with explicit flags
-- **Humans can opt-in** - `--with-subs` flag preserves interactive experience when desired
-
-Example AI workflow:
-```
-AI analyzes task → determines needs DESIGN + TESTING sub-specs
-→ runs: lean-spec create feature --design --testing
-→ no interaction needed, continues working
-```
-
-This aligns with 072-ai-agent-first-use-workflow principles: optimize for AI, accommodate humans.
-
-### Related Specs
-
-- **073-template-engine-agents-md**: Completed Phase 1 (AGENTS.md template engine), Phase 2 split into this spec
-- **012-sub-spec-files**: Original sub-spec design and conventions (archived)
-- **072-ai-agent-first-use-workflow**: AI-first design principles
-- **074-content-at-creation**: Related but different - passing content at creation vs sub-file generation
-
-### Split from Spec 073
-
-Originally planned as Phase 2 of spec 073, split into separate spec because:
-- 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
-
-### Open Questions
-
-- Should we support nested sub-specs (e.g., `design/architecture.md`)?
-- How to handle conflicts if sub-spec file already exists?
-- Should flags be cumulative or last-wins?
-- Should we add `--all-subs` flag to include all optional sub-specs?
-- How to discover available sub-specs for a template?
-
-### Alternative Approaches Considered
-
-**1. Single `--subs` flag with comma-separated list**
-```bash
-lean-spec create feat --subs=design,testing
-```
-- ✅ More concise
-- ❌ Less discoverable (need to know names)
-- ❌ Less idiomatic (most CLIs use separate flags)
-
-**2. Always prompt for sub-specs**
-```bash
-lean-spec create feat
-? Include sub-specs? (Y/n)
-```
-- ❌ Blocks automation
-- ❌ Annoying for quick creates
-- ❌ Not AI-friendly
-
-**3. Config file to specify defaults**
-```json
-{
-  "defaults": {
-    "subSpecs": ["DESIGN.md", "TESTING.md"]
-  }
-}
-```
-- ✅ Could work for power users
-- ⚠️ Adds complexity
-- 🤔 Could be added later as enhancement
-
-**Decision**: Explicit flags as primary interface, interactive as opt-in secondary.

package/.next/standalone/packages/ui/dist/standalone/specs/079-cli-alphabetical-organization/README.md

@@ -1,196 +0,0 @@
----
-status: complete
-created: '2025-11-13'
-tags: []
-priority: medium
-created_at: '2025-11-13T13:58:57.973Z'
-updated_at: '2025-11-13T14:14:29.048Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-13T13:59:02.939Z'
-  - status: complete
-    at: '2025-11-13T14:14:29.048Z'
-completed_at: '2025-11-13T14:14:29.048Z'
-completed: '2025-11-13'
----
-
-# CLI Alphabetical Organization
-
-> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-13
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-The `cli.ts` file has grown to **702 lines** with 20+ commands, making it difficult to maintain and locate commands. Commands are registered in implementation order (not alphabetical), and the help text groupings are incomplete.
-
-**Goal**: Refactor CLI architecture to be maintainable at scale with clear organization patterns.
-
-## Problems
-
-1. **Size**: 702 lines in single file
-2. **Order**: Commands not alphabetically sorted (hard to find)
-3. **Inconsistency**: Help text missing `analyze`, `split`, `compact`, `tokens`
-4. **Duplication**: Command logic mixed with registration
-5. **Maintainability**: Adding commands requires editing massive file
-
-## Design
-
-### Pattern: Command Definition Files
-
-Move each command's CLI definition to its own command file, following commander.js patterns used by tools like `pnpm`, `turbo`, `nx`:
-
-```
-commands/
-  archive.ts        - export archiveSpec() AND archiveCommand()
-  backfill.ts       - export backfillTimestamps() AND backfillCommand()
-  create.ts         - export createSpec() AND createCommand()
-  ...
-```
-
-Each command file exports TWO things:
-1. **Business logic function** (already exists): e.g., `archiveSpec()`
-2. **NEW: Command definition function**: e.g., `archiveCommand()` that returns Commander `Command` object
-
-### Architecture
-
-**Before (current)**:
-```typescript
-// cli.ts (702 lines)
-program
-  .command('archive <spec>')
-  .description('...')
-  .action(async (spec) => {
-    await archiveSpec(spec);
-  });
-// ... 20+ more commands
-```
-
-**After (proposed)**:
-```typescript
-// cli.ts (~150 lines)
-import { registerCommands } from './commands/registry.js';
-const program = new Command();
-registerCommands(program);
-program.parse();
-
-// commands/registry.ts
-export function registerCommands(program: Command) {
-  // Alphabetically sorted
-  program.addCommand(analyzeCommand());
-  program.addCommand(archiveCommand());
-  program.addCommand(backfillCommand());
-  // ... etc
-}
-
-// commands/archive.ts
-export function archiveCommand(): Command {
-  return new Command('archive')
-    .description('Move spec to archived/')
-    .argument('<spec>', 'Spec to archive')
-    .action(async (spec) => {
-      await archiveSpec(spec);
-    });
-}
-
-export async function archiveSpec(specPath: string) {
-  // existing logic
-}
-```
-
-### Benefits
-
-1. **Alphabetical by default**: Registry enforces order
-2. **Single responsibility**: Each file = one command
-3. **Easier to add commands**: Create file, export command, add to registry
-4. **Testable**: Can test command definitions separately
-5. **Smaller files**: ~50 lines per command vs 702-line monolith
-6. **Clear structure**: Command definition co-located with logic
-
-### Command Groups in Help
-
-Update help text to use **functional grouping** with complete command list:
-
-```
-Command Groups:
-
-  Core Workflow:
-    init, create, update, archive, migrate
-    
-  Discovery & Search:
-    list, view, open, search, files
-    
-  Project Analytics:
-    board, stats, timeline, gantt, deps
-    
-  Quality & Optimization:
-    analyze, tokens, validate, check
-    
-  Advanced Editing:
-    split, compact
-    
-  Configuration:
-    templates
-    
-  Integration:
-    mcp (MCP server)
-```
-
-## Plan
-
-### Phase 1: Extract Command Definitions
-- [ ] Create `commands/registry.ts` with `registerCommands()` function
-- [ ] Update each command file (e.g., `archive.ts`) to export command definition function
-- [ ] Verify each command still exports business logic for backward compatibility
-
-### Phase 2: Refactor cli.ts
-- [ ] Import and call `registerCommands()` in `cli.ts`
-- [ ] Remove individual command registrations (keep only program setup + help text)
-- [ ] Update help text with complete alphabetical command list
-- [ ] Reduce `cli.ts` from 702 to ~150 lines
-
-### Phase 3: Validation
-- [ ] Run `pnpm build` - ensure TypeScript compiles
-- [ ] Run `node bin/lean-spec.js --help` - verify alphabetical order
-- [ ] Test sample commands: `create`, `list`, `view`, `validate`, `tokens`
-- [ ] Run existing test suite: `pnpm test:run`
-- [ ] Check command count matches (currently 20+ commands)
-
-## Test
-
-**Validation criteria**:
-- ✅ Commands appear alphabetically in `--help` output
-- ✅ Help text includes ALL commands (analyze, split, compact, tokens)
-- ✅ `cli.ts` reduced to <200 lines
-- ✅ All existing tests pass
-- ✅ No breaking changes to command behavior
-
-**Manual testing**:
-```bash
-node bin/lean-spec.js --help              # alphabetical order
-node bin/lean-spec.js create test-spec    # works
-node bin/lean-spec.js tokens 059          # works
-node bin/lean-spec.js validate            # works
-```
-
-## Notes
-
-### Alternatives Considered
-
-1. **Keep monolithic cli.ts, just alphabetize**: Doesn't solve scalability
-2. **Subcommand grouping** (e.g., `lean-spec analytics board`): Breaking change
-3. **Plugin architecture**: Over-engineering for current scale
-
-### Migration Safety
-
-- Commands already have separate files in `commands/`
-- Business logic stays unchanged
-- Only CLI registration moves
-- Backward compatible (same command syntax)
-
-### Future Enhancements
-
-- Auto-generate help text from command metadata
-- Command aliases (e.g., `ls` → `list`)
-- Plugin system for custom commands