learnship 1.9.0

package/learnship/workflows/sync-upstream-skills.md

@@ -0,0 +1,269 @@
+---
+description: Sync agentic-learning and impeccable skills from their upstream repos (FavioVazquez/agentic-learn + pbakaus/impeccable) — run this when upstream skills have been updated
+---
+
+# sync-upstream-skills
+
+Pull the latest skill content from both upstream repositories into learnship's skill tree, then re-run the installer so all platforms receive the updated skills.
+
+**Usage:** `/sync-upstream-skills`
+
+**What this touches:**
+- `.windsurf/skills/agentic-learning/SKILL.md` — replaced from upstream
+- `.windsurf/skills/agentic-learning/references/` — replaced from upstream
+- `.windsurf/skills/impeccable/<sub-skill>/` — each of 18 sub-skill dirs replaced from upstream
+- `.windsurf/skills/impeccable/SKILL.md` — **NOT touched** (this is learnship's own dispatcher)
+
+---
+
+## Step 1: Verify prerequisites
+
+```bash
+command -v git >/dev/null 2>&1 && echo "git: OK" || echo "git: MISSING"
+command -v node >/dev/null 2>&1 && echo "node: OK" || echo "node: MISSING"
+test -f "$(pwd)/bin/install.js" && echo "installer: OK" || echo "installer: MISSING — run from learnship repo root"
+```
+
+If any check fails, stop and report what is missing.
+
+---
+
+## Step 2: Check current upstream state
+
+Show the user what they're about to pull so there are no surprises:
+
+```bash
+# Latest commit on agentic-learn main
+git ls-remote https://github.com/FavioVazquez/agentic-learn.git HEAD | awk '{print "agentic-learn HEAD: " $1}'
+
+# Latest commit on impeccable main
+git ls-remote https://github.com/pbakaus/impeccable.git HEAD | awk '{print "impeccable HEAD:    " $1}'
+```
+
+Also show current local state:
+```bash
+# What version of SKILL.md do we currently have for agentic-learning?
+head -6 "$(pwd)/.windsurf/skills/agentic-learning/SKILL.md"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► UPSTREAM SKILL SYNC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Will pull from:
+  agentic-learn  → github.com/FavioVazquez/agentic-learn (main)
+  impeccable     → github.com/pbakaus/impeccable (main)
+
+Files updated:
+  .windsurf/skills/agentic-learning/SKILL.md
+  .windsurf/skills/agentic-learning/references/   (full replace)
+  .windsurf/skills/impeccable/<18 sub-skills>/    (full replace each)
+
+Files preserved (learnship-owned):
+  .windsurf/skills/impeccable/SKILL.md            (dispatcher — never touched)
+
+Proceed? (yes/no)
+```
+
+Wait for confirmation.
+
+---
+
+## Step 3: Clone upstreams into temp dirs
+
+```bash
+TMPDIR=$(mktemp -d)
+AGENTIC_LEARN_TMP="$TMPDIR/agentic-learn"
+IMPECCABLE_TMP="$TMPDIR/impeccable"
+
+echo "Cloning agentic-learn..."
+git clone --depth 1 https://github.com/FavioVazquez/agentic-learn.git "$AGENTIC_LEARN_TMP"
+
+echo "Cloning impeccable..."
+git clone --depth 1 https://github.com/pbakaus/impeccable.git "$IMPECCABLE_TMP"
+
+echo "Clone complete."
+ls "$AGENTIC_LEARN_TMP"
+ls "$IMPECCABLE_TMP/source/skills/"
+```
+
+Confirm both clones succeeded — `SKILL.md` must exist in `$AGENTIC_LEARN_TMP` and the 18 sub-skill dirs must exist under `$IMPECCABLE_TMP/source/skills/`. If either is missing, stop.
+
+---
+
+## Step 4: Back up current skills
+
+```bash
+BACKUP_DIR="$(pwd)/.windsurf/skills/.upstream-backup-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$BACKUP_DIR"
+
+cp -r "$(pwd)/.windsurf/skills/agentic-learning" "$BACKUP_DIR/agentic-learning"
+cp -r "$(pwd)/.windsurf/skills/impeccable" "$BACKUP_DIR/impeccable"
+
+echo "Backup created at: $BACKUP_DIR"
+```
+
+---
+
+## Step 5: Sync agentic-learning
+
+Replace `SKILL.md` and `references/` verbatim from upstream. The upstream repo root IS the skill — `SKILL.md` lives at the repo root, references live in `references/`.
+
+```bash
+SKILL_DIR="$(pwd)/.windsurf/skills/agentic-learning"
+
+# Replace SKILL.md
+cp "$AGENTIC_LEARN_TMP/SKILL.md" "$SKILL_DIR/SKILL.md"
+
+# Replace references/ entirely
+rm -rf "$SKILL_DIR/references"
+cp -r "$AGENTIC_LEARN_TMP/references" "$SKILL_DIR/references"
+
+echo "agentic-learning synced:"
+echo "  SKILL.md — replaced"
+echo "  references/ — $(ls "$SKILL_DIR/references" | wc -l | tr -d ' ') files replaced"
+```
+
+---
+
+## Step 6: Sync impeccable sub-skills
+
+Upstream layout: `source/skills/<sub-skill>/SKILL.md` (+ any reference files).
+Learnship layout: `.windsurf/skills/impeccable/<sub-skill>/SKILL.md`.
+
+**Important:** Do NOT touch `.windsurf/skills/impeccable/SKILL.md` — that is learnship's own dispatcher file.
+
+```bash
+IMPECCABLE_SRC="$IMPECCABLE_TMP/source/skills"
+IMPECCABLE_DEST="$(pwd)/.windsurf/skills/impeccable"
+
+# Save learnship's dispatcher SKILL.md before any operations
+DISPATCHER_CONTENT=$(cat "$IMPECCABLE_DEST/SKILL.md")
+
+synced=0
+for sub_dir in "$IMPECCABLE_SRC"/*/; do
+  skill_name=$(basename "$sub_dir")
+
+  # Verify it has a SKILL.md
+  if [ ! -f "$sub_dir/SKILL.md" ]; then
+    echo "  SKIP $skill_name — no SKILL.md found upstream"
+    continue
+  fi
+
+  # Replace the sub-skill dir entirely
+  rm -rf "$IMPECCABLE_DEST/$skill_name"
+  cp -r "$sub_dir" "$IMPECCABLE_DEST/$skill_name"
+  echo "  ✓ $skill_name"
+  synced=$((synced + 1))
+done
+
+# Restore dispatcher SKILL.md (in case it was accidentally touched)
+echo "$DISPATCHER_CONTENT" > "$IMPECCABLE_DEST/SKILL.md"
+
+echo ""
+echo "impeccable synced: $synced sub-skills replaced"
+echo "impeccable/SKILL.md preserved (learnship dispatcher)"
+```
+
+---
+
+## Step 7: Verify sync integrity
+
+Check all 18 expected sub-skills are present and have a `SKILL.md`:
+
+```bash
+IMPECCABLE_DEST="$(pwd)/.windsurf/skills/impeccable"
+expected="adapt animate audit bolder clarify colorize critique delight distill extract frontend-design harden normalize onboard optimize polish quieter teach-impeccable"
+missing=""
+
+for skill in $expected; do
+  if [ ! -f "$IMPECCABLE_DEST/$skill/SKILL.md" ]; then
+    missing="$missing $skill"
+  fi
+done
+
+if [ -n "$missing" ]; then
+  echo "WARNING: missing sub-skills after sync:$missing"
+  echo "Restoring from backup..."
+  cp -r "$BACKUP_DIR/impeccable/." "$IMPECCABLE_DEST/"
+  echo "Restored. Check upstream structure manually."
+else
+  echo "All 18 impeccable sub-skills present ✓"
+fi
+
+# Verify dispatcher is still intact
+if grep -q "name: impeccable" "$IMPECCABLE_DEST/SKILL.md"; then
+  echo "impeccable/SKILL.md dispatcher intact ✓"
+else
+  echo "WARNING: dispatcher SKILL.md looks wrong — restoring"
+  cp "$BACKUP_DIR/impeccable/SKILL.md" "$IMPECCABLE_DEST/SKILL.md"
+fi
+
+# Verify agentic-learning
+if grep -q "name: agentic-learning" "$(pwd)/.windsurf/skills/agentic-learning/SKILL.md"; then
+  echo "agentic-learning/SKILL.md present ✓"
+else
+  echo "WARNING: agentic-learning SKILL.md looks wrong — restoring"
+  cp "$BACKUP_DIR/agentic-learning/SKILL.md" "$(pwd)/.windsurf/skills/agentic-learning/SKILL.md"
+fi
+```
+
+---
+
+## Step 8: Re-run installer for all platforms
+
+Propagate updated skills to every installed platform (Claude Code plugins, Windsurf, OpenCode, Gemini CLI, Codex context files):
+
+```bash
+cd "$(pwd)"
+node bin/install.js --all
+```
+
+This ensures:
+- **Windsurf** — skills already live in `.windsurf/skills/` (updated in place above)
+- **Claude Code** — `~/.claude/plugins/learnship/` rebuilt with updated skill content + rewritten `references/` paths
+- **OpenCode / Gemini CLI / Codex** — `learnship/skills/` context files updated
+
+---
+
+## Step 9: Clean up temp dirs
+
+```bash
+rm -rf "$TMPDIR"
+echo "Temp files cleaned up."
+```
+
+---
+
+## Step 10: Done
+
+Display summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► SKILL SYNC COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+agentic-learning:
+  SKILL.md       ✓ synced from FavioVazquez/agentic-learn
+  references/    ✓ synced ([N] files)
+
+impeccable:
+  18 sub-skills  ✓ synced from pbakaus/impeccable
+  SKILL.md       ✓ preserved (learnship dispatcher)
+
+All platforms updated (installer re-run):
+  Windsurf       ✓ skills updated in place
+  Claude Code    ✓ plugins/learnship/ rebuilt
+  Other platforms ✓ learnship/skills/ context files updated
+
+Backup saved at: .windsurf/skills/.upstream-backup-<timestamp>/
+Run: git diff .windsurf/skills/ to review all changes before committing.
+```
+
+Remind the user:
+> If upstream added new actions to `agentic-learning` (new entries in `SKILL.md`), update `.windsurf/skills/agentic-learning/SKILL.md`'s `description` frontmatter field to list them — it's what agents use to decide when to invoke the skill.
+>
+> If upstream added a new sub-skill to `impeccable`, also add it to `.windsurf/skills/impeccable/SKILL.md`'s Actions section and `references/` list.

package/learnship/workflows/transition.md

@@ -0,0 +1,165 @@
+---
+description: Hand off a project context to a new session or collaborator — writes a HANDOFF.md with full state snapshot
+---
+
+# Transition
+
+Create a comprehensive handoff document capturing the full project state. Useful when bringing in a collaborator, onboarding a new developer, or preparing a complete context snapshot for a fresh session after a long break.
+
+**Usage:** `transition`
+
+## Step 1: Read All Context
+
+Read the full project state:
+```bash
+cat .planning/PROJECT.md
+cat .planning/STATE.md
+cat .planning/ROADMAP.md
+cat .planning/REQUIREMENTS.md 2>/dev/null
+cat .planning/DECISIONS.md 2>/dev/null
+cat .planning/config.json
+```
+
+List all planning artifacts:
+```bash
+find .planning/ -name "*.md" | sort
+```
+
+Read the most recent SUMMARY.md files (last 3 phases):
+```bash
+ls -t .planning/phases/*/*-SUMMARY.md 2>/dev/null | head -6
+```
+
+Check git status:
+```bash
+git log --oneline -10
+git status --short
+```
+
+## Step 2: Assess Current Position
+
+Determine precisely where the project stands:
+- Which phases are complete (have SUMMARY.md)?
+- Which phase is in progress (has PLAN.md but no SUMMARY.md)?
+- Which phases are planned but not started?
+- Are there any open UAT issues?
+- Are there pending todos?
+
+```bash
+for phase_dir in .planning/phases/*/; do
+  plans=$(ls "${phase_dir}"*-PLAN.md 2>/dev/null | wc -l)
+  summaries=$(ls "${phase_dir}"*-SUMMARY.md 2>/dev/null | wc -l)
+  echo "$(basename $phase_dir): $plans plans, $summaries summaries"
+done
+```
+
+## Step 3: Write HANDOFF.md
+
+Write `HANDOFF.md` at the project root:
+
+```markdown
+---
+created: [date]
+milestone: [VERSION]
+phase: [current phase]
+status: [current status]
+---
+
+# Project Handoff — [Project Name]
+
+> Generated by learnship on [date].
+> Read this file first when resuming or onboarding.
+
+## What This Project Is
+
+[2-3 sentences from PROJECT.md — what it does, who it's for]
+
+## Current State
+
+**Milestone:** [VERSION] — [Milestone Name]
+**Phase:** [N] — [Phase Name]
+**Status:** [planning | executing | verifying | blocked]
+
+### What's Done
+[List of completed phases with one-sentence summary each]
+
+### What's In Progress
+[Current phase: what it's building, how far along]
+
+### What's Next
+[Next 2-3 phases from ROADMAP.md]
+
+## How to Resume
+
+```
+/ls             — see current position, next step, offer to run it
+/next           — auto-pilot: just picks up and runs the right workflow
+/resume-work    — full context restoration for long breaks
+```
+
+If starting fresh context:
+1. Read `.planning/STATE.md` first
+2. Read `.planning/ROADMAP.md` to see all phases
+3. Read the most recent SUMMARY.md for the last completed phase
+4. Run `/ls` to get current position and routing to next step
+
+## Key Decisions Made
+
+[Top 5-8 decisions from DECISIONS.md or CONTEXT.md files that constrain future work]
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| [topic] | [choice] | [why] |
+
+## Architecture Overview
+
+[2-4 sentences describing the system structure — from STACK.md/ARCHITECTURE.md if available]
+
+**Key files:**
+- [file]: [role]
+- [file]: [role]
+
+## Tech Stack
+
+[From AGENTS.md or research files]
+
+## Open Items
+
+### Pending Todos
+[From .planning/todos/pending/ — list titles]
+
+### Open UAT Issues
+[From any *-UAT.md files with status: open]
+
+### Known Risks
+[From CONCERNS.md or RESEARCH.md files]
+
+## Git State
+
+**Last commit:** [hash and message]
+**Uncommitted changes:** [none | list of files]
+**Tags:** [version tags]
+
+---
+*Generated by: learnship — transition workflow*
+```
+
+## Step 4: Commit
+
+```bash
+git add HANDOFF.md
+git commit -m "docs: create project handoff snapshot"
+```
+
+## Step 5: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► HANDOFF READY ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+HANDOFF.md created at project root.
+
+Share with collaborator: HANDOFF.md + the git repo
+Resume fresh session: /resume-work
+```

package/learnship/workflows/update.md

@@ -0,0 +1,166 @@
+---
+description: Update the learnship platform itself to the latest version
+---
+
+# Update
+
+Update the platform workflows and skills to the latest version. Backs up any locally modified files before overwriting so you don't lose customizations.
+
+**Usage:** `update`
+
+## Step 1: Detect Install Location
+
+Find where the platform is installed:
+
+```bash
+# Check local install
+test -d "$(pwd)/.windsurf/workflows" && LOCAL_WF="$(pwd)/.windsurf" || LOCAL_WF=""
+
+# Check global install
+test -d "$HOME/.codeium/windsurf/workflows" && GLOBAL_WF="$HOME/.codeium/windsurf" || GLOBAL_WF=""
+```
+
+If both exist, ask: "Update local install, global install, or both?"
+
+If neither found: "Could not detect install location. Run `bash install.sh` to reinstall."
+Stop.
+
+## Step 2: Find Platform Source
+
+Locate the platform source repository:
+
+```bash
+# Common locations
+for loc in \
+  "$HOME/favio/learnship" \
+  "$HOME/learnship" \
+  "$(find $HOME -name "install.sh" -path "*/learnship/*" 2>/dev/null | head -1 | xargs dirname 2>/dev/null)"; do
+  test -d "$loc/.windsurf/workflows" && SOURCE_DIR="$loc" && break
+done
+```
+
+If source not found:
+```
+Platform source directory not found.
+
+To update, either:
+1. Clone the latest version and run: bash install.sh
+2. Specify the source path manually
+```
+Stop.
+
+## Step 3: Check for Updates
+
+Compare installed workflow files to source:
+
+```bash
+# Check modification times and content
+for wf in "$SOURCE_DIR/.windsurf/workflows/"*.md; do
+  name=$(basename "$wf")
+  target="$INSTALL_DIR/workflows/$name"
+  if [ -f "$target" ] && ! diff -q "$wf" "$target" > /dev/null 2>&1; then
+    echo "CHANGED: $name"
+  elif [ ! -f "$target" ]; then
+    echo "NEW: $name"
+  fi
+done
+```
+
+Display:
+```
+Update check:
+
+New workflows available ([N]):
+- [workflow name]: [description from frontmatter]
+
+Updated workflows ([M]):
+- [workflow name]: content changed
+
+Your local modifications ([K]):
+- [workflow name]: locally modified (will be backed up)
+
+No changes: [N] workflows already up to date
+```
+
+If nothing to update:
+```
+Platform is up to date. All [N] workflows match the source.
+```
+Stop.
+
+## Step 4: Back Up Local Modifications
+
+For any workflow file that exists in install dir AND differs from source AND differs from the current source (meaning you modified it):
+
+```bash
+mkdir -p "$INSTALL_DIR/local-patches"
+```
+
+For each locally modified file:
+```bash
+cp "$INSTALL_DIR/workflows/$name" "$INSTALL_DIR/local-patches/$name"
+```
+
+Write a manifest:
+```bash
+cat > "$INSTALL_DIR/local-patches/PATCHES.md" << EOF
+# Local Patches Backup
+Created: $(date)
+
+Files backed up before update:
+$(for f in "$INSTALL_DIR/local-patches/"*.md; do echo "- $(basename $f)"; done)
+
+To restore: run reapply-patches
+EOF
+```
+
+Display:
+```
+[K] locally modified file(s) backed up to .windsurf/local-patches/
+Run reapply-patches after update to merge your changes back.
+```
+
+## Step 5: Confirm Update
+
+```
+Ready to update:
+- [N] new workflows will be added
+- [M] existing workflows will be updated
+- [K] local modifications backed up
+
+Proceed? (yes/no)
+```
+
+Wait for confirmation.
+
+## Step 6: Apply Update
+
+Copy updated workflows:
+```bash
+for wf in "$SOURCE_DIR/.windsurf/workflows/"*.md; do
+  cp "$wf" "$INSTALL_DIR/workflows/"
+done
+```
+
+Update skills:
+```bash
+cp -r "$SOURCE_DIR/.windsurf/skills/agentic-learning/." "$INSTALL_DIR/skills/agentic-learning/"
+cp -r "$SOURCE_DIR/.windsurf/skills/frontend-design/." "$INSTALL_DIR/skills/frontend-design/"
+```
+
+## Step 7: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► UPDATE COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Added: [N] new workflows
+Updated: [M] workflows
+Skills: updated
+
+[If local patches were backed up:]
+⚠️  [K] local modification(s) backed up. Run reapply-patches to restore.
+
+Platform is now up to date.
+```