@getpipher/workspace 0.2.0 → 0.3.1

package/README.md

@@ -1,13 +1,13 @@
 # @getpipher/workspace
 
-repo catch-up, AGENTS.md initialization, ecosystem context-file architecture, doc organization, planning sync, and cross-session handoff. Built for [pi](https://github.com/earendil-works/pi-coding-agent).
+repo catch-up, AGENTS.md initialization, ecosystem context-file architecture, doc organization, planning sync, and cross-session handoff. Host-neutral — works in [pi](https://github.com/earendil-works/pi-coding-agent), Claude Code, and any AGENTS.md-aware coding agent.
 
 ## Skills
 
 | Skill | Purpose |
 |---|---|
 | `workspace-catch-up` | Show repo mission, tech stack, current state, last 5 commits, analyze uncommitted files |
-| `workspace-ecosystem-claude` | Create ecosystem-wide context-file architecture (AGENTS.md | CLAUDE.md) for multi-repo orgs |
+| `workspace-ecosystem-agents` | Create ecosystem-wide context-file architecture (AGENTS.md | CLAUDE.md) for multi-repo orgs |
 | `workspace-init-agents` | Create or improve a project AGENTS.md with intelligent codebase analysis (host-neutral) |
 | `workspace-organize-docs` | Intelligently analyze and organize all .md files in a repository (read-only advisor) |
 | `workspace-planning-sync` | Analyze repo and provide intelligent planning documentation suggestions (read-only) |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getpipher/workspace",
-  "version": "0.2.0",
-  "description": "Workspace & context-management skills for pi \u2014 repo catch-up, AGENTS.md initialization, ecosystem context-file architecture, doc organization, planning sync, and cross-session handoff.",
+  "version": "0.3.1",
+  "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",
     "pi-skills",

package/skills/catch-up/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: workspace-catch-up
 description: Show repo mission, tech stack, current state, last 5 commits, and analyze uncommitted files
-allowed-tools: ["bash", "read", "write", "edit"]
 ---
 
 # Catch-Up: Complete Repository Context
@@ -12,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
@@ -54,7 +55,7 @@ Let me gather complete context for you:
   - First paragraph after title
   - Features/Goals section
   - Tech Stack section
-- If no docs found: Infer from file structure and suggest creating an `AGENTS.md` (try `/workspace:init-agents`)
+- If no docs found: Infer from file structure and suggest creating an `AGENTS.md` (try the `workspace-init-agents` skill)
 
 ### Smart File Analysis Patterns
 
@@ -148,7 +149,7 @@ Let me gather complete context for you:
 
 ```bash
 # Get complete context when returning to a project
-/catch-up
+Invoke with: workspace-catch-up
 
 # Use when:
 # - You just opened the project after time away

package/skills/{ecosystem-claude → ecosystem-agents}/SKILL.md

@@ -1,15 +1,13 @@
 ---
-name: workspace-ecosystem-claude
+name: workspace-ecosystem-agents
 description: Create ecosystem-wide context-file architecture (AGENTS.md | CLAUDE.md) for multi-repo organizations. Host-neutral — works for Claude Code, Pi, and any AGENTS.md-aware agent.
-argument-hint: "[org-name]"
-allowed-tools: ["bash", "read", "write", "edit"]
 ---
 
 # Ecosystem Context-File Architecture (AGENTS.md)
 
 Bismillah! I'll analyze your organization's repositories and help set up an ecosystem-wide **context-file architecture** — the cross-tool standard where `AGENTS.md` is the primary file (read by Claude Code, Pi, and any `AGENTS.md`-aware agent) and `CLAUDE.md` is Claude Code's legacy name for the same file.
 
-> **Hub / satellite model.** One **ecosystem hub** `AGENTS.md` (usually in your org's main/overview repo) carries org-wide context: mission, repo index, cross-repo standards. Each member repo gets a lightweight **satellite** `AGENTS.md` that links to the hub and holds only repo-specific content. An agent landing in any repo can orient itself: the satellite points to the hub, the hub indexes everything. This mirrors the `/workspace:init-agents` hub/satellite pattern at org scale.
+> **Hub / satellite model.** One **ecosystem hub** `AGENTS.md` (usually in your org's main/overview repo) carries org-wide context: mission, repo index, cross-repo standards. Each member repo gets a lightweight **satellite** `AGENTS.md` that links to the hub and holds only repo-specific content. An agent landing in any repo can orient itself: the satellite points to the hub, the hub indexes everything. This mirrors the `workspace-init-agents` hub/satellite pattern at org scale.
 
 **This command is always safe to run.** It detects first, shows analysis, and asks before any changes.
 
@@ -24,7 +22,7 @@ Bismillah! I'll analyze your organization's repositories and help set up an ecos
 - **`AGENTS.md` exists** → analyze and build on it.
 - **Neither exists** → create from scratch (Step 4+).
 
-When migrating, rephrase any CC-flavored framing host-neutrally ("guidance to Claude Code" → "guidance for AI agents"). This is the same migration the `/workspace:init-agents` skill performs per-repo; run it across every member repo as you wire the ecosystem.
+When migrating, rephrase any CC-flavored framing host-neutrally ("guidance to Claude Code" → "guidance for AI agents"). This is the same migration the `workspace-init-agents` skill performs per-repo; run it across every member repo as you wire the ecosystem.
 
 ---
 

package/skills/init-agents/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: workspace-init-agents
 description: Create or improve a project AGENTS.md with intelligent codebase analysis. Host-neutral satellite context file read by Claude Code, Pi, and any AGENTS.md-aware agent.
-argument-hint: ""
-allowed-tools: ["bash", "read", "write", "edit"]
 ---
 
 # AGENTS.md Initialization (project satellite)
 
 Bismillah! I'll analyze this codebase and create (or improve) a project `AGENTS.md` — the cross-tool context file that Claude Code, Pi, and any `AGENTS.md`-aware agent read on startup.
 
-> **Hub / satellite model.** This skill generates a **satellite**: a host-neutral file describing *this repo*. It extends — never duplicates — the **global hub** (`~/.claude/CLAUDE.md` / `~/.pi/agent/AGENTS.md`), which already carries persona, dev standards, git conventions, secret rules, etc. A satellite holds **only project-specific** content (overview, architecture, commands, conventions, gotchas). No identity, no generic standards, no host-specific tooling — those belong to the hub.
+> **Hub / satellite model.** This skill generates a **satellite**: a host-neutral file describing *this repo*. It extends — never duplicates — the **global hub** (your global agent context file), which already carries persona, dev standards, git conventions, secret rules, etc. A satellite holds **only project-specific** content (overview, architecture, commands, conventions, gotchas). No identity, no generic standards, no host-specific tooling — those belong to the hub.
 
 ---
 
@@ -94,7 +92,7 @@ Information that requires reading **multiple files** to understand:
 Use this structure (omit sections if not applicable):
 
 ```
-<!-- Satellite context file — extends the global hub (~/.claude/CLAUDE.md | ~/.pi/agent/AGENTS.md). Host-neutral; project-specific only. Do not duplicate hub standards here. -->
+<!-- Satellite context file — extends your global agent context file (the hub). Host-neutral; project-specific only. Do not duplicate hub standards here. -->
 
 # {Project Name}
 

package/skills/organize-docs/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: workspace-organize-docs
 description: Intelligently analyze and organize all .md files in repository (read-only advisor)
-argument-hint: "[--apply] [--dry-run] [--backup] [--config CONFIG_FILE]"
-allowed-tools: ["bash", "read", "write", "edit"]
 ---
 
 # Documentation Organization Advisor v2
 
 Bismillah! I'll analyze all markdown files in your repository and propose an intelligent organization structure.
 
-Arguments provided: $ARGUMENTS
+Arguments: [--apply] [--dry-run] [--backup] [--config FILE]
 
 ---
 
@@ -226,7 +224,8 @@ DRY_RUN=true
 CREATE_BACKUP=true
 CONFIG_FILE=".docs-organize.yml"
 
-for arg in $ARGUMENTS; do
+ARGS="<flags from the invocation arguments>"
+for arg in $ARGS; do
   case $arg in
     --apply)
       APPLY_CHANGES=true
@@ -510,8 +509,7 @@ Files already in docs/: 3
 Scattered files: 15
   ⚠️  tmux/TMUX_GUIDE.md
   ⚠️  zsh/SHELL_CONFIG.md
-  ⚠️  claude/.claude/COMMANDS.md
-  ⚠️  scripts/SCRIPTS_README.md
+  ⚠️  dotfiles/agent/COMMANDS.md
   ... [11 more files]
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -546,8 +544,7 @@ Updates needed: 12 internal links
   │
   └── 📁 reference/ (4 files) - Information-oriented
       ├── api.md               ← REORGANIZE: ./docs/API.md
-      ├── commands.md          ← MOVE: ./claude/.claude/COMMANDS.md
-      ├── scripts.md           ← MOVE: ./scripts/SCRIPTS_README.md
+      ├── commands.md          ← MOVE: ./dotfiles/agent/COMMANDS.md
       └── ...
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -692,8 +689,7 @@ When you need technical specifications.
 - **Reference**: Technical descriptions
 
 Last updated: 2025-10-14
-Generated by: `/docs:organize` command
-```
+Generated by: the workspace-organize-docs skill
 
 ### For API-First Structure:
 ```markdown
@@ -728,8 +724,7 @@ Complete API documentation for [Project Name].
 ---
 
 Last updated: 2025-10-14
-Generated by: `/docs:organize` command
-```
+Generated by: the workspace-organize-docs skill
 
 ---
 
@@ -823,10 +818,9 @@ HTML: <a href="file.md">text</a>
 
 ```bash
 # Generate configuration template
-/docs:organize --generate-config divio
-/docs:organize --generate-config microsoft
-/docs:organize --generate-config api-first
-```
+workspace-organize-docs --generate-config divio
+workspace-organize-docs --generate-config microsoft
+workspace-organize-docs --generate-config api-first
 
 Creates `.docs-organize.yml` with sensible defaults for chosen structure.
 
@@ -847,9 +841,9 @@ Creates `.docs-organize.yml` with sensible defaults for chosen structure.
 
 ## Integration with Workflow
 
-✅ **Complements `/planning:sync`:**
-- `/planning:sync` detects scattered docs → suggests `/docs:organize`
-- `/docs:organize` fixes organization → keeps planning docs synced
+✅ **Complements `workspace-planning-sync`:**
+- `workspace-planning-sync` detects scattered docs → suggests `workspace-organize-docs`
+- `workspace-organize-docs` fixes organization → keeps planning docs synced
 
 ✅ **Context-File Alignment (AGENTS.md):**
 - "Clarify Before Acting" - Multiple confirmation points
@@ -869,28 +863,28 @@ Creates `.docs-organize.yml` with sensible defaults for chosen structure.
 
 ```bash
 # Dry run with auto-detection (safe, read-only analysis)
-/docs:organize
+workspace-organize-docs
 
 # Dry run with specific config
-/docs:organize --config .docs-organize.yml
+workspace-organize-docs --config .docs-organize.yml
 
 # Generate configuration template
-/docs:organize --generate-config divio
+workspace-organize-docs --generate-config divio
 
 # Apply reorganization (with confirmation)
-/docs:organize --apply
+workspace-organize-docs --apply
 
 # Apply with backup (recommended)
-/docs:organize --apply --backup
+workspace-organize-docs --apply --backup
 
 # Apply without backup (use with caution)
-/docs:organize --apply --no-backup
+workspace-organize-docs --apply --no-backup
 
 # Try different structure type
-/docs:organize --structure microsoft --dry-run
+workspace-organize-docs --structure microsoft --dry-run
 
 # Export report without applying
-/docs:organize --export docs-plan.md
+workspace-organize-docs --export docs-plan.md
 ```
 
 ---

package/skills/planning-sync/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: workspace-planning-sync
 description: Analyze repo and provide intelligent planning documentation suggestions (read-only)
-argument-hint: "[--force] [--type=<repo-type>] [--export]"
-allowed-tools: ["bash", "read", "write", "edit"]
 ---
 
 # Adaptive Planning Advisor (Read-Only Analysis)
 
 Bismillah! I'll intelligently analyze your codebase and provide comprehensive planning documentation suggestions without modifying any files.
 
-Arguments provided: $ARGUMENTS
+Arguments: [--force] [--type=<repo-type>] [--export]
 
 ---
 
@@ -48,7 +46,7 @@ This command adapts to different repository types:
 
 ## Using with Thinking Mode
 
-When executing with **mode: think** or **mode: think hard**, I will:
+When executing (use an extended-reasoning mode if your environment provides one), I will:
 
 - **Repository Type Intelligence**: Deep analysis to detect repo purpose
 - **Context-Aware Suggestions**: Recommendations matching your workflow
@@ -72,7 +70,8 @@ FORCE_MODE=false
 OVERRIDE_TYPE=""
 EXPORT_MODE=false
 
-for arg in $ARGUMENTS; do
+ARGS="<flags from the invocation arguments>"
+for arg in $ARGS; do
   case $arg in
     --force)
       FORCE_MODE=true
@@ -313,7 +312,7 @@ esac
 **Search Patterns:**
 ```
 PRD: PRD.md, REQUIREMENTS.md, PRODUCT_REQUIREMENTS.md
-Locations: /, /docs/, /planning/, /.github/   (also check host context dir: ~/.claude/ or ~/.pi/agent/ for global notes)
+Locations: /, /docs/, /planning/, /.github/   (also check your global agent context dir if known, e.g. via $AGENT_CONTEXT_DIR, for global notes)
 
 Execution: EXECUTION.md, EXECUTION_PLAN.md, IMPLEMENTATION.md, PROGRESS.md
 Locations: /, /docs/, /planning/
@@ -364,7 +363,7 @@ SCATTERED_COUNT=$(echo "$SCATTERED" | grep -c "\.md$" || echo "0")
 - Inconsistent location patterns
 - No clear docs/ directory structure
 
-**Note for report:** If scattered documentation is detected (>3 .md files outside docs/), mention this in the recommendations section and suggest using `/docs:organize` command for comprehensive reorganization.
+**Note for report:** If scattered documentation is detected (>3 .md files outside docs/), mention this in the recommendations section and suggest using the `workspace-organize-docs` skill for comprehensive reorganization.
 
 ---
 
@@ -487,7 +486,7 @@ Analysis: 2025-10-13 09:30 UTC
 Searched locations:
   - /docs/PRD.md ❌
   - /PRD.md ❌
-  - /.claude/PRD.md ❌
+  - /<agent-context-dir>/PRD.md ❌
   - /EXECUTION.md ❌
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -516,9 +515,9 @@ Tool 2: Shell Configuration (Zsh)
 ├─ Config Area 2.3: Functions ⏳
 │  └─ Settings: Custom functions (planned)
 
-Tool 3: Claude Code Configuration
+Tool 3: AI Assistant Configuration
 ├─ Status: 55% Complete (6/11 config areas)
-├─ Config Area 3.1: Slash Commands ✅
+├─ Config Area 3.1: Custom Commands ✅
 │  └─ Settings: 15 commands across 6 categories
 ├─ Config Area 3.2: Global Config ✅
 │  └─ Settings: context-file (AGENTS.md) workflow
@@ -529,7 +528,7 @@ Evidence Files:
   - tmux/.tmux.conf (234 lines)
   - tmux/plugins/ (12 plugins installed)
   - zsh/.zshrc (456 lines)
-  - claude/.claude/commands/ (15 slash commands)
+  - agent/commands/ (15 commands)
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 💡 RECOMMENDATIONS
@@ -571,7 +570,7 @@ Evidence Files:
        TODO: Categorize and document purpose
 
    🟡 MEDIUM PRIORITY (Consider Adding):
-     - Claude Code hooks not configured
+     - Agent hooks not configured
        Suggested: Pre-commit formatting hook
 
      - Shell functions lacking documentation
@@ -589,7 +588,7 @@ Evidence Files:
    **Scattered documentation locations:**
      - tmux/TMUX_SETUP.md
      - zsh/ALIASES_GUIDE.md
-     - claude/COMMANDS_REFERENCE.md
+     - agent/COMMANDS_REFERENCE.md
      - [5 more files in various directories]
 
    **Recommended structure:**
@@ -604,7 +603,7 @@ Evidence Files:
      - Better documentation navigation
 
    **How to fix:**
-     Run: `/docs:organize` for intelligent reorganization suggestions
+     Run: `workspace-organize-docs` for intelligent reorganization suggestions
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝 PROPOSED STRUCTURE PREVIEW
@@ -725,23 +724,23 @@ Here's what I suggest for docs/CONFIG_PLAN.md:
 
 ---
 
-## Tool 3: Claude Code Configuration
+## Tool 3: AI Assistant Configuration
 **Purpose:** AI-powered development assistant setup
 **Status:** 55% Complete (6/11 areas)
 **Priority:** High
 
-### Config Area 3.1: Slash Commands ✅
-**What:** Custom Claude Code commands
+### Config Area 3.1: Custom Commands ✅
+**What:** Custom assistant commands
 **Why:** Automate common workflows
 **Implementation:**
-  - Command directory: claude/.claude/commands/
+  - Command directory: agent/commands/
   - 15 commands across 6 categories:
     - git/ (7 commands): commit, create-pr, merge-pr, etc.
     - init/ (2 commands): repo initialization
-    - planning/ (1 command): planning:sync
+    - planning/ (1 command): planning-sync
     - quality/ (2 commands): lint-fix, type-check
     - superteam/ (2 commands): bounty, hackathon
-    - meta/ (1 command): make-slash
+    - meta/ (1 command): make-command
 **Status:** Complete
 **Tested:** ✅ All commands functional
 
@@ -749,17 +748,17 @@ Here's what I suggest for docs/CONFIG_PLAN.md:
 **What:** CLAUDE.md/AGENTS.md workflow preferences
 **Why:** Consistent AI assistance behavior
 **Implementation:**
-  - Global config: host context file (`~/.claude/CLAUDE.md` for CC, `~/.pi/agent/AGENTS.md` for pi — whichever you maintain as your global agent config)
+  - Global config: the global agent context file (whichever you maintain)
   - Workflow definitions
   - Code standards and preferences
 **Status:** Complete
 **Maintained:** Regularly updated
 
 ### Config Area 3.3: Hooks ⏳
-**What:** Automated Claude Code triggers
+**What:** Automated agent triggers
 **Why:** Pre-commit checks, auto-formatting
 **Implementation:**
-  - Hook directory: .claude/hooks/ (not created)
+  - Hook directory: agent/hooks/ (not created)
   - Pre-commit: Planned linting/formatting
   - Post-write: Planned test triggers
 **Status:** Not started
@@ -767,7 +766,7 @@ Here's what I suggest for docs/CONFIG_PLAN.md:
 **Suggested Hooks:**
   - pre-commit: Run linters before commit
   - on-file-write: Trigger related tests
-**Next Step:** Research Claude Code hook capabilities
+**Next Step:** Research agent hook capabilities
 
 ---
 
@@ -779,7 +778,7 @@ Here's what I suggest for docs/CONFIG_PLAN.md:
 | 🔴 HIGH | Shell | Organize aliases | 1h | Medium |
 | 🟡 MED | Tmux | TPM plugin system | 1.5h | Medium |
 | 🟡 MED | Shell | Document functions | 2h | Medium |
-| 🟡 MED | Claude | Configure hooks | 3h | High |
+| 🟡 MED | Assistant | Configure hooks | 3h | High |
 | 🟢 LOW | All | Plugin docs | 4h | Low |
 
 ## Next Session Goals
@@ -791,7 +790,7 @@ Here's what I suggest for docs/CONFIG_PLAN.md:
 
 2. **Short-term (This Month):**
    - Set up TPM for tmux plugins
-   - Configure Claude Code hooks
+   - Configure agent hooks
    - Document all configuration choices
 
 3. **Long-term (This Quarter):**
@@ -967,7 +966,7 @@ Found 12 discrepancies across documentation:
    To prevent this:
    - Sync docs weekly (every Monday)
    - Update EXECUTION.md after each PR merge
-   - Run /planning:sync before major releases
+   - Run workspace-planning-sync before major releases
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝 PROPOSED UPDATES PREVIEW
@@ -1198,7 +1197,7 @@ echo "1. Review drafts: cd /tmp/planning-sync-drafts && ls -la"
 echo "2. Edit if needed: open /tmp/planning-sync-drafts/CONFIG_PLAN.md"
 echo "3. Copy to repo: cp /tmp/planning-sync-drafts/*.md docs/"
 echo ""
-echo "Or run: /planning:sync --apply-drafts"
+echo "Or run: workspace-planning-sync --apply-drafts"
 ```
 
 ### Option 2: Show Detailed Analysis

package/skills/session-handoff/SKILL.md

@@ -1,25 +1,26 @@
 ---
 name: workspace-session-handoff
-description: Use when ending a session and work needs to continue in a new session (Claude Code or Pi). Creates a self-contained starter prompt with full context so the next session picks up seamlessly. Host-neutral — the handoff bridges sessions across either host (shared workspace + vault).
-allowed-tools: ["bash", "read", "write", "edit"]
+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).
 ---
 
 # Session Handoff
 
 Create a starter prompt file that a fresh session can use to continue work without context loss.
 
-> **Host-neutral.** This skill works the same in Claude Code and Pi. The handoff file lives in the shared `$HANDOFF_VAULT/{project}/` vault (default `$HANDOFF_VAULT`=`~/.local/handoffs` — a local directory; override via the `HANDOFF_VAULT` env var to point at your own private/synced vault), so a session in either host can write it and the next session (same host or the other) can resume — they share the workspace and the vault. Don't assume the next session runs in the same host as this one.
+> **Host-neutral.** This skill works the same in any harness. The handoff file lives in the shared `$HANDOFF_VAULT/{project}/` vault (default `$HANDOFF_VAULT`=`~/.local/handoffs` — a local directory; override via the `HANDOFF_VAULT` env var to point at your own private/synced vault), so a session in any host can write it and the next session (same host or another) can resume — they share the workspace and the vault. Don't assume the next session runs in the same host as this one.
 
 ## When to Use
 
 - End of a long session with pending tasks
-- Before a context-compaction / session switch (CC: `/compact`; pi: `/reload` or restart) when work remains
+- Before a context-compaction / session switch (your host's context-compaction or session-restart mechanism) when work remains
 - When context window is getting full and work remains
 - User says "save progress", "wrap up", "continue later", "new session"
 
 ## 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`).
 
@@ -44,7 +45,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.
@@ -62,7 +63,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.
@@ -106,7 +107,7 @@ Structure (the `## Progress Table` section is inserted only if Steps 2–3 produ
 
 ## Starter Prompt
 
-Copy-paste this into a new session (CC or pi):
+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:}
@@ -170,9 +171,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
 
@@ -196,7 +210,7 @@ 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.