lean-spec 0.2.5 → 0.2.6-dev.20251125010539

package/templates/examples/dashboard-widgets/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "dashboard-widgets-demo",
+  "version": "1.0.0",
+  "description": "React Dashboard for LeanSpec Tutorial 2",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "keywords": ["leanspec", "tutorial", "demo"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.2.1",
+    "vite": "^5.0.0"
+  }
+}

package/templates/examples/dashboard-widgets/src/App.css

@@ -0,0 +1,20 @@
+.app {
+  padding: 20px;
+  max-width: 1400px;
+  margin: 0 auto;
+}
+
+header {
+  margin-bottom: 30px;
+}
+
+header h1 {
+  margin: 0 0 5px 0;
+  color: #333;
+}
+
+header p {
+  margin: 0;
+  color: #666;
+  font-size: 14px;
+}

package/templates/examples/dashboard-widgets/src/App.jsx

@@ -0,0 +1,16 @@
+import Dashboard from './components/Dashboard';
+import './App.css';
+
+function App() {
+  return (
+    <div className="app">
+      <header>
+        <h1>Analytics Dashboard</h1>
+        <p>Demo for LeanSpec Tutorial 2</p>
+      </header>
+      <Dashboard />
+    </div>
+  );
+}
+
+export default App;

package/templates/examples/dashboard-widgets/src/components/Dashboard.css

@@ -0,0 +1,17 @@
+.dashboard-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: 20px;
+}
+
+@media (min-width: 768px) {
+  .dashboard-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (min-width: 1200px) {
+  .dashboard-grid {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}

package/templates/examples/dashboard-widgets/src/components/Dashboard.jsx

@@ -0,0 +1,15 @@
+import StatsWidget from './widgets/StatsWidget';
+import ChartWidget from './widgets/ChartWidget';
+import './Dashboard.css';
+
+function Dashboard() {
+  return (
+    <div className="dashboard-grid">
+      <StatsWidget />
+      <ChartWidget />
+      {/* TODO: Add new widgets here */}
+    </div>
+  );
+}
+
+export default Dashboard;

package/templates/examples/dashboard-widgets/src/components/WidgetWrapper.css

@@ -0,0 +1,23 @@
+.widget {
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+  overflow: hidden;
+}
+
+.widget-header {
+  padding: 15px 20px;
+  border-bottom: 1px solid #eee;
+  background: #fafafa;
+}
+
+.widget-header h3 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  color: #333;
+}
+
+.widget-body {
+  padding: 20px;
+}

package/templates/examples/dashboard-widgets/src/components/WidgetWrapper.jsx

@@ -0,0 +1,16 @@
+import './WidgetWrapper.css';
+
+function WidgetWrapper({ title, children }) {
+  return (
+    <div className="widget">
+      <div className="widget-header">
+        <h3>{title}</h3>
+      </div>
+      <div className="widget-body">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+export default WidgetWrapper;

package/templates/examples/dashboard-widgets/src/components/widgets/ChartWidget.css

@@ -0,0 +1,33 @@
+.chart {
+  height: 200px;
+}
+
+.chart-bars {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-around;
+  height: 100%;
+  gap: 8px;
+}
+
+.chart-bar-container {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  height: 100%;
+}
+
+.chart-bar {
+  width: 100%;
+  background: linear-gradient(to top, #2563eb, #60a5fa);
+  border-radius: 4px 4px 0 0;
+  transition: height 0.3s ease;
+  min-height: 4px;
+}
+
+.chart-label {
+  margin-top: 8px;
+  font-size: 11px;
+  color: #666;
+}

package/templates/examples/dashboard-widgets/src/components/widgets/ChartWidget.jsx

@@ -0,0 +1,28 @@
+import WidgetWrapper from '../WidgetWrapper';
+import { getChartData } from '../../utils/mockData';
+import './ChartWidget.css';
+
+function ChartWidget() {
+  const data = getChartData();
+  const maxValue = Math.max(...data.map(d => d.value));
+  
+  return (
+    <WidgetWrapper title="Activity Trend">
+      <div className="chart">
+        <div className="chart-bars">
+          {data.map((item, index) => (
+            <div key={index} className="chart-bar-container">
+              <div 
+                className="chart-bar"
+                style={{ height: `${(item.value / maxValue) * 100}%` }}
+              />
+              <div className="chart-label">{item.label}</div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </WidgetWrapper>
+  );
+}
+
+export default ChartWidget;

package/templates/examples/dashboard-widgets/src/components/widgets/StatsWidget.css

@@ -0,0 +1,24 @@
+.stats-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 15px;
+}
+
+.stat-item {
+  text-align: center;
+  padding: 10px;
+}
+
+.stat-value {
+  font-size: 28px;
+  font-weight: bold;
+  color: #2563eb;
+  margin-bottom: 5px;
+}
+
+.stat-label {
+  font-size: 12px;
+  color: #666;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}

package/templates/examples/dashboard-widgets/src/components/widgets/StatsWidget.jsx

@@ -0,0 +1,22 @@
+import WidgetWrapper from '../WidgetWrapper';
+import { getStats } from '../../utils/mockData';
+import './StatsWidget.css';
+
+function StatsWidget() {
+  const stats = getStats();
+  
+  return (
+    <WidgetWrapper title="Quick Stats">
+      <div className="stats-grid">
+        {stats.map((stat, index) => (
+          <div key={index} className="stat-item">
+            <div className="stat-value">{stat.value}</div>
+            <div className="stat-label">{stat.label}</div>
+          </div>
+        ))}
+      </div>
+    </WidgetWrapper>
+  );
+}
+
+export default StatsWidget;

package/templates/examples/dashboard-widgets/src/index.css

@@ -0,0 +1,13 @@
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+    sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  background: #f5f5f5;
+}
+
+* {
+  box-sizing: border-box;
+}

package/templates/examples/dashboard-widgets/src/main.jsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

package/templates/examples/dashboard-widgets/src/utils/mockData.js

@@ -0,0 +1,30 @@
+/**
+ * Mock data generators for dashboard widgets
+ */
+
+export function getStats() {
+  return [
+    { label: 'Users', value: '2,453' },
+    { label: 'Revenue', value: '$12.5K' },
+    { label: 'Orders', value: '186' },
+    { label: 'Growth', value: '+23%' },
+  ];
+}
+
+export function getChartData() {
+  return [
+    { label: 'Mon', value: 45 },
+    { label: 'Tue', value: 62 },
+    { label: 'Wed', value: 38 },
+    { label: 'Thu', value: 71 },
+    { label: 'Fri', value: 55 },
+    { label: 'Sat', value: 28 },
+    { label: 'Sun', value: 34 },
+  ];
+}
+
+// TODO: Add more mock data generators for new widgets
+// Example:
+// export function getActivityFeed() { ... }
+// export function getPerformanceMetrics() { ... }
+// export function getQuickActions() { ... }

package/templates/examples/dashboard-widgets/vite.config.js

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+});

package/templates/standard/AGENTS.md

@@ -0,0 +1,113 @@
+# AI Agent Instructions
+
+## Project: {project_name}
+
+Lightweight spec methodology for AI-powered development.
+
+## Core Rules
+
+1. **Read README.md first** - Understand project context
+2. **Check specs/** - Review existing specs before starting
+3. **Use `lean-spec --help`** - When unsure about commands, check the built-in help
+4. **Follow LeanSpec principles** - Clarity over documentation
+5. **Keep it minimal** - If it doesn't add clarity, cut it
+6. **NEVER manually edit system-managed frontmatter** - Fields like `status`, `priority`, `tags`, `assignee`, `transitions`, `created_at`, `updated_at`, `completed_at`, `depends_on`, `related` are system-managed. Always use `lean-spec update`, `lean-spec link`, `lean-spec unlink`, or `lean-spec create` commands. Manual edits will cause metadata corruption and tracking issues.
+7. **Never use nested code blocks** - Markdown doesn't support code blocks within code blocks. If you need to show code examples in documentation, use indentation or describe the structure instead of nesting backticks.
+
+## When to Use Specs
+
+Write a spec for:
+- Features affecting multiple parts of the system
+- Breaking changes or significant refactors
+- Design decisions needing team alignment
+
+Skip specs for:
+- Bug fixes
+- Trivial changes
+- Self-explanatory refactors
+
+## Essential Commands
+
+**Quick Reference** (for full details, see `lean-spec --help`):
+
+**Discovery:**
+- `lean-spec list` - See all specs
+- `lean-spec search "<query>"` - Find relevant specs
+
+**Working with specs:**
+- `lean-spec create <name>` - Create new spec
+- `lean-spec update <spec> --status <status>` - Update status (REQUIRED - never edit frontmatter manually)
+- `lean-spec update <spec> --priority <priority>` - Update priority
+- `lean-spec deps <spec>` - Show dependency graph
+- `lean-spec tokens <spec>` - Count tokens for context management
+
+**Project overview:**
+- `lean-spec board` - Kanban view with project health
+- `lean-spec stats` - Quick project metrics
+
+**When in doubt:** Run `lean-spec --help` or `lean-spec <command> --help` to discover commands.
+
+## Spec Relationships
+
+LeanSpec has two types of relationships:
+
+### `related` - Bidirectional Soft Reference
+Informational relationship between specs. Automatically shown from both sides.
+
+**Use when:** Specs cover related topics, work is coordinated but not blocking.
+
+### `depends_on` - Directional Blocking Dependency
+Hard dependency - spec cannot start until dependencies complete.
+
+**Use when:** Spec truly cannot start until another completes, work order matters.
+
+**Best Practice:** Use `related` by default. Reserve `depends_on` for true blocking dependencies.
+
+## SDD Workflow
+
+1. **Discover** - Check existing specs with `lean-spec list`
+2. **Plan** - Create spec with `lean-spec create <name>` (status: `planned`)
+3. **Start Work** - Run `lean-spec update <spec> --status in-progress` before implementing
+4. **Implement** - Write code/docs, keep spec in sync as you learn
+5. **Complete** - Run `lean-spec update <spec> --status complete` after implementation done
+6. **Document** - Report progress and document changes into the spec
+
+**CRITICAL - What "Work" Means:**
+- ❌ **NOT**: Creating/writing the spec document itself
+- ✅ **YES**: Implementing what the spec describes (code, docs, features, etc.)
+
+**Frontmatter Editing Rules:**
+- **NEVER manually edit**: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on`, `related`
+- **Use CLI commands**: `lean-spec update`, `lean-spec link`, `lean-spec unlink`
+
+**Note on Archiving**: Archive specs when they're no longer actively referenced (weeks/months after completion), not immediately. Use `lean-spec archive <spec>` to move old/stale specs to `archived/` directory.
+
+## Quality Standards
+
+- Code is clear and maintainable
+- Tests cover critical paths
+- Specs stay in sync with implementation
+- **Status tracking is mandatory:**
+  - Specs start as `planned` after creation
+  - Mark `in-progress` BEFORE starting implementation work
+  - Mark `complete` AFTER implementation is finished
+  - **Remember**: Status tracks implementation, not spec document completion
+  - Never leave specs with stale status
+
+## Spec Complexity Guidelines
+
+**Token Thresholds:**
+- **<2,000 tokens**: ✅ Optimal
+- **2,000-3,500 tokens**: ✅ Good
+- **3,500-5,000 tokens**: ⚠️ Warning - Consider splitting
+- **>5,000 tokens**: 🔴 Should split
+
+**Check with:** `lean-spec tokens <spec>`
+
+**When to split:** >3,500 tokens, multiple concerns, takes >10 min to read
+
+**How to split:** Use sub-specs or split into related specs with `lean-spec link --related`
+
+---
+
+**Remember**: LeanSpec is a mindset, not a rulebook. When in doubt, keep it simple and use `lean-spec --help` to discover features as needed.

package/templates/standard/README.md

@@ -1,16 +1,17 @@
 # Standard Template
 
-Recommended for most projects. Includes AI agent instructions and sensible defaults.
+Recommended for most projects. Single-file specs with AI agent instructions.
 
 ## What's Included
 
 - **AGENTS.md** - Instructions for AI coding assistants
-- Spec folder structure
+- **Single-file spec template** - All sections in one README.md
 - Opinionated defaults for fast iteration
 
 ## When to Use
 
 - Solo developers or small teams
+- Simple to moderate complexity specs
 - Want AI agent integration
 - Need clear but not heavy-weight process
 
@@ -22,3 +23,4 @@ Keep it lean. Write specs for features that need clarity. Skip them for obvious
 
 1. Customize AGENTS.md for your project
 2. Create your first spec: `lean-spec create my-feature`
+