# Usage

Owner and AI-agent guide for working with `pi-minimax-pack`. Core harness stays generic; project-specific behavior flows through `.pi/minimax-policy.json` and profiles.

## How it works

The extension hooks into Pi's event lifecycle:

- `before_agent_start`
  - detect project, load merged policy
  - inject the global agent contract into the system prompt
  - auto-route relevant skills based on prompt keywords
  - append installed-resource advice when policy enables it
  - append validation directive (build/test/lint commands) when present
- `input`
  - reset per-turn tracking state (skipped when source is `extension`)
  - classify the workstream from the prompt for drift detection
  - detect correction phrases and (optionally) propose policy promotion
- `tool_call`
  - block shell redirection (force `write`/`edit` tool)
  - block plain `go build` for Wails projects
  - apply policy decision per command category (`safeRead`, `build`, `install`, `destructive`, `deploy`, `database`, `network`, `unknown`)
  - require read-before-edit for the `edit` tool
- `tool_execution_end`
  - track read/write/edit ops for status report
  - detect failed validation commands and capture evidence + hint
  - run artifact validation after a successful BUILD command when policy enables it
- `message_end`
  - append auto Status Report (changed / verified / unverified / blocked)
  - trigger auto-grind verification turn when files changed and validation commands exist
  - trigger force-verify turn for unverified writes (only when grind did not already run)

Auto-grind and force-verify are queued via `pi.sendUserMessage(..., { deliverAs: "steer" })` so Pi handles ordering. Extension-injected messages are detected via `event.source === "extension"` to avoid loops.

## Profiles

Profiles add technology-specific guidance without hardcoding project logic into core. The detector recommends profiles from evidence files in the project root.

Available profiles:

- `generic`
- `node`
- `go`
- `wails`
- `tauri`
- `rust`
- `python`
- `php`
- `postgres`
- `docker`

Policy can override or extend profile defaults. Wails is the canonical profile example: detector finds `wails.json`, profile blocks plain `go build`, policy can override.

## Policy layers

Merge order (later overrides earlier):

1. global user policy — `~/.pi/minimax-policy.json`
2. workspace policy — `<workspace>/.pi/minimax-policy.json`
3. project policy — `<project>/.pi/minimax-policy.json`
4. task/session policy — `<project>/.pi/minimax-policy.session.json`

See `POLICY_SCHEMA.md` for the full schema and rule format.

### Common scenarios

- **Generic**: rely on the default policy and add only local command overrides.
- **Node**: prefer build/test/lint commands from `package.json` scripts.
- **Go**: set migration/build expectations explicitly in project policy.
- **Wails**: profile or project policy keeps `wails build -clean` as the canonical build command.
- **Python**: use `pyproject.toml`/`requirements.txt` detection, then add test/migration rules.
- **PHP**: use `composer.json` detection and add install/migration rules.
- **Database**: use artifact and backup notes for migration flows.
- **Docker**: use deploy/network caution rules per project policy.

## Self-improvement loop

The harness can promote corrections into policy rules when `memoryPolicy.detectCorrections` is enabled:

1. detect correction phrase or repeated failure pattern in user input
2. extract candidate rule (id, condition, action, message)
3. require explicit approval (UI confirm) — unless `memoryPolicy.autoPromote` is enabled
4. write the approved rule to `.pi/minimax-policy.json`
5. enforce the rule through the policy gate, not from memory alone

Memory supplies context; policy supplies enforcement. Default policy keeps both `detectCorrections` and `autoPromote` off.

## Editing the harness

The repo is owner-controlled. Agents may edit any file when required.

- `extensions/global-contract.ts` must be edited with a verified patch/read-back workflow. Do not use careless rewrites that can damage escape sequences inside the embedded contract.
- Project-specific behavior belongs in policy and profiles, not in extension code.
- Prefer installed prompts/extensions before suggesting new installs.

## Rollback

If a change misbehaves:

1. revert the latest change with `git`
2. re-run `npm run smoke` and the relevant module test
3. inspect the merged policy before applying stronger enforcement