agileflow 2.76.0 → 2.78.0

package/src/core/commands/session/resume.md

@@ -1,6 +1,19 @@
 ---
 description: Pick a session to switch to or resume
 argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:resume - Switch between parallel sessions"
+    - "Lists all registered sessions (active and inactive) with status"
+    - "User selects which session to resume"
+    - "Returns `cd` command to switch to selected session"
+    - "Formats nickname/branch with activity status (Active now / inactive)"
+    - "Marks current session with '(current)' label"
+  state_fields:
+    - current_session
+    - all_sessions
+    - user_selection
 ---
 
 # /agileflow:session:resume
@@ -89,3 +102,156 @@ Run /agileflow:session:new to create a new parallel workspace.
 - `/agileflow:session:new` - Create new session
 - `/agileflow:session:status` - Quick status view
 - `/agileflow:session:end` - End current session
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## ⚠️ COMPACT SUMMARY - /agileflow:session:resume IS ACTIVE
+
+**CRITICAL**: This command is the primary way to **switch between parallel sessions**. User selects, you display the cd command.
+
+---
+
+### 🚨 RULE #1: ALWAYS USE AskUserQuestion
+
+**NEVER just describe the sessions.** Build an AskUserQuestion with:
+- One option per session
+- Current session marked "(current)"
+- Active sessions marked "Active now"
+- Inactive sessions show "last active: {time}"
+- "Create new session" option at bottom
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which session would you like to resume?",
+  "header": "Sessions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Session 1: main (current)",
+     "description": "US-0042: User Auth API │ Active now │ /home/user/project"},
+    {"label": "Session 2: \"auth\"",
+     "description": "US-0038: Fix Login │ Active now │ ../project-auth"},
+    {"label": "Session 3: feature/payments",
+     "description": "US-0051 │ Inactive (1 day ago) │ ../project-payments"},
+    {"label": "Create new session",
+     "description": "Start a fresh parallel workspace"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+### 🚨 RULE #2: HANDLE EACH SELECTION CASE
+
+**If user selects current session:**
+```
+You're already in Session 1!
+```
+
+**If user selects different session:**
+```
+To resume Session 2 "auth":
+
+┌─────────────────────────────────────────────────────────┐
+│   cd ../project-auth && claude --resume                 │
+└─────────────────────────────────────────────────────────┘
+
+Session info:
+  Branch: session-2
+  Story:  US-0038 (in-progress)
+```
+
+**If user selects "Create new session":**
+```
+Run /agileflow:session:new to create a new parallel workspace.
+```
+
+---
+
+### 🚨 RULE #3: FORMATTING LABELS & DESCRIPTIONS
+
+**Label format (session option):**
+- Session with nickname: `Session {id}: "{nickname}"`
+- Session with branch: `Session {id}: {branch}`
+- Current session: append ` (current)`
+
+**Description format:**
+- Include story ID if available: `US-0042`
+- Include status: `Active now` OR `Inactive (N days ago)`
+- Include relative path: `../project-auth`
+- Format: `{STORY_ID} │ {STATUS} │ {PATH}`
+
+---
+
+### 🚨 RULE #4: SESSION DATA STRUCTURE
+
+Sessions from `session-manager.js list --json` contain:
+```json
+{
+  "id": 1,
+  "path": "/home/user/project",
+  "branch": "main",
+  "nickname": null,
+  "status": "active",
+  "is_current": true,
+  "is_main": true,
+  "created": "2025-12-20T10:00:00Z",
+  "last_active": "2025-12-20T10:30:00Z"
+}
+```
+
+Use these fields to build readable labels.
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `.agileflow/sessions/registry.json` | Master list of all sessions |
+| `.agileflow/sessions/{id}.lock` | Lock file = session is active |
+| `.agileflow/scripts/session-manager.js` | Script providing session data |
+
+---
+
+### WORKFLOW
+
+1. **Get sessions** → `node .agileflow/scripts/session-manager.js list --json`
+2. **Parse JSON** → Extract id, branch, nickname, status, path
+3. **Build options** → Create readable labels with status
+4. **Show AskUserQuestion** → Let user select
+5. **Handle selection** → Show cd command or appropriate response
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Just list sessions without AskUserQuestion
+❌ Format label as "session_1_main" (use readable format)
+❌ Show path as absolute when relative is shorter
+❌ Don't mark current session with "(current)"
+❌ Don't show "Active now" status for active sessions
+
+### DO THESE INSTEAD
+
+✅ ALWAYS use AskUserQuestion with user options
+✅ Format labels as "Session 1: main (current)"
+✅ Show relative paths (../project-auth)
+✅ Mark current session clearly
+✅ Show activity status (Active now / Inactive Xd ago)
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:session:resume` IS ACTIVE
+- ALWAYS use AskUserQuestion to let user select
+- Format labels clearly: `Session {id}: {nickname/branch} {(current)}`
+- Show status in description: `Active now` OR `Inactive (N days ago)`
+- Handle each case: current / different / create new
+- Return cd command when user selects different session
+
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/session/status.md

@@ -1,6 +1,19 @@
 ---
 description: View current session state and activity
 argument-hint: (no arguments)
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:status - Display all sessions in table"
+    - "Does NOT prompt for action (read-only display)"
+    - "Shows current session, then table of other sessions"
+    - "Marks active sessions with ● bullet, inactive with ○"
+    - "Returns session count and active count"
+  state_fields:
+    - current_session
+    - all_sessions
+    - active_count
+    - total_count
 ---
 
 # /agileflow:session:status
@@ -63,3 +76,156 @@ Run /agileflow:session:new to create a parallel workspace.
 - `/agileflow:session:new` - Create new session
 - `/agileflow:session:resume` - Switch sessions
 - `/agileflow:session:end` - End current session
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## ⚠️ COMPACT SUMMARY - /agileflow:session:status IS ACTIVE
+
+**CRITICAL**: This command displays read-only status. It NEVER prompts for action - just shows information.
+
+---
+
+### 🚨 RULE #1: READ-ONLY DISPLAY (NO USER PROMPTS)
+
+**NEVER use AskUserQuestion or present options.** This command is informational only.
+
+| Command | Has Prompts? | Use Case |
+|---------|-------------|----------|
+| `/agileflow:session:status` | ❌ No | Quick info view |
+| `/agileflow:session:resume` | ✅ Yes | Switch sessions |
+| `/agileflow:session:new` | ✅ Yes | Create session |
+| `/agileflow:session:end` | ✅ Yes | End session |
+
+---
+
+### 🚨 RULE #2: DISPLAY FORMAT
+
+**Structure:**
+1. Header with emoji: `📊 Session Status`
+2. Current session info (highlighted)
+3. Table of other sessions
+4. Summary line: `Total: X sessions │ Y active`
+5. Quick actions (optional)
+
+**Example:**
+```
+📊 Session Status
+
+Current: Session 1 (main)
+         Branch: main │ Story: US-0042 │ Active
+
+Other Sessions:
+┌─────┬──────────────────┬─────────────┬────────────┐
+│  #  │ Name/Branch      │ Story       │ Status     │
+├─────┼──────────────────┼─────────────┼────────────┤
+│  2  │ "auth"           │ US-0038     │ ● Active   │
+│  3  │ feature/payments │ -           │ ○ Inactive │
+└─────┴──────────────────┴─────────────┴────────────┘
+
+Total: 3 sessions │ 2 active
+```
+
+---
+
+### 🚨 RULE #3: STATUS BULLETS
+
+- **● Active** - Session has lock file (Claude process running)
+- **○ Inactive** - No lock file (can be resumed)
+
+---
+
+### 🚨 RULE #4: SHOW QUICK ACTIONS (OPTIONAL)
+
+After the table, show optional quick actions info:
+```
+💡 Quick actions:
+   /agileflow:session:new    - Create parallel session
+   /agileflow:session:resume - Switch to another session
+   /agileflow:session:end    - End current session
+```
+
+---
+
+### 🚨 RULE #5: HANDLE EDGE CASES
+
+**If no sessions exist:**
+```
+📊 Session Status
+
+No sessions registered yet. You're in the main project directory.
+Run /agileflow:session:new to create a parallel workspace.
+```
+
+**If only current session:**
+```
+📊 Session Status
+
+Current: Session 1 (main)
+         Branch: main │ Active
+
+This is your only session. Use /agileflow:session:new to create more.
+```
+
+---
+
+### FORMATTING RULES
+
+| Element | Format | Example |
+|---------|--------|---------|
+| Session name | Branch or nickname | `main` or `"auth"` |
+| Story ID | US-#### or dash | `US-0042` or `-` |
+| Status | ● Active or ○ Inactive | `● Active` |
+| Session reference | Session {id} | `Session 1` |
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `.agileflow/sessions/registry.json` | Master list of sessions |
+| `.agileflow/sessions/{id}.lock` | Lock file marks session active |
+| `.agileflow/scripts/session-manager.js` | Data source |
+
+---
+
+### WORKFLOW
+
+1. **Get sessions** → `node .agileflow/scripts/session-manager.js list --json`
+2. **Parse JSON** → Extract sessions, identify current
+3. **Build display** → Format header, current session, table
+4. **Show summary** → Total and active counts
+5. **Optionally show** → Quick actions reference
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Use AskUserQuestion to prompt for action
+❌ Show "Resume Session 2?" or similar prompts
+❌ Use table without proper formatting
+❌ Show path in table (too much info)
+❌ Skip summary line showing counts
+
+### DO THESE INSTEAD
+
+✅ Display as read-only information
+✅ Use ● and ○ bullets for status
+✅ Format table with proper borders
+✅ Show summary with counts
+✅ Optionally show quick actions for reference
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:session:status` IS ACTIVE
+- NEVER prompt for action (read-only display)
+- Format: header + current session + table + summary
+- Use ● for active, ○ for inactive
+- Show session counts in summary
+- Optionally show quick actions reference
+
+<!-- COMPACT_SUMMARY_END -->

package/src/core/commands/skill/create.md

@@ -1,6 +1,21 @@
 ---
 description: Generate a custom skill with web research, cookbook pattern, and MCP integration
 argument-hint: [SKILL_NAME] (optional)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:skill:create - Generates custom research-backed skills"
+    - "MUST enter Plan Mode FIRST to research THREE sources: web docs, local docs, codebase patterns"
+    - "MUST output to .claude/skills/<skill-name>/ (directly usable by Claude Code)"
+    - "MUST include references.md linking web docs, local docs, and codebase patterns"
+    - "MUST use cookbook pattern for complex skills (2+ use cases)"
+    - "NEVER copy entire docs - reference URLs instead"
+    - "CRITICAL: Ask for approval of plan before generating skill files"
+  state_fields:
+    - skill_name
+    - research_sources
+    - use_cases_count
+    - mcp_server_found
 ---
 
 # /agileflow:skill:create
@@ -11,27 +26,67 @@ Generate dynamic, research-backed skills that combine web documentation, user's
 
 <!-- COMPACT_SUMMARY_START -->
 
-## Compact Summary
+## 🚨 COMPACT SUMMARY - /agileflow:skill:create IS ACTIVE
 
-**ROLE**: Skill Generator - creates custom skills via comprehensive research.
+**CRITICAL**: This command creates custom skills by researching THREE sources and building research-backed workflows.
 
-### Critical Rules
-1. **ALWAYS use Plan Mode** - Enter plan mode to explore before generating
-2. **Research THREE sources**: Web docs, user's local docs, user's codebase
-3. **Link to external docs** - Reference URLs, don't copy entire docs
-4. **Reference local patterns** - Point to user's existing practices and code
-5. **Use cookbook pattern** for multi-use-case skills
-6. **Output to `.claude/skills/<skill-name>/`** - directly usable by Claude Code
-
-### Generated Skill Structure
+### 🚨 RULE #1: Enter Plan Mode First
+ALWAYS start with Plan Mode to explore before generating ANY skill files.
 ```
-.claude/skills/<skill-name>/
-├── SKILL.md              # Pivot file with references to all sources
-├── cookbook/             # Per-use-case workflows
-├── references.md         # Links to web docs + local docs + code patterns
-├── tools/                # Executable scripts (optional)
-└── .mcp.json             # MCP server config (if applicable)
+EnterPlanMode
 ```
+This prevents wasted generations and gets user approval on research findings.
+
+### 🚨 RULE #2: Research Three Sources
+In Plan Mode, research and collect (DON'T generate):
+1. **Web docs**: Official documentation URLs, API reference URLs, best practices links
+2. **Local docs**: Files in `docs/02-practices/`, `docs/04-architecture/`, `docs/03-decisions/`
+3. **Codebase patterns**: Existing code using Glob/Grep to find patterns
+
+### 🚨 RULE #3: Link, Never Copy
+- Link to external docs with URLs (don't copy entire docs)
+- Point to local files that exist (don't reference user's docs/02-practices/ directly)
+- Show codebase patterns with file locations and code snippets
+
+### 🚨 RULE #4: Output Structure
+Output ALWAYS goes to `.claude/skills/<skill-name>/` with:
+- `SKILL.md` (main file with activation triggers and cookbook references)
+- `references.md` (all documentation links)
+- `cookbook/` directory (one .md per use case)
+- `.mcp.json` (if MCP server found)
+
+### 🚨 RULE #5: Cookbook Pattern
+- **Simple skill** (1 use case): SKILL.md only
+- **Complex skill** (2+ use cases): SKILL.md + cookbook/ directory with per-use-case files
+
+### 🚨 RULE #6: Get Approval Before Writing
+After research and plan creation:
+1. Show plan findings to user
+2. Ask for approval
+3. Exit Plan Mode with approval
+4. THEN write the skill files
+
+### Critical Files Generated
+| File | Purpose | Required? |
+|------|---------|-----------|
+| SKILL.md | Main skill file with activation triggers | Yes |
+| references.md | Links to all web/local/codebase docs | Yes |
+| cookbook/<use-case>.md | Per-use-case workflow | If 2+ cases |
+| .mcp.json | MCP server configuration | If found |
+
+### Anti-Patterns
+- ❌ DON'T write skill files without Plan Mode approval
+- ❌ DON'T copy entire external documentation
+- ❌ DON'T reference docs/02-practices/ that user hasn't created
+- ❌ DON'T skip cookbook pattern for complex skills
+- ❌ DON'T forget references.md (critical for user context)
+
+### REMEMBER AFTER COMPACTION
+- Skill creation is 5 phases: Requirements → Plan Mode Research → Get Approval → Generate → Write Files
+- Plan Mode research finds URLs and local patterns (don't generate from plan)
+- User must approve plan before ANY files are written
+- Complex skills need cookbook/ for each use case
+- references.md is the pivot file linking all sources
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -564,3 +619,46 @@ If validation fails:
 # With skill name hint
 /agileflow:skill:create supabase-swift
 ```
+
+---
+
+## POST-CREATION ACTIONS
+
+After successfully creating a skill, offer next steps:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Skill '<skill-name>' created! What would you like to do next?",
+  "header": "Next Steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Test the skill (Recommended)", "description": "Verify the skill works correctly"},
+    {"label": "View all skills", "description": "See full skill inventory with /agileflow:skill:list"},
+    {"label": "Create another skill", "description": "Build another custom skill"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Test the skill"**:
+- Run `/agileflow:skill:test SKILL=<skill-name>`
+- Provide sample input scenarios
+- Verify output matches expectations
+
+**If "View all skills"**:
+- Run `/agileflow:skill:list`
+
+**If "Create another skill"**:
+- Re-run `/agileflow:skill:create`
+
+---
+
+## Related Commands
+
+- `/agileflow:skill:list` - View all installed skills
+- `/agileflow:skill:test` - Test a skill with sample inputs
+- `/agileflow:skill:edit` - Modify an existing skill
+- `/agileflow:skill:delete` - Remove a skill
+- `/agileflow:skill:upgrade` - Update skill with new patterns

package/src/core/commands/skill/delete.md

@@ -1,6 +1,19 @@
 ---
 description: Remove an installed skill from .claude/skills/
 argument-hint: [SKILL_NAME] (optional)
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:skill:delete - Removes installed skills"
+    - "MUST list available skills if SKILL_NAME not provided"
+    - "MUST show exactly what will be deleted (tree view of files)"
+    - "MUST ask for explicit confirmation before deletion (no undo)"
+    - "MUST offer backup option before deletion"
+    - "MUST create backup in .claude/skills-backup/ if requested"
+    - "NEVER delete without explicit user confirmation"
+  state_fields:
+    - selected_skill_for_deletion
+    - backup_created
 ---
 
 # /agileflow:skill:delete
@@ -9,6 +22,110 @@ Remove a skill from `.claude/skills/`.
 
 ---
 
+<!-- COMPACT_SUMMARY_START -->
+
+## 🚨 COMPACT SUMMARY - /agileflow:skill:delete IS ACTIVE
+
+**CRITICAL**: This command deletes skills with full safety features and backup options.
+
+### 🚨 RULE #1: Select Skill
+If SKILL_NAME not provided:
+```bash
+ls -d .claude/skills/*/ | xargs -I {} basename {}
+```
+Show options and ask user which to delete.
+
+### 🚨 RULE #2: Show Exactly What Will Be Deleted
+Display complete tree view:
+```
+⚠️  About to delete: skill-name
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+This will permanently remove:
+  .claude/skills/skill-name/
+  ├── SKILL.md
+  ├── references.md
+  ├── cookbook/
+  │   ├── use-case-1.md
+  │   └── use-case-2.md
+  └── .mcp.json
+
+Total: 5 files in 2 directories
+```
+
+### 🚨 RULE #3: Ask for Confirmation
+Multiple confirmation levels:
+1. **First ask**: "Are you sure?" (show file tree)
+2. **Options**:
+   - "Yes, delete permanently" - Proceed with deletion
+   - "No, keep it" - Cancel
+   - "Export first" - Create backup first
+
+### 🚨 RULE #4: Handle Backup Request
+If user chooses "Export first":
+```bash
+mkdir -p .claude/skills-backup/
+cp -r .claude/skills/<skill> .claude/skills-backup/<skill>-$(date +%Y%m%d-%H%M%S)/
+```
+Show backup location, then return to confirmation.
+
+### 🚨 RULE #5: Execute Deletion
+After confirmed deletion:
+```bash
+rm -rf .claude/skills/<skill>/
+```
+Show confirmation message with success emoji.
+
+### 🚨 RULE #6: Offer Next Actions
+After deletion, ask:
+```
+What would you like to do next?
+- Delete another skill
+- Create new skill
+- List remaining skills
+- Done
+```
+
+### Safety Features
+| Feature | Purpose |
+|---------|---------|
+| Show file tree | User sees EXACTLY what's deleted |
+| Explicit confirmation | Can't accidentally delete |
+| Backup option | Can recover if needed |
+| One at a time | No batch delete accidents |
+| Timestamp in backup | Identify which version backed up |
+
+### Backup Location
+```
+.claude/skills-backup/<skill>-<YYYYMMDD-HHMMSS>/
+```
+
+Example:
+```
+.claude/skills-backup/supabase-swift-20251227-143052/
+├── SKILL.md
+├── references.md
+├── cookbook/
+└── .mcp.json
+```
+
+### Anti-Patterns
+- ❌ DON'T delete without showing file tree
+- ❌ DON'T proceed without explicit confirmation
+- ❌ DON'T skip backup option offer
+- ❌ DON'T allow batch/wildcard deletes (one at a time)
+- ❌ DON'T delete without confirming again if backup created
+
+### REMEMBER AFTER COMPACTION
+- Delete is always: Select → Show tree → Ask confirm → [Backup if requested] → Delete → Show next actions
+- NEVER delete without explicit confirmation
+- Always offer backup option before deletion
+- Backup goes to .claude/skills-backup/ with timestamp
+- One skill at a time (no batch delete)
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
 ## Workflow
 
 ### STEP 1: Select skill to delete