sidekick

Files (1)

• SKILL.md

SKILL.md (first lines)

# Sidekick

Single-mode skill: **capture-and-exit**. Writes one seed, emits one event, returns. The host invokes this skill from inside its own task to durably record a sideline idea without breaking flow.

For *when* a host should invoke this skill, read [`shared/sidekick-capture.md`](../shared/sidekick-capture.md). This SKILL.md describes the skill's own behavior — what it accepts, what it writes, and what it emits.

## When to Use

- A host skill (`specstudio:ideate`, `specstudio:specify`, third-party adopter) has detected a sideline idea per `shared/sidekick-capture.md` and is invoking on the host's behalf.
- A user has typed `/sidekick <one-liner>` directly to park an idea.

## Anti-Pattern: Content-Deliberation at Capture

This skill MUST NOT deliberate the *merits* of the seed, ask follow-up questions about the idea's content, scan existing seeds for content duplicates, or trigger any review pipeline. Content-deliberation (is this idea worth capturing? does it duplicate an existing one? does it need scoping?) is the consilium's job (a separate Feature, not yet built). If a host invocation arrives that requires content-deliberation, that is a contract violation in the host — capture the seed and return.

The destination-resolution UX in multi-repo workspaces (see [Destination resolution](#destination-resolution-multi-repo-workspaces) below) is NOT content-deliberation: it is a pre-write confirmation of *where* the seed is durably stored, never *whether* it should be. The skill still writes (or aborts cleanly) on a single user response; no follow-up clarifying questions about the idea's substance ever happen.

## Input

The skill accepts:

- **One-liner** (required): a string of 1–500 characters after trimming leading/trailing whitespace.
- **`--body <markdown>`** (optional): additional markdown content that follows the H1 heading. A captured seed is `status: queued`, so total body length (H1 line + body) MUST NOT exceed 3000 characters (authors are advised to keep it under 2500).

## Validation rules (REQs `input-validation`, `writes-seed-artifact`)

Reject with a clear error message and exit non-zero in any of these cases:

| Case | Error message |
|---|---|
| One-liner is empty or whitespace-only | `Empty one-liner. Provide a one-line description, 1–500 chars.` |
| One-liner exceeds 500 chars after trimming | `One-liner too long (<N> chars). Max is 500.` |
| Body, combined with the H1 line, exceeds 3000 chars total (the queued cap) | `Body too long (<N> chars). Max body (incl. H1 line) is 3000 chars.` |
| Unknown flag (anything starting with `--` that is not `--body`) | `Unknown flag: <flag>. Supported: --body.` |

On rejection, the skill MUST NOT create any file, MUST NOT emit any event, and MUST exit non-zero.

## Slug derivation (REQ `seed-slug-derivation`)

The skill does **not** derive the slug — `specscore sidekick new` does, from the one-liner. The canonical algorithm **and** the slug-format validation live in the CLI (the `cli/sidekick/new` Feature), so the skill carries no copy to keep in sync. In the common case the skill omits `--slug` and lets the CLI derive. It supplies `--slug <slug>` to override — either a specific slug the user asked for, or a `-N` disambiguator for a [collision](#collision-disambiguation-req-writes-seed-artifact) — and lets the CLI validate it (an invalid slug exits `2`). The skill does **not** restate the format rules.

## Destination resolution (multi-repo workspaces)

Implements [`sidekick-capture/destination-resolution`](../../spec/features/sidekick-capture/destination-resolution/README.md). The output of this section is `<destination-repo-root>` — the absolute path of the repo the seed will be written into. Every subsequent section (Collision disambiguation, Writing the seed file, Output) uses that value.

In a **single-repo workspace** (the source project is the only `specscore.yaml`-bearing directory in its parent), this entire section is skipped: `<destination-repo-root>` is the source project root, and the skill goes directly to "Collision disambiguation". Today's behavior preserved.

### Step 1 — Sibling-dir scan (REQ `sibling-dir-scan`)

Before any seed-file write, scan the parent of the source project for sibling repos containing `specscore.yaml`:

- Walk the source project's parent directory (`..`).
- For each immediate-child entry:
  - **Skip** if the name starts with `.` (hidden dirs like `.git`, `.specscore`).
  - **Skip** if the entry is a symlink whose target resolves outside `..` (no symlink-out follows).
  - **Include** if the entry is a directory containing a `specscore.yaml`.
- Always include the source project itself as a candidate (unconditional).

The scan MUST complete in under 500ms for ≤20 siblings. For each candidate, read its `specscore.yaml` and capture `project.repo` — that's the candidate identity used downstream.

If **zero siblings** are matched (only the source project is a candidate), skip every step below this and proceed to "Collision disambiguation" using the source project root as `<destination-repo-root>`. REQ `single-repo-bypass`.

If **≥1 siblings** are matched, continue to step 2.

### Step 2 — Invoke the deliberation helper (REQ `invokes-helper-before-write`)

Read [`shared/destination-resolution.md`](../shared/destination-resolution.md) and assemble the prompt by substituting:

- `<seed-one-liner>` in section (a): the user's actual one-liner (verbatim, no normalization).
- The candidates table in section (b): one row per candidate. Each row contains:
  - **`project.repo` cell:** the value from the candidate's `specscore.yaml`. If `project.repo` is unset, fall back to the candidate's directory basename (the agent treats the fallback identifier identically — see section (b)'s fallback clause in `shared/destination-resolution.md`).
  - **Features cell:** the names of `spec/features/*/` top-level directories AND their immediate sub-directories (where they exist), formatted as `<top-level>` for plain top-level entries and `<top-level>/<sub-dir>` for nested ones. Comma-separated, capped at 20 entries per candidate with `, …` truncation when more exist. Use the literal `(no Features)` when the candidate has no `spec/features/*/` directories.

Pass the assembled prompt to the host AI agent. No seed file is written until this and the confirmation UX complete.

### Step 3 — Parse the agent's response (REQ `parses-agent-response`)

Parse per the helper's section (c) contract:

- **Exactly one line.** Multi-line response → malformed.
- **≤120 characters total** (counting the `; ` separator and reason).
- **Shape `<repo>; <reason>`** — `<repo>` (case-insensitive, whitespace-trimmed) MUST match exactly one candidate's `project.repo`.
- The literal token **`UNCERTAIN`** (case-sensitive, alone on its line, no other content) is the helper's section (d) escape clause.

Routing:

- Well-formed → step 5 (pick-with-reason confirmation).
- Malformed OR `UNCERTAIN` → step 4 (one retry).

### Step 4 — Retry, then fall through (REQ `malformed-or-uncertain-response`)

On the FIRST malformed/`UNCERTAIN` response only, re-invoke the helper. Same assembled prompt, with this corrective instruction appended at the end of the prompt body:

> Your previous response was unparseable; reply EXACTLY in `<repo>; <reason>` ≤120 chars, where `<repo>` is one of: `<comma-separated-candidate-slugs>`.

Parse the retry per step 3.

- Well-formed → step 5.
- Malformed OR `UNCERTAIN` (second time) → step 6 (ask-without-pre-fill).

There is NO second retry. The agent gets two chances; the user picks next.

### Step 5 — Pick-with-reason confirmation (REQ `shows-pick-with-reason`)

Display this exact line to the user (whitespace and punctuation literal):

```
Routing to <repo> because <reason> — press enter to accept, type other to override.
```

Where `<repo>` is the parsed pick and `<reason>` is the agent's parsed reason verbatim (including the agent's own punctuation choices). The prompt MUST appear as the next message in the host conversation and MUST block further sidekick progress until user input arrives.

On user input:

- **Empty input** (whitespace-only, including bare enter): route to the agent's picked candidate. `<destination-repo-root>` becomes that candidate's path. Proceed to "Collision disambiguation". REQ `accepts-enter-as-route-to-agent-pick`.
- **Non-empty input**: treat as an override per step 7.

### Step 6 — Ask-without-pre-fill (REQ `shows-ask-without-pre-fill`)

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills