joseconti/keel-skill/keel

Keel — project lifecycle (idea → release)

Keel v7.5.0 — Licensed under GPL-3.0-or-later. Keel is the structural backbone laid down first, on which the whole project is built.

Skill maintenance — update check & version policy (RUN FIRST, NON-BLOCKING)

Once per session, when Keel is invoked and before the entry-mode decision, load references/keel-maintenance.md and execute it. It defines the release update check (throttled to one remote lookup per 24 hours via the machine-local .keel-update-check stamp), the multi-copy comparison and verified-replacement procedure, the post-update reconciliation trigger, the lock-freshness check (CLAUDE.md + AGENTS.md), and version reporting. In a Keel project's repo the portability lock makes the full read of this SKILL.md its step 1, and this block routes straight there — so the checks run in every session, whether or not the skill auto-triggered. Start it first, then carry on: if any step fails or the remote lookup does not answer promptly, skip it silently, continue on the running version, and do not retry in this session (the full rule is in references/keel-maintenance.md). The user's work never waits on it.

Version change policy (UNBREAKABLE): Keel's own version — metadata.version in the frontmatter, the heading above, CHANGELOG.md, and the MANIFEST.md header — is NEVER changed, and no changelog entry is ever added, without the user's explicit instruction in the current conversation. Nothing else counts: not the scale of the edits, not semver conventions, not gratitude, not a past conversation. If a bump seems warranted, propose a specific number and WAIT. The full policy, including what does and does not count as authorisation, lives in references/keel-maintenance.md — but this paragraph is binding on its own.

Session start setup — four questions, one batch, settled once (RUN FIRST, with the maintenance block)

Immediately after the maintenance block and before the entry-mode decision, Keel settles where the work will survive, how it is allowed to work, and how it reaches the developer. The four questions go out in ONE batch — never separately — and every answer is recorded on the project card (Durability:, Autonomy:, Notify:) plus a D-entry, so no later session asks again. On a project that already carries those lines nothing is asked: the recorded answers are applied and the session says in one line what it applied. Question 0 is the exception to "settled once": its recorded ANSWER is never re-asked, but the two mechanical facts behind it — a repository exists, and it has a remote or the tree sits inside a synced folder — are re-checked every session, because a remote can be removed and a folder can be moved out of sync without anyone noticing.

Question 0 — where does this work survive, if this machine does not? Asked FIRST, before anything is created, because it decides whether the rest of the session's output exists in one place or two. Keel looks before it asks: is there a repository (git rev-parse --git-dir), does it have a remote (git remote -v), and does the project path sit inside a synced folder (Dropbox, iCloud Drive, Google Drive, OneDrive, pCloud, Sync, Nextcloud, or a network/backup mount the user names)? Then it states what it found in one line and recommends the fix for what is missing. The full rule, the recommendations and what happens when the user declines are in "Work never lives only on this machine" below; the answer lands on the project card's Durability: line.

Question 1 — automatic mode: yes or no? This is the person's call and it is the hinge the rest of the session hangs on, so it is asked first and its consequences are stated in the same breath. Explain the problem in one line: in manual — Claude Code's default — a command is matched STATICALLY against the allow rules, so anything composite (a shell variable, a &&, a ;, a pipe) opens a dialog even when every command inside it is allowed, and Keel's phases are made of exactly those commands; the result is not slower work, it is stopped work.

• If the answer is yes (automatic): Keel creates or MERGES .claude/settings.local.json at the repo root — permissions.defaultMode: "auto", a minimal deny block, env.PATH — announces in one line that it did, and asks nothing further about it. Merging never removes or reorders a rule the user put there. Writing needs no second permission because the file is machine-local and gitignored: it binds this checkout and nobody else. This is the single exception to "Keel never creates a personal config file"; the COMMITTED .claude/settings.json is untouched and still requires explicit confirmation per references/assistant-config.md. Where the user wants automatic mode but no file written, the per-session route is equivalent and vanishes with the session — claude --permission-mode auto, or Shift+Tab until the mode reads auto — say that rather than letting them find out.

In automatic mode Keel does not ask and Keel pushes. git push is deliberately NOT in the file's ask list: pushing is the assistant's own duty (see "Git flow" below), and a dialog on every push reinstates exactly the queue of unpushed commits that rule abolishes. Control over what reaches users sits at the develop → main merge, which Keel never performs.

• If the answer is no: the mode stays as it is and the opposite regime applies in full — Keel asks, every time, and pushes nothing that was not explicitly asked for. No settings file is written. Work is still committed and branches still follow the flow below, but each push waits for the user to request it, and the resulting local commits are named in docs/PROGRESS.md so nothing is silently stranded. Say plainly what this costs: dialogs throughout, and long unattended stretches will not happen.
• Whenever Claude Code is in use — the running session, or an accepted tool on the card — Keel ALWAYS ensures `env.CLAUDE_CODE_EXPERIMENTAL_AGENTS_TEAMS: "1"` in `.claude/settings.local.json`, whatever question 1 was answered. It switches on Claude Code's agent teams, the native orchestration the parallel-development contract can use (references/parallel-development.md). It is not a question and not a permission: it grants no tool, widens no mode and pushes nothing, so a "no" to question 1 still gets this one key — and only this key — merged in, announced in one line. The procedure is in references/keel-maintenance.md ("Agent teams flag").
• Verify `.claude/settings.local.json` is in `.gitignore` either way; if not, add it (already an unconditional entry).
• Hygiene that follows from `env.PATH`: Keel never prefixes a command with export PATH=... && .... That prefix ALONE makes the command composite, forcing a dialog on every single call — the exact problem this step removes.

Question 2 — forge issues: the after-sprint duty. Should Keel review the project's issues at every sprint close — new arrivals triaged into docs/issues.md, and issues whose fix has landed answered on the forge? Answering is publishing — a third party reads it — so the mechanics are fixed and not negotiable per project: Keel comments, Keel notifies the developer when a deploy is needed for the reporter to test, Keel comments again when it is testable, and Keel never closes an issue on its own reading of the code. The same duty also guards the other edge: a sprint kickoff opening more than Issue sweep interval: after docs/issues.md's last sweep runs that same inbound check before the sprint is planned, so a gap of days between sprints never leaves a fresh report or an awaiting reporter reply sitting unread until the next close. If accepted, ask the interval too — default 24h, changeable per project — and record it beside the duty on the card. Full three-beat lifecycle and the kickoff sweep in references/project-state.md ("docs/issues.md"), the kickoff step in references/phase-5-development.md ("Sprint kickoff"), and references/notifications.md.

Question 2b — issue capture: should a problem YOU report become a forge issue? Asked in the same batch, and only where the project has a forge. Today a defect the user reports in conversation is worked and disappears: what was wrong, what it turned out to be and how it was fixed exist in the chat and nowhere a person can find them in six months. With capture on, Keel opens the issue on the forge BEFORE starting the work — so the record exists even if the session dies mid-fix — works it, and comments on it as the work advances, exactly like an issue anyone else filed. Ask it; never assume it. A tracker is a public, shared surface, and filling somebody's with entries they did not ask for is not a favour — some projects want every defect traceable, others keep their tracker for third-party reports and would find this noise. Record the answer on the card as Issue capture: on|off|n/a no forge. Mechanics, and the one case that must not produce a duplicate, in references/project-state.md ("docs/issues.md").

Question 3 — out-of-band notification: how does Keel reach you when it stops? A blocked session and a working session look identical from outside, which turns a thirty-second question into a lost afternoon. Keel probes what this session can actually deliver with, offers only what answered, and asks for the recipient explicitly — never inferring an address from git config or commit history. A channel counts only if it DELIVERS: a connector that composes drafts but cannot send is recorded as compose-only and is not a notification. If nothing delivers, the session says so plainly, so the user knows silence means silence. Full protocol in references/notifications.md.

File contents and merge rules live in references/keel-maintenance.md ("Permission mode"); the channel probe and the notification triggers in references/notifications.md; the doctor's advisory rows in references/test-automation.md.

Work never lives only on this machine (cross-cutting, UNBREAKABLE)

A disk fails, a laptop is stolen, a folder is deleted by the wrong rm — and a project that existed in exactly one place is simply gone, along with every decision, every artifact and every hour that went into it. This is not a release-time concern and it is not the user's problem to remember: from the first file Keel writes, the work must exist somewhere other than this computer. The requirement is checked at session start (Question 0 of the setup batch), it is checked again before Keel creates anything in a new location, and its state lives on the project card's Durability: line.

Two things satisfy it, and Keel checks both:

1. A Git repository with a remote — the preferred form by a wide margin, because it also gives history, branches and the whole flow below. git rev-parse --git-dir says whether there is a repo; git remote -v says whether it reaches anywhere.
2. A location that replicates off the machine — Dropbox, iCloud Drive, Google Drive, OneDrive, pCloud, Sync, Nextcloud, a network volume, or a real backup the user names. Detected from the project's absolute path plus what the user states; Keel never assumes a folder is synced because its name looks like it.