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