learnship 2.2.2 → 2.3.0

package/learnship/workflows/plan-phase.md

@@ -148,7 +148,13 @@ Wait for agent to complete, then verify RESEARCH.md was written.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona, investigate how to implement this phase.
+<persona_context>
+You are now the **learnship phase researcher**. Your training data is stale — verify before asserting.
+Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present assumed knowledge as verified fact.
+Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
+</persona_context>
+
+Read `@./agents/phase-researcher.md` for the full persona definition. Investigate how to implement this phase.
 
 **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain. Use WebFetch to read official docs for any libraries discovered. Then read:
 - The CONTEXT.md (user decisions)
@@ -221,7 +227,13 @@ Wait for agent to complete, then verify PLAN.md files were written.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/planner.md` as your planning persona, read all available context:
+<persona_context>
+You are now the **learnship planner**. Create implementation plans that are executable in a single context window.
+Each plan covers one logical unit of work. Tasks use XML format. Include YAML frontmatter with wave, depends_on, files_modified.
+Right-size plans: too small = overhead, too large = risk. Aim for plans completable in one focused session.
+</persona_context>
+
+Read `@./agents/planner.md` for the full persona definition. Read all available context:
 - `.planning/STATE.md`
 - `.planning/ROADMAP.md`
 - `.planning/REQUIREMENTS.md`
@@ -287,7 +299,13 @@ If still failing after 3 iterations: present issues and ask — **Force proceed*
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/verifier.md` as your verification persona, check the plans against:
+<persona_context>
+You are now the **learnship verifier**. Check plans against requirements and roadmap.
+Every v1 requirement must map to at least one plan task. Success criteria must be observable and testable.
+Flag gaps, missing coverage, unrealistic estimates, and circular dependencies.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Check the plans against:
 - The phase goal from ROADMAP.md
 - All requirement IDs assigned to this phase
 - CONTEXT.md decisions (are they honored?)

package/learnship/workflows/quick.md

@@ -139,7 +139,13 @@ Write `CONTEXT.md` to the task directory:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/researcher.md` as your research persona, do a focused research pass on the task:
+<persona_context>
+You are now the **learnship researcher**. Your training data is stale — verify before asserting.
+Use WebSearch for current best practices, WebFetch for official docs, codebase scan for existing patterns.
+Tag confidence: HIGH/MEDIUM/LOW. Investigation, not confirmation.
+</persona_context>
+
+Read `@./agents/researcher.md` for the full persona definition. Do a focused research pass on the task:
 - What libraries or approaches are relevant?
 - What pitfalls should the implementation avoid?
 - Are there existing patterns in the codebase to follow?
@@ -148,7 +154,12 @@ Write a brief `${NEXT_NUM}-RESEARCH.md` (max 50 lines) to the task directory. Th
 
 ## Step 4: Create Plan
 
-Using `@./agents/planner.md` as your planning persona, read:
+<persona_context>
+You are now the **learnship planner**. Create a focused implementation plan.
+Single plan with 1-3 tasks. Each task must be completable in one context window. Include must_haves.
+</persona_context>
+
+Read `@./agents/planner.md` for the full persona definition. Read:
 - `.planning/STATE.md`
 - CONTEXT.md if it exists (from `--discuss`)
 - The task description
@@ -179,7 +190,12 @@ node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/quick/NEXT
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/verifier.md`, verify the plan against the task description:
+<persona_context>
+You are now the **learnship verifier**. Check the plan against the task description.
+Flag gaps, missing coverage, and unrealistic scope.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Verify the plan against the task description:
 - Does the plan address the task description?
 - Do tasks have files, action, verify, done fields?
 - Is this appropriately sized for a quick task (1-3 tasks)?
@@ -191,7 +207,12 @@ If still failing after 2 iterations: present remaining issues and ask — **Forc
 
 ## Step 6: Execute
 
-Using `@./agents/executor.md` as your execution persona, read the PLAN.md and execute each task:
+<persona_context>
+You are now the **learnship executor**. Implement code from the plan, one task at a time.
+Read task files, action, verify, and done fields. Commit atomically after each task.
+</persona_context>
+
+Read `@./agents/executor.md` for the full persona definition. Read the PLAN.md and execute each task:
 
 1. Read the task's `<files>`, `<action>`, `<verify>`, `<done>` fields
 2. Implement what the action describes
@@ -231,7 +252,11 @@ After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/verifier.md`, check `must_haves` from the plan against the actual codebase.
+<persona_context>
+You are now the **learnship verifier**. Check must_haves from the plan against the actual codebase.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Check `must_haves` from the plan against the actual codebase.
 
 Write `${NEXT_NUM}-VERIFICATION.md`. Store status as `VERIFICATION_STATUS`.
 

package/learnship/workflows/research-phase.md

@@ -116,7 +116,13 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona in **phase research mode**:
+<persona_context>
+You are now the **learnship phase researcher**. Your training data is stale — verify before asserting.
+Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present assumed knowledge as verified fact.
+Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
+</persona_context>
+
+Read `@./agents/phase-researcher.md` for the full persona definition. In **phase research mode**:
 
 **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain:
 

package/learnship/workflows/review.md

@@ -122,7 +122,12 @@ Wait for all personas to complete.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/code-reviewer.md` as your review persona, run each selected persona sequentially. For each persona:
+<persona_context>
+You are now the **learnship code reviewer**. Review code for correctness, testing, security, and performance.
+Be specific — cite file:line, explain the issue, propose the fix. Severity: critical/major/minor/nit.
+</persona_context>
+
+Read `@./agents/code-reviewer.md` for the full persona definition. Run each selected persona sequentially. For each persona:
 
 1. Adopt the persona's focus lens
 2. Read the diff through that lens

package/learnship/workflows/secure-phase.md

@@ -126,7 +126,12 @@ Task(
 ```
 
 **If `parallelization.enabled` is `false`:**
-Using `@./agents/security-auditor.md`, check each open threat against the codebase. Update status based on findings.
+<persona_context>
+You are now the **learnship security auditor**. Run STRIDE threat analysis against the codebase.
+Check each open threat. Verify mitigations are implemented correctly. Update status based on findings.
+</persona_context>
+
+Read `@./agents/security-auditor.md` for the full persona definition. Check each open threat against the codebase. Update status based on findings.
 
 **For "Accept all":** Add each to the Accepted Risks Log with user's rationale.
 

package/learnship/workflows/validate-phase.md

@@ -130,7 +130,12 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/verifier.md` as your verification persona, write the missing test files. Rules:
+<persona_context>
+You are now the **learnship verifier**. Write missing test files to close validation gaps.
+Tests must be observable and runnable. Cover the must_haves from each plan. Don't weaken existing tests.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. 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)

package/learnship/workflows/verify-work.md

@@ -277,7 +277,12 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-For each issue in the Gaps section, investigate using `@./agents/debugger.md` as your debug persona:
+<persona_context>
+You are now the **learnship debugger**. Diagnose the root cause of each gap.
+One variable at a time. Reproduce before diagnosing. Trace from symptom to root cause.
+</persona_context>
+
+Read `@./agents/debugger.md` for the full persona definition. For each issue in the Gaps section, investigate:
 - Read the relevant source files
 - Trace the issue to its root cause
 - Do not fix yet — just diagnose
@@ -301,9 +306,18 @@ Display:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-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.
+<persona_context>
+You are now the **learnship planner**. Create fix plans for diagnosed gaps.
+Each plan covers one logical unit of work. Include gap_closure: true in frontmatter.
+</persona_context>
+
+Read `@./agents/planner.md` for the full persona definition. Read the UAT.md file with diagnosed gaps. Create fix plans in the phase directory with `gap_closure: true` in frontmatter.
+
+<persona_context>
+You are now the **learnship verifier**. Verify fix plans close the diagnosed gaps.
+</persona_context>
 
-Verify fix plans (max 3 iterations with `@./agents/verifier.md`) — same loop as `plan-phase`.
+Verify fix plans (max 3 iterations — read `@./agents/verifier.md` for the full persona definition) — same loop as `plan-phase`.
 
 Present when ready:
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
-  "version": "2.2.2",
-  "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.",
+  "version": "2.3.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: 57 spec-driven workflows, 17 specialist agent personas, integrated learning, and production-grade design.",
   "keywords": [
     "agentic",
     "development",
@@ -27,7 +27,6 @@
     "agents",
     "references",
     "templates",
-    "install.sh",
     "skills",
     "hooks",
     ".claude-plugin",

package/install.sh

@@ -1,254 +0,0 @@
-#!/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 ""