sparkgen-prompt

name	sparkgen-prompt
description	Validate, render, preview, and manage the 6-layer prompt system
user_invokable	true
auto_invokable	true
auto_invoke_hint	Invoke when the user discusses prompts, prompt templates, context files, or prompt variables
arguments	<validate|render|preview|variables|create|layers> [agent-name]

SparkGen Prompt

Manage the 6-layer prompt system.

Dynamic Context

Before any action:

1. List prompt files: ls prompts/
2. List context files: ls contexts/
3. Read config/prompt_variables.yaml
4. Read config/ai_workflow.yaml — prompts: and agents[].prompt sections

The 6 Prompt Layers

1. System prompt — prompts/<agent>.md (Jinja2 template)
2. Context files — contexts/*.md injected into the prompt
3. Variables — from config/prompt_variables.yaml + agent-level variables
4. RAG context — dynamically injected retrieved documents (if RAG enabled)
5. Guardrail instructions — injected safety rules from active guardrail sets
6. Suffix — agent-specific prompt_suffix from workflow YAML

Actions

Validate (/sparkgen-prompt validate)

python -m app.prompts.validator --base-dir . --variables config/prompt_variables.yaml

Checks:

• All prompt files referenced in workflow YAML exist
• All context files referenced exist
• All variables used in templates are defined
• Jinja2 syntax is valid
• No unresolved template variables

Render (/sparkgen-prompt render <agent-name>)

If server is running:

curl -s http://localhost:8000/v1/prompts/render?agent=<agent-name> \
  -H "X-API-Key: ${API_KEY:-dev-local-key}"

Displays the fully rendered prompt with all 6 layers merged.

Preview (/sparkgen-prompt preview <agent-name>)

Show each layer separately for the given agent:

1. Read and display prompts/<agent>.md
2. Read and display each context file
3. Show variables from config/prompt_variables.yaml + agent-level overrides
4. Show RAG context template (if configured)
5. Show guardrail instructions that would be injected
6. Show the prompt suffix

Variables (/sparkgen-prompt variables)

Display all prompt variables from config/prompt_variables.yaml: | Variable | Value | Used By | For each variable, show which prompt files reference it.

Create (/sparkgen-prompt create <agent-name>)

Create a new prompt file prompts/<agent-name>.md with a template:

You are {% raw %}{{ agent_name }}{% endraw %}, a specialized AI assistant.

## Role
<describe the agent's role>

## Instructions
<specific instructions for this agent>

## Guidelines
- Be helpful and accurate
- Cite sources when available

Also add the prompt file reference to the agent's config in config/ai_workflow.yaml. Run make validate-prompts after creation.

Layers (/sparkgen-prompt layers)

Explain the 6-layer prompt architecture and show how each layer is configured for every agent. Display a matrix: Agent × Layer showing what's configured at each level.