mirror of
https://github.com/coderabbitai/skills.git
synced 2026-09-14 20:26:36 +08:00
Align assisted onboarding with guarded config protocol
This commit is contained in:
nehal-a2z
@@ -21,8 +21,13 @@ This file is the repository's operating inventory for where CodeRabbit skills an
|
||||
|
||||
## Solutions-assisted onboarding suite
|
||||
|
||||
See [candidate prerequisites and the four-lane acceptance checklist](solutions/README.md)
|
||||
before sharing this suite. The configuration protocol must be verified on the
|
||||
chosen CLI build; installing the latest stable CLI is not sufficient evidence.
|
||||
|
||||
These skills are public source but are not part of the default skill package or
|
||||
native plugins. Install one only from its exact repository path:
|
||||
native plugins. After the suite is merged, install one only from its exact
|
||||
repository path:
|
||||
|
||||
```bash
|
||||
npx skills add https://github.com/coderabbitai/skills/tree/main/solutions/onboard --skill onboard
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
# Opt-in assisted onboarding
|
||||
|
||||
`onboard`, `config`, and `connect` are optional assisted-engagement skills, not
|
||||
part of ordinary skills discovery, native plugins, or the CodeRabbit CLI's
|
||||
default skill release archive. Install only a skill the user explicitly asks
|
||||
for, using its exact repository path and `--skill` name. See the repository's
|
||||
[distribution guide](../DISTRIBUTION_CHANNELS.md) for installation commands.
|
||||
|
||||
## CLI prerequisite
|
||||
|
||||
Use an engagement-approved CLI candidate that implements the guided
|
||||
`coderabbit config` flow, human-driven `--detailed` mode, and configuration
|
||||
protocol v1. Record the candidate version and build provenance; do not assume
|
||||
the latest public release supports these operations.
|
||||
|
||||
```bash
|
||||
coderabbit --version
|
||||
coderabbit config --help
|
||||
coderabbit config inspect --help
|
||||
coderabbit config apply --help
|
||||
coderabbit config validate --help
|
||||
```
|
||||
|
||||
On an existing YAML fixture, `inspect --json` must report `protocolVersion: 1`
|
||||
and a base hash. On a new repository, it must identify guided creation as
|
||||
required. Missing capabilities are a candidate blocker, not permission for an
|
||||
agent-authored fallback. Standard and both human-driven lanes require a real
|
||||
interactive terminal; an agent must leave choices to the human.
|
||||
|
||||
## Four acceptance lanes
|
||||
|
||||
Use disposable repositories and the approved candidate. Exercise each lane
|
||||
with both a new repository and an existing sparse YAML file containing comments,
|
||||
an explicit parent/inheritance setting, and an unrelated non-default setting.
|
||||
Do not submit reviews, install host skills, authorize integrations, or modify
|
||||
product settings as part of these checks.
|
||||
|
||||
| Lane | Entry point | Required observation |
|
||||
| --- | --- | --- |
|
||||
| Standard `/config` | Invoke `$config` and choose Standard. | Opens `coderabbit config` in a PTY; the human owns source/style choices and preview approval. Preserves parent configuration unless the human deliberately changes it. |
|
||||
| Detailed `/config` | Invoke `$config` and choose Detailed. Supply a few explicit preferences upfront. | Considers the detailed sections without re-asking settled choices; asks only material unknowns, at most three together. Uses inspect → proposal → validate → hash-checked dry-run → one approval → exact apply → re-inspect. |
|
||||
| Human-driven Standard | Run `coderabbit config` directly. | Completes the quick guided flow and preview without agent-authored YAML. Existing parent/inheritance behavior is preserved unless explicitly changed. |
|
||||
| Human-driven Detailed | Run `coderabbit config --detailed` directly. | The human drives the CLI's core-settings wizard. This is not the agent's schema-wide Detailed discovery workflow. |
|
||||
|
||||
For new repositories, both skill lanes must let the guided CLI check central
|
||||
configuration and create the initial file before any agent proposal. Re-inspect
|
||||
after creation. Without a PTY, provide the exact human command and stop. If the
|
||||
guided flow leaves no active local file, do not proceed to apply. For existing
|
||||
YAML, preserve comments, unrelated settings, and sparse inheritance; never
|
||||
materialize defaults or a resolved configuration.
|
||||
|
||||
Additional failure cases:
|
||||
|
||||
- Valid YAML with a schema-invalid value: `/onboard` must run validation and
|
||||
report `Needs action`, even when inspection returns `ok: true`.
|
||||
- Install only `/connect`, then request repository integration settings with no
|
||||
local YAML: use guided creation first; never propose an `apply --base none`.
|
||||
- Change the repository YAML after a Detailed dry-run: the old-hash apply must
|
||||
fail without replacing the changed file. Re-inspect, rebase, and obtain fresh
|
||||
approval for the revised proposal.
|
||||
- TypeScript, delegated, symlinked, or ambiguous authority: no local apply.
|
||||
- No supported connection-status response: `/connect` reports `Unknown` or
|
||||
`Configured, verification pending`, not a completed live connection.
|
||||
|
||||
Record the candidate version/build, fixture, lane, exact commands, observed
|
||||
exit codes, before/after diff, and pass/fail or blocker. A passing packaging
|
||||
check below does not establish that these interactive lanes passed.
|
||||
|
||||
## Repeatable packaging checks
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
node --test solutions/tests/distribution.test.mjs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
The test checks the current default source directory and the committed `HEAD`
|
||||
archive used by release packaging. Re-run after committing packaging changes.
|
||||
It does not install skills or call the network.
|
||||
|
||||
With an already available Skills CLI, use local listing only:
|
||||
|
||||
```bash
|
||||
DISABLE_TELEMETRY=1 skills add . --list
|
||||
DISABLE_TELEMETRY=1 skills add . --all --list
|
||||
DISABLE_TELEMETRY=1 skills add ./solutions/onboard --skill onboard --list
|
||||
DISABLE_TELEMETRY=1 skills add ./solutions/config --skill config --list
|
||||
DISABLE_TELEMETRY=1 skills add ./solutions/connect --skill connect --list
|
||||
```
|
||||
|
||||
The first two must expose only `autofix` and `code-review`; each direct path
|
||||
must expose only its named skill. If no Skills CLI is already available, record
|
||||
that limitation rather than installing it on the host just for this check.
|
||||
@@ -24,7 +24,7 @@ coderabbit --version
|
||||
coderabbit config --help
|
||||
```
|
||||
|
||||
If `coderabbit` is missing or `config` does not support the requested operation, ask the user to upgrade from <https://docs.coderabbit.ai/cli>. Do not implement a fallback editor.
|
||||
This assisted workflow requires a CLI candidate that supports the guided flow and configuration protocol v1 (`inspect` and `apply`). If `coderabbit` is missing or the requested operation is unsupported, report the missing capability and ask for a compatible candidate from the engagement owner. The [CLI installation docs](https://docs.coderabbit.ai/cli) do not establish that the latest released CLI supports this protocol. Do not implement a fallback editor.
|
||||
|
||||
Local configuration does not require CodeRabbit authentication. Do not block this workflow on `coderabbit auth status`.
|
||||
|
||||
@@ -40,7 +40,7 @@ Pass a user-named file as one argument. Add `--json` when structured diagnostics
|
||||
|
||||
If the user has not chosen, offer:
|
||||
|
||||
1. **Standard (recommended)** — a quick balanced setup or review-style change.
|
||||
1. **Standard (recommended)** — a quick guided setup or review-style change that preserves existing parent configuration unless the user chooses otherwise.
|
||||
2. **Detailed** — inspect the repository and work linearly through a complete, evidence-backed configuration.
|
||||
|
||||
Default to Standard. Do not describe Detailed as inherently better.
|
||||
@@ -65,17 +65,20 @@ Read [references/detailed-discovery.md](references/detailed-discovery.md), then
|
||||
coderabbit config inspect --json
|
||||
```
|
||||
|
||||
Require `ok: true`, `protocolVersion: 1`, and `writable: true` before preparing a local-file proposal. If the CLI reports TypeScript, delegated, symlinked, or ambiguous authority, explain the reported reason and stop instead of guessing.
|
||||
Require `ok: true` and `protocolVersion: 1` before continuing. Inspection reports authority and syntax, not schema validity.
|
||||
|
||||
If inspection reports no active repository configuration, do not author the
|
||||
first YAML file. Run `coderabbit config` in an interactive terminal and let the
|
||||
user complete the guided creation and preview, which checks for central
|
||||
Handle `requiresGuidedCreation: true` or no `activeConfig` before checking
|
||||
writability: do not author the first YAML file. Run `coderabbit config` in an
|
||||
interactive terminal and let the user complete the guided creation and preview,
|
||||
which checks for central
|
||||
configuration. Then inspect the created sparse file and continue Detailed
|
||||
analysis. If no interactive terminal is available, give the exact command and
|
||||
stop. This keeps central configuration detection and initial authority inside
|
||||
the CLI.
|
||||
|
||||
Use the returned raw YAML as the starting document and the returned schema URL as the current source of truth. The agent may reason across any setting in that live schema, but it must recommend only settings supported by repository evidence or an explicit user choice. Follow the reference's Detailed sequence in order. For each section, show the current repository value, recommendation, and evidence, then let the user accept, change, or skip it. Keep questions to three or fewer at a time.
|
||||
For an existing active file, require `writable: true` and a real `baseHash` before preparing a proposal. If the CLI reports TypeScript, delegated, symlinked, or ambiguous authority, explain the reported reason and stop instead of guessing. A guided flow that creates no local file does not authorize an apply.
|
||||
|
||||
Use the returned raw YAML as the starting document and the returned schema URL as the current source of truth. The agent may reason across any setting in that live schema, but it must recommend only settings supported by repository evidence or an explicit user choice. Consider the reference's Detailed sections in order, reusing explicit choices the user has already made. Show the current repository value, recommendation, and evidence; ask only about material unknowns, in batches of no more than three questions. Do not require a separate approval for every section. Request one approval for the complete validated proposal below.
|
||||
|
||||
Create the complete proposed YAML in a temporary file outside the repository. Preserve existing comments, ordering, and unrelated settings wherever possible. Keep it sparse; do not materialize defaults.
|
||||
|
||||
@@ -88,7 +91,7 @@ coderabbit config validate <temporary-proposal.yaml> --json
|
||||
Then preview it against the inspected base hash:
|
||||
|
||||
```bash
|
||||
coderabbit config apply <temporary-proposal.yaml> --dry-run --base <baseHash|none> --json
|
||||
coderabbit config apply <temporary-proposal.yaml> --dry-run --base <baseHash> --json
|
||||
```
|
||||
|
||||
Show the user:
|
||||
@@ -101,7 +104,7 @@ Show the user:
|
||||
Ask for explicit approval. Only after approval, apply the exact validated proposal:
|
||||
|
||||
```bash
|
||||
coderabbit config apply <temporary-proposal.yaml> --yes --base <baseHash|none> --json
|
||||
coderabbit config apply <temporary-proposal.yaml> --yes --base <baseHash> --json
|
||||
```
|
||||
|
||||
If the base changed, inspect again and rebase the proposal. Never bypass the hash check. Remove the temporary proposal when finished.
|
||||
|
||||
@@ -44,7 +44,7 @@ Session evidence may improve a recommendation; it must never silently authorize
|
||||
|
||||
## Work through the Detailed sequence
|
||||
|
||||
Move through these sections in order. For each section, show current repository values, a recommendation with evidence, and `Accept / Change / Skip`. Ask no more than three questions at once.
|
||||
Consider these sections in order. Show current repository values and recommendations with evidence, reusing the user's explicit choices without asking them again. Ask only about material unknowns, in batches of no more than three questions. The user may change or skip any recommendation; do not require section-by-section approvals. Request one approval for the complete validated proposal.
|
||||
|
||||
1. **Configuration source** — Preserve existing configuration inheritance. For a new file, let `coderabbit config` detect central configuration before continuing. Do not claim central or dashboard settings exist without CLI evidence.
|
||||
2. **Review profile** — Choose `reviews.profile` from the user's desired feedback depth. Distinguish an explicit repository value from an inherited value or schema default.
|
||||
@@ -79,7 +79,7 @@ Generated or vendored paths usually support a scope/filter recommendation, not a
|
||||
|
||||
## Build the proposal
|
||||
|
||||
Use the live schema URL returned by `coderabbit config inspect --json`; do not rely on a remembered key catalog. Preserve the current raw YAML as the base document. For a new file, produce a sparse proposal containing only deliberate choices.
|
||||
Use the live schema URL returned by `coderabbit config inspect --json`; do not rely on a remembered key catalog. Preserve the existing raw YAML as the base document. If guided creation is required or no active file exists, complete the human-guided CLI flow and inspect again before preparing a proposal. Never author the first YAML independently.
|
||||
|
||||
Before validation, check that:
|
||||
|
||||
|
||||
@@ -102,10 +102,20 @@ After the connection exists, invoke `$config` when available for any repository
|
||||
setting, such as issue scope, Jira project keys, MCP usage, disabled MCP servers,
|
||||
or linked repositories.
|
||||
|
||||
Without `$config`, use only the CLI-owned configuration protocol. Prefer the
|
||||
interactive flow when it covers the requested setting. For a broader proposal,
|
||||
require `coderabbit config inspect --json`, schema validation, dry-run, base-hash
|
||||
checking, and explicit approval before `coderabbit config apply`.
|
||||
Without `$config`, use only a CLI candidate supporting the guided flow and
|
||||
configuration protocol v1; do not assume the latest released CLI supports it.
|
||||
Run `coderabbit config inspect --json` and require `ok: true` and
|
||||
`protocolVersion: 1`. Handle `requiresGuidedCreation: true` or no `activeConfig`
|
||||
before checking writability: let the human complete `coderabbit config` in a
|
||||
PTY so the CLI checks central configuration, then inspect again. Without a PTY,
|
||||
give that exact command and stop. Never prepare the first YAML independently.
|
||||
|
||||
For an existing active YAML file, require `writable: true` and its real
|
||||
`baseHash`; stop on unsupported or ambiguous authority. Start a sparse proposal
|
||||
from the existing raw YAML and the returned live schema. Require schema
|
||||
validation, a dry-run against that hash, and one explicit approval for the exact
|
||||
proposal before `coderabbit config apply`. Never use `--base none`. If the base
|
||||
changes, inspect again and rebase the proposal rather than bypassing the guard.
|
||||
|
||||
Never edit `.coderabbit.yaml` directly and never materialize the resolved
|
||||
configuration or schema defaults into the file.
|
||||
|
||||
@@ -61,6 +61,17 @@ state without writing:
|
||||
coderabbit config inspect --json
|
||||
```
|
||||
|
||||
Inspection establishes authority and syntax, not schema validity. For an active
|
||||
YAML file, also run the read-only validation command:
|
||||
|
||||
```bash
|
||||
coderabbit config validate --json
|
||||
```
|
||||
|
||||
Require successful schema validation before reporting local configuration as
|
||||
`Ready`. Failed validation is `Needs action`; unavailable validation is
|
||||
`Unknown`. Do not infer validity from `ok: true` in inspection output.
|
||||
|
||||
Treat a missing command as unsupported, not as permission to inspect home
|
||||
directories, query product databases directly, or invent a fallback result.
|
||||
|
||||
@@ -74,7 +85,7 @@ evidence and the next owner:
|
||||
| CLI | An official CLI is present and `coderabbit doctor` has no blocking local failure. |
|
||||
| Authentication | Structured auth status confirms login and the intended organization. |
|
||||
| Git-platform access | A supported product or CLI response proves CodeRabbit can access this repository. Local Git access alone is insufficient. |
|
||||
| Repository configuration | CLI inspection reports a valid active file, or authoritative product/backend evidence proves the intended effective configuration without one. |
|
||||
| Repository configuration | CLI inspection identifies the active YAML file and `coderabbit config validate --json` succeeds, or authoritative product/backend evidence proves the intended effective configuration without a local YAML file. |
|
||||
| Context connections | Required issue tracker, MCP, related-repository, and reporting setup is verified; optional connections may be `Not needed`. |
|
||||
| Review proof | A real local review or existing pull-request review has completed on the intended repository. |
|
||||
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
import assert from 'node:assert/strict';
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { test } from 'node:test';
|
||||
|
||||
const root = fileURLToPath(new URL('../../', import.meta.url));
|
||||
const defaultSkills = ['autofix', 'code-review'];
|
||||
|
||||
test('ordinary skill source contains only the default skills', () => {
|
||||
const names = readdirSync(new URL('../../skills/', import.meta.url))
|
||||
.filter((name) => existsSync(new URL(`../../skills/${name}/SKILL.md`, import.meta.url)))
|
||||
.sort();
|
||||
assert.deepEqual(names, defaultSkills);
|
||||
const cursor = JSON.parse(readFileSync(new URL('../../.cursor-plugin/plugin.json', import.meta.url)));
|
||||
assert.equal(cursor.skills, './skills/');
|
||||
});
|
||||
|
||||
test('the committed release archive excludes the entire assisted suite', () => {
|
||||
const archive = execFileSync('git', ['archive', '--format=tar', 'HEAD'], { cwd: root });
|
||||
const entries = execFileSync('tar', ['-tf', '-'], { input: archive, encoding: 'utf8' })
|
||||
.trim()
|
||||
.split('\n');
|
||||
assert.equal(entries.some((path) => path.startsWith('solutions/')), false);
|
||||
const skills = entries.filter((path) => path.endsWith('/SKILL.md')).sort();
|
||||
assert.deepEqual(skills, defaultSkills.map((name) => `skills/${name}/SKILL.md`));
|
||||
});
|
||||
Reference in New Issue
Block a user