agileflow 2.77.0 → 2.79.0

package/src/core/commands/deploy.md

@@ -1,6 +1,20 @@
 ---
 description: Set up automated deployment pipeline
 argument-hint: (no arguments)
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Auto-detect project type (static, full-stack, mobile, containers, serverless)"
+    - "Recommend deployment platform based on project (Vercel for Next.js, Netlify for static, Railway for containers)"
+    - "ALWAYS show configuration preview and wait for YES/NO before creating files"
+    - "Generate platform-specific config (vercel.json, netlify.toml, Dockerfile, etc.)"
+    - "Create .env.example template with all required secrets (never commit actual secrets)"
+    - "Create CI/CD workflow (.github/workflows/deploy.yml) with staging+production environments"
+  state_fields:
+    - project_type
+    - detected_platform
+    - environments_configured
+    - secrets_template_created
 ---
 
 # setup-deployment
@@ -15,89 +29,218 @@ If the user confirms they want the full details, continue. Otherwise, stop here.
 Automatically set up deployment pipeline for the project.
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Purpose**: Auto-configure CI/CD deployment pipeline for your project type
+## ⚠️ COMPACT SUMMARY - /agileflow:setup-deployment IS ACTIVE
+
+**CRITICAL**: You are configuring deployment pipeline for production. Auto-detection determines platform; always show preview before creating files.
+
+**ROLE**: Deployment Configurator - Auto-detect project type, recommend platform, generate configs, create CI/CD workflow
+
+---
+
+### 🚨 RULE #1: AUTO-DETECT PROJECT TYPE
+
+Always detect first (before prompting for platform):
+- **Static**: package.json + only build script (no server)
+- **Full-stack**: Express/FastAPI/Next.js API routes
+- **Mobile**: expo config or react-native
+- **Containers**: Dockerfile present
+- **Serverless**: Lambda functions or serverless.yml
+
+If unclear, ask user: "Is this [static/full-stack/containers]?"
+
+---
+
+### 🚨 RULE #2: PLATFORM RECOMMENDATIONS
+
+| Project Type | Recommended | Reason |
+|---|---|---|
+| Next.js | **Vercel** | Built for Next.js, no config needed |
+| React SPA | **Netlify** | Static + built-in redirects |
+| Node.js server | **Railway** | Cheap, Docker-based, easy |
+| Docker container | **Fly.io** | Native container support |
+| Expo/React Native | **EAS** | Official Expo deployment |
+| AWS preference | **Lambda + API Gateway** | FaaS with full control |
+
+---
+
+### 🚨 RULE #3: DIFF-FIRST PATTERN
+
+ALWAYS preview all generated files before creating:
 
-**Quick Usage**:
 ```
-/agileflow:setup-deployment PLATFORM=auto ENV=both AUTO_DEPLOY=no
+Deployment Setup for: Next.js web app
+Recommended platform: Vercel
+
+Will create:
+✓ vercel.json (deployment config)
+✓ .github/workflows/deploy.yml (CI/CD)
+✓ .env.example (secrets template)
+✓ docs/02-practices/deployment.md (guide)
+
+Environments:
+• Staging: staging.example.com (branch: staging)
+• Production: example.com (branch: main)
+
+Proceed? (YES/NO)
 ```
 
-**What It Does**:
-1. Detects project type (static, full-stack, mobile, containers, serverless)
-2. Recommends deployment platform based on project
-3. Generates platform-specific configuration files
-4. Creates CI/CD workflow file
-5. Creates .env.example and secrets management docs
-6. Shows configuration preview
-7. Creates files after YES/NO confirmation
-8. Displays next steps (add secrets, connect repo, test deploy)
-
-**Required Inputs**:
-- None (all optional with auto-detection)
-
-**Optional Inputs**:
-- `PLATFORM=auto|vercel|netlify|heroku|aws|gcp|docker|eas` (default: auto)
-- `ENV=staging|production|both` (default: both)
-- `AUTO_DEPLOY=yes|no` (default: no, manual trigger)
-
-**Output Files**:
-- Platform config (vercel.json, netlify.toml, Dockerfile, etc.)
-- `.github/workflows/deploy.yml` - CI/CD workflow
-- `.env.example` - Secrets template
-- `docs/02-practices/deployment.md` - Deployment guide
-- `docs/02-practices/secrets-management.md` - Secrets guide
-
-**Platform Recommendations**:
-- Next.js / React → Vercel
-- Static sites → Netlify
-- Node.js server → Railway, Heroku
-- Docker apps → Fly.io
-- Mobile (Expo) → EAS
-- Serverless → AWS Lambda, Vercel Functions
-
-**Tools Used**:
-- TodoWrite: Track 8-step deployment setup workflow
-
-**TodoWrite Example**:
+Then ask: "Create deployment configuration? (YES/NO)"
+
+---
+
+### 🚨 RULE #4: ENVIRONMENT CONFIGURATION
+
+Always create BOTH environments (unless ENV=production specified):
+
+**Staging**:
+- Branch: staging
+- URL: staging.example.com or staging.vercel.app
+- Database: Staging DB
+- Secrets from: STAGING_* variables
+
+**Production**:
+- Branch: main
+- URL: example.com
+- Database: Production DB
+- Secrets from: PROD_* variables
+
+Both workflows deploy automatically on push.
+
+---
+
+### 🚨 RULE #5: SECRETS MANAGEMENT
+
+**NEVER** commit actual secrets to git:
+1. Create `.env.example` with placeholder values
+2. Create `docs/02-practices/secrets-management.md` with instructions
+3. Show user how to add secrets to platform:
+   - Vercel: `vercel env add DATABASE_URL`
+   - Heroku: `heroku config:set DATABASE_URL=...`
+   - GitHub Actions: Settings → Secrets → Actions
+
+---
+
+### 🚨 RULE #6: USE TodoWrite FOR TRACKING
+
+Track all 8 steps explicitly:
 ```xml
 <invoke name="TodoWrite">
 <parameter name="content">
-1. Detect project type (static, full-stack, mobile, containers, serverless)
-2. Recommend platform based on project type
-3. Generate deployment configuration files
-4. Create CI/CD workflow file
-5. Create .env.example and secrets management docs
-6. Show configuration preview
-7. Create files after YES/NO confirmation
-8. Display next steps (add secrets, connect repo, test deploy)
+1. Detect project type
+2. Recommend platform
+3. Generate config files
+4. Create CI/CD workflow
+5. Create .env.example
+6. Create deployment docs
+7. Show preview + confirm
+8. Display next steps
 </parameter>
 <parameter name="status">in-progress</parameter>
 </invoke>
 ```
 
-**Workflow**:
-1. Detect project type from package.json, Dockerfile, etc.
-2. Recommend deployment platform
-3. Generate platform-specific config files
-4. Create CI/CD workflow (staging + production)
-5. Create environment management templates
-6. Show preview of all files
-7. Ask: "Create deployment configuration? (YES/NO)"
-8. If YES: Write files and show next steps
-
-**Example Next Steps**:
+---
+
+### ANTI-PATTERNS (DON'T DO THESE)
+
+❌ Skip platform detection, use user's first choice
+❌ Create files without preview
+❌ Hardcode secrets in config files
+❌ Only create production environment
+❌ Forget to create .env.example template
+❌ Create deployment docs without next steps
+
+### DO THESE INSTEAD
+
+✅ Auto-detect project type first
+✅ Show full preview before creating
+✅ Use .env.example with placeholders
+✅ Create staging + production (unless specified)
+✅ Create .env.example + secrets management guide
+✅ Display clear next steps checklist
+
+---
+
+### WORKFLOW PHASES
+
+**Phase 1: Detection (Steps 1-2)**
+- Scan for package.json, Dockerfile, etc.
+- Detect project type
+- Recommend platform
+
+**Phase 2: Generation (Steps 3-6)**
+- Generate platform-specific config
+- Generate CI/CD workflow with both envs
+- Generate .env.example with all required vars
+- Generate deployment guide
+
+**Phase 3: Preview & Confirm (Step 7)**
+- Display all files side-by-side
+- Ask: "Create deployment configuration? (YES/NO)"
+
+**Phase 4: Complete (Step 8)**
+- Write all files
+- Display next steps checklist
+
+---
+
+### NEXT STEPS TO DISPLAY
+
 ```
 ✅ Deployment configured for Vercel!
 
 Next steps:
-1. Add secrets: vercel env add DATABASE_URL
-2. Link repo: vercel link
-3. Test deploy: git push origin staging
-4. Check logs: vercel logs
-5. Deploy prod: merge staging → main
+
+1. Add secrets to Vercel:
+   vercel env add DATABASE_URL production
+   vercel env add API_KEY production
+   [... more secrets from .env.example]
+
+2. Link repository to Vercel:
+   vercel link
+
+3. Test staging deploy:
+   git checkout -b staging
+   git push origin staging
+   Check: https://staging.vercel.app
+
+4. Test production deploy:
+   git push origin main
+   Check: https://example.com
+
+5. Set up custom domain (if needed):
+   vercel domains add example.com
+
+Documentation: docs/02-practices/deployment.md
+Secrets guide: docs/02-practices/secrets-management.md
 ```
+
+---
+
+### KEY FILES TO REMEMBER
+
+| File | Purpose |
+|------|---------|
+| `vercel.json` (or platform equivalent) | Deployment configuration |
+| `.github/workflows/deploy.yml` | CI/CD workflow for both environments |
+| `.env.example` | Template for all required secrets |
+| `docs/02-practices/deployment.md` | Team deployment guide |
+| `docs/02-practices/secrets-management.md` | How to add secrets |
+
+---
+
+### REMEMBER AFTER COMPACTION
+
+- `/agileflow:setup-deployment` IS ACTIVE - configure deployment
+- Always auto-detect project type first
+- Recommend appropriate platform based on type
+- ALWAYS show preview before creating files
+- Create BOTH staging and production (unless specified)
+- Create .env.example template (never commit actual secrets)
+- Use TodoWrite to track 8 steps
+- Display next steps with exact commands
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/deps.md

@@ -2,6 +2,21 @@
 description: Visualize dependency graph with critical path detection
 argument-hint: [SCOPE=story|epic|all] [EPIC=<id>] [STORY=<id>] [FORMAT=ascii|mermaid|graphviz|json] [ANALYSIS=critical-path|circular|blocking|all]
 model: haiku
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Parse dependencies from TWO sources: 1) Story frontmatter (depends_on/blocks fields), 2) Bus log (implicit blocked events)"
+    - "Build adjacency list graph and run DFS for critical path analysis"
+    - "Detect circular dependencies as ERRORS (cannot complete - flag prominently)"
+    - "Calculate blocking impact: stories that block multiple others are bottlenecks"
+    - "Generate ASCII tree with legend, critical path highlighted, blocking stories marked"
+    - "Support multiple formats: ascii (default), mermaid, graphviz, json"
+    - "Provide actionable recommendations: work on blockers first, parallelize independent stories"
+  state_fields:
+    - scope_analyzed
+    - circular_deps_detected
+    - critical_path_calculated
+    - blocking_stories_identified
 ---
 
 # dependencies

package/src/core/commands/diagnose.md

@@ -1,5 +1,21 @@
 ---
 description: System health diagnostics
+compact_context:
+  priority: high
+  preserve_rules:
+    - "No arguments required - runs full system diagnostics automatically"
+    - "Run 4 validation checks: JSON files, auto-archival, hooks system, file sizes"
+    - "JSON Validation CRITICAL - validate status.json, metadata, settings with jq empty"
+    - "Auto-Archival System - check script executable and hook configuration"
+    - "Hooks System - validate .claude/settings.json structure"
+    - "File Size Analysis - warn if status.json exceeds 100KB"
+    - "Report issues with indicators: ✅ (pass), ❌ (fail), ⚠️ (warn), ℹ️ (info)"
+    - "Exit code 0 (healthy) or 1 (issues found)"
+  state_fields:
+    - total_checks
+    - passed_checks
+    - warning_count
+    - failure_count
 ---
 
 # diagnose

package/src/core/commands/docs.md

@@ -1,6 +1,21 @@
 ---
 description: Synchronize documentation with code changes
 argument-hint: [BRANCH=<name>] [BASE=<branch>] [AUTO_CREATE=yes|no]
+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"
+    - "ALWAYS use diff-first, YES/NO pattern before writing"
+    - "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
@@ -18,76 +33,180 @@ node .agileflow/scripts/obtain-context.js docs
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-
-**Purpose**: Automatically detect code changes and synchronize documentation to prevent drift.
-
-**Core Workflow**:
-1. Activate command using STEP 0 registration script
-2. Compare branch against base using git diff
-3. Categorize changes (API, UI, services, config, database)
-4. Map code changes to expected documentation locations
-5. Analyze gaps (missing docs, outdated docs, deprecated references)
-6. Generate gap report with status indicators (❌ missing, ⚠️ incomplete, ✅ up-to-date)
-7. Preview suggested documentation updates
-8. Get explicit user approval before making changes
-
-**Critical Rules**:
-- NEVER delete documentation without explicit user approval
-- ALWAYS use diff-first, YES/NO pattern for all modifications
-- PRESERVE custom content - don't overwrite manually written sections
-- USE managed section markers: `<!-- MANAGED:section-id --> ... <!-- /MANAGED -->`
-- LINK docs to source files for traceability
-- INFER documentation from TypeScript types, JSDoc, OpenAPI decorators, test files
-
-**Expected Documentation Mapping**:
-- API endpoints → `docs/04-architecture/api.md` or OpenAPI spec
-- UI components → `docs/04-architecture/components.md` or Storybook
-- Services/utilities → `docs/04-architecture/services.md`
-- Configuration → `docs/02-practices/configuration.md`
-- Database migrations → `docs/04-architecture/database.md`
-
-**Smart Inference Sources**:
-- TypeScript types and interfaces
-- JSDoc comments and annotations
-- OpenAPI/Swagger decorators
-- Function signatures and parameters
-- Test files as usage examples
-
-**Auto-Create Mode** (AUTO_CREATE=yes):
-- Creates all missing documentation automatically
-- Marks sections with "TODO: Add details" for manual review
-- Commits with message: "docs: sync with codebase changes"
-
-**Integration Features**:
-- Create tracking story for significant doc gaps
-- Log to agent bus: `{"type":"docs-sync","missing":N,"outdated":N}`
-- Suggest PR checklist item: "- [ ] Documentation updated"
-- Recommend CI integration for automated checks
-
-**Gap Report Format**:
+
+## ⚠️ 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**: <name> | **Base**: <branch> | **Generated**: <timestamp>
+**Branch**: feature/auth | **Base**: main | **Generated**: 2025-12-22T10:30Z
 
-## Missing Documentation
-### API Endpoints (N)
-- ❌ POST /endpoint (src/path/file.ts)
+## 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
-- 📄 Deprecated references to removed code
+## Outdated Documentation (1)
+- 📄 Mentions /api/v1/login (removed in this branch)
 
-## Up-to-Date
-- ✅ Correctly documented components
+## 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.
 ```
 
-**Output Deliverables**:
-- Markdown gap report with categorized findings
-- List of recommended actions with previews
-- Optional: Pull request with documentation updates (if approved)
+---
 
-**Tool Usage Example**:
-When asking for approval before creating docs:
+### 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
+
+**TodoWrite** (to track sync process):
+```xml
+<invoke name="TodoWrite">
+<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">[{
@@ -95,14 +214,27 @@ When asking for approval before creating docs:
   "header": "Documentation Sync",
   "multiSelect": false,
   "options": [
-    {"label": "Create all missing docs", "description": "Auto-generate stubs for all missing documentation"},
-    {"label": "Review each one first", "description": "Preview each change before creating"},
+    {"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 -->
 
 ---