codeswarm 0.1.0

package/dashboard/server.js

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+const express = require('express');
+const http = require('http');
+const { WebSocketServer } = require('ws');
+const chokidar = require('chokidar');
+const fs = require('fs');
+const path = require('path');
+
+// ─── Parse args ───────────────────────────────────────
+const args = process.argv.slice(2);
+let projectDir = '';
+let sessionId = '';
+let port = 3777;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--project' || args[i] === '-p') projectDir = args[++i];
+  else if (args[i] === '--session' || args[i] === '-s') sessionId = args[++i];
+  else if (args[i] === '--port') port = parseInt(args[++i], 10);
+  else if (args[i] === '--help' || args[i] === '-h') {
+    console.log(`
+Agentic Dashboard — Real-time monitoring for multi-agent coordinator
+
+Usage:
+  node server.js --project <path> [--session <id>] [--port 3777]
+
+Options:
+  --project, -p   Path to project with .codeswarm/ directory (required)
+  --session, -s   Specific session ID (default: latest)
+  --port          Server port (default: 3777)
+`);
+    process.exit(0);
+  }
+}
+
+if (!projectDir) {
+  console.error('ERROR: --project <path> is required');
+  process.exit(1);
+}
+
+projectDir = path.resolve(projectDir);
+const agenticDir = path.join(projectDir, '.codeswarm');
+const sessionsDir = path.join(agenticDir, 'sessions');
+
+if (!fs.existsSync(agenticDir)) {
+  console.error(`ERROR: ${agenticDir} does not exist`);
+  process.exit(1);
+}
+
+// ─── Find session ─────────────────────────────────────
+function findLatestSession() {
+  if (!fs.existsSync(sessionsDir)) return null;
+  const dirs = fs.readdirSync(sessionsDir)
+    .filter(d => d.startsWith('session_'))
+    .sort()
+    .reverse();
+  return dirs[0] || null;
+}
+
+function getSessionDir() {
+  const sid = sessionId || findLatestSession();
+  if (!sid) return null;
+  return path.join(sessionsDir, sid);
+}
+
+// ─── Parse session data ───────────────────────────────
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function parseCoordinatorLog(sessionPath) {
+  const logFile = path.join(sessionPath, 'coordinator.log');
+  if (!fs.existsSync(logFile)) return [];
+  const raw = fs.readFileSync(logFile, 'utf-8');
+  const lines = raw.split('\n').filter(Boolean);
+  return lines.map(line => {
+    const clean = stripAnsi(line);
+    return { raw: clean, ts: extractTimestamp(clean) };
+  });
+}
+
+function extractTimestamp(line) {
+  const m = line.match(/^\[(\d{2}:\d{2}:\d{2})\]/);
+  return m ? m[1] : null;
+}
+
+function parseTaskFile(sessionPath) {
+  const taskFile = path.join(projectDir, '.codeswarm', 'task.md');
+  if (!fs.existsSync(taskFile)) return { title: '', subtasks: [], isPrd: false };
+
+  const raw = fs.readFileSync(taskFile, 'utf-8');
+  const titleMatch = raw.match(/^# Task:\s*(.+)/m);
+  const title = titleMatch ? titleMatch[1].trim() : '';
+
+  // Detect if this is a PRD-derived task (has [US-XXX] tags)
+  const isPrd = /\[US-\d+\]/.test(raw);
+
+  const subtasks = [];
+  const lines = raw.split('\n');
+  let currentSubtask = null;
+  for (const line of lines) {
+    const m = line.match(/^(\d+):?\s*- \[(.)\]\s*(.+)/);
+    const m2 = !m ? line.match(/- \[(.)\]\s*(.+)/) : null;
+    if (m || m2) {
+      const checkbox = m ? m[2] : m2[1];
+      const text = m ? m[3].trim() : m2[2].trim();
+      const status = checkbox === 'x' ? 'done' : checkbox === '/' ? 'in_progress' : 'pending';
+
+      // Extract [US-XXX] tag if present
+      const usMatch = text.match(/^\*?\*?\[?(US-\d+)\]?/);
+      const storyId = usMatch ? usMatch[1] : null;
+
+      currentSubtask = { num: subtasks.length + 1, status, title: text, storyId, acceptanceCriteria: [] };
+      subtasks.push(currentSubtask);
+    } else if (currentSubtask && line.match(/^\s+- Acceptance Criteria:/)) {
+      // Mark next lines as AC
+    } else if (currentSubtask && line.match(/^\s{4,}- \[(.)\]/)) {
+      const acMatch = line.match(/^\s{4,}- \[(.)\]\s*(.+)/);
+      if (acMatch) {
+        currentSubtask.acceptanceCriteria.push({
+          status: acMatch[1] === 'x' ? 'pass' : acMatch[1] === '/' ? 'in_progress' : 'pending',
+          text: acMatch[2].trim()
+        });
+      }
+    }
+  }
+  return { title, subtasks, isPrd };
+}
+
+function getAgentFiles(sessionPath) {
+  if (!fs.existsSync(sessionPath)) return [];
+  const files = fs.readdirSync(sessionPath);
+  const agents = {};
+
+  for (const f of files) {
+    const logMatch = f.match(/^log_(\d+)_(\w+)\.md$/);
+    if (logMatch) {
+      const seq = parseInt(logMatch[1], 10);
+      const name = logMatch[2];
+      if (!agents[name]) agents[name] = { name, logs: [], prompts: [] };
+      const filePath = path.join(sessionPath, f);
+      const stat = fs.statSync(filePath);
+      agents[name].logs.push({
+        seq,
+        file: f,
+        size: stat.size,
+        mtime: stat.mtimeMs
+      });
+    }
+
+    const promptMatch = f.match(/^prompt_(\d+)_(\w+)\.md$/);
+    if (promptMatch) {
+      const seq = parseInt(promptMatch[1], 10);
+      const name = promptMatch[2];
+      if (!agents[name]) agents[name] = { name, logs: [], prompts: [] };
+      agents[name].prompts.push({ seq, file: f });
+    }
+  }
+
+  return Object.values(agents).map(a => ({
+    ...a,
+    logs: a.logs.sort((x, y) => x.seq - y.seq),
+    prompts: a.prompts.sort((x, y) => x.seq - y.seq),
+    latestLog: a.logs.length > 0 ? a.logs[a.logs.length - 1] : null
+  }));
+}
+
+function getAgentLogTail(sessionPath, logFile, lines = 50) {
+  const filePath = path.join(sessionPath, logFile);
+  if (!fs.existsSync(filePath)) return '';
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const allLines = raw.split('\n');
+  return stripAnsi(allLines.slice(-lines).join('\n'));
+}
+
+function parseDirectives(sessionPath) {
+  if (!fs.existsSync(sessionPath)) return [];
+  const files = fs.readdirSync(sessionPath);
+  const directives = files
+    .filter(f => f.startsWith('directive_'))
+    .sort()
+    .map(f => {
+      const raw = fs.readFileSync(path.join(sessionPath, f), 'utf-8');
+      const clean = stripAnsi(raw);
+      const actionMatch = clean.match(/ACTION:\s*(\w+)/i);
+      const subtaskMatch = clean.match(/SUBTASK:\s*(\d+)/i);
+      const instructMatch = clean.match(/INSTRUCTIONS?:\s*(.+)/i);
+      return {
+        file: f,
+        action: actionMatch ? actionMatch[1] : 'UNKNOWN',
+        subtask: subtaskMatch ? parseInt(subtaskMatch[1], 10) : null,
+        instructions: instructMatch ? instructMatch[1].trim() : ''
+      };
+    });
+  return directives;
+}
+
+function detectAgentRoles(sessionPath) {
+  // Primary: read metadata.json written by coordinator
+  const metaFile = path.join(sessionPath, 'metadata.json');
+  if (fs.existsSync(metaFile)) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(metaFile, 'utf-8'));
+      return {
+        planner: meta.planner || null,
+        executor: meta.executor || null,
+        reviewers: meta.reviewers || [],
+        frontendDev: meta.frontendDev || null,
+        frontendReviewers: meta.frontendReviewers || []
+      };
+    } catch (e) { /* fall through to log parsing */ }
+  }
+
+  // Fallback: parse coordinator log
+  const log = parseCoordinatorLog(sessionPath);
+  const roles = { planner: null, executor: null, reviewers: [], frontendDev: null, frontendReviewers: [] };
+  for (const entry of log) {
+    const line = entry.raw;
+    if (line.includes('Planner:')) {
+      const m = line.match(/Planner:\s*(\w+)/);
+      if (m) roles.planner = m[1];
+    }
+    if (line.includes('Executor:')) {
+      const m = line.match(/Executor:\s*(\w+)/);
+      if (m) roles.executor = m[1];
+    }
+    if (line.includes('Reviewers:') || line.includes('reviewers:')) {
+      const m = line.match(/Reviewers?:\s*(.+?)(?:\(|$)/i);
+      if (m) roles.reviewers = m[1].trim().split(/[\s,]+/).filter(Boolean);
+    }
+    if (line.includes('FE Dev:')) {
+      const m = line.match(/FE Dev:\s*(\w+)/);
+      if (m) roles.frontendDev = m[1];
+    }
+    if (line.includes('FE Review:')) {
+      const m = line.match(/FE Review:\s*(.+?)(?:\(|$)/i);
+      if (m) roles.frontendReviewers = m[1].trim().split(/[\s,]+/).filter(Boolean);
+    }
+  }
+  return roles;
+}
+
+function getSessionState() {
+  const sessionPath = getSessionDir();
+  if (!sessionPath || !fs.existsSync(sessionPath)) {
+    return { error: 'No session found', sessions: listSessions() };
+  }
+
+  const sid = path.basename(sessionPath);
+  const coordLog = parseCoordinatorLog(sessionPath);
+  const task = parseTaskFile(sessionPath);
+  const agents = getAgentFiles(sessionPath);
+  const directives = parseDirectives(path.join(sessionPath, 'directives'));
+  const roles = detectAgentRoles(sessionPath);
+
+  // Detect current round from coordinator log
+  let currentRound = 0;
+  for (const entry of coordLog) {
+    const m = entry.raw.match(/Round\s+(\d+)/i);
+    if (m) currentRound = Math.max(currentRound, parseInt(m[1], 10));
+  }
+
+  // Detect running agents (files modified in last 60s)
+  const now = Date.now();
+  const runningAgents = agents
+    .filter(a => a.latestLog && (now - a.latestLog.mtime) < 60000)
+    .map(a => a.name);
+
+  return {
+    sessionId: sid,
+    sessionPath,
+    project: projectDir,
+    roles,
+    currentRound,
+    task,
+    agents,
+    runningAgents,
+    directives,
+    coordLog: coordLog.slice(-100),
+    sessions: listSessions()
+  };
+}
+
+function listSessions() {
+  if (!fs.existsSync(sessionsDir)) return [];
+  return fs.readdirSync(sessionsDir)
+    .filter(d => d.startsWith('session_'))
+    .sort()
+    .reverse()
+    .slice(0, 20);
+}
+
+// ─── Express + WebSocket ──────────────────────────────
+const app = express();
+const server = http.createServer(app);
+const wss = new WebSocketServer({ server });
+
+app.use(express.static(path.join(__dirname, 'public')));
+
+app.get('/api/state', (req, res) => {
+  res.json(getSessionState());
+});
+
+app.get('/api/sessions', (req, res) => {
+  res.json(listSessions());
+});
+
+app.get('/api/session/:sid', (req, res) => {
+  sessionId = req.params.sid;
+  res.json(getSessionState());
+});
+
+app.get('/api/log/:file', (req, res) => {
+  const sessionPath = getSessionDir();
+  if (!sessionPath) return res.status(404).json({ error: 'No session' });
+  const lines = parseInt(req.query.lines) || 200;
+  const tail = getAgentLogTail(sessionPath, req.params.file, lines);
+  res.json({ content: tail });
+});
+
+// Search within a log file
+app.get('/api/log-search/:file', (req, res) => {
+  const sessionPath = getSessionDir();
+  if (!sessionPath) return res.status(404).json({ error: 'No session' });
+  const query = (req.query.q || '').toLowerCase();
+  if (!query) return res.json({ matches: [], total: 0 });
+
+  const filePath = path.join(sessionPath, req.params.file);
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'File not found' });
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const allLines = raw.split('\n');
+  const matches = [];
+  for (let i = 0; i < allLines.length; i++) {
+    const clean = stripAnsi(allLines[i]);
+    if (clean.toLowerCase().includes(query)) {
+      matches.push({ line: i + 1, content: clean });
+    }
+  }
+  res.json({ matches: matches.slice(0, 100), total: matches.length });
+});
+
+// Download raw log file
+app.get('/api/log-download/:file', (req, res) => {
+  const sessionPath = getSessionDir();
+  if (!sessionPath) return res.status(404).json({ error: 'No session' });
+  const filePath = path.join(sessionPath, req.params.file);
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'File not found' });
+
+  // Strip ANSI codes for clean download
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const clean = stripAnsi(raw);
+  res.setHeader('Content-Disposition', `attachment; filename="${req.params.file}"`);
+  res.setHeader('Content-Type', 'text/plain');
+  res.send(clean);
+});
+
+// Detect agent phase from log content
+app.get('/api/log-phases/:file', (req, res) => {
+  const sessionPath = getSessionDir();
+  if (!sessionPath) return res.status(404).json({ error: 'No session' });
+  const filePath = path.join(sessionPath, req.params.file);
+  if (!fs.existsSync(filePath)) return res.status(404).json({ error: 'File not found' });
+
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const clean = stripAnsi(raw);
+  const phases = detectPhases(clean);
+  res.json({ phases, currentPhase: phases.length > 0 ? phases[phases.length - 1].phase : null });
+});
+
+function detectPhases(logContent) {
+  const phases = [];
+  const lines = logContent.split('\n');
+  const phasePatterns = [
+    { pattern: /reading|read file|view_file|cat |examining|analyzing/i, phase: 'Reading' },
+    { pattern: /writing|write_to_file|creating file|edit |modifying|implement/i, phase: 'Implementing' },
+    { pattern: /test|jest|mocha|pytest|mvn test|npm test|running tests/i, phase: 'Testing' },
+    { pattern: /build|compile|mvn compile|npm run build|tsc/i, phase: 'Building' },
+    { pattern: /git commit|git add|committing/i, phase: 'Committing' },
+    { pattern: /review|checking|verif|validat/i, phase: 'Reviewing' },
+  ];
+
+  for (let i = 0; i < lines.length; i++) {
+    for (const { pattern, phase } of phasePatterns) {
+      if (pattern.test(lines[i])) {
+        if (phases.length === 0 || phases[phases.length - 1].phase !== phase) {
+          phases.push({ phase, line: i + 1 });
+        }
+        break;
+      }
+    }
+  }
+  return phases;
+}
+
+// WebSocket broadcast
+function broadcast(data) {
+  const msg = JSON.stringify(data);
+  wss.clients.forEach(client => {
+    if (client.readyState === 1) client.send(msg);
+  });
+}
+
+// File watcher
+let watcher = null;
+
+function startWatching() {
+  const sessionPath = getSessionDir();
+  if (!sessionPath) return;
+
+  if (watcher) watcher.close();
+
+  const watchPaths = [sessionPath, path.join(agenticDir, 'task.md')];
+  watcher = chokidar.watch(watchPaths, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 200 }
+  });
+
+  watcher.on('all', (event, filePath) => {
+    broadcast({ type: 'update', event, file: path.basename(filePath), state: getSessionState() });
+  });
+
+  // Also watch for new sessions
+  chokidar.watch(sessionsDir, { depth: 0, ignoreInitial: true }).on('addDir', () => {
+    const latest = findLatestSession();
+    if (latest && latest !== sessionId) {
+      sessionId = latest;
+      startWatching();
+      broadcast({ type: 'new_session', sessionId: latest, state: getSessionState() });
+    }
+  });
+}
+
+wss.on('connection', (ws) => {
+  ws.send(JSON.stringify({ type: 'init', state: getSessionState() }));
+});
+
+// ─── Start ────────────────────────────────────────────
+server.listen(port, () => {
+  console.log(`\n🎯 Agentic Dashboard running at http://localhost:${port}`);
+  console.log(`📁 Project: ${projectDir}`);
+  const sid = sessionId || findLatestSession();
+  console.log(`📋 Session: ${sid || '(waiting for session...)'}\n`);
+  startWatching();
+});

package/docs/prd-example.md

@@ -0,0 +1,90 @@
+# PRD: CMMS Work Order Management API
+
+## Overview
+Build a RESTful API for managing maintenance work orders in a CMMS (Computerized Maintenance Management System). The API handles work order lifecycle from creation through completion, with assignment, priority management, and status tracking.
+
+## Tech Stack
+Java 21, Spring Boot 3.x, PostgreSQL, Liquibase, Maven
+
+## User Stories
+
+### US-001: Database Schema & Entity [priority: 1]
+**Description:** Create the database schema and JPA entity for work orders. This is the foundation for all other stories.
+**Files:** `src/main/resources/db/changelog/001-create-work-orders.xml`, `src/main/java/com/app/domain/model/WorkOrder.java`, `src/main/java/com/app/domain/model/WorkOrderStatus.java`, `src/main/java/com/app/domain/model/WorkOrderPriority.java`
+**Acceptance Criteria:**
+- [ ] Liquibase migration creates `work_orders` table with columns: id, title, description, status, priority, assigned_to, created_by, due_date, completed_at, created_at, updated_at
+- [ ] WorkOrder JPA entity maps correctly with proper annotations (@Entity, @Table, @Id, @Version)
+- [ ] WorkOrderStatus enum: OPEN, IN_PROGRESS, ON_HOLD, COMPLETED, CANCELLED
+- [ ] WorkOrderPriority enum: CRITICAL, HIGH, MEDIUM, LOW
+- [ ] `mvn compile` passes with no errors
+**Dependencies:** none
+**Notes:** Follow hexagonal architecture. Use `@GeneratedValue(strategy = GenerationType.SEQUENCE)` with a dedicated sequence.
+
+### US-002: Repository & Basic Service [priority: 2]
+**Description:** Create the repository interface and service layer with basic CRUD operations.
+**Files:** `src/main/java/com/app/infrastructure/adapter/out/persistence/WorkOrderRepository.java`, `src/main/java/com/app/domain/service/WorkOrderService.java`, `src/main/java/com/app/application/dto/WorkOrderDto.java`, `src/main/java/com/app/application/dto/CreateWorkOrderRequest.java`
+**Acceptance Criteria:**
+- [ ] JpaRepository with custom query: findByStatus, findByAssignedTo, findByPriority
+- [ ] WorkOrderService implements: create, findById, findAll, update, delete
+- [ ] CreateWorkOrderRequest DTO with Jakarta validation annotations (@NotBlank, @NotNull)
+- [ ] WorkOrderDto as a Java record for responses
+- [ ] Service uses constructor injection (no @Autowired on fields)
+- [ ] `mvn compile` passes
+**Dependencies:** US-001
+**Notes:** Use MapStruct for entity-DTO mapping if the project already uses it, otherwise manual mapping.
+
+### US-003: REST Controller [priority: 3]
+**Description:** Create REST endpoints for work order CRUD operations with proper HTTP status codes and error handling.
+**Files:** `src/main/java/com/app/infrastructure/adapter/in/web/WorkOrderController.java`, `src/main/java/com/app/shared/exception/ResourceNotFoundException.java`
+**Acceptance Criteria:**
+- [ ] POST /api/work-orders — creates work order, returns 201 with Location header
+- [ ] GET /api/work-orders — lists all work orders with pagination (Pageable)
+- [ ] GET /api/work-orders/{id} — returns single work order or 404
+- [ ] PUT /api/work-orders/{id} — updates work order or 404
+- [ ] DELETE /api/work-orders/{id} — soft-delete or 404
+- [ ] @Valid on request bodies triggers 400 with field-level error messages
+- [ ] Global exception handler returns consistent error JSON: { timestamp, status, message, path }
+- [ ] `mvn compile` passes
+**Dependencies:** US-002
+**Notes:** Use @RestController with @RequestMapping("/api/work-orders"). Follow existing controller patterns in the project.
+
+### US-004: Status Transitions & Business Rules [priority: 4]
+**Description:** Implement work order status transition logic with validation. Not all transitions are valid (e.g., CANCELLED → IN_PROGRESS is not allowed).
+**Files:** `src/main/java/com/app/domain/service/WorkOrderService.java`, `src/main/java/com/app/domain/model/WorkOrder.java`, `src/main/java/com/app/shared/exception/InvalidStatusTransitionException.java`
+**Acceptance Criteria:**
+- [ ] Valid transitions: OPEN→IN_PROGRESS, OPEN→CANCELLED, IN_PROGRESS→ON_HOLD, IN_PROGRESS→COMPLETED, IN_PROGRESS→CANCELLED, ON_HOLD→IN_PROGRESS, ON_HOLD→CANCELLED
+- [ ] Invalid transitions throw InvalidStatusTransitionException (returns 409 Conflict)
+- [ ] PATCH /api/work-orders/{id}/status endpoint accepts { "status": "IN_PROGRESS" }
+- [ ] completed_at is automatically set when transitioning to COMPLETED
+- [ ] assigned_to is required before transitioning to IN_PROGRESS
+- [ ] `mvn compile` passes
+**Dependencies:** US-003
+**Notes:** Consider using a state machine pattern or a simple Map<Status, Set<Status>> for allowed transitions.
+
+### US-005: Search & Filtering [priority: 5]
+**Description:** Add search and filtering capabilities to the work orders list endpoint.
+**Files:** `src/main/java/com/app/infrastructure/adapter/in/web/WorkOrderController.java`, `src/main/java/com/app/infrastructure/adapter/out/persistence/WorkOrderRepository.java`, `src/main/java/com/app/application/dto/WorkOrderFilterRequest.java`
+**Acceptance Criteria:**
+- [ ] GET /api/work-orders?status=OPEN&priority=HIGH — filter by status and/or priority
+- [ ] GET /api/work-orders?search=pump — case-insensitive search in title and description
+- [ ] GET /api/work-orders?assignedTo=user123 — filter by assignee
+- [ ] GET /api/work-orders?dueBefore=2025-01-01 — filter by due date
+- [ ] Filters are combinable (AND logic)
+- [ ] Pagination still works with filters (page, size, sort parameters)
+- [ ] `mvn compile` passes
+**Dependencies:** US-003
+**Notes:** Use Spring Data JPA Specifications or @Query with dynamic parameters. Do NOT use Criteria API directly.
+
+---
+
+## Non-Functional Requirements
+- All endpoints require authentication (existing Spring Security config handles this)
+- Use SLF4J Logger, not System.out.println
+- Follow existing naming conventions in the project
+- Database columns use snake_case, Java fields use camelCase
+
+## Out of Scope
+- File attachments on work orders
+- Work order comments/notes
+- Email notifications
+- Audit log integration

package/docs/prd-template.md

@@ -0,0 +1,45 @@
+# PRD: <Project Title>
+
+## Overview
+<2-3 sentence description of what this project/feature delivers and why>
+
+## Tech Stack
+<language, framework, database, etc.>
+
+## User Stories
+
+### US-001: <Title> [priority: 1]
+**Description:** <what needs to be done and why>
+**Files:** `path/to/file1.java`, `path/to/file2.java`
+**Acceptance Criteria:**
+- [ ] <specific, testable criterion>
+- [ ] <specific, testable criterion>
+- [ ] <specific, testable criterion>
+**Dependencies:** none
+**Notes:** <optional context, patterns to follow, gotchas>
+
+### US-002: <Title> [priority: 2]
+**Description:** <what needs to be done and why>
+**Files:** `path/to/file1.java`
+**Acceptance Criteria:**
+- [ ] <specific, testable criterion>
+- [ ] <specific, testable criterion>
+**Dependencies:** US-001
+**Notes:** <optional>
+
+### US-003: <Title> [priority: 3]
+**Description:** <what needs to be done and why>
+**Files:** `path/to/new-file.java`
+**Acceptance Criteria:**
+- [ ] <specific, testable criterion>
+- [ ] <specific, testable criterion>
+**Dependencies:** US-001, US-002
+**Notes:** <optional>
+
+---
+
+## Non-Functional Requirements
+- <performance, security, logging, etc.>
+
+## Out of Scope
+- <what is explicitly NOT included>