@leanspec/ui 0.2.6-dev.20251125010539 → 0.2.6

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

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

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