agileflow 2.77.0 → 2.79.0

package/src/core/commands/context/full.md

@@ -1,6 +1,21 @@
 ---
 description: Generate/refresh full context brief for web AI tools
 argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:context:full - Generates docs/context.md for external AI tools"
+    - "ALWAYS create TodoWrite list for multi-step workflow tracking"
+    - "ALWAYS show diff BEFORE ANY file writes - wait for YES/NO confirmation"
+    - "PRESERVE user-written content - only update sections between MANAGED_SECTION markers"
+    - "REQUIRED SOURCES: status.json, bus/log.jsonl, epics, stories, ADRs, practices, architecture, CI, CHANGELOG"
+    - "MANAGED SECTIONS: overview, features, tech, decisions, progress, next"
+    - "DIFF-FIRST PATTERN: Read → Gather → Generate → Show diff → Confirm → Apply"
+  state_fields:
+    - context_sources
+    - managed_sections
+    - user_content_preserved
+    - user_confirmation
 ---
 
 # /agileflow:context:full
@@ -24,24 +39,182 @@ This file is designed to be pasted into ChatGPT, Perplexity, Gemini, or Claude w
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:context:full`
-**Purpose**: Generate/refresh docs/context.md with project context for web AI tools
-
-### Critical Rules
-- **ALWAYS create TodoWrite list** to track multi-step workflow
-- **Diff-first**: Show changes and wait for YES/NO before ANY file writes
-- **Preserve user-written content**: Only update managed sections
-- **Sources**: status.json, bus/log.jsonl, epics, stories, ADRs, practices, architecture, CI, CHANGELOG
-
-### Workflow
-1. Create todo list
-2. Read existing docs/context.md (if exists)
-3. Gather sources
-4. Generate/update managed sections
-5. Show diff for review
-6. Apply changes after YES
+
+## ⚠️ COMPACT SUMMARY - /agileflow:context:full IS ACTIVE
+
+**CRITICAL**: You are generating `docs/context.md` for external AI tools. Follow these rules EXACTLY.
+
+**PURPOSE**: Create comprehensive context brief with managed sections that external AI tools (ChatGPT, Claude web, Perplexity) can paste for full project understanding.
+
+---
+
+### 🚨 RULE #1: ALWAYS START WITH TodoWrite LIST
+
+**Before ANY gathering, create TodoWrite to track workflow:**
+
+```xml
+<invoke name="TodoWrite">
+<parameter name="todos">[
+  {"content": "Read existing docs/context.md", "status": "in_progress", "activeForm": "Reading context file"},
+  {"content": "Gather sources (status.json, bus, epics, ADRs, practices, architecture, CI, CHANGELOG)", "status": "pending", "activeForm": "Gathering sources"},
+  {"content": "Generate/update managed sections (6 sections)", "status": "pending", "activeForm": "Generating sections"},
+  {"content": "Show diff for review", "status": "pending", "activeForm": "Showing diff"},
+  {"content": "Apply changes after YES confirmation", "status": "pending", "activeForm": "Applying changes"}
+]</parameter>
+</invoke>
+```
+
+**NEVER skip this.** It's how we track multi-step work.
+
+---
+
+### 🚨 RULE #2: DIFF-FIRST - ALWAYS SHOW CHANGES BEFORE WRITING
+
+**Workflow sequence is NON-NEGOTIABLE:**
+1. **Read** existing `docs/context.md` (if exists) - identify user vs managed content
+2. **Gather** all source files (see REQUIRED SOURCES below)
+3. **Generate** new managed sections
+4. **Show diff** - display exactly what changed (use diff format)
+5. **Confirm** - call AskUserQuestion: "Apply these changes?"
+6. **Apply** - only after YES, write to file using Edit tool
+
+**❌ WRONG:** Write changes without showing diff first
+**✅ RIGHT:** Show diff, wait for YES, then write
+
+---
+
+### 🚨 RULE #3: PRESERVE USER-WRITTEN CONTENT
+
+**MANAGED SECTIONS are within markers:**
+```markdown
+<!-- MANAGED_SECTION: overview -->
+[Content here - OK to update]
+<!-- END_MANAGED -->
+```
+
+**USER-WRITTEN SECTIONS have no markers:**
+```markdown
+## My Custom Section
+[Content here - NEVER touch this]
+```
+
+**Rules for updating:**
+- Only modify content between `<!-- MANAGED_SECTION: X -->` markers
+- NEVER delete or modify sections without markers
+- If user has added custom sections outside markers, preserve them
+- If user section conflicts with managed section, show diff and ask
+
+---
+
+### 🚨 RULE #4: REQUIRED SOURCES & MANAGED SECTIONS
+
+**Required source files (gather ALL, even if missing):**
+```
+docs/09-agents/status.json       # Current story/epic status (REQUIRED)
+docs/09-agents/bus/log.jsonl     # Last 10 progress messages (REQUIRED)
+docs/05-epics/*.md               # Epic details (if exists)
+docs/06-stories/*/*.md           # Story details (if exists)
+docs/03-decisions/*.md           # ADRs (if exists)
+docs/02-practices/*.md           # Development practices (if exists)
+docs/04-architecture/*.md        # System architecture (if exists)
+package.json / pyproject.toml    # Project manifest (for tech stack)
+.github/workflows/*.yml          # CI config (if exists)
+CHANGELOG.md                     # Recent changes (if exists)
+```
+
+**Managed sections to generate (6 total):**
+
+| Section | Source | Purpose | Max Lines |
+|---------|--------|---------|-----------|
+| **overview** | README, package.json | What we're building + current focus | 10 |
+| **features** | status.json epics | Epic map with story counts | 20 |
+| **tech** | package.json, workflows | Tech stack and dependencies | 15 |
+| **decisions** | ADRs directory | Key ADRs with status | 15 |
+| **progress** | bus/log.jsonl | Last 10 bus messages (chronological) | 30 |
+| **next** | status.json | Ready/in-progress stories | 20 |
+
+---
+
+### 🚨 RULE #5: HANDLING MISSING FILES
+
+**If file doesn't exist, DON'T ERROR - adapt:**
+
+| Missing File | Action |
+|--------------|--------|
+| `docs/context.md` | Create new file with all sections |
+| `status.json` | Skip features/next sections, leave placeholders |
+| `bus/log.jsonl` | Skip progress section |
+| `ADR files` | Skip decisions section |
+| `CI config` | Skip CI details from tech section |
+
+**Placeholder format for missing sections:**
+```markdown
+<!-- MANAGED_SECTION: features -->
+No epics found. Create epics in docs/05-epics/ to populate this section.
+<!-- END_MANAGED -->
+```
+
+---
+
+### 🚨 RULE #6: CONFIRMATION BEFORE WRITING
+
+**Always use AskUserQuestion before Edit:**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Apply these changes to docs/context.md?",
+  "header": "Confirm Context Update",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, update", "description": "Write changes to file"},
+    {"label": "No, abort", "description": "Cancel without saving"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Only call Edit tool if response is YES.**
+
+---
+
+### KEY FILES & STATE TO REMEMBER
+
+| File/State | Purpose | Path |
+|-----------|---------|------|
+| Managed source | List of files to read | Required sources (Rule 4) |
+| Diff display | What's changing | Show before confirm |
+| User confirmation | Gate before writing | YES = write, NO = cancel |
+| Managed sections | Content to update | 6 sections (overview, features, tech, decisions, progress, next) |
+| File markers | Protect user content | Between `<!-- MANAGED_SECTION: X -->` markers |
+
+---
+
+### ANTI-PATTERNS & CORRECT PATTERNS
+
+❌ **DON'T**: Write directly without diff
+✅ **DO**: Show diff → ask → write
+
+❌ **DON'T**: Modify user-written content
+✅ **DO**: Only touch content between MANAGED_SECTION markers
+
+❌ **DON'T**: Skip gathering if file missing
+✅ **DO**: Gather what exists, use placeholders for missing
+
+❌ **DON'T**: Create context.md without section markers
+✅ **DO**: All managed content wrapped in `<!-- MANAGED_SECTION: X -->` markers
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+After this command completes:
+- ✓ docs/context.md created/updated with managed sections
+- ✓ User-written content preserved (outside markers untouched)
+- ✓ File ready for pasting into ChatGPT, Perplexity, Gemini, Claude web
+- ✓ Use `/agileflow:context:export` to get ≤300 line excerpt for pasting
+- ✓ Use `/agileflow:context:note` to add quick timestamped notes
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/context/note.md

@@ -1,6 +1,21 @@
 ---
 description: Add timestamped note to context file
 argument-hint: NOTE=<text>
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:context:note NOTE=\"text\" - Append timestamped note to docs/context.md"
+    - "ALWAYS show diff BEFORE applying changes - wait for YES/NO confirmation"
+    - "REQUIRED ARGUMENT: NOTE must be provided (ask user if missing)"
+    - "AUTO-CREATE: Creates Notes section if missing, appends note to end"
+    - "ISO TIMESTAMP: Always use ISO 8601 format for timestamps"
+    - "PRESERVE: Creates docs/context.md if missing (don't error, create it)"
+    - "CHRONOLOGICAL ORDER: Notes appear in order added (newest at bottom)"
+  state_fields:
+    - note_text
+    - context_file_exists
+    - notes_section_exists
+    - user_confirmation
 ---
 
 # /agileflow:context:note
@@ -16,11 +31,240 @@ Quickly add a note to `docs/context.md` under the "Notes" section. Useful for re
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `/agileflow:context:note NOTE="your note here"`
-**Purpose**: Append timestamped note to docs/context.md
-**Key Rules**: Diff-first, creates Notes section if missing
+## ⚠️ COMPACT SUMMARY - /agileflow:context:note IS ACTIVE
+
+**CRITICAL**: You are appending a timestamped note to `docs/context.md`. Follow these rules EXACTLY.
+
+**PURPOSE**: Quickly record decisions, observations, and reminders as timestamped notes that persist in project context.
+
+---
+
+### 🚨 RULE #1: REQUIRE NOTE ARGUMENT
+
+**The NOTE argument is MANDATORY.**
+
+**If not provided, ask user:**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What note would you like to add to docs/context.md?",
+  "header": "Enter note text",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enter note (use 'Other' field)", "description": "Type your 1-5 line note"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Then extract the user's text from response and proceed.**
+
+**Examples of good notes:**
+```
+"Decided to use JWT instead of sessions"
+"User reported auth bug in production, investigating now"
+"Sprint planning: focusing on US-0042 and US-0045 this week"
+"Performance issue fixed: reduced API response time by 40%"
+"Stakeholder meeting: new feature request added to backlog"
+```
+
+---
+
+### 🚨 RULE #2: AUTO-CREATE MISSING FILES
+
+**If docs/context.md doesn't exist, CREATE it with Notes section:**
+
+```markdown
+# Project Context
+
+<!-- MANAGED_SECTION: placeholder -->
+Run /agileflow:context:full to populate project context.
+<!-- END_MANAGED -->
+
+## Notes
+
+[Notes will appear here]
+```
+
+**Do NOT error or skip. Create the file and add the note.**
+
+---
+
+### 🚨 RULE #3: FIND OR CREATE NOTES SECTION
+
+**Workflow:**
+1. Read docs/context.md
+2. Look for `## Notes` section
+3. If NOT found, CREATE it at the end of the file:
+
+```markdown
+
+## Notes
+```
+
+4. If found, position cursor after last note
+
+**Append format (ALWAYS use this):**
+```markdown
+- **[ISO_TIMESTAMP]**: Note text here
+```
+
+**Example:**
+```markdown
+## Notes
+
+- **[2024-12-31T10:30:00Z]**: Decided to use JWT instead of sessions
+- **[2024-12-31T15:45:00Z]**: User reported auth bug in production
+- **[2025-01-01T09:00:00Z]**: Sprint planning: focusing on US-0042 this week
+```
+
+---
+
+### 🚨 RULE #4: ALWAYS DIFF-FIRST
+
+**NEVER write directly. Always show changes first:**
+
+1. **Read** docs/context.md (or create new)
+2. **Find/Create** Notes section
+3. **Generate** new note with ISO timestamp
+4. **Show diff** (display exactly what changed)
+5. **Confirm** (ask user: "Add this note?")
+6. **Apply** (only after YES, write using Edit tool)
+
+**Diff format:**
+```diff
+## Notes
+
+- **[2024-12-31T10:30:00Z]**: Old note here
++ - **[2025-01-07T14:22:00Z]**: New note being added
+```
+
+---
+
+### 🚨 RULE #5: ISO 8601 TIMESTAMP FORMAT
+
+**ALWAYS use ISO 8601 format for all timestamps.**
+
+**Format**: `YYYY-MM-DDTHH:MM:SSZ` (UTC/Zulu time)
+
+**Examples:**
+- `2024-12-31T10:30:00Z` - correct
+- `2025-01-07T15:45:30Z` - correct
+- `12/31/2024 3:30 PM` - WRONG (not ISO)
+- `Jan 7, 2025 3:45 PM` - WRONG (not ISO)
+
+**To get current timestamp in JavaScript:**
+```javascript
+new Date().toISOString()  // Returns "2025-01-07T14:22:18.123Z"
+// Remove milliseconds: "2025-01-07T14:22:18Z"
+```
+
+---
+
+### 🚨 RULE #6: CONFIRMATION BEFORE WRITING
+
+**Always use AskUserQuestion before Edit:**
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Add this note to docs/context.md?",
+  "header": "Confirm Note Addition",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, add note", "description": "Append note to Notes section"},
+    {"label": "No, cancel", "description": "Cancel without saving"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Only call Edit tool if response is YES.**
+
+---
+
+### KEY FILES & STATE TO REMEMBER
+
+| File/State | Purpose | Format |
+|-----------|---------|--------|
+| docs/context.md | Target file | Markdown with Notes section |
+| Notes section | Append location | `## Notes` header at end |
+| Timestamp | Each note | ISO 8601: `YYYY-MM-DDTHH:MM:SSZ` |
+| Note format | Structure | `- **[timestamp]**: note text` |
+| Diff display | Review before confirm | Show change with context lines |
+| User confirmation | Gate before write | YES = write, NO = cancel |
+
+---
+
+### WORKFLOW SEQUENCE
+
+**This is the EXACT workflow:**
+
+```
+1. Validate NOTE argument provided
+   ├─ If missing: AskUserQuestion for note text
+   └─ If provided: Use provided value
+
+2. Read docs/context.md
+   ├─ If missing: Create new file with placeholder
+   └─ If exists: Read entire file
+
+3. Find or Create Notes section
+   ├─ If found: Position after last note
+   └─ If missing: Add at end of file
+
+4. Generate note entry
+   ├─ Get current ISO timestamp
+   ├─ Format: "- **[timestamp]**: note text"
+   └─ Store as pending_entry
+
+5. Show diff to user
+   ├─ Display before/after
+   └─ Add context lines
+
+6. Confirm with AskUserQuestion
+   ├─ If YES: Go to step 7
+   └─ If NO: Exit, don't write
+
+7. Apply change using Edit tool
+   ├─ Call Edit with old_string and new_string
+   └─ Done
+```
+
+---
+
+### ANTI-PATTERNS & CORRECT PATTERNS
+
+❌ **DON'T**: Write note without showing diff
+✅ **DO**: Show diff → confirm → write
+
+❌ **DON'T**: Error if docs/context.md missing
+✅ **DO**: Create file with placeholder, add note
+
+❌ **DON'T**: Use non-ISO timestamp format
+✅ **DO**: Use `YYYY-MM-DDTHH:MM:SSZ` format
+
+❌ **DON'T**: Skip creating Notes section
+✅ **DO**: Create `## Notes` if missing, append notes there
+
+❌ **DON'T**: Use custom timestamp format
+✅ **DO**: All notes use same ISO format (consistent ordering)
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+After this command completes:
+- ✓ Note appended to docs/context.md (diff shown first)
+- ✓ ISO 8601 timestamp added automatically
+- ✓ Notes section created if missing
+- ✓ Note visible in `/agileflow:context:export` (if space allows)
+- ✓ Notes persist across sessions
+- ✓ Use `/agileflow:context:full` to regenerate managed sections
+- ✓ Use `/agileflow:context:export` to get excerpt for pasting
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/debt.md

@@ -1,5 +1,22 @@
 ---
 description: Track and prioritize technical debt items
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "Scan for debt indicators: TODOs, complexity >10, functions >50 lines, duplication, coverage <70%"
+    - "Parse story tags: tech-debt: true, blocked by debt, 'refactor' or 'cleanup' in title"
+    - "Check ADRs for deprecated status and negative consequences"
+    - "Analyze git history: high churn files, unclear ownership"
+    - "Score each item (0-100): Severity × Scope × Pain / 10"
+    - "Categorize: Architecture/CodeQuality/Documentation/Testing/Security/Performance/Dependencies"
+    - "NEVER auto-create stories without user approval"
+    - "Provide realistic effort estimates (err on high side)"
+    - "Show debt trend analysis and recommendations for reduction"
+  state_fields:
+    - debt_items_found
+    - critical_count
+    - high_count
+    - stories_created
 ---
 
 # tech-debt