singularity-claude 0.1.0

package/scripts/score-manager.sh

@@ -0,0 +1,301 @@
+#!/usr/bin/env bash
+# score-manager.sh — CLI for managing singularity skill scores
+# Uses jq if available, falls back to node -e for JSON manipulation
+
+set -euo pipefail
+
+SINGULARITY_DATA="${HOME}/.claude/singularity"
+SCORES_DIR="${SINGULARITY_DATA}/scores"
+
+# JSON tool detection
+json_tool=""
+if command -v jq &>/dev/null; then
+  json_tool="jq"
+elif command -v node &>/dev/null; then
+  json_tool="node"
+else
+  echo "Error: Neither jq nor node found. Install one to use score-manager." >&2
+  exit 1
+fi
+
+# Atomic write: write to temp file, then rename
+atomic_write() {
+  local target="$1"
+  local content="$2"
+  local tmp="${target}.tmp.$$"
+  printf '%s' "$content" > "$tmp"
+  mv "$tmp" "$target"
+}
+
+# Read JSON file and extract with jq or node
+json_query() {
+  local file="$1"
+  local query="$2"
+  if [ "$json_tool" = "jq" ]; then
+    jq -r "$query" "$file"
+  else
+    node -e "const d=JSON.parse(require('fs').readFileSync('${file}','utf8')); const q=${query}; console.log(typeof q==='object'?JSON.stringify(q,null,2):q)"
+  fi
+}
+
+usage() {
+  cat <<'EOF'
+Usage: score-manager.sh <command> <skill-name> [options]
+
+Commands:
+  init <skill>                     Create score file for a new skill
+  add <skill> <score>              Record a score (0-100)
+    [--version <ver>]              Version (auto-detected from git tag or v1.0.0)
+    [--context <text>]             What the skill was used for
+    [--strengths <json-array>]     What went well
+    [--weaknesses <json-array>]    What needs improvement
+    [--edge-cases <json-array>]    Edge cases encountered
+  list <skill>                     Show score history
+  average <skill> [--version <v>]  Get average score
+  trend <skill>                    Show score trend across versions
+  maturity <skill>                 Get current maturity level
+EOF
+  exit 1
+}
+
+cmd_init() {
+  local skill="$1"
+  local file="${SCORES_DIR}/${skill}.json"
+
+  if [ -f "$file" ]; then
+    echo "Score file already exists for '${skill}'" >&2
+    exit 1
+  fi
+
+  mkdir -p "${SCORES_DIR}"
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  local content
+  content=$(cat <<INIT
+{
+  "\$schema": "singularity-score-v1",
+  "skillName": "${skill}",
+  "versions": [
+    {
+      "version": "v1.0.0",
+      "gitTag": "singularity/${skill}/v1.0.0",
+      "scores": [],
+      "averageScore": 0,
+      "executionCount": 0,
+      "maturity": "draft"
+    }
+  ],
+  "currentVersion": "v1.0.0",
+  "createdAt": "${now}",
+  "lastScoredAt": null
+}
+INIT
+)
+  atomic_write "$file" "$content"
+  echo "Initialized score file for '${skill}'"
+}
+
+cmd_add() {
+  local skill="$1"
+  local score="$2"
+  shift 2
+
+  # Parse optional args
+  local version="" context="" strengths="[]" weaknesses="[]" edge_cases="[]"
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --version) version="$2"; shift 2 ;;
+      --context) context="$2"; shift 2 ;;
+      --strengths) strengths="$2"; shift 2 ;;
+      --weaknesses) weaknesses="$2"; shift 2 ;;
+      --edge-cases) edge_cases="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+
+  # Validate score
+  if ! [[ "$score" =~ ^[0-9]+$ ]] || [ "$score" -lt 0 ] || [ "$score" -gt 100 ]; then
+    echo "Error: Score must be 0-100" >&2
+    exit 1
+  fi
+
+  local file="${SCORES_DIR}/${skill}.json"
+  if [ ! -f "$file" ]; then
+    echo "Error: No score file for '${skill}'. Run 'init' first." >&2
+    exit 1
+  fi
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+  # Use current version if not specified
+  if [ -z "$version" ]; then
+    version=$(jq -r '.currentVersion' "$file" 2>/dev/null || echo "v1.0.0")
+  fi
+
+  if [ "$json_tool" = "jq" ]; then
+    local updated
+    updated=$(jq --arg ver "$version" --argjson score "$score" --arg ts "$now" \
+      --arg ctx "$context" --argjson str "$strengths" --argjson weak "$weaknesses" \
+      --argjson edge "$edge_cases" '
+      .lastScoredAt = $ts |
+      (.versions[] | select(.version == $ver)) |= (
+        .scores += [{
+          "timestamp": $ts,
+          "score": $score,
+          "context": $ctx,
+          "strengths": $str,
+          "weaknesses": $weak,
+          "edgeCasesEncountered": $edge
+        }] |
+        .executionCount = (.scores | length) |
+        .averageScore = ((.scores | map(.score) | add) / (.scores | length) | floor)
+      )
+    ' "$file")
+    atomic_write "$file" "$updated"
+  else
+    node -e "
+      const fs = require('fs');
+      const d = JSON.parse(fs.readFileSync('${file}', 'utf8'));
+      const v = d.versions.find(v => v.version === '${version}');
+      if (!v) { console.error('Version not found'); process.exit(1); }
+      v.scores.push({
+        timestamp: '${now}', score: ${score}, context: '${context}',
+        strengths: ${strengths}, weaknesses: ${weaknesses},
+        edgeCasesEncountered: ${edge_cases}
+      });
+      v.executionCount = v.scores.length;
+      v.averageScore = Math.floor(v.scores.reduce((s,e) => s + e.score, 0) / v.scores.length);
+      d.lastScoredAt = '${now}';
+      fs.writeFileSync('${file}', JSON.stringify(d, null, 2));
+    "
+  fi
+
+  # Compute and update maturity
+  _update_maturity "$skill" "$version"
+
+  # Show result
+  local avg
+  avg=$(jq -r --arg ver "$version" '.versions[] | select(.version == $ver) | .averageScore' "$file" 2>/dev/null || echo "?")
+  local count
+  count=$(jq -r --arg ver "$version" '.versions[] | select(.version == $ver) | .executionCount' "$file" 2>/dev/null || echo "?")
+  echo "Recorded score ${score} for ${skill} ${version} (avg: ${avg}/100, ${count} runs)"
+}
+
+_update_maturity() {
+  local skill="$1"
+  local version="$2"
+  local file="${SCORES_DIR}/${skill}.json"
+
+  if [ "$json_tool" = "jq" ]; then
+    local updated
+    updated=$(jq --arg ver "$version" '
+      (.versions[] | select(.version == $ver)) |= (
+        .maturity = (
+          if .maturity == "crystallized" then "crystallized"
+          elif .executionCount >= 5 and .averageScore >= 80 and (.scores | map(.edgeCasesEncountered // []) | flatten | length) > 0 then "hardened"
+          elif .executionCount >= 3 and .averageScore >= 60 then "tested"
+          else "draft"
+          end
+        )
+      )
+    ' "$file")
+    atomic_write "$file" "$updated"
+  fi
+}
+
+cmd_list() {
+  local skill="$1"
+  local file="${SCORES_DIR}/${skill}.json"
+
+  if [ ! -f "$file" ]; then
+    echo "No score file for '${skill}'" >&2
+    exit 1
+  fi
+
+  if [ "$json_tool" = "jq" ]; then
+    jq -r '
+      .versions[] |
+      "Version: \(.version) | Maturity: \(.maturity) | Avg: \(.averageScore)/100 | Runs: \(.executionCount)",
+      (.scores[] | "  [\(.timestamp)] Score: \(.score) — \(.context // "no context")")
+    ' "$file"
+  else
+    node -e "
+      const d = JSON.parse(require('fs').readFileSync('${file}', 'utf8'));
+      d.versions.forEach(v => {
+        console.log('Version: ' + v.version + ' | Maturity: ' + v.maturity + ' | Avg: ' + v.averageScore + '/100 | Runs: ' + v.executionCount);
+        v.scores.forEach(s => console.log('  [' + s.timestamp + '] Score: ' + s.score + ' — ' + (s.context || 'no context')));
+      });
+    "
+  fi
+}
+
+cmd_average() {
+  local skill="$1"
+  shift
+  local version=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --version) version="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+
+  local file="${SCORES_DIR}/${skill}.json"
+  if [ ! -f "$file" ]; then
+    echo "No score file for '${skill}'" >&2
+    exit 1
+  fi
+
+  if [ -n "$version" ]; then
+    jq -r --arg ver "$version" '.versions[] | select(.version == $ver) | .averageScore' "$file"
+  else
+    jq -r '.versions[-1].averageScore' "$file"
+  fi
+}
+
+cmd_trend() {
+  local skill="$1"
+  local file="${SCORES_DIR}/${skill}.json"
+
+  if [ ! -f "$file" ]; then
+    echo "No score file for '${skill}'" >&2
+    exit 1
+  fi
+
+  jq -r '
+    .versions | to_entries[] |
+    "\(.value.version)\t\(.value.averageScore)\t\(.value.executionCount)\t\(.value.maturity)"
+  ' "$file" | while IFS=$'\t' read -r ver avg count mat; do
+    printf "%-10s  avg: %3s/100  runs: %s  maturity: %s\n" "$ver" "$avg" "$count" "$mat"
+  done
+}
+
+cmd_maturity() {
+  local skill="$1"
+  local file="${SCORES_DIR}/${skill}.json"
+
+  if [ ! -f "$file" ]; then
+    echo "No score file for '${skill}'" >&2
+    exit 1
+  fi
+
+  jq -r '.versions[-1].maturity' "$file"
+}
+
+# Main dispatch
+[ $# -lt 2 ] && usage
+
+cmd="$1"
+shift
+
+case "$cmd" in
+  init) cmd_init "$@" ;;
+  add) cmd_add "$@" ;;
+  list) cmd_list "$@" ;;
+  average) cmd_average "$@" ;;
+  trend) cmd_trend "$@" ;;
+  maturity) cmd_maturity "$@" ;;
+  *) usage ;;
+esac

package/scripts/telemetry-writer.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# telemetry-writer.sh — CLI for singularity skill telemetry
+# Writes structured JSON logs for skill execution auditing
+
+set -euo pipefail
+
+SINGULARITY_DATA="${HOME}/.claude/singularity"
+TELEMETRY_DIR="${SINGULARITY_DATA}/telemetry"
+
+usage() {
+  cat <<'EOF'
+Usage: telemetry-writer.sh <command> <skill-name> [options]
+
+Commands:
+  log <skill> [options]            Record a telemetry entry
+    --trigger <type>               How the skill was invoked (user-invoked, auto-repair, gap-detected)
+    --version <ver>                Skill version (default: from registry)
+    --summary <text>               What happened
+    --score <n>                    Score if available
+    --error <text>                 Error message if failed
+    --edge-case <text>             Edge case encountered
+    --files-created <json-array>   Files created
+    --files-modified <json-array>  Files modified
+    --duration <ms>                Execution duration in milliseconds
+
+  list <skill> [--last <n>]        Show recent telemetry entries (default: 10)
+
+  replay <skill> <timestamp>       Show full telemetry entry
+
+  prune [--days <n>]               Remove entries older than n days (default: 90)
+EOF
+  exit 1
+}
+
+cmd_log() {
+  local skill="$1"
+  shift
+
+  # Parse options
+  local trigger="user-invoked" version="" summary="" score="" error="" edge_case=""
+  local files_created="[]" files_modified="[]" duration="0"
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --trigger) trigger="$2"; shift 2 ;;
+      --version) version="$2"; shift 2 ;;
+      --summary) summary="$2"; shift 2 ;;
+      --score) score="$2"; shift 2 ;;
+      --error) error="$2"; shift 2 ;;
+      --edge-case) edge_case="$2"; shift 2 ;;
+      --files-created) files_created="$2"; shift 2 ;;
+      --files-modified) files_modified="$2"; shift 2 ;;
+      --duration) duration="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+
+  # Auto-detect version from registry
+  if [ -z "$version" ] && [ -f "${SINGULARITY_DATA}/registry.json" ] && command -v jq &>/dev/null; then
+    version=$(jq -r --arg s "$skill" '.skills[$s].currentVersion // "v1.0.0"' "${SINGULARITY_DATA}/registry.json" 2>/dev/null || echo "v1.0.0")
+  fi
+  [ -z "$version" ] && version="v1.0.0"
+
+  local now
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  local short_id
+  short_id=$(head -c 4 /dev/urandom | xxd -p | head -c 8)
+  local date_part
+  date_part=$(date -u +"%Y-%m-%d-%H-%M-%S")
+
+  local skill_dir="${TELEMETRY_DIR}/${skill}"
+  mkdir -p "$skill_dir"
+
+  local filename="${date_part}-${short_id}.json"
+  local filepath="${skill_dir}/${filename}"
+
+  # Build score field
+  local score_field="null"
+  [ -n "$score" ] && score_field="$score"
+
+  # Build errors array
+  local errors_field="[]"
+  [ -n "$error" ] && errors_field="[\"$(printf '%s' "$error" | sed 's/"/\\"/g')\"]"
+
+  # Build edge cases array
+  local edge_cases_field="[]"
+  [ -n "$edge_case" ] && edge_cases_field="[\"$(printf '%s' "$edge_case" | sed 's/"/\\"/g')\"]"
+
+  cat > "$filepath" << ENTRY
+{
+  "\$schema": "singularity-telemetry-v1",
+  "skillName": "${skill}",
+  "version": "${version}",
+  "timestamp": "${now}",
+  "trigger": "${trigger}",
+  "inputs": {},
+  "outputs": {
+    "filesCreated": ${files_created},
+    "filesModified": ${files_modified},
+    "summary": "$(printf '%s' "$summary" | sed 's/"/\\"/g')"
+  },
+  "duration_ms": ${duration},
+  "score": ${score_field},
+  "errors": ${errors_field},
+  "edgeCases": ${edge_cases_field},
+  "repairTriggered": false
+}
+ENTRY
+
+  echo "Telemetry logged: ${filepath}"
+}
+
+cmd_list() {
+  local skill="$1"
+  shift
+  local last=10
+
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --last) last="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+
+  local skill_dir="${TELEMETRY_DIR}/${skill}"
+  if [ ! -d "$skill_dir" ]; then
+    echo "No telemetry for '${skill}'" >&2
+    exit 1
+  fi
+
+  # List most recent entries
+  ls -1t "$skill_dir"/*.json 2>/dev/null | head -n "$last" | while read -r f; do
+    if command -v jq &>/dev/null; then
+      jq -r '"[\(.timestamp)] \(.trigger) | score: \(.score // "n/a") | \(.outputs.summary // "no summary")"' "$f"
+    else
+      basename "$f"
+    fi
+  done
+}
+
+cmd_replay() {
+  local skill="$1"
+  local timestamp="$2"
+  local skill_dir="${TELEMETRY_DIR}/${skill}"
+
+  # Find matching file
+  local match
+  match=$(ls -1 "${skill_dir}/"*"${timestamp}"* 2>/dev/null | head -1)
+
+  if [ -z "$match" ]; then
+    echo "No telemetry entry matching '${timestamp}' for '${skill}'" >&2
+    exit 1
+  fi
+
+  if command -v jq &>/dev/null; then
+    jq '.' "$match"
+  else
+    cat "$match"
+  fi
+}
+
+cmd_prune() {
+  local days=90
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --days) days="$2"; shift 2 ;;
+      *) shift ;;
+    esac
+  done
+
+  local count=0
+  find "$TELEMETRY_DIR" -name "*.json" -mtime +"$days" -print0 2>/dev/null | while IFS= read -r -d '' f; do
+    rm "$f"
+    count=$((count + 1))
+  done
+  echo "Pruned ${count} entries older than ${days} days"
+}
+
+# Main dispatch
+[ $# -lt 1 ] && usage
+
+cmd="$1"
+shift
+
+case "$cmd" in
+  log) [ $# -lt 1 ] && usage; cmd_log "$@" ;;
+  list) [ $# -lt 1 ] && usage; cmd_list "$@" ;;
+  replay) [ $# -lt 2 ] && usage; cmd_replay "$@" ;;
+  prune) cmd_prune "$@" ;;
+  *) usage ;;
+esac

package/skills/creating-skills/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: creating-skills
+description: Use when a new reusable skill needs to be built, either detected by gap analysis, requested by the user, or triggered by /singularity-create
+---
+
+# Create a New Skill
+
+Build a new Claude Code skill through a structured workflow that ensures quality, testability, and integration with the singularity evolution engine.
+
+## Prerequisites
+
+- Read `superpowers:writing-skills` if available — it defines SKILL.md authoring best practices
+- This skill creates standard Claude Code skills usable by any plugin
+
+## Workflow
+
+### Step 1: Requirements Gathering
+
+Ask the user ONE question at a time:
+
+1. **What** does this skill do? (core purpose in one sentence)
+2. **When** should it trigger? (symptoms, conditions, error messages)
+3. **What tools** does it need? (Read, Write, Edit, Bash, Agent, etc.)
+4. **What's the output?** (files created, code modified, analysis produced)
+
+### Step 2: Check Registry
+
+Read `~/.claude/singularity/registry.json` to verify no duplicate or overlapping skill exists.
+
+If a similar skill exists, ask: *"A skill called '<name>' already covers <overlap>. Should I extend it or create a separate skill?"*
+
+### Step 3: Generate SKILL.md
+
+Create the skill following these conventions:
+
+```yaml
+---
+name: <skill-name>  # kebab-case, verb-first (e.g., creating-api-clients)
+description: Use when <triggering conditions>  # Max 500 chars, start with "Use when"
+---
+```
+
+**Content structure:**
+- Overview (1-2 sentences)
+- When to use / when NOT to use
+- Workflow steps (numbered, actionable)
+- Common mistakes / red flags
+- Integration with other skills (if applicable)
+
+**Rules:**
+- Description = triggering conditions ONLY, not what the skill does
+- Keep under 500 words for frequently-used skills
+- Use cross-references (`superpowers:skill-name`) not file paths
+- Include a "When NOT to use" section
+
+### Step 4: Write the Skill
+
+Write to `~/.claude/skills/<skill-name>/SKILL.md`
+
+If the skill needs supporting files (templates, rubrics, scripts), create them in:
+`~/.claude/skills/<skill-name>/references/`
+
+### Step 5: Register
+
+Update `~/.claude/singularity/registry.json`:
+
+```bash
+# Using score-manager to initialize scoring
+"${CLAUDE_PLUGIN_ROOT}/scripts/score-manager.sh" init <skill-name>
+```
+
+Then update registry.json to add the skill entry:
+```json
+{
+  "skills": {
+    "<skill-name>": {
+      "location": "~/.claude/skills/<skill-name>/SKILL.md",
+      "createdBy": "singularity-claude:creating-skills",
+      "createdAt": "<ISO-8601>",
+      "currentVersion": "v1.0.0",
+      "maturity": "draft",
+      "tags": ["<relevant>", "<tags>"],
+      "lastExecuted": null,
+      "executionCount": 0,
+      "averageScore": 0
+    }
+  }
+}
+```
+
+### Step 6: Initial Test
+
+Invoke the newly created skill via the `Skill` tool to verify it loads correctly.
+
+### Step 7: Initial Score
+
+Run `singularity-claude:scoring` on the test output to establish a baseline score.
+
+### Step 8: Log Telemetry
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/telemetry-writer.sh" log <skill-name> \
+  --trigger "creation" \
+  --summary "Created new skill: <description>"
+```
+
+## Output
+
+After creation, report:
+- Skill location: `~/.claude/skills/<skill-name>/SKILL.md`
+- Initial version: v1.0.0
+- Maturity: draft
+- Next steps: use the skill, then score with `/singularity-score`

package/skills/creating-skills/references/scoring-template.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "singularity-score-v1",
+  "skillName": "{{SKILL_NAME}}",
+  "versions": [
+    {
+      "version": "v1.0.0",
+      "gitTag": "singularity/{{SKILL_NAME}}/v1.0.0",
+      "scores": [],
+      "averageScore": 0,
+      "executionCount": 0,
+      "maturity": "draft"
+    }
+  ],
+  "currentVersion": "v1.0.0",
+  "createdAt": "{{TIMESTAMP}}",
+  "lastScoredAt": null
+}

package/skills/creating-skills/references/skill-template.md

@@ -0,0 +1,36 @@
+---
+name: {{SKILL_NAME}}
+description: Use when {{TRIGGERING_CONDITIONS}}
+---
+
+# {{SKILL_TITLE}}
+
+{{OVERVIEW — 1-2 sentences describing the core purpose}}
+
+## When to Use
+
+- {{Symptom or condition 1}}
+- {{Symptom or condition 2}}
+
+## When NOT to Use
+
+- {{Anti-pattern or wrong context}}
+
+## Workflow
+
+### Step 1: {{First action}}
+
+{{Instructions}}
+
+### Step 2: {{Second action}}
+
+{{Instructions}}
+
+## Common Mistakes
+
+- **{{Mistake}}** — {{Why it's wrong and what to do instead}}
+
+## Red Flags
+
+- Never {{dangerous action}}
+- Always {{safety measure}}