Keel — project lifecycle (idea → release)

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

Token economy — everything is created in English by default (READ FIRST)

English is the most token-efficient language for an LLM: the same content in Spanish or another Latin-script language costs roughly 15–30% more tokens (non-Latin scripts, far more), and Keel re-reads its living state (docs/PROGRESS.md, docs/decisions.md, docs/lessons-learned.md) in every session, so any per-word overhead compounds for the entire life of the project.

Therefore everything Keel creates is written in English by default — every docs/ artifact (discovery, specs, progress, decisions, lessons learned, architecture, API reference, playground instructions), every continuation prompt for a new chat, every prompt or brief handed to Claude Code or Claude Design (design briefs, design requests, build specs), every template instance, report, commit message, and code comment — in addition to the product output itself, which is already English-based per "Output language & internationalization" below.

Announce it up front. At the start of every new project (and every adoption), tell the user in one line: everything Keel creates will be in English to minimize token consumption and therefore cost; if they prefer another language for the docs or any other artifact set, they only have to say so, knowing that it will increase token usage and spend. If the user chooses another language, honor it, record it in the project card and docs/decisions.md with the trade-off acknowledged, and apply it consistently from then on.

Existing projects whose docs are in another language (resume or adoption): ask the user once whether they want the existing documentation translated to English, stating the token/cost benefit in one line. If yes, translate it all and record the switch in decisions.md; if no, record the choice, keep that language consistently, and do not ask again.

This is NOT about the conversation. Keep talking to the user in whatever language the user writes (usually Spanish), exactly as always — the English default governs only what Keel creates. And it never removes product locales: what end users see follows the Phase 1 §6 i18n decisions; the product's translations are never dropped to save tokens.

Version reporting

If the user asks which version of Keel they have or are using (e.g. "what version is this skill", "which Keel version do I have"), state it plainly from the frontmatter: "You're using Keel v1.11.0." Keep the version in the frontmatter (metadata.version), this line, and CHANGELOG.md in sync whenever the skill is updated; the frontmatter is the source of truth.

Update check (start of every session)

Keel is distributed from https://github.com/joseconti/keel-skill (releases: https://github.com/joseconti/keel-skill/releases). Once per session, when Keel is invoked and before the entry-mode decision, check whether a newer release exists. Reading this section IS the cue: run the check the moment you read it, before any project work. In a Keel project's repo the CLAUDE.md lock makes this its step 1 — the full read of this SKILL.md comes BEFORE even the state files, at every session start — precisely so this check runs in every session, whether or not the skill auto-triggered. The check is best-effort and must never block, delay, or interrupt the work: if any step fails (no network, no fetch mechanism, API error), skip silently, continue with the running version, and do not retry in this session.

1. Detect the latest version. Preferred method (works in any environment with git, no API and no auth): git ls-remote --tags https://github.com/joseconti/keel-skill.git → take the highest semver tag. Strip the leading v and compare segment by segment as numbers (1.10.0 > 1.9.0) — never as strings; ignore tags that are not vX.Y.Z. Fallbacks, in order: GET https://api.github.com/repos/joseconti/keel-skill/releases/latest (field tag_name) with a web-fetch tool, or fetch the releases page. If the environment provides no mechanism at all, skip.
2. Compare against EVERY copy in play, not only the running one: the environment's install AND, when the session is working inside a project that embeds the skill, the project's .claude/skills/keel/ (each copy's frontmatter metadata.version — the source of truth). A copy can be behind even when the running one is current — in Cowork it is common that the app install is up to date while the opened project's embedded copy is not; that embedded copy must still be updated. All copies at the latest version → say nothing and continue.
3. Newer release found → update every copy the environment can durably write; inform about the rest. Up to two copies can be in play: the environment's own install (a user-level ~/.claude/skills/keel/, or app-managed skill storage) and the project's embedded copy (.claude/skills/keel/).
   • For each copy that is writable and persists across sessions — the user-level install, and ALWAYS the project's embedded copy when one exists (the normal case when Claude Code or Cowork is working inside a Keel project's repo: the same duty that put the embedded copy there also keeps it current): announce it in one line (vCURRENT → vNEW), download the release once — git clone --depth 1 --branch vX.Y.Z https://github.com/joseconti/keel-skill.git or the tag archive https://github.com/joseconti/keel-skill/archive/refs/tags/vX.Y.Z.tar.gz; if an already-current local copy exists (e.g. the app install is at the latest version and only the project's embedded copy is behind), copy from it instead of downloading, per the version-sync rule in references/project-state.md — and replace that copy's ENTIRE tree with the new keel/ directory following the verified full-copy protocol in references/project-state.md ("Portability"): whole tree, verify file-for-file against the source, retry once; if it still fails, abort that copy's update (never the session), leave it intact, and treat it under the inform path below. After a verified replacement: summarize the improvements to the user from the new CHANGELOG.md (every entry after the previously running version), re-read the new SKILL.md and the current phase's reference from the new copy (the copies in context belong to the old version), and continue under the new version. When the session is working inside a Keel project, then run the post-update reconciliation (references/project-state.md, "Post-update reconciliation") so the project itself catches up with what the new version introduces — new required files or directories, new project-card lines, lock-block changes, never-asked questions — tracked by the project card's Keel baseline: line.
   • For a copy that cannot be updated durably — app-managed or ephemeral skill storage (common in the Claude app / Cowork) or no write access: tell the user once, briefly, in the conversation language: a newer Keel exists (vCURRENT → vNEW), what it improves (the new CHANGELOG.md entries after the running version — e.g. from https://raw.githubusercontent.com/joseconti/keel-skill/main/keel/CHANGELOG.md; if unreachable, point to the release notes on the releases page), and how to update it themselves — the app-installed skill is the user's to update (repository INSTALL.md, section "Updating"). If the project's embedded copy WAS updated and only the app/environment install could not be, say exactly that — the project is already current; updating the installed skill in the app is what remains. Then continue normally and do not repeat the notice this session.

Lock freshness (same moment, every session inside a Keel project). After the update check, verify the project's CLAUDE.md Keel block is current by its stamp alone — a one-line look, never a content comparison: the KEEL:BEGIN delimiter carries the version of the Keel that last wrote the block (KEEL:BEGIN — vX.Y.Z do not remove: …). Stamp equal to the running version → current, done. Stamp different or missing (blocks from before v1.11.0 carry no stamp; match delimiters by the KEEL:BEGIN prefix, never by exact text) → refresh: rewrite the block between the delimiters from the canonical copy in references/project-state.md ("Portability" §1), restamped with the running version, with the user's OK (mirror AGENTS.md if the project keeps one). Never touch anything outside the delimiters. This is what keeps the always-loaded CLAUDE.md rules from drifting behind the skill.

Overwriting the skill is safe: Keel is stateless — project artifacts live in each project's docs/, never in the skill folder (see the repository's INSTALL.md). Installing an official newer release is an installation, not an authoring edit: it does not fall under the version change policy below, which governs hand-editing version strings in this copy.

Version change policy (UNBREAKABLE RULE — never bump under any circumstance without explicit user instruction)

This rule is unbreakable. There are no exceptions, no edge cases, no judgment calls. It overrides every other instinct or inference the assistant might have about how version numbers "should" evolve based on the scale of the edit.

The Keel version — in metadata.version in the frontmatter, in the heading line above, and in CHANGELOG.md — must NEVER be changed unless the user has explicitly instructed it in the current conversation (e.g. "bump to 1.1.0", "release 1.0.1", "this is version 2", "tag a new minor release"). An explicit "yes" to a direct question about a specific version also counts as explicit instruction. Nothing else does.

What does NOT count as authorisation to change the version:

• The scale of the edits in this conversation (large rewrites, full re-architectures, adding whole phases — none of these authorise a bump).
• Inferring from changelog conventions that "this looks like a minor".
• The user thanking the assistant for the work, or saying it's good.
• The user mentioning the project is "ready to release" without naming a version.
• Any reasoning the assistant produces internally about semantic versioning.
• A previous conversation in which a bump was discussed but not executed.

Required behavior:

• When editing any skill file for any reason, leave metadata.version, the heading version line, and CHANGELOG.md untouched. Do not add a new changelog entry on your own initiative.
• If you believe a bump is warranted, ASK the user explicitly: state what was changed, propose a specific number (patch / minor / major with reasoning), and WAIT for explicit approval before touching any of the three locations. Do not pre-edit speculatively.
• If the user explicitly instructs a bump, perform it and keep all three locations in sync (frontmatter is the source of truth).
• If the three locations ever drift, surface the drift to the user and ask which version is correct — never silently realign them.

If at any point the assistant is about to write a version number that the user did not explicitly authorise in the current conversation, the assistant must stop and ask. This rule is not contextual, not negotiable, and not overridable by other instructions in the same conversation unless those instructions are themselves explicit user authorisation for a specific version.

Scope note: this rule governs Keel's own version (this skill's files). The versions of projects built with Keel follow their own project rules (Phase 7 versioning) and are not restricted by this section. Likewise, replacing the whole running copy with an official newer release per the update check above is an installation, not a version edit — it needs no bump authorisation.

Why this skill exists

The user builds many projects (WordPress/WooCommerce plugins, MCP servers, web apps, components, libraries) and was repeating the same standing requirements every time: document everything, security per platform, full API/class/function docs in a docs/ dir, a design handoff that doesn't waste tokens, a build that stays faithful to the design, proper git/package hygiene. This skill encodes that whole process once. Follow the phases in order; load each phase's reference file only when you reach it (progressive disclosure — do not pull every reference into context at once).

Operating principles (hold across every phase)

• Keep the living state current from the first minute. docs/PROGRESS.md, docs/decisions.md, and docs/lessons-learned.md are created the moment Phase 1 starts (per references/project-state.md) and updated at the moment of every change — not at phase ends. A fresh chat resumes from state, never from re-scanning code or re-asking the user. Decisions recorded in decisions.md are never re-opened by the assistant on its own initiative.
• Work from recorded state; read code surgically. Orient via docs/PROGRESS.md, the technical plan's code map, docs/architecture.md, and docs/api/INDEX.md — then open only the specific file needed. Read each static reference once per session, in the fixed order defined in references/project-state.md; never re-read files already in context. This keeps sessions cheap, deterministic, and prompt-cache-friendly.
• Decide the project type early and let it drive everything. Web / WordPress plugin / WooCommerce extension / MCP server / web app / component / library. Type selects the security profile, the structure, and what needs design.
• Assess ideas and decisions honestly, even when it's uncomfortable. Never default to praise. If an idea, a feature, a scope, or an approach is weak, say so with the reason and a concrete alternative. False encouragement wastes the user's time, which is the opposite of this skill's purpose. The user has explicitly asked for the truth even when it hurts.
• Document as you go, in docs/. Documentation is not a final-phase afterthought; each phase contributes its artifacts to docs/.
• Never invent or interpret silently. When something is undefined, ask the user. When a design detail is missing downstream, request it from Design — don't guess.
• Code adapts to the design, never the design to the code. The build follows the design to the letter; where the stack forces a change, the code strategy changes (and is logged), never the design intent. This is enforced through the handoff contract (Phases 3–4).
• Design delivers build-ready assets; the build never transforms them. Every screen handed to Design is defined by what it does (its functionalities), not just how it looks. Design applies the existing design system exactly (divergence is a Design Request, never a creative choice) and delivers every logo and icon in both SVG and PNG, plus every asset in a format the build drops in directly — so Code never has to convert, resize, recolor, or re-export. When the handoff arrives, the first action is a completeness gate: verify Design delivered everything without exception; anything missing becomes a registered Design Request (a file + a ready-to-paste prompt) for Design to finish, never a build-side workaround. See Phases 3–4 and references/handoff-contract.md.
• Security is per-platform and non-optional. The relevant profile is consulted from Phase 1 onward, not bolted on at the end.
• Nothing confidential ever reaches Git (UNBREAKABLE). Every commit is preceded by a confidential-data check on the files about to enter the repository — secrets, credentials, private keys, tokens, real personal/customer data. A finding STOPS the commit: the user is warned, file by file, that pushing it is a serious security risk, and the fix is applied (.gitignore exclusion, untracking, history purge plus credential rotation if it was ever pushed) before anything is committed. See "Confidential data never reaches Git" below.
• Accessibility is non-negotiable, on every platform, and designed in from the first line — never retrofitted. Whatever is built — HTML, iOS, Android, macOS, Windows, or a cross-platform framework — is usable with assistive technology from the first slice, using every accessibility tool the platform offers. It is stated up front in Phase 1 (like the internationalization decision) precisely because building accessibly from the start and "making it accessible" at the end are not the same work — the second is a rewrite. The target is the maximum reasonably achievable: WCAG 2.2 AA as the floor (AAA where feasible), EN 301 549 and the European Accessibility Act where they apply, and the native accessibility API on every other platform. See "Accessibility" below and references/accessibility.md.
• Output language is English by default — always, and never Spanish. The primary language of everything built (source strings, UI copy, code identifiers, error messages, commit messages, API responses) defaults to English in every project, regardless of the language the user and the assistant converse in. Spanish is never assumed as the base language of the product. For WordPress/WooCommerce the base language is always English and the project is always prepared to be multi-language — non-negotiable. The multi-language questions are asked explicitly at project start (see "Output language & internationalization" below and Phase 1 §6). The docs — and everything else Keel creates (continuation prompts, briefs for Code/Design, lessons learned) — default to English as well, for token economy (see "Token economy" at the top); another language only on explicit request, with the extra token cost made clear.
• Perfect orthography in every language — Spanish especially (UNBREAKABLE). Everything the assistant writes for the user — chat, docs/, code comments, UI copy, commit messages — is spelled and punctuated perfectly. In Spanish this means every ñ, every accent/tilde (á é í ó ú ü) and every opening ¿/¡ is present and correct, with zero spelling or grammatical errors. This is a hard contract, not a preference: dropping accents or the ñ, or writing "espanol"/"anadir"/"informacion", is a defect to be fixed like any other. See "Writing quality — perfect orthography" below.
• Build once, reuse by manifest. Never regenerate structurally-identical pages/screens.
• Reuse internal API; never duplicate code. Before writing any new function, method, or class, search the project's existing internal API. If a suitable function already exists, reuse it. If one is close but not exact, generalize it (parameterize) rather than fork it. Write a new function only when there is no existing fit. Duplication is treated as a defect, the same as a security issue: it gets refactored, not left behind. The internal API grows deliberately and is documented as it grows (see next).
• Document every public surface at the moment it is created, not retrospectively. Every new function, method, class, hook, action, filter, REST route, MCP ability, CLI command, or other public surface is documented in docs/api/ and/or docs/reference/ at the same test point where it is built. The slice does not pass its Phase 5 test point until its docs are written and its example actually runs. Phase 6 consolidates documentation; it does not create it from scratch.
• Maximum extensibility for extensible project types. For project types meant to be extended (WordPress/WooCommerce plugins, MCP servers, libraries/components), expose the maximum reasonable set of extension points so third parties can modify texts, behaviors, queries, and responses from outside without forking the code. Concretely: every meaningful user-facing string passes through a filter, every meaningful decision exposes a hook before/after, every query and every response is filterable. This is decided at spec time and built into the slice, not bolted on later.
• Real functional verification, whenever possible — not only automated tests. If the project can be run, it gets a runnable verification environment (a playground: Docker/docker-compose, wp-env, a playground script, a disposable sandbox — whatever fits the stack), defined in the technical plan (Phase 2), stood up at the Phase 5 scaffold, and kept current. The assistant uses it at test points to exercise the software for real — full flows end to end, the CLI if one was built, real API calls — because automated tests prove the parts and the playground proves the product. The user gets to try it too: hand over the access details when needed (URL/host, user, password — local, throwaway credentials only, never production secrets) together with step-by-step try-it instructions, maintained in docs/playground.md.
• Budgets are AI-time based, never human-time based. When the user needs to quote the project (or a feature) to a client, the estimate is built from the AI's working hours plus the vibe coder's supervision hours (answering questions, making decisions, real-world testing the AI cannot do, uploading code) — never from what a traditional human team would take (months). Everything is itemized into segments with hours; the developer's hours are priced at their asked rate, the AI's token cost is computed per model and payment mode (≈ 0 marginal on subscription), the two blocks stay SEPARATE, and the budget is adjusted with the user before it is final. Preliminary estimate at Phase 1 close, firm estimate and client budget at Phase 2 close, recomputed on scope changes. See "Estimation & budget" below and references/estimation-budget.md.
• Forge issues are tracked in a living log. Whenever the project's issues on its Git forge — GitHub, GitLab, Gitea, Bitbucket, or any other — are accessed or worked, docs/issues.md records the full picture at the moment it changes: the inventory of what exists, what was resolved and exactly HOW (diagnosis, resolution, commits, verification), and what remains pending. If a problem surfaces later, what was done is on record — never reconstructed from memory. Template and rules in references/project-state.md.
• Confirm before advancing a phase. Each phase has a definition of done; do not slide into the next phase with the current one's gaps open.

Phase map

Work through these in order. The reference file for a phase is the authoritative instruction set for it — read it when you enter the phase.

Phase	Purpose	Reference to load
1. Discovery	Competitive scan first, then idea, feature discussion, project type, constraints, preliminary estimate	references/phase-1-discovery.md
2. Functional spec	Flows, requirements, scope, technical plan (stack/architecture/conventions), what needs design, firm estimate & client budget	references/phase-2-functional-spec.md
3. Design handoff	What to tell Design + the files Design must read/return	references/phase-3-design-handoff.md
4. Faithful build	Audit Design's return, consolidate spec, build with zero deviation, guided external setup	references/phase-4-faithful-build.md
5. Development	How to build, with test points throughout	references/phase-5-development.md
6. Documentation	docs/: API, classes, functions, usage, architecture	references/phase-6-documentation.md
7. Release	git hygiene, package hygiene, release prep	references/phase-7-release.md
8. Project website (conditional)	study the product, plan & build its site: site type, sections, domain, design direction, vanilla build, self-hosted fonts, product screenshots, SEO + AEO, launch	references/phase-8-website.md

Phases 3 and 4 are skipped only if Phase 2 concludes the project genuinely needs no UI/design. If there is any UI, they are mandatory.