docs(11-05): add comprehensive agent prompts
- Add prompts.ts module with mode-specific agent prompts - Discuss prompt includes question categories and output format - Breakdown prompt includes phase design rules - Execute prompt for standard worker agents
This commit is contained in:
Lukas May
@@ -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
|
||||
---
|
||||
|
||||
<objective>
|
||||
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.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@@ -74,24 +76,228 @@ Output: spawnArchitect procedure and mode-aware agent spawning.
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Add spawnArchitect convenience procedures</name>
|
||||
<name>Task 2: Create comprehensive agent prompts module</name>
|
||||
<files>src/agent/prompts.ts, src/agent/index.ts</files>
|
||||
<action>
|
||||
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';
|
||||
```
|
||||
</action>
|
||||
<verify>npm run build passes</verify>
|
||||
<done>Comprehensive agent prompts module created with discuss, breakdown, and execute modes</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Add spawnArchitect tRPC procedures</name>
|
||||
<files>src/trpc/router.ts</files>
|
||||
<action>
|
||||
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.`;
|
||||
}
|
||||
```
|
||||
</action>
|
||||
<verify>npm run build passes</verify>
|
||||
<done>Architect spawn procedures with mode-specific prompts added</done>
|
||||
<done>Architect spawn procedures use comprehensive prompts from prompts module</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
@@ -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
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- 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
|
||||
</success_criteria>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user