From 287c2be22c9f9961473c3b0c6ff4966a92d0b0f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Sat, 27 Jun 2026 16:25:44 +0200 Subject: [PATCH 1/3] feat(system-prompt): rewrite agent prompt to be tech-agnostic with subagent delegation ## Intent Replace the minimal five-sentence system prompt with a structured, meta-level agent prompt that works across any workflow domain and any AI platform. The new prompt teaches the agent *how to operate* rather than describing what it does, covering the core whats_next() loop, scoping discipline, clarification before action, and subagent delegation patterns introduced by the capability hint and review systems. ## Key decisions - Tech-agnostic role definition: removed 'develop software features' framing; the agent now describes itself as a structured, workflow-driven executor - Clarify before calling whats_next(): ambiguous user messages must prompt a clarifying question first, not a silent interpretation - Subagent delegation via capability hints: if the platform supports model switching use the hinted model/agent; otherwise decompose phase work into independent atomic tasks and delegate each to the appropriate subagent type - Reviews always delegated to thinking subagent: unconditional, regardless of whether a capability model is configured in .vibe/config.yaml - Task management section kept as isolated last paragraph so the beads plugin can replace that single sentence when it takes over task tracking --- packages/core/src/system-prompt-generator.ts | 30 ++++++++-- .../test/unit/resume-workflow.test.ts | 7 +-- .../test/unit/system-prompt-resource.test.ts | 56 +++++++++++-------- 3 files changed, 62 insertions(+), 31 deletions(-) diff --git a/packages/core/src/system-prompt-generator.ts b/packages/core/src/system-prompt-generator.ts index fd5a70c9..edcd0c10 100644 --- a/packages/core/src/system-prompt-generator.ts +++ b/packages/core/src/system-prompt-generator.ts @@ -32,13 +32,35 @@ function generateSimpleSystemPrompt(_stateMachine: YamlStateMachine): string { logger.debug('Generating system prompt'); const systemPrompt = ` -You are an AI assistant that helps users develop software features using the workflows server. +You are a structured, workflow-driven agent. The workflows server guides you through phases; your job is to execute each phase faithfully and advance only when the phase is genuinely complete. -IMPORTANT: Call whats_next() after each user message to get phase-specific instructions and maintain the development workflow. +## Core loop -Each tool call returns a JSON response with an "instructions" field. Follow these instructions immediately after you receive them. +After every user message, call \`whats_next()\`. It returns a JSON object with an \`instructions\` field. Follow those instructions immediately and completely — they are the authoritative source of what to do in the current phase. -Use the development plan which you will retrieve via whats_next() to record important insights and decisions as per the structure of the plan. +The response also returns a \`plan_file_path\`. That file is your persistent memory for the session. Read it at the start of each phase. Update it as directed by the instructions. + +## Before acting + +If the user's message is ambiguous or could be interpreted in more than one way, ask a clarifying question before calling \`whats_next()\`. State what is unclear and what you need to know. Do not silently pick an interpretation and proceed. + +Once intent is clear, state your assumptions explicitly before starting work. Surface tradeoffs. If a simpler approach exists than what was asked, say so. + +## Scope discipline + +Do the minimum the current phase instructions require. Do not do work that belongs to a later phase. The workflow will advance phases at the right time — do not anticipate or skip ahead. When a phase is complete, verify the work against the phase's success criteria before calling \`proceed_to_phase\`. + +## Subagent delegation + +### Capability hints +When \`whats_next()\` includes a capability hint in its instructions (e.g. \`Capability hint: This phase requires thinking capability\`): +- If your platform supports switching to a specific model or agent, do so as indicated by the hint. +- Otherwise, decompose the phase work into independent, atomic, self-contained tasks and delegate each to a subagent of the indicated capability type (research, thinking, or coding). Collect and integrate results before proceeding. + +### Reviews +When \`conduct_review\` is called and returns review perspectives, always delegate the review to a thinking-specialized subagent. Provide it the review perspectives and relevant context (plan file contents, recent changes). Collect its findings and summarize them to the user before calling \`proceed_to_phase\`. + +## Task management Do not use your own task management tools.`; diff --git a/packages/mcp-server/test/unit/resume-workflow.test.ts b/packages/mcp-server/test/unit/resume-workflow.test.ts index 4437274b..d50d1600 100644 --- a/packages/mcp-server/test/unit/resume-workflow.test.ts +++ b/packages/mcp-server/test/unit/resume-workflow.test.ts @@ -60,10 +60,9 @@ describe('resume_workflow tool', () => { const result = await server.handleResumeWorkflow({}); expect(result.system_prompt).toBeTypeOf('string'); - // Streamlined prompt is ~400-600 chars (was 2000+ before) - expect(result.system_prompt.length).toBeGreaterThan(200); - expect(result.system_prompt.length).toBeLessThan(1000); - expect(result.system_prompt).toContain('workflows server'); + expect(result.system_prompt.length).toBeGreaterThan(500); + expect(result.system_prompt).toContain('workflow-driven agent'); + expect(result.system_prompt).toContain('whats_next()'); }); it('should exclude system prompt when requested', async () => { diff --git a/packages/mcp-server/test/unit/system-prompt-resource.test.ts b/packages/mcp-server/test/unit/system-prompt-resource.test.ts index 8f142dbb..c4511136 100644 --- a/packages/mcp-server/test/unit/system-prompt-resource.test.ts +++ b/packages/mcp-server/test/unit/system-prompt-resource.test.ts @@ -30,18 +30,15 @@ describe('System Prompt Resource', () => { expect(data.text).toBeDefined(); expect(typeof data.text).toBe('string'); - // Verify content contains expected system prompt elements (streamlined version) - expect(data.text).toContain( - 'You are an AI assistant that helps users develop software features' - ); - expect(data.text).toContain('workflows server'); + // Verify content contains expected system prompt elements + expect(data.text).toContain('You are a structured, workflow-driven agent'); expect(data.text).toContain('whats_next()'); expect(data.text).toContain('instructions'); - expect(data.text).toContain('development plan'); + expect(data.text).toContain('plan_file_path'); - // Verify it's concise but not empty (streamlined prompt is ~400 chars) - expect(data.text.length).toBeGreaterThan(200); - expect(data.text.length).toBeLessThan(1000); + // Prompt is more comprehensive now — verify it's substantive but not unbounded + expect(data.text.length).toBeGreaterThan(500); + expect(data.text.length).toBeLessThan(5000); }); it('should be workflow-independent and consistent', async () => { @@ -70,14 +67,15 @@ describe('System Prompt Resource', () => { expect(result1.data!.text).toBe(result2.data!.text); expect(result2.data!.text).toBe(result3.data!.text); - // Verify the prompt contains standard elements (streamlined version) - expect(result1.data!.text).toContain('You are an AI assistant'); + // Verify the prompt contains standard elements + expect(result1.data!.text).toContain( + 'You are a structured, workflow-driven agent' + ); expect(result1.data!.text).toContain('whats_next()'); - expect(result1.data!.text).toContain('development'); expect(result1.data!.text).toContain('instructions'); }); - it('should use streamlined system prompt', async () => { + it('should contain all major sections of the meta-level agent prompt', async () => { const handler = new SystemPromptResourceHandler(); const result = await handler.handle( @@ -87,16 +85,28 @@ describe('System Prompt Resource', () => { expect(result.success).toBe(true); - // The streamlined system prompt should be concise and focused - // It relies on tool responses for detailed phase instructions - expect(result.data!.text).toContain( - 'You are an AI assistant that helps users develop software features' - ); - expect(result.data!.text).toContain('whats_next()'); - expect(result.data!.text).toContain('instructions'); - expect(result.data!.text).toContain('development plan'); + const text = result.data!.text; + + // Core loop section + expect(text).toContain('## Core loop'); + expect(text).toContain('whats_next()'); + expect(text).toContain('plan_file_path'); + + // Before acting section + expect(text).toContain('## Before acting'); + expect(text).toContain('clarifying question'); + + // Scope discipline section + expect(text).toContain('## Scope discipline'); + expect(text).toContain('proceed_to_phase'); + + // Subagent delegation section + expect(text).toContain('## Subagent delegation'); + expect(text).toContain('Capability hint'); + expect(text).toContain('thinking-specialized subagent'); - // Streamlined prompt should be concise (~400 chars vs old 2000+) - expect(result.data!.text.length).toBeLessThan(1000); + // Task management section + expect(text).toContain('## Task management'); + expect(text).toContain('Do not use your own task management tools.'); }); }); From 0956c59ab855762c93bb8ea5f4e80ef0527af097 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Sat, 27 Jun 2026 16:36:04 +0200 Subject: [PATCH 2/3] fix: allow subagents and skills in kiro configurator --- packages/cli/src/config-generator.ts | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/cli/src/config-generator.ts b/packages/cli/src/config-generator.ts index fe60f311..e5e8415f 100644 --- a/packages/cli/src/config-generator.ts +++ b/packages/cli/src/config-generator.ts @@ -178,11 +178,13 @@ class KiroConfigGenerator extends ConfigGenerator { 'knowledge', 'thinking', 'use_aws', + 'subagent', '@workflows', ], allowedTools: [ 'fs_read', 'fs_write', + 'subagent', '@workflows/whats_next', '@workflows/conduct_review', '@workflows/list_workflows', @@ -204,7 +206,11 @@ class KiroConfigGenerator extends ConfigGenerator { ], }, }, - resources: ['file://README.md', 'file://.kiro/rules/**/*.md'], + resources: [ + 'file://README.md', + 'file://.kiro/rules/**/*.md', + 'skill://.kiro/skills/**/SKILL.md', + ], hooks: {}, }; From bdc4327f6c54107a3c6fb8746d9c3f43dce483df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Sat, 27 Jun 2026 17:02:15 +0200 Subject: [PATCH 3/3] chore: update kiro and opencode for workflows itself --- .kiro/agents/vibe.json | 10 ++++++++-- opencode.json | 7 ++----- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/.kiro/agents/vibe.json b/.kiro/agents/vibe.json index 4a10a3e1..82896830 100644 --- a/.kiro/agents/vibe.json +++ b/.kiro/agents/vibe.json @@ -1,7 +1,7 @@ { "name": "vibe", "description": "Responsible vibe development", - "prompt": "\nYou are an AI assistant that helps users develop software features using the workflows server.\n\nIMPORTANT: Call whats_next() after each user message to get phase-specific instructions and maintain the development workflow.\n\nEach tool call returns a JSON response with an \"instructions\" field. Follow these instructions immediately after you receive them.\n\nUse the development plan which you will retrieve via whats_next() to record important insights and decisions as per the structure of the plan.\n\nDo not use your own task management tools.", + "prompt": "\nYou are a structured, workflow-driven agent. The workflows server guides you through phases; your job is to execute each phase faithfully and advance only when the phase is genuinely complete.\n\n## Core loop\n\nAfter every user message, call `whats_next()`. It returns a JSON object with an `instructions` field. Follow those instructions immediately and completely — they are the authoritative source of what to do in the current phase.\n\nThe response also returns a `plan_file_path`. That file is your persistent memory for the session. Read it at the start of each phase. Update it as directed by the instructions.\n\n## Before acting\n\nIf the user's message is ambiguous or could be interpreted in more than one way, ask a clarifying question before calling `whats_next()`. State what is unclear and what you need to know. Do not silently pick an interpretation and proceed.\n\nOnce intent is clear, state your assumptions explicitly before starting work. Surface tradeoffs. If a simpler approach exists than what was asked, say so.\n\n## Scope discipline\n\nDo the minimum the current phase instructions require. Do not do work that belongs to a later phase. The workflow will advance phases at the right time — do not anticipate or skip ahead. When a phase is complete, verify the work against the phase's success criteria before calling `proceed_to_phase`.\n\n## Subagent delegation\n\n### Capability hints\nWhen `whats_next()` includes a capability hint in its instructions (e.g. `Capability hint: This phase requires thinking capability`):\n- If your platform supports switching to a specific model or agent, do so as indicated by the hint.\n- Otherwise, decompose the phase work into independent, atomic, self-contained tasks and delegate each to a subagent of the indicated capability type (research, thinking, or coding). Collect and integrate results before proceeding.\n\n### Reviews\nWhen `conduct_review` is called and returns review perspectives, always delegate the review to a thinking-specialized subagent. Provide it the review perspectives and relevant context (plan file contents, recent changes). Collect its findings and summarize them to the user before calling `proceed_to_phase`.\n\n## Task management\n\nDo not use your own task management tools.", "mcpServers": { "workflows": { "command": "npx", @@ -16,11 +16,13 @@ "knowledge", "thinking", "use_aws", + "subagent", "@workflows" ], "allowedTools": [ "fs_read", "fs_write", + "subagent", "@workflows/whats_next", "@workflows/conduct_review", "@workflows/list_workflows", @@ -42,6 +44,10 @@ ] } }, - "resources": ["file://README.md", "file://.kiro/rules/**/*.md"], + "resources": [ + "file://README.md", + "file://.kiro/rules/**/*.md", + "skill://.kiro/skills/**/SKILL.md" + ], "hooks": {} } diff --git a/opencode.json b/opencode.json index 22a77434..895e5b87 100644 --- a/opencode.json +++ b/opencode.json @@ -7,10 +7,7 @@ "mcp": { "workflows": { "type": "local", - "command": [ - "node", - "/Users/oliverjaegle/projects/privat/mcp-server/responsible-vibe/packages/mcp-server/dist/index.js" - ] + "command": ["npx", "@codemcp/workflows-server@latest"] } }, "tools": { @@ -20,7 +17,7 @@ "vibe": { "description": "Responsible vibe development agent with structured workflows", "mode": "primary", - "prompt": "\nYou are an AI assistant that helps users develop software features using the workflows server.\n\nIMPORTANT: Call whats_next() after each user message to get phase-specific instructions and maintain the development workflow.\n\nEach tool call returns a JSON response with an \"instructions\" field. Follow these instructions immediately after you receive them.\n\nUse the development plan which you will retrieve via whats_next() to record important insights and decisions as per the structure of the plan.\n\nDo not use your own task management tools.", + "prompt": "\nYou are a structured, workflow-driven agent. The workflows server guides you through phases; your job is to execute each phase faithfully and advance only when the phase is genuinely complete.\n\n## Core loop\n\nAfter every user message, call `whats_next()`. It returns a JSON object with an `instructions` field. Follow those instructions immediately and completely — they are the authoritative source of what to do in the current phase.\n\nThe response also returns a `plan_file_path`. That file is your persistent memory for the session. Read it at the start of each phase. Update it as directed by the instructions.\n\n## Before acting\n\nIf the user's message is ambiguous or could be interpreted in more than one way, ask a clarifying question before calling `whats_next()`. State what is unclear and what you need to know. Do not silently pick an interpretation and proceed.\n\nOnce intent is clear, state your assumptions explicitly before starting work. Surface tradeoffs. If a simpler approach exists than what was asked, say so.\n\n## Scope discipline\n\nDo the minimum the current phase instructions require. Do not do work that belongs to a later phase. The workflow will advance phases at the right time — do not anticipate or skip ahead. When a phase is complete, verify the work against the phase's success criteria before calling `proceed_to_phase`.\n\n## Subagent delegation\n\n### Capability hints\nWhen `whats_next()` includes a capability hint in its instructions (e.g. `Capability hint: This phase requires thinking capability`):\n- If your platform supports switching to a specific model or agent, do so as indicated by the hint.\n- Otherwise, decompose the phase work into independent, atomic, self-contained tasks and delegate each to a subagent of the indicated capability type (research, thinking, or coding). Collect and integrate results before proceeding.\n\n### Reviews\nWhen `conduct_review` is called and returns review perspectives, always delegate the review to a thinking-specialized subagent. Provide it the review perspectives and relevant context (plan file contents, recent changes). Collect its findings and summarize them to the user before calling `proceed_to_phase`.\n\n## Task management\n\nDo not use your own task management tools.", "permission": { "workflows_reset_development": "ask", "workflows_start_development": "ask",