create-dss-project 0.1.0

package/template/docs/skill-authoring-guide.md

@@ -0,0 +1,212 @@
+# Skill Authoring Guide
+
+How to create and contribute new skills for the DS Strategy Stack.
+
+---
+
+## SKILL.md Frontmatter
+
+Every skill lives in `skills/{skill-name}/SKILL.md`. The file **must** begin with YAML frontmatter containing at least two required fields:
+
+```yaml
+---
+name: my-skill-name
+description: A one-sentence summary of what this skill does and when to use it.
+---
+```
+
+- **name** (required): Lowercase, hyphenated identifier. Must match the directory name.
+- **description** (required): Plain text, one to two sentences. Shown in skill listings and help output.
+
+## Directory Structure
+
+```
+skills/
+  my-skill-name/
+    SKILL.md          # The skill definition (required)
+```
+
+Each skill gets its own directory under `skills/`. The directory name must match the `name` field in the frontmatter. Keep one skill per directory — do not bundle multiple skills together.
+
+## Skill Types
+
+Skills fall into two categories:
+
+### Rigid Skills
+
+Rigid skills execute every step in order. The user (or Claude) must not skip steps or reorder them. Use rigid skills for processes where completeness matters — audits, checklists, onboarding flows.
+
+**Example**: `health-check` runs every check regardless of context.
+
+When writing a rigid skill, number each step clearly and include a note at the top:
+
+```markdown
+> **Type: Rigid** — Execute all steps in order. Do not skip or reorder.
+```
+
+### Flexible Skills
+
+Flexible skills provide a framework that adapts to context. Steps can be skipped, reordered, or expanded based on what the project needs right now. Use flexible skills for creative or analytical work — research synthesis, competitive analysis, decision-making.
+
+**Example**: `synthesise` may focus on different research areas depending on what data is available.
+
+When writing a flexible skill, note which steps are optional:
+
+```markdown
+> **Type: Flexible** — Adapt steps to the current context. Steps marked (optional) may be skipped.
+```
+
+## Memory File Interactions
+
+Skills frequently read from and write to memory files. Document these interactions clearly so that users and other skills know what to expect.
+
+### Reading Memory
+
+If your skill reads from memory files, list them at the top of the skill:
+
+```markdown
+## Inputs
+- `memory/MEMORY.md` — current project state and priorities
+- `memory/research.md` — entity capability map and research findings
+```
+
+### Writing to Memory
+
+If your skill updates memory files, specify exactly what it changes:
+
+```markdown
+## Outputs
+- Updates `memory/MEMORY.md` § Current Priority
+- Appends to `memory/discovery.md` § Discovery Log
+```
+
+Always use the **append or update** pattern — never overwrite an entire memory file. Other skills depend on sections you did not write.
+
+## Evidence Grading System
+
+All factual claims in research and discovery files must carry an evidence grade. When your skill produces or processes factual content, enforce these tags:
+
+| Tag | Meaning | When to use |
+|-----|---------|-------------|
+| `[CONFIRMED]` | Verified from a primary source | Official docs, direct quotes, first-party data |
+| `[SECONDARY]` | From a credible but indirect source | Industry reports, reputable journalism |
+| `[INFERENCE]` | Logically derived from confirmed facts | Reasonable conclusions from known data |
+| `[ASSUMPTION]` | Unverified belief or estimate | Hypotheses, rough estimates, hearsay |
+
+If your skill generates research output, include a reminder to tag every factual claim. If your skill consumes research, validate that evidence grades are present and flag ungraded claims.
+
+## Adding Dashboard Data Extraction
+
+If your skill produces structured data that should appear on the dashboard, you need to extend the build pipeline.
+
+### Step 1: Define your data shape
+
+Decide what JSON structure your data should produce. For example:
+
+```json
+{
+  "lastUpdated": "2026-03-26",
+  "items": [
+    { "name": "Example", "status": "active" }
+  ]
+}
+```
+
+### Step 2: Extend build-data.js
+
+Open `dashboard/build-data.js` and add a new extraction function:
+
+```javascript
+// Extract data for my-skill
+function extractMySkillData() {
+  // Read source files from research/, memory/, or discovery/
+  // Parse and structure the data
+  // Write to dashboard/data/my-skill.json
+}
+```
+
+Call your function from the main build sequence at the bottom of the file.
+
+### Step 3: Create a dashboard view (optional)
+
+If your data warrants its own page, create a new HTML file in `dashboard/` following the patterns in existing pages like `competitors.html` or `pipeline.html`.
+
+## Testing Your Skill
+
+After creating or modifying a skill:
+
+1. **Run the health check** to catch structural issues:
+   ```bash
+   scripts/health-check.sh
+   ```
+
+2. **Validate placeholders** if your skill references template tokens:
+   ```bash
+   scripts/validate-placeholders.sh
+   ```
+
+3. **Check frontmatter** manually — ensure `name` and `description` are present and the name matches your directory.
+
+4. **Test the skill end-to-end** by invoking it in a Claude session and verifying:
+   - All listed inputs are read
+   - All listed outputs are written correctly
+   - Memory files are updated (not overwritten)
+   - Evidence grades are applied where relevant
+
+## Example Skill Template
+
+Below is a minimal skill you can copy and adapt:
+
+```markdown
+---
+name: example-skill
+description: A brief description of what this skill does and when it should be invoked.
+---
+
+# Example Skill
+
+> **Type: Flexible** — Adapt steps to the current context.
+
+## Inputs
+- `memory/MEMORY.md` — current project state
+
+## Outputs
+- Updates `memory/MEMORY.md` § Current Priority
+
+---
+
+## Step 1 — Assess Current State
+
+Read `memory/MEMORY.md` and summarise the current project phase and priorities.
+
+## Step 2 — Perform Analysis
+
+<!-- Your skill logic here -->
+
+## Step 3 — Update Memory (optional)
+
+If the analysis produced new insights, update `memory/MEMORY.md` with:
+- Any changed priorities
+- New findings tagged with evidence grades
+```
+
+## Australian English Requirement
+
+All content in this project — skill definitions, comments, documentation, and code comments — must use Australian English spelling conventions:
+
+- **-ise** not -ize (e.g. organise, prioritise, recognise, synthesise)
+- **-our** not -or (e.g. colour, behaviour, honour)
+- **-re** not -er (e.g. centre, theatre)
+- **analyse** not analyze
+
+This applies to skill descriptions, step text, comments in code, and any generated output.
+
+## Checklist Before Submitting
+
+- [ ] `SKILL.md` has valid frontmatter with `name` and `description`
+- [ ] Directory name matches the `name` field
+- [ ] Skill type (Rigid or Flexible) is clearly stated
+- [ ] Inputs and outputs are documented
+- [ ] Evidence grading guidance is included (if the skill handles factual content)
+- [ ] Tested with `scripts/health-check.sh`
+- [ ] Australian English spelling used throughout

package/template/memory/MEMORY.md

@@ -0,0 +1,84 @@
+# MEMORY.md — {{PROJECT_NAME}}
+
+**Project**: {{ONE_LINE_DESCRIPTION}}
+**Goal**: {{GOAL}}
+**Team**: {{TEAM}}
+**Current phase**: Phase 1 — Setup
+**Last updated**: {{DATE}}
+
+---
+
+## Project State
+
+- **Research**: Not started.
+- **Leading hypothesis**: {{STRATEGIC_HYPOTHESIS}}
+- **Discovery**: Not started.
+- **Build/Prototype**: Not started.
+
+## Current Priority
+
+<!-- Update each session with the 1–2 most important things to focus on -->
+
+---
+
+## Memory File Index (Layer 2 — load when topic is active)
+
+| File | Contents | Load when |
+|------|----------|-----------|
+| `memory/research.md` | Competitor map, market sizing, entity list, technical findings | Competitor/market questions |
+| `memory/discovery.md` | Kill conditions, call log, WTP signals, pain rankings | Discovery/call work |
+| `memory/decisions.md` | Strategic decisions with rationale | Questioning the strategy |
+| `memory/scoring.md` | Option scoring, recommended strategy | Hypothesis/positioning work |
+
+---
+
+## Key Facts
+
+<!-- Add 8–12 facts that any session needs to know. Include:
+- Target customer description
+- Product description
+- Market sizing headline numbers
+- Key entities in pipeline
+- Price target or revenue model
+- Key architectural or strategic constraints
+- Competitive white space
+- Timeline or convergence window
+-->
+
+---
+
+## Key Decisions (one-liners — full rationale in `memory/decisions.md`)
+
+<!-- Add numbered one-liner decisions as they're made. Example:
+1. SaaS only — no managed services (wrong unit economics)
+2. API-first — no proprietary SDKs (switching cost concern)
+-->
+
+---
+
+## Kill Conditions
+
+<!-- Define 4–6 falsifiable thresholds. If crossed, the project should stop or pivot. -->
+
+| # | Condition | Status |
+|---|-----------|--------|
+| 1 | | UNTESTED |
+| 2 | | UNTESTED |
+| 3 | | UNTESTED |
+| 4 | | UNTESTED |
+
+---
+
+## Important File Paths
+
+| Asset | Path |
+|-------|------|
+| Executive summary | `docs/executive-summary.md` |
+| Status board | `STATUS.md` |
+| Option scoring | `memory/scoring.md` |
+| Competitor synthesis | `research/competitors/` |
+| Market sizing | `research/market/` |
+| Target entities (CSV) | `{{PIPELINE_SOURCE_OF_TRUTH}}` |
+| Reference context | `docs/memos/reference-context.md` |
+| Housekeeping rules | `docs/memos/housekeeping-reference.md` |
+| Status blurb | `docs/output/status-blurb.md` |

package/template/memory/decisions.md

@@ -0,0 +1,13 @@
+# Strategic Decisions — {{PROJECT_NAME}}
+
+Full rationale for each decision. One-liners in `memory/MEMORY.md`.
+
+---
+
+| # | Decision | Rationale | Date | Reversible? |
+|---|----------|-----------|------|-------------|
+
+<!-- Example:
+| 1 | SaaS only — no managed services | Unit economics don't support services at this stage. $X CAC with services vs $Y without. Revisit if discovery shows services are table stakes. | 2026-03-01 | Yes (add later) |
+| 2 | API-first, no proprietary SDKs | Customer interviews showed SDK fatigue across all segments. S2S/webhooks are sufficient for MVP scope. | 2026-03-05 | Partially (SDK can be added; hard to remove once shipped) |
+-->

package/template/memory/discovery.md

@@ -0,0 +1,48 @@
+# Discovery — {{PROJECT_NAME}}
+
+> **OPTIONAL MODULE** — Include this file if your project involves customer discovery, stakeholder interviews, or external validation. Omit for pure research or internal strategy projects.
+
+---
+
+## Pain Point Rankings
+
+<!-- Update after every discovery call. Rank by frequency and intensity across calls. -->
+
+| Rank | Pain Point | Mentions | Intensity (1–5) | Evidence Grade |
+|------|-----------|----------|-----------------|---------------|
+
+---
+
+## WTP (Willingness to Pay) Signals
+
+| {{ENTITY_TYPE}} | Signal | Amount/Range | Context | Evidence Grade |
+|-----------------|--------|-------------|---------|---------------|
+
+---
+
+## Kill Condition Tracker (Detailed)
+
+<!-- Detailed tracking with evidence per kill condition. Summary lives in MEMORY.md. -->
+
+### KC1: {{CONDITION}}
+- **Status**: UNTESTED
+- **Evidence**:
+
+### KC2: {{CONDITION}}
+- **Status**: UNTESTED
+- **Evidence**:
+
+### KC3: {{CONDITION}}
+- **Status**: UNTESTED
+- **Evidence**:
+
+### KC4: {{CONDITION}}
+- **Status**: UNTESTED
+- **Evidence**:
+
+---
+
+## Outreach Log
+
+| Date | {{ENTITY_TYPE}} | Channel | Action | Result | Next Step |
+|------|-----------------|---------|--------|--------|-----------|

package/template/memory/research.md

@@ -0,0 +1,33 @@
+# Research — {{PROJECT_NAME}}
+
+## Entity Capability Map
+
+<!-- Add columns relevant to your domain. Examples: Category, Cost, Pricing Model, Lock-In, Sentiment -->
+
+| Entity | Category | Key Strength | Key Weakness | Relevance |
+|--------|----------|-------------|-------------|-----------|
+
+---
+
+## Market Sizing Summary
+
+| Metric | Value | Source | Evidence Grade |
+|--------|-------|--------|---------------|
+| TAM | | | |
+| SAM | | | |
+| SOM (Y1) | | | |
+
+---
+
+## Target Entity List
+
+<!-- Track the {{ENTITY_TYPE_PLURAL}} you're actively pursuing or researching -->
+
+| # | Name | Tier | Status | Notes |
+|---|------|------|--------|-------|
+
+---
+
+## Technical Findings
+
+<!-- Key technical feasibility findings, architectural decisions, or platform constraints -->

package/template/memory/scoring.md

@@ -0,0 +1,34 @@
+# Option Scoring — {{PROJECT_NAME}}
+
+## Options Reference
+
+<!-- List the strategic options, entry angles, or approaches being evaluated -->
+
+| Code | Name | Description |
+|------|------|-------------|
+
+---
+
+## Scoring Matrix
+
+<!-- Common dimensions: White Space, Urgency, Feasibility, Defensibility, Revenue Potential, Pipeline/Demand.
+     Each scored 1–5. Adapt dimensions to your project. -->
+
+| Option | {{DIM_1}} | {{DIM_2}} | {{DIM_3}} | {{DIM_4}} | {{DIM_5}} | Total | Rank |
+|--------|-----------|-----------|-----------|-----------|-----------|-------|------|
+
+**Scoring guide**:
+- **5** = Strong structural advantage or high confidence
+- **3** = Partial, with a credible path to strengthening
+- **1** = Absent or high uncertainty
+
+---
+
+## Recommended Strategy
+
+<!-- After scoring, document the recommended approach and rationale -->
+
+**Lead with**:
+**Rationale**:
+**Key risks**:
+**Fallback if lead option fails**:

package/template/project.config.example.json

@@ -0,0 +1,31 @@
+{
+  "templateVersion": "1.0.0",
+  "templateSource": "github.com/DiffTheEnder/DSS-Claude-Stack",
+  "projectType": "",
+  "projectName": "",
+  "projectSlug": "",
+  "oneLineDescription": "",
+  "goal": "",
+  "team": "",
+  "scope": "",
+  "outOfScope": "",
+  "strategicHypothesis": "",
+  "icpDescription": "",
+  "entityType": "",
+  "entityTypePlural": "",
+  "pipelineSourceOfTruth": "data/entities.csv",
+  "dashboardUrl": "",
+  "modules": {
+    "discovery": true,
+    "pipeline": true,
+    "dashboard": true
+  },
+  "scoringDimensions": [
+    "White Space",
+    "Urgency",
+    "Feasibility",
+    "Defensibility",
+    "Revenue Potential"
+  ],
+  "killConditions": []
+}

package/template/scripts/build-cli-template.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Copies template files into cli/template/ for npm publishing.
+# Run from repo root or via cli/package.json prepublishOnly.
+
+set -e
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TEMPLATE_DIR="$REPO_ROOT/cli/template"
+
+echo "Building CLI template from repo..."
+
+# Clean previous build
+rm -rf "$TEMPLATE_DIR"
+mkdir -p "$TEMPLATE_DIR"
+
+# Copy everything except excluded paths
+rsync -a \
+  --exclude='.git' \
+  --exclude='node_modules' \
+  --exclude='.DS_Store' \
+  --exclude='cli' \
+  --exclude='.next' \
+  --exclude='.claude' \
+  --exclude='dashboard/data/*.json' \
+  --exclude='dashboard/screenshot.png' \
+  --exclude='project.config.json' \
+  --exclude='CONTRIBUTING.md' \
+  --exclude='.github/ISSUE_TEMPLATE' \
+  --exclude='.github/pull_request_template.md' \
+  "$REPO_ROOT/" "$TEMPLATE_DIR/"
+
+echo "✓ Template built at cli/template/"

package/template/scripts/health-check.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# health-check.sh
+# Lightweight CLI health check for the DS Strategy Stack.
+# Mirrors the checks in skills/health-check/SKILL.md.
+# Uses Australian English throughout.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+PASSES=0
+WARNS=0
+FAILS=0
+
+pass() {
+  echo "  [PASS] $1"
+  PASSES=$((PASSES + 1))
+}
+
+warn() {
+  echo "  [WARN] $1"
+  WARNS=$((WARNS + 1))
+}
+
+fail() {
+  echo "  [FAIL] $1"
+  FAILS=$((FAILS + 1))
+}
+
+echo "=== Project Health Check ==="
+echo "Project root: $PROJECT_ROOT"
+echo ""
+
+# -----------------------------------------------
+# Check 1: Unreplaced placeholders
+# -----------------------------------------------
+echo "--- Check 1: Unreplaced Placeholders ---"
+if "$SCRIPT_DIR/validate-placeholders.sh" > /dev/null 2>&1; then
+  pass "No unreplaced placeholders found."
+else
+  fail "Unreplaced {{PLACEHOLDER}} tokens remain. Run: scripts/validate-placeholders.sh for details."
+fi
+echo ""
+
+# -----------------------------------------------
+# Check 2: project.config.json exists
+# -----------------------------------------------
+echo "--- Check 2: Project Configuration ---"
+if [ -f "$PROJECT_ROOT/project.config.json" ]; then
+  pass "project.config.json exists."
+else
+  warn "project.config.json is missing. Onboarding may be incomplete."
+fi
+echo ""
+
+# -----------------------------------------------
+# Check 3: Dashboard data freshness
+# -----------------------------------------------
+echo "--- Check 3: Dashboard Data Freshness ---"
+
+# Helper: get file modification timestamp (cross-platform)
+file_mtime() {
+  if [[ "$(uname)" == "Darwin" ]]; then
+    stat -f %m "$1" 2>/dev/null || echo 0
+  else
+    stat -c %Y "$1" 2>/dev/null || echo 0
+  fi
+}
+
+STALE_COUNT=0
+# Map source files to their corresponding dashboard JSON
+declare -a SOURCES=("memory/research.md" "docs/executive-summary.md" "memory/MEMORY.md")
+declare -a JSONS=("dashboard/data/competitors.json" "dashboard/data/overview.json" "dashboard/data/entities.json")
+
+for i in "${!SOURCES[@]}"; do
+  SRC="$PROJECT_ROOT/${SOURCES[$i]}"
+  JSON="$PROJECT_ROOT/${JSONS[$i]}"
+
+  if [ -f "$SRC" ] && [ -f "$JSON" ]; then
+    SRC_TIME=$(file_mtime "$SRC")
+    JSON_TIME=$(file_mtime "$JSON")
+    if [ "$SRC_TIME" -gt "$JSON_TIME" ]; then
+      warn "Dashboard data stale: ${SOURCES[$i]} is newer than ${JSONS[$i]}."
+      STALE_COUNT=$((STALE_COUNT + 1))
+    fi
+  fi
+done
+
+if [ "$STALE_COUNT" -eq 0 ]; then
+  pass "Dashboard data appears up to date (or source/JSON files not yet created)."
+fi
+echo ""
+
+# -----------------------------------------------
+# Check 4: Versioned files (_v2, _old, _backup)
+# -----------------------------------------------
+echo "--- Check 4: Versioned / Backup Files ---"
+VERSIONED=$(find "$PROJECT_ROOT" \
+  \( -name "*_v[0-9]*" -o -name "*_old*" -o -name "*_backup*" \) \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" 2>/dev/null || true)
+
+if [ -z "$VERSIONED" ]; then
+  pass "No versioned or backup files found."
+else
+  VCOUNT=$(echo "$VERSIONED" | wc -l | tr -d ' ')
+  warn "$VCOUNT versioned/backup file(s) found. Keep only the latest version."
+  echo "$VERSIONED" | while read -r f; do echo "    -> $f"; done
+fi
+echo ""
+
+# -----------------------------------------------
+# Check 5: MEMORY.md line count
+# -----------------------------------------------
+echo "--- Check 5: MEMORY.md Size ---"
+MEMORY_FILE="$PROJECT_ROOT/memory/MEMORY.md"
+if [ -f "$MEMORY_FILE" ]; then
+  LINE_COUNT=$(wc -l < "$MEMORY_FILE" | tr -d ' ')
+  if [ "$LINE_COUNT" -gt 300 ]; then
+    fail "MEMORY.md is $LINE_COUNT lines (limit 300). Must prune immediately."
+  elif [ "$LINE_COUNT" -gt 200 ]; then
+    warn "MEMORY.md is $LINE_COUNT lines (recommended limit 200). Consider pruning."
+  else
+    pass "MEMORY.md is $LINE_COUNT lines. Within acceptable range."
+  fi
+else
+  warn "memory/MEMORY.md does not exist."
+fi
+echo ""
+
+# -----------------------------------------------
+# Summary
+# -----------------------------------------------
+echo "==========================================="
+echo "  Health Check Summary"
+echo "==========================================="
+echo "  Passed : $PASSES"
+echo "  Warnings: $WARNS"
+echo "  Failures: $FAILS"
+echo ""
+
+if [ "$FAILS" -gt 0 ]; then
+  echo "  Overall: FAIL — $FAILS critical issue(s) require attention."
+  exit 1
+elif [ "$WARNS" -gt 0 ]; then
+  echo "  Overall: WARN — No critical issues, but $WARNS warning(s) to address."
+  exit 0
+else
+  echo "  Overall: PASS — Project is healthy."
+  exit 0
+fi