learnship 1.9.24 → 2.0.1

package/learnship/workflows/ship.md

@@ -0,0 +1,219 @@
+---
+description: Ship pipeline — test, lint, commit, push, PR
+---
+
+# Ship
+
+End-to-end ship pipeline: detect test runner → run tests → lint → stage → conventional commit → push → create PR with auto-description. Closes the loop from verified code to production-ready PR.
+
+**Usage:** `ship` — run the full ship pipeline
+**Usage:** `ship --skip-tests` — skip test execution (use when tests were just run)
+
+**Sequencing:** Run after `/review` (code quality) and before `/compound` (capture learnings).
+
+## Step 1: Pre-flight Check
+
+```bash
+# Current branch
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "Branch: $BRANCH"
+
+# Check we're not on main/master
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo "ERROR: Cannot ship from $BRANCH. Create a feature branch first."
+  exit 1
+fi
+
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If uncommitted changes exist, ask: "You have uncommitted changes. Stage and commit them as part of the ship, or stash first?"
+
+## Step 2: Run Tests
+
+**Skip if:** `--skip-tests` flag, or `ship.auto_test` is `false` in config.
+
+Detect the test runner:
+
+```bash
+# Check for common test runners
+[ -f "package.json" ] && grep -q '"test"' package.json && echo "npm test"
+[ -f "Makefile" ] && grep -q '^test:' Makefile && echo "make test"
+[ -f "pytest.ini" ] || [ -f "setup.cfg" ] && echo "pytest"
+[ -f "Cargo.toml" ] && echo "cargo test"
+[ -f "go.mod" ] && echo "go test ./..."
+```
+
+Run the detected test command:
+
+```bash
+[detected test command]
+```
+
+If tests fail:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► TESTS FAILED — SHIP ABORTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[test output]
+
+Fix the failing tests, then run /ship again.
+▶ Or: /debug [test failure description]
+```
+
+Stop. Do not proceed with a failing test suite.
+
+## Step 3: Lint (Optional)
+
+Detect and run the linter if available:
+
+```bash
+[ -f "package.json" ] && grep -q '"lint"' package.json && echo "npm run lint"
+[ -f ".eslintrc" ] || [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] && echo "npx eslint ."
+[ -f "pyproject.toml" ] && grep -q "ruff" pyproject.toml && echo "ruff check ."
+[ -f ".rubocop.yml" ] && echo "rubocop"
+```
+
+If linter found, run it. Report warnings but don't block on them. Block on errors.
+
+## Step 4: Stage Changes
+
+```bash
+# Show what will be committed
+git diff --stat
+
+# Stage all tracked changes
+git add -u
+
+# Check for untracked files that should be included
+UNTRACKED=$(git ls-files --others --exclude-standard)
+if [ -n "$UNTRACKED" ]; then
+  echo "Untracked files found:"
+  echo "$UNTRACKED"
+fi
+```
+
+If untracked files exist, ask: "These files are new and untracked. Include them in the commit?"
+- **Yes, include all** → `git add .`
+- **Let me choose** → present list, user selects
+- **No, skip them** → proceed with tracked only
+
+## Step 5: Conventional Commit
+
+**If `ship.conventional_commits` is `true` in config (default: `true`):**
+
+Analyze the staged changes to determine the commit type:
+
+| Type | When |
+|------|------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no logic change |
+| `refactor` | Code restructuring, no behavior change |
+| `test` | Adding or updating tests |
+| `chore` | Build, config, tooling |
+
+Generate the commit message:
+```
+[type]([scope]): [short description]
+
+[optional body — what changed and why, max 3 lines]
+```
+
+Present the proposed commit message. Ask: "Use this commit message, or edit?"
+
+```bash
+git commit -m "[commit message]"
+```
+
+## Step 6: Push
+
+```bash
+git push origin $BRANCH
+```
+
+If this is the first push for the branch:
+```bash
+git push -u origin $BRANCH
+```
+
+## Step 7: Create PR
+
+**If `ship.pr_template` is `true` in config (default: `true`):**
+
+Auto-generate the PR description from:
+- Commit messages on the branch
+- SUMMARY.md files from the current phase (if exists)
+- Test results from Step 2
+
+```bash
+# Get base branch
+BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||')
+[ -z "$BASE_BRANCH" ] && BASE_BRANCH="main"
+
+# Get commit log for PR body
+COMMITS=$(git log --oneline origin/$BASE_BRANCH..HEAD)
+```
+
+Create the PR using available tooling:
+
+```bash
+# GitHub CLI
+gh pr create --base "$BASE_BRANCH" --head "$BRANCH" --title "[type]([scope]): [description]" --body "[auto-generated description]"
+
+# Or if gh not available, output the PR URL
+echo "Create PR: https://github.com/[org]/[repo]/compare/$BASE_BRANCH...$BRANCH"
+```
+
+## Step 8: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► SHIPPED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Branch: [branch]
+Tests: passed ✓
+Lint: passed ✓ | skipped
+Commit: [hash] [type]([scope]): [description]
+PR: [URL]
+
+💡 Compound this work? Run `/compound` to capture any notable solutions
+or patterns while context is fresh.
+
+▶ Next steps:
+- Review the PR and request reviews
+- /compound — capture learnings from this work
+```
+
+---
+
+## Config Options
+
+- `"ship.auto_test": true` — run tests before shipping
+- `"ship.conventional_commits": true` — use conventional commit format
+- `"ship.pr_template": true` — auto-generate PR description
+
+---
+
+## Integration Points
+
+- `verify-work` banner: "▶ Next: /ship" after UAT passes
+- `complete-milestone`: "Did you /ship first?" if unshipped changes exist
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After shipping, offer:
+
+> 💡 **Learning moment:** Shipping is a natural reflection point:
+>
+> `@agentic-learning reflect` — What went well in this phase? What would you do differently? Reflection after shipping cements the lessons before context fades.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to consolidate lessons from this shipping cycle."*

package/learnship/workflows/sync-docs.md

@@ -0,0 +1,159 @@
+---
+description: Detect stale documentation after code changes
+---
+
+# Sync Docs
+
+Scan documentation against recent code changes to detect stale sections, outdated references, and drift between docs and implementation. Auto-update simple cases, flag complex ones for manual review.
+
+**Usage:** `sync-docs` — scan all docs for staleness
+**Usage:** `sync-docs [path]` — scan docs for a specific module or directory
+
+## Step 1: Discover Documentation
+
+Find all documentation files in the project:
+
+```bash
+# README and top-level docs
+find . -maxdepth 1 -name "*.md" -type f 2>/dev/null
+
+# Docs directory
+find docs/ -name "*.md" -type f 2>/dev/null
+
+# API docs, guides, etc.
+find . -path "*/docs/*" -name "*.md" -type f 2>/dev/null | head -30
+
+# Planning docs
+find .planning/ -name "*.md" -type f 2>/dev/null | grep -v "phases\|debug\|milestones" | head -20
+```
+
+If a path argument was provided, narrow the scan to docs related to that module.
+
+## Step 2: Identify Recent Changes
+
+```bash
+# Get files changed in last 30 commits
+git log --oneline -30 --format="" --name-only | sort -u
+
+# Get files changed since last tag/release
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)
+if [ -n "$LAST_TAG" ]; then
+  git diff --name-only "$LAST_TAG"..HEAD
+fi
+```
+
+Map changed source files to their documentation:
+- `src/auth/` changes → check docs mentioning auth, authentication, login
+- API route changes → check API documentation
+- Config changes → check setup/installation docs
+- Schema changes → check data model docs
+
+## Step 3: Scan for Staleness
+
+For each documentation file, check:
+
+1. **Dead references** — does the doc reference files, functions, or APIs that no longer exist?
+```bash
+# Extract code references from doc (backtick-wrapped paths, function names)
+grep -oE '`[^`]+\.(ts|js|py|rb|go)`' [doc_file] 2>/dev/null
+# Check if referenced files exist
+```
+
+2. **Outdated descriptions** — does the doc describe behavior that's changed?
+- Compare doc descriptions against actual code behavior
+- Check version numbers, dependency names, command syntax
+
+3. **Missing coverage** — are there new files/features with no documentation?
+```bash
+# Find source files with no corresponding doc mention
+for file in $(git log --oneline -30 --format="" --name-only | sort -u | grep -E '\.(ts|js|py|rb|go)$'); do
+  BASENAME=$(basename "$file" | sed 's/\.[^.]*$//')
+  grep -ril "$BASENAME" docs/ 2>/dev/null | wc -l | tr -d ' '
+done
+```
+
+## Step 4: Report Findings
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DOC SYNC REPORT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Scanned: [N] documentation files
+Changes since: [last tag or last 30 commits]
+
+## Stale Sections
+
+| Doc | Section | Issue | Severity |
+|-----|---------|-------|----------|
+| [file] | [heading] | [what's wrong] | high/medium/low |
+
+## Dead References
+
+| Doc | Reference | Status |
+|-----|-----------|--------|
+| [file] | `[reference]` | removed / renamed to [new name] |
+
+## Missing Documentation
+
+| New File/Feature | Suggested Doc |
+|------------------|---------------|
+| [file] | Add to [existing doc] or create new |
+
+## Auto-Fixable
+
+[N] issues can be auto-fixed (renamed references, updated paths)
+```
+
+## Step 5: Auto-Fix Simple Cases
+
+For issues that can be fixed automatically (renamed files, updated paths, version numbers):
+
+```bash
+# Apply fixes
+sed -i 's/old_reference/new_reference/g' [doc_file]
+
+git add [fixed files]
+git commit -m "docs: sync — fix [N] stale references"
+```
+
+For complex issues (rewritten behavior, new feature descriptions), present to user:
+
+```
+These [N] issues need manual review:
+1. [doc]: [section] — [what needs updating and why]
+2. [doc]: [section] — [what needs updating and why]
+```
+
+## Step 6: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DOC SYNC COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Auto-fixed: [N] issues
+Manual review needed: [M] issues
+Missing docs: [K] new features without documentation
+```
+
+---
+
+## Integration Points
+
+- `complete-milestone`: optionally run `/sync-docs` before releasing
+- `release`: suggest `/sync-docs` as pre-release checklist item
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After sync, offer:
+
+> 💡 **Learning moment:** Documentation drift is a signal about process:
+>
+> `@agentic-learning reflect` — Why did these docs get stale? Is there a pattern (e.g., docs always lag behind API changes)? Reflecting on the drift pattern prevents it next time.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` to understand why docs drifted and prevent it."*

package/learnship/workflows/validate-phase.md

@@ -14,10 +14,10 @@ Retroactively audit and fill test coverage gaps for a completed phase. Useful af
 
 Read `.planning/config.json`:
 ```bash
-cat .planning/config.json | grep "nyquist_validation"
+cat .planning/config.json | grep "validation"
 ```
 
-If `nyquist_validation: false`: stop — "Validation is disabled. Enable it in `/settings` to use this workflow."
+If `validation: false`: stop — "Validation is disabled. Enable it in `/settings` to use this workflow."
 
 ## Step 2: Validate Phase
 
@@ -76,7 +76,7 @@ For each requirement ID assigned to this phase:
    - **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`.
+If no gaps (all COVERED): proceed directly to step 8 with `compliant: true`.
 
 ## Step 7: Present Gap Plan and Fill
 
@@ -118,7 +118,7 @@ Write `$PHASE_DIR/[padded_phase]-VALIDATION.md`:
 
 ```markdown
 ---
-nyquist_compliant: true | false
+compliant: true | false
 wave_0_complete: true | false
 phase: [N]
 validated: [date]

package/learnship/workflows/verify-work.md

@@ -185,6 +185,9 @@ Display summary:
 ```
 All tests passed. ✓
 
+💡 Compound learnings? Run `/compound` to capture any notable solutions
+or patterns from this phase while context is fresh.
+
 ▶ Next: discuss-phase [X+1]
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "1.9.24",
+  "version": "2.0.1",
   "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",

package/references/model-profiles.md

@@ -1,40 +1,49 @@
 # Model Profiles
 
-Model profiles control which AI model each learnship agent uses. This allows balancing quality vs token spend.
+Model profiles control which AI model tier each learnship agent uses. Profiles are platform-agnostic — they use three tiers (`large`, `medium`, `small`) that map to specific models depending on your platform.
 
 ## Profile Definitions
 
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
-| planner | opus | opus | sonnet |
-| roadmapper | opus | sonnet | sonnet |
-| executor | opus | sonnet | sonnet |
-| phase-researcher | opus | sonnet | haiku |
-| project-researcher | opus | sonnet | haiku |
-| research-synthesizer | sonnet | sonnet | haiku |
-| debugger | opus | sonnet | sonnet |
-| codebase-mapper | sonnet | haiku | haiku |
-| verifier | sonnet | sonnet | haiku |
-| plan-checker | sonnet | sonnet | haiku |
-| integration-checker | sonnet | sonnet | haiku |
-| nyquist-auditor | sonnet | sonnet | haiku |
+| planner | large | large | medium |
+| executor | large | medium | medium |
+| phase-researcher | large | medium | small |
+| debugger | large | medium | medium |
+| verifier | medium | medium | small |
+| plan-checker | medium | medium | small |
+| solution-writer | medium | medium | small |
+| code-reviewer | large | medium | medium |
+| challenger | large | medium | medium |
+| ideation-agent | large | medium | small |
+
+## Platform Model Resolution
+
+Each tier resolves to the best available model on your platform:
+
+| Tier | Anthropic (Claude Code) | Google (Gemini CLI) | OpenAI (Codex CLI) | Windsurf / Cursor / OpenCode |
+|------|------------------------|--------------------|--------------------|-----------------------------|
+| `large` | Claude Opus 4.6 | Gemini 3.1 Pro | GPT-5.4 | Uses platform default (best available) |
+| `medium` | Claude Sonnet 4.6 | Gemini 3.1 Flash | GPT-5.4-mini | Uses platform default |
+| `small` | Claude Haiku 4.5 | Gemini 3.1 Flash-Lite | GPT-5.4-nano | Uses platform default |
+
+> **Note:** Windsurf, Cursor, and OpenCode do not expose per-agent model selection. The profile tiers are still useful — they signal the *intended complexity* of each agent's task, and workflows will adapt their prompting strategy accordingly (e.g., more explicit instructions for `small`-tier agents).
 
 ## Profile Philosophy
 
-**quality** - Maximum reasoning power
-- Opus for all decision-making agents
-- Sonnet for read-only verification
+**quality** — Maximum reasoning power
+- `large` for all decision-making agents (planner, researcher, reviewer, challenger)
+- `medium` for verification (needs reasoning, not just pattern matching)
 - Use when: quota available, critical architecture work
 
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
+**balanced** (default) — Smart allocation
+- `large` only for planning (where architecture decisions happen)
+- `medium` for execution, research, and verification
 - Use when: normal development, good balance of quality and cost
 
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
+**budget** — Minimal large-model usage
+- `medium` for anything that writes code
+- `small` for research and verification
 - Use when: conserving quota, high-volume work, less critical phases
 
 ## Resolution Logic
@@ -45,7 +54,8 @@ Resolution order:
 1. Read .planning/config.json
 2. Check model_overrides for agent-specific override
 3. If no override, look up agent in profile table
-4. Apply the resolved profile when adopting the agent persona
+4. Map the tier (large/medium/small) to the platform's actual model
+5. Apply the resolved model when adopting the agent persona
 ```
 
 ## Per-Agent Overrides
@@ -56,13 +66,13 @@ Override specific agents without changing the entire profile:
 {
   "model_profile": "balanced",
   "model_overrides": {
-    "executor": "opus",
-    "planner": "haiku"
+    "executor": "large",
+    "planner": "small"
   }
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
+Overrides take precedence over the profile. Valid values: `large`, `medium`, `small`.
 
 ## Switching Profiles
 
@@ -77,14 +87,12 @@ Per-project default: Set in `.planning/config.json`:
 
 ## Design Rationale
 
-**Why Opus for the planner?**
+**Why `large` for the planner?**
 Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
 
-**Why Sonnet for the executor?**
+**Why `medium` for the executor?**
 Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
 
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+**Why `medium` (not `small`) for verifiers in balanced?**
+Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching. Medium-tier models handle this well; small-tier models may miss subtle gaps.
 
-**Why Haiku for the codebase-mapper?**
-Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.

package/templates/config.json

@@ -3,6 +3,8 @@
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
+  "parallelization": false,
+  "test_first": false,
   "planning": {
     "commit_docs": true,
     "commit_mode": "auto",
@@ -12,7 +14,17 @@
     "research": true,
     "plan_check": true,
     "verifier": true,
-    "nyquist_validation": true
+    "validation": true,
+    "review": true,
+    "solutions_search": true
+  },
+  "review": {
+    "auto_after_verify": false
+  },
+  "ship": {
+    "auto_test": true,
+    "conventional_commits": true,
+    "pr_template": true
   },
   "git": {
     "branching_strategy": "none",