learnship 1.9.0

package/learnship/workflows/validate-phase.md

@@ -0,0 +1,174 @@
+---
+description: Retroactive test coverage audit for a completed phase — fill validation gaps without modifying implementation
+---
+
+# Validate Phase
+
+Retroactively audit and fill test coverage gaps for a completed phase. Useful after hotfixes, for phases executed before test infrastructure was set up, or when `audit-milestone` surfaces validation gaps.
+
+**Usage:** `validate-phase [N]`
+
+**Rule:** Never modifies implementation files — only writes test files and updates VALIDATION.md.
+
+## Step 1: Check Config
+
+Read `.planning/config.json`:
+```bash
+cat .planning/config.json | grep "nyquist_validation"
+```
+
+If `nyquist_validation: false`: stop — "Validation is disabled. Enable it in `/settings` to use this workflow."
+
+## Step 2: Validate Phase
+
+```bash
+test -f .planning/ROADMAP.md && grep -E "Phase [N]:" .planning/ROADMAP.md
+```
+
+Determine the phase directory:
+```bash
+ls .planning/phases/ | grep -E "^0*[N]-"
+PHASE_DIR=".planning/phases/[matched dir]"
+```
+
+## Step 3: Detect State
+
+Check what exists:
+```bash
+ls "$PHASE_DIR"/*.md 2>/dev/null
+```
+
+- **State A** — VALIDATION.md exists: run audit on existing file, fill gaps
+- **State B** — SUMMARY.md exists, no VALIDATION.md: build validation from execution artifacts
+- **State C** — no SUMMARY.md: phase not executed yet — stop: "Run `execute-phase [N]` first."
+
+## Step 4: Read Phase Artifacts
+
+Read all PLAN.md and SUMMARY.md files for phase `[N]`:
+```bash
+cat "$PHASE_DIR"/*-PLAN.md
+cat "$PHASE_DIR"/*-SUMMARY.md
+```
+
+Extract:
+- Task names and `<verify>` commands
+- Requirement IDs covered by each task
+- Key files created or modified
+
+## Step 5: Detect Test Infrastructure
+
+```bash
+find . \( -name "jest.config.*" -o -name "vitest.config.*" -o -name "pytest.ini" -o -name "pyproject.toml" \) -not -path "*/node_modules/*" 2>/dev/null
+
+find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" \) -not -path "*/node_modules/*" 2>/dev/null | head -20
+```
+
+Identify: test framework, how to run tests, existing test file patterns.
+
+## Step 6: Map Requirements to Tests
+
+For each requirement ID assigned to this phase:
+
+1. Look for existing tests that cover this behavior (by filename, describe block, test name)
+2. Classify:
+   - **COVERED** — test exists, targets the behavior, runs green
+   - **PARTIAL** — test exists but incomplete or failing
+   - **MISSING** — no test found
+
+If no gaps (all COVERED): proceed directly to step 8 with `nyquist_compliant: true`.
+
+## Step 7: Present Gap Plan and Fill
+
+Show gap table:
+```
+Phase [N] Validation Gaps
+
+| Requirement | Status | Suggested test |
+|-------------|--------|----------------|
+| REQ-AUTH-01 | MISSING | src/__tests__/auth.test.ts |
+| REQ-DASH-02 | PARTIAL | src/__tests__/dashboard.test.ts |
+
+Options:
+1. Fill all gaps — I'll write the missing tests
+2. Mark as manual-only — skip automation, verify manually
+3. Cancel
+```
+
+Wait for choice.
+
+**If "Fill all gaps":** Write the missing test files. Rules:
+- Never touch implementation files
+- Match the existing test framework and style
+- Write tests that actually run (import real modules, not mocks of the implementation)
+- If a test reveals an implementation bug, log it as an escalation — don't fix the implementation
+
+Run tests to verify they pass:
+```bash
+[test command for framework] [test file]
+```
+
+Up to 3 debug attempts if tests fail. If still failing after 3, move to manual-only and note why.
+
+## Step 8: Write/Update VALIDATION.md
+
+**State B (create new):**
+
+Write `$PHASE_DIR/[padded_phase]-VALIDATION.md`:
+
+```markdown
+---
+nyquist_compliant: true | false
+wave_0_complete: true | false
+phase: [N]
+validated: [date]
+---
+
+# Phase [N] Validation
+
+## Test Infrastructure
+| Tool | Version | Run command |
+|------|---------|-------------|
+| [framework] | [version] | [command] |
+
+## Per-Requirement Coverage
+
+| Requirement | Task | Test file | Status |
+|-------------|------|-----------|--------|
+| REQ-XX-01 | [task name] | [test file path] | ✓ automated |
+
+## Manual-Only Items
+[Items that require a running app to verify]
+
+## Audit Trail
+Validated: [date] — [N] covered, [M] manual-only
+```
+
+**State A (update existing):**
+
+Update the Per-Requirement Coverage table, add resolved gaps, move escalated items to Manual-Only. Append audit trail entry.
+
+## Step 9: Commit
+
+```bash
+git add [test files]
+git commit -m "test([padded_phase]): add validation tests"
+
+git add "$PHASE_DIR/[padded_phase]-VALIDATION.md"
+git commit -m "docs([padded_phase]): update validation strategy"
+```
+
+## Step 10: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PHASE [N] VALIDATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[N] requirements automated ✓
+[M] requirements manual-only
+[K] escalated (implementation bugs found — see VALIDATION.md)
+
+Status: COMPLIANT | PARTIAL
+
+▶ Next: audit-milestone
+```

package/learnship/workflows/verify-work.md

@@ -0,0 +1,264 @@
+---
+description: Manual user acceptance testing — walk through what was built, log issues, create fix plans
+---
+
+# Verify Work
+
+Validate built features through conversational testing. Walk through each deliverable one at a time. You present what SHOULD happen — user confirms or describes what's different.
+
+**Usage:** `verify-work [N]`
+
+**Philosophy:** Show expected, ask if reality matches. No pass/fail buttons. No severity questions. Just: "Here's what should happen. Does it?"
+
+## Step 1: Initialize
+
+Check for existing UAT sessions:
+```bash
+find .planning/phases -name "*-UAT.md" -type f 2>/dev/null
+```
+
+**If active sessions exist and no phase number given:**
+
+Read each file's frontmatter (status, phase) and current test.
+
+Display:
+```
+## Active UAT Sessions
+
+| # | Phase | Status | Current Test | Progress |
+|---|-------|--------|--------------|----------|
+| 1 | [phase] | testing | [test name] | [N/M] |
+
+Reply with a number to resume, or provide a phase number to start new.
+```
+
+Wait for response. If number → resume that session. If phase number → start new session.
+
+**If no sessions and no phase given:**
+```
+No active UAT sessions.
+
+Provide a phase number to start testing (e.g., verify-work 4)
+```
+
+## Step 2: Find Deliverables
+
+Read all SUMMARY.md files for the phase:
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-SUMMARY.md 2>/dev/null
+```
+
+Extract testable deliverables from each SUMMARY.md — focus on **user-observable outcomes**, not implementation details:
+- What features/functionality was added?
+- What UI changes are visible?
+- What workflows can a user now do?
+
+Skip internal changes (refactors, type changes, test additions).
+
+**Cold-start smoke test:** If any SUMMARY.md mentions server entry points, database files, migrations, or docker files — prepend a "Cold Start Smoke Test" as the first test:
+```
+Expected: Kill any running server. Clear ephemeral state. Start from scratch.
+Server boots without errors, any seed/migration completes, primary query returns live data.
+```
+
+## Step 3: Create UAT File
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-UAT.md`:
+
+```markdown
+---
+status: testing
+phase: [padded_phase]-[phase_slug]
+source: [list of SUMMARY.md files]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Test
+number: 1
+name: [first test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior]
+result: pending
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: pending
+
+...
+
+## Summary
+
+total: [N]
+passed: 0
+issues: 0
+pending: [N]
+skipped: 0
+
+## Gaps
+
+[none yet]
+```
+
+## Step 4: Present Tests One at a Time
+
+For each test, display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  UAT: Test [N] of [total]                                    ║
+╚══════════════════════════════════════════════════════════════╝
+
+**[Test Name]**
+
+[Expected behavior — specific, observable, copy-pasteable commands or clear UI actions]
+
+──────────────────────────────────────────────────────────────
+→ Type "pass" or describe what's wrong
+──────────────────────────────────────────────────────────────
+```
+
+Wait for plain text response (no multiple-choice).
+
+## Step 5: Process Each Response
+
+**If response indicates pass:** "yes", "y", "ok", "pass", "next", "approved", empty
+→ Mark test: `result: pass`
+
+**If response indicates skip:** "skip", "can't test", "n/a"
+→ Mark test: `result: skipped`, capture reason
+
+**If response is anything else:**
+→ Treat as issue description. Infer severity from language:
+- "crash", "error", "exception", "fails" → `blocker`
+- "doesn't work", "wrong", "missing", "can't" → `major`
+- "slow", "weird", "off", "minor" → `minor`
+- "color", "font", "spacing", "alignment" → `cosmetic`
+- Default: `major`
+
+Mark test:
+```
+result: issue
+reported: "[verbatim user response]"
+severity: [inferred]
+```
+
+Append to Gaps section:
+```yaml
+- truth: "[expected behavior from test]"
+  status: failed
+  reason: "User reported: [verbatim response]"
+  severity: [inferred]
+  test: [N]
+```
+
+After each response: update Summary counts, update `updated` timestamp, write to UAT file, move to next test.
+
+## Step 6: Complete Session
+
+After all tests, update frontmatter: `status: complete`.
+
+Commit:
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-UAT.md"
+git commit -m "test([padded_phase]): complete UAT - [N] passed, [M] issues"
+```
+
+Display summary:
+```
+## UAT Complete: Phase [X]
+
+| Result  | Count |
+|---------|-------|
+| Passed  | [N]   |
+| Issues  | [N]   |
+| Skipped | [N]   |
+```
+
+**If no issues:** 
+```
+All tests passed. ✓
+
+▶ Next: discuss-phase [X+1]
+```
+
+**If issues found:** Continue to Step 7.
+
+## Step 7: Diagnose Issues
+
+```
+[N] issues found. Diagnosing root causes...
+```
+
+For each issue in the Gaps section, investigate using `@./agents/debugger.md` as your debug persona:
+- Read the relevant source files
+- Trace the issue to its root cause
+- Do not fix yet — just diagnose
+
+Update each gap in UAT.md with the root cause:
+```yaml
+- truth: "[expected]"
+  status: failed
+  reason: "User reported: [response]"
+  severity: [severity]
+  root_cause: "[What's actually broken and why]"
+  affected_files: ["[file1]", "[file2]"]
+```
+
+## Step 8: Create Fix Plans
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PLANNING FIXES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/planner.md` as your planning persona, read the UAT.md file with diagnosed gaps. Create fix plans in the phase directory with `gap_closure: true` in frontmatter.
+
+Verify fix plans (max 3 iterations with `@./agents/verifier.md`) — same loop as `plan-phase`.
+
+Present when ready:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► FIXES READY ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase [X]** — [N] gap(s) diagnosed, [M] fix plan(s) created
+
+| Gap | Root Cause | Fix Plan |
+|-----|------------|----------|
+| [issue] | [root cause] | [plan file] |
+
+▶ Next: execute-phase [X] (will run gap closure plans)
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto` and UAT passed with no issues:**
+
+> 💡 **Learning moment:** Tests passed — lock in what was learned before moving on:
+>
+> `@agentic-learning space` — Identifies concepts from this phase and schedules them for spaced revisit. Writes to `docs/revisit.md`. The next phase starts with less decay.
+>
+> `@agentic-learning quiz [phase topic]` — Quick active recall while the implementation is still fresh. Better now than two phases later.
+
+**If `auto` and issues were found and fixed:**
+
+> 💡 **Learning moment:** Bugs found during UAT are high-signal learning. Don’t just fix and move on:
+>
+> `@agentic-learning learn [bug domain]` — Active retrieval on the concept that caused the issue. Turns a frustrating bug into a lasting pattern.
+>
+> `@agentic-learning space` — Schedule the key concepts from this debugging session for spaced review.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning space` · `@agentic-learning quiz [topic]` to consolidate this phase."*

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "learnship",
+  "version": "1.9.0",
+  "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: spec-driven workflows, integrated learning, and production-grade design.",
+  "keywords": [
+    "agentic",
+    "development",
+    "windsurf",
+    "claude-code",
+    "cursor",
+    "opencode",
+    "gemini-cli",
+    "codex",
+    "workflow",
+    "ai",
+    "learning",
+    "planning",
+    "cascade",
+    "agentic-ai",
+    "ai-agent",
+    "ai-workflow"
+  ],
+  "files": [
+    "bin",
+    "commands",
+    "learnship",
+    "agents",
+    "references",
+    "templates",
+    "install.sh",
+    "skills",
+    "hooks",
+    ".claude-plugin",
+    ".cursor-plugin",
+    "cursor-rules",
+    "gemini-extension.json",
+    "SKILL.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/FavioVazquez/learnship#readme",
+  "bugs": {
+    "url": "https://github.com/FavioVazquez/learnship/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FavioVazquez/learnship.git"
+  },
+  "license": "MIT",
+  "author": "Favio Vazquez",
+  "bin": {
+    "learnship": "./bin/install.js"
+  },
+  "scripts": {
+    "start": "node bin/learnship.js",
+    "test": "bash tests/run_all.sh"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/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