AGEN-6 - trckr

← AGEN-6

feature

Created: 2026-02-03 • Updated: 2026-02-03

Relationships Loading...

# Full Jinja2 When Expressions

Implement Jinja2-based conditional execution with when field (extends skip-if from AGEN-2).

## Scope
~250 lines of code + tests

## Implementation
1. Add \`when\` field to task schema (string with Jinja2 expression) (validator.py)
2. Before task execution, evaluate \`when\` expression using Jinja2 (executor.py)
3. If evaluates to false/empty/null, skip task (return skipped status)
4. Upgrade utils.py interpolation to support full Jinja2:
   - Boolean logic: and, or, not
   - Comparisons: ==, !=, <, >, <=, >=
   - String operations: in, not in
5. Use Jinja2 NativeEnvironment for proper type handling

## YAML API
\`\`\`yaml
template-variables:
  environment: "production"
  tests-passed: true

task:
  - deploy:
      when: "{{environment}} == 'production' and {{tests-passed}}"
      prompt: "Deploy to production"

- skip-ci:
      when: "{{environment}} != 'ci'"
      prompt: "Skip in CI environment"
\`\`\`

## Files to Modify
- src/executor.py (~90 lines)
- src/utils.py (~80 lines - upgrade to full Jinja2)
- src/validator.py (~20 lines)
- tests/test_when_conditions.py (new, ~60 lines)

## Tests Required
- Simple equality: when: "{{var}} == 'value'"
- Boolean and logic: when: "{{a}} and {{b}}"
- Boolean or logic: when: "{{a}} or {{b}}"
- Negation: when: "not {{skip}}"
- Multiple operators: when: "{{a}} == 'x' or {{b}} == 'y'"
- Undefined variable in when raises error
- when: "" (empty string) skips task
- when: "true" executes task
- Combine with skip-if (both work independently)

## Dependencies
**Blocks:** None
**Blocked by:** AGEN-2 (Simple skip-if)

Extends the skip-if framework with full Jinja2 expressions.

## QA Validation Steps

### 1. Simple Equality Test
**Action:**
\`\`\`yaml
template-variables:
  deploy-env: "production"
task:
  - deploy:
      when: "{{deploy-env}} == 'production'"
      prompt: "Create deployed.txt"
\`\`\`
**Expected:** Task executes, file created
**Verify:** deployed.txt exists

### 2. Boolean AND Test
**Action:**
\`\`\`yaml
template-variables:
  env: "prod"
  tests-pass: true
task:
  - deploy:
      when: "{{env}} == 'prod' and {{tests-pass}}"
      prompt: "Create deployed.txt"
\`\`\`
**Expected:** Task executes (both conditions true)
**Verify:** deployed.txt created

### 3. Boolean OR Test
**Action:**
\`\`\`yaml
template-variables:
  env: "staging"
  force: true
task:
  - deploy:
      when: "{{env}} == 'prod' or {{force}}"
      prompt: "Create deployed.txt"
\`\`\`
**Expected:** Task executes (force is true)
**Verify:** deployed.txt created

### 4. Skip Test
**Action:**
\`\`\`yaml
template-variables:
  env: "ci"
task:
  - deploy:
      when: "{{env}} == 'production'"
      prompt: "Should be skipped"
\`\`\`
**Expected:** Task skipped (condition false)
**Verify:** Stderr shows skip reason, no output created

### 5. Combine with skip-if Test
**Action:**
\`\`\`yaml
task:
  - deploy:
      when: "{{env}} == 'prod'"
      skip-if:
        file-exists: "deployed.flag"
      prompt: "Deploy"
\`\`\`
**Expected:** Both conditions checked independently
**Verify:** Task skips if EITHER condition met

### Pass Criteria
✅ All 5 tests pass
✅ Boolean logic works correctly
✅ Works with skip-if independently
✅ Unit tests pass

### Fail Criteria
❌ Any test fails
❌ Condition evaluation incorrect
❌ Breaks existing {{var}} interpolation

Pull Requests (comma-separated URLs)

Attachments

Comments (2)

agent · 2026-02-03

## Implementation Complete ### What was implemented Added full Jinja2 `when` expressions for conditional task execution as specified in the issue. ### Changes Made 1. **src/utils.py** (+140 lines) - Added `evaluate_expression()` function using `NativeEnvironment` for proper boolean evaluation - Added `_flatten_variables()` helper to flatten nested dicts for variable access in expressions - Supports comparisons (==, !=, <, >, <=, >=), boolean logic (and, or, not), string ops (in, not in) 2. **src/when_conditions.py** (new, 127 lines) - `WhenConditionResult` class for encapsulating evaluation results - `WhenConditionError` exception for evaluation failures - `check_when_condition()` function that evaluates expressions and returns should_execute status 3. **src/executor.py** (+33 lines) - Added when condition check after skip-if (line ~185-220) - Follows same error handling pattern as skip-if - Returns skipped status with when_condition details when condition is false 4. **src/validator.py** (+26 lines) - Added `when` to list of known meta fields - Added `_validate_when_config()` method to validate when must be a string 5. **tests/test_when_conditions.py** (new, 692 lines) - 62 comprehensive tests covering all specified scenarios - Tests for equality, boolean AND/OR, negation, comparisons - Tests for executor integration, combining with skip-if - Tests for error handling and real-world scenarios 6. **examples/39-when-conditions.yaml** (new, 92 lines) - Example workflow demonstrating all when condition features 7. **CLAUDE.md** (+87 lines) - Added When Conditions section with usage documentation - Updated module architecture and examples list ### Test Results All 852 tests pass (62 new when_conditions tests + 790 existing tests). ### How to Verify ```yaml template-variables: environment: "production" tests-passed: true task: - deploy: when: "{{environment}} == 'production' and {{tests-passed}}" prompt: "Deploy to production" ``` Run with different variable values to verify conditional execution works correctly.

triage-agent · 2026-02-03

## Feature Triage Complete **Status:** NOT IMPLEMENTED (Ready for implementation) **Summary:** This feature adds Jinja2-based conditional execution via a `when` field, extending the existing skip-if mechanism from AGEN-2. The key discovery is that we need to use Jinja2's `NativeEnvironment` (instead of standard `Environment`) to properly evaluate expressions to native Python types (bool, int) rather than strings. **Implementation Location:** - New file: `src/when_conditions.py` (~60 lines) - Modify: `src/utils.py` (+25 lines) - add `evaluate_expression()` using NativeEnvironment - Modify: `src/executor.py` (+20 lines) - add when check after skip-if - Modify: `src/validator.py` (+25 lines) - schema validation - New tests: `tests/test_when_conditions.py` (~80 lines) **Complexity:** Low-Medium (~280 lines total including tests) **Key Finding:** The existing Jinja2 infrastructure in `src/utils.py` provides most of the foundation. The main addition is using `NativeEnvironment` for boolean evaluation instead of the current string-rendering `Environment`. **Pattern to Follow:** The skip-if implementation in `src/skip_conditions.py` provides the exact pattern for pre-execution checks that return `{status: 'skipped'}`. **Dependencies:** AGEN-2 (Simple skip-if) is complete and merged. See full triage report: `/tmp/triage-AGEN-6.md`