Beislið

A human-centric, extensible framework for collaborating with coding agents.
Make agents follow the same ticket, verification, review, and PR handoff process your team expects.

Install · How to use · FAQ · Philosophy

---

v0.2 migration for existing installs

Beislið v0.2 starts from a clean repository history. If you installed v0.1.x, do a one-time migration from a fresh v0.2 checkout instead of git pull:

mv ~/Projects/beislid ~/Projects/beislid-pre-v0.2-archive
git clone git@github.com:sandsower/beislid.git ~/Projects/beislid
~/Projects/beislid/install.sh --migrate-v0.2

The migration reads the previous install manifest, removes only old Beislið symlinks that point into the previous checkout, preserves install targets and opt-ins, and reinstalls from the new checkout. It never deletes the old checkout or clobbers regular files.

New installs can skip this and use the normal install below.

What this is

Beislið (/ˈpeislɪð/, "BASE-tlith", Icelandic for "the harness") is a workflow harness for coding agents.

It installs portable Markdown skills, but the skills act only as the interface. The product is the lifecycle: shared gates, repo-local config, verification evidence, review loops, and human-in-the-loop checkpoints.

spec → blueprint → implement → verify → review → ready-for-review

Project workflow lives in .beislid/workflow.md, so a repo can declare its own ticket sources, branch patterns, quality gates, lifecycle actions, lifecycle hooks, PR review sources, and PR handoff rules.

Who it is for

Beislið is for developers and teams who want agent-assisted work to be disciplined and reviewable:

• Senior developers who want a repeatable personal workflow instead of one-off prompting.
• Tech leads and staff engineers who want agents in a repo to follow shared team process.
• Teams that need explicit gates before code, claims, review risk, pushes, comments, or PR creation.

It is not a fully autonomous coding mode, a replacement for CI, or a replacement for human review.

Why it feels different

Step	What it prevents
spec / kickoff	building the wrong thing from vague requirements
blueprint	coding before the approach is named and approved
implement	wandering through a large change without a file-level plan
verify	claiming done before fresh evidence exists
review / fresh-eyes	handing off with obvious local findings, drift, or stale docs
ready-for-review	opening a PR before gates, optional clean eval, review, and release notes are ready

60-second start

Install Beislið:

git clone git@github.com:sandsower/beislid.git ~/Projects/beislid
~/Projects/beislid/install.sh

The installer also links the beislid CLI into ${BEISLID_BIN_DIR:-~/.local/bin}. If that directory is not on PATH, add it or run the checkout's bin/beislid directly.

Then open a project repo and pick the right entry point:

Situation	Start with
Vague idea or unclear product behavior	spec
Existing ticket or branch	kickoff
Clear requirement, unknown implementation	blueprint
Bug, failing test, or unexpected behavior	debug
Work is done but not proven	verify
Branch is ready for PR	ready-for-review
PR review or QA feedback came back	review-response
Open PR needs babysitting through CI/review	babysit

For repo-aware ticket, PR, and quality-gate workflows, configure the project first:

setup → doctor → kickoff or ready-for-review

Basic skills work after install. Repo-aware orchestrators such as kickoff, ready-for-review, review-response, and babysit need .beislid/workflow.md when they must read tickets, run configured gates, or interact with PR review sources. babysit also requires host goal support: Claude includes /goal; Pi users need the pi-goal package enabled.

See How to use for more information.

Bootstrap a repo

Fresh sessions should read .beislid/workflow.md first, then choose the first Beislið skill from the repo state:

• Existing ticket or branch → kickoff
• Clear requirements, implementation still undecided → blueprint
• Work is done but not yet proven → verify
• Branch is ready for PR → ready-for-review

This repo includes a matching AGENTS.md bootstrap block you can copy into project repos.

Repo-local workflow

Beislið keeps project policy in the repo:

<repo>/.beislid/workflow.md

Use setup to create or update it. Use doctor to audit it and probe configured capabilities.

A workflow can define:

• issue tracker source and branch pattern
• PR target and review source
• ticket or PR update commands
• scopes and quality gates
• PR babysitting and optional closeout automation
• triggered checks such as translation sync or browser compatibility
• guided walkthrough thresholds

See Configuration for details and workflow.md format for the full grammar.

Optional Lavish visual surfaces

Lavish is an optional supplemental visual-surface provider for planning/review loops. Markdown/chat artifacts remain canonical: enabling the user plugin does not activate any workflow by itself, and every Beislið workflow must continue through its normal Markdown/chat gates when Lavish is unavailable.

To discover and prepare the local plugin path:

beislid plugin enable lavish
beislid plugin status lavish

beislid plugin status lavish is a light check only. Add --check only when you intentionally want to invoke the configured Lavish command, which may touch npm, network, and the local package cache when the command is the default npx -y lavish-axi. Environments that need a pinned or local runtime can use beislid plugin enable lavish --command 'path/to/lavish-axi'.

Repo-level routing is configured separately with beislid:visual_surfaces in .beislid/workflow.md; see Configuration for modes, fallbacks, troubleshooting, the Beislið/Lavish ownership boundary, conservative blueprint/poke-holes planning surfaces, Show Me deck routing, artifact retention, and typed BEISLID_VISUAL_FEEDBACK_V1 handling. show-me decks remain portable local artifacts; Lavish wrappers under .lavish/ are supplemental and ignored unless a workflow explicitly opts into preserve-repo with an intentional gitignore exception (for example, publishing a docs/example artifact). Typed gate feedback is distinct from freeform annotations; unknown, malformed, or freeform-only visual feedback falls back to manual Markdown/chat review; visual choices are copied into canonical Markdown/chat records and do not approve implementation by themselves.

Core workflows

Lifecycle artifact templates are standardized in .beislid/artifact-templates.md: spec, blueprint, implementation plan, verification report, review report, fresh-eyes report, ship summary, and feedback response log. Planning/proof/review records stay local or in chat by default; ticket/PR surfaces get concise summaries or configured replies.

• Shape work: spec, break-spec, blueprint, poke-holes
• Execute safely: implement, debug, handoff
• Check evidence: verify, review, fresh-eyes, rinse, show-me
• Deliver work: ready-for-review, review-response, babysit, pr-patrol, walk-the-diff
• Manage config: setup, doctor, retro

See Skills for the full catalog and Workflows for lifecycle diagrams. For guidance on writing your own skills, see Skill authoring.

Install

git clone git@github.com:sandsower/beislid.git ~/Projects/beislid
~/Projects/beislid/install.sh

Symlinks land in:

• ~/.agents/skills/<name>
• ~/.claude/skills/<name>
• ~/.codex/skills/<name>
• ${BEISLID_BIN_DIR:-~/.local/bin}/beislid

Edit the repo to edit the skills. When Beislið probes for a named project skill, repo-local .beislid/skills/<name> takes priority, then $BEISLID_SKILLS_DIRS, then the global host skill dirs above.

CLI commands available now:

beislid install user [--strict]
beislid install project [path] [--copy] [--strict]
beislid repair user [--force] [--strict]
beislid repair project [path] [--force] [--strict]
beislid status
beislid status project [path]
beislid plugin enable lavish [--command COMMAND] [--artifact-root PATH]
beislid plugin disable lavish
beislid plugin status lavish [--check]
beislid workflow normalize --json
beislid resource resolve <name>
beislid workflow-signal status
beislid workflow-signal emit waiting --skill ready-for-review
beislid visual-feedback normalize [feedback-file]
beislid update
beislid migrate v0.2
beislid help

Project install defaults to symlink mode. Use beislid install project [path] --copy when the project needs portable local copies instead. Add --strict when you want the command to exit nonzero on skipped or conflicted expected artifacts; it still never clobbers unowned files or directories. With no path, beislid install project targets the git root when run inside a git repo; outside git it targets the current directory and warns. An explicit path is used exactly, even when it sits inside a larger repo. The installer creates all three project-local host dirs:

• <project>/.agents/skills
• <project>/.claude/skills
• <project>/.codex/skills

It writes <project>/.beislid/project-install.json and warns softly when <project>/.beislid/workflow.md is missing. Copy mode also writes .beislid-owner.json inside each copied skill dir so reruns can refresh only Beislið-owned copies. Unmarked project files or skill dirs are never clobbered, even with --force. beislid repair project [path] restores an existing project install without guessing a mode or rewriting .gitignore; use install project when you are bootstrapping or intentionally changing install options. beislid status project [path] reports missing skills per host and exits non-zero when any supported host is missing a skill. Project installs print a suggested .gitignore block by default; pass --write-gitignore to create or replace the managed block idempotently. It does not create workflow config; run the setup skill when repo-aware workflows need it.

Update an existing install from an agent host:

/setup update

Or from the Beislið checkout / CLI:

~/Projects/beislid/install.sh --update
beislid update

Update fast-forwards the checkout with git pull --ff-only, aborts if the checkout has uncommitted local changes, preserves prior manifest install targets and opt-ins such as security hooks, then relinks skills/hooks as needed.

For the v0.1.x → v0.2 history reset only, use the migration command from a fresh v0.2 checkout:

~/Projects/beislid/install.sh --migrate-v0.2
# or, once the v0.2 CLI is on PATH:
beislid migrate v0.2

Flags:

• --with-security-hooks: enable credential_guard for Claude Code
• --strict: exit nonzero when expected artifacts are skipped or conflicted during install
• repair user: restore the user install from the current checkout and preserved manifest targets
• repair project [path]: restore an existing project install in symlink or copy mode
• --update: fast-forward the Beislið checkout and re-run install
• --migrate-v0.2: one-time migration from pre-v0.2 installs after cloning the clean v0.2 history
• --status: print installed commit and symlink status
• --project [path]: compatibility sugar for a project install via install.sh
• --copy: copy project-local skills instead of symlinking them
• --write-gitignore: create or replace the managed project .gitignore block
• --force: repoint/replace existing symlinks. Never clobbers unmarked regular files or directories.

Machine state for user installs lives at ${BEISLID_STATE_DIR:-~/.local/state/beislid}/install.json and records the CLI path when the CLI link is installed or already correct. Durable run-ledger state lives under ${BEISLID_STATE_DIR:-~/.local/state/beislid}/runs/<flow>/<repo_hash>/<run_id>/ and can be managed with beislid run-ledger ... for Rondo-style runs, gate logs, interruptions, and final reports. Project install state lives at <project>/.beislid/project-install.json. Re-running is safe: dangling symlinks are auto-repaired; symlinks pointing at another live target are left alone unless you pass --force. Regular files are never clobbered. Update never touches project-owned .beislid/workflow.md files.

Homebrew packaging

This repo includes the Homebrew formula at packaging/homebrew/beislid.rb. It packages the runtime subset under libexec, including .beislid/, and exposes beislid on PATH. Homebrew users update with brew upgrade beislid; source-checkout installs update with beislid update / install.sh --update.

The formula is maintained in this repo as the release source of truth.

Release/update process:

1. Update packaging/homebrew/beislid.rb in the same change as any runtime-layout or CLI packaging change.
2. Run the install integration suite and a local formula sanity check before release.
3. Publish the tap/release that carries the updated formula.
4. Users upgrade with brew upgrade beislid after the new tap/release lands.

The CLI is package-layout friendly: it resolves its runtime from the real bin/beislid path, or from BEISLID_HOME when a packaged wrapper points at a separate runtime root. If the runtime subset is incomplete, it prints a layout error instead of failing with a shell source error.

Invocation

Invocation syntax depends on the host.

• Use the short skill name when your host supports direct invocation: spec, blueprint, ready-for-review.
• Use slash syntax when your host exposes skills that way: /spec, /blueprint, /ready-for-review.
• Use namespaced syntax when your host requires it: /skill:spec, /skill:blueprint.
• Natural-language triggers work in some agents, but direct invocation is safest when a gate matters.

When installed as a Pi package, Beislið includes a Pi extension that registers managed slash-command wrappers for the skill surface. Boundary workflows can automatically start a fresh Pi session from a readable checkpoint pointer and continue with a pointer-only prompt. Repo intent is configured with beislid:pi_handoff; local Pi settings are the final override. Claude and other hosts keep the existing manual checkpoint guidance.

Docs

• How to use: first-run guide and common paths.
• Workflows: lifecycle diagrams and routing rules.
• Skills: full skill catalog.
• Configuration: setup, doctor, .beislid/workflow.md, scopes, gates, lifecycle hooks, and probe cache.
• Workflow authoring: how to write and test .beislid/workflow.md for your team.
• Team rollout: minimum viable repo config, strictness layers, and the AGENTS.md block for Beislið-ready repos.
• Example team workflow configurations: seven complete drop-in configs for common team shapes.
• Skill authoring: how to write portable custom skills with hard gates, clear triggers, and host portability.
• Review workflows: review primitives and review/PR handoff/feedback flows.
• FAQ: positioning, comparisons, autonomy, team use, and philosophy.
• Show Me: local HTML evidence and explanation decks.
• Credential guard: optional Claude Code hook for blocking secret-dumping commands.

Optional integrations

• credential_guard hook: blocks bash commands that dump secrets. Claude Code-specific; the skills themselves are portable markdown.
• Beislið Pi extension: managed slash-command wrappers for Beislið skills plus automatic fresh-session handoff from checkpoint pointers when configured.
• workflow_signals: optional local workflow-state fan-out; v1 can drive tmux-glance tab markers through beislid workflow-signal when configured.

Philosophy

1. Shape unclear product work before implementation design.
2. Design before code. No implementation until the approach is named and approved.
3. Evidence before claims. No "should work" or "probably fixes". Run it, verify, then submit it for review.
4. Root cause before fix. Guessing is rejected. Understand the bug before proposing a patch.
5. Keep the human in the loop. Agents can do the work, but people own product direction, risk, review, and release.

Credits

Several Beislið skills draw from Matt Pocock's mattpocock/skills, especially:

• poke-holes, based on Matt's grill-me (renamed to disambiguate from elicitation; in Beislið it pressure-tests an existing plan or design rather than extracting requirements from scratch).
• spec / break-spec, which overlap with Matt's to-prd and to-issues.
• implement, which shares the test-first / vertical-slice philosophy of Matt's tdd.

Beislið diverges by keeping skills agent-agnostic, installing under short unprefixed names, using a local installer/manifest, and organizing the workflow around repo-local project configuration.

Contributing

See CONTRIBUTING.md.

License

MIT