Sage Help

---
name: sage-help
description: "Help with sage: how to set it up, switch sage mode and autopilot, read the board, answer the chief's questions, pick a skill or a principle, fix a run that went wrong, and find where sage keeps its files. The user types /sage:sage-help (or /sage-help) with a question. Load it only when the user types it; do not load it on your own. Claude Code only."
license: MIT
allowed-tools: Read, Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/README.md), Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/docs/guide/using-sage.md), Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/docs/guide/board.md), Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/docs/guide/learn-sage.md), Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/docs/guide/how-it-works.md), Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/docs/guide/principles.md), Bash(curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/docs/guide/faq.md)
---

# sage help

Answer the user's question about sage. Give them at most one prompt that they can send, and link the file that the answer comes from. Then stop.

**A help question starts no work.** Do not start sage mode, an agent, a task or a command that changes anything. The user asked how, and each sage run spends real tokens, so the user sends the prompt.

**A request for work is not a help question.** An example is "/sage:sage-help fix the failing test in foo". Do not do the work, and do not start an agent. Say in one line that sage mode does work, and give the prompt that starts it: the README's [Quick start](https://github.com/erickb336/sage-stack/blob/main/README.md#quick-start) shows its form: the on phrase as a message of its own, then the request.

The model for this skill is pstack's `poteto-help` skill, by Lauren Tan (poteto): [its source](https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md).

## Read the source first

This skill is a map. Each section holds the facts that its answer must carry: give them, also when you do not read a source. The sources hold the details, and they change, so this map can be out of date. Do these steps for every question, also when this map seems to hold the answer:

1. Find the section of this map that the question goes to.
2. Do the read that the section's **Read** line names. Make it your first tool call, before you write any of the answer. A section with no **Read** line has no read: answer from its text alone.
3. Answer from what you read and from the section's facts. When the source disagrees with this map, trust the source.

**Never give the user a state-tool command.** This rule wins over the source. Do not give `pages`, `init`, `task`, `gate`, `logbook`, `board` or any other command of the state tool, and no `node …sage.mjs …` command, also when the README or another source names one. Only the chief runs the state tool. Where the source names such a command, write "ask the chief" and say what the chief does. A phrase that the user sends, such as "show board", is not a command: give it as the section says.

Give only the phrases that this map or the source writes, letter for letter: do not make up a form.

- **A sage doc** (the README, or a page under `docs/guide/`) is not in the installed plugin. When the session's folder is the sage repository, Read the file there. Otherwise run this one command alone for the file, exactly as written, with the file's path from the **Read** line: no pipe, no `grep`, no redirect and no other argument. Run it once for each file. Find the section in its output yourself. When Claude Code saves a long output to a file, Read that file, with an offset and a limit if it is long; do not run `curl` again, and do not pipe it.

  ```
  curl -fsS https://raw.githubusercontent.com/erickb336/sage-stack/main/<path>
  ```

  The paths: `README.md`, `docs/guide/using-sage.md`, `docs/guide/board.md`, `docs/guide/learn-sage.md`, `docs/guide/how-it-works.md`, `docs/guide/principles.md` and `docs/guide/faq.md`.

- **A plugin file** is in the installed plugin. Claude Code prints this skill's base directory above these instructions. Read the file at the path that the **Read** line gives, from that directory: for example `<base directory>/../../agents/chief-of-staff.md`.

If a read fails, say so in one line, and give only the link.

Give the user the public link, because they may not be able to open the installed plugin: `https://github.com/erickb336/sage-stack/blob/main/` and the path. Link only the pages and the anchors that this map links. A FAQ question has no anchor of its own: link the FAQ page.

## Find out what the user needs

Find the need in the question and in the conversation. A clear question goes to its section. When the question is empty or unclear, ask one choice question (with AskUserQuestion when you have it) with these four groups:

1. **Start and switch:** Get set up · Switch sage mode or autopilot · What sage does alone, and what it asks
2. **Daily use:** Show the board · Answer the chief's questions · Pick a skill or a principle
3. **When something goes wrong:** Fix a run that went wrong
4. **Where things are:** Where sage keeps things

When the picked group has two or more sections, ask a second choice question with its sections as the options. A group with one section goes to it. Answer only the section that the user picks. Without AskUserQuestion, write the four groups as a numbered list, and ask the user to reply with a number.

## Get set up

**Read:** the README, section "Quick start", and `docs/guide/faq.md`.

Install the plugin, then start a new session: a session that is already open does not get the new skills and hooks. The [Quick start](https://github.com/erickb336/sage-stack/blob/main/README.md#quick-start) has the install commands, which the user runs in a terminal. [To update sage](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#to-update-sage) gives the update command. The [FAQ](https://github.com/erickb336/sage-stack/blob/main/docs/guide/faq.md) says which projects fit and what sage costs.

## Switch sage mode or autopilot

**Read:** `docs/guide/using-sage.md`, section "Every phrase".

sage mode makes the session the user's chief of staff. Autopilot lets verified pull requests merge without the user. Autopilot is off until the user turns it on. A switch needs the exact phrase as the user's whole message, in any letter case, with at most one full stop: "sage mode" or "sage mode on" turns the mode on, "sage mode off" turns it off, and "autopilot on" and "autopilot off" switch autopilot, which needs sage mode on. A message with more words switches nothing, so the request goes in the next message. The message "sage help" lists every phrase. The rules are in [Every phrase](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#every-phrase): link that table, and do not copy it.

## Show the board

**Read:** the README, section "The board", and `docs/guide/board.md`.

The board is a short view of every project's logbook: what needs the user, the agents running now, and each active task. A message that starts with "show board" prints it for this project, "show board for all" for every project, and "show board for <project>" for one project. [Ask for the board](https://github.com/erickb336/sage-stack/blob/main/docs/guide/board.md#ask-for-the-board) gives the other forms and what each part shows. “show board T197” and “sage board T197” show that task in this project. “show status” and “sage status” show short status lines. The phrases work at the start of the user's own message, outside quoted text. The board command reads recorded facts; it does not change a task.

## Answer the chief's questions

**Read:** `docs/guide/using-sage.md`, section "When the chief asks you".

The chief asks at most once per task, in one batch of product questions. Each question has options, a recommendation and a default. The user picks an option on the choice card, or answers in their own words, and the chief records the answer as theirs. An open question also shows under "Needs you" on the board. [When the chief asks you](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#when-the-chief-asks-you) gives the exceptions that can ask again.

## What sage does alone, and what it asks

**Read:** `docs/guide/faq.md`, the question "Is it safe to let it work alone?".

The chief decides the engineering choices, runs the team, and tells the user the results with evidence. The user decides the product questions. With autopilot on, a verified pull request merges after its clean cycles.

Every answer from this section carries these two facts, in these words:

- "The chief's instructions say that a deploy, deleting data, and closing a pull request that is not sage's always need your yes, also on autopilot. That rule is not yet held in code."
- "The hook refuses every force-push, also on autopilot."

This section answers a question; it has no prompt to send. Do not give one. Link these two sources and no other:

- [The chief's instructions](https://github.com/erickb336/sage-stack/blob/main/plugins/sage/agents/chief-of-staff.md): what the chief always asks first, also on autopilot.
- [FAQ](https://github.com/erickb336/sage-stack/blob/main/docs/guide/faq.md), the question "Is it safe to let it work alone?": what the hook holds, and that the rule above is not yet in code.

## Pick a skill or a principle

**Read:** `docs/guide/principles.md`, and the `SKILL.md` of the skill that you name, at `<base directory>/../<skill>/SKILL.md`.

sage mode is the default answer for real work: the chief runs the agents and the principles when the steps need them. Name a skill only when the user wants it alone. A plugin skill has the form `/sage:<skill>`.

| The user wants to | Skill |
| --- | --- |
| Get work done by a team of agents | sage mode ([Quick start](https://github.com/erickb336/sage-stack/blob/main/README.md#quick-start)) |
| Follow, steer or start sessions from a phone | [`/sage:remote-control`](https://github.com/erickb336/sage-stack/blob/main/plugins/sage/skills/remote-control/SKILL.md) |
| Write text that a person reads on the first pass | [`writing-standard`](https://github.com/erickb336/sage-stack/blob/main/plugins/sage/skills/writing-standard/SKILL.md) |
| Write or review a project README | [`readme-guide`](https://github.com/erickb336/sage-stack/blob/main/plugins/sage/skills/readme-guide/SKILL.md) |
| Use sage's approved words | [`dictionary`](https://github.com/erickb336/sage-stack/blob/main/plugins/sage/skills/dictionary/SKILL.md) |
| Apply one working rule, such as "prove it works" | a `principle-<name>` skill ([Principles](https://github.com/erickb336/sage-stack/blob/main/docs/guide/principles.md)) |
| Find their way around sage | `/sage:sage-help` |

For a skill that is not in this table, read its description in its `SKILL.md` and route by it. Two skills are for sage itself, not for the user: `sage` (the chief's state tool) and `report` (the end of each agent's run).

Each role agent of sage mode starts with the principles of its role, so the user seldom loads one. To ask for one, the user names it in the request, for example "apply prove it works".

## Fix a run that went wrong

**Read:** `docs/guide/using-sage.md`, section "Troubleshooting", and `docs/guide/how-it-works.md`, section "A task's life".

| The user sees | What to do |
| --- | --- |
| A mode did not switch | The phrase must be the user's whole message, with no other words. A message sent while Claude works can switch only autopilot off; send any other phrase again when Claude is idle. The message "sage help" lists every phrase. See [Every phrase](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#every-phrase). |
| Merges must stop now | Send the autopilot off phrase alone ([Every phrase](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#every-phrase)). Pull requests then wait for the user. |
| The user wants a normal session again | Send the off phrase of sage mode ([Every phrase](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#every-phrase)). It holds for the rest of the session, also in a session that started as the chief. |
| A task waits and nothing moves | Show the board: an open question under "Needs you" holds the task until the user answers. A task in the held state waits for the user: for an answer to a product question, or, after 3 repair rounds that did not make it clean, for the user to choose what comes next. The chief asks one question with options, a recommendation and a default; the user picks one or answers in their own words. A task in the replan state waits for a new plan. A task of a milestone waits for the user's approval of the milestone's breakdown (a question under "Needs you" on its pilot task), then for its pilot to merge; `status` shows what each task waits for. Link [the chief's instructions](https://github.com/erickb336/sage-stack/blob/main/plugins/sage/agents/chief-of-staff.md), step 4 (an escalation when the tool says held or replan). |
| A pull request does not merge | A merge needs its clean cycles on the exact head commit. A new commit starts again from cycle 1, except a clean merge of main that keeps the pull request's own change the same and passes CI ([A task's life](https://github.com/erickb336/sage-stack/blob/main/docs/guide/how-it-works.md#a-tasks-life)). Tell the chief what to do with it in your own words. |
| An agent must stop | There is no fixed phrase: the user tells the chief in their own words. Give this example as the prompt, letter for letter: "stop the run on T3" (the user replaces T3 with the task id). The agent's slot frees as soon as the agent ends, fails or is stopped ([Rules held in code](https://github.com/erickb336/sage-stack/blob/main/docs/design/rules-in-code.md)). |
| A new version of sage has no effect | Start a new session ([To update sage](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#to-update-sage)). |

## Where sage keeps things

This section has no read: the README and the chief's instructions name state-tool commands here. Answer from this text alone. Give these paths, and no state-tool command (see the rule above).

- **The logbook** of each project, in `~/.claude/sage/<project>-<hash>/`: its tasks, runs, findings, verdicts, the user's answers and the decision trail.
- **The hook's state**, in `~/.claude/sage/.hooks/`: the modes, autopilot and the agent slots.
- **The pages folder** of each task, in `~/sage-worktrees/<project>-<hash>/pages/<task>/`, outside the logbook: research pages, designs and findings pages.
- **The board's files**, when the user runs the board server: its config in `~/.config/sage-board/`; after a setup by hand, its installed copy and pages folder in `~/.local/share/sage-board/`, and its login file `~/Library/LaunchAgents/dev.sage.board.plist`.

To see the exact folders, the user first sends the on phrase of sage mode as a message of its own, as in the README's Quick start, then this prompt (replace T3 with the task id):

```
Make the pages folder of T3, and print its path and the path of this project's logbook.
```

Link [Where sage keeps things](https://github.com/erickb336/sage-stack/blob/main/docs/guide/using-sage.md#where-sage-keeps-things).

## Close calls

- **The board or "status":** the board reads every project's logbook; "status" gives the lines of one project.
- **The off phrase of sage mode, or autopilot off:** autopilot off stops only the merges; the off phrase of sage mode ends the mode, and autopilot goes off with it.
- **Not in sage:** pstack's own modes, poteto mode, orchestrate and autopilot (sage mode replaces them; see [Credit](https://github.com/erickb336/sage-stack/blob/main/CONTRIBUTING.md#credit)). sage's own autopilot is a different thing: the switch above. sage mode does not run in Codex yet: Codex gets the principles, the writing skills and the manual logbook commands ([sage in Codex](https://github.com/erickb336/sage-stack/blob/main/docs/guide/codex.md)).

## Reply

Lead with the answer, in two to five sentences. Give at most one prompt that the user can send, in a code block, and none when the section says so. End with the public link of the file that the answer comes from. Write at 80% of Simplified Technical English, with sage's approved words. Keep it short unless the user asks for the whole map.