---
name: Formax Permissions Workflow
slug: formax-permissions-workflow
category: AI Engineering
description: Formax Permissions Workflow is used when changing or debugging Formax permission rules, approval prompts, workspace boundaries, and /permissions management. It covers policy preflight, matching, persistence, and UI parity with Claude Code.
github: "https://github.com/yusifeng/formax/tree/main/.codex/skills/formax-permissions-workflow"
language: TypeScript
stars: 192
forks: 7
install: "npx degit https://github.com/yusifeng/formax/tree/main/.codex/skills/formax-permissions-workflow ~/.claude/skills/formax-permissions-workflow"
installs_to: ~/.claude/skills/formax-permissions-workflow
source_path: .codex/skills/formax-permissions-workflow/SKILL.md
collection_size: 22
category_size: 3278
collection_url: "https://dirskills.com/collections/yusifeng/formax"
added: 2026-09-06T05:19:18.333Z
last_synced: 2026-09-06T05:19:18.333Z
canonical_url: "https://dirskills.com/skills/formax-permissions-workflow"
---

# Formax Permissions Workflow

Formax Permissions Workflow is used when changing or debugging Formax permission rules, approval prompts, workspace boundaries, and /permissions management. It covers policy preflight, matching, persistence, and UI parity with Claude Code.

**Install:**

```bash
npx degit https://github.com/yusifeng/formax/tree/main/.codex/skills/formax-permissions-workflow ~/.claude/skills/formax-permissions-workflow
```

## README

# Formax permissions / approvals workflow

## Goal

Use this skill when changing policy preflight, approval prompts, remember side-effects, or `/permissions` management.

## Read First

- `docs/contracts/permissions-policy-contract.md`
- `docs/contracts/interactive-input-contract.md`
- `docs/contracts/semantics-contract.md` when the change crosses TUI / app-server / Web

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

## Code Map

### 1) Policy preflight (ToolCall -> allow/ask/deny decision)
- `packages/core/src/tools/executor/policyPreflight.ts`: turns `ToolCall` into a `PolicyAction` and decides deny / prompt / allow
- `packages/core/src/tools/executor/policyAction.ts`: `ToolCall` -> `PolicyAction` mapping
- `packages/core/src/tools/executor/policyExplain.ts`: explain / debug text for decisions
- `packages/core/src/tools/modules/bash/policy.ts`: Bash risk classification

### 2) Permissions storage + matching (rules & precedence)
- `packages/core/src/adapters/permissions/permissionsStore.ts`: read / write settings and merge precedence
- `packages/core/src/adapters/permissions/permissionKeys.ts`: stable keys / paths for settings
- `packages/core/src/adapters/permissions/matcher.ts`: matcher semantics

### 3) Approvals (prompt UI + persistence side-effects)
- `packages/core/src/tools/executor/approvalService.ts`: `ensureApproved` flow and remember writes
- UI prompts:
  - `packages/core/src/components/tool/bashApprovalPrompt.tsx`
  - `packages/core/src/components/tool/fsReadApprovalPrompt.tsx`
  - `packages/core/src/components/tool/fsWriteApprovalPrompt.tsx`
  - `packages/core/src/components/tool/skillApprovalPrompt.tsx`
  - `packages/core/src/components/tool/editApprovalPrompt.tsx`
- Shared pieces:
  - `packages/core/src/components/ui/ApprovalHeader.tsx`
  - `packages/core/src/components/ui/ConfirmMenu.tsx`

### 4) /permissions overlay (manage rules + workspace)
- `packages/core/src/tui/permissions/PermissionsDialog.tsx`: state machine + key handling
- `packages/core/src/tui/permissions/ui.tsx`: rendering primitives
- `packages/core/src/features/repl/controller/ui/overlays.ts`: overlay open / close and dismissal messages
- Slash command wiring:
  - `packages/core/src/features/commands/registry.ts`
  - `packages/core/src/screens/repl/createReplCommandRegistry.ts`

If app-server or Web input behavior moves, also inspect:
- `packages/core/src/app-server/turn/inputStore.ts`
- `packages/core/src/app-server/server.ts`
- `packages/web-reference-react/src/store.ts`

## High-Signal Patterns

- Pattern A: tool approval prompt (3 options + Esc)
  - `Yes`
  - `Yes, ...` (remember / allow in repo or session)
  - `Type here to tell Claude what to do differently`
  - cancellation remains `Esc to cancel`, not a bespoke menu item
- Pattern B: destructive confirm prompt
  - use `Yes / No`
  - still support `Esc to cancel`
- Pattern C: partial emphasis in menu options
  - use `ConfirmMenu` emphasis support instead of ad-hoc JSX or ANSI
  - selected rows must not leave mismatched emphasis colors behind

## Minimal Workflow

1. Read the canonical contract(s) above and define the exact behavior delta.
2. Change the narrowest canonical code path first (`policyPreflight`, matcher / store, `approvalService`, or overlay state machine).
3. Preserve existing UI copy / spacing / colors / keys unless the user explicitly asks for UI changes.
4. Keep “what the user sees” separate from “what is injected back into model context”.
5. Run the minimum regression set below, then review via `AGENTS.md` before commit.

## Minimum Regression

- `bun run test -- packages/core/src/tools/executor/policyPreflight.test.ts`
- `bun run test -- packages/core/src/tools/executor/approvalService.test.ts`
- `bun run test -- packages/core/src/components/tool/bashApprovalPrompt.test.tsx`
- `bun run test -- packages/core/src/components/tool/fsReadApprovalPrompt.test.tsx`
- `bun run test -- packages/core/src/components/tool/fsWriteApprovalPrompt.test.tsx`
- `bun run test -- packages/core/src/components/tool/skillApprovalPrompt.test.tsx`
- `bun run test -- packages/core/src/tui/permissions/PermissionsDialog.test.tsx`
- If app-server / Web input behavior changed:
  - `bun run test -- packages/core/src/app-server/turn/inputStore.test.ts packages/core/src/app-server/server.test.ts`
  - `npm --prefix packages/web-reference-react run test -- src/store.test.ts`

## Guardrails

- Do not encode permission semantics inside prompt components; contracts live in policy / approval layers.
- Do not add bespoke key handling or ANSI styling when shared approval components already cover the case.
- Do not loosen permissions or remember scope just to make parity demos pass.
- Preserve approval UI copy / spacing / colors / key paths unless the user explicitly asks for UI changes.