# Release v1.8.0: Intent Metadata System
**Release Date:** 2025-12-16
## 🎯 Overview
This release introduces the **Intent Metadata System** - a groundbreaking feature that enables AI context continuity across iterations. LLMs can now document WHY design decisions were made, not just WHAT was built.
## ✨ New Features
### Intent Metadata for Workflow Nodes
Add optional `_intent` metadata to any workflow node to preserve reasoning, assumptions, and risks:
```json
{
"_intent": {
"reason": "Fetch customer data from CRM",
"assumption": "API returns JSON array",
"risk": "Rate limit exceeded",
"alternative": "Could use webhook instead",
"dependency": "Requires CRM API credentials",
"created_at": "2025-12-16T10:30:00Z",
"version": "1.0"
}
}
```
### 6 New MCP Tools
#### 1. `add_node_intent`
Add "why" metadata to a workflow node for AI context continuity.
**Parameters:**
- `workflow_id` (required): Workflow ID
- `node_name` (required): Node name
- `reason` (required): Why this node exists / what problem it solves
- `assumption` (optional): Assumptions made when building this node
- `risk` (optional): Known risks or limitations
- `alternative` (optional): Alternative approaches considered
- `dependency` (optional): Dependencies on other nodes or systems
#### 2. `get_workflow_intents`
Retrieve all intent metadata from a workflow.
**Parameters:**
- `workflow_id` (required): Workflow ID
- `format` (optional): Output format - "report" (default) or "json"
#### 3. `analyze_intent_coverage`
Analyze how well a workflow is documented with intent metadata.
**Parameters:**
- `workflow_id` (required): Workflow ID
**Returns:**
- Coverage percentage
- Nodes with/without intent
- Critical nodes missing documentation
- Node type breakdown
- Recommendations
#### 4. `suggest_node_intent`
Get AI-generated intent suggestions for a specific node.
**Parameters:**
- `workflow_id` (required): Workflow ID
- `node_name` (required): Node name to analyze
#### 5. `update_node_intent`
Update existing intent metadata fields.
**Parameters:**
- `workflow_id` (required): Workflow ID
- `node_name` (required): Node name
- `reason` (optional): Updated reason
- `assumption` (optional): Updated assumption
- `risk` (optional): Updated risk
- `alternative` (optional): Updated alternative
- `dependency` (optional): Updated dependency
#### 6. `remove_node_intent`
Remove intent metadata from a node.
**Parameters:**
- `workflow_id` (required): Workflow ID
- `node_name` (required): Node name
## 🎨 New Module
### `src/n8n_workflow_builder/intent.py`
New `IntentManager` class with 8 static methods:
- `create_intent()` - Create intent metadata structure
- `add_intent_to_node()` - Add intent to node
- `get_node_intent()` - Retrieve node intent
- `update_node_intent()` - Update intent fields
- `remove_intent_from_node()` - Remove intent
- `get_workflow_intents()` - Get all workflow intents
- `generate_intent_report()` - Generate markdown report
- `analyze_intent_coverage()` - Analyze documentation coverage
- `suggest_intent_for_node()` - Generate AI suggestions
## 💡 Use Cases
### 1. Cross-Iteration Context
When an LLM modifies a workflow weeks later, it can read intent metadata to understand WHY decisions were made:
```python
# Original builder documents their reasoning
add_node_intent(
workflow_id="abc123",
node_name="Filter_High_Value",
reason="Filter out low-value leads to save API calls",
assumption="Lead score > 80 indicates high value",
risk="Might miss valuable leads with lower scores"
)
# Later, another LLM reads this and understands the context
intents = get_workflow_intents(workflow_id="abc123")
```
### 2. Documentation Quality
Track how well workflows are documented:
```python
analysis = analyze_intent_coverage(workflow_id="abc123")
# Returns: 75% coverage, 3 critical nodes missing intent
```
### 3. AI-Assisted Documentation
Get suggestions for nodes without intent:
```python
suggestion = suggest_node_intent(
workflow_id="abc123",
node_name="HTTP_Request_1"
)
# Returns context-aware intent suggestion based on node type and connections
```
## 🔧 Technical Details
### Intent Metadata Structure
All intent metadata includes:
- **reason**: Core purpose of the node (required)
- **assumption**: Assumptions made during design (optional)
- **risk**: Known risks or edge cases (optional)
- **alternative**: Alternative approaches considered (optional)
- **dependency**: External dependencies or prerequisites (optional)
- **created_at**: ISO 8601 timestamp (auto-generated)
- **version**: Metadata schema version (auto-generated)
### Storage Location
Intent metadata is stored directly in the node definition as `_intent` field:
- Not interpreted by n8n
- Preserved across workflow updates
- Available for LLM context retrieval
- Exportable in JSON format
### Coverage Analysis
The analyzer categorizes nodes:
- **Triggers**: Webhook, Schedule, Manual
- **Logic nodes**: IF, Switch, Filter, Merge
- **Action nodes**: HTTP Request, Database, Email, etc.
Critical nodes (triggers, logic, data transformations) are flagged if missing intent.
## 📊 Impact
This feature enables **"Denk-Kontinuität"** (thinking continuity) - maintaining reasoning across LLM iterations:
✅ **Before**: LLM rebuilds logic from scratch, potentially introducing bugs
✅ **After**: LLM reads intent metadata and makes informed modifications
✅ **Before**: No record of WHY design decisions were made
✅ **After**: Complete audit trail of reasoning and assumptions
✅ **Before**: Complex workflows become unmaintainable over time
✅ **After**: Self-documenting workflows that explain their own logic
## 🚀 Quality Improvement
Intent metadata is a **"massiver Qualitätshebel"** (massive quality lever):
- Reduces context loss across iterations
- Prevents regression bugs from forgotten assumptions
- Enables better collaboration between LLM agents
- Creates self-documenting workflows
- Facilitates easier debugging and maintenance
## 📝 Example Workflow
```python
# Build workflow with intent documentation
workflow = create_workflow(name="Lead Processing")
add_node_intent(
workflow_id=workflow["id"],
node_name="Webhook",
reason="Receive leads from landing page form",
assumption="Webhook payload contains email, name, company",
risk="Form spam could overwhelm the workflow"
)
add_node_intent(
workflow_id=workflow["id"],
node_name="Filter_Valid_Email",
reason="Filter out invalid email addresses before CRM sync",
assumption="Email validation regex catches 99% of invalid formats",
risk="Some valid international emails might be rejected",
alternative="Could use email verification API but adds latency"
)
# Analyze documentation quality
analysis = analyze_intent_coverage(workflow_id=workflow["id"])
print(f"Coverage: {analysis['coverage_percentage']}%")
# Generate report for team review
report = get_workflow_intents(workflow_id=workflow["id"], format="report")
```
## 🔍 Files Changed
### New Files
- `src/n8n_workflow_builder/intent.py` (337 lines)
### Modified Files
- `src/n8n_workflow_builder/server.py` (+257 lines)
- Added 6 new tool definitions
- Added 6 new tool handlers
- Integrated IntentManager
## 📦 Installation
No additional dependencies required. The feature uses existing n8n workflow structures.
## 🎉 Credits
Feature requested and designed to solve the real-world problem of LLMs losing context across iterations.
---
**Full Changelog**: v1.7.1...v1.8.0
