agileflow 2.76.0 → 2.78.0

package/src/core/commands/multi-expert.md

@@ -1,12 +1,89 @@
 ---
 description: Deploy multiple domain experts on the same problem for higher confidence
 argument-hint: <question or task>
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:multi-expert - Parallel expert orchestration"
+    - "CRITICAL: Deploy ALL experts in SINGLE message with multiple Task tool calls (not sequential)"
+    - "MUST wait for all experts via TaskOutput with block=true before synthesis"
+    - "MUST analyze agreement: 3+ experts agree = HIGH confidence, 2 agree = MEDIUM, 1 = unique insight"
+    - "MUST detect domain keywords from user question to select 3-5 experts"
+    - "Synthesis format: Key Findings (agreement) | Unique Insights (single expert) | Disagreements (needs review)"
+  state_fields:
+    - selected_experts
+    - user_question
+    - expert_results
+    - confidence_scores
 ---
 
 # /agileflow-multi-expert
 
 Deploy multiple Agent Experts on the same problem. Each expert validates independently, then results are synthesized for higher confidence answers.
 
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:multi-expert` - Deploy 3-5 domain experts in parallel for high-confidence analysis
+
+**Quick Usage**:
+```
+/agileflow:multi-expert Is our authentication implementation secure?
+```
+
+**What It Does**: Analyze question for domains → Select 3-5 experts → Deploy in PARALLEL → Collect results → Synthesize with confidence scoring
+
+**Experts Available**: Security, API, Testing, Database, Performance, CI/CD, DevOps, Accessibility, Architecture
+
+**Critical Rules**:
+- 🚨 Deploy ALL experts in ONE message with multiple Task calls (not sequential)
+- 🚨 Wait for all results before synthesis (use TaskOutput with block=true)
+- 🚨 Confidence: HIGH (3+ agree) | MEDIUM (2 agree) | UNIQUE INSIGHT (1 expert with evidence)
+- Detect domain keywords to select 3-5 experts (max 5 to avoid overhead)
+
+**Output Format**: Key Findings (high confidence) | Unique Insights (single expert) | Disagreements (needs review) | Recommended Actions
+
+**Tool Usage Examples**:
+
+**Task** (deploy expert in parallel):
+```xml
+<invoke name="Task">
+<parameter name="description">[Domain] analysis of: {question}</parameter>
+<parameter name="prompt">EXPERTISE FIRST: Read packages/cli/src/core/experts/{domain}/expertise.yaml
+
+QUESTION: {user_question}
+
+Analyze from your {domain} perspective:
+1. What do you observe in your domain?
+2. What concerns or issues do you see?
+3. What recommendations do you have?
+4. Confidence level (High/Medium/Low) and why?
+
+Be specific with file paths and code references.</parameter>
+<parameter name="subagent_type">agileflow-{domain}</parameter>
+<parameter name="run_in_background">true</parameter>
+</invoke>
+```
+
+**TaskOutput** (collect all results):
+```xml
+<invoke name="TaskOutput">
+<parameter name="task_id">{expert_task_id}</parameter>
+<parameter name="block">true</parameter>
+</invoke>
+```
+
+**Domain Detection Keywords**:
+| Domain | Keywords |
+|--------|----------|
+| Security | auth, JWT, OAuth, vulnerability, XSS, CSRF, secure, encrypt |
+| API | endpoint, REST, GraphQL, route, controller, backend |
+| Testing | test, spec, coverage, mock, assertion |
+| Database | schema, table, query, migration, SQL, model |
+| Performance | optimize, cache, latency, profiling, slow |
+
+<!-- COMPACT_SUMMARY_END -->
+
 ## When to Use
 
 - **Complex cross-domain questions** - "How does user authentication flow from login to API?"

package/src/core/commands/packages.md

@@ -1,5 +1,21 @@
 ---
 description: Manage dependencies with updates and security audits
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Auto-detect package manager (npm, pip, cargo, etc.) from manifest files"
+    - "MUST use TodoWrite to track 8-step workflow (inputs, detect, analyze, generate, preview, confirm, apply, save)"
+    - "ALWAYS show diff-first before applying updates (YES/NO confirmation)"
+    - "Prioritize security updates - run ACTION=audit first if vulnerabilities suspected"
+    - "For major updates: Create stories, don't auto-update (may require code changes)"
+    - "NEVER auto-update without approval (AUTO_PR default is no)"
+    - "Update/create reports in docs/08-project/ (dependencies-dashboard.md, dependency-report-*.md)"
+    - "If critical CVEs found, create story: 'US-XXXX: Fix security vulnerabilities in dependencies'"
+  state_fields:
+    - package_manager_detected
+    - vulnerabilities_found
+    - updates_applied
+    - report_saved
 ---
 
 # packages

package/src/core/commands/pr.md

@@ -1,9 +1,26 @@
 ---
 description: Generate pull request description from story
 argument-hint: STORY=<US-ID> [TITLE=<text>] [TEST_EVIDENCE=<text>]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "STORY ID is REQUIRED - always ask if missing"
+    - "Read story file FIRST from docs/06-stories/<STORY>.md"
+    - "Extract: epic reference, summary, dependencies, acceptance criteria"
+    - "NEVER guess AC or dependencies - read from story file"
+    - "Output is PASTE-READY - format as GitHub PR markdown"
+    - "Include ALL dependencies found in story file"
+    - "Preserve AC checkbox states from AC_CHECKED input"
+    - "Suggest conventional commit format: feat/fix/chore based on story type"
+  state_fields:
+    - story_id
+    - title
+    - ac_checked
+    - test_evidence
+    - notes
 ---
 
-# pr-template
+# pr
 
 ## STEP 0: Gather Context
 
@@ -16,91 +33,168 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Purpose**: Generate complete, paste-ready pull request descriptions from user story files and test evidence.
-
-**Role**: PR Author
-
-**Key Inputs**:
-- `STORY=<US-ID>` - User story identifier (required)
-- `TITLE=<text>` - Short PR title (optional)
-- `AC_CHECKED=<checkbox list>` - Acceptance criteria with checked/unchecked state (optional)
-- `TEST_EVIDENCE=<bullets/paths>` - Test results, screenshots, logs (optional)
-- `NOTES=<text>` - Additional context or notes (optional)
-
-**Core Workflow**:
-1. Parse all input arguments (STORY, TITLE, AC_CHECKED, TEST_EVIDENCE, NOTES)
-2. Read the story file from `docs/06-stories/<STORY>.md` to extract:
-   - Epic reference and context
-   - Story summary and description
-   - Dependencies on other stories
-   - Acceptance criteria
-3. Generate comprehensive PR description with all standard sections
-4. Output paste-ready PR body in markdown format
-5. Suggest Conventional Commit subject line for squash merges
-
-**PR Description Structure**:
-- **Title**: `<STORY>: <TITLE>` format
-- **Summary**: High-level overview of changes
-- **Linked Issues**: Story ID + dependencies from story file
-- **Checklist**: Acceptance criteria with checkbox states from AC_CHECKED
-- **Test Evidence**: Formatted test results, paths, screenshots from TEST_EVIDENCE
-- **Screenshots/GIFs**: Placeholder section for visual evidence
-- **Risk Assessment**: Potential risks and rollback plan
-- **Code Owners**: Auto-populated from @CODEOWNERS
-
-**Output Format**:
-```markdown
-## Summary
-[Generated from story summary + NOTES]
 
-## Linked Issues
-- Implements #<STORY>
-- Depends on #<DEP-1>, #<DEP-2>
+## ⚠️ COMPACT SUMMARY - /agileflow:pr IS ACTIVE
+
+**CRITICAL**: You are generating pull request descriptions from stories. These are paste-ready GitHub PR bodies.
 
-## Checklist
-- [x] AC1: Description
-- [ ] AC2: Description
+**ROLE**: PR Description Generator
+
+---
 
-## Test Evidence
-[Formatted TEST_EVIDENCE content]
+### 🚨 RULE #1: STORY ID IS REQUIRED (ALWAYS)
+
+Always require `STORY=<US-ID>` input. If missing, ask user: "Which story is this PR for? (e.g., US-0042)"
+
+---
+
+### 🚨 RULE #2: READ STORY FILE FIRST (MANDATORY)
+
+**BEFORE ANYTHING ELSE**: Read the story file from `docs/06-stories/<STORY>.md`
+
+Extract these from the story file (NEVER guess):
+- Epic reference
+- Story summary and description
+- Dependencies on other stories
+- Acceptance criteria (exact text)
+- Owner/assignee
+
+❌ WRONG: Generate PR description without reading story file
+✅ RIGHT: Read story file, extract actual AC and deps
+
+---
 
-## Screenshots/GIFs
-[Placeholder or provided content]
+### 🚨 RULE #3: PR DESCRIPTION STRUCTURE (EXACT FORMAT)
 
-## Risk Assessment
-[Analysis of potential risks and rollback strategy]
+Generate GitHub PR body with these sections in order:
 
-## Code Owners
-@team-name
+| Section | Source | Format |
+|---------|--------|--------|
+| Title | Input TITLE or story summary | `<STORY>: <TITLE>` |
+| Summary | Story summary + NOTES input | 2-3 paragraph description |
+| Linked Issues | Story ID + dependencies from file | Bullet list of #STORY |
+| Checklist | AC_CHECKED input (preserve state) | `- [x]` / `- [ ]` format |
+| Test Evidence | TEST_EVIDENCE input | Formatted bullets/paths/links |
+| Screenshots | User-provided or placeholder | Links or "See attached" |
+| Risk Assessment | Analyze potential risks | Bulleted risks + rollback plan |
+| Code Owners | From @CODEOWNERS file | @team or specific users |
+
+---
+
+### 🚨 RULE #4: OUTPUT IS PASTE-READY
+
+The PR body output MUST be copy-paste-ready for GitHub:
+- Use proper markdown formatting
+- No internal notes or meta-commentary
+- No "Here's what I generated:" prefixes
+- No instructions about what to do next
+
+**SHOW OUTPUT**:
+```markdown
+[Actual PR body here - ready to paste into GitHub]
 ```
 
-**Conventional Commit Suggestion**: Provides a proper commit message following conventional commit format (feat/fix/chore) based on story type.
+Then ask: "Copy the PR body above. Continue? (YES/NO)"
 
-**File Operations**: Read-only - no file writes, only reads story file for context.
+---
+
+### 🚨 RULE #5: CONVENTIONAL COMMIT SUGGESTION
+
+Suggest a commit message following conventional format:
+
+| Story Type | Format | Example |
+|-----------|--------|---------|
+| New feature | `feat: <description>` | `feat: add user authentication` |
+| Bug fix | `fix: <description>` | `fix: resolve login timeout issue` |
+| Refactor | `refactor: <description>` | `refactor: simplify user service` |
+| Chore | `chore: <description>` | `chore: update dependencies` |
+
+---
 
-**Best Practices**:
-- Always read the story file first to ensure accurate context
-- Include all dependencies found in story file
-- Preserve checkbox states from AC_CHECKED input
-- Format test evidence clearly and readably
-- Suggest meaningful commit messages aligned with change type
+### ANTI-PATTERNS (DON'T DO THESE)
 
-**Tool Usage Examples**:
+❌ Generate PR description without reading story file
+❌ Guess at acceptance criteria instead of extracting them
+❌ Add meta-commentary or instructions to PR body
+❌ Forget to include dependencies
+❌ Lose checkbox states from AC_CHECKED input
+❌ Include internal development notes in PR body
 
-TodoWrite:
+### DO THESE INSTEAD
+
+✅ Always read story file first
+✅ Extract actual AC and dependencies from story
+✅ Output paste-ready PR markdown
+✅ Include all dependencies as linked issues
+✅ Preserve AC checkbox states
+✅ Suggest meaningful conventional commit message
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `docs/06-stories/<STORY>.md` | Story source - read for AC and deps |
+| `docs/09-agents/status.json` | Story metadata reference |
+| `.github/CODEOWNERS` | Code owners for PR section |
+
+---
+
+### WORKFLOW
+
+1. **Input Validation**: Ensure STORY is provided or ask user
+2. **Read Story File**: Load story from `docs/06-stories/<STORY>.md`
+3. **Extract Metadata**: Get epic, summary, dependencies, AC
+4. **Generate PR Body**: Build complete markdown (using template above)
+5. **Show Output**: Display paste-ready PR body
+6. **Suggest Commit**: Provide conventional commit message
+7. **Confirm**: Ask user to confirm and copy
+
+---
+
+### TOOL USAGE EXAMPLES
+
+**TodoWrite** (to track PR generation):
 ```xml
 <invoke name="TodoWrite">
 <parameter name="content">1. Parse inputs (STORY, TITLE, AC_CHECKED, TEST_EVIDENCE, NOTES)
-2. Read story file to extract epic/summary/deps
-3. Generate PR description with all sections
-4. Output paste-ready PR body
-5. Suggest Conventional Commit subject</parameter>
+2. Read story file from docs/06-stories/
+3. Extract: epic, summary, deps, AC
+4. Generate PR description with all sections
+5. Output paste-ready PR body
+6. Suggest conventional commit message</parameter>
 <parameter name="status">in-progress</parameter>
 </invoke>
 ```
 
+**AskUserQuestion** (for confirmation):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Use this PR description?",
+  "header": "Confirm",
+  "multiSelect": false,
+  "options": [
+    {"label": "Copy to clipboard", "description": "Ready to paste into GitHub"},
+    {"label": "Edit it", "description": "Let me modify sections"},
+    {"label": "Cancel", "description": "Don't create PR now"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:pr` IS ACTIVE - generating PR descriptions
+- STORY ID required - ask if missing
+- Read story file FIRST - extract AC, deps, summary
+- Output MUST be paste-ready for GitHub
+- Include conventional commit suggestion
+- Preserve AC checkbox states from input
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/readme-sync.md

@@ -1,6 +1,22 @@
 ---
 description: Synchronize a folder's README.md with its current contents
 argument-hint: FOLDER=<path> | FOLDER=all
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "FOLDER is REQUIRED or ask user (single folder or 'all')"
+    - "Spawn readme-updater agent to do actual work"
+    - "If FOLDER=all, spawn agent for each docs/* subfolder in parallel"
+    - "List all files and subdirectories with descriptions"
+    - "Build '## Contents' section with file descriptions"
+    - "Always show diff/preview FIRST, wait for YES/NO BEFORE updating"
+    - "Only update '## Contents' section - preserve other sections"
+    - "Use Edit tool to update README only after approval"
+  state_fields:
+    - folder_path
+    - all_folders_flag
+    - files_count
+    - updated_flag
 ---
 
 # readme-sync