Beislið

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

Install · How to use · FAQ · Philosophy

---

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 → ship-it

Project workflow lives in .beislid/workflow.md, so a repo can declare its own ticket sources, branch patterns, quality gates, PR review sources, and shipping 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	shipping with obvious local findings, drift, or stale docs
ship-it	opening a PR before gates, 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	ship-it
PR review or QA feedback came back	heard-chef

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

setup → doctor → kickoff or ship-it

Basic skills work after install. Repo-aware orchestrators such as kickoff, ship-it, and heard-chef need .beislid/workflow.md when they must read tickets, run configured gates, or interact with PR review sources.

See How to use for more information.

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
• triggered checks such as translation sync or browser compatibility
• guided walkthrough thresholds

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

Core workflows

• Shape work: spec, break-spec, blueprint, poke-holes
• Execute safely: implement, debug, handoff
• Check evidence: verify, review, fresh-eyes, rinse, show-me
• Deliver work: ship-it, heard-chef, pr-patrol, walk-the-diff
• Manage config: setup, doctor

See Skills for the full catalog and Workflows for lifecycle diagrams.

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.

CLI commands available now:

beislid install user
beislid install project [path]
beislid status
beislid status project [path]
beislid update
beislid help

Project install defaults to symlink mode. Use beislid install project [path] --copy when the project needs portable local copies instead. 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. 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 and Pi show-me, then relinks skills/hooks as needed.

Flags:

• --with-security-hooks: enable credential_guard for Claude Code
• --with-pi-show-me: install the Pi extension for show-me
• --update: fast-forward the Beislið checkout and re-run install
• --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. 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 draft

This repo includes a draft formula at packaging/homebrew/beislid.rb. It is for packaging validation and future tap work, not the published install path yet. Full Homebrew support, including publishing and upgrade policy, is tracked in #67.

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, ship-it.
• Use slash syntax when your host exposes skills that way: /spec, /blueprint, /ship-it.
• 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.

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, and probe cache.
• Review workflows: review primitives and review/ship/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.
• show-me Pi extension: typed deck-builder tools, command evidence capture, asset ingestion, browser screenshots when Playwright is installed, and /show-me doctor|list|open|clean. The portable skill still works without Pi.

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