@kennethsolomon/shipkit 3.5.0 → 3.6.0

package/README.md

@@ -244,6 +244,7 @@ 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.5.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:mvp/SKILL.md

@@ -215,7 +215,84 @@ Maximum 3 loop iterations. If issues persist after 3 loops, present remaining is
 
 ---
 
-## Step 9 — Present the Output
+## Step 9 — Generate Project Context Docs
+
+Generate 3 lightweight documentation files in `docs/` from information already gathered in Steps 1-2. No new questions — use the product name, value prop, audience, features, and tech stack already captured.
+
+### Files to Generate
+
+**`docs/vision.md`**
+```markdown
+# [Product Name]
+
+## Value Proposition
+[One-line value prop from Step 1]
+
+## Target Audience
+[Target audience from Step 1]
+
+## Key Features
+[Bullet list of 3-5 features from Step 1]
+
+## North Star Metric
+[Suggest one metric that measures core value — e.g., "weekly active waitlist signups" or "daily feature usage"]
+```
+
+**`docs/prd.md`**
+```markdown
+# PRD — [Product Name]
+
+## Overview
+[1-2 sentence product description]
+
+## User Stories
+[For each key feature from Step 1, write a user story: "As a [audience], I want to [feature] so that [benefit]"]
+
+## Feature Acceptance Criteria
+[For each feature, list 2-3 concrete acceptance criteria]
+
+## Out of Scope (MVP)
+- Real authentication
+- Real database
+- Third-party integrations
+- Deployment
+```
+
+**`docs/tech-design.md`**
+```markdown
+# Tech Design — [Product Name]
+
+## Stack
+- **Framework:** [chosen stack from Step 2]
+- **Styling:** Tailwind CSS
+- **Fonts:** [chosen fonts]
+
+## Project Structure
+[List the key directories and files generated during scaffolding]
+
+## Component Map
+### Landing Page
+[List all 9 sections and their components]
+
+### App Pages
+[List each page and its key components]
+
+## Data Model
+### Waitlist
+- email: string (validated)
+- timestamp: ISO 8601 string
+
+### Fake Data Entities
+[List the fake data structures used in the app]
+```
+
+After generating the docs, output:
+> **Context docs generated:** `docs/vision.md`, `docs/prd.md`, `docs/tech-design.md`
+> These persist context for future sessions. Run `/sk:context` to load `docs/vision.md` into the session brief, or read the others directly.
+
+---
+
+## Step 10 — Present the Output
 
 Summarize what was generated:
 

package/skills/sk:setup-claude/templates/CLAUDE.md.template

@@ -363,4 +363,5 @@ Create entries in: `[ARCH_CHANGELOG_DIR]`
 | `/sk:features` | Sync feature specs with shipped implementation |
 | `/sk:release` | Version bump + changelog + tag |
 | `/sk:status` | Show workflow + task status |
+| `/sk:context` | Load all context files + output session brief for fast session start |
 | `/sk:setup-optimizer` | Diagnose + update workflow + enrich CLAUDE.md |