agileflow 2.77.0 → 2.79.0

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

@@ -1,6 +1,20 @@
 ---
 description: View past session history and metrics
 argument-hint: "[DAYS=7|30|90|all]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:history - Show sessions filtered by age"
+    - "Accepts DAYS argument: 7, 30, 90, or all (default: 30)"
+    - "Filters sessions by created timestamp"
+    - "Shows table with creation date, branch, story, status"
+    - "Read-only display (no prompts)"
+    - "Shows summary: total sessions, active count, inactive count"
+  state_fields:
+    - timeframe_days
+    - filtered_sessions
+    - active_count
+    - inactive_count
 ---
 
 # /agileflow:session:history
@@ -71,3 +85,199 @@ Try /agileflow:session:history DAYS=all to see all sessions.
 
 - `/agileflow:session:status` - Current status
 - `/agileflow:session:resume` - Switch sessions
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## ⚠️ COMPACT SUMMARY - /agileflow:session:history IS ACTIVE
+
+**CRITICAL**: This command shows historical session data. It NEVER prompts for action - read-only display only.
+
+---
+
+### 🚨 RULE #1: PARSE DAYS ARGUMENT
+
+Valid values: `7`, `30`, `90`, `all`
+
+```
+/agileflow:session:history DAYS=7    → Last 7 days
+/agileflow:session:history DAYS=30   → Last 30 days (default)
+/agileflow:session:history DAYS=90   → Last 90 days
+/agileflow:session:history DAYS=all  → All sessions
+/agileflow:session:history           → Default to 30 days
+```
+
+---
+
+### 🚨 RULE #2: FILTER BY CREATED TIMESTAMP
+
+After getting all sessions, filter by their `created` timestamp:
+```javascript
+const cutoffDate = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
+filtered = sessions.filter(s => new Date(s.created) >= cutoffDate);
+```
+
+For `DAYS=all`, include all sessions.
+
+---
+
+### 🚨 RULE #3: DISPLAY FORMAT
+
+**Structure:**
+1. Header with emoji: `📜 Session History (Last {DAYS} days)`
+2. Table with columns: #, Created, Name/Branch, Story, Status
+3. Summary: `Summary: X sessions │ Y active │ Z inactive`
+4. Tips (optional)
+
+**Example:**
+```
+📜 Session History (Last 30 days)
+
+┌─────┬────────────┬──────────────────┬─────────────┬────────────┐
+│  #  │ Created    │ Name/Branch      │ Story       │ Status     │
+├─────┼────────────┼──────────────────┼─────────────┼────────────┤
+│  1  │ Dec 20     │ main             │ -           │ ● Active   │
+│  2  │ Dec 22     │ "auth"           │ US-0042     │ ● Active   │
+│  3  │ Dec 23     │ feature/payments │ US-0051     │ ○ Inactive │
+│  4  │ Dec 25     │ "bugfix"         │ US-0038     │ ○ Inactive │
+└─────┴────────────┴──────────────────┴─────────────┴────────────┘
+
+Summary: 4 sessions │ 2 active │ 2 inactive
+```
+
+---
+
+### 🚨 RULE #4: DATE FORMATTING
+
+Show dates in compact form:
+- Format: `Dec 20` (month + day)
+- No year needed (assumed current year or implied by context)
+- Makes table compact
+
+---
+
+### 🚨 RULE #5: READ-ONLY DISPLAY (NO PROMPTS)
+
+**NEVER use AskUserQuestion.** This command is informational only.
+
+For user actions, show tips:
+```
+💡 Tips:
+   • /agileflow:session:new to create a new session
+   • /agileflow:session:delete {id} to remove old sessions
+   • Inactive sessions can be resumed with /agileflow:session:resume
+```
+
+---
+
+### 🚨 RULE #6: HANDLE EMPTY RESULTS
+
+If no sessions in timeframe:
+```
+📜 Session History
+
+No sessions found in the last {DAYS} days.
+
+Try /agileflow:session:history DAYS=all to see all sessions.
+```
+
+---
+
+### FORMATTING RULES
+
+| Element | Format | Example |
+|---------|--------|---------|
+| Date | Month + day | `Dec 20` |
+| Session name | Nickname or branch | `"auth"` or `feature/payments` |
+| Story | US-#### or dash | `US-0042` or `-` |
+| Status | ● Active or ○ Inactive | `● Active` |
+| Summary | Count format | `4 sessions │ 2 active │ 2 inactive` |
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `.agileflow/sessions/registry.json` | All sessions with created timestamps |
+| `.agileflow/scripts/session-manager.js` | Data source via list --json |
+
+---
+
+### WORKFLOW
+
+1. **Parse DAYS argument** → Default to 30 if not provided
+2. **Get all sessions** → `session-manager.js list --json`
+3. **Filter by date** → Compare created timestamp to cutoff
+4. **Count active/inactive** → Check status field
+5. **Build table** → Format with proper columns
+6. **Show summary** → Total and active counts
+7. **Optionally show** → Tips for actions
+
+---
+
+### SESSION DATA STRUCTURE
+
+From `session-manager.js list --json`:
+```json
+{
+  "id": 1,
+  "branch": "main",
+  "nickname": null,
+  "status": "active",
+  "created": "2025-12-20T10:00:00Z",
+  "last_active": "2025-12-20T10:30:00Z"
+}
+```
+
+Use `created` for filtering.
+
+---
+
+### ARGUMENT VALIDATION
+
+```
+DAYS=7    ✅ Valid
+DAYS=30   ✅ Valid
+DAYS=90   ✅ Valid
+DAYS=all  ✅ Valid
+DAYS=14   ❌ Invalid (suggest 7, 30, 90, or all)
+DAYS=xyz  ❌ Invalid (suggest 7, 30, 90, or all)
+(no arg)  ✅ Valid (default to 30)
+```
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Use AskUserQuestion to prompt for action
+❌ Show "Delete old sessions?" or similar prompts
+❌ Accept arbitrary DAYS values (only 7, 30, 90, all)
+❌ Show full ISO timestamp (use compact date)
+❌ Show absolute paths (too much info)
+❌ Forget summary line with counts
+
+### DO THESE INSTEAD
+
+✅ Display as read-only information
+✅ Use ● and ○ bullets for status
+✅ Accept only: 7, 30, 90, all
+✅ Format dates compactly: Dec 20
+✅ Show summary with active/inactive counts
+✅ Optionally show tips for related commands
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:session:history` IS ACTIVE
+- Accepts DAYS: 7, 30, 90, all (default: 30)
+- Filter by created timestamp
+- Format: header + table + summary
+- Use ● for active, ○ for inactive
+- NEVER prompt for action (read-only)
+- Show date as "Dec 20" (compact format)
+- Optionally show tips
+
+<!-- COMPACT_SUMMARY_END -->

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

@@ -1,6 +1,19 @@
 ---
 description: Initialize session harness with test verification
 argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:init - Initialize session tracking"
+    - "Creates `.agileflow/sessions/` directory and `registry.json` if missing"
+    - "Registers current directory as active session with lock file"
+    - "Runs automatically via SessionStart hook on session begin"
+    - "Safe to run multiple times (idempotent operation)"
+    - "If registry.json exists, validates schema before use"
+  state_fields:
+    - session_id
+    - registry_status
+    - active_session_count
 ---
 
 # /agileflow:session:init
@@ -82,3 +95,106 @@ If session is already registered:
 
 - `/agileflow:session:status` - View all sessions
 - `/agileflow:session:new` - Create parallel session
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## ⚠️ COMPACT SUMMARY - /agileflow:session:init IS ACTIVE
+
+**CRITICAL**: This command sets up session tracking infrastructure. It MUST run before any session management features work.
+
+---
+
+### 🚨 RULE #1: IDEMPOTENT OPERATION
+
+This command is **safe to run multiple times**. It:
+- Creates `.agileflow/sessions/` if missing
+- Creates `registry.json` with schema if missing
+- Registers current directory if not already registered
+- Updates lock file if already registered
+
+**No data is lost, no conflicts occur on repeated runs.**
+
+---
+
+### 🚨 RULE #2: AUTOMATIC INVOCATION
+
+This command runs automatically via **SessionStart hook**. You typically don't call it manually unless:
+- Debugging session tracking
+- Setting up manually without hook
+- Recovering from corrupted session state
+
+---
+
+### 🚨 RULE #3: REGISTRY SCHEMA
+
+The generated `registry.json` has this structure:
+```json
+{
+  "version": "1.0",
+  "sessions": [
+    {
+      "id": 1,
+      "path": "/home/user/project",
+      "branch": "main",
+      "created": "2025-12-20T10:00:00Z",
+      "last_active": "2025-12-20T10:30:00Z",
+      "is_main": true,
+      "nickname": null,
+      "status": "active"
+    }
+  ]
+}
+```
+
+---
+
+### 🚨 RULE #4: LOCK FILE MANAGEMENT
+
+Session tracking uses lock files at `.agileflow/sessions/{id}.lock`:
+- Lock file = session is **active** (has running Claude process)
+- No lock file = session is **inactive** (can be resumed)
+- Lock files are created on init, removed on `/agileflow:session:end`
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `.agileflow/sessions/` | Session directory (created by init) |
+| `.agileflow/sessions/registry.json` | Master registry of all sessions |
+| `.agileflow/sessions/{id}.lock` | Lock file marking session active |
+| `.agileflow/scripts/session-manager.js` | Script that does the work |
+
+---
+
+### TYPICAL WORKFLOW
+
+1. **First time in project**:
+   - SessionStart hook runs → `/agileflow:session:init` called automatically
+   - Creates infrastructure, registers main session
+   - You never see this happening
+
+2. **Debugging session state**:
+   - Run `/agileflow:session:init` manually
+   - Check `.agileflow/sessions/registry.json` for current state
+   - Use `/agileflow:session:status` to view readable output
+
+3. **Manual setup**:
+   - If hook is disabled, run this to initialize
+   - Then use other session commands
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:session:init` IS ACTIVE
+- Creates `.agileflow/sessions/` directory and registry
+- Runs automatically via SessionStart hook
+- Safe to run multiple times (idempotent)
+- Lock files track active vs inactive sessions
+- Check `registry.json` for current session state
+
+<!-- COMPACT_SUMMARY_END -->

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

@@ -1,6 +1,20 @@
 ---
 description: Create a new parallel session with git worktree
 argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:new - Create parallel session with worktree"
+    - "Validates git repo and prerequisites before proceeding"
+    - "Prompts user with 3 creation options: auto-create / named / existing branch"
+    - "Each option leads to different AskUserQuestion prompt"
+    - "Returns success message with `cd` command to activate new session"
+    - "Worktrees created in ../project-{id} or ../project-{name} directories"
+  state_fields:
+    - session_count
+    - user_choice
+    - new_session_id
+    - new_session_path
 ---
 
 # /agileflow:session:new
@@ -150,3 +164,285 @@ Show the created session details and the command to start working:
 - `/agileflow:session:resume` - Switch between sessions
 - `/agileflow:session:status` - View all sessions
 - `/agileflow:session:end` - End current session
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## ⚠️ COMPACT SUMMARY - /agileflow:session:new IS ACTIVE
+
+**CRITICAL**: This command creates new parallel sessions with git worktrees. Three-step process: validate → present options → create.
+
+---
+
+### 🚨 RULE #1: VALIDATE PREREQUISITES
+
+Before doing anything, check:
+```bash
+git rev-parse --is-inside-work-tree
+```
+
+If NOT in a git repo:
+```
+Error: You're not in a git repository. Session creation requires git.
+```
+
+Then exit.
+
+---
+
+### 🚨 RULE #2: PRESENT THREE OPTIONS WITH AskUserQuestion
+
+Get current session count first:
+```bash
+node .agileflow/scripts/session-manager.js status
+```
+
+Then show exactly these 3 options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "How would you like to create your new session?",
+  "header": "New session",
+  "multiSelect": false,
+  "options": [
+    {"label": "Auto-create Session 2 (Recommended)",
+     "description": "Creates ../project-2 with new branch session-2"},
+    {"label": "Name this session",
+     "description": "Give it a memorable name like 'auth' or 'bugfix'"},
+    {"label": "Use existing branch",
+     "description": "Create session from one of your existing branches"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Increment session number based on current count.
+
+---
+
+### 🚨 RULE #3: HANDLE OPTION #1 - AUTO-CREATE
+
+If user selects "Auto-create":
+```bash
+node .agileflow/scripts/session-manager.js create
+```
+
+Display:
+```
+✓ Created Session {id}
+
+  Workspace: ../project-{id}
+  Branch:    session-{id}
+
+┌─────────────────────────────────────────────────────────┐
+│ To start working in this session, run:                  │
+│                                                         │
+│   cd ../project-{id} && claude                          │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+
+💡 Tip: Use /agileflow:session:resume to see all sessions
+```
+
+---
+
+### 🚨 RULE #4: HANDLE OPTION #2 - NAME THIS SESSION
+
+If user selects "Name this session", present suggestions:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What should this session be called?",
+  "header": "Session name",
+  "multiSelect": false,
+  "options": [
+    {"label": "auth", "description": "Working on authentication"},
+    {"label": "bugfix", "description": "Fixing bugs"},
+    {"label": "feature", "description": "New feature work"},
+    {"label": "experiment", "description": "Trying something out"},
+    {"label": "Other", "description": "Custom name"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+If user selects "Other", prompt for custom input (AskUserQuestion with text input if available).
+
+Then create:
+```bash
+node .agileflow/scripts/session-manager.js create --nickname {name}
+```
+
+Display:
+```
+✓ Created Session {id} "{name}"
+
+  Workspace: ../project-{name}
+  Branch:    session-{id}-{name}
+
+┌─────────────────────────────────────────────────────────┐
+│ To start working in this session, run:                  │
+│                                                         │
+│   cd ../project-{name} && claude                        │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+
+💡 Tip: Use /agileflow:session:resume to see all sessions
+```
+
+---
+
+### 🚨 RULE #5: HANDLE OPTION #3 - USE EXISTING BRANCH
+
+If user selects "Use existing branch":
+
+1. Get branches:
+```bash
+git branch --format='%(refname:short)'
+```
+
+2. Limit to 5-6 most recent and present:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which branch?",
+  "header": "Select branch",
+  "multiSelect": false,
+  "options": [
+    {"label": "feature/auth", "description": ""},
+    {"label": "bugfix/login", "description": ""},
+    {"label": "feature/payments", "description": ""},
+    {"label": "main", "description": "Default branch"},
+    {"label": "Other", "description": "See all branches"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+3. If user selects "Other", show all branches.
+
+4. Create with selected branch:
+```bash
+node .agileflow/scripts/session-manager.js create --branch {branch_name}
+```
+
+Display success as above.
+
+---
+
+### 🚨 RULE #6: ERROR HANDLING
+
+**If directory exists:**
+```
+Error: ../project-{name} already exists.
+
+Suggestions:
+  • Choose a different name
+  • Remove the directory: rm -rf ../project-{name}
+  • Use an existing directory as a session (advanced)
+```
+
+**If branch conflict:**
+```
+Error: Branch session-{id}-{name} already exists.
+
+Try a different name or use /agileflow:session:new again.
+```
+
+**If git error:**
+```
+Error: Git operation failed
+
+{error_message}
+
+Try running: git status
+```
+
+---
+
+### 🚨 RULE #7: SUCCESS MESSAGE FORMAT
+
+All three options show same format:
+```
+✓ Created Session {id} ["{nickname}" OR empty]
+
+  Workspace: ../project-{path}
+  Branch:    {branch_name}
+
+┌─────────────────────────────────────────────────────────┐
+│ To start working in this session, run:                  │
+│                                                         │
+│   {cd_command}                                          │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+
+💡 Tip: Use /agileflow:session:resume to see all sessions
+```
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `.agileflow/sessions/registry.json` | Session registry (updated) |
+| `.agileflow/scripts/session-manager.js` | Create session |
+| `../project-{id/name}/` | New worktree directory |
+
+---
+
+### WORKFLOW
+
+1. **Validate git** → `git rev-parse --is-inside-work-tree`
+2. **Get session count** → `session-manager.js status`
+3. **Present options** → AskUserQuestion with 3 choices
+4. **User selects** → Option 1, 2, or 3
+5. **Handle selection** → Different flow for each
+6. **Create session** → Call manager script
+7. **Show success** → Display cd command
+
+---
+
+### SESSION CREATION METHODS
+
+| Method | Path | Branch | Command |
+|--------|------|--------|---------|
+| Auto-create | ../project-{id} | session-{id} | create |
+| Named | ../project-{name} | session-{id}-{name} | create --nickname {name} |
+| Existing branch | ../project-{name} | {branch_name} | create --branch {branch} |
+
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Don't validate git repo in the middle of process
+❌ Don't show more/fewer than 3 initial options
+❌ Don't create session without explicit user choice
+❌ Don't skip error handling (directory exists, branch conflict)
+❌ Don't forget cd command in success message
+❌ Show different success formats for different methods
+
+### DO THESE INSTEAD
+
+✅ Validate git first, exit if not in repo
+✅ Always show exactly 3 options
+✅ Wait for user to select before creating
+✅ Handle all error cases gracefully
+✅ Always show cd command in success
+✅ Use consistent success format
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:session:new` IS ACTIVE
+- ALWAYS validate git repo first
+- Present 3 options: auto-create / named / existing branch
+- Each option leads to different flow
+- Use AskUserQuestion for user selections
+- Handle all error cases (directory, branch, git)
+- Return success with cd command
+- Show tip to use /agileflow:session:resume
+
+<!-- COMPACT_SUMMARY_END -->