Formax System Prompt Workflow

---
name: formax-system-prompt-workflow
description: Use when designing, refactoring, or debugging Formax system prompt assembly, system-reminder injection, or skills/deferred-tool prompt exposure semantics; mandatory for any change involving FORMAX_DEFERRED_TOOL_EXPOSURE and request-payload parity checks.
---

# formax-system-prompt-workflow

## Goal

Use this skill when changing system prompt assembly, reminder injection, deferred tool exposure, or skills prompt presentation.

## Read First

- `docs/contracts/prompt-tool-exposure-contract.md`
- `docs/contracts/skills-contract.md`
- `docs/contracts/semantics-contract.md` when request-scoped helper blocks affect replay or transcript semantics

Optional working notes:
- `references/parity-checklist.md`
- `references/parity-evidence-template.md`

These docs are canonical. If stable behavior changes, update them before or with code.

## Invariants

1. Keep a single prompt-profile path.
   - do not reintroduce `promptProfile`, `lite`, or similar profile branches
2. Treat `FORMAX_DEFERRED_TOOL_EXPOSURE` as a linked behavior bundle.
   - prompt variant, tools exposure style, and skills presentation must stay aligned
3. Keep helper blocks request-scoped and ephemeral.
   - injected `<system-reminder>` blocks and deferred helper blocks must not pollute persisted long-term history
4. Only claim capabilities that Formax runtime actually implements.
   - do not add CC-like capability prose before the runtime supports it

## Code Map

- `packages/core/src/prompts/system.ts`: system prompt text, variant selection, capability gates
- `packages/core/src/features/repl/controller/send/sendMainTurn.ts`: per-turn injected block order and REPL assembly
- `packages/core/src/tools/runtime/deferredToolExposureResolver.ts`: deferred tools exposure and helper-block content
- `packages/core/src/tools/modules/skill/index.ts`: skill tool description shaping and skills reminder text
- `packages/core/src/chat/engine.ts`: request assembly and injected-block persistence boundaries
- Cross-entrypoint mirrors when semantics move:
  - `packages/core/src/app-server/turnRunner.ts`
  - `packages/core/src/sdk/query/runner.ts`
- `scripts/repl-request-preview.ts`: quick dry-run payload preview without live network calls

## Deferred Exposure Checklist (`FORMAX_DEFERRED_TOOL_EXPOSURE=1`)

- system prompt variant resolves to `deferred_aligned`
- request contains `<available-deferred-tools>` helper content
- skills availability is delivered as a skills system-reminder helper block
- tool list starts from deferred exposure resolver output (`ToolSearch` first)
- tool-call chain remains valid: `ToolSearch(select:<tool>) -> <tool>`

## Minimal Workflow

1. Classify the change first: all-mode or deferred-only (`FORMAX_DEFERRED_TOOL_EXPOSURE=1`).
2. Update the canonical contract and prompt text first, then change resolver / wiring code.
3. Keep helper blocks request-scoped and ephemeral; do not let them leak into persisted history.
4. If semantics move, check REPL, app-server, and SDK paths together before calling the change done.
5. Run the minimum regression set below, then use request preview only as evidence, not as the only validation.

## Minimum Regression

- `bun run test -- packages/core/src/prompts/system.test.ts packages/core/src/tools/runtime/deferredToolExposureResolver.test.ts packages/core/src/features/repl/controller/send/sendMainTurn.test.ts`
- `bun run test -- packages/core/src/chat/engine.test.ts packages/core/src/config/settings/resolve.test.ts packages/core/src/sdk/query.test.ts packages/core/src/sdk/query.options-alignment.test.ts`
- `bun run test -- packages/core/src/app-server/turnRunner.test.ts` when app-server request assembly changes
- `bun run type-check`
- `bun run request:preview -- --text "执行下 pwd" --deferred` for quick payload inspection when deferred exposure is involved

## Guardrails

- Do not reintroduce prompt-profile branches (`lite`, `full`, `promptProfile`, or equivalents).
- Do not add new environment toggles for prompt capability sections; use code-level capability switches in `system.ts`.
- Do not loosen permissions or allow-list behavior just to make parity demos pass.