agileflow 2.77.0 → 2.78.0

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

@@ -1,6 +1,18 @@
 ---
 description: Export concise context excerpt for web AI tools
 argument-hint: (no arguments)
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:context:export - Read-only export command"
+    - "READ-ONLY: No file writes, no confirmation needed, no state changes"
+    - "OUTPUT LIMIT: ≤300 lines maximum for easy pasting into web AI tools"
+    - "REQUIRED INPUT: docs/context.md must exist (run /agileflow:context:full first if missing)"
+    - "EXTRACT ONLY: overview, focus, tech, decisions, features, next steps (skip progress, notes)"
+    - "NO TodoWrite needed - single-step read-only operation"
+  state_fields:
+    - context_file_exists
+    - output_line_count
 ---
 
 # /agileflow:context:export
@@ -18,11 +30,188 @@ Reads `docs/context.md` and outputs a condensed excerpt (≤300 lines) ready to
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `/agileflow:context:export`
-**Purpose**: Output concise context brief for pasting into web AI tools
-**Key Rule**: Read-only, no file writes, ≤300 lines output
+## ⚠️ COMPACT SUMMARY - /agileflow:context:export IS ACTIVE
+
+**CRITICAL**: You are exporting a condensed context brief from `docs/context.md`. Follow these rules EXACTLY.
+
+**PURPOSE**: Extract ≤300 line excerpt ready to paste into ChatGPT, Perplexity, Gemini, or Claude web for immediate context loading.
+
+---
+
+### 🚨 RULE #1: READ-ONLY COMMAND
+
+**This command NEVER writes, modifies, or changes state:**
+- ✓ Read docs/context.md
+- ✓ Extract and format
+- ✓ Output to code block
+- ✗ NO file writes
+- ✗ NO Edit tool calls
+- ✗ NO confirmation needed
+- ✗ NO state changes
+
+**Purpose**: Simple read → extract → display workflow.
+
+---
+
+### 🚨 RULE #2: OUTPUT LIMIT IS STRICT - ≤300 LINES
+
+**Maximum output size is 300 lines.** This is critical for pasting into web AI tools.
+
+**If context.md is longer:**
+1. Extract ONLY these sections (in order):
+   - What We're Building (overview)
+   - Current Focus (active work)
+   - Tech Stack (technologies)
+   - Key Decisions (ADRs list only, not full descriptions)
+   - Feature Map (one-line-per-epic summary)
+   - Next Steps (upcoming work)
+
+2. **SKIP these to save space:**
+   - Recent Progress (too verbose)
+   - Notes section (too long)
+   - Detailed story descriptions
+   - Full ADR content
+
+3. **Count lines as you extract** - use line counter to stay under 300
+
+**Format as:**
+```markdown
+# Project Context Brief
+Last updated: [timestamp from context.md]
+
+## What We're Building
+[Max 5 lines]
+
+## Current Focus
+[Max 5 lines]
+
+## Tech Stack
+[Max 8 lines]
+
+## Key Decisions
+[Max 10 lines - ADR titles only]
+
+## Feature Map
+[Max 15 lines - one per epic]
+
+## Next Steps
+[Max 15 lines - ready stories only]
+```
+
+---
+
+### 🚨 RULE #3: REQUIRED INPUT FILE
+
+**docs/context.md MUST exist before exporting.**
+
+**If missing:**
+```
+Error: docs/context.md not found.
+
+To create it, run: /agileflow:context:full
+
+Then you can export with: /agileflow:context:export
+```
+
+**Do NOT create placeholder or fallback - user must run :full first.**
+
+---
+
+### 🚨 RULE #4: EXTRACTION SEQUENCE
+
+**Extract in this EXACT order (don't rearrange):**
+
+| Step | Section | Source | Max Lines |
+|------|---------|--------|-----------|
+| 1 | Header | "# Project Context Brief" | 1 |
+| 2 | Timestamp | Last updated: [from context.md] | 1 |
+| 3 | What We're Building | From overview section | 5 |
+| 4 | Current Focus | From overview/focus section | 5 |
+| 5 | Tech Stack | From tech section (short list) | 8 |
+| 6 | Key Decisions | From decisions section (titles only) | 10 |
+| 7 | Feature Map | From features section (one per epic) | 15 |
+| 8 | Next Steps | From next section (ready stories) | 15 |
+| 9 | Footer | Paste instructions | 3 |
+| | | **TOTAL** | **≤300** |
+
+---
+
+### 🚨 RULE #5: CONTENT CONDENSING RULES
+
+**When extracting, apply these rules to stay under limit:**
+
+| Element | Full Size | Condensed Size | Rule |
+|---------|-----------|----------------|------|
+| ADRs | Full description | Title + status only | "ADR-001: Feature X (Accepted)" |
+| Stories | Title + description | Title + status | "US-0042 (in-progress)" |
+| Tech | Full list + versions | Framework + key deps only | "Next.js 16, TensorFlow.js, Tailwind" |
+| Epics | Title + stories list | Title + story count + status | "EP-001: Auth (3 stories, 1 done)" |
+| Decisions | Full context | One-liner | "JWT instead of sessions" |
+
+---
+
+### 🚨 RULE #6: OUTPUT FORMAT IS EXACT
+
+**Always output in code block for easy copying:**
+
+```
+markdown
+# Project Context Brief
+Last updated: [ISO timestamp]
+
+[Extracted sections...]
+
+---
+**Paste this into**: ChatGPT, Perplexity, Gemini, or Claude web
+**Purpose**: Load full project context for AI assistance
+**Limit**: This excerpt is ≤300 lines for easy pasting
+```
+
+**DO NOT output as plain text, tables, or separate sections - use single code block for easy selection and copy.**
+
+---
+
+### KEY FILES & STATE TO REMEMBER
+
+| File/State | Purpose | Notes |
+|-----------|---------|-------|
+| docs/context.md | Source file | Must exist, read-only |
+| Output limit | Max 300 lines | Count carefully |
+| Line counter | Track total | Update as you extract |
+| Code block | Output format | For easy copy-paste |
+
+---
+
+### ANTI-PATTERNS & CORRECT PATTERNS
+
+❌ **DON'T**: Modify docs/context.md
+✅ **DO**: Read-only extract only
+
+❌ **DON'T**: Output >300 lines
+✅ **DO**: Condense to fit limit
+
+❌ **DON'T**: Include full ADR descriptions
+✅ **DO**: ADR titles + status only
+
+❌ **DON'T**: Include progress/notes sections
+✅ **DO**: Overview, focus, tech, decisions, features, next only
+
+❌ **DON'T**: Output as plain text
+✅ **DO**: Single markdown code block for copy-paste
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+After this command completes:
+- ✓ Excerpt extracted from docs/context.md (read-only)
+- ✓ Output ≤300 lines (verified count)
+- ✓ Formatted in markdown code block
+- ✓ Ready to paste into ChatGPT, Perplexity, Gemini, Claude web
+- ✓ Use `/agileflow:context:full` to regenerate docs/context.md
+- ✓ Use `/agileflow:context:note` to add timestamped notes to context.md
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

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 -->
 
 ---