Setup

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. ``

1. 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ð. ``

1. Check /install.sh exists and is executable. If not, hard-fail with the same recovery guidance.
2. 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] ```

1. 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:

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/@@'`.

1. 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
• Source: sandsower/beislid
• License: MIT

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