agileflow 3.4.2 → 4.0.0-alpha.1

package/src/core/commands/docs.md

@@ -1,469 +0,0 @@
----
-description: Synchronize documentation with code changes
-phase: post-impl
-argument-hint: "[BRANCH=<name>] [BASE=<branch>] [AUTO_CREATE=true|false]"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "Compare BRANCH against BASE using git diff"
-    - "Categorize changes: API, UI, services, config, database"
-    - "Generate gap report: missing, outdated, up-to-date docs"
-    - "NEVER delete docs without explicit approval"
-    - "{{RULES:file_preview}}"
-    - "PRESERVE custom content - use managed section markers"
-    - "INFER docs from TypeScript types, JSDoc, OpenAPI, tests"
-    - "Optional AUTO_CREATE mode auto-generates all missing docs"
-  state_fields:
-    - branch_name
-    - base_branch
-    - auto_create_flag
----
-
-# docs-sync
-
-Synchronize documentation with codebase changes.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js docs
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-
-## ⚠️ COMPACT SUMMARY - /agileflow:docs-sync IS ACTIVE
-
-**CRITICAL**: You are detecting code changes and synchronizing documentation. Goal: prevent documentation drift.
-
-**ROLE**: Documentation Synchronizer
-
----
-
-### 🚨 RULE #1: COMPARE BRANCHES AND DETECT CHANGES
-
-Use git diff to compare BRANCH against BASE:
-
-```bash
-git diff <BASE>...<BRANCH> --name-status
-```
-
-Categorize changes:
-- **API endpoints**: src/api/, src/routes/, src/controllers/
-- **UI components**: src/components/, src/pages/
-- **Services**: src/services/, src/utils/
-- **Config**: *.config.js, *.yml, .env.example
-- **Database**: migrations/, schema/
-
----
-
-### 🚨 RULE #2: MAP TO EXPECTED DOCUMENTATION
-
-For each changed file, map to expected docs:
-
-| Code Change | Expected Doc Location | Gap Status |
-|-------------|----------------------|-----------|
-| New API endpoint | docs/04-architecture/api.md | Check section exists |
-| New UI component | docs/04-architecture/components.md | Check section exists |
-| New service/utility | docs/04-architecture/services.md | Check section exists |
-| Config change | docs/02-practices/configuration.md | Check referenced |
-| Database migration | docs/04-architecture/database.md | Check documented |
-
----
-
-### 🚨 RULE #3: GENERATE GAP REPORT
-
-Always create gap report showing status for each change:
-
-```markdown
-# Documentation Sync Report
-**Branch**: feature/auth | **Base**: main | **Generated**: 2025-12-22T10:30Z
-
-## Missing Documentation (3)
-- ❌ POST /api/auth/login (src/api/auth/login.ts)
-- ❌ LoginForm component (src/components/LoginForm.tsx)
-- ❌ JWT_SECRET env var (.env.example)
-
-## Outdated Documentation (1)
-- 📄 Mentions /api/v1/login (removed in this branch)
-
-## Up-to-Date (2)
-- ✅ UserAvatar component documented
-- ✅ Database schema up-to-date
-```
-
----
-
-### 🚨 RULE #4: NEVER DELETE WITHOUT APPROVAL
-
-**CRITICAL**: When docs are removed or changed:
-1. Show diff to user
-2. Ask explicit approval: "Delete this section? (YES/NO)"
-3. Only delete if user approves
-
-❌ WRONG: Remove outdated docs without asking
-✅ RIGHT: Show diff, ask approval, delete only if approved
-
----
-
-### 🚨 RULE #5: DIFF-FIRST, YES/NO PATTERN
-
-**ALWAYS follow this pattern:**
-
-1. Generate all proposed changes in memory (don't write)
-2. Show diff/preview to user
-3. Ask: "Create missing documentation? (YES/NO)"
-4. Only write files if user says YES
-
----
-
-### 🚨 RULE #6: SMART INFERENCE
-
-Infer documentation from code sources:
-
-**From TypeScript**:
-```typescript
-// Code:
-export interface User {
-  id: string;
-  email: string;
-  name: string;
-}
-
-// Generated doc:
-## User Interface
-- id (string) - Unique user identifier
-- email (string) - User email address
-- name (string) - User full name
-```
-
-**From JSDoc**:
-```typescript
-/**
- * Authenticates user with email and password
- * @returns JWT token and user profile
- */
-export async function login(email: string, password: string)
-
-// Generated doc:
-POST /api/auth/login
-Authenticates user with email and password.
-Returns JWT token and user profile.
-```
-
----
-
-### ANTI-PATTERNS (DON'T DO THESE)
-
-❌ Delete docs without approval
-❌ Skip diff-first pattern
-❌ Overwrite manually written sections
-❌ Create vague doc stubs ("TODO: Add details")
-❌ Ignore outdated documentation
-❌ Skip gap report
-
-### DO THESE INSTEAD
-
-✅ Always ask before deleting
-✅ Show diffs for user approval
-✅ Preserve custom content
-✅ Generate complete doc stubs from code
-✅ Flag outdated docs clearly
-✅ Create comprehensive gap report
-
----
-
-### WORKFLOW
-
-1. **Get Diff**: Compare BRANCH vs BASE with git diff
-2. **Categorize**: Group changes by type (API, UI, services, etc.)
-3. **Map**: For each change, identify expected doc location
-4. **Analyze**: Check if docs exist, are current, or are missing
-5. **Report**: Generate gap report with status indicators
-6. **Preview**: Show all proposed changes to user
-7. **Ask**: "Create missing documentation? (YES/NO)"
-8. **Create**: Only if user approves - generate stubs from code
-9. **Commit**: If AUTO_CREATE=yes, commit with message "docs: sync with codebase changes"
-
----
-
-### TOOL USAGE EXAMPLES
-
-**TaskCreate/TaskUpdate** (to track sync process):
-```xml
-<invoke name="TaskCreate/TaskUpdate">
-<parameter name="content">1. Get git diff between BASE and BRANCH
-2. Categorize changes (API, UI, services, config, DB)
-3. Map to expected documentation locations
-4. Analyze gaps (missing, outdated, current)
-5. Generate gap report
-6. Preview proposed changes
-7. Get user approval
-8. Create docs if approved</parameter>
-<parameter name="status">in-progress</parameter>
-</invoke>
-```
-
-**AskUserQuestion** (for approval):
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Create missing documentation for detected code changes?",
-  "header": "Documentation Sync",
-  "multiSelect": false,
-  "options": [
-    {"label": "Create all missing docs", "description": "Auto-generate stubs from code"},
-    {"label": "Review each one first", "description": "Preview changes before creating"},
-    {"label": "Skip documentation", "description": "Don't create docs now"}
-  ]
-}]</parameter>
-</invoke>
-```
-
----
-
-### REMEMBER AFTER COMPACTION
-
-- `/agileflow:docs-sync` IS ACTIVE
-- Compare BRANCH vs BASE with git diff
-- Categorize changes (API, UI, services, etc.)
-- Generate gap report (missing, outdated, current)
-- Never delete docs without approval
-- Use diff-first, YES/NO pattern
-- Infer docs from code (TypeScript, JSDoc, tests)
-- Optional AUTO_CREATE auto-generates all missing docs
-
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Prompt
-
-ROLE: Documentation Synchronizer
-
-OBJECTIVE
-Detect code changes and ensure corresponding documentation is created or updated.
-
-INPUTS (optional)
-- BRANCH=<branch name> (default: current branch)
-- BASE=<base branch> (default: main/master)
-- AUTO_CREATE=yes|no (default: no, ask first)
-
-DETECTION WORKFLOW
-1. Get git diff between BASE and BRANCH:
-   ```bash
-   git diff <BASE>...<BRANCH> --name-status
-   ```
-
-2. Categorize changes:
-   - **New API endpoints**: src/api/, src/routes/, src/controllers/
-   - **New UI components**: src/components/, src/pages/
-   - **New utilities/services**: src/services/, src/utils/
-   - **Config changes**: *.config.js, *.yml, .env.example
-   - **Database changes**: migrations/, schema/
-
-3. Map to expected docs:
-   - API endpoints → docs/04-architecture/api.md or OpenAPI spec
-   - UI components → docs/04-architecture/components.md or Storybook
-   - Services → docs/04-architecture/services.md
-   - Config → docs/02-practices/configuration.md
-   - Migrations → docs/04-architecture/database.md
-
-ANALYSIS
-For each changed file:
-```
-File: src/api/auth/login.ts (ADDED)
-Expected doc: docs/04-architecture/api.md
-Section: Authentication Endpoints
-Status: ❌ MISSING (section exists but endpoint not documented)
-
-Suggestion:
-## POST /api/auth/login
-**Added**: <date>
-**Story**: <US_ID if found in commit>
-
-Request:
-\`\`\`json
-{ "email": "string", "password": "string" }
-\`\`\`
-
-Response:
-\`\`\`json
-{ "token": "string", "user": {...} }
-\`\`\`
-
-Authentication: None (public endpoint)
-Rate limit: 5 requests/minute
-```
-
-GAP REPORT
-```markdown
-# Documentation Sync Report
-
-**Branch**: <BRANCH>
-**Base**: <BASE>
-**Generated**: <ISO timestamp>
-
-## Missing Documentation
-
-### API Endpoints (3)
-- ❌ POST /api/auth/login (src/api/auth/login.ts)
-- ❌ GET /api/users/:id (src/api/users/get.ts)
-- ❌ DELETE /api/sessions (src/api/sessions/delete.ts)
-
-### UI Components (2)
-- ❌ LoginForm (src/components/LoginForm.tsx)
-- ⚠️ UserProfile (src/components/UserProfile.tsx) - stub exists, needs details
-
-### Configuration (1)
-- ❌ New env var: JWT_SECRET (.env.example)
-
-## Outdated Documentation
-
-### Deprecated
-- 📄 docs/04-architecture/api.md mentions /api/v1/login (removed in this branch)
-
-## Up-to-Date
-- ✅ UserAvatar component documented
-- ✅ Database schema up-to-date
-```
-
-ACTIONS (after user review)
-1. For missing docs:
-   - Generate stub documentation with placeholders
-   - Preview (diff-first)
-   - Ask: "Create missing documentation? (YES/NO)"
-
-2. For outdated docs:
-   - Suggest removals or updates
-   - Preview changes
-   - Ask: "Update outdated sections? (YES/NO)"
-
-3. If AUTO_CREATE=yes:
-   - Create all missing docs automatically
-   - Mark sections with "TODO: Add details" for manual review
-   - Commit: "docs: sync with codebase changes"
-
-SMART INFERENCE
-Try to infer documentation from:
-- TypeScript types/interfaces
-- JSDoc comments
-- OpenAPI decorators
-- Function signatures
-- Test files (use as examples)
-
-Example:
-```typescript
-// Code: src/api/auth/login.ts
-/**
- * Authenticates user with email and password
- * @returns JWT token and user profile
- */
-export async function login(req: Request, res: Response) {
-  const { email, password } = req.body;
-  // ...
-}
-
-// Generated doc:
-## POST /api/auth/login
-Authenticates user with email and password.
-Returns JWT token and user profile.
-```
-
-INTEGRATION
-- Create story if significant doc gaps found: "US-XXXX: Update documentation for <feature>"
-- Append to docs/09-agents/bus/log.jsonl: {"type":"docs-sync","missing":3,"outdated":1}
-- Optionally add to PR checklist: "- [ ] Documentation updated"
-
-CI INTEGRATION
-Suggest adding to PR checks:
-```yaml
-- name: Check docs sync
-  run: npx claude-code /agileflow:docs-sync BRANCH=${{ github.head_ref }}
-  # Fail if critical docs missing (e.g., public API endpoints)
-```
-
-RULES
-- Never delete docs without explicit approval
-- Preserve custom content (don't overwrite manually written sections)
-- Use managed section markers: <!-- MANAGED:api-endpoints --> ... <!-- /MANAGED -->
-- Link docs to source files for traceability
-- Diff-first, YES/NO for all changes
-
-OUTPUT
-- Gap report (markdown)
-- List of actions to take
-- Optional: PR with doc updates (if approved)
-
----
-
-## Expected Output
-
-### Success - Gap Analysis
-
-```
-📚 Documentation Gap Analysis
-══════════════════════════════════════════════════════════════
-
-Scanning codebase...
-✓ Found 45 exported functions
-✓ Found 12 API endpoints
-✓ Found 8 React components
-
-📊 Coverage Report:
-┌────────────────────┬────────────┬────────────┬───────────┐
-│ Category           │ Documented │ Total      │ Coverage  │
-├────────────────────┼────────────┼────────────┼───────────┤
-│ API Endpoints      │ 10         │ 12         │ 83% 🟡    │
-│ Public Functions   │ 38         │ 45         │ 84% 🟡    │
-│ React Components   │ 8          │ 8          │ 100% 🟢   │
-│ README files       │ 5          │ 8          │ 63% 🔴    │
-└────────────────────┴────────────┴────────────┴───────────┘
-
-🔴 Missing Documentation:
-1. POST /api/orders/bulk - No JSDoc or OpenAPI spec
-2. POST /api/webhooks/stripe - No JSDoc or OpenAPI spec
-3. docs/06-stories/README.md - Folder missing README
-4. docs/07-testing/README.md - Folder missing README
-
-Generate missing docs? [Y/n]
-```
-
-### Success - Docs Updated
-
-```
-📚 Documentation Update
-══════════════════════════════════════════════════════════════
-
-✓ Updated docs/api/orders.md (added bulk endpoint)
-✓ Created docs/06-stories/README.md
-✓ Created docs/07-testing/README.md
-✓ Regenerated docs/api/openapi.yaml
-
-4 files updated.
-Coverage: 63% → 88% (+25%)
-```
-
-### Error - Source Not Found
-
-```
-❌ Error: Source directory not found
-
-Path: src/api/
-
-Please verify project structure or specify source:
-/agileflow:docs SOURCE=lib/
-```
-
----
-
-## Related Commands
-
-- `/agileflow:readme-sync` - Sync folder README with contents
-- `/agileflow:changelog` - Generate changelog from commits
-- `/agileflow:update` - Generate stakeholder progress report
-- `/agileflow:template` - Manage custom templates
-- `/agileflow:pr` - Generate pull request from story

package/src/core/commands/epic/edit.md

@@ -1,213 +0,0 @@
----
-description: Edit an existing epic's fields (title, owner, goal, status)
-argument-hint: "EPIC=<EP-ID> [TITLE=<text>] [OWNER=<id>] [GOAL=<text>] [STATUS=<status>]"
-compact_context:
-  priority: high
-  preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:epic:edit - Edit epic fields with diff-preview-confirm"
-    - "{{RULES:json_operations}}"
-    - "{{RULES:user_confirmation}}"
-    - "{{RULES:file_preview}}"
-    - "MUST read current epic from status.json BEFORE proposing changes"
-    - "MUST show diff of old vs new values"
-    - "MUST confirm with AskUserQuestion before writing"
-    - "MUST log edit event to bus/log.jsonl"
-    - "MUST update epic file in docs/05-epics/ if it exists"
-  state_fields:
-    - epic_id
-    - fields_changed
----
-
-# /agileflow:epic:edit
-
-Edit an existing epic's metadata fields with diff preview and confirmation.
-
----
-
-## STEP 0: Gather Context
-
-```bash
-node .agileflow/scripts/obtain-context.js epic:edit
-```
-
----
-
-<!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Command**: `/agileflow:epic:edit EPIC=<EP-ID> [TITLE=...] [OWNER=...] [GOAL=...] [STATUS=...]`
-**Purpose**: Edit epic fields in status.json with diff-preview-confirm workflow
-
-### Flow
-1. Parse EPIC parameter (required) and optional field overrides
-2. Read current epic from status.json
-3. Show diff of proposed changes
-4. Confirm via AskUserQuestion
-5. Apply changes to status.json
-6. Update epic file in docs/05-epics/ if it exists
-7. Log edit event to bus/log.jsonl
-
-### Critical Rules
-- **Diff preview**: Always show old vs new before writing
-- **Confirmation**: Never write without user approval
-- **Bus logging**: Always append epic-edited event
-- **Epic file sync**: Update markdown file if it exists
-- **Validation**: Verify JSON integrity after write
-<!-- COMPACT_SUMMARY_END -->
-
----
-
-## Arguments
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| EPIC | Yes | Epic ID (e.g., EP-0041) |
-| TITLE | No | New epic title |
-| OWNER | No | New owner (e.g., AG-DEVOPS, AG-API) |
-| GOAL | No | New epic goal description |
-| STATUS | No | New status (ready, active, complete, on-hold) |
-
-At least one optional field must be provided (otherwise suggest `/agileflow:epic:view`).
-
----
-
-## IMMEDIATE ACTIONS
-
-### Step 1: Validate Input
-
-If EPIC not provided:
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Which epic would you like to edit?",
-  "header": "Select",
-  "multiSelect": false,
-  "options": [
-    {"label": "Enter epic ID", "description": "Provide an EP-XXXX identifier"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-### Step 2: Read Current Epic
-
-Read the epic entry from `docs/09-agents/status.json`:
-
-```javascript
-const data = JSON.parse(fs.readFileSync('docs/09-agents/status.json', 'utf8'));
-const epic = data.epics[epicId];
-```
-
-If epic not found, show error: "Epic {EPIC} not found in status.json"
-
-### Step 3: Build Change Set
-
-Compare provided fields against current values. Skip fields that match current values (no-op).
-
-If no fields would change, inform user: "No changes detected. Current values match provided values."
-
-### Step 4: Show Diff Preview
-
-Display a clear diff of what will change:
-
-```markdown
-## Editing EP-0041: Current Title
-
-| Field | Current | New |
-|-------|---------|-----|
-| title | "DX Quick Wins" | "DX Quick Wins - March 2026" |
-| owner | AG-DEVOPS | AG-API |
-| status | ready | active |
-
-Files modified:
-1. docs/09-agents/status.json (epic entry update)
-2. docs/05-epics/EP-0041-*.md (if exists, update frontmatter)
-3. docs/09-agents/bus/log.jsonl (edit event append)
-```
-
-### Step 5: Confirm Changes
-
-```xml
-<invoke name="AskUserQuestion">
-<parameter name="questions">[{
-  "question": "Apply these changes to EP-0041?",
-  "header": "Confirm edit",
-  "multiSelect": false,
-  "options": [
-    {"label": "Yes, apply changes (Recommended)", "description": "Update status.json and log edit event"},
-    {"label": "No, cancel", "description": "Discard changes"}
-  ]
-}]</parameter>
-</invoke>
-```
-
-### Step 6: Apply Changes
-
-On confirmation:
-
-1. **Update status.json** using Edit tool or jq:
-   - Update only the changed fields in the epic entry
-   - Set `updated` timestamp to current ISO date
-
-2. **Update epic file** (if exists in `docs/05-epics/`):
-   - Find matching file: `docs/05-epics/EP-XXXX-*.md`
-   - Update title in heading and frontmatter
-   - Update owner, status, goal fields
-
-3. **Validate JSON**:
-```bash
-node -e "JSON.parse(require('fs').readFileSync('docs/09-agents/status.json','utf8')); console.log('valid')"
-```
-
-4. **Append to bus/log.jsonl**:
-```json
-{"ts":"<ISO>","type":"epic-edited","from":"USER","epic":"<EPIC>","changes":{"field":"old_value->new_value"},"text":"Epic edited: <changed fields>"}
-```
-
-### Step 7: Confirm Success
-
-```
-Epic EP-0041 updated:
-  title: "DX Quick Wins" -> "DX Quick Wins - March 2026"
-  status: ready -> active
-```
-
----
-
-## Example Usage
-
-```bash
-# Edit title
-/agileflow:epic:edit EPIC=EP-0041 TITLE="Updated Title"
-
-# Change owner and status
-/agileflow:epic:edit EPIC=EP-0041 OWNER=AG-API STATUS=active
-
-# Update goal
-/agileflow:epic:edit EPIC=EP-0041 GOAL="New goal description for this epic"
-
-# Multiple fields at once
-/agileflow:epic:edit EPIC=EP-0041 TITLE="New Title" OWNER=AG-UI STATUS=active
-```
-
----
-
-## Rules
-
-- **Always preview**: Show diff before applying
-- **Always confirm**: Use AskUserQuestion before writes
-- **Always log**: Append edit event to bus/log.jsonl
-- **Always validate**: Check JSON integrity after write
-- **Sync epic file**: Update docs/05-epics/ markdown if it exists
-- **No silent changes**: Every change must be visible to the user
-
----
-
-## Related Commands
-
-- `/agileflow:epic:view` - View epic details
-- `/agileflow:epic:list` - List all epics
-- `/agileflow:epic` - Create new epic
-- `/agileflow:story:edit` - Edit story fields
-- `/agileflow:status` - Quick status update