chore(persona): terminal-renderer local skill files#168
Merged
Conversation
User asked for the persona's skills to be LOCAL files (not phantom
remote package references like the autonomous-actor pattern). This
commit:
1. Creates six substantive markdown skill files under
.agentworkforce/workforce/personas/__assets/terminal-renderer/ —
each capturing a discrete domain of the persona's expertise:
- xterm-internals.md (105 lines) — parser pipeline, renderer
trade-offs, addon discipline, focus mode, viewport vs scrollback,
font measurement timing
- pty-broker-pipeline.md (172 lines) — chunk path from broker IPC
to term.write, rAF coalescing, snapshot-vs-replay race, SIGWINCH
bounce, trim cap accounting, predictive echo discipline
- ansi-vt-sequences.md (152 lines) — sequence taxonomy, cursor
movement, DECSET modes (?1004 / ?1049 / ?2026), TUI redraw
patterns and their failure modes
- bug-class-triage.md (104 lines) — symptom-to-bug-class lookup
table built from the PR #158 catalogue; use BEFORE reading source
- lifecycle-decoupling.md (249 lines) — runtime registry pattern,
token-based mount ownership, parked host, clearOnDataIf identity
check, dispose ordering
- fix-discipline.md (152 lines) — one-write invariant, read before
guessing, minimal-diff scope, instrument-don't-guess after two
failed fixes, AGENTS.md test requirement
2. Updates terminal-renderer.json skills array to reference each file
via __assets/terminal-renderer/<id>.md local path. Description for
each skill summarizes the file content for quick orientation.
Matches the existing .agentworkforce local asset pattern (slack-comms
uses __assets/slack-comms/slack-comms.md for its claudeMd).
934 lines of structured operating knowledge extracted from the PR #158
fix cycle so future investigations don't have to re-derive it.
|
Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI. |
|
Warning Review limit reached
More reviews will be available in 22 minutes and 48 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
📝 WalkthroughWalkthroughThis PR adds a comprehensive documentation suite for terminal rendering, PTY pipeline mechanics, and systematic bug diagnosis. Six new markdown guides establish shared vocabulary for xterm internals, PTY streaming invariants, escape sequence semantics, React lifecycle safety, and fix methodology. The persona configuration is updated to register these skills. ChangesTerminal Renderer Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![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 comprehensive documentation and guidelines for the terminal renderer persona, covering xterm.js internals, PTY streaming pipelines, ANSI/VT escape sequences, bug triage, lifecycle decoupling, and fix discipline. The review feedback provides valuable corrections to technical details in the documentation, such as removing spaces from character set designation escape sequences, correcting the terminology of a 'one-pixel bounce' to a 'one-row bounce', and clarifying the distinction between absolute and relative cursor movement sequences.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
@.agentworkforce/workforce/personas/__assets/terminal-renderer/ansi-vt-sequences.md:
- Around line 78-83: The fenced code block containing the ANSI escape sequences
(\e[?2026h, \e[H, <card content>, \e[?2026l) is untyped and triggers MD040; add
an explicit language tag to the opening fence (for example ```ansi or ```text or
```console) so the block is typed for the linter while preserving the existing
content and escape sequences.
- Around line 151-152: Update the two companion link filenames referenced
(`pty-broker-streaming-pipeline.md` and `renderer-bug-class-triage.md`) to match
the actual assets in this PR by replacing them with `pty-broker-pipeline.md` and
`bug-class-triage.md` respectively so the links resolve correctly; locate the
references in ansi-vt-sequences.md and change those exact filename tokens.
In
@.agentworkforce/workforce/personas/__assets/terminal-renderer/bug-class-triage.md:
- Around line 100-104: Update the "Companion reading" links in
bug-class-triage.md to reference the new local filenames under
__assets/terminal-renderer instead of the old names; specifically replace
`pty-broker-streaming-pipeline.md`, `ansi-vt-escape-sequences.md`, and
`fix-discipline-and-instrumentation.md` with the renamed skill asset filenames
that were added in this PR so the links resolve locally within
__assets/terminal-renderer.
In
@.agentworkforce/workforce/personas/__assets/terminal-renderer/fix-discipline.md:
- Around line 83-89: The fenced code block containing the snippet with
localStorage.setItem('PEAR_DIAG_PTY', '1') ...
localStorage.removeItem('PEAR_DIAG_PTY') needs a language tag to satisfy MD040;
update the opening fence from ``` to ```ts (or ```javascript) so the block is
declared as TypeScript/JavaScript, ensuring the markdown linter passes.
- Around line 149-152: Update the companion-reading bullet list in
fix-discipline.md to reference the new filenames: replace
`renderer-bug-class-triage.md` with `bug-class-triage.md`,
`pty-broker-streaming-pipeline.md` with `pty-broker-pipeline.md`, and
`xterm-internals-and-renderers.md` with `xterm-internals.md` so the Companion
reading links (the bullets under "Companion reading") match the new local skill
files.
In
@.agentworkforce/workforce/personas/__assets/terminal-renderer/lifecycle-decoupling.md:
- Around line 245-249: Update the stale companion-reading filenames in
lifecycle-decoupling.md: replace `xterm-internals-and-renderers.md` with
`xterm-internals.md`, `pty-broker-streaming-pipeline.md` with
`pty-broker-pipeline.md`, and `renderer-bug-class-triage.md` with
`bug-class-triage.md` so the listed references match the actual asset filenames
added in this PR.
In
@.agentworkforce/workforce/personas/__assets/terminal-renderer/pty-broker-pipeline.md:
- Around line 170-172: The three referenced companion filenames are wrong;
update the links in the list that currently point to
`xterm-internals-and-renderers.md`, `ansi-vt-escape-sequences.md`, and
`renderer-bug-class-triage.md` to the actual files added by this PR:
`xterm-internals.md`, `ansi-vt-sequences.md`, and `bug-class-triage.md` so
readers don't hit dead links — locate the list in the pty-broker-pipeline.md
block and replace each outdated filename with its corresponding new filename.
- Around line 7-19: The fenced code block starting with the PTY child process
pipeline diagram is missing a language identifier, which violates markdown
linting rule MD040. Add an appropriate language identifier after the opening
triple backticks (for example, "text", "plaintext", or "diagram") to specify the
code block language. This will ensure the markdown lints correctly in strict
documentation CI environments.
In
@.agentworkforce/workforce/personas/__assets/terminal-renderer/xterm-internals.md:
- Around line 103-105: The companion-reading filenames referenced in the prose
(`react-lifecycle-decoupling-and-token-ownership.md`,
`pty-broker-streaming-pipeline.md`, `ansi-vt-escape-sequences.md`) are outdated;
update these references to the actual asset filenames introduced in this PR
(`lifecycle-decoupling.md`, `pty-broker-pipeline.md`, `ansi-vt-sequences.md`) so
links/mentions match the repo. Locate the mentions in xterm-internals.md and
replace the three old filenames with the corresponding new names
(`lifecycle-decoupling.md`, `pty-broker-pipeline.md`, `ansi-vt-sequences.md`)
ensuring spelling and hyphenation match the asset files exactly.
- Around line 9-11: Add a language tag to the fenced code block that contains
"Parser → InputHandler → Buffer → Renderer" so the block is not
language-ambiguous (MD040); edit the triple-backtick opening to include an
appropriate language identifier such as "text" (or "flow"/"mermaid" if you
intend it to be rendered as a diagram) to satisfy the linter and preserve the
existing content.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: ba2611ae-9d5e-44ed-ad76-ed7a0afd3046
📒 Files selected for processing (7)
.agentworkforce/workforce/personas/__assets/terminal-renderer/ansi-vt-sequences.md.agentworkforce/workforce/personas/__assets/terminal-renderer/bug-class-triage.md.agentworkforce/workforce/personas/__assets/terminal-renderer/fix-discipline.md.agentworkforce/workforce/personas/__assets/terminal-renderer/lifecycle-decoupling.md.agentworkforce/workforce/personas/__assets/terminal-renderer/pty-broker-pipeline.md.agentworkforce/workforce/personas/__assets/terminal-renderer/xterm-internals.md.agentworkforce/workforce/personas/terminal-renderer.json
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 7 files
You’re at about 95% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Multiple bot reviewers (coderabbit, cubic, gemini) flagged the same
high-confidence issue: 'Companion reading' sections in each skill file
referenced the original long ID names (xterm-internals-and-renderers.md,
pty-broker-streaming-pipeline.md, etc.) rather than the actual short
filenames (xterm-internals.md, pty-broker-pipeline.md). Cross-doc links
were dead.
Fixed:
- All 6 'Companion reading' sections now reference the actual filenames
- Two inline references (bug-class-triage.md, fix-discipline.md)
- Character set designation sequences: \e(B / \e(0 (no space between
'(' and final byte — gemini correctly noted my readability spaces
were technically inaccurate)
- 'one-pixel bounce' → 'one-row bounce' for the SIGWINCH bounce (it's
a terminal-row resize, not a pixel resize)
- 'Move up 60 lines' clarified to distinguish absolute (CSI <r>;<c> H)
vs relative (CSI <n> A) cursor movement
- Language tags on the untyped fenced blocks the bots flagged
specifically (MD040 in xterm-internals, pty-broker-pipeline,
ansi-vt-sequences, fix-discipline)
H1 titles in each file (e.g. # xterm-internals-and-renderers) preserved
— they're descriptive section names, not file references, and serve as
the canonical skill IDs which the persona JSON also uses.
|
Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI. |
…ative paths The 6 skills[] sources used paths relative to the personas dir (`__assets/terminal-renderer/*.md`), but the AgentWorkforce local-skill provider (persona-kit skills.js `localProvider`) resolves a relative `source` against `repoRoot = process.cwd()` (cli.js:1242/1346/1376) — the project root. So they resolved to `<root>/__assets/...`, which does not exist, and the `cp` install silently failed: the skills never loaded. Fix: use the full repo-root-relative path `.agentworkforce/workforce/personas/__assets/terminal-renderer/*.md`, matching the supported local-skill form documented in the provider (e.g. `.agentworkforce/workforce/skills/<name>.md`). All 6 now resolve to real files; JSON validates; skill files unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI. |
A Claude skill is only valid/discoverable with a YAML frontmatter block (name + description). The 6 terminal-renderer skill .md files started straight at the H1 with no frontmatter, so they would not register as skills once installed. Add `name` + a one-line "Use when…" `description` to each, matching the workforce personas/skills/<name>/SKILL.md shape. `name` is set to each file's basename stem (ansi-vt-sequences, bug-class-triage, fix-discipline, lifecycle-decoupling, pty-broker-pipeline, xterm-internals) — the install dir the local-skill provider derives from the source basename, which a Claude skill's frontmatter name must match. Files stay where they are; the earlier path fix is unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Your free trial PR review limit of 300 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Six substantive markdown skill files extracted from the PR #158 fix-cycle operating knowledge, plus the persona JSON updated to reference them via local paths under
__assets/terminal-renderer/.Supersedes #165 (which used phantom remote-package source references). Matches the existing
.agentworkforcelocal-asset pattern (slack-commsuses__assets/slack-comms/slack-comms.mdfor itsclaudeMd).Skills
xterm-internals.mdpty-broker-pipeline.mdterm.write, rAF coalescing per agent key, tail-only listener semantics, snapshot-vs-replay race during attach, SIGWINCH bounce for Ink TUIs, 10k trim cap accounting, predictive echo disciplineansi-vt-sequences.mdbug-class-triage.mdlifecycle-decoupling.mdclearOnDataIfidentity-checked clear, dispose orderingfix-discipline.mdTotal: 934 lines of structured operating knowledge.
Why this exists
PR #158's six-hour fix cycle (15 bugs caught + 8 fixes + the token-ownership refactor + the AGENTS.md test suite) generated a lot of hard-won renderer-specific knowledge. Capturing it as structured persona assets means future investigations don't have to re-derive the same lessons from scratch.
🤖 Generated with Claude Code