@kennethsolomon/shipkit 3.4.0 → 3.6.0

package/README.md

@@ -243,6 +243,8 @@ Requirement changes → /sk:change → re-enter at correct step
 |---------|-------------|
 | `/sk:help` | Show all commands and workflow overview |
 | `/sk:status` | Show workflow and task status at a glance |
+| `/sk:dashboard` | Read-only workflow Kanban board — localhost server, multi-worktree |
+| `/sk:context` | Load all context files + output session brief for fast session start |
 | `/sk:skill-creator` | Create or improve ShipKit skills |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:brainstorming/SKILL.md

@@ -32,6 +32,7 @@ You MUST create a task for each of these items and complete them in order:
    - Key decisions made
    - Chosen approach + rationale
    - Open questions (if any remain)
+   Additionally, **append** an ADR entry to `docs/decisions.md` (see "Decisions Log" section below).
    (Optionally also write a full design doc to docs/plans/YYYY-MM-DD-<topic>-design.md)
 6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
 
@@ -89,13 +90,49 @@ digraph brainstorming {
 
 **Documentation:**
 - Write the findings to `tasks/findings.md` (required — captures problem, decisions, approach, rationale)
+- Append an ADR entry to `docs/decisions.md` (required — see "Decisions Log" section below)
 - Optionally: Create a full design doc at `docs/plans/YYYY-MM-DD-<topic>-design.md` for complex projects
-- Commit the findings and any design document to git
+- Commit the findings, decisions log entry, and any design document to git
 
 **Implementation:**
 - Invoke the writing-plans skill to create a detailed implementation plan
 - Do NOT invoke any other skill. writing-plans is the next step.
 
+## Decisions Log
+
+After writing findings to `tasks/findings.md`, also **append** an Architecture Decision Record (ADR) entry to `docs/decisions.md`. This file is **cumulative and append-only** — never overwrite or remove existing entries.
+
+### If `docs/decisions.md` does not exist
+
+Create it with this header before the first entry:
+
+```markdown
+# Architecture Decision Records
+
+A cumulative log of key design decisions made across features. Append-only — never overwrite.
+```
+
+### ADR Entry Format
+
+Append this template for each brainstorm decision:
+
+```markdown
+## [YYYY-MM-DD] [Feature/Task Name]
+
+**Context:** [problem being solved — 1-2 sentences]
+**Decision:** [chosen approach — 1 sentence]
+**Rationale:** [why this approach over alternatives]
+**Consequences:** [trade-offs accepted]
+**Status:** accepted
+```
+
+### Rules
+
+- **Append-only** — never edit or delete existing entries in `docs/decisions.md`
+- **One entry per brainstorm** — each completed brainstorm adds exactly one ADR entry
+- **Use absolute dates** — always `YYYY-MM-DD`, never relative dates
+- Entries accumulate across features — this is a project-level historical record
+
 ## Key Principles
 
 - **One question at a time** - Don't overwhelm with multiple questions

package/skills/sk:context/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: sk:context
+description: "Session initializer — loads all project context files and outputs a formatted session brief. Run this at the start of every conversation to orient the AI and yourself."
+---
+
+# /sk:context — Session Brief + Context Loader
+
+Load all project context files into the conversation and output a formatted session brief. Designed to be run at the **start of every session** for instant orientation.
+
+## What It Does
+
+1. **Reads** all context files (listed below) to load project state into the conversation
+2. **Outputs** a formatted SESSION BRIEF the user can read at a glance
+3. **Applies** all active lessons from `tasks/lessons.md` as standing constraints for the session
+
+## Hard Rules
+
+- **Read-only.** This skill does not modify any files.
+- **Graceful fallback.** Missing files are noted in the brief, not treated as errors.
+- **No questions.** This skill runs silently — it does not ask the user anything.
+
+---
+
+## Files to Read (in order)
+
+| # | File | What to Extract |
+|---|------|-----------------|
+| 1 | `tasks/todo.md` | Task name (from `# TODO —` heading), milestone progress, count of `- [x]` (done) vs `- [ ]` (pending) checkboxes |
+| 2 | `tasks/workflow-status.md` | Current step (row with `>> next <<`), step name, command to run |
+| 3 | `tasks/progress.md` | Last 5 entries only (most recent work). If file is large, read only the last 50 lines. |
+| 4 | `tasks/findings.md` | Current decisions, chosen approach, open questions |
+| 5 | `tasks/lessons.md` | All active lessons — read in full, apply as constraints for this session |
+| 6 | `docs/decisions.md` | If exists: last 3 ADR entries. If missing: note "no decisions log yet" |
+| 7 | `docs/vision.md` | If exists: product name + value proposition. If missing: note "no vision.md found" |
+
+### Reading Strategy
+
+- Read files 1-5 first (these are the core context).
+- Files 6-7 are optional — check if they exist before reading.
+- For `tasks/progress.md`: only read the last 50 lines to avoid loading a huge file.
+- If `tasks/todo.md` is missing: the project has no active task.
+- If `tasks/workflow-status.md` is missing: the workflow hasn't started.
+
+---
+
+## Output Format
+
+After reading all files, output this session brief:
+
+```
+╔══════════════════════════════════════════╗
+║            SESSION BRIEF                 ║
+╚══════════════════════════════════════════╝
+Branch:     [current git branch]
+Task:       [task name from todo.md, or "No active task"]
+Step:       [step #] [step name] → run `/sk:[command]`
+Last done:  [last progress.md entry summary, 1 line]
+Pending:    [N] checkboxes remaining in todo.md
+Lessons:    [count] active — [most critical 1-liner from lessons.md]
+Open Qs:    [open questions from findings.md, or "none"]
+Product:    [value prop from vision.md, or "no vision.md found"]
+════════════════════════════════════════════
+```
+
+### Field Rules
+
+- **Branch:** Run `git branch --show-current` to get the current branch name.
+- **Task:** Extract from the first `# TODO —` line in `tasks/todo.md`. If the file doesn't exist or all checkboxes are done, show "No active task — ready to start fresh".
+- **Step:** Find the row containing `>> next <<` in `tasks/workflow-status.md`. Extract step number, name, and command. If no `>> next <<` found, show "Workflow complete" or "Not started".
+- **Last done:** The most recent entry from `tasks/progress.md`. Summarize in one line.
+- **Pending:** Count `- [ ]` lines in `tasks/todo.md`. Stop counting at the first `## Verification`, `## Acceptance Criteria`, or `## Risks` heading (these are meta-sections, not tasks).
+- **Lessons:** Count `### [` headings in `tasks/lessons.md` (each lesson starts with `### [YYYY-MM-DD]`). Show the count + the **Prevention:** line from the most recent lesson.
+- **Open Qs:** Check for an "## Open Questions" section in `tasks/findings.md`. List them or say "none".
+- **Product:** From `docs/vision.md`, extract the value proposition. If file doesn't exist, say "no vision.md found".
+
+---
+
+## After the Brief
+
+After outputting the session brief:
+
+1. **State the active lessons** that apply as constraints. List each prevention rule as a bullet.
+2. **State what's next** — tell the user the next step and the command to run.
+3. If the user has a specific request, proceed with it (the context is now loaded).
+
+---
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| No `tasks/todo.md` | Show "No active task — ready to start fresh" |
+| No `tasks/workflow-status.md` | Show "Workflow not started" for Step field |
+| No `tasks/progress.md` | Show "No progress logged yet" for Last done |
+| No `tasks/findings.md` | Show "none" for Open Qs |
+| No `tasks/lessons.md` | Show "0 active" for Lessons |
+| No `docs/decisions.md` | Show "no decisions log yet" — do not error |
+| No `docs/vision.md` | Show "no vision.md found" — do not error |
+| All checkboxes done in todo.md | Show "Task complete — 0 pending" |
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:context"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | sonnet |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |
+
+> This skill is lightweight (read-only file operations + brief output). Sonnet is sufficient for all quality profiles. Haiku for budget.

package/skills/sk:dashboard/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: sk:dashboard
+description: Read-only workflow Kanban board — localhost server showing workflow status across git worktrees
+license: Complete terms in LICENSE.txt
+---
+
+# /sk:dashboard
+
+## Purpose
+
+Read-only Kanban board that visualizes workflow progress across all git worktrees in a project. Runs as a standalone localhost server — no workflow integration required. Use it anytime you want a visual overview of where each worktree stands in the workflow.
+
+## How to Start
+
+```bash
+node skills/sk:dashboard/server.js
+```
+
+Opens on `http://localhost:3333`. Stop with `Ctrl+C`.
+
+Override the port:
+
+```bash
+node skills/sk:dashboard/server.js --port 4000
+# or
+PORT=4000 node skills/sk:dashboard/server.js
+```
+
+## What It Shows
+
+- **Swimlanes per worktree** — one row per worktree discovered via `git worktree list`
+- **Phase timeline** — workflow steps laid out as columns (Read, Explore, Plan, Branch, Tests, Implement, Lint, Verify, Security, Review, E2E, Finalize)
+- **Status indicators** — done, skipped, partial, in-progress, not yet
+- **Progress bars** — percentage of steps completed per worktree
+- **Current task** — the active task name from `tasks/todo.md`
+
+## Architecture
+
+Zero-dependency Node.js server. Uses only built-in modules (`http`, `fs`, `path`, `child_process`).
+
+- `server.js` serves the dashboard HTML and exposes `/api/status`
+- `/api/status` reads `tasks/workflow-status.md` and `tasks/todo.md` from each worktree, parses step statuses, and returns JSON
+- `dashboard.html` is a single-file UI (HTML + embedded CSS + JS) that polls `/api/status` every 3 seconds
+- Worktree discovery via `git worktree list`
+
+## Key Details
+
+- Read-only — does not modify any files
+- Auto-discovers worktrees via `git worktree list`
+- Graceful degradation: missing files show empty state, offline falls back to system fonts
+- Default port 3333, configurable via `--port` flag or `PORT` env var
+- Uses only Node.js built-in modules (http, fs, path, child_process)
+
+## Files
+
+- `server.js` — Node.js HTTP server (~150 lines)
+- `dashboard.html` — Single-file Kanban UI (HTML + embedded CSS + JS)
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:dashboard"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | sonnet |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |