prompt-vars

Files (1)

• SKILL.md

SKILL.md (first lines)

# Prompt Vars

This environment provides:
- built-in derived prompt vars for the active plan and design files
- project vars from `.pi/agent-mode-vars.json`
- global fallback vars from `~/.pi/agent/agent-mode-vars.json`
- a project-local write-location config in `.pi/agent-mode-vars-config.json`
- a `vars` tool and `/vars` command for runtime inspection, bootstrap, and mutation

If you need the full wiring and implementation details, read:
- `extensions/z-prompt-vars/README.md`

## What they are for

Use prompt vars to make prompts adapt to the workspace and current runtime state without hardcoding absolute paths.

Typical uses:
- agent mode definitions
- other system-prompt-like text artifacts
- runtime inspection when you need the live value of a var
- workspace-local or user-global configuration that should persist across sessions

## Built-in derived prompt vars

These are computed at runtime and are read-only:
- `${plan.path}`
- `${plan.exists}`
- `${plan.active}`
- `${design.path}`
- `${design.exists}`
- `${design.active}`
- `${plan}`
- `${design}`

Meaning:
- `*.path` is the canonical active file path
- `*.exists` is `true` or `false`
- `*.active` is `true` when the corresponding mode is currently active (`planner` for plan, `designer` for design)
- `${plan}` and `${design}` expand to short status sentences

The source path vars for those built-ins are:
- `paths.plan`
- `paths.design`

If `paths.plan` or `paths.design` is unset, the extension falls back to:
- `.pi/plans/active.md`
- `.pi/designs/active.md`

## Read and write behavior

Read precedence:
1. project `.pi/<vars-file-name>`
2. global `~/.pi/agent/<vars-file-name>`

Project vars override global vars.

Writes go to the location selected by:
- `.pi/agent-mode-vars-config.json`

The config contains:

```json
{
  "pi-location": "project",
  "vars-file-name": "agent-mode-vars.json"
}
```

`pi-location` may be:
- `project`
- `global`

`vars-file-name` is optional and overrides the default vars filename while keeping the project/global directories fixed.
If a path is mistakenly provided, the extension keeps only the final path segment.

## Workspace vars

Examples of useful stored keys:
- `project.name`
- `feature.flag`
- `release.owner`
- `paths.design`
- `subagents.dispatch.defaultContext`
- `automode.enabled`
- `gate.auto.*` for pi-gate local auto-approval configuration

Recommended default:
- `subagents.dispatch.defaultContext = "fresh"`
- `automode.enabled = false`
- `gate.auto.enabled = false`
- `gate.auto.startOnSession = false`

Use `fork` only as an exception when a subagent truly needs prior session context.

## Runtime interfaces

### The `vars` tool

Agents should use the `vars` tool when they need a live value or need to update vars programmatically.

Examples:
- `vars({ action: "bootstrap" })`
- `vars({ action: "list" })`
- `vars({ action: "get", key: "plan.path" })`
- `vars({ action: "get", key: "project.name" })`
- `vars({ action: "set", key: "project.name", value: "Prompt Vars" })`
- `vars({ action: "set", key: "flags", value: { beta: true, rollout: 25 } })`
- `vars({ action: "set", key: "subagents.dispatch.defaultContext", value: "fresh" })`
- `vars({ action: "set", key: "subagents.dispatch.defaultContext", value: "fork" })`
- `vars({ action: "unset", key: "project.name" })`
- `vars({ action: "location" })`
- `vars({ action: "location", value: "global" })`

### The `/vars` command

Users can do the same interactively.

Examples:
- `/vars bootstrap`

From judepayne/picode, MIT.

More from judepayne/picode