refactor: restructure PM Analysis Agent as a LangGraph subgraph

- Replace PMAnalysisAgent class with functional invokePmAnalysisAgent
- Create dedicated PM Agent subgraph with createPmAgentGraph
- Move PM Agent nodes to pm-agent/nodes directory for better organization
- Add proper retry policies for PM Agent nodes
- Simplify main graph by using PM Agent as a subgraph
- Update tests and documentation to reflect new architecture

This change aligns the PM Agent architecture with the DB Agent pattern,
making the codebase more consistent and maintainable.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: MH4GF

frontend/internal-packages/agent/src/chat/workflow/README.md

@@ -8,22 +8,19 @@ A **LangGraph implementation** for processing chat messages in the LIAM applicat
 %%{init: {'flowchart': {'curve': 'linear'}}}%%
 graph TD;
 	__start__([<p>__start__</p>]):::first
-	analyzeRequirements(analyzeRequirements)
-	invokeSaveArtifactTool(invokeSaveArtifactTool)
+	pmAgent(pmAgent)
 	dbAgent(dbAgent)
 	generateUsecase(generateUsecase)
 	prepareDML(prepareDML)
 	validateSchema(validateSchema)
 	finalizeArtifacts(finalizeArtifacts)
 	__end__([<p>__end__</p>]):::last
-	__start__ --> analyzeRequirements;
+	__start__ --> pmAgent;
 	dbAgent --> generateUsecase;
 	finalizeArtifacts --> __end__;
 	generateUsecase --> prepareDML;
-	invokeSaveArtifactTool --> analyzeRequirements;
+	pmAgent --> dbAgent;
 	prepareDML --> validateSchema;
-	analyzeRequirements -.-> invokeSaveArtifactTool;
-	analyzeRequirements -.-> dbAgent;
 	validateSchema -.-> dbAgent;
 	validateSchema -.-> finalizeArtifacts;
 	classDef default fill:#f2f0ff,line-height:1.2;
@@ -76,13 +73,53 @@ interface WorkflowState {
 
 ## Nodes
 
-1. **analyzeRequirements**: Organizes and clarifies requirements from user input (performed by pmAnalysisAgent)
-2. **saveRequirementToArtifact**: Processes analyzed requirements, saves artifacts to database, and syncs timeline (performed by pmAgent)
-3. **dbAgent**: DB Agent subgraph that handles database schema design - contains designSchema and invokeSchemaDesignTool nodes (performed by dbAgent)
-4. **generateUsecase**: Creates use cases for testing with automatic timeline sync (performed by qaAgent)
-5. **prepareDML**: Generates DML statements for testing (performed by qaAgent)
-6. **validateSchema**: Executes DML and validates schema (performed by qaAgent)
-7. **finalizeArtifacts**: Generates and saves comprehensive artifacts to database, handles error timeline items (performed by dbAgentArtifactGen)
+1. **pmAgent**: PM Agent subgraph that handles requirements analysis - contains analyzeRequirements and invokeSaveArtifactTool nodes
+2. **dbAgent**: DB Agent subgraph that handles database schema design - contains designSchema and invokeSchemaDesignTool nodes (performed by dbAgent)
+3. **generateUsecase**: Creates use cases for testing with automatic timeline sync (performed by qaAgent)
+4. **prepareDML**: Generates DML statements for testing (performed by qaAgent)
+5. **validateSchema**: Executes DML and validates schema (performed by qaAgent)
+6. **finalizeArtifacts**: Generates and saves comprehensive artifacts to database, handles error timeline items (performed by dbAgentArtifactGen)
+
+## PM Agent Subgraph
+
+The `pmAgent` node is implemented as a **LangGraph subgraph** that encapsulates all requirements analysis and artifact management logic as an independent, reusable component following multi-agent system best practices.
+
+### PM Agent Architecture
+
+```mermaid
+%%{init: {'flowchart': {'curve': 'linear'}}}%%
+graph TD;
+	__start__([<p>__start__</p>]):::first
+	analyzeRequirements(analyzeRequirements)
+	invokeSaveArtifactTool(invokeSaveArtifactTool)
+	__end__([<p>__end__</p>]):::last
+	__start__ --> analyzeRequirements;
+	invokeSaveArtifactTool --> analyzeRequirements;
+	analyzeRequirements -.-> invokeSaveArtifactTool;
+	analyzeRequirements -.-> __end__;
+	classDef default fill:#f2f0ff,line-height:1.2;
+	classDef first fill-opacity:0;
+	classDef last fill:#bfb6fc;
+```
+
+### PM Agent Components
+
+#### 1. analyzeRequirements Node
+- **Purpose**: Analyzes and structures user requirements into BRDs
+- **Performed by**: PM Analysis Agent with GPT-5
+- **Retry Policy**: maxAttempts: 3 (internal to subgraph)
+- **Timeline Sync**: Automatic message synchronization
+
+#### 2. invokeSaveArtifactTool Node
+- **Purpose**: Saves analyzed requirements as artifacts to database
+- **Performed by**: saveRequirementsToArtifactTool
+- **Retry Policy**: maxAttempts: 3 (internal to subgraph)
+- **Tool Integration**: Direct database artifact storage
+
+### PM Agent Flow Patterns
+
+1. **Simple Analysis**: `START → analyzeRequirements → END` (when requirements are fully analyzed)
+2. **Iterative Saving**: `START → analyzeRequirements → invokeSaveArtifactTool → analyzeRequirements → ... → END`
 
 ## DB Agent Subgraph
 

frontend/internal-packages/agent/src/chat/workflow/nodes/index.ts

@@ -1,5 +1,3 @@
-export { invokeSaveArtifactToolNode } from '../../../pm-agent/nodes/invokeSaveArtifactToolNode'
-export { analyzeRequirementsNode } from './analyzeRequirementsNode'
 export { finalizeArtifactsNode } from './finalizeArtifactsNode'
 export { generateUsecaseNode } from './generateUsecaseNode'
 export { prepareDmlNode } from './prepareDmlNode'

frontend/internal-packages/agent/src/createGraph.test.ts

@@ -7,22 +7,19 @@ describe('createGraph', () => {
   const expectedMermaidDiagram = `%%{init: {'flowchart': {'curve': 'linear'}}}%%
 graph TD;
 	__start__([<p>__start__</p>]):::first
-	analyzeRequirements(analyzeRequirements)
-	invokeSaveArtifactTool(invokeSaveArtifactTool)
+	pmAgent(pmAgent)
 	dbAgent(dbAgent)
 	generateUsecase(generateUsecase)
 	prepareDML(prepareDML)
 	validateSchema(validateSchema)
 	finalizeArtifacts(finalizeArtifacts)
 	__end__([<p>__end__</p>]):::last
-	__start__ --> analyzeRequirements;
+	__start__ --> pmAgent;
 	dbAgent --> generateUsecase;
 	finalizeArtifacts --> __end__;
 	generateUsecase --> prepareDML;
-	invokeSaveArtifactTool --> analyzeRequirements;
+	pmAgent --> dbAgent;
 	prepareDML --> validateSchema;
-	analyzeRequirements -.-> invokeSaveArtifactTool;
-	analyzeRequirements -.-> dbAgent;
 	validateSchema -.-> dbAgent;
 	validateSchema -.-> finalizeArtifacts;
 	classDef default fill:#f2f0ff,line-height:1.2;

frontend/internal-packages/agent/src/createGraph.ts

@@ -1,16 +1,14 @@
 import { END, START, StateGraph } from '@langchain/langgraph'
 import type { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint'
 import {
-  analyzeRequirementsNode,
   finalizeArtifactsNode,
   generateUsecaseNode,
-  invokeSaveArtifactToolNode,
   prepareDmlNode,
   validateSchemaNode,
 } from './chat/workflow/nodes'
 import { createAnnotations } from './chat/workflow/shared/langGraphUtils'
 import { createDbAgentGraph } from './db-agent/createDbAgentGraph'
-import { routeAfterAnalyzeRequirements } from './pm-agent/routing/routeAfterAnalyzeRequirements'
+import { createPmAgentGraph } from './pm-agent/createPmAgentGraph'
 import { RETRY_POLICY } from './shared/errorHandling'
 
 /**
@@ -21,17 +19,11 @@ import { RETRY_POLICY } from './shared/errorHandling'
 export const createGraph = (checkpointer?: BaseCheckpointSaver) => {
   const ChatStateAnnotation = createAnnotations()
   const graph = new StateGraph(ChatStateAnnotation)
-
-  // Create DB Agent subgraph with checkpoint support
+  const pmAgentSubgraph = createPmAgentGraph(checkpointer)
   const dbAgentSubgraph = createDbAgentGraph(checkpointer)
 
   graph
-    .addNode('analyzeRequirements', analyzeRequirementsNode, {
-      retryPolicy: RETRY_POLICY,
-    })
-    .addNode('invokeSaveArtifactTool', invokeSaveArtifactToolNode, {
-      retryPolicy: RETRY_POLICY,
-    })
+    .addNode('pmAgent', pmAgentSubgraph)
     .addNode('dbAgent', dbAgentSubgraph)
     .addNode('generateUsecase', generateUsecaseNode, {
       retryPolicy: RETRY_POLICY,
@@ -46,19 +38,13 @@ export const createGraph = (checkpointer?: BaseCheckpointSaver) => {
       retryPolicy: RETRY_POLICY,
     })
 
-    .addEdge(START, 'analyzeRequirements')
-    .addEdge('invokeSaveArtifactTool', 'analyzeRequirements')
+    .addEdge(START, 'pmAgent')
+    .addEdge('pmAgent', 'dbAgent')
     .addEdge('dbAgent', 'generateUsecase')
     .addEdge('generateUsecase', 'prepareDML')
     .addEdge('prepareDML', 'validateSchema')
     .addEdge('finalizeArtifacts', END)
 
-    // Conditional edges for requirements analysis
-    .addConditionalEdges('analyzeRequirements', routeAfterAnalyzeRequirements, {
-      invokeSaveArtifactTool: 'invokeSaveArtifactTool',
-      dbAgent: 'dbAgent',
-    })
-
     // Conditional edges for validation results
     .addConditionalEdges(
       'validateSchema',

frontend/internal-packages/agent/src/langchain/agents/index.ts

@@ -1,2 +1 @@
-export { PMAnalysisAgent } from './pmAnalysisAgent'
 export { QAGenerateUsecaseAgent } from './qaGenerateUsecaseAgent'

frontend/internal-packages/agent/src/langchain/agents/pmAnalysisAgent/agent.ts

@@ -0,0 +1,47 @@
+import { END, START, StateGraph } from '@langchain/langgraph'
+import type { BaseCheckpointSaver } from '@langchain/langgraph-checkpoint'
+import { createAnnotations } from '../chat/workflow/shared/langGraphUtils'
+import { analyzeRequirementsNode } from './nodes/analyzeRequirementsNode'
+import { invokeSaveArtifactToolNode } from './nodes/invokeSaveArtifactToolNode'
+import { routeAfterAnalyzeRequirements } from './routing/routeAfterAnalyzeRequirements'
+
+/**
+ * Retry policy configuration for PM Agent nodes
+ */
+const RETRY_POLICY = {
+  maxAttempts: process.env['NODE_ENV'] === 'test' ? 1 : 3,
+}
+
+/**
+ * Create and configure the PM Agent subgraph for requirements analysis
+ *
+ * The PM Agent handles the requirements analysis process:
+ * 1. analyzeRequirements - Analyzes and structures user requirements
+ * 2. invokeSaveArtifactTool - Saves requirements as artifacts using tools
+ * 3. Loop between analysis and tool invocation until requirements are saved
+ *
+ * @param checkpointer - Optional checkpoint saver for persistent state management
+ */
+export const createPmAgentGraph = (checkpointer?: BaseCheckpointSaver) => {
+  const ChatStateAnnotation = createAnnotations()
+  const pmAgentGraph = new StateGraph(ChatStateAnnotation)
+
+  pmAgentGraph
+    .addNode('analyzeRequirements', analyzeRequirementsNode, {
+      retryPolicy: RETRY_POLICY,
+    })
+    .addNode('invokeSaveArtifactTool', invokeSaveArtifactToolNode, {
+      retryPolicy: RETRY_POLICY,
+    })
+
+    .addEdge(START, 'analyzeRequirements')
+    .addEdge('invokeSaveArtifactTool', 'analyzeRequirements')
+    .addConditionalEdges('analyzeRequirements', routeAfterAnalyzeRequirements, {
+      invokeSaveArtifactTool: 'invokeSaveArtifactTool',
+      dbAgent: END,
+    })
+
+  return checkpointer
+    ? pmAgentGraph.compile({ checkpointer })
+    : pmAgentGraph.compile()
+}

frontend/internal-packages/agent/src/langchain/agents/pmAnalysisAgent/index.ts

@@ -0,0 +1,62 @@
+import {
+  type AIMessage,
+  type BaseMessage,
+  SystemMessage,
+} from '@langchain/core/messages'
+import { ChatOpenAI } from '@langchain/openai'
+import { ok, ResultAsync } from 'neverthrow'
+import * as v from 'valibot'
+import type { WorkflowConfigurable } from '../chat/workflow/types'
+import { reasoningSchema } from '../langchain/utils/schema'
+import type { Reasoning } from '../langchain/utils/types'
+import { removeReasoningFromMessages } from '../utils/messageCleanup'
+import { PM_ANALYSIS_SYSTEM_MESSAGE } from './prompts/pmAnalysisPrompts'
+import { saveRequirementsToArtifactTool } from './tools/saveRequirementsToArtifactTool'
+
+type AnalysisWithReasoning = {
+  response: AIMessage
+  reasoning: Reasoning | null
+}
+
+/**
+ * Invoke PM Analysis Agent to analyze user requirements and extract structured BRDs
+ * This function replaces the PMAnalysisAgent class with a simpler functional approach
+ */
+export const invokePmAnalysisAgent = (
+  messages: BaseMessage[],
+  configurable: WorkflowConfigurable,
+): ResultAsync<AnalysisWithReasoning, Error> => {
+  const cleanedMessages = removeReasoningFromMessages(messages)
+
+  const allMessages: BaseMessage[] = [
+    new SystemMessage(PM_ANALYSIS_SYSTEM_MESSAGE),
+    ...cleanedMessages,
+  ]
+
+  const model = new ChatOpenAI({
+    model: 'gpt-5',
+    reasoning: { effort: 'high', summary: 'detailed' },
+    useResponsesApi: true,
+  }).bindTools(
+    [{ type: 'web_search_preview' }, saveRequirementsToArtifactTool],
+    {
+      parallel_tool_calls: false,
+    },
+  )
+
+  return ResultAsync.fromPromise(
+    model.invoke(allMessages, { configurable }),
+    (error) => (error instanceof Error ? error : new Error(String(error))),
+  ).andThen((response) => {
+    const parsedReasoning = v.safeParse(
+      reasoningSchema,
+      response.additional_kwargs['reasoning'],
+    )
+    const reasoning = parsedReasoning.success ? parsedReasoning.output : null
+
+    return ok({
+      response,
+      reasoning,
+    })
+  })
+}

frontend/internal-packages/agent/src/pm-agent/createPmAgentGraph.ts

@@ -1,10 +1,10 @@
 import type { RunnableConfig } from '@langchain/core/runnables'
 import type { Database } from '@liam-hq/db'
-import { PMAnalysisAgent } from '../../../langchain/agents'
-import { WorkflowTerminationError } from '../../../shared/errorHandling'
-import { getConfigurable } from '../shared/getConfigurable'
-import type { WorkflowState } from '../types'
-import { logAssistantMessage } from '../utils/timelineLogger'
+import { getConfigurable } from '../../chat/workflow/shared/getConfigurable'
+import type { WorkflowState } from '../../chat/workflow/types'
+import { logAssistantMessage } from '../../chat/workflow/utils/timelineLogger'
+import { WorkflowTerminationError } from '../../shared/errorHandling'
+import { invokePmAnalysisAgent } from '../invokePmAnalysisAgent'
 
 /**
  * Analyze Requirements Node - Requirements Organization
@@ -31,9 +31,7 @@ export async function analyzeRequirementsNode(
     assistantRole,
   )
 
-  const pmAnalysisAgent = new PMAnalysisAgent()
-
-  const analysisResult = await pmAnalysisAgent.generate(
+  const analysisResult = await invokePmAnalysisAgent(
     state.messages,
     configurableResult.value,
   )