Skip to content

Improve README: explain chapters concept, add prerequisites & troubleshooting #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ringku1 wants to merge 1 commit into
base: main
Choose a base branch
from
+31 −0
Open

Improve README: explain chapters concept, add prerequisites & troubleshooting #71

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,17 @@
<a href="https://github.com/ReviewStage/stage-cli/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/stagereview.svg" alt="license"></a>
</p>

## What's a chapter?

Instead of reviewing a pull request as one long, undifferentiated diff, Stage groups related changes into "chapters" — for example, one chapter for a new API integration, another for a schema migration, another for test cleanup. Each chapter comes with a short summary of what changed and what's actually risky, so you know where to focus before reading line by line.

## Prerequisites

- Node.js 18 or later
- A local git repository with changes to review
- An AI coding agent that supports the `skills` convention (see [Which agents work with this?](#which-agents-work-with-this))
- Optional: the [GitHub CLI](https://cli.github.com/) (`gh`), only needed for `--pr` to review a pull request by number or URL

## Install

```bash
Expand Down Expand Up @@ -100,6 +111,26 @@ dist/**

Ignored files still appear in the "Other changes" chapter so nothing is silently hidden. Comments (`#`), blank lines, and negation patterns (`!`) are supported — last matching pattern wins.

## Troubleshooting

**`/stage-chapters` isn't recognized in my agent.**
Re-run `npx skills add ReviewStage/stage-cli` to confirm it installed cleanly, and restart your agent — most agents only pick up newly registered skills after a restart.

**Stage says there's nothing to review.**
By default it looks for staged, unstaged, and untracked changes. If everything's already committed, use `--ref staged` or diff against a specific commit with `--compare`.

@cubic-dev-ai cubic-dev-ai Bot Jul 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: Troubleshooting gives incorrect recovery advice: --ref staged will produce an empty diff when everything is already committed, and mischaracterizes the default diff scope as always scanning the working tree rather than auto-detecting between working-tree and committed modes.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 120:

<comment>Troubleshooting gives incorrect recovery advice: `--ref staged` will produce an empty diff when everything is already committed, and mischaracterizes the default diff scope as always scanning the working tree rather than auto-detecting between working-tree and committed modes.</comment>

<file context>
@@ -100,6 +111,26 @@ dist/**
+Re-run `npx skills add ReviewStage/stage-cli` to confirm it installed cleanly, and restart your agent — most agents only pick up newly registered skills after a restart.
+
+**Stage says there's nothing to review.**
+By default it looks for staged, unstaged, and untracked changes. If everything's already committed, use `--ref staged` or diff against a specific commit with `--compare`.
+
+**It picked the wrong base branch.**
</file context>
Suggested change
By default it looks for staged, unstaged, and untracked changes. If everything's already committed, use `--ref staged` or diff against a specific commit with `--compare`.
+By default it auto-detects whether to review uncommitted changes (staged, unstaged, and untracked) or committed changes against the base branch. If the wrong scope is detected, use `--ref work` to force a working-tree review, or diff against specific commits with `--compare`.


**It picked the wrong base branch.**
Auto-detection looks for `main` or `master`. If your default branch is named differently, pass it explicitly: `--base your-branch-name`.

**`--pr` isn't working.**
This requires the [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`). Confirm `gh` works on its own first — Stage relies on it to fetch PR data.

## Which agents work with this?

Stage runs on the `skills` convention for AI coding agents, so support depends on whether your agent implements that convention. If `npx skills add` doesn't complete, or `/stage-chapters` doesn't show up as a command afterward, check your agent's own docs for skills or plugin support.

*(Note to the Stage team: this is the one thing I couldn't verify from outside the project — worth explicitly listing which agents you've tested against, since "works with any AI agent" is the first thing a new user will want confirmed.)*

@cubic-dev-ai cubic-dev-ai Bot Jul 1, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Public README contains an internal editorial note addressed to the maintainers rather than end users.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 132:

<comment>Public README contains an internal editorial note addressed to the maintainers rather than end users.</comment>

<file context>
@@ -100,6 +111,26 @@ dist/**
+
+Stage runs on the `skills` convention for AI coding agents, so support depends on whether your agent implements that convention. If `npx skills add` doesn't complete, or `/stage-chapters` doesn't show up as a command afterward, check your agent's own docs for skills or plugin support.
+
+*(Note to the Stage team: this is the one thing I couldn't verify from outside the project — worth explicitly listing which agents you've tested against, since "works with any AI agent" is the first thing a new user will want confirmed.)*
+
 <img width="1840" height="1196" alt="Stage CLI" src="https://raw.githubusercontent.com/ReviewStage/stage-cli/main/assets/screenshot.png" />
</file context>
Suggested change
*(Note to the Stage team: this is the one thing I couldn't verify from outside the project — worth explicitly listing which agents you've tested against, since "works with any AI agent" is the first thing a new user will want confirmed.)*
+(For a list of confirmed compatible agents, see the project documentation or open an issue if your agent isn't listed.)


<img width="1840" height="1196" alt="Stage CLI" src="https://raw.githubusercontent.com/ReviewStage/stage-cli/main/assets/screenshot.png" />

## License
Expand Down