# Slash Commands

A reference for `$FJX_OWNER` (you, the human). These are the `/<command>` directives you can type in an issue comment to drive [PM](../agents/pm.md). They are the deterministic, vocabulary-bound surface for talking to PM; prose works too (see [prose vs slash commands](#prose-vs-commands) below).

Slash commands are parsed and executed by the `fjx` CLI itself (in `fjx pm next`), not by the PM agent. The agent's job is the looser, judgment-driven work — reading prose, curating briefs, deciding what gets promoted to the wiki. Working agents (dev, qa, build) never parse slash commands themselves; that's reserved for the fjx tooling, with the trust map as the choke point.

## How it works

- Type the command anywhere in the issue body or comment. PR comments are out of scope; only issue comments are swept.
- Commands are honored only from authors listed in the trust map (`pm.trustMap` in `.fjx-cache.json`). Unauthorized commands are logged in the PM ledger as `rejected — @<author> not authorized` and ignored.
- One command per comment is typical, but a comment may contain multiple. Each is recorded as a separate Activity entry in the PM ledger.
- Commands are parsed and executed by `fjx pm next`; effects are not instant, they land on the next cycle.
- Unknown `/foo` tokens are recorded as `unrecognized` and surfaced for review.

## Command vocabulary

<style>
  .retype-markdown .stacked-defs dt { float: none; width: auto; clear: none; padding: 0; margin: 1rem 0 0.5rem 0; border-top: 0; }
  .retype-markdown .stacked-defs dd { width: auto; margin-left: 0; padding: 0; margin: 0 0 2rem 0; border-top: 0; }
</style>

::: stacked-defs
`/needs-spec`
: The issue is non-trivial and you want dev to propose a spec before writing code.

`/spec-approved`
: Dev posted a spec proposal and you accept it.

`/spec-rejected`
: Dev posted a spec proposal and it needs revision.

`/block <reason>`
: Park an issue; agents should stop picking it up.

`/unblock`
: Resume a parked issue.

`/brief <role>`
: Force PM to regenerate a brief (e.g., after you edited the issue body or added context).

`/note <text>`
: Capture a freeform observation against the issue without changing state.

`/depends <id>...`
: Declare that this issue depends on the listed open issue ids (`/depends none` clears). While any listed dep is still open, `fjx pm next` suppresses dispatch (brief refreshes, label changes, assignee changes) for this issue so PM doesn't hand work to something that isn't ready. Resumes automatically once the blocking issues close.

`/assign <user>`
: Hand the issue directly to `<user>` (a Forgejo login; a leading `@` is optional), overriding PM's routing. Sets the assignee on the next `fjx pm next` cycle — use it to pull an issue back to yourself or push it to a specific role/person. Requires a `<user>` argument; an empty `/assign` is rejected and recorded in the ledger.
:::

This list is the canonical vocabulary. If a `/foo` token isn't listed, `fjx pm next` won't act on it — though the PM agent may still pick up the intent from the surrounding prose (see below).

## Prose vs Commands

You don't have to use a slash command to get PM to do something. The PM agent is prompted to read owner prose comments on every tick and act on obvious intent ("fix X and archive", "@agent-dev pick this back up", "this needs a fresh brief") without waiting for a `/command`. You should never have to repeat yourself, and you should never have to escalate to a slash command to get an obvious handoff executed.

Use a slash command when you want **deterministic, auditable** behavior — the list above is contractual, parsed by `fjx pm next`, and every invocation lands in the PM ledger's Activity list as a numbered entry. Use prose when the request doesn't fit the vocabulary, or when you want to combine several intents in one comment. Working agents (dev, qa, build) also read natural-language directives from comments per the [PR conventions](./pr.md).

Two things that don't work either way:

- **`/<command>` in PR comments.** Only issue comments are swept. Use the issue, not the PR.
- **Commands from non-trusted authors.** Add the user to `pm.trustMap` first, or run the action manually.

## Manual mode

PM is off the critical path. Anything a command does, you can also do by hand in the Forgejo UI: apply/remove labels, edit the brief comment (use the `` marker so agents find it), reassign issues. See [PM › Manual Mode](../agents/pm.md#manual-mode).

## See also

- [PM agent](../agents/pm.md) — the design doc for PM, including trust map, brief lifecycle, ledger structure.
- [Issue conventions](./issue.md) — labels, assignment, ledger markers.
- [CLI reference › `pm`](../cli-reference.md#pm) — the `fjx pm ...` subcommands (these are operator/agent commands, not the slash commands above).