feat(AI-81): author stage-chapters SKILL.md scaffold#25
Conversation
Adds skills/stage-chapters/SKILL.md at the repo root with vercel-labs/skills frontmatter, prerequisites (stage-cli + git repo checks), base ref detection (origin/HEAD → main → master), merge-base diff retrieval, JSON-shape documentation matching ChaptersFileSchema, and the final stage-cli show step. Step 3 (cluster + narrate) is left as a TODO pointing at Issue 11.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces the stage-chapters skill, which automates the generation and visualization of Stage chapters for a local git branch. The review identified several technical inaccuracies in the git commands and shell scripts provided in the documentation: the command for detecting the base reference needs to be updated to return a symbolic name instead of a SHA, the diff command requires adjustment to correctly include uncommitted working-tree changes, and the timestamp generation for temporary files needs to be made portable for macOS environments.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bc2170db14
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
- Use the published npm package name `stagereview` (binary is `stage-cli`) in the install instructions - Use `git rev-parse --abbrev-ref origin/HEAD` for base detection so the output is `origin/main` (a strippable ref name), not a commit SHA - Drop the trailing `..` from `git diff "$MERGE_BASE"` so the output actually includes uncommitted working-tree changes for tracked files - Replace `date +%s%N` with `mktemp` template so unique filename generation works on macOS BSD `date` (which has no `%N`)
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a14ab7b59b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…clones Previously the skill stripped `origin/` from `origin/main`, leaving `<base>` set to `main`. In single-branch clones (and after deleting a local `main`) that local ref does not exist, so the subsequent `git merge-base <base> HEAD` and `git rev-parse <base>` calls fail. Use the full remote-tracking ref (`origin/main`) as `<base>` directly — git accepts it everywhere a commit-ish is expected.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6653b18178
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 6653b18. Configure here.
…plate - Step 2 now uses `git diff "$MERGE_BASE..HEAD"` (committed range only) so chapter `hunkRefs`/`lineRefs` reference the exact range the SPA renders for `committed` scope (`baseSha..headSha` per `packages/cli/src/routes/diff.ts`). Mixing in working-tree changes would produce hunks the SPA cannot show; instruct users to commit uncommitted edits first. - JSON example now sets `baseSha = mergeBaseSha = $MERGE_BASE` so the SPA's `baseSha..headSha` query matches the chapter-generation range even when the base branch has advanced past the merge-base. - mktemp template is `stage-chapters.XXXXXX` (no `.json` suffix). BSD `mktemp` returns the template verbatim when characters follow the X's, breaking uniqueness on macOS. `stage-cli show` reads JSON regardless of extension.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 01f1cc9106
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…acks When `origin/HEAD` is unset (some clones, or after the user deletes the local default branch) and there is no local `main`/`master`, the skill previously aborted even though `origin/main`/`origin/master` were valid review bases. Append them as the last two fallbacks before giving up.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 11b7833702
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Without an explicit guard, `git merge-base <base> HEAD` failing (unrelated histories or shallow clones) leaves `MERGE_BASE` empty, and the subsequent `git diff "..HEAD"` becomes `HEAD..HEAD` — an empty diff that would silently produce zero chapters. Tell the agent to abort with a clear error before continuing.
dastratakos
deleted the
dean/ai-81-issue-14-author-skillmd-scaffold-frontmatter-prerequisites
branch
1 participant
Summary
Authors the structural skeleton of
skills/stage-chapters/SKILL.mdso the/stage-chaptersskill works end-to-end except for chapter generation (deferred to Issue 11). Linear: AI-81.Changes
skills/stage-chapters/SKILL.mdat the repo root withvercel-labs/skillsfrontmatter (name,description,user-invocable: true).stage-clior non-git directory), Step 1 base detection (origin/HEAD→main→master), Step 2 merge-base diff retrieval with the three SHAs, Step 3 TODO placeholder for Issue 11, Step 4 JSON-shape docs matchingChaptersFileSchemainpackages/cli/src/schema.ts, Step 5stage-cli show "$TMPFILE".Testing
ChaptersFileSchemato confirm parity (scope variants, chapter / hunkRef / keyChange / lineRef constraints).