agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/commands/pr.md

@@ -1,337 +0,0 @@
----
-description: Generate pull request description from story
-phase: pre-pr
-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
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js pr
-```
-
-This gathers git status, stories/epics, session state, and registers for PreCompact.
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-
-## ⚠️ COMPACT SUMMARY - /agileflow:pr IS ACTIVE
-
-**CRITICAL**: You are generating pull request descriptions from stories. These are paste-ready GitHub PR bodies.
-
-**ROLE**: PR Description Generator
-
----
-
-### 🚨 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
-
----
-
-### 🚨 RULE #3: PR DESCRIPTION STRUCTURE (EXACT FORMAT)
-
-Generate GitHub PR body with these sections in order:
-
-| 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]
-```
-
-Then ask: "Copy the PR body above. Continue? (YES/NO)"
-
----
-
-### 🚨 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` |
-
----
-
-### ANTI-PATTERNS (DON'T DO THESE)
-
-❌ 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
-
-### 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
-
-**TaskCreate/TaskUpdate** (to track PR generation):
-```xml
-<invoke name="TaskCreate/TaskUpdate">
-<parameter name="content">1. Parse inputs (STORY, TITLE, AC_CHECKED, TEST_EVIDENCE, NOTES)
-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 - include context from story):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "PR description ready for [STORY]: [N] files changed, [AC_count] AC items. What next?",
-  "header": "PR Action",
-  "multiSelect": false,
-  "options": [
-    {"label": "Create PR with gh CLI (Recommended)", "description": "Push branch and create PR linking [STORY] with [N] files changed"},
-    {"label": "Edit description first", "description": "Modify summary, add test evidence, or adjust sections"},
-    {"label": "Add test plan section", "description": "Include testing instructions before creating PR"},
-    {"label": "Cancel", "description": "PR description saved, create later"}
-  ]
-}]</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 -->
-
----
-
-Generate a complete PR description from story and test evidence.
-
-## Prompt
-
-ROLE: PR Author
-
-TODO LIST TRACKING
-**CRITICAL**: Immediately create a todo list using TaskCreate/TaskUpdate tool to track PR description generation:
-```
-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 for squash
-```
-
-Mark each step complete as you finish it. This ensures nothing is forgotten.
-
-INPUTS
-STORY=<US-ID>  TITLE=<short>
-AC_CHECKED=<checkbox list>  TEST_EVIDENCE=<bullets/paths>  NOTES=<optional>
-
-ACTIONS
-1) Read story file to pull epic/summary/deps.
-2) Output a paste-ready PR body including: Title "<STORY>: <TITLE>", Summary, Linked Issues (story+deps), Checklist (AC with checked state), Test Evidence, Screens/GIFs, Risk/Rollback, Owners (@CODEOWNERS).
-3) Suggest a Conventional Commit subject for squash.
-
-No file writes.
-
----
-
-## Expected Output
-
-### Successful PR Description
-
-```
-📝 Generating PR description for US-0042...
-
-Reading story file: docs/06-stories/EP-0010/US-0042-login-form.md
-✅ Found epic: EP-0010 (User Authentication)
-✅ Found 3 acceptance criteria
-✅ Found 1 dependency: US-0041
-
-───────────────────────────────────────────────────────────
-PASTE-READY PR BODY (Copy everything below this line)
-───────────────────────────────────────────────────────────
-
-## US-0042: Implement Login Form with Validation
-
-### Summary
-
-Implements the user login form with email/password validation as part of the
-User Authentication epic (EP-0010). This PR adds client-side validation,
-error handling, and integration with the authentication API.
-
-### Linked Issues
-
-- Closes #US-0042
-- Depends on #US-0041 (Authentication API)
-
-### Acceptance Criteria
-
-- [x] User can enter email and password
-- [x] Form validates email format
-- [ ] Form shows error messages for invalid input
-- [x] Submit button disabled while validating
-
-### Test Evidence
-
-- `npm test src/components/LoginForm.test.tsx` - 12 tests passing
-- Manual testing: Verified on Chrome, Firefox, Safari
-- Screenshot: login-form-validation.png
-
-### Screenshots
-
-![Login Form](./screenshots/login-form.png)
-
-### Risk Assessment
-
-- **Low risk**: UI-only changes, no backend modifications
-- **Rollback**: Revert this PR if issues detected
-
-### Code Owners
-
-@frontend-team
-
-───────────────────────────────────────────────────────────
-
-**Suggested commit message:**
-```
-feat(auth): implement login form with validation
-
-Closes US-0042
-```
-
-[AskUserQuestion: "Use this PR description?"]
-```
-
-### Missing Story ID
-
-```
-❌ Missing required input: STORY
-
-Usage:
-/agileflow:pr STORY=US-0042 TITLE="Login Form"
-
-Optional parameters:
-- AC_CHECKED="1,2,4" - Mark AC items 1, 2, 4 as checked
-- TEST_EVIDENCE="npm test passes, manual QA complete"
-- NOTES="Additional context for reviewers"
-```
-
-### Story File Not Found
-
-```
-❌ Story file not found
-
-Searched:
-- docs/06-stories/US-0042.md
-- docs/06-stories/EP-*/US-0042-*.md
-
-Create the story first:
-/agileflow:story EPIC=EP-0010 STORY=US-0042 TITLE="Login Form" OWNER=AG-UI
-```
-
----
-
-## Related Commands
-
-- `/agileflow:story` - Create user stories
-- `/agileflow:review` - AI-powered code review
-- `/agileflow:verify` - Run tests and update story status
-- `/agileflow:status` - Update story status and progress
-- `/agileflow:ci` - Bootstrap CI/CD workflow

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

@@ -1,329 +0,0 @@
----
-description: Synchronize a folder's README.md with its current contents
-argument-hint: "FOLDER=<path>|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"
-    - "{{RULES:file_preview}}"
-    - "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
-
-Synchronize a folder's README.md with its current contents.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js readme-sync
-```
-
----
-
-## Context Loading (Documentation)
-
-**PURPOSE**: Immediately load full context before executing any logic.
-
-**ACTIONS**:
-1. Read this command file (`.agileflow/commands/readme-sync.md`) in its entirety
-2. Absorb all instructions, rules, and examples
-3. Proceed to execution phase with complete context
-
-**WHY**: Prevents incomplete instruction loading and ensures consistent behavior.
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-- **Command**: /agileflow:readme-sync
-- **Purpose**: Synchronize folder README.md with current contents
-- **Arguments**: FOLDER=<path> | FOLDER=all
-- **Agent Spawning**: Spawns `readme-updater` agent for actual work
-- **Key Actions**: List files → Extract descriptions → Build Contents section → Show diff → Update if approved
-- **FOLDER=all**: Sync all docs/*/ subdirectories in parallel
-
-### Tool Usage Examples
-
-**Task** (to spawn readme-updater agent):
-```xml
-<invoke name="Task">
-<parameter name="description">Sync README for docs/02-practices</parameter>
-<parameter name="prompt">Audit and synchronize README.md for: docs/02-practices
-1. List all files and subdirectories
-2. Read current README.md (if exists)
-3. Extract descriptions from each file
-4. Build new '## Contents' section
-5. Show diff and ask for confirmation
-6. Update if approved</parameter>
-<parameter name="subagent_type">agileflow-readme-updater</parameter>
-</invoke>
-```
-
-**AskUserQuestion** (when folder is missing):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{"question": "Which folder should I sync?", "header": "Folder", "multiSelect": false, "options": [{"label": "docs/02-practices (Recommended)", "description": "Sync practices documentation folder"}, {"label": "docs/04-architecture", "description": "Sync architecture documentation"}, {"label": "all", "description": "Sync all docs/ subfolders"}]}]</parameter>
-</invoke>
-```
-
-**AskUserQuestion** (for confirmation):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{"question": "Apply these changes to README.md?", "header": "Update", "multiSelect": false, "options": [{"label": "Yes, update README (Recommended)", "description": "Write the proposed ## Contents section"}, {"label": "No, abort", "description": "Cancel without making changes"}]}]</parameter>
-</invoke>
-```
-
-**Edit** (to update README contents):
-```xml
-<invoke name="Edit">
-<parameter name="file_path">/full/path/to/docs/02-practices/README.md</parameter>
-<parameter name="old_string">## Contents\n\n[old file list]</parameter>
-<parameter name="new_string">## Contents\n\n- **file.md** – Description\n- **folder/** – Description</parameter>
-</invoke>
-```
-
-- **Output**: Updates only "## Contents" section, preserves all other sections
-- **Use Cases**: After adding files, before releases, documentation cleanup, reorganizing folders
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Prompt
-
-ROLE: README Sync Orchestrator
-
-🔴 **AskUserQuestion Format** (when asking decisions):
-- NEVER ask users to "type" anything - use proper options
-- Use XML invoke format with multiSelect for multiple choices
-- See AskUserQuestion format examples in any configuration agent
-
-INPUTS
-FOLDER=<path>   Path to folder (e.g., docs/02-practices)
-FOLDER=all      Sync all docs/ subfolders
-
-AGENT SPAWNING
-This command spawns the `readme-updater` agent to do the actual work:
-
-```
-Task(
-  description: "Sync README for <FOLDER>",
-  prompt: "Audit and synchronize README.md for: <FOLDER>
-    1. List all files and subdirectories
-    2. Read current README.md (if exists)
-    3. Extract descriptions from each file
-    4. Build new '## Contents' section
-    5. Show diff and ask for confirmation
-    6. Update if approved",
-  subagent_type: "agileflow-readme-updater"
-)
-```
-
-ACTIONS
-1) If FOLDER=all:
-   - List all docs/*/ subdirectories
-   - Spawn readme-updater agent for each folder (can run in parallel)
-   - Report summary of all folders updated
-
-2) If FOLDER=<path>:
-   - Validate folder exists
-   - Spawn readme-updater agent with the folder path
-   - Agent handles: listing, diffing, confirmation, updating
-
-3) If FOLDER is missing:
-   - Use AskUserQuestion to ask which folder to sync:
-   ```xml
-   <invoke name="AskUserQuestion">
-   <parameter name="questions">[{
-     "question": "Which folder should I sync?",
-     "header": "Folder",
-     "multiSelect": false,
-     "options": [
-       {"label": "docs/02-practices (Recommended)", "description": "Sync practices documentation folder"},
-       {"label": "docs/04-architecture", "description": "Sync architecture documentation"},
-       {"label": "all", "description": "Sync all docs/ subfolders"},
-       {"label": "Other", "description": "Enter custom folder path"}
-     ]
-   }]</parameter>
-   </invoke>
-   ```
-
-WORKFLOW DETAILS
-
-### Step 1: List Folder Contents
-```bash
-ls -la FOLDER/           # All files + one sublevel
-ls -1 FOLDER/*/          # Subdirectories and their contents
-```
-
-### Step 2: Extract Descriptions
-For each file found:
-- Read first heading (# Heading) from markdown files
-- OR first sentence from file
-- Extract 1-2 line summary
-
-### Step 3: Build Contents Section
-Generate markdown bullet list:
-```markdown
-## Contents
-
-- **filename.md** – Brief description of what this file is
-- **subfolder/** – Description of what's in this subfolder
-  - subfolder/file.md – Specific file description
-```
-
-### Step 4: Show Diff & Apply
-- Display the proposed changes (diff format)
-- Ask user with AskUserQuestion:
-  ```xml
-  <invoke name="AskUserQuestion">
-  <parameter name="questions">[{
-    "question": "Apply these changes to README.md?",
-    "header": "Update",
-    "multiSelect": false,
-    "options": [
-      {"label": "Yes, update README (Recommended)", "description": "Write the proposed ## Contents section to README.md"},
-      {"label": "No, abort", "description": "Cancel without making changes"}
-    ]
-  }]</parameter>
-  </invoke>
-  ```
-- If "Yes, update README": Use Edit tool to update "## Contents" section
-- If "No, abort": Exit without changes
-
-EXAMPLE OUTPUT
-
-```
-📁 Syncing docs/02-practices/README.md
-=====================================
-
-Found 8 files:
-  • README.md (existing)
-  • testing.md – Test strategy, patterns, test infrastructure
-  • git-branching.md – Git workflow, branching strategy, commit conventions
-  • ci.md – CI/CD pipeline configuration, testing gates
-  • security.md – Security practices, input validation, authentication
-  • releasing.md – Release procedures, versioning, changelog
-
-Proposed Changes to ## Contents Section:
-─────────────────────────────────────────
-- **testing.md** – Test strategy, patterns, test infrastructure
-- **git-branching.md** – Git workflow, branching strategy, commit conventions
-- **ci.md** – CI/CD pipeline configuration, testing gates
-- **security.md** – Security practices, input validation, authentication
-- **releasing.md** – Release procedures, versioning, changelog
-
-Update README.md with these changes? (YES/NO)
-```
-
-WHEN TO USE
-- After adding new files to a folder (keep README current)
-- Before major releases (ensure docs match code)
-- During documentation cleanup (quarterly maintenance)
-- After reorganizing folder structure (update navigation)
-- When README "Contents" section is out of date
-- Use FOLDER=all to sync entire docs/ directory at once
-
-USAGE EXAMPLES
-```bash
-# Sync single folder
-/agileflow:readme-sync FOLDER=docs/02-practices
-
-# Sync all docs folders
-/agileflow:readme-sync FOLDER=all
-
-# Sync architecture docs
-/agileflow:readme-sync FOLDER=docs/04-architecture
-```
-
-WHAT IT UPDATES
-Only the `## Contents` section of README.md:
-- Removes old file listings
-- Adds all current files with descriptions
-- Maintains all other sections unchanged
-- Preserves custom notes and links
-
----
-
-## Expected Output
-
-### Success - README Synced
-
-```
-📁 Syncing docs/02-practices/README.md
-══════════════════════════════════════════════════════════════
-
-Found 8 files:
-  • README.md (existing)
-  • testing.md – Test strategy, patterns, test infrastructure
-  • git-branching.md – Git workflow, branching strategy
-  • ci.md – CI/CD pipeline configuration, testing gates
-  • security.md – Security practices, input validation
-  • releasing.md – Release procedures, versioning
-
-Proposed Changes to ## Contents Section:
-─────────────────────────────────────────
-- **testing.md** – Test strategy, patterns, test infrastructure
-- **git-branching.md** – Git workflow, branching strategy
-- **ci.md** – CI/CD pipeline configuration, testing gates
-- **security.md** – Security practices, input validation
-- **releasing.md** – Release procedures, versioning
-
-Update README.md with these changes? (YES/NO)
-
-✅ README.md updated successfully!
-```
-
-### Success - All Folders Synced
-
-```
-📁 Syncing All Documentation Folders
-══════════════════════════════════════════════════════════════
-
-Spawning readme-updater agents...
-
-  ✓ docs/02-practices (8 files)
-  ✓ docs/03-decisions (12 files)
-  ✓ docs/04-architecture (15 files)
-  ✓ docs/05-epics (6 files)
-  ✓ docs/06-stories (42 files)
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Summary: 5 READMEs updated
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Error - Folder Not Found
-
-```
-❌ Folder not found: docs/invalid-folder
-
-Available documentation folders:
-  • docs/02-practices
-  • docs/03-decisions
-  • docs/04-architecture
-  • docs/05-epics
-
-Usage: /agileflow:readme-sync FOLDER=docs/02-practices
-```
-
----
-
-## Related Commands
-
-- `/agileflow:docs` - Synchronize documentation with code
-- `/agileflow:changelog` - Generate changelog from commits
-- `/agileflow:template` - Manage custom templates
-- `/agileflow:configure` - Manage AgileFlow features