@fgv/repo-template 5.1.0-2

package/templates/.gitignore.tmpl

@@ -0,0 +1,85 @@
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Runtime data
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+
+# next.js build output
+.next
+
+# OS X temporary files
+.DS_Store
+
+# IntelliJ IDEA project files
+.idea/
+*.iml
+
+# Rush temporary files
+common/deploy/
+deploy/
+common/temp/
+common/autoinstallers/*/.npmrc
+**/.rush/temp/
+
+# Heft temporary files
+.heft
+
+# TypeScript incremental build info
+*.tsbuildinfo
+
+# built output
+lib/
+dist/
+temp/
+
+# AI workflow runtime artifacts
+.ai/tasks/active/
+.ai/tasks/completed/

package/templates/ACTIVE_DEVELOPMENT.md.tmpl

@@ -0,0 +1,58 @@
+# Active Development Guidelines
+
+This document covers guidelines specific to the libraries and applications currently under active development. These rules supplement the general coding standards.
+
+## Active Development Scope
+
+<!-- Update this section with your domain-specific projects -->
+
+### Libraries (all actively developed)
+| Library | Path | Purpose |
+|---------|------|---------|
+{{ACTIVE_LIBRARIES}}
+
+### Other Libraries (from @fgv/*, handle with care)
+The @fgv/* utility packages are consumed as published npm dependencies. Do not modify them in this repo.
+
+---
+
+## Compatibility Rules
+
+### New Libraries: No Compatibility Burden
+
+All libraries in this repo are new code. Compatibility is **not** a consideration:
+
+- **Do not** preserve deprecated values, types, or re-exports
+- **Do not** add backwards-compatibility shims or renamed aliases
+- **Do not** leave dead code "just in case"
+- If a change is necessary or appropriate, **break compatibility and fix consumers** rather than accumulating cruft
+
+---
+
+## Testing Philosophy During Active Development
+
+### Prioritize Functional Breadth Over Measured Coverage
+
+The repo requires 100% coverage to merge to `main`, but during active development:
+
+1. **Focus on functional correctness** - Write tests that verify behavior, not just hit lines
+2. **Coverage metrics come later** - Once code settles down, fill coverage gaps systematically
+3. **Don't skip tests** - Still write tests, just prioritize breadth of behavior over coverage percentage
+
+### Balance Effort vs Value
+
+- Don't spend an hour writing tests for a 5-minute fix
+- Use judgment about when tests add enough value to justify the work
+- When in doubt, ask
+
+---
+
+## General Principles
+
+### Correctness Over Convenience
+
+Prioritize correctness over ease, convenience, or brevity:
+
+- Follow all repo guidelines including Result pattern with chaining
+- Don't take shortcuts that sacrifice type safety or error handling
+- A correct, slightly verbose solution is better than a clever but fragile one

package/templates/CLAUDE.md.tmpl

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Quick Reference
+
+This is a Rush-based TypeScript monorepo. Key commands:
+
+```bash
+rush install          # Install dependencies
+rush build            # Build all projects
+rush test             # Test all projects
+rushx build/test      # Build/test current project (from project dir)
+rushx coverage        # Run with coverage
+```
+
+## Core Instructions
+
+All coding standards, testing guidelines, and review checklists are defined in the shared `.ai/` directory. These guidelines apply to all AI assistants and are the authoritative source:
+
+@.ai/instructions/CODING_STANDARDS.md
+@.ai/instructions/TESTING_GUIDELINES.md
+@.ai/instructions/CODE_REVIEW_CHECKLIST.md
+@.ai/instructions/MONOREPO_GUIDE.md
+@.ai/instructions/ACTIVE_DEVELOPMENT.md
+
+## Critical Rules Summary
+
+These rules are **absolute and non-negotiable**:
+
+1. **Never use `any` type** - Use `unknown`, branded types, or proper interfaces. Will fail CI.
+2. **Use Result pattern** - All fallible operations return `Result<T>`, not exceptions
+3. **Use Converters/Validators** - Never manual type checking with unsafe casts
+4. **100% test coverage** - Required for all code
+
+## Project Structure
+
+### Libraries (`libraries/`)
+| Library | Purpose |
+|---------|---------|
+{{PROJECT_TABLE}}
+
+## Code Review
+
+When reviewing code, use the checklist in [CODE_REVIEW_CHECKLIST.md](.ai/instructions/CODE_REVIEW_CHECKLIST.md). Key checks:
+
+- No `any` type usage (Priority 1 - blocking)
+- No manual type checking with unsafe casts (Priority 1)
+- Result pattern used correctly (Priority 1)
+- Proper error handling with context (Priority 2)
+- Follows existing codebase patterns (Priority 2)
+
+## Testing
+
+Use Result matchers from `@fgv/ts-utils-jest`:
+
+```typescript
+expect(operation()).toSucceed();
+expect(operation()).toSucceedWith(expectedValue);
+expect(operation()).toFailWith(/error pattern/i);
+expect(operation()).toSucceedAndSatisfy((result) => {
+  expect(result.property).toBe(expected);
+});
+```
+
+## Complex Task Orchestration
+
+For complex multi-phase tasks (new features, major refactoring), the task-master workflow system is available in `.claude/agents/`. This provides:
+
+- Structured requirements analysis with confirmation gates
+- Design review phases
+- Implementation coordination with specialized agents
+- Automated and manual testing phases
+- Artifact preservation for future reference
+
+Workflow templates are in `.ai/workflows/`. Use task-master for:
+- Multi-step features requiring coordination
+- Major refactoring with behavior preservation
+- Tasks benefiting from structured documentation
+
+## Claude-Specific Notes
+
+### Avoid Over-Engineering
+- Only make changes that are directly requested
+- Don't add features beyond what was asked
+- Don't refactor surrounding code during bug fixes
+- Keep solutions simple and focused
+
+### Webpack Dev Mode
+Webpack may not pick up library changes. If a web app fails to load:
+1. Kill the dev server
+2. Restart the application
+
+### Package Management
+Always use `rush add -p package-name` or `rush remove -p package-name`. Never use npm directly or edit package.json manually for dependencies.
+
+## File Organization
+
+```
+.ai/                          # Shared AI assistant instructions
+├── instructions/             # Coding standards (all AI tools)
+│   ├── CODING_STANDARDS.md
+│   ├── TESTING_GUIDELINES.md
+│   ├── CODE_REVIEW_CHECKLIST.md
+│   ├── MONOREPO_GUIDE.md
+│   └── ACTIVE_DEVELOPMENT.md
+├── workflows/                # Task orchestration workflows
+└── tasks/                    # Runtime task artifacts
+
+.claude/                      # Claude-specific configuration
+├── agents/                   # Orchestration agents (task-master, etc.)
+├── skills/                   # On-demand skills
+├── settings.json             # Permissions
+└── project/                  # Project-specific design docs
+
+CLAUDE.md                     # This file (Claude entry point)
+.windsurfrules                # Windsurf adapter → .ai/
+.cursorrules                  # Cursor adapter → .ai/
+```
+
+## Additional Resources
+
+- Project design docs are in `.claude/project/`
+- Workflow templates are in `.ai/workflows/`

package/templates/command-line.json.tmpl

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/command-line.schema.json",
+  "commands": [
+    {
+      "name": "prettier",
+      "commandKind": "global",
+      "summary": "Used by the pre-commit git hook to invoke prettier",
+      "safeForSimultaneousRushProcesses": true,
+      "autoinstallerName": "rush-prettier",
+      "shellCommand": "pretty-quick --staged"
+    },
+    {
+      "name": "test",
+      "commandKind": "bulk",
+      "summary": "Run tests for all projects in the monorepo",
+      "description": "Runs the 'test' npm script for each project in the monorepo according to dependency order. Projects without a test script will be skipped.",
+      "safeForSimultaneousRushProcesses": false,
+      "enableParallelism": true,
+      "ignoreDependencyOrder": false,
+      "ignoreMissingScript": true,
+      "allowWarningsInSuccessfulBuild": false,
+      "incremental": false
+    },
+    {
+      "name": "lint",
+      "commandKind": "bulk",
+      "summary": "Run linting for all projects in the monorepo",
+      "description": "Runs the 'lint' npm script for each project in the monorepo according to dependency order. Projects without a lint script will be skipped.",
+      "safeForSimultaneousRushProcesses": false,
+      "enableParallelism": true,
+      "ignoreDependencyOrder": false,
+      "ignoreMissingScript": true,
+      "allowWarningsInSuccessfulBuild": false,
+      "incremental": false
+    },
+    {
+      "name": "build-docs",
+      "commandKind": "bulk",
+      "summary": "Build generated documentation for all projects in the monorepo",
+      "description": "Runs the 'build-docs' npm script for each project in the monorepo according to dependency order. Projects without a build-docs script will be skipped.",
+      "safeForSimultaneousRushProcesses": false,
+      "enableParallelism": true,
+      "ignoreDependencyOrder": false,
+      "ignoreMissingScript": true,
+      "allowWarningsInSuccessfulBuild": false,
+      "incremental": false
+    }
+  ],
+  "parameters": []
+}

package/templates/package.json.tmpl

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@microsoft/rush": "^5.168.0"
+  }
+}

package/templates/version-policies.json.tmpl

@@ -0,0 +1,8 @@
+[
+  {
+    "definitionName": "lockStepVersion",
+    "policyName": "{{VERSION_POLICY_NAME}}",
+    "version": "{{VERSION}}",
+    "nextBump": "minor"
+  }
+]

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./node_modules/@rushstack/heft-node-rig/profiles/default/tsconfig-base.json",
+  "compilerOptions": {
+    "resolveJsonModule": true,
+    "types": ["node"]
+  }
+}