System prompt customization

IsonForge has four flags for the system prompt: two to replace it, two to append to it. All four work in interactive and print modes.

Flag	Effect
`--system-prompt <text>`	Replace the entire default prompt with this text
`--system-prompt-file <path>`	Replace from file contents
`--append-system-prompt <text>`	Append after the default prompt
`--append-system-prompt-file <path>`	Append file contents after the default prompt

The replace flags (--system-prompt, --system-prompt-file) are mutually exclusive. Append can combine with either.

Append (most common)

Append preserves IsonForge's default tool guidance, project context, FORGE.md injection, and safety rails. You just add session-specific rules:

isonforge --append-system-prompt "Always use TypeScript strict mode. No \`any\`."

isonforge --append-system-prompt-file ./team-style.md

Settings.json equivalent:

{
  "systemPromptAppend": "Always use TypeScript strict mode. No `any`."
}

Use this for:

Project-specific style rules.
Per-task constraints ("output only JSON", "respond in Indonesian").
Tightening or relaxing default behavior.

Replace (advanced)

Replacing drops the entire default prompt: tool guidance, FORGE.md, project metadata, safety rails. You take responsibility for everything the agent needs.

isonforge --system-prompt "You are a translator. Translate input from English to Indonesian. No other behavior."

isonforge --system-prompt-file ./prompts/translator.md "translate" < input.txt

Use this when:

The session has a completely different identity from coding (e.g., translation, summarization, classification).
You're running a non-interactive -p script and don't want any default tool-use behavior.
You're integrating IsonForge as a generic LLM endpoint with your own prompt.

When --system-prompt is active, IsonForge skips:

FORGE.md auto-load
Project metadata block (git branch, file index, add_dirs)
Web Forge workspace summary
Tool list inventory
Plan mode addition

The system prompt becomes literally what you provided. Tool calling still works mechanically (tools are exposed to the model), but without the default guidance the model may behave very differently. Test before relying on it.

Decision matrix

You want to...	Use
Add a rule on top of normal IsonForge behavior	`--append-system-prompt`
Repeat a rule across many sessions	`systemPromptAppend` in settings.json
Run a non-coding task in a script	`--system-prompt-file`
Try out a completely different agent persona	`--system-prompt`
Apply per-team conventions	`--append-system-prompt-file ./team-rules.md` in a wrapper script

Examples

Strict TypeScript:

isonforge --append-system-prompt "All TypeScript MUST use strict mode. Refuse to add 'any'. Prefer 'unknown' + narrowing."

Output format lock:

echo "raw data here" | isonforge -p \
  --append-system-prompt "Output ONLY a single JSON object. No prose, no fences." \
  --output-format json \
  "extract user info"

Translation agent:

isonforge -p --system-prompt-file ./prompts/id-translator.md "translate" < article.md

Where id-translator.md is:

You are a professional Indonesian translator. The user will provide English text. Translate it into Bahasa Indonesia.

Rules:
- Match register: casual stays casual, formal stays formal.
- Preserve code identifiers + library names in English.
- Output only the translation. No commentary.

Per-project conventions:

{
  "systemPromptAppend": "Project conventions:\n- All routes use the response helper in lib/response.ts\n- Validation via Zod, no manual checks\n- Tests required for every new route"
}

Verify what got sent

isonforge --verbose ... logs the assembled system prompt to stderr. Use this when an append rule isn't taking effect to confirm the gateway received it.