agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/commands/epic.md

@@ -1,477 +0,0 @@
----
-description: Create a new epic with stories
-phase: pre-story
-argument-hint: "EPIC=<EP-ID> TITLE=<text> OWNER=<id> GOAL=<text> [STORIES=<list>] [RESEARCH=<file>]"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:epic-new - Epic creator for feature planning"
-    - "{{RULES:task_tracking}}"
-    - "{{RULES:file_preview}}"
-    - "{{RULES:json_operations}}"
-    - "{{RULES:user_confirmation}}"
-    - "STORIES format: 'US-ID|title|owner,US-ID2|title2|owner2' (comma-separated triplets)"
-    - "{{RULES:research_first}}"
-  state_fields:
-    - epic_id
-    - owner
-    - story_count
-    - creation_timestamp
-    - research_validated
----
-
-# epic-new
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js epic
-```
-
-This gathers git status, stories/epics, session state, and registers for PreCompact.
-
----
-
-Create a new epic with optional child stories.
-
-<!-- COMPACT_SUMMARY_START -->
-
-## ⚠️ COMPACT SUMMARY - /agileflow:epic-new IS ACTIVE
-
-**CRITICAL**: You are the Epic Creator. This command creates new epics with associated stories. Follow every rule.
-
----
-
-### 🚨 RULE #1: ALWAYS Create TaskCreate/TaskUpdate Task List FIRST
-
-Create a 6-step task list IMMEDIATELY:
-```xml
-<invoke name="TaskCreate/TaskUpdate">
-<parameter name="content">1. Parse inputs (EPIC, TITLE, OWNER, GOAL, STORIES)
-2. Create epic file from template
-3. For each story: create docs/06-stories/<EPIC>/<US_ID>-<slug>.md
-4. Merge entries into status.json
-5. Append assign events to bus/log.jsonl
-6. Show preview and confirm with user</parameter>
-<parameter name="status">in-progress</parameter>
-</invoke>
-```
-Mark each step complete as you finish it.
-
-### 🚨 RULE #2: NEVER Create Files Without Preview + Confirmation
-
-**Workflow** (ALWAYS follow this order):
-1. Parse and validate all inputs
-2. Create epic file from template
-3. Create story files from template
-4. Prepare status.json merge
-5. Prepare bus/log.jsonl append
-6. Show unified DIFF preview (all files + status.json + bus log)
-7. Ask user YES/NO/CANCEL confirmation
-8. Only on YES: Execute writes and update status
-
-### 🚨 RULE #3: NEVER Use echo/cat > For JSON Operations
-
-**ALWAYS use one of**:
-- Edit tool for small changes
-- jq for complex merges
-- JSON validation after every write:
-```bash
-if ! jq empty docs/09-agents/status.json 2>/dev/null; then
-  echo "❌ ERROR: status.json is now invalid JSON!"
-  exit 1
-fi
-```
-
-### 🚨 RULE #4: ALWAYS Validate JSON After Modifications
-
-After ANY change to status.json:
-```bash
-jq empty docs/09-agents/status.json 2>/dev/null || {
-  echo "❌ VALIDATION FAILED: status.json is corrupt"
-  exit 1
-}
-```
-
----
-
-## Key Files & Formats
-
-**Input Parameters**:
-```
-EPIC=<EP-ID>           # e.g., EP-0001 (required)
-TITLE=<text>           # Epic title (required)
-OWNER=<id>             # Agent or person name (required)
-GOAL=<outcome>         # Epic goal/metric (required)
-STORIES=<list>         # Comma-separated triplets (optional)
-  Format: "US-0001|Story One|owner,US-0002|Story Two|owner2"
-RESEARCH=<file>        # Research note filename (optional)
-  Format: "20260119-feature-research.md" (in docs/10-research/)
-```
-
-**Output Files Created**:
-| File | Purpose | Template |
-|------|---------|----------|
-| docs/05-epics/EP-<ID>.md | Epic definition | epic-template.md |
-| docs/06-stories/EP-<ID>/US-<ID>-<slug>.md | Child stories | story-template.md |
-| docs/09-agents/status.json | Merged entries | jq merge |
-| docs/09-agents/bus/log.jsonl | Appended events | JSONL lines |
-
-**Merge into status.json**:
-- Epic entry: {id, owner, status: "active", summary, created, updated}
-- Story entries: {id, owner, status: "ready", epic, estimate: "0.5d", deps: [], created, updated}
-
-**Append to bus/log.jsonl**:
-```json
-{"ts":"ISO","type":"assign","from":"SYSTEM","to":"<owner>","epic":"<EPIC>","text":"Epic created"}
-{"ts":"ISO","type":"assign","from":"SYSTEM","to":"<owner>","story":"<US-ID>","text":"Story created"}
-```
-
----
-
-## Anti-Patterns & Correct Usage
-
-❌ **DON'T**:
-- Ask user to "type" story list (use structured format)
-- Create files without showing preview
-- Overwrite status.json (always merge)
-- Skip JSON validation after edits
-- Create stories without linking to epic
-
-✅ **DO**:
-- Show file previews for all 3-5 files being created
-- Use proper STORIES format with pipes and commas
-- Merge entries into existing JSON (preserve data)
-- Validate JSON after every modification
-- Link all stories to epic in status.json
-
----
-
-## Confirmation Flow
-
-1. **Show preview box** with all files being created
-   - Epic file path and frontmatter
-   - Story file paths and frontmatter
-   - status.json changes (diff format)
-   - bus/log.jsonl lines to append
-
-2. **Ask confirmation**:
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Create epic EP-0010 with 3 stories?",
-  "header": "Confirm Epic Creation",
-  "multiSelect": false,
-  "options": [
-    {"label": "Yes, create", "description": "Write all files"},
-    {"label": "No, edit", "description": "Modify details"},
-    {"label": "Cancel", "description": "Don't create"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-3. **On YES**: Execute all writes (files, merge, append)
-4. **On NO/CANCEL**: Abort without changes
-
----
-
-## REMEMBER AFTER COMPACTION
-
-- Command creates epics + child stories in one operation
-- ALWAYS parse and validate STORIES input (triplet format)
-- ALWAYS preview before confirming (prevents mistakes)
-- ALWAYS validate JSON after merge (prevents corruption)
-- Use TaskCreate/TaskUpdate for step tracking (6 steps)
-- Files: epic file, N story files, status.json, bus/log.jsonl
-- **RESEARCH-FIRST**: For complex epics (3+ stories), validate research exists; suggest /agileflow:research:ask if missing
-
-<!-- COMPACT_SUMMARY_END -->
-
-## Prompt
-
-ROLE: Epic Creator
-
-OBJECTIVE
-Analyze feature requirements and create structured epics with associated stories. Evaluate story breakdown, assess dependencies, and consider implementation sequencing to ensure comprehensive planning.
-
-TODO LIST TRACKING
-**CRITICAL**: Immediately create a todo list using TaskCreate/TaskUpdate tool to track epic creation:
-```
-1. Parse inputs (EPIC, TITLE, OWNER, GOAL, STORIES)
-2. Create docs/05-epics/<EPIC>.md from template
-3. For each story: create docs/06-stories/<EPIC>/<US_ID>-<slug>.md
-4. Merge entries into docs/09-agents/status.json
-5. Append assign lines to docs/09-agents/bus/log.jsonl
-6. Show preview and wait for YES/NO confirmation
-```
-
-Mark each step complete as you finish it. This ensures nothing is forgotten.
-
-INPUTS
-EPIC=<ID e.g., EP-0001>
-TITLE=<Epic title>
-OWNER=<name or agent id>
-GOAL=<outcome/metric>
-STORIES=<optional> comma-separated "<US_ID>|<short title>|<owner>"
-
-TEMPLATE
-Use the following epic template structure:
-@packages/cli/src/core/templates/epic-template.md
-
-ACTIONS
-1) Create docs/05-epics/<EPIC>.md from epic-template.md (status=active; created/updated=now).
-2) For each story, create docs/06-stories/<EPIC>/<US_ID>-<slug>.md from story-template.md (status=ready; estimate=0.5d; deps=[]).
-3) Merge entries into docs/09-agents/status.json (owner,status,branch,summary,last_update).
-4) Append "assign" lines to docs/09-agents/bus/log.jsonl.
-
-Always show previews; YES/NO before writing.
-
----
-
-## POST-CREATION ACTIONS
-
-After successfully creating the epic, offer next steps:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Epic <EPIC> created with <N> stories! What would you like to do next?",
-  "header": "Next Steps",
-  "multiSelect": false,
-  "options": [
-    {"label": "Add more stories (Recommended)", "description": "Epic may need additional work items"},
-    {"label": "Start working on first story", "description": "Begin implementation immediately"},
-    {"label": "Plan sprint for this epic", "description": "Schedule stories with /agileflow:sprint"},
-    {"label": "View epic details", "description": "See full epic with /agileflow:epic:view"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-**If "Add more stories"**:
-- Re-run `/agileflow:story EPIC=<EPIC>` with next story ID
-
-**If "Start working on first story"**:
-1. Show ready stories in this epic
-2. Let user pick one
-3. Run `/agileflow:status <STORY> STATUS=in_progress`
-4. Ask: "Enter plan mode to explore implementation?"
-
-**If "Plan sprint"**:
-- Run `/agileflow:sprint` with this epic's stories
-
-**If "View epic details"**:
-- Run `/agileflow:epic:view EPIC=<EPIC>`
-
----
-
-## Research-First Validation (GSD Integration)
-
-Before creating an epic or starting work, validate that research exists for complex features.
-
-### Research Validation Flow
-
-**Step 1: Check for Research Field**
-
-When epic has a `research` field in status.json:
-```javascript
-const epic = status.epics["EP-0022"];
-if (epic.research) {
-  // Verify research file exists
-  const researchPath = `docs/10-research/${epic.research}`;
-  if (!fs.existsSync(researchPath)) {
-    console.warn(`⚠️  Research file not found: ${researchPath}`);
-  }
-}
-```
-
-**Step 2: Warn if No Research for Complex Epic**
-
-If epic has 3+ stories and no research field, suggest research first:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "This epic has no linked research. Complex features benefit from research-first planning. What would you like to do?",
-  "header": "Research Check",
-  "multiSelect": false,
-  "options": [
-    {"label": "Create research first (Recommended)", "description": "Run /agileflow:research:ask to gather context"},
-    {"label": "Continue without research", "description": "Proceed with epic creation"},
-    {"label": "Link existing research", "description": "Specify research file to link"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-**If "Create research first"**:
-- Suggest: `/agileflow:research:ask <topic>`
-- After research created, re-run epic creation with RESEARCH parameter
-
-**If "Link existing research"**:
-- Show list of recent research files in docs/10-research/
-- Let user select one
-- Add to epic: `research: "selected-file.md"`
-
-### Epic Schema with Research
-
-```json
-{
-  "EP-0022": {
-    "title": "GSD Integration",
-    "status": "in_progress",
-    "owner": "AG-DEVOPS",
-    "goal": "Adopt GSD workflow patterns",
-    "research": "20260119-gsd-agileflow-integration-analysis.md",
-    "research_required": false,
-    "stories": ["US-0129", "US-0130", "US-0131", "US-0132"]
-  }
-}
-```
-
-**Fields**:
-- `research` (optional): Filename of research note in docs/10-research/
-- `research_required` (optional): If true, blocks implementation until research exists
-
-### When Starting Work Without Research
-
-If user tries to start a story in an epic that has `research_required: true` but no valid research file:
-
-```
-⚠️  Research Required
-
-Epic EP-0022 requires research before implementation.
-Research file not found: 20260119-missing-research.md
-
-Suggested actions:
-1. Run /agileflow:research:ask "GSD workflow integration"
-2. Link existing research with /agileflow:epic RESEARCH=<file>
-3. Remove research_required flag if research is optional
-```
-
----
-
-## Related Commands
-
-- `/agileflow:epic:list` - View all epics with progress
-- `/agileflow:epic:view` - View epic details with all stories
-- `/agileflow:story` - Create story in epic
-- `/agileflow:story:list` - View all stories
-- `/agileflow:sprint` - Plan sprint with epic stories
-- `/agileflow:board` - Visual kanban board
-
----
-
-## Expected Output
-
-### Successful Epic Creation
-
-```
-📦 Creating Epic: EP-0010
-
-Title: User Authentication System
-Owner: AG-API
-Goal: Enable secure user login with OAuth support
-
-Files to create:
-───────────────────────────
-1. docs/05-epics/EP-0010.md
-   - Epic definition with goal and stories
-
-2. docs/06-stories/EP-0010/US-0042-login-form.md
-   - Story: Login Form (AG-UI)
-
-3. docs/06-stories/EP-0010/US-0043-oauth-integration.md
-   - Story: OAuth Integration (AG-API)
-
-4. docs/06-stories/EP-0010/US-0044-session-management.md
-   - Story: Session Management (AG-API)
-
-5. docs/09-agents/status.json (merge)
-   + "EP-0010": {
-   +   "id": "EP-0010",
-   +   "owner": "AG-API",
-   +   "status": "active",
-   +   "stories": ["US-0042", "US-0043", "US-0044"]
-   + }
-   + "US-0042": { "epic": "EP-0010", "owner": "AG-UI", "status": "ready" }
-   + "US-0043": { "epic": "EP-0010", "owner": "AG-API", "status": "ready" }
-   + "US-0044": { "epic": "EP-0010", "owner": "AG-API", "status": "ready" }
-
-6. docs/09-agents/bus/log.jsonl (append)
-   + {"type":"assign","to":"AG-API","epic":"EP-0010","text":"Epic created"}
-   + {"type":"assign","to":"AG-UI","story":"US-0042","text":"Story created"}
-   + {"type":"assign","to":"AG-API","story":"US-0043","text":"Story created"}
-   + {"type":"assign","to":"AG-API","story":"US-0044","text":"Story created"}
-
-[AskUserQuestion: "Create epic EP-0010 with 3 stories?"]
-
-✅ Epic EP-0010 created successfully!
-✅ Created 3 stories: US-0042, US-0043, US-0044
-✅ Bus messages sent to assigned owners
-
-[AskUserQuestion: "What would you like to do next?"]
-```
-
-### Research Validation Warning
-
-```
-📦 Creating Epic: EP-0010 (5 stories)
-
-⚠️  Research Check
-
-This epic has no linked research.
-Complex features (3+ stories) benefit from research-first planning.
-
-[AskUserQuestion: "What would you like to do?"]
-  - Create research first (Recommended)
-  - Continue without research
-  - Link existing research
-```
-
-### With Linked Research
-
-```
-📦 Creating Epic: EP-0010
-
-Research linked: 20260121-auth-system-analysis.md
-
-✅ Research file validated
-✅ Key findings extracted:
-   • OAuth 2.0 recommended over custom auth
-   • JWT for session tokens
-   • 3 integration points identified
-
-[Proceeding with epic creation...]
-```
-
-### Validation Error
-
-```
-❌ Invalid STORIES format
-
-Received: US-0042,US-0043
-Expected: US-0042|title|owner,US-0043|title|owner
-
-Format: "US-ID|title|owner,US-ID2|title2|owner2"
-
-Example:
-STORIES="US-0042|Login Form|AG-UI,US-0043|OAuth|AG-API"
-```
-
-### Epic Already Exists
-
-```
-❌ Epic EP-0010 already exists
-
-Existing epic:
-  Title: User Authentication System
-  Status: in_progress
-  Stories: 3 (1 done, 2 in progress)
-
-To add stories, use:
-  /agileflow:story EPIC=EP-0010 STORY=US-00XX TITLE="..." OWNER=...
-```

package/src/core/commands/export.md

@@ -1,238 +0,0 @@
----
-description: Export stories and epics to CSV, JSON, or Markdown for stakeholder reporting
-argument-hint: "FORMAT=csv|json|md [EPIC=<EP-ID>] [STATUS=<status>] [OWNER=<id>]"
-compact_context:
-  priority: medium
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:export - Export stories/epics to CSV/JSON/Markdown"
-    - "{{RULES:json_operations}}"
-    - "MUST read status.json as data source"
-    - "MUST support FORMAT=csv|json|md (default: csv)"
-    - "MUST support optional filters: EPIC, STATUS, OWNER"
-    - "MUST save output to docs/08-project/exports/"
-  state_fields:
-    - format
-    - filter_epic
-    - filter_status
-    - filter_owner
-    - output_path
----
-
-# /agileflow:export
-
-Export stories and epics from status.json to CSV, JSON, or Markdown for stakeholder reporting.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js export
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:export FORMAT=csv|json|md [EPIC=...] [STATUS=...] [OWNER=...]`
-**Purpose**: Export filtered stories to CSV, JSON, or Markdown files
-
-### Flow
-1. Parse FORMAT and optional filters
-2. Read status.json
-3. Apply filters (epic, status, owner)
-4. Generate output in requested format
-5. Save to docs/08-project/exports/export-YYYYMMDD.{csv|json|md}
-6. Show summary and file path
-
-### Critical Rules
-- **Default format**: CSV if not specified
-- **CSV must be Excel-compatible**: Proper quoting, comma-separated
-- **JSON mirrors status.json**: Filtered subset of stories structure
-- **Markdown generates table**: Paste-ready for docs/reports
-- **Always show count**: "Exported N stories to <path>"
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Arguments
-
-| Argument | Required | Default | Description |
-|----------|----------|---------|-------------|
-| FORMAT | No | csv | Output format: `csv`, `json`, or `md` |
-| EPIC | No | all | Filter by epic ID (e.g., EP-0041) |
-| STATUS | No | all | Filter by status: ready, in_progress, blocked, done, completed |
-| OWNER | No | all | Filter by owner (e.g., AG-API, AG-UI) |
-
-Multiple filters can be combined. All are AND-joined (stories must match all filters).
-
----
-
-## IMMEDIATE ACTIONS
-
-### Step 1: Parse Arguments
-
-```
-FORMAT = argument or "csv" (default)
-EPIC = optional epic filter
-STATUS = optional status filter
-OWNER = optional owner filter
-```
-
-Validate FORMAT is one of: csv, json, md. If invalid, show error and suggest valid values.
-
-### Step 2: Read and Filter Data
-
-Read `docs/09-agents/status.json` and filter stories:
-
-```javascript
-const data = JSON.parse(fs.readFileSync('docs/09-agents/status.json', 'utf8'));
-let stories = Object.entries(data.stories).map(([id, s]) => ({ id, ...s }));
-
-// Apply filters
-if (EPIC) stories = stories.filter(s => s.epic === EPIC);
-if (STATUS) stories = stories.filter(s => s.status === STATUS);
-if (OWNER) stories = stories.filter(s => s.owner === OWNER);
-```
-
-If no stories match, inform user: "No stories match the given filters."
-
-### Step 3: Generate Output
-
-#### CSV Format
-
-Columns: ID, Title, Epic, Status, Owner, Priority, Estimate
-
-```csv
-ID,Title,Epic,Status,Owner,Priority,Estimate
-US-0380,"Add story:edit and epic:edit commands",EP-0041,done,AG-API,high,3h
-US-0381,"Add status:undo command for story status rollback",EP-0041,done,AG-API,high,2h
-```
-
-Rules:
-- First row is header
-- Quote fields containing commas or quotes
-- Escape quotes by doubling them
-- Use UTF-8 encoding
-
-#### JSON Format
-
-```json
-{
-  "exported_at": "2026-03-03T12:00:00Z",
-  "filters": { "epic": "EP-0041", "status": null, "owner": null },
-  "count": 8,
-  "stories": [
-    {
-      "id": "US-0380",
-      "title": "Add story:edit and epic:edit commands",
-      "epic": "EP-0041",
-      "status": "done",
-      "owner": "AG-API",
-      "priority": "high",
-      "estimate": "3h"
-    }
-  ]
-}
-```
-
-#### Markdown Format
-
-```markdown
-# Story Export - 2026-03-03
-
-**Filters**: Epic: EP-0041
-**Count**: 8 stories
-
-| ID | Title | Epic | Status | Owner | Priority | Estimate |
-|----|-------|------|--------|-------|----------|----------|
-| US-0380 | Add story:edit and epic:edit commands | EP-0041 | done | AG-API | high | 3h |
-| US-0381 | Add status:undo command | EP-0041 | done | AG-API | high | 2h |
-```
-
-### Step 4: Save Output
-
-Create output directory if needed:
-```bash
-mkdir -p docs/08-project/exports
-```
-
-Save to: `docs/08-project/exports/export-YYYYMMDD.{csv|json|md}`
-
-If file already exists for today, append a counter: `export-YYYYMMDD-2.csv`
-
-### Step 5: Show Summary
-
-```
-Exported 8 stories to docs/08-project/exports/export-20260303.csv
-
-Filters applied:
-  Epic: EP-0041
-  Status: all
-  Owner: all
-
-Preview (first 3 rows):
-  US-0380 | Add story:edit and epic:edit commands | done
-  US-0381 | Add status:undo command | done
-  US-0382 | Add export command | in_progress
-```
-
-Then offer next steps:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Export complete. What next?",
-  "header": "Next steps",
-  "multiSelect": false,
-  "options": [
-    {"label": "Open/view the exported file", "description": "Display full file contents"},
-    {"label": "Export in another format", "description": "Re-export as json/md/csv"},
-    {"label": "Done", "description": "Export saved successfully"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-## Example Usage
-
-```bash
-# Export all stories as CSV (default)
-/agileflow:export
-
-# Export specific epic as JSON
-/agileflow:export FORMAT=json EPIC=EP-0041
-
-# Export ready stories as Markdown
-/agileflow:export FORMAT=md STATUS=ready
-
-# Export specific owner's stories as CSV
-/agileflow:export OWNER=AG-API STATUS=done
-
-# Combine filters
-/agileflow:export FORMAT=md EPIC=EP-0041 STATUS=ready OWNER=AG-API
-```
-
----
-
-## Rules
-
-- **CSV Excel-compatible**: Proper quoting, commas, UTF-8
-- **JSON well-formed**: Pretty-printed, includes metadata
-- **Markdown paste-ready**: Standard table format
-- **Always show preview**: Display first few rows after export
-- **Always show path**: User needs to know where the file is
-- **No destructive overwrites**: Counter suffix for same-day exports
-
----
-
-## Related Commands
-
-- `/agileflow:story:list` - Interactive story listing
-- `/agileflow:epic:list` - Interactive epic listing
-- `/agileflow:board` - Visual kanban board
-- `/agileflow:sprint` - Sprint planning view
-- `/agileflow:changelog` - Generate changelog