learnship 1.9.0

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

package/references/learning-design.md

@@ -0,0 +1,142 @@
+# Learning × Design Integration
+
+How to use the Learning Partner and Design System together. These two layers amplify each other when used at the right moments.
+
+---
+
+## The Core Idea
+
+Building software teaches you things. Building *interfaces* teaches you even more — because design decisions are high-stakes, visible, and often irreversible once shipped. The Learning Partner captures that knowledge before it evaporates.
+
+The pattern:
+1. **Before design** — brainstorm to surface blind spots
+2. **During design** — use steering commands to maintain quality
+3. **After design** — reflect to consolidate what you learned
+
+---
+
+## Before Any Design Work
+
+### Start with brainstorm
+
+Before writing a line of UI code, use:
+```
+@agentic-learning brainstorm [interface or feature name]
+```
+
+This surfaces:
+- What problem does this UI solve? For whom?
+- What mental model does the user have coming in?
+- What are the 2-3 approaches? What are the trade-offs?
+- What's the one thing they'll remember about this interface?
+
+The brainstorm is saved to `docs/brainstorm/` — it becomes a design brief that both the agent and you can reference.
+
+### Use either-or to log design decisions
+
+When you choose between two approaches (card layout vs. table, modal vs. inline edit, sidebar vs. tabs), log it:
+```
+@agentic-learning either-or
+```
+
+This creates a decision journal entry — paths considered, the choice, the rationale. When you revisit the design in 3 weeks and wonder "why did we do it this way?", the journal has the answer.
+
+---
+
+## During Design Sprints
+
+### Use steering commands to maintain quality
+
+While building interfaces, invoke design steering commands directly:
+
+| Moment | Command |
+|--------|---------|
+| Before starting any new component | `/audit` — check what quality problems to avoid |
+| After first pass of implementation | `/critique` — get honest feedback before polish |
+| Typography looks off | `/typography` — systematic type review |
+| Colors feel wrong | `/color` — OKLCH-based palette review |
+| Layout feels cramped or cluttered | `/layout` — spatial rhythm review |
+| Adding animations | `/motion` — purposeful motion, not decoration |
+| Building forms | `/forms` — labels, validation, error states |
+| Writing button labels or headings | `/copy` — UX writing review |
+| Worried about accessibility | `/accessibility` — focus, contrast, screen readers |
+
+### The AI Slop Test
+
+Run `/critique` and ask: "If someone saw this and said 'AI made this' — would they be right?"
+
+If yes, that's the signal to push harder. Use `@agentic-learning struggle` to work through it yourself first:
+```
+@agentic-learning struggle "make this interface feel genuinely designed, not AI-generated"
+```
+
+This forces you to try your own design thinking before getting a solution — which builds the design intuition that transfers to the next project.
+
+---
+
+## After Design Phases
+
+### Reflect after execute-phase
+
+When a UI phase finishes executing:
+```
+@agentic-learning reflect
+```
+
+Three questions:
+1. What design decisions did you make? Which ones felt right?
+2. What were you trying to achieve aesthetically and functionally?
+3. What's still fuzzy — patterns you used but don't fully understand?
+
+### Schedule design patterns for review
+
+After a design-heavy phase:
+```
+@agentic-learning space
+```
+
+This schedules the design patterns you used (OKLCH color, container queries, motion easing, etc.) for spaced review — so they transfer to long-term memory instead of being forgotten between projects.
+
+---
+
+## Learning Design Patterns Explicitly
+
+When you encounter a design pattern you want to understand deeply (not just copy):
+
+```
+@agentic-learning learn [pattern name]
+```
+
+Examples:
+- `@agentic-learning learn OKLCH color spaces`
+- `@agentic-learning learn container queries vs media queries`
+- `@agentic-learning learn exponential easing curves`
+- `@agentic-learning learn fluid typography with clamp()`
+
+The `learn` action uses active retrieval — you explain what you know first, then gaps are filled. This is how design patterns become intuition, not just copy-paste.
+
+### Quiz yourself on design principles
+
+After reading the design skill reference files:
+```
+@agentic-learning quiz typography
+@agentic-learning quiz color-and-contrast
+@agentic-learning quiz motion-design
+```
+
+---
+
+## The Full Design-Learning Loop
+
+```
+brainstorm → build → /critique → /polish → reflect → space
+```
+
+1. `@agentic-learning brainstorm` — clarify the problem and approach
+2. Build with steering commands as checkpoints
+3. `/critique` — honest quality check
+4. `/polish` — elevate and refine
+5. `@agentic-learning reflect` — consolidate what you learned
+6. `@agentic-learning space` — schedule patterns for review
+
+Each time through this loop, the design decisions get better — not because the AI gets better, but because *you* do.

package/references/model-profiles.md

@@ -0,0 +1,90 @@
+# Model Profiles
+
+Model profiles control which AI model each learnship agent uses. This allows balancing quality vs token spend.
+
+## 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 |
+
+## Profile Philosophy
+
+**quality** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- 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)
+- 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
+- Use when: conserving quota, high-volume work, less critical phases
+
+## Resolution Logic
+
+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
+```
+
+## Per-Agent Overrides
+
+Override specific agents without changing the entire profile:
+
+```json
+{
+  "model_profile": "balanced",
+  "model_overrides": {
+    "executor": "opus",
+    "planner": "haiku"
+  }
+}
+```
+
+Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
+
+## Switching Profiles
+
+Runtime: `/set-profile <profile>`
+
+Per-project default: Set in `.planning/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## Design Rationale
+
+**Why Opus 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?**
+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 Haiku for the codebase-mapper?**
+Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.

package/references/planning-config.md

@@ -0,0 +1,184 @@
+<planning_config>
+
+Configuration options for `.planning/` directory behavior.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "phase_branch_template": "phase-{phase}-{slug}",
+  "milestone_branch_template": "{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"phase"`, or `"milestone"` |
+| `git.phase_branch_template` | `"phase-{phase}-{slug}"` | Branch template for phase strategy |
+| `git.milestone_branch_template` | `"{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- SUMMARY.md, STATE.md, ROADMAP.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for `.planning/` files
+- User must add `.planning/` to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Reading `commit_docs` from config:**
+
+```bash
+# Read commit_docs from config.json
+COMMIT_DOCS=$(python3 -c "import json; c=json.load(open('.planning/config.json')); print(c.get('planning',{}).get('commit_docs','true'))" 2>/dev/null || echo 'true')
+```
+
+**Auto-detection:** If `.planning/` is gitignored, treat `commit_docs` as `false` regardless of config.json. This prevents git errors.
+
+```bash
+# Check if .planning/ is gitignored
+git check-ignore -q .planning && COMMIT_DOCS=false
+```
+
+**Committing planning docs (when commit_docs is true):**
+
+```bash
+git add .planning/STATE.md && git commit -m "docs: update state"
+```
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" .planning/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips `.planning/`
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include `.planning/`
+- Only needed when searching entire repo and expecting `.planning/` matches
+
+**Note:** Most learnship operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .planning/
+   ```
+
+3. **Existing tracked files:** If `.planning/` was previously tracked:
+   ```bash
+   git rm -r --cached .planning/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+4. **Branch merges:** When using `branching_strategy: phase` or `milestone`, the `complete-milestone` workflow automatically strips `.planning/` files from staging before merge commits when `commit_docs: false`.
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `phase` | At `execute-phase` start | Single phase | User merges after phase |
+| `milestone` | At first `execute-phase` of milestone | Entire milestone | At `complete-milestone` |
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- **Standard learnship behavior**
+
+**When `git.branching_strategy: "phase"`:**
+- `execute-phase` creates/switches to a branch before execution
+- Branch name from `phase_branch_template` (e.g., `phase-03-authentication`)
+- All plan commits go to that branch
+- User merges branches manually after phase completion
+- `complete-milestone` offers to merge all phase branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `execute-phase` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `v1.0-mvp`)
+- All phases in milestone commit to same branch
+- `complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{phase}` | phase_branch_template | Zero-padded phase number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+Read config directly:
+```bash
+python3 -c "import json; c=json.load(open('.planning/config.json')); g=c.get('git',{}); print(g.get('branching_strategy','none'), g.get('phase_branch_template','phase-{phase}-{slug}'), g.get('milestone_branch_template','{milestone}-{slug}'))"
+```
+
+**Branch creation:**
+
+```bash
+# For phase strategy
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  PHASE_SLUG=$(echo "$PHASE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$PHASE_BRANCH_TEMPLATE" | sed "s/{phase}/$PADDED_PHASE/g" | sed "s/{slug}/$PHASE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `phase` | Code review per phase, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+</planning_config>