setup-tobico-skills

Files (1)

• SKILL.md

SKILL.md (first lines)

# Setup (tobico skills)

Owns the per-project git-workflow conventions the tobico skills read. Everything lives in one committed file, **`docs/agents/git-workflow.md`**, with one section per convention:

- `## Branch naming` — the feature-branch pattern (read by `/to-tasks`)
- `## Review process` — how a finished feature branch is landed (read by `/next-task`)

Sections are filled **on demand**: a section counts as configured only when it has real content, not just a heading.

## Asking questions

Whenever you put a question to the user — a convention menu, the handle prompt, or an ad-hoc question when something is unclear — ask it and wait for their answer before carrying on. See the menu note below for how this applies to the convention menus.

## Invocation

- **Directly (`/setup-tobico-skills`)** — proactive full setup: walk *every* section, showing the current value where one exists and offering keep-or-change, and write the complete file.
- **Scoped (delegated by another skill)** — configure only the section that skill named (`branch-naming` or `review-process`), then return so the caller continues. This is the normal path; `/to-tasks` and `/next-task` invoke it when their section is missing.

Determine the scope from how you were invoked. If a caller named a section, do only that one. A bare direct invocation does all sections.

## Menus are the only place conventions are chosen

Other skills never prompt for these conventions — they read the file or delegate here. Keep the menus and the canonical section text in this skill only.

Present each menu as its numbered choices with the default marked, and let the user free-type a custom answer instead of picking one.

- **A proactive full run asks both convention menus together.** They're independent of each other, so there's nothing to gain by walking them section by section.
- **Ask for the handle alongside the branch-naming menu**, rather than waiting to see whether the chosen pattern contains `<handle>`. Skip it when the handle is already in global git config, and ignore the answer if the chosen pattern turns out not to need it.

## Branch naming

The feature-branch pattern is stored as a token string on a `Pattern:` line. Supported tokens:

- `<feature>` — the kebab-case feature name the caller picked (e.g. `credential-storage`)
- `<handle>` — the developer's short handle (see **Handle** below)

Anything else in the pattern is literal text.

### Configure

1. If the section already has a `Pattern:` line and this is a proactive run, show it and ask whether to keep or change it. If keeping, skip to the handle step.
2. Otherwise present the menu (offer these three; the user may free-type a custom pattern):

   - **`<handle>/<feature>`** — e.g. `tobi/credential-storage`
   - **`<feature>`** — bare kebab-case, no prefix
   - **Free text** — a custom pattern using the `<handle>` and `<feature>` tokens (e.g. `feature/<feature>`)

3. Write the chosen pattern into `docs/agents/git-workflow.md` under `## Branch naming`:

        ## Branch naming

        Pattern: `<chosen pattern>`

4. **Handle** — only if the chosen pattern contains the `<handle>` token:
   - Read the per-user handle from `git config --global tobico.handle`.
   - If it's set, nothing to do.
   - If it's unset, ask the user for their handle, offering a default derived from the email local-part (`git config user.email`, the part before `@`). Store the answer:

            git config --global tobico.handle <handle>

     The handle is per-user and lives in global git config — never write it into `git-workflow.md` (that file is committed and shared).

   When invoked scoped and the pattern is *already* configured but the handle is just missing (e.g. a teammate freshly cloned the repo), skip the menu entirely and do only this handle step.

## Review process

Defines how a completed feature branch is finished and landed. Stored under `## Review process` as a `### Finish sequence` (the ordered steps `/next-task` executes) plus a `### Notes` block.

### Configure

1. If the section already has a `### Finish sequence` and this is a proactive run, show it and ask whether to keep or change it.
2. Otherwise present the menu (offer these four; the user may free-type a custom process, e.g. Bitbucket):

   - **GitHub PR** — push the branch and open a draft PR.
   - **GitHub PR, stacked** — the same, plus native stacked PRs via `gh stack` for a roadmap stage that builds on a predecessor whose PR hasn't merged. It is the GitHub PR option with a second path bolted on, so an unstacked feature behaves identically.
   - **None** — merge the finished branch directly to the default branch.
   - **Free text** — the user describes their own process.

   Suggest the stacked variant where it can pay off — a GitHub remote, and `/to-roadmap` work plausible in this repo. It is dead weight somewhere that only ever runs single-stage features.

3. Write the chosen finish steps into `docs/agents/git-workflow.md`. `/next-task` executes these steps verbatim, supplying dynamic context (feature name, completed-task summary, roadmap stage) when a step opens a PR.

   For **GitHub PR**, write:

        ## Review process

        ### Finish sequence

        1. Push the current feature branch to origin.
        2. Open a **draft** PR (`gh pr create --draft`). Title = feature name;
           body = summary of the completed tasks (name the stage and roadmap if
           this was a roadmap stage). Return the PR URL.

        ### Notes

        - Default branch: <detected default, e.g. main>
        - PRs open as draft. Change "draft" to "ready" here to open ready-for-review.

   For **GitHub PR, stacked**, write the same thing with the stacked path added:

        ## Review process

        ### Finish sequence

        **Unstacked branch** — the normal case:

        1. Push the current feature branch to origin.
        2. Open a **draft** PR (`gh pr create --draft`). Title = feature name;
           body = summary of the completed tasks (name the stage and roadmap if
           this was a roadmap stage). Return the PR URL.

        **Stacked branch** — created with `gh stack init`/`gh stack add`:

        1. `gh stack submit --auto` — pushes every branch in the stack, opens a
           PR for each branch that lacks one, repoints the base of existing PRs,
           and creates or updates the Stack on GitHub. **Always pass `--auto`**:
           bare `gh stack submit` opens an interactive editor an agent can't
           drive. With `--auto` new PRs are created as drafts (`--open` would
           make them ready for review — don't).

From tobico/tobico-skills, MIT.

More from tobico/tobico-skills