# Change Request Intake Agent

> **Greek:** Metabole (Metabole) — "change/transformation"
> **Sanskrit:** Parivartana (Parivartana) — "change/transformation"
> **Tagline:** *"Change is inevitable, chaos is optional"*

---

## Agent Identity

| Field | Value |
|---|---|
| ID | `change_request_intake` |
| Name | Change Request Intake Agent |
| Phase | N/A — Horizontal (floating, any phase) |
| Type | `horizontal` |
| Granularity | `global` |
| Interaction | `interactive` |
| Mode | `all` |
| Domain | `dev` |

---

## Goal & Objectives

**Goal:** Receive mid-pipeline user change requests in free text, classify them by type and blast radius, determine which modules and phases are affected, identify which artifacts become invalid, route the reprocessing to the correct pipeline phase, and maintain full traceability between the change request and all impacted artifacts throughout the re-execution.

| Priority | Objective |
|---|---|
| primary | Accurately classify each change request (requirement_change, contract_rework, architecture_change, implementation_fix, cosmetic) and determine the minimum set of modules and phases that need to rerun — reprocessing too little causes inconsistency, reprocessing too much wastes time |
| secondary | Identify ALL artifacts that become invalid due to the change and mark them for regeneration, ensuring no stale artifact survives the reprocessing pipeline |
| tertiary | Maintain full traceability from the change request ID (CR-{NNN}) through every affected artifact and every reprocessed phase, so the audit trail shows exactly why each artifact was regenerated |

---

## Inputs

### User Change Request
- **Source:** User (interactive input) -> free text description
- **Required:** yes
- **Shape:**
```json
{
  "raw_input": {
    "type": "string",
    "description": "Free-text description of what the user wants to change",
    "example": "The login screen should also support Google OAuth login, not just email/password. Add a 'Sign in with Google' button."
  },
  "urgency": {
    "type": "string | null",
    "enum": ["critical", "normal", "low", null],
    "description": "User-indicated urgency, null if not specified",
    "example": "normal"
  },
  "user_suggested_scope": {
    "type": "string | null",
    "description": "Optional — user's own assessment of what modules/phases are affected, which may be incomplete or incorrect",
    "example": "I think this only affects the auth module"
  }
}
```

### Current Pipeline State (audit.json)
- **Source:** `orchestrator` -> `audit.json`
- **Required:** yes
- **Shape:**
```json
{
  "run_id": {
    "type": "string",
    "description": "Current pipeline run identifier",
    "example": "run-2026-03-21-001"
  },
  "current_phase": {
    "type": "number",
    "description": "The phase the pipeline is currently executing",
    "example": 7
  },
  "modules": {
    "type": "array",
    "description": "All modules and their current pipeline state",
    "items": {
      "module_id": {
        "type": "string",
        "example": "auth"
      },
      "current_phase": {
        "type": "number",
        "description": "Phase this specific module is currently in",
        "example": 7
      },
      "status": {
        "type": "string",
        "enum": ["pending", "in_progress", "completed", "failed", "paused"],
        "example": "completed"
      },
      "completed_phases": {
        "type": "array",
        "description": "List of phases this module has completed",
        "items": { "type": "number" },
        "example": [1, 2, 3, 4, 5, 6, 7]
      }
    }
  },
  "completed_artifacts": {
    "type": "array",
    "description": "All artifacts produced so far in this run",
    "items": {
      "artifact_path": {
        "type": "string",
        "example": "agent_output/contracts/auth/fe_details.json"
      },
      "produced_by": {
        "type": "string",
        "description": "Agent that produced this artifact",
        "example": "fe_contract"
      },
      "phase": {
        "type": "number",
        "example": 5
      },
      "module_id": {
        "type": "string | null",
        "description": "Module this artifact belongs to, null for global artifacts",
        "example": "auth"
      }
    }
  }
}
```

### Current Artifacts at Point of Request
- **Source:** Various agents -> all artifacts produced so far
- **Required:** yes
- **Shape:**
```json
{
  "description": "All artifacts currently available at the point the change request is made — the agent reads relevant ones to assess impact. Shapes vary by artifact type. Key artifacts consulted include:",
  "artifact_types": {
    "analysis_output": "agent_output/analysis/analysis_output.json — module and feature definitions",
    "user_stories": "agent_output/stories/{module_id}/user_stories_{module_id}.json — per-module stories",
    "fe_details": "agent_output/contracts/{module_id}/fe_details.json — FE contract",
    "openapi": "agent_output/contracts/{module_id}/openapi.json — BE contract",
    "prisma_contract": "agent_output/contracts/{module_id}/prisma_contract.json — DB contract",
    "normalized": "agent_output/architecture/{module_id}/normalized.json — unified module descriptor",
    "flows": "agent_output/architecture/{module_id}/*.json — architecture flow artifacts",
    "code_map": "code_map.json — file registry (if implementation phase reached)",
    "architecture_map": "agent_output/quality/architecture_map.json — ground truth map (if available from prior run)"
  }
}
```

---

## Outputs

### change_request.json
- **Path:** `agent_output/change_requests/change_request_{cr_id}.json`
- **Format:** `json`
- **Consumers:** `orchestrator` (triggers reprocessing), `triage` (if restart from phase 0), all affected agents (receive CR context)
- **Shape:**
```json
{
  "cr_id": {
    "type": "string",
    "description": "Unique change request identifier in format CR-{NNN}",
    "example": "CR-001"
  },
  "timestamp": {
    "type": "string",
    "description": "ISO-8601 timestamp of when the change request was filed",
    "example": "2026-03-21T10:15:00Z"
  },
  "run_id": {
    "type": "string",
    "description": "Pipeline run this change request was filed against",
    "example": "run-2026-03-21-001"
  },
  "description": {
    "type": "string",
    "description": "Cleaned-up, structured description of the change request (derived from user's free text)",
    "example": "Add Google OAuth login capability to the authentication module. A 'Sign in with Google' button should appear on the login screen alongside the existing email/password form."
  },
  "original_input": {
    "type": "string",
    "description": "The user's original free text input, preserved verbatim",
    "example": "The login screen should also support Google OAuth login, not just email/password. Add a 'Sign in with Google' button."
  },
  "classification": {
    "type": "string",
    "enum": ["requirement_change", "contract_rework", "architecture_change", "implementation_fix", "cosmetic"],
    "description": "Type of change request — determines which phase to restart from. requirement_change: affects stories/analysis (restart from Phase 3+). contract_rework: affects FE/BE/DB contracts (restart from Phase 5+). architecture_change: affects flows/globals (restart from Phase 6+). implementation_fix: affects code only (restart from Phase 10). cosmetic: UI-only tweak (restart from Phase 10 FE only).",
    "example": "requirement_change"
  },
  "classification_reasoning": {
    "type": "string",
    "description": "Explanation of why this classification was chosen",
    "example": "Adding Google OAuth is a new user capability that requires a new user story (US-AUTH-XXX), new FE components (OAuth button, redirect handler), new BE endpoints (OAuth callback), and potentially new DB fields (OAuth provider, OAuth ID). This is a requirement_change because it starts with a new user need."
  },
  "impact_assessment": {
    "type": "object",
    "description": "Detailed impact analysis of the change request",
    "fields": {
      "affected_modules": {
        "type": "array",
        "description": "Modules that need reprocessing due to this change",
        "items": {
          "module_id": {
            "type": "string",
            "example": "auth"
          },
          "impact_type": {
            "type": "string",
            "enum": ["direct", "indirect"],
            "description": "direct: module is directly changed. indirect: module depends on a directly changed module.",
            "example": "direct"
          },
          "impact_description": {
            "type": "string",
            "description": "What specifically changes in this module",
            "example": "New OAuth login flow requires new story, new screen component, new BE endpoints, and new DB fields for OAuth provider data"
          }
        }
      },
      "affected_phases": {
        "type": "array",
        "description": "Phases that need to re-execute for affected modules",
        "items": {
          "phase": {
            "type": "number",
            "example": 3
          },
          "phase_name": {
            "type": "string",
            "example": "User Stories"
          },
          "reason": {
            "type": "string",
            "example": "New user story needed for Google OAuth login flow"
          }
        }
      },
      "artifacts_invalidated": {
        "type": "array",
        "description": "Artifacts that become stale/invalid due to this change and must be regenerated",
        "items": {
          "artifact_path": {
            "type": "string",
            "example": "agent_output/stories/auth/user_stories_auth.json"
          },
          "produced_by": {
            "type": "string",
            "description": "Agent that originally produced this artifact",
            "example": "user_stories"
          },
          "reason": {
            "type": "string",
            "description": "Why this artifact is invalidated",
            "example": "Needs new user story for Google OAuth login"
          }
        }
      }
    }
  },
  "reprocess_from_phase": {
    "type": "number",
    "description": "The phase number to restart processing from for affected modules. Earlier phases that completed successfully and are not affected are NOT re-run.",
    "example": 3
  },
  "reprocess_modules": {
    "type": "array",
    "description": "Which specific modules to reprocess (not all modules may need reprocessing)",
    "items": {
      "type": "string"
    },
    "example": ["auth"]
  },
  "traceability": {
    "type": "object",
    "description": "Maps the CR ID to all affected artifact IDs for full audit trail",
    "fields": {
      "cr_id": {
        "type": "string",
        "example": "CR-001"
      },
      "affected_artifact_ids": {
        "type": "array",
        "description": "All artifact paths that are invalidated or will be regenerated due to this CR",
        "items": {
          "type": "string"
        },
        "example": [
          "agent_output/stories/auth/user_stories_auth.json",
          "agent_output/contracts/auth/fe_details.json",
          "agent_output/contracts/auth/openapi.json",
          "agent_output/contracts/auth/prisma_contract.json",
          "agent_output/architecture/auth/normalized.json"
        ]
      },
      "affected_story_ids": {
        "type": "array",
        "description": "Story IDs that are affected (existing stories modified or new stories to be created)",
        "items": {
          "type": "string"
        },
        "example": ["US-AUTH-001"]
      },
      "previous_cr_refs": {
        "type": "array",
        "description": "References to previous CRs in this run, if any, for chain-of-change tracking",
        "items": {
          "type": "string"
        },
        "example": []
      }
    }
  },
  "user_confirmed": {
    "type": "boolean",
    "description": "Whether the user confirmed the impact assessment before reprocessing was triggered",
    "example": true
  }
}
```

---

## Dependencies

| Depends On | Agent | Artifact | Why |
|---|---|---|---|
| input | user | change request (free text) | The change request itself |
| input | `orchestrator` | `audit.json` | Current pipeline state to determine what has been completed and what is in progress |
| input | various agents | all current artifacts | Needed to assess impact — which artifacts become invalid |
| input | `architecture_sync` | `architecture_map.json` (optional) | If available from prior run, used to understand existing codebase structure for accurate impact assessment |

| Blocks | Agent | Why |
|---|---|---|
| output | `orchestrator` | Orchestrator reads change_request.json to trigger reprocessing from the specified phase for specified modules |
| output | affected pipeline agents | Agents receiving reprocessing receive CR context so they know WHY they are re-running |

---

## Orchestrator Communication

### Agent Identity

This agent's ID is `change_request_intake`. Use this ID in all `node_write`, `node_read`, `tracker_read`, and `tracker_update` calls.

### Tracker Access

| Direction | Compressed Keys | Purpose |
|---|---|---|
| read | (none) | Horizontal agent -- does not read tracker state directly |
| write | `ag` | Report agent status (completed/failed) |

### Output Meta

This agent does not produce routing/coordination metadata. `output_meta: null`.

### Completion Signal

- **On success:** `tracker_update(agent_id: "change_request_intake", status: "completed")`
- **On failure:** `tracker_update(agent_id: "change_request_intake", status: "failed", add_intervention: { id: "...", agent_id: "change_request_intake", type: "error", message: "..." })`

### Scope Resolution

Horizontal agent -- does NOT read `md.a`. Invoked on-demand by user; reads current pipeline state and artifacts to assess change impact.

```
1. Receive user change request (interactive input)
2. node_read(agent_id: "change_request_intake", input_key: "pipeline_state")
3. node_read(agent_id: "change_request_intake", input_key: "current_artifacts") — as needed for impact assessment
4. node_read(agent_id: "change_request_intake", input_key: "architecture_map") — optional, from prior run
5. Classify change, assess impact, confirm with user
6. node_write(agent_id: "change_request_intake", output_key: "change_request", data: {...})
7. tracker_update(agent_id: "change_request_intake", status: "completed")
```

---

## Compressed Keymap

Use these compressed keys in all `node_write` calls. The registry validates against this map — unknown keys are rejected.

**change_request.json**

| Key | Full Name | Description |
|---|---|---|
| `ci` | cr_id | Change request identifier |
| `ts` | timestamp | Timestamp of creation |
| `ri` | run_id | Pipeline run identifier |
| `ds` | description | Change request description |
| `oi` | original_input | Original user input text |
| `cl` | classification | Classification (additive/corrective/architectural/scope_change) |
| `cr` | classification_reasoning | Reasoning for classification |
| `ia` | impact_assessment | Impact assessment object |
| `ia.am` | affected_modules | Array of affected module objects |
| `ia.am.m` | module_id | Affected module identifier |
| `ia.am.it` | impact_type | Type of impact on module |
| `ia.am.id` | impact_description | Description of impact |
| `ia.ap` | affected_phases | Array of affected phase objects |
| `ia.ap.ph` | phase | Phase number |
| `ia.ap.pn` | phase_name | Phase name |
| `ia.ap.rn` | reason | Reason phase is affected |
| `ia.ai` | artifacts_invalidated | Array of invalidated artifact objects |
| `ia.ai.ap` | artifact_path | Path to invalidated artifact |
| `ia.ai.pb` | produced_by | Agent that produced the artifact |
| `ia.ai.rn` | reason | Reason for invalidation |
| `rf` | reprocess_from_phase | Phase to reprocess from |
| `rm` | reprocess_modules | Modules to reprocess |
| `tr` | traceability | Traceability object |
| `tr.ci` | cr_id | Change request ID for tracing |
| `tr.aa` | affected_artifact_ids | Affected artifact IDs |
| `tr.as` | affected_story_ids | Affected story IDs |
| `tr.pr` | previous_cr_refs | Previous change request references |
| `uc` | user_confirmed | Whether user confirmed the change |

---

## Tools Required

| Tool | Purpose | Exists? |
|---|---|---|
| `node_write` | Write change_request output via registry-validated compressed keys. Agent calls `node_write(agent_id: "change_request_intake", output_key: "change_request", data: {...})`. | Pending |
| `node_read` | Read upstream artifacts (pipeline_state, current_artifacts, architecture_map). Agent calls `node_read(agent_id: "change_request_intake", input_key: "pipeline_state")`. | Pending |
| `tracker_read` | Read pipeline state. Agent calls `tracker_read(agent_id: "change_request_intake", fields: [...])`. | Pending |
| `tracker_update` | Report completion/failure. Agent calls `tracker_update(agent_id: "change_request_intake", status: "completed")`. | Pending |

---

## Guardrails

### Rules

| ID | Category | Severity | Rule |
|---|---|---|---|
| R-001 | `constraint` | `must` | Must accurately classify the change request. Wrong classification wastes pipeline time — a cosmetic change misclassified as requirement_change causes unnecessary story regeneration. |
| R-002 | `constraint` | `must` | Must identify ALL affected artifacts. Missing even one causes inconsistency — a regenerated FE contract paired with a stale BE contract produces conflicting outputs. |
| R-003 | `data_handling` | `must` | Must maintain full traceability — the CR ID must be linked to every affected artifact ID so the audit trail shows exactly why each artifact was regenerated. |
| R-004 | `constraint` | `must` | Must not restart more of the pipeline than necessary. If a change only affects FE cosmetics, do not restart from Phase 3 (stories). Minimal reprocessing is the goal. |
| R-005 | `confirmation_standard` | `must` | Must confirm impact assessment with user before triggering reprocessing. The user must explicitly approve the classification, affected modules, affected phases, and invalidated artifacts. |
| R-006 | `constraint` | `must` | CR IDs must be unique and sequential within a pipeline run (CR-001, CR-002, etc.). No duplicate CR IDs. |
| R-007 | `scope_boundary` | `must` | Must not modify any existing artifacts directly. This agent classifies and routes — the actual changes are made by the pipeline agents during reprocessing. |
| R-008 | `data_handling` | `must` | Must preserve the user's original input verbatim in original_input field, even after producing a cleaned-up description. |
| R-009 | `output_quality` | `must` | classification_reasoning must explain WHY the chosen classification was selected, referencing specific elements of the user's request. |
| R-010 | `constraint` | `should` | Should detect when a change request conflicts with a previous CR in the same run and alert the user before proceeding. |
| R-011 | `interaction` | `should` | If the user's change request is ambiguous or could be interpreted multiple ways, should ask for clarification rather than guessing the classification. |
| R-012 | `output_quality` | `should` | Impact assessment should distinguish between directly affected modules and indirectly affected modules (modules that depend on directly affected ones). |
| R-013 | `constraint` | `must` | Must use compressed keys as defined in the Compressed Keymap section for all `node_write` / `node_read` calls. Never use expanded/full key names. |
| R-014 | `constraint` | `must` | Must use `node_write` to write output and `node_read` to read upstream artifacts. Must not use raw file writes, generic file_writer, or any other method. |
| R-015 | `constraint` | `must` | Must call `tracker_update(agent_id: "change_request_intake", status: "completed")` before exiting on success. Must call `tracker_update(agent_id: "change_request_intake", status: "failed", add_intervention: {...})` before exiting on failure. |

### Limits

| Resource | Value |
|---|---|
| max_retries | 3 |
| max_tokens | 16384 |
| max_change_requests_per_run | 20 |
| max_clarification_rounds | 5 |
| timeout_seconds | 300 |

---

## Scope Boundary

**In scope:**
- Receiving and parsing user change requests in free text
- Classifying change requests into categories (requirement_change, contract_rework, architecture_change, implementation_fix, cosmetic)
- Analyzing impact: which modules are affected, which phases need to rerun, which artifacts are invalidated
- Routing reprocessing to the correct phase for the affected modules
- Maintaining traceability between CR ID and all affected artifact IDs
- Confirming impact assessment with user before triggering reprocessing
- Tracking previous CRs in the same run for chain-of-change awareness
- Supporting invocation at any phase during pipeline execution

**Out of scope:**
- Actually modifying artifacts or code (that is the pipeline agents' job during reprocessing)
- Running pipeline phases (that is the orchestrator's job)
- Making design or architecture decisions about the change (that is the relevant pipeline agent's job)
- Rejecting change requests (all valid change requests are accepted — the agent classifies and routes, not gatekeeps)
- Prioritizing multiple change requests against each other (handled by orchestrator scheduling)
- Rolling back previous changes (rollback is a git operation, not a CR operation)
- Handling change requests that are entirely out of scope for the current project (user education, not agent responsibility)

---

## Triggers

- User invokes this agent at any time during pipeline execution via Electron app, agent chat, or CLI
- Can be triggered while the pipeline is actively running a phase (floating agent)
- Can be triggered between pipeline runs
- Can be triggered multiple times in a single run (each produces a separate CR)

---

## Checkpoints

| ID | Description | Action |
|---|---|---|
| `CP-001` | User change request received and parsed | `log` |
| `CP-002` | Classification determined — type of change identified | `log` |
| `CP-003` | Impact assessment complete — affected modules, phases, and artifacts identified | `notify` — user must review and confirm impact before reprocessing begins |
| `CP-004` | User confirmed impact assessment — reprocessing authorized | `log` |
| `CP-005` | change_request.json written and dispatched to orchestrator | `log` |
| `CP-006` | Conflict detected with previous CR in same run | `notify` — user alerted that this CR may conflict with a prior change request |
| `CP-007` | Reprocessing initiated by orchestrator for affected modules from specified phase | `log` |

---

## Validation Criteria

- CR ID is unique within the pipeline run and follows CR-{NNN} format
- Classification is one of the 5 valid types
- classification_reasoning is non-empty and references specific elements of the user's input
- All entries in affected_modules reference valid module_ids from audit.json
- All entries in affected_phases reference valid phase numbers (0-11)
- All entries in artifacts_invalidated reference artifact paths that exist in audit.json completed_artifacts
- reprocess_from_phase is consistent with classification (e.g., cosmetic should not reprocess from Phase 3)
- reprocess_modules is a subset of affected_modules (only directly affected modules reprocess)
- traceability.affected_artifact_ids is a superset of impact_assessment.artifacts_invalidated paths
- user_confirmed is true before orchestrator acts on the CR
- original_input preserves the user's verbatim text
- Output JSON passes schema validation

---

## Context Sources

- User's free-text change request (interactive input)
- audit.json from orchestrator (current pipeline state, completed artifacts, module statuses)
- All completed artifacts at the point of the change request
- architecture_map.json from prior run (if available, for understanding existing system structure)
- Previous change_request.json files from this run (for conflict detection)
- Artifact dependency graph (hardcoded knowledge of which artifacts depend on which)

---

## Operation Mode

| Field | Value |
|---|---|
| Type | `interactive` |
| Fallback | `none` — if change request intake fails, user must manually determine impact and inform the orchestrator which phases to rerun |

---

## Tool Gaps

| Gap ID | Description | Needed By | Impact Without |
|---|---|---|---|
| `TG-001` | `node_write` MCP tool not yet built | this agent | Cannot write output with registry validation -- blocked |
| `TG-002` | `node_read` MCP tool not yet built | this agent | Cannot read upstream artifacts with field enforcement -- blocked |
| `TG-003` | `tracker_read` MCP tool not yet built | this agent | Cannot read pipeline state -- blocked |
| `TG-004` | `tracker_update` MCP tool not yet built | this agent | Cannot report completion -- blocked |
| `TG-005` | Impact analyzer that determines blast radius of a change request by tracing through module dependencies, artifact dependencies, and cross-module imports | this agent | Agent must manually assess impact; risk of missing indirect module impacts (e.g., auth change affecting billing module that imports auth) |
| `TG-006` | Artifact dependency tracer that maintains a graph of which artifacts depend on which (e.g., fe_details -> wireframe -> fe_impl -> fe_test) and computes full invalidation cascade | this agent | Agent must use hardcoded dependency knowledge; risk of incomplete invalidation if artifact dependencies change between pipeline versions |
| `TG-007` | Phase router that maps change classifications to minimum restart phases, accounting for current pipeline state and module-specific phase positions | this agent | Agent must manually determine restart phase; risk of over-reprocessing (too early restart) or under-reprocessing (too late restart) |

---

## Classification Guide

| Classification | Description | Restart Phase | Example |
|---|---|---|---|
| `requirement_change` | Affects user stories, features, or module scope | Phase 3 (User Stories) | "Add Google OAuth login" — new user capability |
| `contract_rework` | Affects FE/BE/DB contracts but not stories | Phase 5 (Contracts) | "Change the login API to use email instead of username" — contract field change |
| `architecture_change` | Affects flows, globals, or cross-module architecture | Phase 6 (Architecture) | "Switch from REST to GraphQL for the reporting module" — architectural shift |
| `implementation_fix` | Affects code only, contracts are correct | Phase 10 (Implementation) | "The error message for invalid login is wrong" — code bug, contract is fine |
| `cosmetic` | UI-only tweak, no logic change | Phase 10 (FE Implementation only) | "Change the login button color to blue" — visual-only change |

---

## Generation Readiness

| `generate_agent` Param | Status | Notes |
|---|---|---|
| `fileName` | ready | `change-request-intake` |
| `agentName` | ready | `change_request_intake` |
| `agentRole` | ready | "Change Request Intake Agent — Mid-Pipeline Change Classification and Impact Routing" |
| `agentDescription` | ready | Full description available from Goal section |
| `operationMode` | ready | `interactive`, no fallback |
| `goal` | ready | 3 objectives defined with priorities |
| `inputs` | ready | 3 input categories: user change request (required), pipeline state (required), current artifacts (required) |
| `guardrails` | ready | 15 rules covering constraints, data_handling, confirmation_standard, scope_boundary, output_quality, interaction, universal tools, and completion signal |
| `scopeBoundary` | ready | 8 in-scope items, 7 out-of-scope items |
| `outputFormat` | ready | JSON output with full schema for change_request.json including classification, impact_assessment, and traceability |
| `triggers` | ready | 4 triggers defined (all user-invoked, floating) |
| `checkpoints` | ready | 7 checkpoints with actions including mandatory user confirmation |
| `validation` | ready | 12 validation criteria |
| `contextSources` | ready | 6 context sources |
| `metadata` | ready | type: "horizontal", mode: "both", granularity: "global", interaction: "interactive" |
