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.