@leanspec/ui 0.2.5 → 0.2.6-dev.20251125015611

package/.next/standalone/packages/ui/dist/standalone/specs/archived/013-custom-spec-templates/README.md

@@ -1,413 +0,0 @@
----
-status: complete
-created: '2025-11-02'
-tags:
-  - feature
-  - templates
-  - cli
-  - customization
-priority: high
-completed: '2025-11-02'
----
-
-# Customization-First Template System
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-02 · **Tags**: feature, templates, cli, customization
-
-## Overview
-
-**Core Principle**: LeanSpec's whole purpose is to ensure full control for users over the SDD process with AI agents. Customization must be a first-class citizen, not an afterthought.
-
-**Current Problem**: Templates are locked in the npm package. Users cannot customize spec templates, frontmatter fields, variables, or template directory structure without modifying package files (which are lost on updates).
-
-**Solution**: Invert the architecture - templates live in the user's project (`.lean-spec/templates/`), not the npm package. Package templates become initialization starters only.
-
-## Current Architecture (Template-Centric) ❌
-
-```
-npm package (read-only)
-└── templates/
-    ├── minimal/
-    ├── standard/
-    └── enterprise/
-
-User's project
-└── .lean-spec/
-    └── config.json   # Only stores template name reference
-```
-
-**Problems:**
-- Templates in npm package are immutable
-- No way to add custom templates
-- No way to customize spec structure
-- Users don't own their workflow
-
-## New Architecture (User-Centric) ✅
-
-```
-User's project
-└── .lean-spec/
-    ├── config.json
-    └── templates/
-        ├── spec-template.md      # Default (copied from npm on init)
-        ├── api-spec.md           # User's custom API template
-        ├── rfc.md                # User's custom RFC template
-        └── ...                   # Any custom templates
-
-npm package (initialization only)
-└── templates/
-    ├── minimal/
-    ├── standard/
-    └── enterprise/
-```
-
-**Benefits:**
-- ✅ Users own and control all templates
-- ✅ Can customize immediately after init
-- ✅ Can add unlimited custom templates
-- ✅ Templates are versioned with project
-- ✅ No dependency on npm package structure
-- ✅ True customization-first
-
-## Design
-
-### 1. Template Lifecycle
-
-**Phase 1: Initialization (`lean-spec init`)**
-```bash
-lean-spec init
-# User chooses template: minimal/standard/enterprise
-# Template copied from npm package to .lean-spec/templates/spec-template.md
-# User immediately has full control
-```
-
-**Phase 2: Customization (User's choice)**
-```bash
-# Edit default template
-vim .lean-spec/templates/spec-template.md
-
-# Add custom templates
-cp .lean-spec/templates/spec-template.md .lean-spec/templates/api-spec.md
-# Edit api-spec.md for API-specific structure
-
-# Register in config
-lean-spec templates add api api-spec.md
-```
-
-**Phase 3: Usage**
-```bash
-# Use default template
-lean-spec create my-feature
-
-# Use custom template
-lean-spec create my-api --template=api
-```
-
-### 2. Enhanced Config Structure
-
-```json
-{
-  "template": "spec-template.md",
-  "templates": {
-    "default": "spec-template.md",
-    "api": "api-spec.md",
-    "rfc": "rfc.md"
-  },
-  "specsDir": "specs",
-  "structure": {
-    "pattern": "{date}/{seq}-{name}/",
-    "dateFormat": "YYYYMMDD",
-    "sequenceDigits": 3,
-    "defaultFile": "README.md"
-  },
-  "frontmatter": {
-    "required": ["status", "created"],
-    "optional": ["tags", "priority", "assignee", "reviewer"],
-    "custom": {
-      "epic": "string",
-      "sprint": "number",
-      "estimate": "string",
-      "milestone": "string"
-    }
-  },
-  "variables": {
-    "project_name": "my-project",
-    "team": "platform",
-    "author": "${git_user}",
-    "repo": "${git_repo}"
-  }
-}
-```
-
-### 3. New Commands
-
-```bash
-# List available templates in project
-lean-spec templates list
-
-# Add/register a template
-lean-spec templates add <name> <file>
-# Example: lean-spec templates add api api-spec.md
-
-# Show template content
-lean-spec templates show <name>
-
-# Remove template
-lean-spec templates remove <name>
-
-# Copy existing template as starting point
-lean-spec templates copy <source> <target>
-# Example: lean-spec templates copy default api-spec
-```
-
-### 4. Template Resolution
-
-**In `create.ts`:**
-
-```typescript
-async function resolveTemplate(
-  templateName: string | undefined, 
-  config: LeanSpecConfig, 
-  cwd: string
-): Promise<string> {
-  const templatesDir = path.join(cwd, '.lean-spec', 'templates');
-  
-  // 1. Check for --template flag
-  if (templateName && config.templates?.[templateName]) {
-    const templateFile = config.templates[templateName];
-    const templatePath = path.join(templatesDir, templateFile);
-    
-    try {
-      await fs.access(templatePath);
-      return templatePath;
-    } catch {
-      console.error(chalk.red(`Template not found: ${templateName}`));
-      console.error(chalk.gray(`Looking for: ${templatePath}`));
-      console.error(chalk.gray(`Available templates: ${Object.keys(config.templates || {}).join(', ')}`));
-      process.exit(1);
-    }
-  }
-  
-  // 2. Use default template from config
-  const defaultTemplate = config.template || 'spec-template.md';
-  const defaultPath = path.join(templatesDir, defaultTemplate);
-  
-  try {
-    await fs.access(defaultPath);
-    return defaultPath;
-  } catch {
-    // Error - templates should exist after init
-    console.error(chalk.red('No templates found!'));
-    console.error(chalk.gray('Expected: .lean-spec/templates/spec-template.md'));
-    console.error(chalk.yellow('Run: lean-spec init'));
-    process.exit(1);
-  }
-}
-```
-
-### 5. Custom Frontmatter Support
-
-**Extend frontmatter parser to support custom fields:**
-
-```typescript
-interface FrontmatterConfig {
-  required: string[];
-  optional: string[];
-  custom?: Record<string, 'string' | 'number' | 'boolean' | 'array'>;
-}
-
-// Validate and parse custom fields
-function parseCustomFrontmatter(
-  frontmatter: Record<string, any>,
-  config: FrontmatterConfig
-): Record<string, any> {
-  const custom: Record<string, any> = {};
-  
-  if (config.custom) {
-    for (const [key, type] of Object.entries(config.custom)) {
-      if (key in frontmatter) {
-        // Type validation and coercion
-        custom[key] = coerceType(frontmatter[key], type);
-      }
-    }
-  }
-  
-  return custom;
-}
-```
-
-**Usage:**
-```bash
-# Create with custom frontmatter
-lean-spec create my-feature --epic=PLAT-123 --sprint=42
-
-# Update custom fields
-lean-spec update specs/20251102/001-my-feature --epic=PLAT-456
-```
-
-### 6. Variable Substitution System
-
-**Built-in variables:**
-- `{name}` - Spec name
-- `{date}` - Creation date
-- `{project_name}` - From package.json or config
-- `{author}` - From git config
-- `{git_user}` - Git username
-- `{git_repo}` - Git repository name
-- `{team}` - From config
-
-**Custom variables from config:**
-```json
-{
-  "variables": {
-    "company": "Acme Corp",
-    "department": "Platform Engineering",
-    "default_reviewer": "alice"
-  }
-}
-```
-
-**In templates:**
-```markdown
----
-status: planned
-created: {date}
-assignee: {author}
-reviewer: {default_reviewer}
-epic: {epic}
----
-
-# {name}
-
-**Project**: {project_name}  
-**Team**: {team}  
-**Company**: {company}
-
-...
-```
-
-## Implementation Plan
-
-### Phase 1: Core Template System (Week 1)
-- [ ] Create `.lean-spec/templates/` directory on init
-- [ ] Copy chosen template to `.lean-spec/templates/spec-template.md`
-- [ ] Update `create.ts` to use project templates (remove package fallback)
-- [ ] Implement template resolution logic
-- [ ] Update `init.ts` to set up templates directory
-
-### Phase 2: Template Management (Week 1)
-- [ ] Implement `lean-spec templates list` command
-- [ ] Implement `lean-spec templates add <name> <file>` command
-- [ ] Implement `lean-spec templates show <name>` command
-- [ ] Implement `lean-spec templates copy <source> <target>` command
-- [ ] Implement `lean-spec templates remove <name>` command
-- [ ] Add `--template` flag to `create` command
-
-### Phase 3: Custom Frontmatter (Week 2)
-- [ ] Extend config.json schema with `frontmatter.custom`
-- [ ] Update frontmatter parser to handle custom fields
-- [ ] Add validation and type coercion
-- [ ] Support custom fields in `create` command
-- [ ] Support custom fields in `update` command
-- [ ] Update `list` command to show custom fields
-
-### Phase 4: Variable System (Week 2)
-- [ ] Implement built-in variable resolution
-- [ ] Support custom variables from config
-- [ ] Add git integration for author/repo variables
-- [ ] Apply variables during template rendering
-- [ ] Document all available variables
-
-### Phase 5: Documentation & Dogfooding (Week 2)
-- [ ] Update README.md with customization examples
-- [ ] Update AGENTS.md with template customization workflow
-## Test Cases
-
-### Template Resolution
-- [ ] Uses project template when exists
-- [ ] Errors when template missing (no fallback)
-- [ ] Resolves --template flag correctly
-- [ ] Errors gracefully with helpful message when template not found
-
-### Template Management
-- [ ] `templates list` shows all project templates
-- [ ] `templates add` registers new template
-- [ ] `templates copy` creates copy with new name
-- [ ] `templates remove` unregisters template
-- [ ] Config stays in sync with template commands
-
-### Custom Frontmatter
-- [ ] Parses custom fields from config
-- [ ] Validates field types
-- [ ] Accepts custom fields in create command
-- [ ] Updates custom fields in update command
-- [ ] Lists specs with custom fields
-
-### Variables
-- [ ] Substitutes built-in variables
-- [ ] Substitutes custom variables from config
-- [ ] Resolves git variables correctly
-- [ ] Handles missing variables gracefully
-
-### Init Process
-- [ ] Creates .lean-spec/templates/ directory
-- [ ] Copies chosen template to spec-template.md
-- [ ] Sets up config with templates section
-- [ ] Works with merge/backup/skip for AGENTS.md
-
-## Breaking Changes
-
-**This is a breaking change** - but since lean-spec is new and only dogfooding itself, this is acceptable.
-
-**What breaks:**
-- Projects initialized with old version will have no `.lean-spec/templates/`
-- `lean-spec create` will fail with clear error message
-- Solution: Run `lean-spec init` again or manually create templates directory
-
-**Migration for lean-spec itself:**
-1. Create `.lean-spec/templates/` directory
-2. Copy current package template to `.lean-spec/templates/spec-template.md`
-3. Update config to include templates section
-4. Test creating new specstinuing with: lean-spec create my-feature
-```
-
-**Manual migration:**
-```bash
-lean-spec templates migrate
-```
-
-## Non-Goals (for v1)
-
-- Template inheritance/composition system
-- Template marketplace or sharing
-- Template validation/linting tools
-- Visual template editor
-- Template versioning system
-- Hot-reloading of templates
-- Backward compatibility with pre-templates projects
-
-These can be added later based on user feedback.ly after init
-- ✅ Users can add unlimited custom templates
-- ✅ Users can define custom frontmatter fields
-- ✅ Users can define custom variables
-- ✅ Zero breaking changes for existing projects
-- ✅ Documentation clearly shows customization options
-
-## Notes
-
-**Why this is critical:**
-
-LeanSpec's entire value proposition is about **giving users control** over their SDD process. If templates are locked in npm packages, we're contradicting our core principle. This redesign makes customization the default, not an advanced feature.
-
-**Philosophy alignment:**
-
-> "LeanSpec is a mindset. Adapt these guidelines to what actually helps."
-
-This only works if users can actually adapt the system. Moving templates to `.lean-spec/templates/` makes customization tangible and discoverable.
-
-**Learning from other tools:**
-- **Next.js**: `eject` is available but discouraged (creates maintenance burden)
-- **Create React App**: Same - eject is one-way, creates complexity
-- **Prettier/Tailwind**: Configs in project - users have full control ✅
-
-We should follow the Prettier/Tailwind model: sensible defaults, full customization in user's project.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/015-npm-publishing/README.md

@@ -1,255 +0,0 @@
----
-status: complete
-created: 2025-11-02
-tags: [release, publishing, distribution]
-priority: high
----
-
-# npm-publishing
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-02
-
-## Overview
-
-Publish LeanSpec to npm registry to make it available for global installation and use by external teams. Currently the package is only used locally for dogfooding.
-
-**Why Now:**
-- Core features are stable (13 specs completed)
-- Test suite is comprehensive (62 tests passing)
-- Template system redesign is complete
-- No compilation errors
-- Ready for external validation and feedback
-
-**What Success Looks Like:**
-- Package published to npm as `lean-spec`
-- Users can install via `npm install -g lean-spec` or `pnpm add -D lean-spec`
-- Semantic versioning established
-- Changelog maintained
-- Clear upgrade path for future versions
-
-## Design
-
-### 1. Pre-Publishing Checklist
-
-**Package.json Audit:**
-- ✅ Name: `lean-spec` (check npm availability)
-- ✅ Version: Currently `0.1.0` (appropriate for initial release)
-- ✅ Description: Clear and concise
-- ✅ Keywords: Good SEO (spec, ai, agent, sdd)
-- ✅ License: MIT
-- ⚠️ Repository: Add GitHub repo URL
-- ⚠️ Homepage: Add project homepage
-- ⚠️ Bugs: Add issues URL
-- ⚠️ Author: Verify author info
-- ✅ Bin: `lean-spec` command defined
-
-**Build Configuration:**
-- ✅ TypeScript compilation working
-- ✅ tsup building correctly
-- ⚠️ Files field: Specify what to publish (bin/, dist/, templates/)
-- ⚠️ .npmignore: Exclude dev files (src/, coverage/, .lean-spec/, specs/)
-
-**Documentation:**
-- ✅ README.md comprehensive
-- ⚠️ CHANGELOG.md: Create initial changelog
-- ✅ LICENSE: MIT license present
-- ✅ CONTRIBUTING.md: Present
-
-### 2. Package Structure
-
-```
-lean-spec/
-├── bin/              # CLI entry point ✅
-│   └── lspec.js
-├── dist/             # Compiled JS (tsup output) ✅
-│   ├── cli.js
-│   ├── commands/
-│   └── ...
-├── templates/        # Built-in templates ✅
-│   ├── minimal/
-│   ├── standard/
-│   └── enterprise/
-├── package.json      # Package metadata ⚠️
-├── README.md         # Documentation ✅
-├── LICENSE           # MIT license ✅
-└── CHANGELOG.md      # Version history ❌
-```
-
-**What NOT to publish:**
-- `src/` (TypeScript source - only dist/)
-- `coverage/` (test coverage reports)
-- `.lean-spec/` (project's own specs)
-- `specs/` (development specs)
-- `*.test.ts` files
-- Development configs (vitest.config.ts, tsconfig.json, etc.)
-
-### 3. Versioning Strategy
-
-Follow semantic versioning (semver):
-- `0.1.0` - Initial public release (current)
-- `0.x.y` - Pre-1.0 (breaking changes allowed in minor versions)
-- `1.0.0` - First stable release (after community feedback)
-
-**Version Milestones:**
-- `0.1.0` - Initial release (core features)
-- `0.2.0` - Custom frontmatter + variables complete
-- `0.3.0` - VS Code extension ready
-- `1.0.0` - Production-ready, API stable
-
-### 4. Publishing Process
-
-**Manual Publishing (v1):**
-```bash
-# 1. Update version
-pnpm version patch|minor|major
-
-# 2. Build
-pnpm build
-
-# 3. Test build
-npm pack --dry-run
-
-# 4. Review package contents
-tar -tzf lean-spec-*.tgz
-
-# 5. Publish
-npm publish
-
-# 6. Tag release
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-**Automated Publishing (v2 - future):**
-- GitHub Actions workflow on tag push
-- Automated tests before publish
-- Release notes generation
-
-### 5. Post-Publishing Tasks
-
-- [ ] Add npm badge to README
-- [ ] Announce on relevant communities (if appropriate)
-- [ ] Monitor npm stats
-- [ ] Set up GitHub releases
-- [ ] Create installation documentation
-
-## Plan
-
-### Phase 1: Package Preparation
-- [x] Check npm name availability: `npm view lean-spec` ✅ Available
-- [x] Update package.json with repository, homepage, bugs URLs
-- [x] Add `files` field to package.json (include dist, bin, templates)
-- [x] Create .npmignore (exclude src, coverage, specs, .lean-spec)
-- [x] Create CHANGELOG.md with 0.1.0 entry
-- [x] Verify author and license information
-- [x] Test local installation: `npm link`
-
-### Phase 2: Build Verification
-- [x] Clean build: `rm -rf dist && pnpm build` ✅ Success
-- [x] Verify dist/ contains all necessary files
-- [x] Test CLI after build: `node bin/lspec.js --help`
-- [x] Run full test suite: `pnpm test:run` ✅ 62 tests passing
-- [x] Check for TypeScript errors: `pnpm typecheck` ✅ No errors
-- [x] Dry run pack: `npm pack --dry-run` ✅ 58.6 KB package
-- [x] Review package contents: `tar -tzf lean-spec-*.tgz`
-
-### Phase 3: Publishing
-- [ ] Create npm account (if needed)
-- [ ] Login: `npm login`
-- [ ] Publish: `npm publish` (or `npm publish --access public` if scoped)
-- [ ] Verify on npm: https://www.npmjs.com/package/lean-spec
-- [ ] Test installation: `npm install -g lean-spec`
-- [ ] Test CLI works: `lean-spec --version`
-
-### Phase 4: Git Tagging & Release
-- [ ] Tag release: `git tag v0.1.0`
-- [ ] Push tag: `git push origin v0.1.0`
-- [ ] Create GitHub release with changelog
-- [ ] Add release notes (copy from CHANGELOG.md)
-
-### Phase 5: Documentation Updates
-- [ ] Add npm installation badge to README
-- [ ] Update README with installation instructions
-- [ ] Add "Installing from npm" section
-- [ ] Document upgrade process
-- [ ] Add troubleshooting section
-
-## Test
-
-### Pre-Publishing Tests
-- [x] `npm pack --dry-run` succeeds without errors ✅
-- [x] Package size is reasonable (< 5MB) ✅ 58.6 KB
-- [x] All necessary files are included in tarball ✅
-- [x] No sensitive files included (.env, .lean-spec/, specs/) ✅
-- [x] bin/lspec.js has correct shebang: `#!/usr/bin/env node` ✅
-
-### Post-Publishing Tests
-- [x] `npm link` for local testing ✅
-- [x] `lean-spec --version` shows correct version ✅ 0.1.0
-- [x] `lean-spec --help` displays help ✅
-- [x] `lean-spec init` works in fresh directory ✅
-- [x] `lean-spec create test` creates a spec ✅
-- [x] All commands work after global install ✅
-- [ ] `npm install -g lean-spec` works (after publishing)
-- [ ] Works on macOS, Linux (test in CI)
-
-### Documentation Tests
-- [ ] README on npm page renders correctly
-- [ ] Installation instructions work
-- [ ] Quick start guide works for new users
-
-## Notes
-
-**Preparation Complete - 2025-11-02:**
-- ✅ Package name `lean-spec` confirmed available on npm
-- ✅ package.json updated with all metadata (repository, homepage, bugs, files)
-- ✅ .npmignore created to exclude dev files
-- ✅ CHANGELOG.md created with comprehensive v0.1.0 entry
-- ✅ Clean build successful (58.6 KB package, 254.8 KB unpacked)
-- ✅ All 62 tests passing with no TypeScript errors
-- ✅ Local installation tested with `npm link`
-- ✅ All CLI commands verified working (init, create, list, etc.)
-
-**Ready for Publishing:**
-The package is fully prepared and tested. Run `npm publish` when ready to release v0.1.0 to the npm registry.
-
-**NPM Scope Considerations:**
-- Unscoped: `lean-spec` (requires name availability)
-- Scoped: `@codervisor/lean-spec` (guaranteed availability under your org)
-- Recommendation: Try unscoped first, fall back to scoped
-
-**Package.json Files Field Example:**
-```json
-{
-  "files": [
-    "bin/",
-    "dist/",
-    "templates/",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ]
-}
-```
-
-**.npmignore Example:**
-```
-src/
-coverage/
-specs/
-.lean-spec/
-*.test.ts
-vitest.config.ts
-tsconfig.json
-tsup.config.ts
-.git/
-.github/
-```
-
-**Breaking Changes:**
-- None for v0.1.0 (initial release)
-- For future versions, document in CHANGELOG.md
-
-**References:**
-- npm docs: https://docs.npmjs.com/cli/v10/commands/npm-publish
-- Semantic versioning: https://semver.org/