diff --git a/.planning/phases/11-architect-agent/11-05-PLAN.md b/.planning/phases/11-architect-agent/11-05-PLAN.md index f87325a..25ae7fb 100644 --- a/.planning/phases/11-architect-agent/11-05-PLAN.md +++ b/.planning/phases/11-architect-agent/11-05-PLAN.md @@ -5,16 +5,18 @@ type: execute wave: 3 depends_on: ["11-03", "11-04"] files_modified: + - src/agent/prompts.ts + - src/agent/index.ts - src/trpc/router.ts autonomous: true --- -Add Architect-specific tRPC procedures for spawning agents in discuss/breakdown modes. +Add comprehensive mode-specific agent prompts and Architect spawn procedures. -Purpose: Enable spawning architect agents that use mode-specific prompts and output schemas, with convenience procedures for the discuss→breakdown workflow. +Purpose: Enable spawning architect agents with detailed prompts that explain their role, output format, and expected behavior for each mode. -Output: spawnArchitect procedure and mode-aware agent spawning. +Output: Agent prompts module with comprehensive mode-specific prompts, architect spawn procedures. @@ -74,24 +76,228 @@ Output: spawnArchitect procedure and mode-aware agent spawning. - Task 2: Add spawnArchitect convenience procedures + Task 2: Create comprehensive agent prompts module + src/agent/prompts.ts, src/agent/index.ts + +Create src/agent/prompts.ts with comprehensive mode-specific prompts: + +```typescript +import type { Initiative } from '../db/schema.js'; + +/** + * Build comprehensive prompt for discuss mode. + * Agent asks clarifying questions to understand requirements. + */ +export function buildDiscussPrompt(initiative: Initiative, context?: string): string { + return `You are an Architect agent in the Codewalk multi-agent system operating in DISCUSS mode. + +## Your Role +Transform user intent into clear, documented decisions. You do NOT write code - you capture decisions. + +## Initiative +Name: ${initiative.name} +${initiative.description ? `Description: ${initiative.description}` : ''} +${context ? `\nAdditional Context: ${context}` : ''} + +## Your Task +Ask clarifying questions to understand the requirements. Capture decisions as you go. + +## Question Categories + +**User Journeys:** +- What are the main user workflows? +- What happens on success? On failure? +- What are the edge cases? + +**Technical Constraints:** +- What patterns should we follow? +- What should we avoid? +- What existing code should we reference? + +**Data & Validation:** +- What data structures are needed? +- What validation rules apply? +- What are the constraints? + +**Integration Points:** +- What external systems are involved? +- What APIs do we need? +- What error handling is required? + +## Output Format + +When you need more information, output: +{ + "status": "questions", + "questions": [ + { "id": "q1", "question": "Your question here", "options": [{"label": "Option A"}, {"label": "Option B"}] } + ] +} + +When you have enough information, output: +{ + "status": "context_complete", + "decisions": [ + { "topic": "Authentication", "decision": "Use JWT", "reason": "Stateless, scalable" } + ], + "summary": "Brief summary of all decisions made" +} + +## Rules +- Ask 2-4 questions at a time, not more +- Provide options when choices are clear +- Capture every decision with rationale +- Don't proceed until ambiguities are resolved`; +} + +/** + * Build comprehensive prompt for breakdown mode. + * Agent decomposes initiative into executable phases. + */ +export function buildBreakdownPrompt(initiative: Initiative, contextSummary?: string): string { + return `You are an Architect agent in the Codewalk multi-agent system operating in BREAKDOWN mode. + +## Your Role +Decompose the initiative into executable phases. You do NOT write code - you plan it. + +## Initiative +Name: ${initiative.name} +${initiative.description ? `Description: ${initiative.description}` : ''} +${contextSummary ? `\nContext from Discussion Phase:\n${contextSummary}` : ''} + +## Your Task +Break this initiative into phases that can be executed by worker agents. + +## Phase Design Rules + +**Each phase must be:** +- A coherent unit of work (single concern) +- Independently deliverable +- Testable in isolation + +**Dependencies:** +- Identify what each phase needs from prior phases +- Minimize cross-phase dependencies +- Foundation phases come first + +**Sizing:** +- Phases should be 2-5 tasks each +- Not too big (hard to track), not too small (overhead) + +**Naming:** +- Clear, action-oriented names +- Describe what gets built, not how + +## Output Format + +If you need clarification, output: +{ + "status": "questions", + "questions": [ + { "id": "q1", "question": "Your question here" } + ] +} + +When breakdown is complete, output: +{ + "status": "breakdown_complete", + "phases": [ + { + "number": 1, + "name": "Database Schema", + "description": "Create user tables and authentication schema", + "dependencies": [] + }, + { + "number": 2, + "name": "Auth API", + "description": "JWT generation, validation, and middleware", + "dependencies": [1] + } + ] +} + +## Rules +- Start with foundation/infrastructure phases +- Group related work together +- Make dependencies explicit +- Each phase should be completable in one session`; +} + +/** + * Build prompt for execute mode (standard worker agent). + * This is the default mode for task execution. + */ +export function buildExecutePrompt(taskDescription: string): string { + return `You are a Worker agent in the Codewalk multi-agent system. + +## Your Task +${taskDescription} + +## Output Format + +When task is complete, output: +{ + "status": "done", + "result": "Description of what was accomplished", + "filesModified": ["path/to/file1.ts", "path/to/file2.ts"] +} + +If you need clarification, output: +{ + "status": "questions", + "questions": [ + { "id": "q1", "question": "Your question here" } + ] +} + +If you hit an unrecoverable error, output: +{ + "status": "unrecoverable_error", + "error": "Description of what went wrong", + "attempted": "What you tried before failing" +} + +## Rules +- Complete the task as specified +- Ask questions if requirements are unclear +- Report errors honestly - don't guess`; +} +``` + +Export from src/agent/index.ts: +```typescript +export { buildDiscussPrompt, buildBreakdownPrompt, buildExecutePrompt } from './prompts.js'; +``` + + npm run build passes + Comprehensive agent prompts module created with discuss, breakdown, and execute modes + + + + Task 3: Add spawnArchitect tRPC procedures src/trpc/router.ts -Add architect-specific spawn procedures: +Import prompts and add architect-specific spawn procedures: +1. Add import: +```typescript +import { buildDiscussPrompt, buildBreakdownPrompt } from '../agent/prompts.js'; +``` + +2. Add spawn procedures to appRouter: ```typescript // Spawn architect in discuss mode spawnArchitectDiscuss: publicProcedure .input(z.object({ name: z.string().min(1), initiativeId: z.string().min(1), - context: z.string().optional(), // Initial context about what to discuss + context: z.string().optional(), })) .mutation(async ({ ctx, input }) => { const agentManager = requireAgentManager(ctx); const initiativeRepo = requireInitiativeRepository(ctx); - // Verify initiative exists const initiative = await initiativeRepo.findById(input.initiativeId); if (!initiative) { throw new TRPCError({ @@ -104,7 +310,7 @@ spawnArchitectDiscuss: publicProcedure return agentManager.spawn({ name: input.name, - taskId: input.initiativeId, // Use initiative ID as task reference + taskId: input.initiativeId, prompt, mode: 'discuss', }); @@ -115,7 +321,7 @@ spawnArchitectBreakdown: publicProcedure .input(z.object({ name: z.string().min(1), initiativeId: z.string().min(1), - contextSummary: z.string().optional(), // Summary from discuss phase + contextSummary: z.string().optional(), })) .mutation(async ({ ctx, input }) => { const agentManager = requireAgentManager(ctx); @@ -138,46 +344,10 @@ spawnArchitectBreakdown: publicProcedure mode: 'breakdown', }); }), -``` - -Add helper functions above the router definition: -```typescript -function buildDiscussPrompt(initiative: Initiative, context?: string): string { - return `You are an Architect agent in discuss mode. - -Initiative: ${initiative.name} -${initiative.description ? `Description: ${initiative.description}` : ''} -${context ? `\nContext: ${context}` : ''} - -Your task is to ask clarifying questions to understand the requirements better. -Ask questions about: -- User journeys and workflows -- Technical constraints and preferences -- Edge cases and error handling -- Integration points - -When you have enough information, output status: "context_complete" with your decisions.`; -} - -function buildBreakdownPrompt(initiative: Initiative, contextSummary?: string): string { - return `You are an Architect agent in breakdown mode. - -Initiative: ${initiative.name} -${initiative.description ? `Description: ${initiative.description}` : ''} -${contextSummary ? `\nContext from discussion:\n${contextSummary}` : ''} - -Your task is to break this initiative into phases. -Each phase should be: -- A coherent unit of work -- Deliverable independently -- Clear dependencies on prior phases - -Output status: "breakdown_complete" with an array of phases.`; -} ``` npm run build passes - Architect spawn procedures with mode-specific prompts added + Architect spawn procedures use comprehensive prompts from prompts module @@ -186,17 +356,19 @@ Output status: "breakdown_complete" with an array of phases.`; Before declaring plan complete: - [ ] npm run build succeeds without errors - [ ] npm test passes +- [ ] src/agent/prompts.ts exports buildDiscussPrompt, buildBreakdownPrompt, buildExecutePrompt - [ ] spawnAgent accepts mode parameter -- [ ] spawnArchitectDiscuss spawns agent in discuss mode -- [ ] spawnArchitectBreakdown spawns agent in breakdown mode +- [ ] spawnArchitectDiscuss spawns agent with comprehensive discuss prompt +- [ ] spawnArchitectBreakdown spawns agent with comprehensive breakdown prompt - [ ] Both architect procedures validate initiative exists - All tasks completed -- Architect workflow has dedicated spawn procedures -- Mode-specific prompts guide agent behavior +- Comprehensive prompts explain agent role, output format, and rules +- Prompts module is reusable for future agent types +- Architect spawn procedures use prompts module - Initiative validation prevents orphaned agents