@uasyraf/helm 0.1.0

package/hooks/hooks.json

@@ -0,0 +1,33 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @uasyraf/helm banner 2>/dev/null # helm: SessionStart",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y @uasyraf/helm hook post-tool-use 2>/dev/null # helm: PostToolUse",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "npx -y @uasyraf/helm banner 2>/dev/null # helm: statusline",
+    "padding": 0
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@uasyraf/helm",
+  "version": "0.1.0",
+  "description": "Plug-and-play MCP server + dashboard for durable, multi-developer project state. Sprints, epics, stories, tasks, code-linked tech debt.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "helm": "dist/bin/helm.js"
+  },
+  "main": "./dist/server/src/index.js",
+  "files": [
+    "dist",
+    "skills",
+    "hooks",
+    ".claude-plugin",
+    ".mcp.json",
+    "dashboard/build",
+    "dashboard/package.json",
+    "dashboard/svelte.config.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "tsx server/src/index.ts",
+    "dev": "tsx watch server/src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.14.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "drizzle-orm": "^0.36.0",
+    "zod": "^3.23.0"
+  },
+  "optionalDependencies": {
+    "pg": "^8.20.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.4.5",
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.10",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/backlog/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: backlog
+description: View and prioritise the backlog. Use for "what's in the backlog?", "show unsprinted stories", or planning the next sprint.
+---
+
+# /backlog
+
+The backlog is the view, not an entity: `stories WHERE sprint_id IS NULL ORDER BY priority`.
+
+## Common flows
+
+| User says | Tool |
+|---|---|
+| "what's in the backlog?" | `list_backlog` |
+| "pull X into the sprint" | `move_story(id, sprintId)` |
+| "send X back to backlog" | `move_story(id, sprintId: null)` |
+
+The dashboard's `/sprints` page is the visual equivalent — use the MCP tools when the user is in a Claude session; point them at the dashboard for drag-and-plan flows.

package/skills/debt/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: debt
+description: Tech debt — log, close, list. The killer feature. Use for "log this as debt", "what debt do we have?", "close DEBT-x", or anything tied to code-linked technical debt.
+---
+
+# /debt
+
+Tech debt is helm's differentiator. Use helm MCP tools.
+
+## Common flows
+
+| User says | Tool | Notes |
+|---|---|---|
+| "log this as debt" | `log_debt` | Include `location` (`file:line`) whenever possible |
+| "what debt do we have?" | `list_debt` | `includeClosed: true` for full history |
+| "close that debt" | `close_debt` | Counts toward killer metric for the active sprint |
+
+## Auto-detected debt
+
+The PostToolUse worker scans diffs for:
+- `// DEBT(key=value, ...)` markers (prefix: `//`, `#`, or `--`) — Q2-locked syntax
+- Files crossing 500 lines
+- TypeScript `: any` or `as any`
+
+Auto-detected items appear in `list_debt` within seconds of an Edit/Write. They're de-duplicated by location, so the same line won't fire twice.
+
+## Killer metric
+
+`(debt opened this sprint) − (debt closed this sprint)` = the number Linear/Jira structurally cannot compute, because they don't see code. Surfaces in `get_status` and `sprint_review`.
+
+## DEBT marker format
+
+```
+// DEBT(owner=alice, expires=2026-Q3, severity=high, ref=DBT-12): description
+# DEBT(owner=bob, expires=2026-12-01)
+-- DEBT(owner=carol)
+```
+
+Recognized fields: `owner`, `expires` (ISO date or `YYYY-Qn`), `severity` (`low|med|high|critical`), `ref`.

package/skills/epic/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: epic
+description: Epic lifecycle — open, update, close. Cross-sprint themes that group stories. Use for "open an epic for X", "close the auth epic", or theme-level planning.
+---
+
+# /epic
+
+Epics are cross-sprint themes (e.g. "auth overhaul", "billing v2"). Each epic contains stories. Use helm MCP tools.
+
+## Common flows
+
+| User says | Tool |
+|---|---|
+| "open an epic for X" | `open_epic` |
+| "close the X epic" | `close_epic` (set `dropped: true` to mark dropped instead of done) |
+| "update the epic" | `update_epic` |
+
+## Notes
+
+- Optional `target_sprint_id` for soft commitment. Stories under the epic can be in any sprint.
+- Status enum: `open | in-progress | done | dropped`.
+- Priority 1 (highest) to 5 (lowest), default 3.

package/skills/nelson-integration/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: nelson-integration
+description: Standing-orders addendum for Nelson — emit link_mission at Step 3 (Battle Plan approved) and log_progress at Step 7 (Captain's Log). Auto-invokes whenever Nelson runs a Tier 3 mission.
+---
+
+# helm + Nelson integration
+
+Two seam-points in Nelson's 8-step framework write durable project state to helm:
+
+## Step 3 — Battle Plan approved
+
+Immediately after the user approves the battle plan (Nelson's Step 5 permission gate), the squadron should call:
+
+```
+mcp__helm__link_mission(
+  missionId: "<nelson mission id>",
+  storyId: "<helm story id, if the mission targets one>",
+  sprintId: "<active sprint id, optional — defaults to active>",
+  summary: "<one-line mission brief>"
+)
+```
+
+This creates a `progress_event` row with `kind=mission.linked`, anchoring the mission to the planning surface. If the user hasn't opened a story yet, ask first — "Should I open a story for this mission?" — then call `open_story` followed by `link_mission`.
+
+## Step 7 — Captain's Log
+
+After Nelson's captain's log is written, the squadron should call:
+
+```
+mcp__helm__log_progress(
+  summary: "<mission complete: X files touched, Y debt added, Z debt closed>",
+  refId: "<nelson mission id>"
+)
+```
+
+This creates a `progress_event` row with `kind=progress.logged` tied to the mission. The dashboard's `/sprints/[id]` timeline then shows the mission alongside organic story/debt events.
+
+## Why a standing-orders addendum, not a hook
+
+Nelson's `SubagentStop` would fire mid-mission (after every subagent returns), producing noise. The Step 3 and Step 7 calls are deliberate captain-level acts, not subagent-level signals — they belong in Nelson's documented flow, not in a hook config.
+
+## Failure mode
+
+If helm isn't installed in the user's environment, both MCP calls return tool-not-found. Nelson should swallow this silently — helm integration is opt-in, not load-bearing.

package/skills/project-tracker/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: project-tracker
+description: Use when the user asks about durable project state — sprints, epics, stories, tasks, tech debt, decisions — or wants to record/log/check status across sessions. Triggers on phrases like "what's the state of", "log this as debt", "open a story", "sprint status", "debt delta", "who's working on", or any mention of helm/tracker tools.
+---
+
+# project-tracker
+
+You have access to the helm MCP server, which gives this project durable, shared state across Claude sessions and across teammates.
+
+## When to invoke
+
+Use helm tools whenever the user references project-level state that should survive the session. Examples:
+
+- "what's our sprint status?" → `get_status`
+- "open a story for the dashboard refactor" → `open_story`
+- "log this as tech debt" → `log_debt`
+- "move STORY-123 to the current sprint" → `move_story`
+- "what's the debt delta this sprint?" → `get_status` (or `sprint_review` if a sprint just closed)
+- "record this decision" → `record_decision`
+- "what did Alice do this week?" → `who_did_what(handle="alice")`
+
+## Boundary with other tools
+
+- **TodoWrite** = per-session decomposition. Throw-away. Not shared with teammates.
+- **helm task** = durable, team-shared implementation step inside a story. Survives sessions.
+- **claude-mem** = conversation memory. "What did I try yesterday?" goes there.
+- **helm** = project state. "What's the state of the auth epic?" goes here.
+
+If unsure: durable + shared = helm. Per-session + personal = TodoWrite. Conversation recall = claude-mem.
+
+## Tool surface (Phase 0)
+
+| Tool | Use for |
+|---|---|
+| `get_status` | Active sprint, story counts, open debt, killer metric |
+| `start_sprint` / `end_sprint` | Sprint lifecycle |
+| `sprint_review` | Sprint summary including debt delta |
+| `open_epic` / `update_epic` / `close_epic` | Cross-sprint themes |
+| `open_story` / `update_story` / `move_story` / `close_story` | The unit that gets pulled into a sprint |
+| `list_backlog` | Unsprinted stories by priority |
+| `open_task` / `update_task` / `close_task` | Implementation steps inside a story |
+| `log_debt` / `close_debt` / `list_debt` | Code-linked tech debt — the killer feature |
+| `record_decision` | ADR-lite capture |
+| `log_progress` | Free-form timeline event |
+| `link_mission` | Nelson Step 3 seam |
+| `who_did_what` | Developer activity feed |
+
+## Conventions
+
+- Story IDs are UUIDs. Don't make them up — fetch from `list_backlog` or `get_status` first.
+- The active sprint is auto-detected from session context. Pass `sprintId` explicitly only when targeting a different sprint.
+- When the user describes work that hasn't been opened as a story yet, suggest `open_story` first, then record progress against it.
+- Debt items should include `location` (`file:line` or symbol path) whenever the conversation references specific code.
+
+## Banner format
+
+The SessionStart hook prints: `[helm] sprint-N (dX/Y) | stories: a/b done | debt: N (Δ±M)`.
+- `dX/Y` = day X of an Y-day sprint
+- `a/b` = stories done / total in sprint
+- `Δ±M` = debt opened minus closed this sprint (the killer metric)

package/skills/review/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: review
+description: Sprint review — completed stories, velocity, killer metric. Use for "show me the review", "how did this sprint go?", "what was our debt delta?".
+---
+
+# /review
+
+Sprint review surfaces the four numbers that matter:
+
+1. Completed stories (count + titles + sizes)
+2. Velocity (sized stories closed)
+3. Debt opened during sprint
+4. Debt closed during sprint
+5. **Net delta** — the killer metric: opened − closed
+
+## Common flows
+
+| User says | Tool |
+|---|---|
+| "show me the review" | `sprint_review` (defaults to active sprint) |
+| "review sprint X" | `sprint_review(sprintId: "X")` |
+
+## Boundary
+
+Sprint review is a **view**, not a ceremony entity. helm does not model retro/planning/standup as data rows (PRD § Agile Model). Teams run the ceremonies; helm renders the view.
+
+The dashboard's `/sprints/[id]` route shows the same data plus the per-sprint event timeline.

package/skills/sprint/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: sprint
+description: Sprint lifecycle and status. Use for "what's our sprint status", "start a new sprint", "end this sprint", "show sprint review", or any cadence-level question.
+---
+
+# /sprint
+
+Use the helm MCP tools for sprint operations. The active sprint is auto-detected from session context.
+
+## Common flows
+
+| User says | Tool |
+|---|---|
+| "what's the sprint status?" | `get_status` |
+| "start a new sprint" | `start_sprint` (optionally with `name` + `goal`) |
+| "end this sprint" | `end_sprint` (auto-rolls incomplete stories to backlog per PRD F2) |
+| "show me the review" / "sprint summary" | `sprint_review` (defaults to active sprint) |
+
+## Notes
+
+- `end_sprint` rolls incomplete stories back to backlog (locked behavior — PRD Q4). Done and dropped stories stay attached.
+- Sprint length defaults to 14 days (per-project override via `sprint_length_days`).
+- The killer metric — debt delta this sprint — surfaces in both `get_status` and `sprint_review`.

package/skills/story/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: story
+description: Story lifecycle — open, update, move, close, list backlog. Use for "open a story", "move STORY-x to current sprint", "close this story", "what's in the backlog", or any user-valued-increment work.
+---
+
+# /story
+
+Stories are the unit pulled into a sprint and counted toward velocity. Use helm MCP tools for the lifecycle.
+
+## Common flows
+
+| User says | Tool | Notes |
+|---|---|---|
+| "open a story for X" | `open_story` | Pass `sprintId` to land in sprint, omit for backlog |
+| "move STORY-x to current sprint" | `move_story` | Pass `sprintId: null` to send back to backlog |
+| "close this story" | `close_story` | Sets `completed_at`, marks done |
+| "what's in the backlog?" | `list_backlog` | Sorted by priority |
+| "update the story title" | `update_story` | Pass only the fields that change |
+
+## Boundary with TodoWrite (resolved 2026-05-18, PRD Q5)
+
+- **TodoWrite** = per-session, throw-away decomposition. Not shared with teammates.
+- **helm story** = durable user-valued increment, team-shared, survives sessions.
+
+If unsure: is this a long-lived thing the team needs to see? → helm story. Is this just my plan for the next hour? → TodoWrite.
+
+## Story sizing
+
+T-shirts (XS/S/M/L/XL/XXL) by default per PRD Q12. Velocity chart counts done stories with size set. Skip sizing if the team doesn't ask for it.