@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

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

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

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