# Setup

> Configure Beislið project config (`.beislid/workflow.md`) interactively, or update an installed Beislið distribution. Use when the user says "setup", "/setup", "setup update", "/setup update", "update beislid", "configure beislid", "set up workflow", "add scopes", "change ticket source", "reconfigure beislid", or any intent to add, change, or remove a workflow.md section. Walks through sections c…

- **Type:** Skill
- **Install:** `agentstack add skill-sandsower-beislid-setup`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sandsower](https://agentstack.voostack.com/s/sandsower)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sandsower](https://github.com/sandsower)
- **Source:** https://github.com/sandsower/beislid/tree/main/skills/setup

## Install

```sh
agentstack add skill-sandsower-beislid-setup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Setup

Initialize or update Beislið's per-project config at `/.beislid/workflow.md`, or run the Beislið distribution updater when invoked as `setup update` / `/setup update`. Setup is the canonical config interface — direct file editing still works as an escape hatch but isn't surfaced in user-facing prose.

**First run** (no workflow.md): run a minimal-required interview (ticket source, branch pattern, default PR base, probe cache), write the file, insert the repo bootstrap `## Agent skills` block in `AGENTS.md`, then offer the same menu shown on re-run for adding optional sections.

**Re-run** (workflow.md exists): show a menu — add a section, change a configured section, remove a configured section, reset and regenerate, or cancel. Never silently overwrites; every destructive write shows a diff and asks for confirmation.

Format reference: `workflow-md-format.md` (symlink to the master). Probe semantics for capability discovery: `probe-semantics.md` (symlink to the master).

## 0. Update mode

If the invocation includes update intent (`setup update`, `/setup update`, `update beislid`, or equivalent), do not enter project-config setup and do not read or write `/.beislid/workflow.md`.

Run this distribution-update flow instead:

1. Resolve the install manifest path: `${BEISLID_STATE_DIR:-$HOME/.local/state/beislid}/install.json`.
2. Read the manifest. If missing, hard-fail with:

   ```
   🛑 No Beislið install manifest found at ``. Run `install.sh --update`
   from your Beislið checkout, or reinstall Beislið with `/install.sh`.
   ```

3. Read `repo` from the manifest. If empty, missing, or not a directory, hard-fail with:

   ```
   🛑 Beislið install manifest does not point at a valid repo: ``.
   Run `install.sh --update` from your Beislið checkout, or reinstall Beislið.
   ```

4. Check `/install.sh` exists and is executable. If not, hard-fail with the same recovery guidance.
5. Show the planned action and ask for confirmation:

   ```
   📋 Update Beislið from ``?

   This will run:
   `/install.sh --update`

   The installer will abort if the Beislið checkout has uncommitted changes,
   preserve prior install targets and opt-ins from the manifest, fast-forward
   with `git pull --ff-only`, then relink skills/hooks as needed.

   Proceed? [Y/n]
   ```

6. On `n`, exit cleanly without running anything. On `Y`, run `/install.sh --update` and stream output. Report success or failure with the command's exit code.

Tripwires:

- Update mode never modifies project-owned `.beislid/workflow.md`.
- Do not infer the install repo from skill symlinks; the manifest `repo` field is authoritative.
- Do not add `--force` unless the user explicitly asks for it in the same update request.

## 1. Precheck git repo

Run `git rev-parse --show-toplevel`. If it errors or returns non-zero, hard-fail with prose:

```
🛑 Setup needs a git repo with at least one commit. Run `git init` and make
the first commit, then re-run /setup.
```

Also check `git rev-list --max-parents=0 HEAD` exits 0 (at least one commit). Same hard-fail otherwise.

## 2. Detect mode

Check `/.beislid/workflow.md`:

- **Missing** → first-run flow (sections 3–10 below).
- **Exists** → menu mode (section 11).

## 3. First-run: targeted inspection

Run cheap-signal commands once at the top, before asking anything:

```bash
git remote get-url origin                              # → host + owner/repo
gh auth status 2>&1                                    # → is gh CLI logged in?
git log -50 --pretty=%s                                # → grep for ID patterns
git for-each-ref refs/heads --format='%(refname:short)' --sort=-committerdate \
  | head -20                                           # → branch_pattern candidates
```

Parse `git remote` for host (`github.com` / `gitlab.com` / etc.) and `owner/repo`. Parse `gh auth status` for the auth state on github hosts. Grep commit subjects for `[A-Z]{2,4}-\d+` (Linear/Jira shape) and `^#?\d+` (GitHub/Azure numeric shape). Hold these results in memory for the interview prompts.

## 4. First-run: ticket_source interview

Use the inspection results to suggest a default. One suggestion at a time, single Y/n confirmation; never silent fill.

**If host is github.com + gh authed + numeric IDs detected in commits:**

```
🔍 Detected GitHub Issues with `gh` CLI (numeric IDs in recent commits).
Use `type: cli, command: 'gh issue view {id} --json title,body,labels'`?
[Y/n/different]
```

On `Y`: capture `id_pattern: '^#?\d+$'` and `link_template: 'https://github.com///issues/{id}'` (deterministic from `git remote`).

**If Linear-shaped IDs detected (`[A-Z]+-\d+`):**

Try MCP discovery via `probe-semantics.md` (search for tools matching `*linear*` or `*issue*`). On match:

```
🔍 Linear-shaped IDs in recent commits + Linear MCP tool detected
(``). Use this for ticket fetching? [Y/n/different]
```

On `Y`: capture `type: mcp, tool: , id_pattern: '^[A-Z]+-\d+$'`. Ask once for the workspace name to populate `link_template: 'https://linear.app//issue/{id}'`. If the host resolves the same integration through an alias, keep the configured tool name canonical and let the probe report the alias-satisfied match instead of forcing a session-local override.

If MCP discovery returns no Linear-shaped tools: do NOT ask the user to type an MCP tool name. Pivot:

```
💭 Linear-shaped IDs detected but no Linear MCP tool is available in this
host. Pick an alternative:
  (a) cli — give me the command for fetching tickets
  (b) paste — I'll ask for the title at every PR handoff
```

**If no detectable signal:** ask `(mcp / cli / file / paste)` directly. For `mcp`: list available MCP tools via `probe-semantics.md` and ask to pick one. For `cli`: ask for the command (must contain `{id}` placeholder). For `file`: ask for the file glob. For `paste`: no further input.

In every branch, capture `id_pattern` (auto-derived from the dominant grep pattern) and `link_template` for known hosts (deterministic). Never ask the user to type an MCP tool name.

## 5. First-run: branch_pattern interview

Test these 8 candidate regexes against the last 20 branches. Sort by coverage (number of branches that match).

```
1. ^[a-z]+/([a-z]+-\d+)       — case-mismatched (normalize via id_pattern)
2. ^[a-z]+/([A-Z]+-\d+)       — Jira with type prefix
3. ^([A-Z]+-\d+)              — Jira/Linear direct uppercase
4. ^([a-z]+-\d+)              — direct lowercase
5. ^(\d+)-                    — github/azure numbered with description
6. ^[a-z]+/(\d+)              — feature/123 (Azure DevOps, GitHub)
7. ^[a-z]+/[a-z]+/(\d+)       — Azure DevOps users//12345
8. ^[a-z]+-(\d+)              — gh-123 style
```

Suggest the highest-coverage candidate with stats:

```
🔍 Branch pattern `^[a-z]+/([a-z]+-\d+)` matches 18 of 20 recent branches.
Use it? [Y/n/skip]
```

If best coverage /dev/null | sed 's@^refs/remotes/origin/@@'`.
3. Else: `main`.

If the result is `main`: silent default — don't ask. If the result is anything else, confirm:

```
🔍 Default branch detected: ``. Use as pr_base? [Y/n]
```

On `n`: ask the user for the branch name.

## 7. First-run: compose minimum workflow.md

Compose in memory:

- Version stamp `` (line 1).
- Project name comment from `basename $(git rev-parse --show-toplevel)`.
- `## Issue tracker` section with the captured `ticket_source` and (if present) `branch_pattern` blocks.
- `## PR target` section with `pr_base.default` (only if non-`main`).
- `## Probe cache` section with `ttl_hours: 24`.

No commented-out templates. Only sections the user filled in.

## 8. Show preview

Print the composed workflow.md to the user as context, then ask the explicit approval question once in the final response:

```
📋 Preview of `.beislid/workflow.md`:

Write this to `/.beislid/workflow.md`? [Y/n]
```

On `n`: cancel without writing. On `Y`: continue to step 9.

## 9. Write workflow.md and insert AGENTS.md block

Run `mkdir -p /.beislid/` then write the file. Print:

```
📝 Wrote .beislid/workflow.md
```

Then run the AGENTS.md block insertion (section 12 below).

After writing the minimum, offer the menu mode (section 11 — same UI as re-run) for adding optional sections.

## 10. Next-steps report after writes

After any successful `.beislid/workflow.md` write (first-run, add/change/remove, or reset), print a concise next-steps report:

```
✅ Beislið config written.

Files to review/commit:
- .beislid/workflow.md
- AGENTS.md (when added or updated)

Configured now: 
Not configured yet: 

Next:
1. Run /doctor to verify the config and warm the probe cache.
2. Run each configured gate command once from the repo root.
3. Commit .beislid/workflow.md and AGENTS.md together.
4. For team rollout guidance, read the Beislið team rollout guide: https://github.com/sandsower/beislid/blob/main/docs/team-rollout.md.
```

Keep the report factual. Do not imply unconfigured layers are required; present them as optional strictness layers to add deliberately later.

## 11. Menu mode

When `.beislid/workflow.md` already exists, parse it (using the grammar in `workflow-md-format.md`). If parsing fails, jump to **section 13: parse-error recovery**. Otherwise present:

```
📋 Found .beislid/workflow.md. What would you like to do?

  (1) Add a section
  (2) Change a configured section
  (3) Remove a configured section
  (4) Reset and regenerate from scratch
  (5) I'm done
```

**On (1) Add a section:** present a sub-menu of optional sections that aren't yet configured. Each item shows a one-line "when this fires" hint (plain English, not phase-numbered):

- **Scopes & quality gates** — *Run lint/test commands across the repo, scopes, or changed-file-aware gate sets. Simple gates need only name+command; rich gates may add stage, cost, timeout, selectors, output parser, and failure policy.*
- **Explore skill** — *Let kickoff Step 2 run a project skill as an exploration enhancer or replacement before design.*
- **Model routing** — *Declare preferred or required host model candidates per Beislið skill, with fallback/blocking disclosure.*
- **Translation sync** — *Run a translation-sync skill during quality gates whenever paths under your trigger globs are touched.*
- **Browser compatibility** — *Run an advisory browser compatibility skill during quality gates whenever paths under your trigger globs are touched. Doesn't block PR handoff.*
- **Domain capture** — *After kickoff or PR handoff, ask a domain expert to record findings into a knowledge store. Kickoff can use a subagent or, when the host has no subagent mechanism, an installed skill with the same name. Both the expert name and the store path are required.*
- **PR description formatter** — *Pass drafted PR descriptions through a formatter skill before showing them for approval.*
- **Guided walkthrough thresholds** — *Offer an interactive walkthrough before review when the diff exceeds N files or N lines. Defaults are 5 files / 200 lines.*
- **Clean evaluator** — *Run PR-readiness gates in a clean worktree or container, or skip that path by policy; artifacts and logs stay with the run.*
- **Visual surfaces** — *Configure optional Lavish visual-surface routing; repo config is required before workflows proactively suggest, prompt, or auto-open surfaces.*
- **Workflow signals** — *Configure optional local workflow-state signals, starting with tmux-glance tab markers for semantically instrumented skills.*
- **Babysit** — *Configure `/babysit` goal budget, review-response/gate loop behavior, and optional merge/memento/retro closeout automation.*
- **Fresh-eyes final review** — *Keep the built-in final whole-diff pass, replace it with a command, or explicitly disable it by project policy.*
- **Ticket updates** — *Post kickoff plans and review-response QA replies back to the ticket tracker; optionally create child tickets for out-of-scope feedback.*
- **Planning artifacts** — *Write approved structure/spec/design Markdown files through lifecycle actions, with prompt or safe auto-create behavior.*
- **Lifecycle actions** — *Run configured side effects at Beislið workflow events, such as assigning or moving a ticket when kickoff starts.*
- **PR review source / replies** — *Let review-response read PR review comments and either post clear-fix replies or print manual reply instructions.*
- **PR host override** — *Override owner/repo/remote only when git remote derivation is wrong, such as forks or non-origin upstreams.*

Walk the chosen section's sub-interview (asking one Y/N or value at a time). Compose the section block in memory. Insert at the canonical position in the file (canonical order is the order in `workflow-md-format.md` § Section grammar). Show diff (`git diff --no-index  ` formatted prose). Ask `Write? [Y/n]`. On `Y`: write atomically (whole-file rewrite via Read → mutate → Write), then print the next-steps report from section 10.

**On (2) Change a configured section:** show currently filled sections only. Walk that section's sub-interview pre-filled with current values; user accepts or overrides each value. Show diff; confirm; write, then print the next-steps report from section 10.

**On (3) Remove a configured section:** show currently filled sections only. On selection, check section-dependency rules and prompt for auto-clean:

- Removing `scopes` while `split_policy` is set → "Removing scopes will also remove `split_policy` (it has no meaning without scopes). Proceed? [Y/n]"
- Removing `domain_expert.agent` while `knowledge_store.path` is set → "Also remove `knowledge_store.path`? [Y/n]" (default Y; if n, leaves the half-pair)
- Removing `knowledge_store.path` while `domain_expert.agent` is set → mirror
- Removing `pr_review_source` while `pr_review_update` is set → warn that update can only be used after pasted PR feedback; ask whether to remove update too (default Y)
- Removing `pr_review_update` while `pr_review_source` is set → allowed; review-response will print PR reply/re-request instructions manually

Show diff; confirm; write, then print the next-steps report from section 10.

**On (4) Reset and regenerate from scratch:**

1. Copy current file to `/.beislid/workflow.md.bak`. Print: `📝 Saved current config to .beislid/workflow.md.bak`.
2. Run the full first-run interview (sections 3–8) in memory.
3. Show full diff of the regenerated file vs the original.
4. Ask `Write? [Y/n]`.
5. On `Y`: write atomically, then print the next-steps report from section 10.

**On (5) I'm done:** exit cleanly with no writes.

## 11a. Optional-section interviews added in Phase 3

### Scopes & quality gates

Configure one gate model: changed-file-aware `gate_sets`, scoped `scopes`, or top-level `gates`. Prefer `gate_sets` when the user wants reusable named checks, selector explanations, staged/rich gates by changed path, or multiple touched areas that union checks deterministically. Keep `scopes` and top-level `gates` backward-compatible.

For each simple gate ask: gate name, command, optional autofix command, and whether it is independent/read-only enough for `parallel_safe: true`. Explain that flat gates remain valid and default to `stage: pre-pr`, `kind: sensor`, `execution: computational`, and `mutates: false`.

If the user chooses rich metadata, collect only fields they can answer confidently:

- `stage`: one of `preflight`, `per-edit`, `pre-commit`, `pre-pr`, `post-pr`, `continuous`, `human-interrupt`; default `pre-pr`
- `kind`: default `sensor`
- `execution`: `computational`, `inferential`, or `human`; default `computational`
- `timeout_seconds`, `cost`, `mutates`, `accepts_files`, `required_tools`
- changed-file selector globs under `changed_file_selector.include` / `exclude`
- `output.parser` and `output.agent_summary`
- `failure.retryable`, `failure.max_fix_iterations`, `failure.stop_if_patterns`, and `failure.hint`

For `gate_sets`, collect named sets first (set name, optional cwd, gates), then ordered selectors (selector name, path globs, optional exclude globs, referenced set names). Explain that multiple matchi

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sandsower](https://github.com/sandsower)
- **Source:** [sandsower/beislid](https://github.com/sandsower/beislid)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sandsower-beislid-setup
- Seller: https://agentstack.voostack.com/s/sandsower
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.