learnship 1.9.0

package/learnship/workflows/quick.md

@@ -0,0 +1,256 @@
+---
+description: Execute an ad-hoc task with full agentic guarantees — atomic commits, state tracking, no full planning ceremony
+---
+
+# Quick Task
+
+Execute small, ad-hoc tasks with full agentic guarantees: atomic commits, STATE.md tracking, optional discussion and verification.
+
+**Usage:** `quick [description]`
+
+**Flags:**
+- `--discuss` — lightweight discussion phase before planning (surfaces gray areas)
+- `--full` — adds plan-checking and post-execution verification
+
+**Composable:** `quick --discuss --full "add dark mode toggle"` gives discussion + plan-checking + verification.
+
+## Step 1: Get Task Description
+
+If a description was provided as an argument, use it. Otherwise ask:
+
+"What do you want to do?"
+
+Wait for response. Store as `DESCRIPTION`.
+
+Display banner based on active flags:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► QUICK TASK [flags if any]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 2: Initialize
+
+Check that a project exists:
+```bash
+test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+```
+
+If ROADMAP.md missing: stop — run `new-project` first. Quick tasks require an active project.
+
+Generate a slug from the description (lowercase, hyphens, max 40 chars).
+
+Find the next task number:
+```bash
+ls .planning/quick/ 2>/dev/null | grep -E "^[0-9]+" | sort -n | tail -1
+```
+
+Set `NEXT_NUM` to the next available number (001, 002, etc.).
+
+Create task directory:
+```bash
+mkdir -p ".planning/quick/${NEXT_NUM}-${SLUG}"
+```
+
+Report: "Creating quick task ${NEXT_NUM}: ${DESCRIPTION}"
+
+## Step 3: Discussion Phase (only with `--discuss`)
+
+**Skip this step if `--discuss` flag is not present.**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► DISCUSSING: [DESCRIPTION]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Analyze `DESCRIPTION` to identify 2-4 gray areas — implementation decisions that would change the outcome.
+
+Present them for selection (multi-select):
+- Each area is a concrete decision point (not generic)
+- Include an "All clear — skip discussion" option
+
+If "All clear" → skip to Step 4.
+
+For each selected area, ask 1-2 focused questions with concrete options. Max 2 questions per area — keep it lightweight.
+
+Write `CONTEXT.md` to the task directory:
+
+```markdown
+# Quick Task [NEXT_NUM]: [DESCRIPTION] - Context
+
+**Gathered:** [date]
+**Status:** Ready for planning
+
+<domain>
+## Task Boundary
+
+[DESCRIPTION]
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### [Area discussed]
+- [Decision captured]
+
+### Claude's Discretion
+[Areas not discussed or "you decide" answers]
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+[Any specific references or examples]
+
+</specifics>
+```
+
+## Step 4: Create Plan
+
+Using `@./agents/planner.md` as your planning persona, read:
+- `.planning/STATE.md`
+- CONTEXT.md if it exists (from `--discuss`)
+- The task description
+
+Create a **single PLAN.md** with 1-3 focused tasks in `.planning/quick/${NEXT_NUM}-${SLUG}/${NEXT_NUM}-PLAN.md`.
+
+Each task needs:
+- `<files>` — exact files to create/modify
+- `<action>` — specific implementation instructions
+- `<verify>` — how to confirm it worked
+- `<done>` — observable completion criteria
+
+If `--full`: also include `must_haves` in plan frontmatter (truths, artifacts, key_links).
+
+Verify plan was created:
+```bash
+test -f ".planning/quick/${NEXT_NUM}-${SLUG}/${NEXT_NUM}-PLAN.md" && echo "OK"
+```
+
+## Step 5: Plan Check (only with `--full`)
+
+**Skip if `--full` flag is not present.**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► CHECKING PLAN
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/verifier.md`, 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)?
+- If `--discuss`: does the plan honor locked decisions from CONTEXT.md?
+
+**Revision loop (max 2 iterations):** If issues found, revise and re-check.
+
+If still failing after 2 iterations: present remaining issues and ask — **Force proceed** or **Abort**.
+
+## Step 6: Execute
+
+Using `@./agents/executor.md` as your execution persona, read the PLAN.md and execute each task:
+
+1. Read the task's `<files>`, `<action>`, `<verify>`, `<done>` fields
+2. Implement what the action describes
+3. Verify using the verify criteria
+4. Commit atomically:
+
+```bash
+git add [files modified]
+git commit -m "feat(quick-${NEXT_NUM}): [task description]"
+```
+
+After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
+
+```markdown
+# Quick Task [NEXT_NUM] Summary
+
+**Task:** [DESCRIPTION]
+**Completed:** [date]
+
+## What was done
+[2-3 sentences]
+
+## Files changed
+- [file]: [what changed]
+
+## Commit
+[commit hash]
+```
+
+## Step 7: Verify Results (only with `--full`)
+
+**Skip if `--full` flag is not present.**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► VERIFYING RESULTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/verifier.md`, check `must_haves` from the plan against the actual codebase.
+
+Write `${NEXT_NUM}-VERIFICATION.md`. Store status as `VERIFICATION_STATUS`.
+
+## Step 8: Update STATE.md
+
+Read `.planning/STATE.md` and append to the Quick Tasks table (create section if it doesn't exist):
+
+```markdown
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+| [NEXT_NUM] | [DESCRIPTION] | [date] | [hash] | [path] |
+```
+
+Update "Last activity" line:
+```
+Last activity: [date] - Completed quick task [NEXT_NUM]: [DESCRIPTION]
+```
+
+## Step 9: Final Commit
+
+```bash
+git add ".planning/quick/${NEXT_NUM}-${SLUG}/" .planning/STATE.md
+git commit -m "docs(quick-${NEXT_NUM}): ${DESCRIPTION}"
+```
+
+Display completion:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► QUICK TASK COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Quick Task [NEXT_NUM]: [DESCRIPTION]
+
+Summary: .planning/quick/[NEXT_NUM]-[SLUG]/[NEXT_NUM]-SUMMARY.md
+[If --full: Verification: [status]]
+Commit: [hash]
+
+Ready for next task: quick
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer based on how the task went:
+
+> 💡 **Learning moment:** Task done. Pick the action that matches what happened:
+>
+> `@agentic-learning struggle [task]` — If the task was tricky or used unfamiliar patterns: work through a similar problem from scratch with a hint ladder. Builds deeper intuition than just reading the solution.
+>
+> `@agentic-learning learn [task topic]` — If the task touched an unfamiliar domain: active retrieval while the context is fresh. You explain first, gaps get filled.
+>
+> `@agentic-learning either-or` — If you made a meaningful design decision during the task: log the choice and the alternatives considered.
+
+**If `manual`:** No note for quick tasks (keep it fast).

package/learnship/workflows/reapply-patches.md

@@ -0,0 +1,130 @@
+---
+description: Restore local workflow customizations after updating the platform
+---
+
+# Reapply Patches
+
+Restore local modifications to platform workflows after running `/update`. The update workflow backs up locally modified files before overwriting — this workflow merges your changes back.
+
+**Usage:** `reapply-patches`
+
+**Use after:** `/update` reports that local changes were backed up.
+
+## Step 1: Find Backed-Up Patches
+
+Check for the local patches directory:
+```bash
+ls .windsurf/local-patches/ 2>/dev/null || ls ~/.codeium/windsurf/local-patches/ 2>/dev/null
+```
+
+Also check for a patches manifest:
+```bash
+cat .windsurf/local-patches/PATCHES.md 2>/dev/null
+```
+
+If no patches directory found:
+```
+No local patches found. Nothing to reapply.
+
+If you expected patches, check:
+- .windsurf/local-patches/
+- ~/.codeium/windsurf/local-patches/
+```
+
+Stop.
+
+## Step 2: Inventory Patches
+
+Read the patches directory and list what was backed up:
+
+```bash
+find .windsurf/local-patches/ -name "*.md" -o -name "*.json" 2>/dev/null | sort
+```
+
+Display:
+```
+Found [N] backed-up local modification(s):
+
+- [filename] — [last modified date]
+- [filename] — [last modified date]
+```
+
+## Step 3: Review Each Patch
+
+For each backed-up file, compare it with the current installed version:
+
+Read the backed-up file and the current installed file. Identify:
+- Lines only in your local version (customizations)
+- Lines only in the new version (upstream changes)
+- Lines in both (unchanged)
+
+Display a summary for each file:
+```
+## [filename]
+
+Your local changes:
+- [Line/section you added or modified]
+- [Another change]
+
+New upstream content:
+- [What the update added or changed]
+
+Conflict? [Yes/No — if yes, describe what overlaps]
+```
+
+## Step 4: Merge Strategy
+
+For each file, choose the merge approach:
+
+**Non-conflicting changes** (your edits and upstream edits touch different sections):
+→ Auto-merge: apply your changes on top of the new version
+
+**Conflicting changes** (same section modified by both):
+→ Show the conflict, ask:
+```
+Conflict in [filename]:
+
+Your version:
+[your text]
+
+Upstream version:
+[upstream text]
+
+Choose:
+1. Keep yours (discard upstream change)
+2. Keep upstream (discard your change)
+3. Merge manually — I'll show you both and you edit
+```
+
+Wait for choice.
+
+## Step 5: Apply Merged Files
+
+Write each merged file to its target location. Verify the write succeeded.
+
+## Step 6: Clean Up Patches
+
+After successfully reapplying all patches:
+```bash
+rm -rf .windsurf/local-patches/
+```
+
+Or if the user wants to keep the backup:
+```bash
+mv .windsurf/local-patches/ .windsurf/local-patches-$(date +%Y%m%d)/
+```
+
+## Step 7: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PATCHES REAPPLIED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[N] local modification(s) restored:
+- [file]: [brief description of what was restored]
+
+Local patches directory cleared.
+
+Your customizations are now active on top of the updated platform.
+```

package/learnship/workflows/release.md

@@ -0,0 +1,217 @@
+---
+description: Cut a new learnship release — bump version, update changelog, push to public-main, tag, create GitHub release
+---
+
+# Release — learnship
+
+Ships a new version to the public GitHub repo and creates a GitHub release with changelog notes.
+
+> **Private workflow** — gitignored, never shipped with the product.
+> Requires a GitHub PAT with `repo` scope in the environment or entered at runtime.
+
+---
+
+## Step 1: Confirm you are on main and clean
+
+```bash
+cd /home/ec2-user/favio/agentic-development
+git status
+git log --oneline -5
+```
+
+Everything must be clean. If not, commit or stash first.
+
+---
+
+## Step 2: Decide the version bump
+
+Ask the user: "What kind of release is this?"
+
+- **patch** — bug fixes only (e.g. `1.1.0` → `1.1.1`)
+- **minor** — new workflows, skills, or agent personas (e.g. `1.1.0` → `1.2.0`)
+- **major** — breaking changes or major new capability layers (e.g. `1.1.0` → `2.0.0`)
+
+Read the current version:
+```bash
+node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)"
+```
+
+Calculate the new version based on the bump type.
+
+Ask the user: "Releasing as vX.Y.Z — confirm?"
+
+---
+
+## Step 3: Collect release notes
+
+Ask the user: "What changed in this release? List the highlights."
+
+Wait for their input. Then organize into:
+- `### Added` — new workflows, skills, features
+- `### Changed` — behaviour changes, improvements
+- `### Fixed` — bugs resolved
+
+If any section has no entries, omit it.
+
+---
+
+## Step 4: Update CHANGELOG.md
+
+Prepend a new entry above the current latest version in `CHANGELOG.md`:
+
+```markdown
+## [vX.Y.Z] — [Short title]
+
+**Released:** YYYY-MM-DD
+
+### Added
+- ...
+
+### Fixed
+- ...
+```
+
+Use today's date (run `date +%Y-%m-%d` to get it).
+
+---
+
+## Step 5: Bump version in package.json
+
+Edit `package.json` — change the `"version"` field to the new version string.
+
+---
+
+## Step 6: Run tests to verify nothing is broken
+
+```bash
+bash tests/run_all.sh
+```
+
+If any test fails, stop and fix before proceeding.
+
+---
+
+## Step 7: Commit on main
+
+```bash
+git add CHANGELOG.md package.json
+git commit -m "chore: release vX.Y.Z — [short title]"
+```
+
+---
+
+## Step 8: Set remote URL with PAT
+
+Ask the user for their GitHub PAT if not already set, or check if it's in `.env`:
+
+```bash
+source .env 2>/dev/null && echo "PAT found: ${GITHUB_PAT:0:8}..." || echo "PAT not in .env — will prompt"
+```
+
+If not in `.env`, ask: "Please provide your GitHub PAT."
+
+Set the remote:
+```bash
+git remote set-url origin https://<PAT>@github.com/FavioVazquez/learnship.git
+```
+
+---
+
+## Step 9: Cherry-pick release commit onto public-main
+
+```bash
+git checkout public-main
+
+# Bring over CHANGELOG.md and package.json from main
+git checkout main -- CHANGELOG.md package.json
+git add CHANGELOG.md package.json
+git commit -m "chore: release vX.Y.Z — [short title]"
+
+# Push to GitHub main
+git push origin public-main:main
+```
+
+---
+
+## Step 10: Tag the release
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+---
+
+## Step 11: Create GitHub release via API
+
+```bash
+RELEASE_NOTES="$(cat <<'NOTES'
+## What's new in vX.Y.Z
+
+[paste formatted release notes here]
+
+## Install
+
+\`\`\`bash
+npx github:FavioVazquez/learnship
+\`\`\`
+
+See [CHANGELOG.md](https://github.com/FavioVazquez/learnship/blob/main/CHANGELOG.md) for full details.
+NOTES
+)"
+
+curl -s -X POST \
+  -H "Authorization: token <PAT>" \
+  -H "Content-Type: application/json" \
+  https://api.github.com/repos/FavioVazquez/learnship/releases \
+  -d "{
+    \"tag_name\": \"vX.Y.Z\",
+    \"target_commitish\": \"main\",
+    \"name\": \"vX.Y.Z — [Short title]\",
+    \"body\": $(echo "$RELEASE_NOTES" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))'),
+    \"draft\": false,
+    \"prerelease\": false
+  }" | python3 -c "import sys,json; r=json.load(sys.stdin); print(r.get('html_url', r.get('message','ERROR')))"
+```
+
+If successful, the release URL is printed.
+
+---
+
+## Step 12: Switch back to main and strip the PAT
+
+```bash
+git checkout main
+git remote set-url origin https://github.com/FavioVazquez/learnship.git
+```
+
+Verify the token is gone:
+```bash
+git remote -v
+# Must show plain HTTPS — no token visible
+```
+
+---
+
+## Step 13: Verify
+
+```bash
+git log --oneline public-main -3   # new release commit at top
+git tag --sort=-version:refname | head -5   # new tag at top
+```
+
+Open the release URL printed in Step 11 to confirm it looks correct on GitHub.
+
+---
+
+## Done
+
+```
+✓ vX.Y.Z tagged and pushed
+✓ GitHub release created with notes
+✓ CHANGELOG.md and package.json updated
+✓ PAT stripped from remote URL
+✓ Back on local main
+```
+
+Next release: repeat from Step 1.