@assistkick/create 1.0.0

package/templates/product-system/tests/work_summary.test.ts

@@ -0,0 +1,211 @@
+/**
+ * Tests for WorkSummaryParser — parsing structured work summaries from
+ * developer Claude output and git diff --name-status.
+ * Uses node:test built-in runner per nfr_001.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { WorkSummaryParser } from '../packages/shared/lib/work_summary_parser.js';
+
+describe('WorkSummaryParser', () => {
+  describe('parseFromOutput', () => {
+    it('extracts approach and decisions from well-formed output', () => {
+      const parser = new WorkSummaryParser();
+      const output = `
+Some implementation text here...
+
+## Work Summary
+### Approach
+I added a new column to the database and updated the pipeline to capture developer output after each cycle. The work summary is parsed from a structured block in the Claude output.
+### Decisions
+- Used a JSON column instead of a separate table for simplicity
+- Chose to capture git diff --name-status rather than full diff to keep data small
+- Made the work summary section collapsible in the UI
+`;
+
+      const result = parser.parseFromOutput(output);
+
+      assert.ok(result.approach.includes('added a new column'));
+      assert.equal(result.decisions.length, 3);
+      assert.ok(result.decisions[0].includes('JSON column'));
+      assert.ok(result.decisions[1].includes('git diff'));
+      assert.ok(result.decisions[2].includes('collapsible'));
+    });
+
+    it('returns empty values when no work summary block exists', () => {
+      const parser = new WorkSummaryParser();
+      const output = 'Just some regular output without a work summary.';
+
+      const result = parser.parseFromOutput(output);
+
+      assert.equal(result.approach, '');
+      assert.deepEqual(result.decisions, []);
+    });
+
+    it('handles approach without decisions', () => {
+      const parser = new WorkSummaryParser();
+      const output = `
+## Work Summary
+### Approach
+Simple implementation with minimal changes.
+`;
+
+      const result = parser.parseFromOutput(output);
+
+      assert.ok(result.approach.includes('Simple implementation'));
+      assert.deepEqual(result.decisions, []);
+    });
+
+    it('handles decisions with asterisk bullets', () => {
+      const parser = new WorkSummaryParser();
+      const output = `
+## Work Summary
+### Approach
+Did the thing.
+### Decisions
+* Decision one
+* Decision two
+`;
+
+      const result = parser.parseFromOutput(output);
+
+      assert.equal(result.decisions.length, 2);
+      assert.equal(result.decisions[0], 'Decision one');
+      assert.equal(result.decisions[1], 'Decision two');
+    });
+
+    it('stops parsing decisions at next heading', () => {
+      const parser = new WorkSummaryParser();
+      const output = `
+## Work Summary
+### Approach
+Did it.
+### Decisions
+- Decision A
+
+## Some Other Section
+This should not be parsed as decisions.
+`;
+
+      const result = parser.parseFromOutput(output);
+
+      assert.equal(result.decisions.length, 1);
+      assert.equal(result.decisions[0], 'Decision A');
+    });
+  });
+
+  describe('parseDiffNameStatus', () => {
+    it('categorizes files by A/M/D status markers', () => {
+      const parser = new WorkSummaryParser();
+      const diffOutput = `A\tpackages/shared/lib/new_file.ts
+M\tpackages/shared/lib/pipeline.ts
+M\tpackages/shared/db/schema.ts
+D\tpackages/frontend/src/old_component.tsx
+A\tpackages/frontend/src/KanbanView.tsx`;
+
+      const result = parser.parseDiffNameStatus(diffOutput);
+
+      assert.deepEqual(result.filesCreated, [
+        'packages/shared/lib/new_file.ts',
+        'packages/frontend/src/KanbanView.tsx',
+      ]);
+      assert.deepEqual(result.filesUpdated, [
+        'packages/shared/lib/pipeline.ts',
+        'packages/shared/db/schema.ts',
+      ]);
+      assert.deepEqual(result.filesDeleted, [
+        'packages/frontend/src/old_component.tsx',
+      ]);
+    });
+
+    it('returns empty arrays for empty diff', () => {
+      const parser = new WorkSummaryParser();
+      const result = parser.parseDiffNameStatus('');
+
+      assert.deepEqual(result.filesCreated, []);
+      assert.deepEqual(result.filesUpdated, []);
+      assert.deepEqual(result.filesDeleted, []);
+    });
+
+    it('handles single added file', () => {
+      const parser = new WorkSummaryParser();
+      const diffOutput = `A\tsrc/index.ts`;
+
+      const result = parser.parseDiffNameStatus(diffOutput);
+
+      assert.deepEqual(result.filesCreated, ['src/index.ts']);
+      assert.deepEqual(result.filesUpdated, []);
+      assert.deepEqual(result.filesDeleted, []);
+    });
+
+    it('handles single modified file', () => {
+      const parser = new WorkSummaryParser();
+      const diffOutput = `M\tsrc/index.ts`;
+
+      const result = parser.parseDiffNameStatus(diffOutput);
+
+      assert.deepEqual(result.filesCreated, []);
+      assert.deepEqual(result.filesUpdated, ['src/index.ts']);
+      assert.deepEqual(result.filesDeleted, []);
+    });
+
+    it('handles single deleted file', () => {
+      const parser = new WorkSummaryParser();
+      const diffOutput = `D\tsrc/removed.ts`;
+
+      const result = parser.parseDiffNameStatus(diffOutput);
+
+      assert.deepEqual(result.filesCreated, []);
+      assert.deepEqual(result.filesUpdated, []);
+      assert.deepEqual(result.filesDeleted, ['src/removed.ts']);
+    });
+
+    it('treats unknown status markers as updated', () => {
+      const parser = new WorkSummaryParser();
+      const diffOutput = `R\tsrc/renamed.ts`;
+
+      const result = parser.parseDiffNameStatus(diffOutput);
+
+      assert.deepEqual(result.filesCreated, []);
+      assert.deepEqual(result.filesUpdated, ['src/renamed.ts']);
+      assert.deepEqual(result.filesDeleted, []);
+    });
+  });
+
+  describe('buildSummary', () => {
+    it('combines cycle, diff name-status, and Claude output into a WorkSummary', () => {
+      const parser = new WorkSummaryParser();
+      const diffOutput = `A\tsrc/new.ts
+M\tsrc/foo.ts`;
+      const claudeOutput = `
+## Work Summary
+### Approach
+Implemented the feature by adding a new module.
+### Decisions
+- Chose class-based approach per nfr_001
+`;
+
+      const summary = parser.buildSummary(1, diffOutput, claudeOutput);
+
+      assert.equal(summary.cycle, 1);
+      assert.deepEqual(summary.filesCreated, ['src/new.ts']);
+      assert.deepEqual(summary.filesUpdated, ['src/foo.ts']);
+      assert.deepEqual(summary.filesDeleted, []);
+      assert.ok(summary.approach.includes('new module'));
+      assert.equal(summary.decisions.length, 1);
+      assert.ok(summary.timestamp);
+    });
+
+    it('provides default approach when none in output', () => {
+      const parser = new WorkSummaryParser();
+      const summary = parser.buildSummary(2, '', 'No summary block here');
+
+      assert.equal(summary.cycle, 2);
+      assert.deepEqual(summary.filesCreated, []);
+      assert.deepEqual(summary.filesUpdated, []);
+      assert.deepEqual(summary.filesDeleted, []);
+      assert.equal(summary.approach, 'No approach narrative provided.');
+      assert.deepEqual(summary.decisions, []);
+    });
+  });
+});

package/templates/product-system/tests/zoom_pan.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Tests for Zoom and Pan logic (feat_019).
+ * Tests pure computation functions extracted from GraphView.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+// Pure function extracted from GraphView
+const nodeRadius = (d: { edgeCount: number }) => {
+  const base = 8;
+  const scale = Math.min(d.edgeCount * 1.5, 20);
+  return base + scale;
+};
+
+describe('Zoom and Pan', () => {
+
+  describe('nodeRadius (affects zoom bounds)', () => {
+    it('returns base radius of 8 for zero-edge node', () => {
+      assert.equal(nodeRadius({ edgeCount: 0 }), 8);
+    });
+
+    it('increases radius with edge count', () => {
+      const r0 = nodeRadius({ edgeCount: 0 });
+      const r5 = nodeRadius({ edgeCount: 5 });
+      assert.ok(r5 > r0, 'more edges should yield larger radius');
+    });
+
+    it('caps radius at 28 (8 base + 20 max scale)', () => {
+      assert.equal(nodeRadius({ edgeCount: 100 }), 28);
+      assert.equal(nodeRadius({ edgeCount: 200 }), 28);
+    });
+  });
+
+  describe('nodeRadius consistency', () => {
+    it('nodeRadius returns consistent values for force simulation', () => {
+      const node = { edgeCount: 5 };
+      const r1 = nodeRadius(node);
+      const r2 = nodeRadius(node);
+      assert.equal(r1, r2);
+      assert.equal(r1, 8 + Math.min(5 * 1.5, 20)); // 15.5
+    });
+  });
+});

package/templates/product-system/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "strict": false,
+    "allowJs": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ESNext",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "build",
+    "rootDir": ".",
+    "sourceMap": true,
+    "declaration": true
+  },
+  "include": [
+    "tests/**/*.ts",
+    "smoke_test.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "packages"
+  ]
+}

package/templates/skills/product-bootstrap/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: product-bootstrap
+description: Bootstrap the product knowledge graph for an existing project by scanning the codebase and interviewing the user. Use when the user wants to onboard a project, bootstrap the graph, initialize the product system, or bring the knowledge graph up to speed for an existing codebase.
+---
+
+# Product Bootstrap Skill
+
+## Your Role
+You are bootstrapping the product knowledge graph for an existing project.
+Your goal is to rapidly build a well-connected specification graph by
+**scanning the codebase first** and **asking the user only about intent,
+priorities, and preferences**. You interact with the graph exclusively
+through the tools below.
+
+All tools live in `product-system/packages/shared/tools/` and
+are run with `npx tsx`.
+
+## Bootstrap Philosophy
+Unlike a greenfield interview, the project already exists. The codebase is
+the primary source of truth for **what exists**. The user is the source of
+truth for **what matters, what's next, and why**.
+
+- **Read code first, ask questions second**
+- **Populate aggressively** — create nodes for everything you discover
+- **Ask the user to confirm and prioritize**, not to describe what you can see
+- **Wire edges densely** — a bootstrap graph with sparse edges is useless
+
+## Session Start Protocol
+1. Call `start_session`
+2. Call `get_status` — check if this is a cold start or a continuation
+3. If cold start (empty graph): begin with **Phase 1**
+4. If continuing: call `get_gaps --blocking-only` and resume at the
+   appropriate phase
+
+## Phase 1 — Project Survey (Codebase Scan)
+
+**Goal:** Understand the project structure, tech stack, and domain without
+asking the user a single question yet.
+
+1. **Explore the project root** — read `package.json`, `Cargo.toml`,
+   `pyproject.toml`, `go.mod`, `Gemfile`, or equivalent to identify:
+   - Language and framework
+   - Key dependencies
+   - Build system and scripts
+2. **Scan directory structure** — use Glob to map top-level directories and
+   understand the layout (e.g. `src/`, `lib/`, `api/`, `components/`,
+   `models/`, `migrations/`)
+3. **Read configuration files** — `.env.example`, CI configs, Docker files,
+   `tsconfig.json`, etc. to identify infrastructure and deployment patterns
+4. **Identify data models** — look for ORM models, database schemas,
+   migration files, type definitions, or GraphQL schemas
+5. **Identify API surface** — look for route definitions, controllers,
+   resolvers, or API handlers
+6. **Identify UI structure** (if applicable) — look for pages, components,
+   layouts
+
+**Output of Phase 1:** A mental map of the project. Do NOT create nodes yet.
+Present a summary to the user:
+- "Here's what I found in your codebase: [tech stack], [main modules],
+  [data entities], [API shape]. Does this look right? Anything I missed?"
+
+## Phase 2 — Foundation Nodes
+
+**Goal:** Create the structural backbone of the graph. Create nodes in this
+order, using what you learned in Phase 1.
+
+### 2a. Tech Choices
+For each technology identified (language, framework, database, hosting,
+key libraries), create a `tech_choice` node:
+```
+add_node --type tech_choice --name "TypeScript" --description "Primary language..."
+```
+
+### 2b. User Roles
+Scan for auth logic, role enums, middleware, or permission checks. Create a
+`user_role` node for each role discovered. Ask the user: "I found these
+roles: [list]. Are there others? Which is the primary user?"
+
+### 2c. Design Patterns
+Identify architectural patterns in use (e.g. MVC, event-driven, repository
+pattern, component composition, state management approach). Create a
+`design_pattern` node for each.
+
+### 2d. Decisions
+For patterns that reflect deliberate architectural choices (e.g. "monorepo",
+"REST over GraphQL", "server-side rendering"), create `decision` nodes.
+Ask the user: "I see these architectural decisions. Any context on why, or
+any you'd revisit?"
+
+### 2e. Data Entities
+For each model/schema/table discovered, create a `data_entity` node with
+fields listed in the description. Wire `reads_writes` edges as you discover
+which modules touch which entities.
+
+### Edge Pass after Phase 2:
+- `tech_choice` → `governed_by` → relevant `decision` nodes
+- `design_pattern` → `governed_by` → relevant `decision` nodes
+- `data_entity` → `reads_writes` edges to each other where foreign keys exist
+
+Present all created nodes and edges to the user for confirmation.
+
+## Phase 3 — Feature Discovery
+
+**Goal:** Map the project's capabilities as features in the graph.
+
+1. **Scan for feature boundaries** — look at:
+   - Route/page definitions (each route often = a feature)
+   - Major UI components or pages
+   - API endpoint groups
+   - Background jobs, workers, or cron tasks
+   - CLI commands (if applicable)
+2. **Create top-level features** — one `feature` node per major capability.
+   Set status to `defined` for features that are clearly implemented.
+3. **Decompose large features** — if a feature has sub-routes, tabs, or
+   distinct modes, create sub-features and wire `contains` edges.
+4. **Wire edges:**
+   - `feature` → `implemented_with` → `tech_choice` or `component`
+   - `feature` → `depends_on` → other features it requires
+   - `feature` → `reads_writes` → `data_entity`
+   - `feature` → `performed_by` → `user_role`
+   - `feature` → `governed_by` → `decision` or `design_pattern`
+
+Ask the user: "Here are the features I identified: [list]. Any missing?
+Which are most important to you right now?"
+
+## Phase 4 — Component Mapping
+
+**Goal:** Map internal components and modules that implement features.
+
+1. **Identify reusable components** — shared UI components, service classes,
+   utility modules, middleware, hooks
+2. **Create `component` nodes** for significant reusable pieces
+3. **Wire edges:**
+   - `component` → `implemented_with` → `tech_choice`
+   - `feature` → `implemented_with` → `component`
+   - `component` → `reads_writes` → `data_entity`
+   - `component` → `depends_on` → other components
+
+## Phase 5 — Non-Functional Requirements & Constraints
+
+**Goal:** Capture the quality attributes and constraints.
+
+Ask the user about (only what's relevant):
+- Performance targets (response times, throughput)
+- Security requirements (auth method, data sensitivity, compliance)
+- Scalability expectations
+- Accessibility requirements
+- Browser/device support
+- Uptime/availability targets
+
+Create `non_functional_requirement` nodes and wire `constrained_by` edges
+from the features they apply to.
+
+## Phase 6 — Flows & Integration Points
+
+**Goal:** Capture key user journeys and external integrations.
+
+1. **Identify critical flows** — onboarding, checkout, CRUD cycles, admin
+   workflows. Create `flow` nodes with step-by-step descriptions.
+2. **Identify external integrations** — third-party APIs, webhooks, OAuth
+   providers, payment processors. Create nodes and wire appropriately.
+3. **Wire edges:**
+   - `flow` → `contains` → features involved in the flow
+   - `flow` → `performed_by` → `user_role`
+
+## Phase 7 — Gap Analysis & Prioritization
+
+**Goal:** Identify what's missing and let the user prioritize.
+
+1. Call `get_gaps` — present the full gap report
+2. Call `get_status` — show completeness metrics
+3. Ask the user:
+   - "Which areas should I dig deeper into?"
+   - "Are there planned features not yet in the codebase?"
+   - "Any known technical debt or areas you want to redesign?"
+4. Create nodes for planned/future work with status `draft`
+
+## Session End Protocol
+1. Call `get_gaps` — report remaining gaps
+2. Call `get_status` — show overall progress
+3. Call `end_session` with a summary
+4. Tell the user which phase to resume at next session
+
+## Tool Reference
+
+### start_session
+```
+npx tsx packages/shared/tools/start_session.ts
+```
+
+### end_session
+```
+npx tsx packages/shared/tools/end_session.ts --summary "..." --nodes-touched "feat_001,dec_001" --questions-resolved 3
+```
+
+### search_nodes
+```
+npx tsx packages/shared/tools/search_nodes.ts --query "keyword"
+npx tsx packages/shared/tools/search_nodes.ts --type feature
+npx tsx packages/shared/tools/search_nodes.ts --has-open-questions
+npx tsx packages/shared/tools/search_nodes.ts --completeness-below 0.5
+```
+
+### get_node
+```
+npx tsx packages/shared/tools/get_node.ts <node_id>
+npx tsx packages/shared/tools/get_node.ts --name "Node Name"
+```
+Returns full .md content plus a Relations section listing all connected nodes
+with direction, relation type, name, type, and status.
+
+### add_node
+```
+npx tsx packages/shared/tools/add_node.ts --type <type> --name "Name" --description "..."
+```
+Valid types: feature, component, data_entity, decision, tech_choice,
+non_functional_requirement, design_token, design_pattern, user_role,
+flow, assumption, open_question
+
+### update_node
+```
+npx tsx packages/shared/tools/update_node.ts <id> --add-acceptance-criteria "..."
+npx tsx packages/shared/tools/update_node.ts <id> --add-open-question "..."
+npx tsx packages/shared/tools/update_node.ts <id> --add-note "Session N: ..."
+npx tsx packages/shared/tools/update_node.ts <id> --set-status <draft|partially_defined|defined>
+npx tsx packages/shared/tools/update_node.ts <id> --set-priority <low|medium|high|blocking>
+npx tsx packages/shared/tools/update_node.ts <id> --set-description "..."
+npx tsx packages/shared/tools/update_node.ts <id> --set-section "SectionName=content"
+```
+
+### resolve_question
+```
+npx tsx packages/shared/tools/resolve_question.ts <id> --question "..." --answer "..."
+```
+
+### add_edge
+```
+npx tsx packages/shared/tools/add_edge.ts <from_id> <relation> <to_id>
+```
+Valid relations: contains, depends_on, governed_by, constrained_by,
+implemented_with, reads_writes, exposes, consumes, performed_by,
+escalates_to, relates_to
+
+### remove_edge
+```
+npx tsx packages/shared/tools/remove_edge.ts <from_id> <relation> <to_id>
+```
+
+### get_gaps
+```
+npx tsx packages/shared/tools/get_gaps.ts
+npx tsx packages/shared/tools/get_gaps.ts --blocking-only
+npx tsx packages/shared/tools/get_gaps.ts --type feature
+```
+
+### get_status
+```
+npx tsx packages/shared/tools/get_status.ts
+```
+
+### rebuild_index
+```
+npx tsx packages/shared/tools/rebuild_index.ts
+npx tsx packages/shared/tools/rebuild_index.ts --dry-run
+```
+
+## Search Strategy
+The `search_nodes --query` tool returns graph-aware relevance-ranked results.
+
+1. **Start with specific keywords** — direct matches appear first with
+   `relevance: "direct"`.
+2. **Read expansion results** — each direct match surfaces its 1-hop graph
+   neighbors. Use them to discover related nodes without manual edge walking.
+3. **Fall back to structural overview** — on zero matches, the tool returns
+   the top-5 most-connected nodes per type (the project backbone).
+4. **Use `--type` filters to drill in** — narrow with `--type feature`,
+   `--type decision`, etc.
+5. **Trust strong-edge neighbors** — `depends_on`, `implemented_with`,
+   `governed_by`, `contains` are architecturally significant. `relates_to`
+   is a weak signal.
+
+## Edge Type Semantics
+
+- **depends_on** — prerequisite chain
+- **implemented_with** — technical realization
+- **governed_by** — architectural constraints
+- **constrained_by** — non-functional limits
+- **contains** — parent-child composition
+- **reads_writes** — data access
+- **exposes** — API surface
+- **consumes** — data intake
+- **performed_by** — actor
+- **escalates_to** — delegation
+- **relates_to** — loose association (weakest)
+
+## Rules
+1. Never read or write graph.tson or .md files directly — always use the tools
+2. Always call get_node before update_node — never update blind
+3. Always record answers via resolve_question — don't just add a note
+4. Nodes should reflect reality (codebase + user statements), not inferences —
+   use `assumption` node type for inferences
+5. If the user contradicts something in the graph, update it and add a note
+6. All tool commands must be run from the `product-system/`
+   directory
+7. Set status to `defined` for features clearly implemented in the codebase;
+   use `draft` for planned/future work
+8. **Scan code before asking** — only ask the user about intent, priorities,
+   and preferences. Never ask "how does X work?" when you can read the code.
+9. **Batch node creation** — create multiple related nodes before running
+   edge discovery, to maximize edge connections found in a single pass
+10. **Present and confirm** — after each phase, show the user what you created
+    and get confirmation before moving on