parallel-prompt-generator

Prompt Generator

Generate agent-ready prompts from existing task specification files in tasks/.

CRITICAL: Prompt Template Requirements

Every generated prompt file MUST include ALL of these sections (see Step 4 for full template):

Section	Purpose	Required
=== REQUIRED SKILLS ===	Skills to invoke at start	YES
=== CONTEXT ===	Shared project context	YES
=== OBJECTIVE ===	Task goal	YES
=== CONTRACTS ===	Contract file references	YES
=== FILES TO CREATE ===	Scope CREATE	YES
=== FILES TO MODIFY ===	Scope MODIFY	YES
=== DO NOT MODIFY ===	Scope BOUNDARY	YES
=== IMPLEMENTATION REQUIREMENTS ===	Requirements	YES
=== ACCEPTANCE CRITERIA ===	Checklist	YES
=== EXECUTION INSTRUCTIONS ===	How to implement	MANDATORY
=== IMPORTANT RULES ===	Constraints	MANDATORY
=== COMPLETION SIGNAL ===	touch .claude-task-complete	MANDATORY

DO NOT generate prompts without the EXECUTION INSTRUCTIONS, IMPORTANT RULES, and COMPLETION SIGNAL sections.

When to Use

• After editing task files in tasks/
• To regenerate prompts with updated template
• Before running cpo run if prompts are missing
• To test different prompt formats

Input Requirements

The parallel directory must have:

parallel/TS-XXXX-slug/
  manifest.json       # Required: wave structure, agents
  context.md          # Required: shared context
  contracts/          # Required: types.py, api-schema.yaml
  tasks/              # Required: task-*.md files
    task-001-users.md
    task-002-products.md

Output

Generates:

parallel/TS-XXXX-slug/
  prompts/
    agent-prompts.md   # Wave summary and launch commands
    task-001.txt       # Individual agent prompt
    task-002.txt
    ...

Workflow

flowchart TB
    Start[("tasks/ folder")]
    Read["1. Read manifest.json"]
    Context["2. Load context.md"]
    Parse["3. Parse each task file"]
    Generate["4. Generate task-NNN.txt"]
    Summary["5. Create agent-prompts.md"]
    Done[("prompts/ ready")]

    Start --> Read
    Read --> Context
    Context --> Parse
    Parse --> Generate
    Generate --> Summary
    Summary --> Done

Step 1: Read manifest.json

Extract:

• Wave structure and task ordering
• Agent assignments per task
• Tech spec reference
• Technology stack

Step 2: Load context.md

The shared context is injected into every prompt for efficiency.

Step 3: Parse Task Files

For each tasks/task-NNN-*.md:

1. Extract YAML frontmatter:

   id: task-001
   component: users
   wave: 1
   deps: []
   agent: python-experts:django-expert
   contracts: [contracts/types.py, contracts/api-schema.yaml]
   

2. Extract Markdown sections:

   • ## Scope -> CREATE, MODIFY, BOUNDARY
   • ## Requirements -> Implementation requirements
   • ## Checklist -> Acceptance criteria

3. Resolve skills for each task:

   • Read parallel-agents/agent-skills-mapping.yaml for agent-to-skills mapping
   • Look up the agent from task frontmatter (e.g., python-experts:django-expert)
   • Get the skills list for that agent
   • Format as full skill names: plugin:skill-name

Note: The Output Format section is not in task files. It's a static template that the prompt generator always includes in generated prompts.

Step 4: Generate Individual Prompts

CRITICAL: Copy content EXACTLY from task files. Do not summarize or rewrite.

When generating prompts:

1. Include FULL context.md content (do not summarize - include every line)
2. COPY the ## Requirements section VERBATIM - every bullet point, every field name, every type
3. COPY the ## Checklist section VERBATIM - every item exactly as written
4. Match exact field names from contracts (e.g., use principal_id not user_id)

Create prompts/task-NNN.txt using this template:

TASK-{id}: {title}
Agent: {agent}
Wave: {wave}
Dependencies: {deps or "None"}

=== REQUIRED SKILLS ===
Before starting implementation, invoke these skills to load best practices:
{list of skills from agent-skills-mapping.yaml, formatted as bullets}

Invoke skills using: skill: "plugin:skill-name"

=== CONTEXT ===
{contents of context.md}

=== OBJECTIVE ===
{First line of task description or component name}

=== CONTRACTS ===
Reference these contract files before implementing:
{list of contract files with full paths}

=== FILES TO CREATE ===
{CREATE section from Scope}

=== FILES TO MODIFY ===
{MODIFY section from Scope}

=== DO NOT MODIFY ===
{BOUNDARY section from Scope}

=== IMPLEMENTATION REQUIREMENTS ===
{Requirements section content}

=== ACCEPTANCE CRITERIA ===
{Checklist section content}

=== EXECUTION INSTRUCTIONS ===

You MUST write code, not just describe it. Follow these steps:

1. **Read contracts first**: Read all files in contracts/ to understand interfaces
2. **Read existing code**: If modifying files, read them first
3. **Implement**: Use Write/Edit tools to create/modify code
4. **Test & Fix Loop**:
   - Run tests for your implementation
   - If ANY test fails, FIX the issue and rerun tests
   - REPEAT until ALL tests pass
   - Do NOT proceed to step 5 until tests pass
5. **Lint**: Run linters (ruff, mypy, eslint as appropriate)
6. **Commit**: Create atomic commit with conventional format (only after tests pass)

=== IMPORTANT RULES ===

- Do NOT ask for confirmation - proceed immediately with implementation
- Do NOT modify files listed in DO NOT MODIFY section
- Do NOT skip writing tests
- Do NOT deviate from contract interfaces
- Do NOT commit or signal completion until ALL tests pass
- If tests fail, you MUST fix the issues and keep running until they pass
- STOP if you encounter blocking issues and report in output

**CRITICAL - CONTRACTS ARE DESIGN DOCUMENTS:**
- Contracts in `parallel/` are DESIGN SPECIFICATIONS ONLY
- READ them to understand the interface you must implement
- RECREATE the types/interfaces in your actual project code
- NEVER import from `parallel/` directory
- NEVER use sys.path manipulation to access parallel/ files
- The `parallel/` directory is NOT part of the deployed codebase

=== COMPLETION SIGNAL ===

Upon successful completion (ALL tests passing), run: touch .claude-task-complete

CRITICAL: Only signal completion if:
- All tests pass (pytest exits with 0)
- All linting passes
- Code is committed

Step 5: Create agent-prompts.md

Summary file with launch commands:

# Agent Prompts for {name}

Generated: {timestamp}
Tech Spec: {tech_spec_id}
Total Tasks: {count}

## Wave Execution Order

### Wave 1 (Parallel)
| Task | Agent | Component |
|------|-------|-----------|
| task-001 | python-experts:django-expert | users |
| task-002 | python-experts:django-expert | products |

### Wave 2 (Parallel, depends on Wave 1)
| Task | Agent | Component |
|------|-------|-----------|
| task-003 | python-experts:django-expert | orders |

## Launch Commands

### Using cpo (Recommended)
```bash
cpo run parallel/{slug}/

Manual Execution (Wave 1)

# Run in parallel terminals or with &
claude --prompt-file prompts/task-001.txt --agent python-experts:django-expert &
claude --prompt-file prompts/task-002.txt --agent python-experts:django-expert &
wait

Manual Execution (Wave 2)

# After Wave 1 completes
claude --prompt-file prompts/task-003.txt --agent python-experts:django-expert

Prompt Files

File	Task	Lines
prompts/task-001.txt	task-001-users	~150
prompts/task-002.txt	task-002-products	~145
prompts/task-003.txt	task-003-orders	~160

## Validation Before Generation

Check these conditions:

- [ ] `manifest.json` exists and is valid JSON
- [ ] `context.md` exists
- [ ] `contracts/` directory exists with at least one file
- [ ] `tasks/` directory has at least one task file
- [ ] All tasks referenced in manifest exist in `tasks/`

## Error Handling

### Task Not in Manifest

WARNING: task-005-api.md exists but not in manifest.json -> Skipping prompt generation (add to manifest first)

### Missing Contract Reference

WARNING: task-001 references contracts/types.py but file doesn't exist -> Generate prompt with warning comment

## Regeneration Mode

When prompts already exist:

1. **Backup existing**: Move to `prompts.backup-{timestamp}/`
2. **Generate fresh**: Create new prompts from current tasks
3. **Report diff**: Show what changed

```bash
# Command triggers regeneration
/parallel-generate-prompts parallel/TS-0042-inventory/ --force

Token Optimization

The generated prompts are optimized for token efficiency:

• Context is included once (not repeated per section)
• Contract paths reference files (agent reads them)
• Scope uses compact CREATE/MODIFY/BOUNDARY notation
• Checklist is actionable, not verbose

Integration with cpo

The cpo run command expects:

1. manifest.json with wave structure
2. prompts/task-NNN.txt for each task in manifest

This skill ensures prompts match what cpo expects.

Post-Generation Validation

After generating prompts, verify EACH prompt file contains:

# Quick validation - each prompt should have these markers
for f in prompts/task-*.txt; do
  echo "=== $f ==="
  grep -c "=== REQUIRED SKILLS ===" "$f" || echo "MISSING: REQUIRED SKILLS"
  grep -c "=== EXECUTION INSTRUCTIONS" "$f" || echo "MISSING: EXECUTION INSTRUCTIONS"
  grep -c "=== COMPLETION SIGNAL" "$f" || echo "MISSING: COMPLETION SIGNAL"
done

If any prompt is missing these sections, regenerate it using the exact template from Step 4.

Note: Output format and JSON summary blocks are managed via system prompt by the external execution tool, not included in generated prompts.

Related Skills

Skill	Relationship
parallel-decompose	Creates tasks/ that this skill reads
parallel-task-format	Defines the task YAML format parsed here
parallel-execution	Consumes the prompts/ this skill generates
parallel-agents	Overall workflow context + agent-skills-mapping.yaml

Reference Files

• parallel-agents/agent-skills-mapping.yaml - Maps agents to their recommended skills