system-prompt-curator

name	system-prompt-curator
description	Curate production-grade system prompts for autonomous coding agents and multi-agent orchestration. Use when creating, improving, or debugging agent prompts. Not for user-facing messages or chat prompts.
version	2.0.0
argument-hint	[role-description] [--improve path/to/prompt] [--for-orchestrator] [--minimal]

System Prompt Curator

Create and refine production-grade system prompts for autonomous coding agents, based on patterns proven in SWE-agent, OpenHands, Aider, Claude Code, Cursor, Devin, and Windsurf.

Parse Arguments

role_or_path = first non-flag argument (role description or file path to improve)
--improve    = refine an existing prompt (read the file first)
--for-orchestrator = generate a prompt for an orchestrator-dispatched agent (no human interaction)
--minimal    = compact prompt under 600 tokens (for cost-sensitive models)

Core Principles (from research)

These are non-negotiable patterns found across ALL top-performing coding agents:

1. Identity matches the task. If the agent writes code, call it an engineer, not an assistant.

   • SWE-agent: "autonomous programmer working in the command line"
   • Cursor: "AI coding assistant, pair programming"
   • Devin: "a software engineer... few programmers are as talented as you"
   • NEVER: "focused AI agent" or "orchestrator" (too abstract)

2. Autonomous completion mandate. The agent keeps going until done.

   • Cursor: "keep going until the user's query is completely resolved"
   • Windsurf: "keep working, using tools where needed, until the user's query is completely resolved"
   • NEVER: "return complete_run immediately" or "complete_run with your best answer"

3. Structured workflow phases. Explore -> Plan -> Implement -> Verify -> Deliver.

   • Every agent uses this. Without phases, the LLM treats analysis as completion.
   • SWE-agent: 5 concrete steps + 6 failure-mode tips
   • OpenHands: EXPLORATION, ANALYSIS, TESTING, IMPLEMENTATION, VERIFICATION
   • Claude Code: Explore, Plan, Implement, Commit

4. Completion requires evidence. The exit action is gated.

   • SWE-agent: multi-stage submit with diff review before final submission
   • Mini-SWE-agent: magic string echo, not a tool call
   • OpenHands: finish requires summary of actions taken
   • Best pattern: require files_modified (non-empty array) + tests_passed + pr_url

5. Tools listed upfront, not discovered. All available tools in the prompt.

   • Anthropic: "Claude has been trained on thousands of successful trajectories with specific tool schemas"
   • SWE-agent: tools auto-generated from YAML config into {command_docs}
   • Dynamic discovery causes the exact failure mode of "discover, read, complete without acting"

6. Worked demonstration. At least one full trajectory example.

   • SWE-agent: full solved issue trajectory (explore, reproduce, fix, verify, submit)
   • OpenHands: Flask app example with error recovery (create, fail, install dep, succeed)
   • The example MUST show error recovery — teaches agent not to give up on failure

7. Think-before-act transitions. Structured reasoning at key decision points.

   • Devin: mandatory think before git decisions, before code changes, before completion
   • OpenHands: dedicated think tool for brainstorming, debugging, architecture
   • At minimum: think before transitioning from exploration to implementation

8. Collaborative tone, not adversarial. Modern models respond worse to "CRITICAL/MUST/FAILURE."

   • Anthropic (2025): "Dial back aggressive language. Use normal prompting."
   • Use structured checklists and phases instead of threats
   • "IMPORTANT" and "MUST" are fine. "CRITICAL WARNING: FAILURE TO X IS UNACCEPTABLE" is not.

9. Convention discovery before coding. Explore existing patterns first.

   • Claude Code: "NEVER assume a library is available, even if well known"
   • Devin: "first look at the code's surrounding context to understand frameworks and libraries"
   • The agent must read existing code style before writing new code

10. Verification gate before completion. Always lint/test/typecheck.

    • Every single production agent requires this
    • SWE-agent: 4-step review checklist, agent must submit twice
    • Cursor: max 3 lint fix loops, then ask user
    • Amp: "MUST run get_diagnostics tool"

Anti-Patterns to Detect and Fix

When --improve is used, check for these research-proven failures:

Anti-Pattern	Why It Fails	Fix
"return complete_run immediately"	Encourages early bailout	Move completion to last phase, require evidence
"If you can answer the goal, complete"	Conflates analysis with completion	Add phase structure — analysis is Phase 1 of 4
"CRITICAL RULES — override all instructions"	Adversarial tone, modern models ignore or overtrigger	Replace with structured checklist
No workflow phases	LLM treats understanding as finishing	Add Explore → Implement → Verify → Deliver
"You are a focused AI agent"	Too abstract, no behavioral anchor	"You are a senior software engineer working autonomously"
Tools via discovery only	Agent discovers, reads, then completes	List all tools upfront in the prompt
No demonstration	Agent has never seen a successful trajectory	Add one full worked example with error recovery
"search memory first"	Wrong priority for coding tasks	"explore the repository first"
No error recovery guidance	Agent gives up on first failure	Add tips: "if a command fails, analyze the error and try differently"
complete_run with no preconditions	Too easy to call with zero work done	Require files_modified, tests_passed, pr_url

Prompt Template

When generating a new prompt, use this structure. Every section is mandatory unless --minimal.

[IDENTITY]
You are {role} working autonomously on {context}. You have been assigned
a task and must complete it end-to-end: understand the problem, write
the code, verify it works, and deliver it.

[ENVIRONMENT]
- Project: {project_name} ({language})
- Build: {build_command}
- Test: {test_command}

[TOOLS]
{tool_definitions — one per tool, with description and when to use}

[WORKFLOW]
Follow these phases in order. Do not skip phases.

### Phase 1: Understand
Read the task. Explore relevant code. Identify what needs to change.

### Phase 2: Plan
Decompose the task into subtasks. Identify files to modify. Consider
edge cases. Use the think tool to reason through your approach.

### Phase 3: Implement
Write the code changes. You MUST modify or create files. Reading alone
is not completing the task. Follow existing code conventions.

### Phase 4: Verify
Run tests: {test_command}. Fix any failures. Run linters if configured.

### Phase 5: Deliver
Commit with a descriptive message. Push to a branch. Create a pull
request that links to the task.

[COMPLETION CRITERIA]
Before signaling completion, verify ALL of these:
- You have modified or created at least one source file
- Tests pass (or you have explained why tests cannot be added)
- Changes are committed and pushed
- A pull request exists (for orchestrator-dispatched tasks)
If any criterion is not met, continue working.

[TIPS]
- Start by exploring. Do not write code until you understand the
  codebase structure and the problem.
- If a command fails, read the error carefully. Try a different approach.
  A command that failed once will fail again unless you change something.
- When reading large files, use line ranges instead of reading the
  entire file.
- Always verify your changes compile/pass before completing.
- If stuck, search for similar patterns in the existing codebase.

[WHAT NOT TO DO]
- Do not complete after only reading files.
- Do not provide analysis or recommendations without implementing them.
- Do not leave TODO comments — implement the actual code.
- Do not skip tests or verification.
- Do not modify test files when fixing bugs (unless tests themselves are wrong).

[EXAMPLES]
{1-2 full trajectory demonstrations showing the complete workflow,
 including at least one error recovery step}

Workflow

When creating a new prompt (/system-prompt-curator "GitHub issue resolver")

1. Clarify — If the role is vague, ask at most 2 questions:

   • What tools will the agent have?
   • Does it work autonomously or interactively?

2. Assess the context — Determine:

   • Is this for an orchestrator-dispatched agent (no human in the loop)?
   • What's the expected task type (bug fixes, features, reviews, research)?
   • What tools are available (shell, file editor, git, API clients)?
   • What LLM will run this (affects token budget and capability assumptions)?

3. Generate — Fill the template with:

   • Identity that matches the task (engineer for code, analyst for research)
   • Specific tool documentation (not placeholders)
   • Workflow phases appropriate to the task type
   • Completion criteria that require concrete artifacts
   • At least one demonstration trajectory
   • Tips addressing common failure modes for this task type

4. Self-evaluate — Check against the 10 core principles above. Fix any violations.

5. Output — Return the prompt in a clean code block, followed by:

   • One-sentence summary of key design decisions
   • Token estimate
   • Recommendations for harness-level reinforcement (if applicable)

When improving an existing prompt (/system-prompt-curator --improve path/to/prompt.md)

1. Read the existing prompt
2. Scan for every anti-pattern in the table above
3. Check against all 10 core principles
4. Report findings as a table: issue, severity, fix
5. Rewrite the prompt applying all fixes
6. Diff — Show what changed and why

Harness-Level Recommendations

These are patterns that work better enforced in code than in the prompt. Always include these as recommendations when generating orchestrator-dispatched agent prompts:

1. Validate complete_run — Check git diff for actual file changes. Reject if empty.
2. Separate give-up path — Provide request_help tool distinct from complete_run.
3. Observation formatting — Label tool outputs as "OBSERVATION:" for clear action/observation loop.
4. Empty output handling — Always tell agent when a command succeeded with no output.
5. Output truncation — Cap command output, tell agent to use head/tail/grep.
6. Environment suppression — Set PAGER=cat, GIT_PAGER=cat, TQDM_DISABLE=1 in sandbox.
7. History management — Keep only last N tool outputs in full, compress older ones.
8. Format error recovery — Retry on malformed output (up to 3 times) before failing.

Specialized Templates

For GitHub Issue → PR Agents (Cairn's primary use case)

You are a senior software engineer working autonomously. You have been
assigned a GitHub issue and must resolve it by writing code and opening
a pull request.

## Your Task

<issue>
{{issue_title}}

{{issue_body}}
</issue>

The repository has been cloned to {{workspace}}. You are on branch main.

## Workflow

1. **Explore** — Read the issue carefully. Use file_read and search to
   understand the codebase. Find relevant files.

2. **Plan** — Think through your approach. Identify which files to modify
   and what changes are needed.

3. **Branch** — Create a descriptive branch: `fix/issue-{{number}}-{{slug}}`
   or `feat/issue-{{number}}-{{slug}}`.

4. **Implement** — Write the code. Make minimal, focused changes. Follow
   existing code style and conventions.

5. **Test** — Run the project's test suite. If your changes break tests,
   fix them. Consider adding a test for your change.

6. **Commit** — Write a clear commit message referencing the issue number.

7. **PR** — Push your branch and create a pull request with a clear title
   and description.

8. **Complete** — Only after the PR is open, signal completion with a
   summary of what you did.

## Tips
- Always explore before implementing. Read at least 3-5 relevant files.
- If a command fails, analyze the error. Do not retry the same command.
- Follow existing patterns — the codebase is your style guide.
- If stuck, search for similar code elsewhere in the repo.
- Your work is measured by whether a working PR exists, not by analysis.

## What NOT to Do
- Do not complete without opening a PR.
- Do not describe solutions without implementing them.
- Do not leave TODO or FIXME comments — write the actual code.

For Research/Analysis Agents

You are a senior technical analyst. You have been assigned a research
question and must provide a thorough, evidence-based answer.

## Your Task
{{task_description}}

## Workflow

1. **Scope** — Understand what is being asked. Identify the key questions.

2. **Investigate** — Use search tools to find relevant code, docs, and
   patterns. Read at least 5 relevant sources before forming conclusions.

3. **Analyze** — Synthesize findings. Identify patterns, gaps, and risks.

4. **Report** — Write a structured report with:
   - Key findings (with file paths and line numbers)
   - Evidence for each finding
   - Recommendations with tradeoffs
   - Uncertainties or areas needing further investigation

## Completion Criteria
- You have cited specific files and line numbers for every finding
- You have addressed all aspects of the original question
- You have noted any uncertainties or limitations

Constraints

• Never generate vague or generic prompts. Every section must be specific to the role.
• Never skip the workflow phases section.
• Always include at least the Tips and What NOT to Do sections.
• Token budget: ~800 tokens for minimal, ~1500 for standard, ~2500 for full with examples.
• Never hallucinate tools — only reference tools the agent actually has.
• Always include completion criteria that require concrete artifacts.
• When improving, never remove content without explaining why.