learnship 1.9.0

package/install.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# learnship — Installer
+# Usage:
+#   bash install.sh                    # interactive
+#   bash install.sh --local            # project install (non-interactive)
+#   bash install.sh --global           # global install (non-interactive)
+#   bash install.sh --uninstall --local
+#   bash install.sh --uninstall --global
+
+set -e
+
+REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLATFORM_NAME="learnship"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+# ─── Helpers ─────────────────────────────────────────────────────────────────
+
+print_header() {
+  echo ""
+  echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  echo -e "${BOLD}  ${PLATFORM_NAME}${RESET}"
+  echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+  echo ""
+}
+
+print_success() { echo -e "${GREEN}✓${RESET} $1"; }
+print_error()   { echo -e "${RED}✗${RESET} $1" >&2; }
+print_info()    { echo -e "${BLUE}→${RESET} $1"; }
+print_warn()    { echo -e "${YELLOW}!${RESET} $1"; }
+
+# ─── Argument Parsing ────────────────────────────────────────────────────────
+
+SCOPE=""
+UNINSTALL=false
+
+for arg in "$@"; do
+  case "$arg" in
+    --local)     SCOPE="local" ;;
+    --global)    SCOPE="global" ;;
+    --uninstall) UNINSTALL=true ;;
+    --help|-h)
+      echo "Usage: bash install.sh [--local|--global] [--uninstall]"
+      echo ""
+      echo "  --local      Install to current project's .windsurf/ directory"
+      echo "  --global     Install to ~/.codeium/windsurf/ (available in all projects)"
+      echo "  --uninstall  Remove the installation"
+      echo ""
+      echo "Run without flags for interactive mode."
+      exit 0
+      ;;
+    *)
+      print_error "Unknown argument: $arg"
+      echo "Run 'bash install.sh --help' for usage."
+      exit 1
+      ;;
+  esac
+done
+
+# ─── Determine Target Directory ──────────────────────────────────────────────
+
+get_target_dir() {
+  local scope="$1"
+  if [[ "$scope" == "global" ]]; then
+    echo "$HOME/.codeium/windsurf"
+  else
+    # When run via npx, pwd() is the npx cache — use LEARNSHIP_INSTALL_CWD
+    # (set by bin/learnship.js from INIT_CWD) to get the user's actual project dir
+    local project_dir="${LEARNSHIP_INSTALL_CWD:-$(pwd)}"
+    echo "${project_dir}/.windsurf"
+  fi
+}
+
+# ─── Interactive Prompt ──────────────────────────────────────────────────────
+
+if [[ -z "$SCOPE" ]]; then
+  print_header
+
+  echo -e "${BOLD}Where would you like to install?${RESET}"
+  echo ""
+  echo "  [1] Project  — installs to ./.windsurf/ (current project only)"
+  echo "  [2] Global   — installs to ~/.codeium/windsurf/ (all Windsurf projects)"
+  echo ""
+  read -p "Choice [1/2]: " choice
+
+  case "$choice" in
+    1|"") SCOPE="local" ;;
+    2)    SCOPE="global" ;;
+    *)
+      print_error "Invalid choice. Run again and enter 1 or 2."
+      exit 1
+      ;;
+  esac
+fi
+
+TARGET_DIR="$(get_target_dir "$SCOPE")"
+
+# ─── Uninstall ───────────────────────────────────────────────────────────────
+
+if [[ "$UNINSTALL" == true ]]; then
+  print_header
+  echo -e "Uninstalling from: ${BOLD}${TARGET_DIR}${RESET}"
+  echo ""
+
+  REMOVED=0
+
+  if [[ -d "${TARGET_DIR}/workflows" ]]; then
+    # Only remove our workflows (non-destructive: checks for our files)
+    for wf in new-project discuss-phase plan-phase execute-phase verify-work quick progress ls next pause-work resume-work complete-milestone; do
+      if [[ -f "${TARGET_DIR}/workflows/${wf}.md" ]]; then
+        rm "${TARGET_DIR}/workflows/${wf}.md"
+        print_info "Removed workflows/${wf}.md"
+        ((REMOVED++)) || true
+      fi
+    done
+  fi
+
+  if [[ -d "${TARGET_DIR}/skills/agentic-learning" ]]; then
+    rm -rf "${TARGET_DIR}/skills/agentic-learning"
+    print_info "Removed skills/agentic-learning/"
+    ((REMOVED++)) || true
+  fi
+
+  if [[ -d "${TARGET_DIR}/skills/impeccable" ]]; then
+    rm -rf "${TARGET_DIR}/skills/impeccable"
+    print_info "Removed skills/impeccable/"
+    ((REMOVED++)) || true
+  fi
+
+  if [[ -d "${TARGET_DIR}/skills/frontend-design" ]]; then
+    rm -rf "${TARGET_DIR}/skills/frontend-design"
+    print_info "Removed skills/frontend-design/ (legacy)"
+    ((REMOVED++)) || true
+  fi
+
+  if [[ $REMOVED -eq 0 ]]; then
+    print_warn "Nothing found to remove at ${TARGET_DIR}"
+  else
+    echo ""
+    print_success "Uninstall complete. Removed ${REMOVED} item(s)."
+  fi
+  exit 0
+fi
+
+# ─── Install ─────────────────────────────────────────────────────────────────
+
+print_header
+echo -e "Installing to: ${BOLD}${TARGET_DIR}${RESET}"
+if [[ "$SCOPE" == "global" ]]; then
+  print_info "Global install — workflows and skills will be available in all Windsurf projects"
+else
+  print_info "Project install — workflows and skills available in this project only"
+fi
+echo ""
+
+# Validate source directory has the required files
+if [[ ! -d "${REPO_DIR}/.windsurf/workflows" ]]; then
+  print_error "Source workflows not found at ${REPO_DIR}/.windsurf/workflows"
+  print_error "Make sure you are running install.sh from the agentic-development repo root."
+  exit 1
+fi
+
+# Create target directories
+mkdir -p "${TARGET_DIR}/workflows"
+mkdir -p "${TARGET_DIR}/skills"
+
+# ── Install Workflows ──────────────────────────────────────────────────────
+
+echo -e "${BOLD}Installing workflows...${RESET}"
+
+WORKFLOW_COUNT=0
+for wf_file in "${REPO_DIR}/.windsurf/workflows/"*.md; do
+  wf_name="$(basename "$wf_file")"
+  dest="${TARGET_DIR}/workflows/${wf_name}"
+  if [[ "$(realpath "$wf_file")" != "$(realpath "$dest" 2>/dev/null)" ]]; then
+    cp "$wf_file" "$dest"
+    print_success "workflows/${wf_name}"
+    ((WORKFLOW_COUNT++)) || true
+  fi
+done
+
+echo ""
+
+# ── Install Skills ─────────────────────────────────────────────────────────
+
+echo -e "${BOLD}Installing skills...${RESET}"
+
+# agentic-learning
+if [[ -d "${REPO_DIR}/.windsurf/skills/agentic-learning" ]]; then
+  mkdir -p "${TARGET_DIR}/skills/agentic-learning"
+  if [[ "$(realpath "${REPO_DIR}/.windsurf/skills/agentic-learning")" != "$(realpath "${TARGET_DIR}/skills/agentic-learning" 2>/dev/null)" ]]; then
+    cp -r "${REPO_DIR}/.windsurf/skills/agentic-learning/"* "${TARGET_DIR}/skills/agentic-learning/"
+  fi
+  print_success "skills/agentic-learning/ (learning partner)"
+else
+  print_warn "skills/agentic-learning/ not found in source — skipping"
+fi
+
+# impeccable (full design skill suite)
+if [[ -d "${REPO_DIR}/.windsurf/skills/impeccable" ]]; then
+  if [[ "$(realpath "${REPO_DIR}/.windsurf/skills/impeccable")" != "$(realpath "${TARGET_DIR}/skills/impeccable" 2>/dev/null)" ]]; then
+    cp -r "${REPO_DIR}/.windsurf/skills/impeccable" "${TARGET_DIR}/skills/impeccable"
+  fi
+  IMPECCABLE_COUNT=$(find "${REPO_DIR}/.windsurf/skills/impeccable" -name "SKILL.md" | wc -l | tr -d ' ')
+  print_success "skills/impeccable/ (${IMPECCABLE_COUNT} design skills — audit, critique, polish, colorize + more)"
+else
+  print_warn "skills/impeccable/ not found in source — skipping"
+fi
+
+echo ""
+
+# ── Done ──────────────────────────────────────────────────────────────────
+
+echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+echo -e "${GREEN}${BOLD}  Installation complete!${RESET}"
+echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+echo ""
+echo -e "  ${BOLD}Installed:${RESET} ${WORKFLOW_COUNT} workflows + 2 skill suites (agentic-learning, impeccable)"
+echo -e "  ${BOLD}Location:${RESET}  ${TARGET_DIR}"
+echo ""
+
+if [[ "$SCOPE" == "global" ]]; then
+  echo -e "  ${BOLD}Next steps:${RESET}"
+  echo -e "  • Restart Windsurf (or reload the window) to activate"
+  echo -e "  • Open any project and type ${BOLD}/new-project${RESET} to start"
+else
+  echo -e "  ${BOLD}Next steps:${RESET}"
+  echo -e "  • Workflows are immediately available in this project"
+  echo -e "  • Type ${BOLD}/new-project${RESET} in Cascade to start"
+fi
+
+echo ""
+echo -e "  ${BOLD}Quick reference:${RESET}"
+echo -e "  /ls                   Where am I? What's next? (start every session here)"
+echo -e "  /next                 Auto-pilot — runs the right workflow automatically"
+echo -e "  /new-project          Initialize a new project"
+echo -e "  /discuss-phase [N]    Capture implementation decisions"
+echo -e "  /plan-phase [N]       Create executable plans"
+echo -e "  /execute-phase [N]    Run all plans in a phase"
+echo -e "  /verify-work [N]      Manual acceptance testing"
+echo -e "  /quick [description]  Ad-hoc task with full guarantees"
+echo ""
+echo -e "  ${BOLD}Learning mode:${RESET} Set ${BOLD}learning_mode${RESET} in .planning/config.json"
+echo -e "  ${BOLD}  auto${RESET}   (default) Offered at workflow checkpoints"
+echo -e "  ${BOLD}  manual${RESET} Only when you invoke @agentic-learning"
+echo ""
+echo -e "  See ${BOLD}README.md${RESET} or ${BOLD}https://github.com/FavioVazquez/learnship${RESET} for full documentation."
+echo ""

package/learnship/references/design-commands.md

@@ -0,0 +1,119 @@
+# Design Steering Commands
+
+Steering commands for the frontend-design skill. Invoke these during any UI work to get targeted design guidance, critique, and improvements.
+
+---
+
+## Full Command Reference
+
+| Command | What it triggers |
+|---------|-----------------|
+| `/audit` | Comprehensive UI quality audit against the full design checklist |
+| `/critique` | Candid design critique — what's working, what isn't, specific improvements |
+| `/polish` | Refine and elevate an existing interface — details, spacing, hierarchy |
+| `/motion` | Add purposeful motion: entrances, transitions, state changes |
+| `/tokens` | Design token system: color, spacing, typography scale, border radius |
+| `/brand` | Brand coherence check across all surfaces |
+| `/typography` | Typography system: scale, pairing, hierarchy, loading |
+| `/color` | Color palette review: OKLCH, contrast ratios, dark mode, tinting |
+| `/layout` | Layout and spatial rhythm: grid, breathing room, asymmetry |
+| `/responsive` | Mobile-first: container queries, fluid design, breakpoints |
+| `/interaction` | Interaction design: forms, focus states, loading patterns, optimistic UI |
+| `/accessibility` | Accessibility: focus management, contrast, screen reader support |
+| `/empty-states` | Empty state design that teaches the interface |
+| `/loading` | Loading patterns: skeletons, spinners, progressive disclosure |
+| `/forms` | Form UX: labels, validation, error states, field grouping |
+| `/copy` | UX writing: labels, errors, empty states, CTAs |
+| `/density` | Information density: when to compress, when to breathe |
+
+---
+
+## When to Use Each
+
+### Starting a new component or page
+→ `/audit` first — understand what quality problems to avoid before writing a line
+
+### After first implementation pass
+→ `/critique` — honest feedback before spending time on polish
+→ `/layout` — is the spatial rhythm right?
+
+### Typography feels off
+→ `/typography` — systematic review of scale, pairing, hierarchy
+→ `/copy` — are the words doing their job?
+
+### Colors feel wrong or generic
+→ `/color` — OKLCH-based palette review, tinting strategy, contrast
+→ `/tokens` — establish a proper design token system
+
+### Interface feels stiff or lifeless
+→ `/motion` — purposeful animation for state changes and entrances
+→ `/interaction` — does every interactive surface feel responsive?
+
+### Shipping to production
+→ `/accessibility` — focus, contrast ratios, screen reader support
+→ `/responsive` — does it adapt properly at all sizes?
+→ `/polish` — final refinement pass
+
+### Something feels "AI-generated"
+→ `/critique` — the AI slop test: would someone immediately recognize this as AI output?
+
+---
+
+## The Anti-Patterns to Watch For
+
+The design skill actively guards against these common AI aesthetics:
+
+**Colors:**
+- Cyan-on-dark with purple-to-blue gradients
+- Neon accents on dark backgrounds
+- Pure black (#000) or pure white (#fff)
+- Gray text on colored backgrounds
+
+**Layout:**
+- Everything in cards — not everything needs a container
+- Nested cards inside cards
+- Identical card grids (same-sized cards with icon + heading + text, repeated)
+- Centering everything
+- The "hero metric" template: big number, small label, gradient accent
+
+**Typography:**
+- Overused fonts: Inter, Roboto, Arial, Open Sans, system defaults
+- Monospace as lazy "developer vibes"
+- Large rounded icons above every heading
+
+**Motion:**
+- Bounce or elastic easing
+- Animating layout properties (width, height, padding, margin)
+- Scattered micro-interactions everywhere
+
+**Details:**
+- Glassmorphism used decoratively (not purposefully)
+- Rounded elements with thick one-sided colored borders
+- Generic rounded rectangles with drop shadows
+- Gradient text for "impact" on metrics or headings
+
+---
+
+## The AI Slop Test
+
+Before shipping any interface, ask:
+
+> If you showed this to someone and said "AI made this" — would they believe you immediately?
+
+If yes: use `/critique` to find what makes it look templated, then `/polish` to address it.
+
+A well-designed interface makes someone ask **"how was this made?"** not "which AI made this?"
+
+---
+
+## Reference Files
+
+The design skill includes 7 domain-specific reference files:
+
+- `reference/typography.md` — scales, pairing, fluid sizing with clamp()
+- `reference/color-and-contrast.md` — OKLCH, palettes, dark mode strategy
+- `reference/spatial-design.md` — grids, rhythm, container queries
+- `reference/motion-design.md` — timing, easing curves, reduced motion
+- `reference/interaction-design.md` — forms, focus, loading patterns
+- `reference/responsive-design.md` — mobile-first, fluid design, breakpoints
+- `reference/ux-writing.md` — labels, errors, empty states, microcopy

package/learnship/references/git-integration.md

@@ -0,0 +1,249 @@
+<overview>
+Git integration for learnship.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what shipped, not a diary of planning activity.
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| BRIEF + ROADMAP created | YES     | Project initialization                           |
+| PLAN.md created         | NO      | Intermediate - commit with plan completion       |
+| RESEARCH.md created     | NO      | Intermediate                                     |
+| DISCOVERY.md created    | NO      | Intermediate                                     |
+| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
+| **Plan completed**      | YES     | Metadata commit (SUMMARY + STATE + ROADMAP)     |
+| Handoff created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: Run `git init` silently. learnship projects always get their own repo.
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## Project Initialization (brief + roadmap together)
+
+```
+docs: initialize [project-name] ([N] phases)
+
+[One-liner from PROJECT.md]
+
+Phases:
+1. [phase-name]: [goal]
+2. [phase-name]: [goal]
+3. [phase-name]: [goal]
+```
+
+What to commit:
+
+```bash
+git add .planning/ && git commit -m "docs: initialize [project-name] ([N] phases)"
+```
+
+</format>
+
+<format name="task-completion">
+## Task Completion (During Plan Execution)
+
+Each task gets its own commit immediately after completion.
+
+```
+{type}({phase}-{plan}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**Commit types:**
+- `feat` - New feature/functionality
+- `fix` - Bug fix
+- `test` - Test-only (TDD RED phase)
+- `refactor` - Code cleanup (TDD REFACTOR phase)
+- `perf` - Performance improvement
+- `chore` - Dependencies, config, tooling
+
+**Examples:**
+
+```bash
+# Standard task
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08-02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# TDD task - RED phase
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07-02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+
+# TDD task - GREEN phase
+git add src/utils/jwt.ts
+git commit -m "feat(07-02): implement JWT generation
+
+- Uses jose library for signing
+- Includes user ID and expiry claims
+- Signs with HS256 algorithm
+"
+```
+
+</format>
+
+<format name="plan-completion">
+## Plan Completion (After All Tasks Done)
+
+After all tasks committed, one final metadata commit captures plan completion.
+
+```
+docs({phase}-{plan}): complete [plan-name] plan
+
+Tasks completed: [N]/[N]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+SUMMARY: .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md
+```
+
+What to commit:
+
+```bash
+git add .planning/phases/XX-name/{phase}-{plan}-PLAN.md .planning/phases/XX-name/{phase}-{plan}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md
+git commit -m "docs({phase}-{plan}): complete [plan-name] plan"
+```
+
+**Note:** Code files NOT included - already committed per-task.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip: [phase-name] paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+
+```bash
+git add .planning/ && git commit -m "wip: [phase-name] paused at task [X]/[Y]"
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**Old approach (per-plan commits):**
+```
+a7f2d1 feat(checkout): Stripe payments with webhook verification
+3e9c4b feat(products): catalog with search, filters, and pagination
+8a1b2c feat(auth): JWT with refresh rotation using jose
+5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
+2f4a8d docs: initialize ecommerce-app (5 phases)
+```
+
+**New approach (per-task commits):**
+```
+# Phase 04 - Checkout
+1a2b3c docs(04-01): complete checkout flow plan
+4d5e6f feat(04-01): add webhook signature verification
+7g8h9i feat(04-01): implement payment session creation
+0j1k2l feat(04-01): create checkout page component
+
+# Phase 03 - Products
+3m4n5o docs(03-02): complete product listing plan
+6p7q8r feat(03-02): add pagination controls
+9s0t1u feat(03-02): implement search and filters
+2v3w4x feat(03-01): create product catalog schema
+
+# Phase 02 - Auth
+5y6z7a docs(02-02): complete token refresh plan
+8b9c0d feat(02-02): implement refresh token rotation
+1e2f3g test(02-02): add failing test for token refresh
+4h5i6j docs(02-01): complete JWT setup plan
+7k8l9m feat(02-01): add JWT generation and validation
+0n1o2p chore(02-01): install jose library
+
+# Phase 01 - Foundation
+3q4r5s docs(01-01): complete scaffold plan
+6t7u8v feat(01-01): configure Tailwind and globals
+9w0x1y feat(01-01): set up Prisma with database
+2z3a4b feat(01-01): create Next.js 15 project
+
+# Initialization
+5c6d7e docs: initialize ecommerce-app (5 phases)
+```
+
+Each plan produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- PLAN.md creation (commit with plan completion)
+- RESEARCH.md (intermediate)
+- DISCOVERY.md (intermediate)
+- Minor planning tweaks
+- "Fixed typo in roadmap"
+
+**Do commit (outcomes):**
+- Each task completion (feat/fix/test/refactor)
+- Plan completion metadata (docs)
+- Project initialization (docs)
+
+**Key principle:** Commit working code and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{phase}-{plan}"` shows all work for a plan
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing SUMMARY.md = more context for actual work
+
+**Failure recovery:**
+- Task 1 committed ✅, Task 2 failed ❌
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Debugging:**
+- `git bisect` finds exact failing task, not just failing plan
+- `git blame` traces line to specific task context
+- Each commit is independently revertable
+
+**Observability:**
+- Solo developer + Claude workflow benefits from granular attribution
+- Atomic commits are git best practice
+- "Commit noise" irrelevant when consumer is Claude, not humans
+
+</commit_strategy_rationale>