@getpipher/workspace 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getpipher/workspace",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Workspace & context-management skills — repo catch-up, AGENTS.md initialization, ecosystem context-file architecture, doc organization, planning sync, and cross-session handoff. Host-neutral: any AGENTS.md-aware coding agent.",
   "keywords": [
     "pi-package",

package/skills/catch-up/SKILL.md

@@ -11,6 +11,8 @@ Bismillah! Let me show you where we are and what we just did.
 
 Let me gather complete context for you:
 
+0. **Handoff check** — If `$HANDOFF_VAULT/{project}/` (`$HANDOFF_VAULT` defaults to `~/.local/handoffs`) contains session handoffs, surface the newest one (`ls "$HANDOFF_VAULT"/{project}/session-handoff-*.md | sort -r | head -1`) and offer to render its starter prompt before gathering git state.
+
 1. **Extract Mission & Purpose**
    - Read the project context file — `AGENTS.md` (or `CLAUDE.md`, CC's legacy name) — first, for Repository Overview and Tech Stack
    - Fallback to README.md if no context file exists

package/skills/session-handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workspace-session-handoff
-description: Use when ending a session and work needs to continue in a new session (any host). Creates a self-contained starter prompt with full context so the next session picks up seamlessly. Host-neutral — the handoff bridges sessions across hosts (shared workspace + vault).
+description: Use when ending a session and work needs to continue in a new session (any host). Creates a self-contained starter prompt with full context so the next session picks up seamlessly. Host-neutral — the handoff bridges sessions across hosts (shared workspace + vault). Also use when the session relied on skills — audits, TDD, debugging, hunt or release workflows — that follow-up sessions must keep invoking: skill usage must survive the session boundary by exact name.
 ---
 
 # Session Handoff
@@ -18,7 +18,9 @@ Create a starter prompt file that a fresh session can use to continue work witho
 
 ## Output
 
-Write to: `$HANDOFF_VAULT/{project}/session-handoff-{YYYY-MM-DD}.md` (default `$HANDOFF_VAULT`=`~/.local/handoffs`)
+Write to: `$HANDOFF_VAULT/{project}/session-handoff-{YYYY-MM-DD}.md` (default `$HANDOFF_VAULT`=`~/.local/handoffs` — the canonical vault). `$HANDOFF_VAULT` is set machine-globally in the shell profile, never per-session. Durability/backup of the vault is an out-of-band concern (mirror/sync jobs) — never a reason to write elsewhere.
+
+`{project}` = the working directory's repo/bucket folder name (for bug-bounty hunts: the per-target hunt folder name `<platform>-<program>`). Flat, single segment — never a nested path.
 
 If a handoff file already exists for today, append a letter suffix (e.g., `-b`, `-c`).
 
@@ -36,6 +38,7 @@ Collect from the current conversation (do NOT re-read files you already have con
 6. **File paths touched** — specific files modified (helps the next session navigate)
 7. **CI/deploy state** — are all repos green? anything deploying?
 8. **VPS/infra state** — any server-side changes made (env vars, configs, deploys)
+9. **Skills to carry into the next session** — every skill this session invoked, plus every skill the pending work requires, by exact invocable name (e.g., `web2-audit-semantics`, `systematic-debugging`), one line each on when/why for this handoff's pending work. The name must survive verbatim: the next session matches skills by description against fresh context, and a paraphrased handoff ("use the standard audit lens") loses the trigger vocabulary — only the exact name reliably fires it. If the session never named a skill explicitly, infer from the pending work using your installed-skills list. If genuinely no skill applies, record none — never pad with decorative names.
 
 ### Step 2: Decide if a progress table is needed
 
@@ -43,7 +46,7 @@ A **progress table** sits near the top of the handoff (between the header block
 
 **Generate a progress table when ANY apply:**
 
-1. **Predecessor handoff has one** — `ls -t "$HANDOFF_VAULT"/{project}/session-handoff-*.md | head -1` contains `## Progress Table`. Chain consistency > per-session re-evaluation.
+1. **Predecessor handoff has one** — `ls "$HANDOFF_VAULT"/{project}/session-handoff-*.md | sort -r | head -1` contains `## Progress Table`. Chain consistency > per-session re-evaluation. (Reverse-lexicographic sort, not mtime — the `YYYY-MM-DD[-letter]` naming is lexicographically ordered; mtime lies on restore/copy/sync.)
 2. **User explicitly requested** — prompt contains "MUST include progress table" or "include the progress table".
 3. **Work has numbered discrete units** — multi-phase plan with slices/tasks (e.g., "Slice 5.7 done, next 5.8"), or stacked PR chain where order matters.
 4. **More than 3 PRs/issues stacked across sessions** — flat bullet list becomes unscannable.
@@ -61,7 +64,7 @@ A **progress table** sits near the top of the handoff (between the header block
 1. **Find the most recent predecessor handoff** for this project:
 
    ```bash
-   ls -t "$HANDOFF_VAULT"/{project}/session-handoff-*.md 2>/dev/null | head -1
+   ls "$HANDOFF_VAULT"/{project}/session-handoff-*.md 2>/dev/null | sort -r | head -1
    ```
 
    Locate its `## Progress Table` section.
@@ -86,7 +89,7 @@ Adapt column names to the project's vocabulary ("Milestone" instead of "Phase",
 
 ### Step 4: Write the Handoff File
 
-Structure (the `## Progress Table` section is inserted only if Steps 2–3 produced one):
+Structure (conditional sections: `## Progress Table` per Steps 2–3; FIRST-ACTIONS inside the starter prompt per (progress table and/or Step 1 item 9); "Skills to invoke" inside the starter prompt per Step 1 item 9):
 
 ```markdown
 # {Project} — Session Handoff ({date}-{letter} — {one-line headline})
@@ -108,11 +111,26 @@ Structure (the `## Progress Table` section is inserted only if Steps 2–3 produ
 Copy-paste this into a new session:
 
 \```
-{OPENER-ECHO — include ONLY when a progress table was generated (Steps 2–3); omit entirely otherwise. Embed the table verbatim so it travels with the prompt even if the user pastes only this block:}
+{FIRST-ACTIONS — include ONLY when a progress table was generated (Steps 2–3) and/or Step 1 item 9 listed at least one skill; omit entirely when neither applies. Compose it from the parts below that apply, numbered sequentially with no gaps:}
+
+FIRST — before reading any plan, touching any code, or taking any other action — do these, in order:
+
+{only when a progress table exists:}
+1. Render the progress table below back to me verbatim, under the heading "## Resuming — where we left off".
+{end only-when}
+
+{only when skills are listed:}
+{next sequential number}. Invoke every skill named under "Skills to invoke" below — read and follow each before starting the task work.
+{end only-when}
+
+{full progress table copied verbatim from the ## Progress Table section above, including the footer summary line — only when a progress table exists}
+
+{--- — include ONLY together with the SKILL INVOKE section below; omit when it is omitted}
 
-FIRST — before reading any plan, touching any code, or taking any other action — render the progress table below back to me verbatim, under the heading "## Resuming — where we left off". Then continue with the task.
+{SKILL INVOKE — include ONLY when Step 1 item 9 listed at least one skill; omit entirely otherwise. Embed the list verbatim so it travels with the prompt even if the user pastes only this block:}
 
-{full progress table copied verbatim from the ## Progress Table section above, including the footer summary line}
+Skills to invoke:
+- `{skill-name}` — {one line: when/why for THIS handoff's pending work}
 
 ---
 
@@ -169,9 +187,22 @@ pbpaste  # macOS — expected: the handoff path
 
 If the clipboard tool isn't available (e.g., remote SSH session without clipboard forwarding), skip silently — don't treat it as an error. The Confirm step still shows the path as text.
 
-### Step 6: Update MEMORY.md
+### Step 6: Update the project chain index
+
+Maintain `$HANDOFF_VAULT/{project}/MEMORY.md` — the ONLY hand-maintained index:
+
+```markdown
+# {Project} — Handoff Chain Index
+
+|Date|Handoff|State at handoff|
+|---|---|---|
+|{date}|{filename}|{one-line state}|
+
+## Standing context
+- {spec of record / conventions / frozen facts — items that outlive any single handoff}
+```
 
-Add a pointer to the handoff file and update any stale progress entries.
+Add the new row at the bottom (newest last); update stale state lines while there. The global vault-level `MEMORY.md` (if present) is GENERATED by tooling — never hand-edit it.
 
 ### Step 7: Confirm
 
@@ -195,7 +226,8 @@ The new session performs the mirror action on arrival: the starter prompt (Step
 - **No secrets in the prompt** — API keys, passwords, keypairs stay out
 - **Specific over general** — "execute Task 3 in docs/plans/foo.md" beats "continue the work"
 - **Include gotchas** — anything surprising or non-obvious that would trip up a fresh session
-- **Private vault only** — `$HANDOFF_VAULT` (default `~/.local/handoffs`) should be a private/encrypted location, safe for strategy context. Override `$HANDOFF_VAULT` to your own private vault (e.g. an iCloud-synced or encrypted dir).
+- **Private vault only** — the vault must be a private, local, strategy-safe location. `~/.local/handoffs` is the canonical home; durability is provided by an out-of-band mirror, not by writers choosing alternate locations.
 - **Progress table is part of the chain contract** — once a chain starts using a progress table, every handoff in the chain MUST include + update it. Skipping breaks scannability for the next session and forces a rebuild from prior handoffs.
 - **Progress table echo is the closer, not the full handoff** — Step 7's inline table is a snapshot for the current chat. The handoff file (`.md`) is the durable artifact. Don't paraphrase or trim the table when echoing — render it verbatim.
-- **Opener-echo mirrors the closer** — when a progress table exists, the starter prompt's FIRST instruction MUST be "render the table before doing anything." Embed the table inside the starter-prompt block (Step 4), not as a file reference, so it survives the user pasting the prompt alone. The fresh session renders it as its first action — a "where we left off" snapshot symmetric to Step 7's "where we ended" closer. No table generated → no opener-echo.
+- **FIRST-ACTIONS mirror the closer** — when a progress table exists, the starter prompt's ordered list MUST lead with "render the table before doing anything" (item 1 of FIRST-ACTIONS). Embed the table inside the starter-prompt block (Step 4), not as a file reference, so it survives the user pasting the prompt alone. The fresh session renders it as its first action — a "where we left off" snapshot symmetric to Step 7's "where we ended" closer. No table and no skills-to-invoke → no FIRST-ACTIONS block at all; a skills-only handoff still leads with FIRST (invoke is item 1).
+- **Skill continuity travels by exact name** — every skill from Step 1 item 9 MUST appear in the starter prompt's "Skills to invoke" list, exact invocable name verbatim. A paraphrase ("use the standard audit lens") doesn't reliably trigger the next session's skill matching, and continuation phrasing loses the "starting X" vocabulary a fresh session needs to match descriptions. No applicable skill → omit the list entirely; decorative padding erodes the contract.