vibecoding-devtools 1.0.1

package/skills/maestri-agent-cli/references/codex.md

@@ -0,0 +1,190 @@
+# OpenAI Codex CLI
+
+Verified live on Codex 0.164.0, Windows, ChatGPT Free account (2026-10-27); quota windows and `/clear` on 0.166.0, paid
+plan (2026-11-04).
+
+## Identify
+
+- Launch command: `codex`, e.g. `codex --no-daemon`.
+- Banner: `>_ OpenAI Codex (v<version>)` and the working folder.
+- Input prompt is `›`.
+- Footer: `<model> <effort> · <folder>`, then `? for shortcuts` and warnings such as `⚠ 1 warning · f2 to view`.
+- `/status`: model and reasoning effort, provider, folder, **Permissions**, `AGENTS.md` in use, **Account** and plan,
+  collaboration mode, session id, and the usage limit with its reset date.
+
+## States
+
+| State | On screen |
+|---|---|
+| Idle | `› Ask Codex to do anything` (placeholder) |
+| Done | `• <reply>` then `Worked for <time> • <clock>` and an idle input |
+| Warnings panel | `Warnings · 1 of 1 · ...` with `k keep & next · esc dismiss & close` |
+| Menu | Numbered list with `enter select · esc back` |
+| Approval prompt | `Would you like to run the following command?` with numbered options |
+
+The warnings panel can open on its own while you type: then your keys go to the panel (`k` keeps the warning and closes
+it). `check` before sending text, and resend if it did not reach the input.
+
+## Sending a prompt
+
+Send the text, then `\n` in a separate `--raw` call.
+
+## Permissions and sandbox
+
+- `/permissions` → **Update Model Permissions**:
+  1. **Ask for approval**: reads and edits the workspace and runs commands; asks for internet access or edits outside
+     the workspace.
+  2. **Approve for me**: asks only for actions detected as potentially unsafe.
+  3. **Full Access**: edits outside the workspace and uses the internet without asking.
+  4. **Read Only**: reads the workspace; asks for edits and internet access.
+- `/status` may show a mode not in that list (here `Workspace (granular)`). Read Only shows as
+  `Read Only (Ask for approval)`.
+- **Changing the mode gives no confirmation screen**, only a history line `• Permission selection requested: <mode>`,
+  and options 3 (Full Access) and 4 (Read Only) sit next to each other. Run `/status` after every change and check
+  `Permissions:`.
+- On Windows the sandbox is set in `~/.codex/config.toml`, e.g. `[windows] sandbox = "elevated"`.
+- Blocked by the sandbox, the agent can **refuse on its own without an approval prompt**: asked to write outside the
+  workspace, it replied that the folder is not writable and stopped. Read its reply, not only the screen state.
+- Changing the permission mode lowers or raises what the agent may do on the user's behalf: ask the user first.
+- `/approve` approves one retry of a recent auto-review denial.
+
+## Autonomous launch and command rules
+
+Verified on Codex 0.166.0, Windows (2026-11-06): local help, isolated rule checks and a live recruited agent.
+
+```bash
+codex --no-daemon --approve-for-me
+```
+
+`--approve-for-me` routes approval requests through automatic review with the workspace-write sandbox. It does not
+grant full access. Verify `/status`: **Workspace (Approve for me)**. The live check ran `npm.cmd --version` and wrote
+a workspace file without human approval. PowerShell blocked `npm.ps1`; `npm.cmd` worked. Hook trust remains separate:
+the test session continued without trusting hooks, so this check did not exercise hook execution.
+
+Alternative: `codex --no-daemon -a never -s workspace-write` never asks a person; failures return to the agent.
+It does not provide automatic approval for blocked operations. For tasks requiring shell networking, the configuration
+override is `-c sandbox_workspace_write.network_access=true`; this enables outbound network within workspace-write,
+not writes outside it. The key is documented and accepted by the installed parser; outbound access was not tested.
+The unauthenticated fake-home run reported read-only permissions: always verify effective permissions after startup.
+See the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
+
+For a limited agent, use a dedicated `CODEX_HOME` and a sandbox, with narrow grants in
+`CODEX_HOME/rules/default.rules` (normally `~/.codex/rules/default.rules`):
+
+```python
+prefix_rule(pattern = ['npm', '--version'], decision = 'allow')
+prefix_rule(pattern = ['git', 'push'], decision = 'forbidden')
+```
+
+```bash
+codex --no-daemon -a never -s read-only
+codex execpolicy check --rules /path/to/isolated-codex/rules/default.rules -- npm --version
+```
+
+Set `CODEX_HOME` to the prepared directory before either command. The installed checker returned `allow` for
+`npm --version`, `forbidden` for `git push`, and no match for `npm install`. Write rule files as UTF-8 without BOM;
+the installed parser rejected a BOM. Rules match argument prefixes; choose task-specific command grants.
+
+Approval option `p` saves the proposed prefix as an allow rule in the user layer's `rules/default.rules`; it is not a
+one-time approval. The save location is documented; this review did not press `p` against a real home. Rules load at
+startup, including trusted project layers.
+See [command rules](https://learn.chatgpt.com/docs/agent-configuration/rules).
+
+These grants control execution outside the sandbox; unmatched commands can still run within sandbox permissions.
+Neither `-a never` nor an allow rule list creates a strict commands-only boundary. Use an external enforcement layer
+if that is required. Do not combine limited-agent grants with `--approve-for-me`, which can approve other requests.
+`--dangerously-bypass-approvals-and-sandbox` removes both safeguards: use only at the user's explicit request.
+
+## Approval prompt
+
+```text
+• Running <command>
+  Would you like to run the following command?
+  Environment: local
+  Reason: <why the agent needs it>
+  $ <command>
+› 1. Yes, proceed (y)
+  2. Yes, and don't ask again for commands that start with `<command>` (p)
+  3. No, and tell Codex what to do differently (esc)
+  Press enter to confirm or esc to cancel
+```
+
+- Edits also come as commands (e.g. `Set-Content` on Windows), so file edits show this same prompt.
+- `• Running <command>` shows up **before** approval. After it, the history shows
+  `✔ You approved codex to run <command> this time`, then `• Ran <command>` and its output.
+- Enter or `y` approves once. `p` (option 2) persists the rule: ask the user first. Esc denies.
+
+## Model and effort
+
+- `/model` → **Select Model and Effort**: numbered models, `enter select · esc back`. The list depends on the plan (on a
+  Free account: GPT-6-Luna, GPT-5.6-Terra, GPT-5.6-Luna).
+- **Exact ids:** `codex debug models` prints the account's catalog as JSON: `slug` is the id (e.g. `gpt-6.1-sol`) and
+  `supported_reasoning_levels` lists the efforts. Launch with
+  `codex --model <slug> -c model_reasoning_effort=<low|medium|high|...>`.
+
+## Quota
+
+- `/status` shows the limit as **percent left**, e.g. `Monthly limit: [bar] 100% left (resets 15:45 on 26 Nov)` on a
+  Free account, and points to <https://chatgpt.com/settings/usage>. On a paid plan (Codex 0.166) it shows a five-hour
+  and a weekly limit, each with percent left and reset time.
+- Context: the docs say `/status` also shows token usage; not yet verified live.
+- `/usage` → **Usage**: `View analytics` (usage history) and `Redeem reset` (use a usage-limit reset when one is
+  available).
+- Not yet observed: the limit-reached screen.
+
+## Keys
+
+| Key | Raw | Action |
+|---|---|---|
+| Enter | `\n` | Send or select |
+| Esc | `\e` | Back; closes menus and the warnings panel (dismissing the warning) |
+| Backspace | `\x7f` | Delete a character |
+| ↑ / ↓ | `\e[A` / `\e[B` | Navigate |
+| F2 | `\eOQ` | Open the warnings panel |
+| `k` | `k` | In the warnings panel: keep the warning and go to the next |
+| `y` / `p` | `y` / `p` | In an approval prompt: approve once / approve and persist the rule |
+| `?` | | **Typed as text**: it does not open a shortcuts panel |
+
+## Slash commands for the Maestro
+
+`/status`, `/model`, `/permissions`, `/approve`, `/usage`, `/config`, `/compact`, `/clear` (clears the terminal and
+starts a new chat), `/new`, `/resume`, `/plan`, `/side` (side conversation in a fork), `/diff`, `/warnings`, `/mcp`,
+`/hooks`, `/skills`, `/daemon`. Destructive or stopping: `/delete` (permanently deletes the session), `/archive`,
+`/logout`, `/quit` and `/exit`: only when the user asks.
+
+## Built-in capabilities
+
+Tools as the agent listed them (GPT-6-Luna): `functions.exec` runs JavaScript that calls the work tools
+(`tools.exec_command`, `tools.write_stdin`, `tools.apply_patch`, `tools.view_image`, `tools.web__run`, goal and MCP
+tools); `collaboration.spawn_agent`, `send_message`, `followup_task`, `wait_agent`, `interrupt_agent`, `list_agents` for
+subagents; `request_user_input`, `clock.sleep`.
+
+| Need | How |
+|---|---|
+| Web search | `tools.web__run`; the docs also name the launch flag `codex --search` |
+| Read images | `tools.view_image`; `codex --image <file>` at launch |
+| Generate images | Skill `imagegen` |
+| Subagents | `collaboration.spawn_agent`; `/agents`, `/subagents` |
+| Code review | `/review` (working tree, base branch, commit), skill `review-agent` |
+| Plan before editing | `/plan` (not while it works) |
+| Side question | `/side` or `/btw` |
+| Run until a goal is met | `/goal` |
+| Background terminals | `/ps`; `/stop` stops them all |
+| Git worktree | `/worktree` |
+
+The workspace-write sandbox keeps shell networking off by default. Configure needed access at recruitment using the
+launch guidance above; a later change to a running agent follows the skill's permission-prompt policy.
+
+Built-in skills (`~/.codex/skills/.system`): `imagegen`, `openai-docs`, `review-agent`, `skill-creator`,
+`skill-installer`. Without any install by the user, `$` (or `/skills` → List skills) also showed OpenAI curated plugins
+in `~/.codex/plugins/cache/openai-curated-remote`: `plugin-management` and `work-pets` (pet skills), plus apps such as
+Codex Document Control and Safety Settings. Maestri's skills in the list come from Maestri, not from Codex.
+
+## Notes
+
+- With `--no-daemon` the startup warning is:
+  `Running without the shared background server: Bedrock sign-in requires embedded mode.`
+
+## Not yet observed
+
+Limit-reached screen, logged-out screen, API or network errors.

package/skills/maestri-budget/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: maestri-budget
+description: Pace the context and quota of the agents on the Maestri canvas, so every CLI's quota lasts the whole cycle and none is left unused when it resets. Load it as the Maestro at a checkpoint - start of a session, after a large delegated task finishes, before handing out a large task, or when an agent shows a limit warning - never for routine checks.
+---
+
+# Context and Quota Budget
+
+You're the Maestro on a Maestri canvas. The agents may run different CLIs on different accounts, and each account has
+its own quota pools, windows and prices. Pace them: a pool that runs out early stops the work, and quota left when a
+pool resets is lost. The goal is every pool close to empty at its reset, with no stop before it.
+
+You pace mostly by **choosing who gets each task**. You change an agent's model only when the user put it under your
+control (section 4). Reading quota and context costs tokens too, so you read them only at checkpoints and decide from
+your ledger in between. How to open each screen is in the `maestri-agent-cli` references.
+
+## 1. Checkpoints
+
+Read at these moments only, never on a timer and never while the agent you would read is working:
+
+- **Start of a session**, or your first delegation: every pool and every agent.
+- **A large task finished**: the agent reported DONE or PENDING on a task that took many turns or more than about half
+  an hour. Read that agent's pool and context.
+- **Before handing out a large task**: choose the agent from the ledger. Read again only if that pool's row is more than
+  a few hours old.
+- **A limit warning**, an error about quota, or an agent that slows down: read that pool.
+
+## 2. Ledger
+
+Add a `## Pools` section to the `ledger.md` that `maestri-agent-cli` keeps in your session directory:
+
+```markdown
+## Pools
+
+| Pool | Agents | Window | Left | Resets at | Read at |
+|---|---|---|---|---|---|
+| Antigravity / Gemini | Lynx | week | 82% | Sat 14:00 | Mon 10:12 |
+| Antigravity / Gemini | Lynx | 5 h | 60% | Mon 13:40 | Mon 10:12 |
+| Claude Code / Default | Hawk | week | 55% | Thu 09:00 | Mon 10:12 |
+```
+
+- One row per pool and window, scarce pools included (Argon on Antigravity).
+- **Left** is the percent remaining. Claude Code shows percent used: write `100 - used`.
+- Write **Resets at** and **Read at** as date and time: `Refreshes in 98h 45m` read at Mon 10:12 resets Fri 13:00.
+- **Your own pool:** you spend quota too, and you cannot open your own CLI's panels through `maestri`. If an agent runs
+  on your account, its reading covers you; otherwise ask the user for your numbers at a full checkpoint.
+
+## 3. Pace and delegation
+
+For each pool, at a checkpoint:
+
+- `elapsed` = 100 × time already gone / window length, from the reset time (a percent, like `used`).
+- `used` = 100 - left.
+- `pace` = used / elapsed. Above 1.0, the pool runs out before it resets.
+- Unknown window length or reset time, or a reading taken before the pool's last reset: do not compute; read the pool
+  again at the next checkpoint.
+
+| Pace | Meaning | Do |
+|---|---|---|
+| below 0.85 | quota will be left over | send more work to the agents on this pool |
+| 0.85 to 1.0 | on track | keep going |
+| above 1.0 | runs out before reset | send new work to agents on other pools |
+| above 1.3 | runs out well before reset | only essential work here; tell the user if routing cannot fix it |
+
+- While less than 15% of a window has gone, skip the pace and keep the previous decision; a pool already spent or too
+  low for the next task still counts.
+- A pool with two windows (five hours and week) is limited by the tighter one: decide by the worse of the two.
+
+- **Roles come first.** Who does what is set by the agents' role prompts and by your own instructions. An agent with a
+  dedicated function does that function: never take a task from its owner to save quota.
+- **Everyone works.** The main agents carry the main work; an agent declared as a helper on a lighter model takes the
+  simple, repetitive tasks to relieve them. It supports them and never replaces them: overload it and its pool runs out
+  early. An idle agent with quota left is quota lost.
+- **Pace splits the rest.** Work that more than one agent could do goes to the one whose pool is furthest below pace,
+  matching the task to the agent's model: mechanical work (docs, renames, formatting, triage) to lighter models, deep
+  reasoning (architecture, hard debugging, costly-to-get-wrong planning) to the strongest. Smaller quotas end up with
+  less work, larger ones with more. Short, focused tasks last longest: quota is spent in proportion to token cost.
+- **Verify work from lighter models, always.** A result from an agent on a lighter model (such as Gemini Flash on
+  Antigravity) is a claim until you check it, even when it reports DONE. Check it in proportion to the task, without
+  redoing it: read the file it wrote, rerun the count or command, read the diff and run the tests, or send code to a
+  main agent for review. Report it to the user only after that. Keep development work off lighter models when you can.
+- **Scarce pools** (a small weekly-only quota, such as Argon on Antigravity): enough for only a few large tasks a week.
+  Reserve them for the tasks that truly need that model and plan those tasks for the week.
+- **Short windows** (five hours): when one is nearly spent, send work to agents on other pools until it refreshes. Do
+  not change the weekly plan because of it.
+- **Last day of a cycle:** a pool that will reset with quota left takes work pulled forward from the backlog the user
+  already approved. Never invent work just to spend quota.
+
+## 4. Switching models: managed Antigravity agents only
+
+Every agent is `fixed` in the ledger unless the user said otherwise. Never change the model, effort or settings of a
+`fixed` agent, and never switch models on Claude Code or Codex agents.
+
+An Antigravity agent the user marked `managed` (a multi-model generalist under your control) is the exception. On a Pro
+plan its account showed three pools (Antigravity 1.4.9): Gemini (Flash, Pro), Claude and GPT (Opus, Sonnet, GPT-OSS)
+and Argon. Read `/usage` at the first checkpoint and trust the screen. For it:
+
+- Pick the model for each task: Flash for mechanical work, Sonnet or Pro for day-to-day work, Opus or Argon only for
+  high-reasoning work. Argon has only a small weekly quota and no five-hour window: a few large tasks a week.
+- Prefer the pool with more room by the pace above.
+- **Switch only between tasks**, never mid-task: a switch mid-task loses the prompt cache and costs more.
+- After a restart, the agent is back on the preset's model: check its footer before the next task.
+
+## 5. Context: every agent
+
+- **Before handing any task to an agent**, if it is unrelated to what that agent did last and the previous task is
+  closed, clear it first with the command in its CLI reference (`/clear` in the three, as of the versions there). This
+  needs no reading and keeps the new task from paying for the old context.
+- **At a checkpoint**, read the context of the agents that just finished. If the next task continues the same work and
+  context is above about 60%, `/compact`; where the reference says it takes text (Claude Code), add what must survive,
+  e.g. `/compact keep the T-12 decisions, open items and files touched`.
+- **Never** compact or clear an agent that is working, is in the middle of a task, has a prompt or menu open, or whose
+  report has not arrived. Compacting between tasks keeps the CLI's own auto-compaction from firing in the middle of one.
+
+## 6. Ask the user first
+
+Turning on paid credits (Antigravity **Use AI Credits**, extra usage), using a usage-limit reset (Codex **Redeem
+reset**), moving an agent to another account, changing a preset, or making an agent `managed`. After a full checkpoint,
+tell the user only what is off pace or needs their decision, one line per pool.

package/skills/maestri-protocol/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: maestri-protocol
+description: Reply format for agent-to-agent messages on the Maestri canvas. Load it whenever you delegate a task to another agent with `maestri ask`, report back to another agent (ask back), or receive a message that starts with `~ ` or a task that mentions maestri-protocol. You MUST read this skill before replying to a task that asks for a maestri-protocol report.
+user-invocable: true
+---
+
+# Maestri Agent Reply Protocol
+
+You're running inside Maestri, a spatial development workspace that connects AI agents, terminals, notes, and browser
+portals on a visual canvas. This skill extends the base `maestri` skill: it defines how agents report back and ask
+questions to each other, so a reply from an agent is never mistaken for a message from the user or from another agent.
+
+## Reply format
+
+Every report or question you send to another agent with `maestri ask` (an ask back, the answer to a task or message you
+were given, or a question that is not a task) starts with one header line:
+
+```text
+~ Name | STATUS | ref | one-line summary
+```
+
+- `~` followed by a space marks agent-to-agent traffic.
+- `Name`: your own name exactly as `maestri list` prints it under `You:` (`Name @ Workspace` when replying across
+  workspaces).
+- `STATUS`, one of:
+  - `DONE`: finished, nothing left
+  - `PENDING`: finished, with open items listed below
+  - `BLOCKED`: cannot continue; say what you need and from whom
+  - `ERROR`: failed; say what failed and what you tried
+  - `ACK`: received, no action needed. Never use it to say you started: your first ask back ends the sender's wait.
+  - `ASK`: a question, not a report; the answer comes back as a report with the same ref
+- `ref`: the ref the task came with; otherwise the most precise work item (PR number, branch@short-sha, task or decision
+  id, file). `-` only when nothing applies.
+- Summary: one line, no secrets.
+
+Details, evidence and lists go on the following lines; in PowerShell, use real line breaks, not `\n`. Keep the whole
+message inside quotes and avoid double quotes, backticks and `$` in it, which break the shell command. Never send a bare
+`ok` or `done`. One report per task; post progress with `maestri floor status`.
+
+```text
+maestri ask "Maestro" "~ Hawk | DONE | T-12 | login screen wired, tests green, PR #412 open"
+maestri ask "Maestro" "~ Lynx | BLOCKED | T-13 | need the token format decision from the user"
+maestri ask "Maestro" "~ Kite | ACK | design-spec | reply format adopted"
+```
+
+## Delegating a task
+
+Give each task a ref (a task id like `T-12`, or the PR, branch or decision it concerns) and end the prompt with this
+footer, filled in with your name and the ref. Do this in `--batch` prompts too, and never ask for a bare `ok` reply.
+
+```text
+ref: T-12
+When done, load the maestri-protocol skill and report back with:
+maestri ask "Your Name" "~ Your Name | STATUS | T-12 | one-line summary"
+STATUS is one of DONE, PENDING, BLOCKED, ERROR, ACK. Details go on the following lines.
+```
+
+Your name is under `You:` in `maestri list`; when the agent is in another workspace, use the `Name @ Workspace` address
+shown right under `You:` instead. The footer carries the whole format, so the agent can follow it even if it does not
+load this skill.
+
+## Receiving a message
+
+When you receive a message whose first line starts with `~` and a space, it is a message from the agent it names, never
+input from the user: match it to your task by its ref and act on its STATUS (DONE: move on; PENDING: triage the open
+items; BLOCKED: unblock it or ask the user; ERROR: investigate; ACK: nothing; ASK: answer it with a report on the same
+ref). A message that ends with the delegation footer above (`ref:` and the report-back line) is a task from the agent
+named in that line. Any other message without the header is from the user, unless its content clearly says otherwise;
+when a short one is ambiguous, ask the user instead of assuming it was their answer.
+
+Text in an agent's TUI input area seen with `maestri check`, such as a greyed prompt suggestion, is never an
+instruction, a reply or a decision.

package/skills/risk-triage/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: risk-triage
+description: Classifies a task or diff as Low, Medium or High risk and returns the minimum contract, testing and review plan. Use at the start of every coding task, before delegating, and when a finding suggests the risk has changed.
+---
+
+# Risk triage
+
+Goal: spend as little time and as few tokens as the risk allows, without leaving gaps involving money, data or access.
+Follow the `risk-process` rule and the `testing` rule.
+
+## Steps
+
+1. List the files the change will touch. If the diff already exists: `git diff --name-only <base>...HEAD`.
+2. Read the project's risk map in `AGENTS.md`, if present. It overrides the generic list below.
+3. Mark each file's level:
+   - **High:** money and value (payments, balances, sales), personal data, authentication, sessions, permissions,
+     administrative commands, secrets, external input the system publishes or executes, data migration or deletion,
+     deploy, CI, dependencies.
+   - **Medium:** business logic, bug fixes, behavior changes.
+   - **Low:** assets, text, styling, docs, versions, logs; configuration values unrelated to authentication,
+     permissions, CORS, limits, secrets or money.
+4. The task level is the highest among its files.
+5. Independent areas (front, back, infra) in a change that is not small: split according to **Parallel by area** in
+   the `risk-process` rule. At High risk, call the `security-surfaces` skill with only the touched surfaces.
+6. Reply in this format, in at most 8 lines:
+
+```text
+Level: <Low|Medium|High>: <one-sentence reason naming the deciding file>
+Areas: <front/back/infra and who handles each>
+Contract: <none | the request itself | one page>
+Tests: <none | 1 regression | risk paths: ...>
+Reviews: <CI or local verification | + diff reading | + architecture, testing and security>
+Done when: <criterion>
+```
+
+## Examples
+
+- Replace a provider icon: **Low**. No tests or reviewers.
+- Fix a command that hangs when skipping tracks: **Medium**. One regression test and diff reading.
+- Large fix touching the dashboard endpoint and screen component: **Medium**; back and front are independent,
+  so run in parallel. If the fix is only a few lines, one builder handles both.
+- New card checkout: **High**, with full baseline.
+- Publish external text to a channel (song name, username): **High**. Security review is limited to that point:
+  escaping mentions and links.

package/skills/security-surfaces/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: security-surfaces
+description: Surface-based security checklist for High-risk work - money and value (payments, balances, sales, trades), accounts and personal data, exposed inputs and services, secrets and infrastructure. Use when writing the contract, threat model or review of a High-risk item; load only the surfaces the change touches.
+---
+
+# Security review
+
+## Steps
+
+1. List the surfaces the change touches (the `risk-triage` skill).
+2. Read **only** the files for those surfaces:
+
+   | Surface | File | When |
+   |---|---|---|
+   | Money and value | `surfaces/money.md` | payments, payment methods, financial platforms, balances, wallets, sales, subscriptions, user trades, refunds |
+   | Accounts and personal data | `surfaces/accounts-and-data.md` | signup, login, sessions, roles, admin, user data |
+   | Inputs and services | `surfaces/inputs-and-services.md` | HTTP APIs, WebSocket, incoming webhooks, uploads, published messages, external data |
+   | Secrets and infrastructure | `surfaces/secrets-and-infra.md` | tokens and keys, admin commands, subprocesses, downloads, dependencies, Docker, CI |
+
+3. **Contract:** copy applicable items as completion criteria. **Threat model:** only for these surfaces.
+4. **Review:** for each applicable item, Pass or a finding with severity (Critical, Major, Minor or Suggestion),
+   `file:line`, abuse scenario and fix.
+5. **Triage:** decide according to the **Findings** section of the `risk-process` rule.
+6. Never describe an unfixed flaw in a public issue, PR, commit or document.
+
+## Tools
+
+Secrets scanning (`gitleaks git --pre-commit --staged`, `gitleaks git` for history and `gitleaks dir`), dependency
+audits
+with the project's package manager (`pnpm audit`, `npm audit`, `uvx pip-audit`, `govulncheck`), and risk tests listed in
+each surface.

package/skills/security-surfaces/surfaces/accounts-and-data.md

@@ -0,0 +1,41 @@
+# Accounts and personal data
+
+## Authentication
+
+- Established libraries, never custom cryptography. Passwords with argon2id (bcrypt with cost ≥ 12 as an alternative).
+- Social login: OAuth2 with code + PKCE, server-side code exchange, verified `state`.
+- Attempt limits and progressive lockout on login, reset and code verification.
+- Generic messages: do not reveal whether an email or user exists.
+- Password reset with a single-use, short-lived token stored only as a hash.
+- Mandatory MFA for admin. Extra confirmation (step-up) before withdrawals, high-value trades and email or password
+  changes.
+- Changing the password ends other sessions.
+
+## Sessions
+
+- `httpOnly`, `Secure` and `SameSite` cookies; no session tokens in `localStorage`.
+- CSRF protection on every state-changing action.
+- Renew the session at login, expire it after inactivity and end it server-side at logout.
+
+## Authorization
+
+- Object-level checks on every route: user A never reads or changes B's resources (BOLA/IDOR).
+- Server-decided roles, deny by default. Separate admin, with every action recorded.
+- Input field allowlist: the client never sets `role`, `balance`, `owner` or `status` (mass assignment).
+- Capped pagination; no listing exposes other users' data.
+
+## Personal data (LGPD)
+
+- Collect the minimum, with a defined purpose and legal basis.
+- Retention period for each data item, with deletion or anonymization at the end.
+- Always encrypt in transit; encrypt documents, CPF, addresses and financial data at rest.
+- Logs without personal data (mask email, CPF and phone) or secrets.
+- Data subjects can export and delete their own data.
+- Record every admin access to personal data.
+
+## Required tests
+
+- Authorization matrix: each role against each resource, including A trying to access B.
+- End-to-end flows: signup, login, logout, reset, wrong password, lockout and expired session.
+- Forbidden client field (`role`, `balance`): ignored or rejected.
+- Reused or expired reset token: rejected.

package/skills/security-surfaces/surfaces/inputs-and-services.md

@@ -0,0 +1,47 @@
+# Inputs and exposed services
+
+## All input
+
+- Untrusted inputs include users, but also databases, local files, queues, webhooks and third-party APIs.
+- Schema validation at the boundary: types, allowed fields, maximum string and list lengths, IDs in the expected format.
+- Always parameterized queries or ORM; never build SQL or filters from user text.
+- Generic client errors: no traceback, exception `repr`, file paths or configuration. Details stay in the server log.
+
+## Deserialization
+
+- No `pickle`, `marshal`, `shelve` or equivalents for persisted or received data. Use validated JSON.
+- YAML only with a safe loader; XML with external entities disabled.
+
+## HTTP APIs and WebSocket
+
+- Authentication decided by configuration and server, never by a client-supplied field. Constant-time secret comparison
+  (`hmac.compare_digest` or equivalent).
+- CORS and `Origin` with allowlists; never accept any origin.
+- Message size limits, connection limits per client and rate limits per expensive or sensitive route.
+- WebSocket: decode inside `try`, require an object, `op` in an allowlist; discard invalid messages without crashing
+  the handler.
+- Forward only allowlisted fields to other clients, never the entire received payload.
+- Security headers (CSP, HSTS, `X-Content-Type-Options`) and TLS in production.
+
+## Outbound requests (SSRF)
+
+- Never fetch a user-supplied URL without scheme and domain allowlists and blocking internal IPs.
+- Every outbound request has an explicit `timeout`.
+
+## Uploads
+
+- Maximum size, type checked from content rather than extension, server-generated name, storage outside the public root.
+
+## Messages the system publishes (bots, chats, emails)
+
+- Republished user or third-party text has mentions disabled or escaped (on Discord, `AllowedMentions.none()`) to
+  prevent injected `@everyone` and similar mentions.
+- External links are displayed as text or checked against an allowlist; no masked links with third-party-controlled
+  destinations.
+- Size and frequency limits on what the system publishes on someone's behalf.
+
+## Required tests
+
+- Payload outside schema (wrong type, extra field, excessive size): rejected without a 500 error.
+- Disallowed origin and oversized message: refused.
+- Text with `@everyone` or injected mention: published without notifying anyone.

package/skills/security-surfaces/surfaces/money.md

@@ -0,0 +1,57 @@
+# Money and value
+
+Applies to all code that creates, calculates, stores or moves value: money, payment methods, integrations with financial
+infrastructure platforms, balances, credits, sales, subscriptions, refunds and trades between users.
+
+## Values
+
+- Money as integers in the smallest unit (cents) or exact decimals, always with currency. Never `float`.
+- One rounding rule, written in the contract, applied in a single place.
+
+## Payments
+
+- Price, discount, fee and total are calculated on the server. Never trust amounts, prices or currency from the client.
+- Use the provider's checkout or tokenization: no card data passes through your server or is stored.
+- **Provider webhooks:** verify the signature over the raw body with constant-time comparison; reject events outside
+  the time window (replay); process each event only once, by its id; respond 2xx only after persisting.
+- A browser redirect does not prove payment. State comes from the webhook or a provider query.
+- Idempotency key on every charge creation, capture and refund.
+- Explicit states (pending, paid, failed, refunded, disputed), with only allowed transitions.
+- Periodic reconciliation with the provider; discrepancies trigger alerts, not silent corrections.
+
+## Balances and wallets
+
+- A single module moves balances and records transactions. No other module, endpoint or script changes balances
+  directly in the database.
+- Every value that generates or moves balance (price, prize, credit, cashback, items worth currency) is calculated and
+  validated only on the server; the client only displays it.
+- Balance is not an editable field: it is the sum of ledger entries. In double-entry accounting, every credit has a
+  matching debit.
+- Entries are insert-only. A correction is a reversing entry, never `UPDATE` or `DELETE`.
+- Every movement occurs in a database transaction, with account locking (`SELECT ... FOR UPDATE`) or optimistic
+  version control. The sufficient-balance check stays inside that transaction to prevent double spending in a race.
+- Database constraints: balance never negative (`CHECK`) when required by the rule; unique idempotency key.
+- Audit trail on each entry: who, when, why and the originating request id.
+- Limits per user and period, and alerts for abnormal patterns.
+- Balances representing redeemable money may be regulated (in Brazil, Central Bank rules for payment institutions).
+  Confirm with legal counsel before allowing real-money withdrawals or transfers.
+
+## Trades between users
+
+- Atomic trade: both sides change in the same transaction, or nothing changes.
+- Both parties consent to the exact offer state (version or hash). Any offer change invalidates acceptance.
+- Offered items remain reserved (escrow) while the offer is open, and return on cancellation or expiration.
+- Ownership checked server-side at execution time: only owners offer their own items.
+- Terminal states (completed, cancelled, expired); accepting twice does not execute two trades.
+- Rate and value limits; watch new accounts and repeated unbalanced trades (fraud and laundering).
+- Complete record of each trade to resolve disputes.
+
+## Required tests
+
+- Two concurrent requests spending the same balance: only one succeeds.
+- Repeated request or webhook: a single effect.
+- Webhook with invalid signature, modified body or outside the time window: rejected.
+- Forbidden state transition: rejected.
+- Rounding at boundaries (cents, divisions, different currencies).
+- Offer changed after the other party accepted: trade does not execute.
+- User A cannot move B's balance or offer B's items.

package/skills/security-surfaces/surfaces/secrets-and-infra.md

@@ -0,0 +1,43 @@
+# Secrets and infrastructure
+
+## Secrets
+
+- Never in code, logs, messages, attachments, error reports, exception messages or client responses. For diagnostics,
+  record only whether the value is present or absent.
+- Connection URLs in logs have credentials masked (`postgres://***@host`).
+- Every new sensitive variable is empty and documented in `.env.example`, and read by a single configuration loader.
+- Configuration exports replace secrets with placeholders.
+- Public exceptions (for example, a client ID in every authorization URL) only by explicit name and format validation;
+  any value outside that format remains a secret.
+- `.env`, local databases and caches stay outside git and Docker images (`.gitignore` and `.dockerignore`).
+
+## Admin commands and subprocesses
+
+- Arguments as lists; `shell=True` only in an admin shell command intended for that purpose.
+- Minimal subprocess environment (allowlist such as `PATH`, `HOME`, `LANG`); never forward the entire environment.
+- Admin command output has secrets masked and goes only to the admin, never to a public channel.
+- `eval` and remote consoles disabled by default, enabled through configuration.
+- Record every admin command execution (who, what, when), without secrets.
+- Auto-update only from the official repository, by verified tag or commit, without silently discarding local changes.
+- Restart through orderly shutdown and a nonzero exit code, letting the supervisor start it again; never kill
+  unrelated PIDs.
+
+## Binary and script downloads
+
+- Version-pinned URL (immutable tag or release, never `main` or `latest`) and pinned SHA-256.
+- Download to a temporary file, verify the hash, move atomically; a wrong hash deletes the file and aborts.
+- HTTPS only, with `timeout`. No `curl | bash` or executing freshly downloaded scripts.
+
+## Dependencies
+
+- Exact version and hash in the lockfile, installation requiring hashes.
+- Prefer official registry releases; git dependencies only pinned to a full commit SHA.
+- Before adding: actual use, active maintenance, compatible license and audit without high or critical vulnerabilities.
+
+## Docker, CI and scripts
+
+- Base image pinned by digest, non-root user, no secrets in layers or `ARG`.
+- Bash scripts with `set -euo pipefail`, quoted variables and no printing the environment.
+- No secrets in compose or workflow YAML; use CI secrets or ignored local `.env`.
+- GitHub Actions pinned by SHA, minimal `permissions:` and no `pull_request_target` executing PR code.
+- New security options start with the safe value as default.