phewsh 0.15.80 → 0.15.82

package/commands/ion.js

@@ -35,8 +35,9 @@ function showHelp() {
     ${cyan('phewsh ion')}              ${sage('open phewsh.com/ion')}
     ${cyan('phewsh ion open')}         ${sage('same')}
 
-  ${sage('Make this machine available')}
-    ${cyan('phewsh ion serve')}        ${sage('start the local worker bridge')}
+  ${sage('Make this machine available — the two-step')}
+    ${cyan('phewsh project add')}      ${sage('1. register this repo (once per repo)')}
+    ${cyan('phewsh serve')}            ${sage('2. one worker serves the whole machine')}
     ${cyan('phewsh ion status')}       ${sage('show bridge/project/task status')}
 
   ${sage('Use the existing task loop')}
@@ -92,7 +93,7 @@ module.exports = async function run() {
     if (sub === 'serve' || sub === 'worker') return runServe(rest);
     if (sub === 'status') {
       console.log(`\n  ${cream('Ion room:')} ${cyan(WEB_URL)}`);
-      console.log(`  ${sage('Local worker:')} ${cream('phewsh ion serve')}`);
+      console.log(`  ${sage('Local worker:')} ${cream('phewsh project add')} ${sage('(once per repo), then')} ${cream('phewsh serve')}`);
       return runTask(['list']);
     }
     if (sub === 'task' || sub === 'tasks') return runTask(rest.length ? rest : ['list']);

package/lib/packs.js

@@ -44,6 +44,22 @@ const PACKS = {
     targets: ['CLAUDE.md', 'AGENTS.md'],
     content: KARPATHY_GUIDELINES,
   },
+  'boat-to-shore': {
+    kind: 'linked',
+    title: 'Boat to Shore — completion-loop skill',
+    desc: 'A tested Claude skill for recurring autonomous improvement sessions (run it via /loop): one verified slice per session, state-file continuity across resets, branch discipline, honest handoffs. Moves a repo from unfinished (Water) to shippable (Shore) to excellent (Mountain). Pairs with a plan made at phewsh.com/intent.',
+    source: 'github.com/cleverIdeaz/phewsh-cli (skills/boat-to-shore)',
+    license: 'MIT',
+    install: 'mkdir -p ~/.claude/skills/boat-to-shore && curl -fsSL https://raw.githubusercontent.com/cleverIdeaz/phewsh-cli/main/skills/boat-to-shore/SKILL.md -o ~/.claude/skills/boat-to-shore/SKILL.md',
+  },
+  'portfolio-boat-loop': {
+    kind: 'linked',
+    title: 'Portfolio Boat Loop — multi-repo loop router',
+    desc: 'The layer above boat-to-shore: decides which repo gets the next session window, rotates by Water→Shore→Mountain, tracks the whole portfolio in one state file, and keeps loop state from bloating. The repo loop moves one boat; this decides which boat gets the next tide.',
+    source: 'github.com/cleverIdeaz/phewsh-cli (skills/portfolio-boat-loop)',
+    license: 'MIT',
+    install: 'mkdir -p ~/.claude/skills/portfolio-boat-loop && curl -fsSL https://raw.githubusercontent.com/cleverIdeaz/phewsh-cli/main/skills/portfolio-boat-loop/SKILL.md -o ~/.claude/skills/portfolio-boat-loop/SKILL.md',
+  },
   gsd: {
     kind: 'linked',
     title: 'GSD — Get Shit Done',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "phewsh",
-  "version": "0.15.80",
-  "description": "One mission. Many AI tools. No lost context. PHEWSH keeps your project's intent, decisions, and working context aligned across Claude Code, Codex, Cursor, Gemini and your team — so the next AI knows what the last one learned.",
+  "version": "0.15.82",
+  "description": "One mission. Many AI tools. No lost context. PHEWSH keeps your project's intent, decisions, and working context aligned across Claude Code, Codex, Cursor, Gemini and your team \u2014 so the next AI knows what the last one learned.",
   "bin": {
     "phewsh": "bin/phewsh.js"
   },
@@ -10,6 +10,7 @@
     "commands/",
     "lib/",
     "mcp/",
+    "skills/",
     "README.md",
     "SECURITY.md",
     "LICENSE"
@@ -54,4 +55,4 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
   }
-}
+}

package/skills/boat-to-shore/SKILL v1.md

@@ -0,0 +1,62 @@
+---
+name: boat-to-shore
+description: Use when running recurring autonomous improvement sessions on a repository (e.g. via /loop or a scheduled continuation), when resuming work after a session reset or context loss, or when moving a repo from unfinished/TODO-riddled toward shippable without a human available to answer questions.
+---
+
+# Boat to Shore
+
+## Overview
+
+Move the repo from **Water** (broken, unclear, unfinished) to **Shore** (runs, builds, core flow works, verified) to **Mountain** (polished, tested, documented, launch-ready). One verified slice per session. The state file is the anchor: every session starts by reading it and ends by updating it. The loop's output is not just code — it's a repo the next session can pick up cold.
+
+**Violating the letter of these rules is violating the spirit of the loop.** A high-quality sprawl is still a sprawl.
+
+## Session sequence
+
+1. **Rehydrate.** Read `./.agent/boat-loop.md`, `git status`/recent log, and README. If the repo has a `.intent/` directory (phewsh), treat it as the project plan and read it first. If the state file is missing, create it: run a first-pass diagnostic (stack, how to run/build/test, TODO/FIXME/placeholder sweep, run the checks) plus a blind-spot pass (unknown unknowns, risky assumptions, map-vs-territory disagreements — the plan is the map, the repo is the territory; when they disagree, trust the territory and log the disagreement).
+2. **Choose ONE slice.** If the state file already names a Current Session Goal or Next best loop, that is your slice — do not renegotiate it. Otherwise pick the single highest-leverage goal completable and verifiable this session. A slice is one *goal*, not everything that happens to live in the same files. Priority order: runs → builds → core flow works → user understands it → verified → survives real use → feels excellent → next agent moves faster.
+3. **Branch.** `git checkout -b boat/<slug>-<date>` (or reuse the existing boat branch). Never work directly on main/master.
+4. **Implement small.** Smallest coherent change that completes the slice. Check `git diff` as you go. No unrelated refactors, no rewrites without proving the current architecture can't support the goal.
+5. **Verify.** Strongest feasible ladder: typecheck/lint → tests → build → local smoke → browser/Playwright when UI behavior matters. A claim without a run check is not a result.
+6. **Push harder — inside the slice's blast radius.** After it works: is there an error/empty/loading state, a locking test, or a doc line attached to *this* slice? Do the best one. Adjacent backlog items are the next loop's slices, not this one's dessert.
+7. **Update state.** Append to `.agent/boat-loop.md` (never overwrite the log): what changed, what was verified, current status (Water/Shore/Mountain), and **Next best loop**. Log non-obvious decisions and deviations from the plan in `.agent/implementation-notes.md` (discovery → decision → why → risk → verification).
+8. **Report** using the template below.
+
+## Hard rules
+
+- **One slice per session.** Even if the backlog looks small enough to finish. Finishing the backlog in one sitting produces an unreviewable diff and an untestable session.
+- **Never commit to main/master.** Branch, always, even in tiny repos.
+- **"Done" is not a state.** There are only Water, Shore, Mountain — and Mountain still gets a "Next best loop" (a strategic push, or an explicit recommendation to the human to stop the loop). If you wrote "Done", replace it.
+- **Verify before claiming.** If a check fails and is out of scope, document it precisely — don't hide it.
+- **Blocked?** Make the safest reversible assumption, log it, keep moving. Ask a question only if it would change architecture, data model, auth, pricing, or ownership — never "should I continue?"
+- **Bounded research.** Competitor/reference scan at most once per repo, only after Shore, output = implementation moves (not a report), stored in `.agent/competitors.md`.
+
+| Rationalization | Reality |
+|---|---|
+| "The remaining items are small — I'll just do them all" | That's three sessions' worth of review risk in one diff. One slice. |
+| "It's all in the same two tiny files — one coherent slice" | File adjacency doesn't merge goals. The state file's scope instruction wins. |
+| "This repo is tiny, master is fine" | The loop runs unattended. Branches are the undo button. |
+| "Everything on the list is fixed — mark it Done" | The list was the map. Re-inspect the territory: embarrassment test, then write the next loop. |
+| "It seems finished" | Prove it: run the checks, load the UI, read it as a stranger. |
+| "Pushing harder means doing more items" | Pushing harder means making *this* slice excellent. |
+
+## Red flags — stop and re-read Hard rules
+
+Working on main · second backlog item in one session · "Done" anywhere · claiming results with no check run · state file unchanged at session end · asking the human what to do next.
+
+## Session report template
+
+```
+## Session Result — <repo> — <date>
+Status: Water | Shore | Mountain
+### Slice completed
+### Verified (commands run + results)
+### Deviations & assumptions (map vs territory)
+### Remaining risks
+### Next best loop
+### Quiz for the human (3 Qs: main improvement? riskiest assumption? what should the next loop do?)
+```
+
+## The mountain question
+
+Before ending any Shore/Mountain session: *if a real user, a buyer, and a future maintainer saw this tomorrow, what would embarrass us?* The highest-impact answer is the next loop's slice.

package/skills/boat-to-shore/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: boat-to-shore
+description: Use when running recurring autonomous improvement sessions on a repository (e.g. via /loop or a scheduled continuation), when resuming work after a session reset or context loss, or when moving a repo from unfinished/TODO-riddled toward shippable without a human available to answer questions.
+---
+
+# Boat to Shore
+
+## Overview
+
+Move the repo from **Water** (broken, unclear, unfinished) to **Shore** (runs, builds, core flow works, verified) to **Mountain** (polished, tested, documented, launch-ready). One verified slice per session. The state file is the anchor: every session starts by reading it and ends by updating it. The loop's output is not just code — it's a repo the next session can pick up cold.
+
+**Violating the letter of these rules is violating the spirit of the loop.** A high-quality sprawl is still a sprawl.
+
+## Session sequence
+
+1. **Rehydrate.** Read `./.agent/boat-loop.md`, `git status`/recent log, and README. If the repo has a `.intent/` directory (phewsh), treat it as the project plan and read it first. If the state file is missing, create it: run a first-pass diagnostic (stack, how to run/build/test, TODO/FIXME/placeholder sweep, run the checks) plus a blind-spot pass (unknown unknowns, risky assumptions, map-vs-territory disagreements — the plan is the map, the repo is the territory; when they disagree, trust the territory and log the disagreement).
+2. **Choose ONE slice.** If the state file already names a Current Session Goal or Next best loop, that is your slice — do not renegotiate it. Otherwise pick the single highest-leverage goal completable and verifiable this session. A slice is one *goal*, not everything that happens to live in the same files. Priority order: runs → builds → core flow works → user understands it → verified → survives real use → feels excellent → next agent moves faster.
+3. **Branch.** `git checkout -b boat/<slug>-<date>` (or reuse the existing boat branch). Never work directly on main/master.
+4. **Implement small.** Smallest coherent change that completes the slice. Check `git diff` as you go. No unrelated refactors, no rewrites without proving the current architecture can't support the goal.
+5. **Verify.** Strongest feasible ladder: typecheck/lint → tests → build → local smoke → browser/Playwright when UI behavior matters. A claim without a run check is not a result.
+6. **Push harder — inside the slice's blast radius.** After it works: is there an error/empty/loading state, a locking test, or a doc line attached to *this* slice? Do the best one. Adjacent backlog items are the next loop's slices, not this one's dessert.
+7. **Update state.** Append to `.agent/boat-loop.md` (never overwrite the log): what changed, what was verified, current status (Water/Shore/Mountain), and **Next best loop**. Log non-obvious decisions and deviations from the plan in `.agent/implementation-notes.md` (discovery → decision → why → risk → verification).
+8. **Report** using the template below.
+
+## Hard rules
+
+- **One slice per session.** Even if the backlog looks small enough to finish. Finishing the backlog in one sitting produces an unreviewable diff and an untestable session.
+- **Never commit to main/master.** Branch, always, even in tiny repos.
+- **"Done" is not a state.** There are only Water, Shore, Mountain — and Mountain still gets a "Next best loop" (a strategic push, or an explicit recommendation to the human to stop the loop). If you wrote "Done", replace it.
+- **Verify before claiming.** If a check fails and is out of scope, document it precisely — don't hide it.
+- **Blocked?** Make the safest reversible assumption, log it, keep moving. Ask a question only if it would change architecture, data model, auth, pricing, or ownership — never "should I continue?"
+- **Bounded research.** Competitor/reference scan at most once per repo, only after Shore, output = implementation moves (not a report), stored in `.agent/competitors.md`.
+
+| Rationalization | Reality |
+|---|---|
+| "The remaining items are small — I'll just do them all" | That's three sessions' worth of review risk in one diff. One slice. |
+| "It's all in the same two tiny files — one coherent slice" | File adjacency doesn't merge goals. The state file's scope instruction wins. |
+| "This repo is tiny, master is fine" | The loop runs unattended. Branches are the undo button. |
+| "Everything on the list is fixed — mark it Done" | The list was the map. Re-inspect the territory: embarrassment test, then write the next loop. |
+| "It seems finished" | Prove it: run the checks, load the UI, read it as a stranger. |
+| "Pushing harder means doing more items" | Pushing harder means making *this* slice excellent. |
+
+## Red flags — stop and re-read Hard rules
+
+Working on main · second backlog item in one session · "Done" anywhere · claiming results with no check run · state file unchanged at session end · asking the human what to do next.
+
+## Session report template
+
+```
+## Session Result — <repo> — <date>
+Status: Water | Shore | Mountain
+### Slice completed
+### Verified (commands run + results)
+### Deviations & assumptions (map vs territory)
+### Remaining risks
+### Next best loop
+### Quiz for the human (3 Qs: main improvement? riskiest assumption? what should the next loop do?)
+```
+
+## The mountain question
+
+Before ending any Shore/Mountain session: *if a real user, a buyer, and a future maintainer saw this tomorrow, what would embarrass us?* The highest-impact answer is the next loop's slice.

package/skills/portfolio-boat-loop/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: portfolio-boat-loop
+description: Use when managing recurring autonomous improvement sessions across MULTIPLE repositories — deciding which repo gets the next session window, rotating attention, tracking Water/Shore/Mountain across a portfolio, or coordinating loop work across accounts/machines. For the work inside one repo, use boat-to-shore.
+---
+
+# Portfolio Boat Loop
+
+## Overview
+
+The repo loop moves one boat; this loop decides which boat gets the next tide. One session window = one repo selection + one boat-to-shore session in it + portfolio bookkeeping. **The files are the memory; the chat is disposable** — every window must be decidable cold from `portfolio-state.md` alone.
+
+**REQUIRED SUB-SKILL:** boat-to-shore governs the work inside the chosen repo.
+
+## The portfolio session — what it is
+
+1. **Read** `~/boat-loop/portfolio-state.md`. If missing, create it from the template below by inspecting each repo's `.agent/boat-loop.md` (and `.intent/` if present).
+2. **Set the mode** from the table: any repo Water → **Stabilize**; all runnable but some short of Shore → **Complete**; all Shore/Mountain → **Mountain Push**.
+3. **Select ONE repo**: lowest status first (Water < Shore < Mountain); tie-break by clearest Next-best-loop, then oldest Last-session. Skip a repo whose `boat/*` branch is unreviewed when another candidate exists — unless you select it *to review/merge that branch as the session's slice* (review is a valid slice). Parked repos are never selected.
+4. **Run the repo session** in the chosen repo using boat-to-shore, exactly as that skill prescribes.
+5. **Write back exactly two files**: the chosen repo's `.agent/boat-loop.md` (the repo session does this) and `portfolio-state.md` (status, branch, last-session timestamp, slice, verification result, next best loop, review-needed flag). Unchosen repos' state files are the *next* session's anchors — leave them untouched.
+6. **Report** with the template below.
+
+## Portfolio state template
+
+```
+# Portfolio Boat Loop
+Mode: Stabilize | Complete | Mountain Push
+Last consolidation: <date>
+
+| Repo | Path | Status | Branch | Last session | Slice done | Next best loop | Review needed |
+|---|---|---|---|---|---|---|---|
+
+## Shared notes (direction, design language, cross-repo decisions, blockers)
+```
+
+## Maintenance rules
+
+- **Consolidation**: every ~3 sessions per repo, or when a repo's `.agent/boat-loop.md` gets hard to scan, spend that repo's window consolidating instead of building — keep status, verified facts, risks, branch info, next loop; move old detail to `.agent/archive/`; target under 150 lines. Archive, don't delete.
+- **Cold starts**: when a chat bloats, ensure the state files are current, then start fresh and rehydrate from files — never drag an old chat forward.
+- **Parallel accounts/machines**: fine only on different repos, or clearly separate branches with non-overlapping scopes. Record who-is-where in Shared notes.
+- **No portfolio "done"**: statuses are Water/Shore/Mountain/Parked. When everything is Mountain, start another rotation on "what would make this repo more valuable, credible, usable, or sellable?" — or recommend Parking to the human.
+
+## Report template
+
+```
+## Portfolio Window — <date>
+Mode: <mode>  ·  Repo chosen: <repo> — <one-line why>
+### Session result (from boat-to-shore report)
+### Portfolio table (current)
+### Human review needed
+### Next scheduled repo + why
+```