emkeel 0.1.43

Adopt-and-thin SDLC governance framework

Emkeel

SDLC governance for AI-assisted teams, built on GitHub + Jira. Emkeel turns a repo into a governed project: every change flows ticket → branch → PR → deterministic CI gates → human-approved merge → the ticket closes itself. "done" is a computed fact (a check passes), never a self-attested flag — enforcement lives server-side (GitHub Actions + branch protection), out of the agent's reach.

Built for GitHub + Jira. If your team isn't on both, Emkeel isn't for you (yet).

Prerequisites (set these up first)

Need	Where	Notes
GitHub account + a repo	new repo → https://github.com/new	or use one you already have
GitHub CLI gh, authenticated	https://cli.github.com → then run gh auth login	also sets up your git push/pull auth (SSH or HTTPS) — no separate SSH setup needed
Jira Cloud account	https://www.atlassian.com/software/jira	your tickets live here
Jira API token	https://id.atlassian.net/manage-profile/security/api-tokens	you paste it into a hidden prompt; Emkeel verifies it before saving
Python 3.11+	https://www.python.org/downloads	Emkeel has zero other deps

1. Install Emkeel (per platform)

Only this step differs by OS.

Platform	Command
Windows	py -m pip install --user pipx → py -m pipx ensurepath → pipx install emkeel
macOS	brew install pipx → pipx install emkeel
Linux (admin/sudo)	sudo apt install pipx → pipx install emkeel
Linux/server, no sudo	pip install --user --break-system-packages emkeel (safe — zero deps)

Confirm: emkeel version.

2. Set up your repo

First, open a terminal:

• VS Code / Cursor: menu Terminal → New Terminal (or Ctrl+`).
• Or your OS terminal: Linux Ctrl+Alt+T · macOS Terminal.app · Windows PowerShell.

The wizard then guides you in your language (Spanish/English) and confirms before each step (c cancels). Pick your path:

A · You already have a repo

cd my-project
emkeel setup

1. Choose language (Español / English).
2. Choose "Existing repo".
3. Confirm your GitHub repo + Jira (auto-detected — Enter to accept).
4. Enter a Jira key for the branch → it creates chore/<KEY>-adopt-emkeel + Emkeel's files + commit.
5. "Connect now?" → yes: branch protection (require the gates check + PRs) + Jira secrets (email + token verified before saving, hidden).
6. "Finish the adopt?" → yes: push → open the PR → auto-merge when the gates pass → sync your local.

✅ Your repo is governed (via a merged PR).

B · New project (from scratch)

mkdir my-app && cd my-app
emkeel setup

1. Choose language.
2. Choose "New project".
3. Type your GitHub repo (owner/repo) + Jira → it runs git init + Emkeel's files + commit.
4. "Connect now?" → yes: it creates the GitHub repo and pushes it (gh repo create) + branch protection + Jira secrets (verified).

✅ Your new repo is live on GitHub, governed.

Check what's set up / still pending anytime: emkeel doctor. Scripted instead? emkeel init (non-interactive) · emkeel connect / emkeel sync standalone.

3. Remove Emkeel

Order matters: un-govern the repo first, then uninstall the tool. Open a terminal (see §2).

Step 1 — Un-govern a repo (emkeel eject)

cd my-project
emkeel eject

1. Choose language.
2. Answer 3 yes/no questions: remove the wiring? (the basics) · also emkeel-governance/? · also the GitHub side? (branch protection + secrets + push the removal).
3. Review the summary → confirm.

(Scripting/CI? emkeel eject --help shows the non-interactive flags.)

Step 2 — Uninstall the tool

pipx uninstall emkeel

Uninstalling the tool ≠ un-governing your repos. If you only pipx uninstall emkeel, your repos' governance keeps working (their CI installs Emkeel from PyPI) — you just can't run the local emkeel commands to change it. To remove everything: emkeel eject in each repo first, then pipx uninstall emkeel.

4. All commands (by use)

Set up / adopt

Command	What it does
emkeel setup	interactive wizard (recommended — does everything)
emkeel connect	just the GitHub side (branch protection + secrets), standalone
emkeel init .	scaffold non-interactively (for scripts/CI)
emkeel onboard	print the AI-assisted onboarding playbook

Check / maintain

Command	What it does
emkeel doctor	what's set up / what's pending (with fix links)
emkeel sync	after a merge: checkout default + pull + drop the merged branch
emkeel review <KEY>	per-criterion review template for a ticket
emkeel version	installed version (+ flags a newer one on PyPI)

Remove

Command	What it does
emkeel eject (alias emkeel uninstall)	un-govern the repo — interactive, asks what to remove (--help for CI flags)
pipx uninstall emkeel	remove the tool from your machine

Tool

Command	What it does
pipx upgrade emkeel	update Emkeel

Updates are safe: your repo's CI pins emkeel~=0.MINOR.0 — auto patches/minors; a breaking major is opt-in.

What you get

• Deterministic CI gates (server-side, can't be skipped): every change links a ticket; features carry a spec with acceptance criteria; the full test suite runs on every PR.
• Auto-close — merging a PR moves the linked Jira ticket to Done.
• AI review-assist — a per-criterion verdict against the spec before you merge.
• Clean separation — governance artifacts live in one emkeel-governance/ folder, never shipped.

See docs/lifecycle.md for the model.

---

Licensed under Apache-2.0 — © 2026 EMillion Networking LTD (see LICENSE / NOTICE).