agileflow 2.81.0 → 2.82.1

package/src/core/commands/choose.md

@@ -0,0 +1,337 @@
+---
+description: AI-directed decision making with structured options
+argument-hint: <decision> [context]
+compact_context:
+  priority: normal
+  preserve_rules:
+    - "Present structured options with trade-offs"
+    - "AI selects best option based on context"
+    - "Always explain selection rationale"
+    - "Can delegate to experts for analysis before choosing"
+---
+
+# /agileflow:choose
+
+AI-directed decision making. Use when multiple valid approaches exist and you want Claude to analyze trade-offs and recommend the best option.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js choose
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**Role**: Decision Advisor - Analyze options and recommend best approach
+
+**When to use:**
+- Multiple valid approaches exist
+- Trade-offs need analysis
+- Expert judgment required
+- Not a simple yes/no question
+
+**Choice block syntax:**
+```
+choice **<decision criteria>**:
+  option "<name>":
+    - Description
+    - Trade-offs
+  option "<name>":
+    - Description
+    - Trade-offs
+```
+
+**Output format:**
+```
+## Decision: <question>
+
+### Options Analyzed
+1. Option A: [analysis]
+2. Option B: [analysis]
+
+### Recommendation
+**Selected: Option X**
+Rationale: [why this is best]
+
+### Trade-offs Accepted
+- [trade-off 1]
+- [trade-off 2]
+
+### Next Steps
+1. [action 1]
+2. [action 2]
+```
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Usage
+
+```
+/agileflow:choose <decision>
+/agileflow:choose <decision> CONTEXT=<additional_context>
+```
+
+---
+
+## How It Works
+
+### 1. Analyze the Decision
+
+First, understand what's being decided:
+- What are the constraints?
+- What matters most? (speed, quality, maintainability, etc.)
+- What's the current context?
+
+### 2. Generate Options
+
+For each viable approach:
+- **Name**: Clear label
+- **Description**: What this approach entails
+- **Pros**: Benefits and strengths
+- **Cons**: Drawbacks and risks
+- **Effort**: Relative implementation cost
+- **Risk**: Potential failure modes
+
+### 3. Evaluate Against Criteria
+
+Score each option against relevant factors:
+- **Fit**: How well it matches requirements
+- **Feasibility**: How practical to implement
+- **Future-proof**: How well it handles change
+- **Team capacity**: Skills and time available
+
+### 4. Make Recommendation
+
+Select the best option and explain:
+- Why this option wins
+- What trade-offs are accepted
+- What risks to monitor
+- What next steps to take
+
+---
+
+## Examples
+
+### Performance Optimization
+
+```
+/agileflow:choose best approach to fix slow API response times
+```
+
+**Decision**: Best approach to fix slow API response times
+
+**Options:**
+1. **Add Caching (Redis)**
+   - Pros: Fast reads, reduces DB load
+   - Cons: Cache invalidation complexity, added infrastructure
+   - Effort: Medium
+   - Risk: Stale data issues
+
+2. **Optimize Database Queries**
+   - Pros: Addresses root cause, no new dependencies
+   - Cons: May have diminishing returns, requires deep analysis
+   - Effort: High
+   - Risk: May not be enough
+
+3. **Add Pagination**
+   - Pros: Reduces data transfer, simple to implement
+   - Cons: UI changes needed, doesn't fix underlying issue
+   - Effort: Low
+   - Risk: Just masks the problem
+
+**Recommendation**: Start with **Option 2 (Optimize Queries)**, then add **Option 1 (Caching)** if needed.
+
+**Rationale**: Optimizing queries addresses the root cause. Adding caching on top of slow queries just hides the problem. Start with the foundation, then layer caching for frequently accessed data.
+
+---
+
+### Architecture Decision
+
+```
+/agileflow:choose authentication approach for new API CONTEXT="multi-tenant SaaS, 50K users"
+```
+
+**Decision**: Authentication approach for multi-tenant SaaS (50K users)
+
+**Options:**
+1. **JWT with Short Expiry**
+   - Pros: Stateless, scalable, industry standard
+   - Cons: Can't revoke tokens instantly, need refresh token logic
+   - Effort: Medium
+   - Risk: Token theft requires expiry wait
+
+2. **Session-based Auth**
+   - Pros: Instant revocation, simple mental model
+   - Cons: Server state, horizontal scaling needs session store
+   - Effort: Medium
+   - Risk: Session store becomes bottleneck
+
+3. **OAuth 2.0 with Identity Provider**
+   - Pros: SSO support, enterprise ready, offloads auth complexity
+   - Cons: External dependency, more complex integration
+   - Effort: High
+   - Risk: Vendor lock-in, latency from external calls
+
+**Recommendation**: **Option 3 (OAuth 2.0 with Identity Provider)**
+
+**Rationale**: For multi-tenant SaaS with 50K users:
+- Enterprises will expect SSO
+- Managing auth in-house is a liability
+- Auth0/Okta handle the complexity
+- Worth the integration effort upfront
+
+---
+
+### Development Approach
+
+```
+/agileflow:choose how to implement the new dashboard feature
+```
+
+**Decision**: Development approach for new dashboard
+
+**Options:**
+1. **Quick Prototype**
+   - Pros: Fast iteration, early feedback
+   - Cons: Tech debt, may need rewrite
+   - Effort: Low
+   - Risk: Prototype becomes production
+
+2. **Full Architecture First**
+   - Pros: Solid foundation, scalable
+   - Cons: Slow, may over-engineer
+   - Effort: High
+   - Risk: Analysis paralysis
+
+3. **Incremental TDD**
+   - Pros: Quality + speed balance, refactorable
+   - Cons: Requires discipline, initial slowdown
+   - Effort: Medium
+   - Risk: Tests may constrain design
+
+**Recommendation**: **Option 3 (Incremental TDD)**
+
+**Rationale**: Dashboard is user-facing with many edge cases. TDD ensures:
+- Components work correctly from the start
+- Refactoring is safe when design evolves
+- Tests serve as documentation
+
+---
+
+## Integration with Experts
+
+For complex decisions, delegate analysis to domain experts:
+
+```
+choice **best database for this workload**:
+  experts:
+    - agileflow-database (analyze data patterns)
+    - agileflow-performance (analyze scaling needs)
+  options:
+    - PostgreSQL
+    - MongoDB
+    - DynamoDB
+```
+
+This spawns experts in parallel to analyze, then synthesizes their recommendations.
+
+---
+
+## Choice Block Syntax (Advanced)
+
+For embedding choice blocks in workflows:
+
+```markdown
+## Decision Point
+
+choice **<criteria>**:
+  option "<name>":
+    - Description line 1
+    - Description line 2
+  option "<name>":
+    - Description line 1
+    - Description line 2
+
+### After Choice
+
+Proceed with selected option...
+```
+
+The AI evaluates options against the criteria and selects the best one.
+
+---
+
+## Output Format
+
+Every choice decision outputs:
+
+```markdown
+## Decision: [question]
+
+### Context
+[Summary of situation and constraints]
+
+### Options Analyzed
+
+#### Option 1: [name]
+**Description**: [what it is]
+**Pros**: [benefits]
+**Cons**: [drawbacks]
+**Effort**: [low/medium/high]
+**Risk**: [potential issues]
+
+#### Option 2: [name]
+...
+
+### Analysis
+
+[Comparison matrix or discussion]
+
+### Recommendation
+
+**Selected: [option name]**
+
+**Rationale**: [why this option is best for this situation]
+
+**Trade-offs Accepted**:
+- [trade-off 1]
+- [trade-off 2]
+
+### Next Steps
+1. [immediate action]
+2. [follow-up action]
+3. [verification step]
+```
+
+---
+
+## When NOT to Use
+
+- Simple yes/no questions (just answer directly)
+- Only one viable option (just proceed)
+- User has already decided (just implement)
+- Trivial decisions (don't over-engineer the process)
+
+Use `/agileflow:choose` for decisions that:
+- Have 2+ viable options
+- Involve trade-offs worth analyzing
+- Benefit from structured thinking
+- Need documented rationale
+
+---
+
+## Best Practices
+
+1. **Include context**: More context = better recommendations
+2. **Define success criteria**: What matters most?
+3. **Be honest about trade-offs**: Every option has downsides
+4. **Document decisions**: Use `/agileflow:adr` for important architectural choices
+5. **Revisit decisions**: Circumstances change; choices may need updating

package/src/core/commands/workflow.md

@@ -0,0 +1,344 @@
+---
+description: Define and run parameterized workflow templates
+argument-hint: <template> [arguments...]
+compact_context:
+  priority: normal
+  preserve_rules:
+    - "Workflows are reusable templates with arguments"
+    - "Template format: {{arg_name}} for substitution"
+    - "Built-in workflows: review, test-feature, implement, analyze"
+    - "Custom workflows in docs/08-project/workflows/"
+---
+
+# /agileflow:workflow
+
+Run parameterized workflow templates. Enables DRY patterns for common multi-step operations.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js workflow
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**Role**: Workflow Runner - Execute parameterized templates
+
+**Template syntax**: `{{arg}}` for argument substitution
+
+**Built-in workflows:**
+- `review` - Code review with configurable focus
+- `test-feature` - Test and verify a feature
+- `implement` - Implement a story/feature
+- `analyze` - Analyze codebase for issues
+
+**Usage:**
+```
+/agileflow:workflow review path=src/auth.ts focus=security
+/agileflow:workflow implement story=US-0042
+/agileflow:workflow analyze target=src/**/*.ts type=performance
+```
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Usage
+
+```
+/agileflow:workflow <template> [arg1=value1] [arg2=value2] ...
+```
+
+---
+
+## Built-in Workflows
+
+### review
+
+Review code with configurable focus.
+
+**Arguments:**
+- `path` (required): File or glob pattern to review
+- `focus` (optional): Review focus (security, performance, quality, all)
+
+**Template:**
+```markdown
+## Code Review: {{path}}
+
+Focus: {{focus:all}}
+
+### Steps
+1. Read the target file(s)
+2. Analyze for {{focus}} issues
+3. Generate findings with severity
+4. Suggest fixes
+
+### Experts (parallel, on-fail: continue)
+- agileflow-security (if focus=security|all)
+- agileflow-performance (if focus=performance|all)
+- agileflow-testing (if focus=quality|all)
+```
+
+**Example:**
+```
+/agileflow:workflow review path=src/auth.ts focus=security
+```
+
+---
+
+### test-feature
+
+Test a feature end-to-end.
+
+**Arguments:**
+- `feature` (required): Feature name or path
+- `coverage` (optional): Minimum coverage threshold (default: 80)
+
+**Template:**
+```markdown
+## Test Feature: {{feature}}
+
+Coverage threshold: {{coverage:80}}%
+
+### Steps
+1. Identify test files for feature
+2. Run existing tests
+3. Generate missing tests
+4. Verify coverage >= {{coverage}}%
+
+### Expert: agileflow-testing
+Discretion condition: **coverage above {{coverage}}%**
+```
+
+**Example:**
+```
+/agileflow:workflow test-feature feature=user-auth coverage=90
+```
+
+---
+
+### implement
+
+Implement a story or feature.
+
+**Arguments:**
+- `story` (required): Story ID or description
+- `mode` (optional): Implementation mode (quick, thorough, tdd)
+
+**Template:**
+```markdown
+## Implement: {{story}}
+
+Mode: {{mode:thorough}}
+
+### Steps (based on mode)
+
+#### If mode=quick:
+1. Minimal implementation
+2. Basic tests
+3. Quick review
+
+#### If mode=thorough:
+1. Plan mode first
+2. Full implementation
+3. Comprehensive tests
+4. Code review
+5. Documentation
+
+#### If mode=tdd:
+1. Write tests first
+2. Implement to pass tests
+3. Refactor
+4. Verify coverage
+
+### Expert selection based on story domain
+```
+
+**Example:**
+```
+/agileflow:workflow implement story=US-0042 mode=tdd
+```
+
+---
+
+### analyze
+
+Analyze codebase for issues.
+
+**Arguments:**
+- `target` (required): Path or glob pattern
+- `type` (required): Analysis type (security, performance, complexity, all)
+
+**Template:**
+```markdown
+## Analyze: {{target}}
+
+Type: {{type}}
+
+### Steps
+1. Gather files matching {{target}}
+2. Run {{type}} analysis
+3. Generate report with findings
+4. Prioritize by severity
+
+### Experts (parallel, strategy: all, on-fail: continue)
+- agileflow-security (if type=security|all)
+- agileflow-performance (if type=performance|all)
+- agileflow-refactor (if type=complexity|all)
+
+### Output
+Markdown report with:
+- Summary metrics
+- Findings by severity
+- Recommended actions
+```
+
+**Example:**
+```
+/agileflow:workflow analyze target=src/**/*.ts type=all
+```
+
+---
+
+## Custom Workflows
+
+Create custom workflows in `docs/08-project/workflows/`:
+
+```
+docs/08-project/workflows/
+├── deploy-staging.md
+├── release-check.md
+└── onboard-feature.md
+```
+
+### Custom Workflow Format
+
+```markdown
+---
+name: deploy-staging
+description: Deploy to staging environment
+arguments:
+  - name: version
+    required: true
+    description: Version to deploy
+  - name: notify
+    required: false
+    default: true
+    description: Send Slack notification
+---
+
+# Deploy to Staging: {{version}}
+
+## Pre-checks
+1. Verify tests passing
+2. Check no blocking PRs
+
+## Deployment
+1. Build version {{version}}
+2. Deploy to staging cluster
+3. Run smoke tests
+
+## Post-deploy
+{{#if notify}}
+4. Send Slack notification
+{{/if}}
+```
+
+### Using Custom Workflows
+
+```
+/agileflow:workflow deploy-staging version=2.42.0 notify=false
+```
+
+---
+
+## Advanced Features
+
+### Conditional Sections
+
+Use `{{#if arg}}` for conditional content:
+
+```markdown
+{{#if verbose}}
+### Verbose Output
+Show detailed logs...
+{{/if}}
+```
+
+### Default Values
+
+Use `{{arg:default}}` for default values:
+
+```markdown
+Coverage threshold: {{coverage:80}}%
+Mode: {{mode:thorough}}
+```
+
+### Lists
+
+Use `{{args...}}` for multiple values:
+
+```markdown
+Files to process:
+{{#each files}}
+- {{this}}
+{{/each}}
+```
+
+---
+
+## Workflow Composition
+
+Workflows can reference other workflows:
+
+```markdown
+## Full Release
+
+1. /agileflow:workflow test-feature feature=all coverage=90
+2. /agileflow:workflow analyze target=src type=security
+3. /agileflow:workflow deploy-staging version={{version}}
+```
+
+---
+
+## Workflow Discovery
+
+List available workflows:
+
+```
+/agileflow:workflow --list
+
+Built-in workflows:
+- review: Code review with focus
+- test-feature: Test a feature
+- implement: Implement a story
+- analyze: Analyze codebase
+
+Custom workflows (docs/08-project/workflows/):
+- deploy-staging: Deploy to staging
+- release-check: Pre-release checklist
+```
+
+---
+
+## Best Practices
+
+1. **Use descriptive names**: `deploy-staging` not `ds`
+2. **Document arguments**: Include types and defaults
+3. **Keep workflows focused**: One purpose per workflow
+4. **Use composition**: Build complex flows from simple ones
+5. **Version workflows**: Track changes in git
+
+---
+
+## Integration
+
+- Works with babysit for story implementation
+- Can trigger from Ralph Loop
+- Integrates with expert system for multi-domain work