@jeiemgi/cckit 0.1.6

package/templates/kit.config.json.tmpl

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://github.com/tuempresadigital/claude-kit/kit.config.schema.json",
+  "kitVersion": "0.1.0",
+  "mode": "guided",
+  "project": {
+    "name": "{{PROJECT_NAME}}",
+    "slug": "{{PROJECT_SLUG}}",
+    "owner": "{{OWNER_NAME}}",
+    "language": "{{COMMS_LANG}}",
+    "path": "{{PROJECT_PATH}}"
+  },
+  "profile": "{{PROFILE}}",
+  "roles": [{{ROLES_JSON}}],
+  "github": {
+    "repo": "{{GH_REPO}}",
+    "owner": "{{GH_OWNER}}",
+    "projectsV2": {{PROJECTS_V2}},
+    "projectNumber": {{PROJECT_NUMBER}},
+    "projectTitle": "{{PROJECT_BOARD_TITLE}}"
+  },
+  "milestones": [{{MILESTONES_JSON}}],
+  "plans": {
+    "format": "{{PLANS_FORMAT}}",
+    "dir": "{{PLANS_DIR}}"
+  },
+  "memory": {
+    "enabled": {{MEMORY_ENABLED}},
+    "provider": "mempalace",
+    "wing": "{{WING}}",
+    "claudeProjectSlug": "{{CLAUDE_PROJECT_SLUG}}"
+  }
+}

package/templates/knowledge-INDEX.md.tmpl

@@ -0,0 +1,12 @@
+# Knowledge Index — {{PROJECT_NAME}}
+
+Manifest of the knowledge base. Rules (`.claude/rules/knowledge-base.md`):
+
+- **If a file exists in `knowledge/`, it is current.** Superseded docs get DELETED — git is the archive.
+- **The latest decision wins.** Conflicts resolve by decision log + `updated` date.
+- Every doc carries frontmatter `status / owner / updated`. `canonical` = source of truth ·
+  `reference` = consultable, not normative · `historical` = context only.
+- New doc → add a row here in the same PR (`scripts/knowledge-lint.sh` enforces it).
+
+| File | Topic | Status | Owner | Updated |
+| ---- | ----- | ------ | ----- | ------- |

package/templates/lib/kit-sigil.sh.tmpl

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# claude-kit terminal identity — the seed-head sigil, brand palette, glyph vocabulary.
+# Canonical brief: claude-kit terminal identity (kit docs; see cckit.vercel.app:
+# apps/admin/src/plans/terminal-identity brief) #
+# The line-leader is the LOCKED seed-head: ⡶ (U+2876) in Azafrán — the n=13 Vogel
+# seed-head reduced to one Braille cell. One Azafrán per line: the seed only;
+# the slash + wordmark are ink-dim; the note is Polvo. ASCII fallback: o.
+#
+# Public API (source this file, then call):
+#   kit_sigil [skill] [note]   -> the "⡶ / claude-kit" line-leader lockup (footer)
+#   kit_seed                   -> just the leader glyph in Azafrán (⡶ / o)
+#   kit_glyph <name>           -> one state glyph (unicode, or its ASCII fallback)
+#   kit_paint <token> <text…>  -> text wrapped in a brand color (no-op when color is off)
+#
+# After the first call, mode + palette are exposed as KIT_* variables.
+
+# ---- color / glyph mode detection ---------------------------------------
+# Two INDEPENDENT axes — the brand glyph is not gated on the TTY (Claude Code
+# and most pipes render UTF-8 fine; only color is unsafe down a pipe):
+#   Color  : on when FORCE_COLOR=1, or (stdout is a TTY and NO_COLOR is unset).
+#   Unicode: on whenever the locale can render it (UTF-8), off only on an
+#            explicit KIT_ASCII=1 opt-out or a non-UTF-8 locale (braille needs UTF-8).
+#
+#   surface                         | glyph | color
+#   ------------------------------- | ----- | -----
+#   TTY, NO_COLOR unset             | ⡶     | Azafrán
+#   FORCE_COLOR=1 (piped)           | ⡶     | Azafrán   (previews)
+#   piped/redirect (e.g. Claude Code)| ⡶    | none      ← seed-head kept, color stripped
+#   NO_COLOR set                    | ⡶     | none
+#   KIT_ASCII=1 or non-UTF-8 locale | o     | none
+kit_color_mode() {
+  # Unicode axis — capable unless explicitly opted out or the locale isn't UTF-8.
+  local loc="${LC_ALL:-${LC_CTYPE:-${LANG:-}}}"
+  if [ "${KIT_ASCII:-}" = "1" ]; then
+    KIT_UNICODE=0
+  elif printf '%s' "$loc" | grep -qiE 'utf-?8'; then
+    KIT_UNICODE=1
+  else
+    KIT_UNICODE=0
+  fi
+
+  # Color axis — forced, or a TTY without NO_COLOR. Never down a plain pipe.
+  if [ "${FORCE_COLOR:-}" = "1" ]; then
+    KIT_COLOR=1
+  elif [ -t 1 ] && [ -z "${NO_COLOR+x}" ]; then
+    KIT_COLOR=1
+  else
+    KIT_COLOR=0
+  fi
+
+  if [ "$KIT_COLOR" = 1 ]; then
+    KIT_AZAFRAN=$'\033[38;2;201;122;44m'   # #C97A2C — THE accent (the seed / destello)
+    KIT_AZAFRAN_DEEP=$'\033[38;2;168;100;38m' # #A86426 — inner band depth (hero only)
+    KIT_INK=$'\033[2m'                     # terminal default-fg, dimmed — inverts with theme
+    KIT_POLVO=$'\033[38;2;168;160;151m'    # #A8A097 — meta · captions · table rules
+    KIT_VERDE=$'\033[38;2;52;101;56m'      # #346538 — success
+    KIT_AMBAR=$'\033[38;2;149;100;0m'      # #956400 — warning
+    KIT_ROJO=$'\033[38;2;159;47;45m'       # #9F2F2D — danger / error
+    KIT_AZUL=$'\033[38;2;31;108;159m'      # #1F6C9F — info
+    KIT_RESET=$'\033[0m'
+  else
+    KIT_AZAFRAN=''; KIT_AZAFRAN_DEEP=''; KIT_INK=''; KIT_POLVO=''
+    KIT_VERDE=''; KIT_AMBAR=''; KIT_ROJO=''; KIT_AZUL=''; KIT_RESET=''
+  fi
+}
+
+# ---- color wrapper -------------------------------------------------------
+# kit_paint <token> <text…>  — token ∈ azafran|azafran-deep|ink|polvo|verde|ambar|rojo|azul
+#                              (success|warn|danger|info aliases accepted).
+kit_paint() {
+  kit_color_mode
+  local token="$1"; shift
+  local code=""
+  case "$token" in
+    azafran)        code="$KIT_AZAFRAN" ;;
+    azafran-deep)   code="$KIT_AZAFRAN_DEEP" ;;
+    ink)            code="$KIT_INK" ;;
+    polvo)          code="$KIT_POLVO" ;;
+    verde|success)  code="$KIT_VERDE" ;;
+    ambar|warn)     code="$KIT_AMBAR" ;;
+    rojo|danger)    code="$KIT_ROJO" ;;
+    azul|info)      code="$KIT_AZUL" ;;
+  esac
+  printf '%s%s%s' "$code" "$*" "${code:+$KIT_RESET}"
+}
+
+# ---- glyph vocabulary ----------------------------------------------------
+# kit_glyph <name> — emits the brand glyph, or its 7-bit ASCII fallback off-TTY.
+# Grammar: solid seeds (●) + lines and points (▸ › ·). No rings, no AI sparkle.
+kit_glyph() {
+  kit_color_mode
+  case "$1" in
+    leader)        [ "$KIT_UNICODE" = 1 ] && printf '⡶'  || printf 'o' ;;  # U+2876 — the seed-head
+    agent)         [ "$KIT_UNICODE" = 1 ] && printf '●'  || printf '*' ;;  # U+25CF
+    workflow|run)  [ "$KIT_UNICODE" = 1 ] && printf '▸'  || printf '>' ;;  # U+25B8
+    skill)         [ "$KIT_UNICODE" = 1 ] && printf '›'  || printf '>' ;;  # U+203A
+    task|sep)      [ "$KIT_UNICODE" = 1 ] && printf '·'  || printf '-' ;;  # U+00B7
+    success)       [ "$KIT_UNICODE" = 1 ] && printf '●'  || printf 'ok' ;; # U+25CF (verde)
+    warning)       [ "$KIT_UNICODE" = 1 ] && printf '◆'  || printf '!' ;;  # U+25C6 (ámbar)
+    danger|error)  [ "$KIT_UNICODE" = 1 ] && printf '▪'  || printf 'x' ;;  # U+25AA (rojo)
+    info)          [ "$KIT_UNICODE" = 1 ] && printf '·'  || printf 'i' ;;  # U+00B7 (azul)
+    progress|pr)   [ "$KIT_UNICODE" = 1 ] && printf '▸'  || printf '~' ;;  # U+25B8 (azafrán)
+    memory|save)   [ "$KIT_UNICODE" = 1 ] && printf '●'  || printf '+' ;;  # U+25CF (azafrán)
+    version)       printf '+' ;;                                           # U+002B (azafrán)
+    *)             printf '%s' "$1" ;;
+  esac
+}
+
+# ---- the seed (leader glyph, Azafrán) ------------------------------------
+kit_seed() { kit_paint azafran "$(kit_glyph leader)"; }
+
+# ---- the line-leader lockup ----------------------------------------------
+# kit_sigil                       ->  ⡶ / claude-kit
+# kit_sigil "kit-task-pr"         ->  ⡶ / claude-kit · kit-task-pr
+# kit_sigil "" "memoria guardada" ->  ⡶ / claude-kit  memoria guardada
+# One Azafrán per line (the seed); slash + wordmark ink-dim; separator + note Polvo.
+kit_sigil() {
+  kit_color_mode
+  local skill="$1" note="$2" line
+  line="$(kit_seed)$(kit_paint ink ' / claude-kit')"
+  [ -n "$skill" ] && line+="$(kit_paint polvo ' · ')$(kit_paint ink "$skill")"
+  [ -n "$note" ]  && line+="$(kit_paint polvo "  ${note}")"
+  printf '\n%s\n' "$line"
+}

package/templates/rules/branch-naming.md

@@ -0,0 +1,104 @@
+# Branch & Merge Conventions
+
+Canonical naming + merge-order rules so you're never confused about *what a branch is*, *what order PRs merge in*, or *which agent is touching what*.
+
+## Branch name format
+
+```
+<kind>/<issue-number>-<slug>
+```
+
+- `<kind>` — one of the closed set below. No other prefixes.
+- `<issue-number>` — the issue this branch closes. **Always required** for human work.
+- `<slug>` — short kebab-case description (≤ 5 words).
+
+### Closed set of kinds
+
+| Kind       | For                                                | Typical risk |
+| ---------- | -------------------------------------------------- | ------------ |
+| `feat`     | New user-facing feature                            | med          |
+| `fix`      | Bug fix                                            | low–med      |
+| `task`     | Concrete chunk of work (no feature/bug label fits) | low–med      |
+| `chore`    | Tooling, deps, config, housekeeping                | low–med      |
+| `security` | Vulnerability fix or hardening                     | **high**     |
+| `scaffold` | Repo/infra scaffolding                             | med          |
+| `ci`       | CI/CD, workflows, automation                       | med          |
+| `adr`      | Architecture Decision Record                       | low          |
+| `spike`    | Time-boxed research (may be thrown away)           | low          |
+| `plan`     | Plan/report deliverable                            | low          |
+
+### Bot branches (do not create by hand)
+
+| Pattern    | Who                  | Notes                                                        |
+| ---------- | -------------------- | ------------------------------------------------------------ |
+| `agent/*`  | Auto-Dev CI agent    | Label an issue `agent:auto` → it branches + opens a PR. Never merges. |
+| `claude/*` | Claude GitHub Action | Created when an issue/PR mentions `@claude`.                 |
+
+## Merge order
+
+The integration branch is decided by, in priority:
+
+1. **Declared dependencies first.** If PR B needs PR A, put `Depends on #A` in B's body. Land A before B.
+2. **`risk:low` before `risk:high`.** Land cheap, safe, reviewed PRs first to shrink the conflict surface.
+3. **Lockfile-touching PRs last, one at a time** (see below).
+4. **Smaller before larger.** Big diffs rebase cleaner onto a moving target than the reverse.
+
+**Effort relations & session-fit.** At the **effort** level (above PRs), cross-effort dependencies
+are declared as a native GitHub `blocked_by` edge + a `## Relations` line (the board-visible chain) —
+the analogue of the PR-level `Depends on #N` above. A `[Flow]` title tag + `flow:<flow>` label group
+an effort's thread, and a `ctx:*` label drives `kit effort plan`'s session batching. Full spec:
+`rules/effort-model.md` § *Title rule, flow tags, relations, session-fit*.
+
+## The lockfile rule
+
+Lockfiles (`pnpm-lock.yaml`, `package-lock.json`, …) and manifest config conflict on almost every parallel merge. So:
+
+- **Merge at most one dependency-changing PR at a time**, then rebase the others.
+- On a lockfile conflict: take the **base** branch's lockfile, then regenerate (`pnpm install` / `npm install`). Never hand-merge lockfile hunks.
+- Keep a single block per config key (e.g. one `overrides:` in `pnpm-workspace.yaml`). A duplicate key is invalid YAML and breaks CI — a real, recurring incident.
+
+## Parallel work — one worktree per agent (hard rule)
+
+**Two agents in the same git checkout corrupt each other.** The working tree, index, and `HEAD` are a single unguarded shared resource: one agent's `mv`/`add`/`stage` is silently clobbered by another's `reset`/`checkout`/`stash`/`rebase`. Git has no locking for this.
+
+- **One agent = one git worktree** (or a separate clone). Never two agents in the same directory.
+- Prefer giving local sub-agents their own worktree.
+- Remote CI agents (Auto-Dev) are isolated per runner — favor them for parallel fixes.
+- Before editing shared files, check whether another agent is active.
+- One PR per issue. No monster PRs (a `size:XL` label is a smell — split it).
+
+## Optional: PR automation labels
+
+If the project adopts the kit's PR-automation workflows, these labels are applied automatically:
+
+| Label group | Applied by   | Meaning                                                  |
+| ----------- | ------------ | -------------------------------------------------------- |
+| `size:*`    | pr-labeler   | XS/S/M/L/XL by changed lines                             |
+| `risk:*`    | pr-labeler   | low/med/high by diff (sensitive paths, deps, size)       |
+| `blocked`   | pr-deps      | has an open `Depends on #N`                              |
+| `hold`      | human        | opt-out — never auto-merge even if it qualifies          |
+
+**GitHub gotcha:** `pull_request_target` / `workflow_run` / label-event workflows are read from the **default branch only**. If your automation lives on a non-default integration branch, trigger on `pull_request` (read from the PR base) instead — otherwise it silently never fires.
+
+## Branch lifecycle & cleanup
+
+One branch = one issue = one PR = **deleted on merge**. A branch is a short-lived container, not a place work lives.
+
+- **No long-lived uncommitted work.** Don't let a working tree sit dirty across sessions. Commit + PR, or discard. A branch sitting many commits behind the base with uncommitted work can silently revert merged work on a bad rebase — exactly the class of problem this section exists to prevent.
+- **Never work directly on the base branch (`main`/`develop`).** The `guard-base-branch-commit.sh` hook blocks commits there; start every change with `/kit-task-start <issue>` (it branches from a *fresh* base).
+- **Delete on merge.** `/kit-task-pr-merge` removes the worktree and deletes the local + remote branch automatically. Never leave a merged branch or its worktree lingering.
+- **One worktree per branch; remove it when its PR merges.** Parallel agents must use worktrees (never share a checkout).
+- **Sweep on demand.** `/kit-task-gc` prunes merged branches + worktrees, surfaces orphan/unpushed commits and stale stashes, and flags issues whose PR merged but stayed open. Dry-run + confirm.
+- The **SessionStart hygiene hook** (`.claude/hooks/repo-hygiene.sh`) surfaces all of the above at the start of every session so it never accumulates silently.
+
+## Leverage GitHub automations (the enforced layer)
+
+Local hooks + skills are **fast feedback**; the **durable, everyone-applies enforcement** belongs on GitHub. Move guardrails there as they mature — they then enforce for humans, CI agents (Auto-Dev), and the Claude Action alike, regardless of anyone's local setup.
+
+- **Do first (1 toggle):** repo Settings → **"Automatically delete head branches"** — eliminates remote-branch buildup entirely.
+- **Branch protection** on the base branch: require PR, required CI checks, linear history, no direct pushes.
+- **Stale-branch / stale-PR Action** (scheduled) to flag/close abandoned branches + PRs.
+- **Scheduled sweep** that flags "PR merged but issue still open" and "branch merged but not deleted".
+- Extend any adopted `pr-labeler` / `pr-deps` / `pr-automerge` workflows as the enforcement surface.
+
+Principle: **prefer migrating enforcement to GitHub** as it matures; keep only the genuinely local concerns (worktrees, stale base, dirty tree) in hooks.

package/templates/rules/communication-style.md

@@ -0,0 +1,22 @@
+# Communication Style
+
+## Preferences
+
+- **Format:** Bullet points and tables preferred over prose blocks
+- **Length:** Short and direct — no long intros, no padding
+- **Language:** {{COMMS_LANG}} — match the language {{OWNER_NAME}} uses
+- **Tone:** Practical, no fluff
+
+## What to Avoid
+
+- Long introductory sentences before getting to the point
+- Restating what was just said
+- Over-explaining obvious things
+- Excessive caveats
+
+## What to Do
+
+- Lead with the answer or action
+- Use tables for comparisons and status
+- Use bullets for lists and steps
+- If something needs explanation, keep it tight

package/templates/rules/delegation-brief.md

@@ -0,0 +1,40 @@
+# Delegation brief — what every delegated agent gets up front
+
+When spawning a sub-agent (Agent tool, orchestrate, CI agent), **prepend this**. It encodes the
+environment knowns so agents don't burn turns rediscovering "how do I get X". Keep it current —
+when an agent rediscovers something it should have been handed, add it here.
+
+## Project specifics (fill these in for {{PROJECT_NAME}})
+
+- Repo `<owner>/<repo>` · base branch **`main`** · owner **`<owner>`** · project board number **`<N>`**.
+- Build/dep tooling (e.g. pnpm + turbo monorepo, workspaces, package scope).
+- **Secrets by NAME, never value** — the GitHub API token env var (some apps use a custom name like
+  `GH_PAT`, **not** `GITHUB_TOKEN` — state which), model/API env vars, auth keys. Say which file/code
+  path reads each.
+
+## Standing gotchas (transferable — these bite on most projects)
+
+- **Refresh the base first.** An isolation worktree can seed from a **stale commit**. Start with
+  `git fetch origin <base> && git reset --hard origin/<base>` on a fresh branch; confirm
+  `git rev-parse --short HEAD` == `origin/<base>`.
+- **Commit so the guard sees the right branch.** A base-branch commit guard inspects the command's
+  named directory — a `$VAR` path can resolve to the main checkout and false-block. Commit via
+  `git -C <literal-worktree-path>` or `cd <literal-path>` (never a variable).
+- **zsh quirks:** `${VAR:+--flag "$VAR"}` word-splits — pass flags explicitly. `status` and `path`
+  are read-only vars — don't use them as loop variables.
+- **Board finder paginates the full board.** `project_find_item_by_issue` (gh-project.sh) pages the
+  whole board — use it; don't hand-roll a `first:100` query that misses recent issues. Owner/project
+  number resolve from `.claude/kit.config.json` (`.github.owner`, `.github.projectNumber`).
+- **Project IDs are worktree-durable.** `source scripts/lib/gh-project.sh; load_project_ids` reads
+  the captured IDs from the shared git-common-dir, so worktrees see them too.
+
+## Gate commands (fill in for {{PROJECT_NAME}})
+
+- Build / typecheck / lint commands; shell scripts: `bash -n`; any knowledge/plan lint. A green
+  build/typecheck is the bar. State whether CI exists or the gate is local + deploy-provider build.
+
+## Effort flow (the unit of work)
+
+- 1 effort = parent issue + native sub-issues + `effort/<N>` branch + **1 PR** (+ a `## For agents`
+  section listing touched files). See `effort-model.md`. Sub-agents **don't merge** — implement,
+  push, open the PR, and report the PR URL + a short summary + risks.

package/templates/rules/design-routing.md

@@ -0,0 +1,35 @@
+# Design Routing
+
+## Hard rule
+
+**ALL design and adjustment questions must be routed to the Designer agent.**
+
+Includes (not limited to):
+
+- Visual decisions: color, typography, spacing, layout, hierarchy
+- Component design: primitives, variants, states (hover/active/disabled/loading/error/empty)
+- Motion, animation, easing, durations
+- Iconography, illustration, imagery
+- Brand: logo, palette, tone, identity
+- Information architecture, flow, navigation
+- Microcopy and UX writing decisions
+- Accessibility decisions that affect UI (contrast, focus states, tap targets)
+- Responsive behavior and breakpoints
+- "Adjustments" — any tweak to an existing visual/UX surface, however small
+
+## How to route
+
+1. Do **not** answer from the orchestrator level
+2. Spawn the Designer agent (`.claude/agents/designer/AGENT.md`)
+3. Pass the question verbatim plus relevant context (screen name, token name, current state)
+4. Return the Designer's answer to {{OWNER_NAME}}
+
+## Why
+
+The Designer is the canonical voice for craft. Centralizing design decisions there keeps the
+system coherent and prevents ad-hoc visual calls that contradict the established direction.
+
+## Exception
+
+Purely informational questions (e.g. "where is the design system saved?") can be answered directly.
+The rule applies to _decisions_ and _adjustments_, not file lookups.

package/templates/rules/effort-model.md

@@ -0,0 +1,122 @@
+# Effort model — the unit of work (and of the work record)
+
+**GitHub is the single source of truth.** An *effort* is the kit's larger unit of work: bigger than
+a single task, with its own decomposition. The same structure that organizes the work also produces
+a clean, per-unit **record** of it (goal → plan → patch → verify) — useful for review, audit, and as
+a dataset if you train on your own development history.
+
+> Two flows coexist in the kit. Use **tasks** (`task-*`) for a single self-contained change; use
+> **efforts** (`effort-*`) when one goal decomposes into several sub-tasks that build toward one PR.
+
+## The unit
+
+**1 effort = 1 parent issue · 1 branch · 1 worktree · 1 PR.** No forced tiny PRs — a big effort-PR
+is fine while building. 1 effort decomposes into **N native GitHub sub-issues** (parallel or
+sequential, decided at scoping).
+
+```
+parent issue #N  ──►  effort/<N> branch + worktree (from main)
+   ├─ sub #a ─► sub/<N>a worktree (from effort/<N>)  ─┐
+   ├─ sub #b ─► sub/<N>b worktree                     ├─ merge into effort/<N>
+   └─ sub #c ─► sub/<N>c worktree                     ┘
+effort/<N>  ──►  ONE PR ──►  main  ──►  effort-close
+```
+
+Solo/sequential efforts may commit sub-issues directly on `effort/<N>` (one commit per sub-issue —
+the commit diff is that sub-issue's patch). Parallel sub-issues use their own worktrees
+(file-disjoint) and merge in.
+
+## Parent-issue template
+
+Every parent issue body uses these four sections (they double as the columns of the work record):
+
+```markdown
+## Goal           → problem statement
+What outcome, in one or two lines.
+
+## Scope          → plan (the sub-issue DAG; mark each parallel | sequential / dependsOn)
+The decomposition. Sub-issues are linked natively (GitHub parent/child).
+
+## For agents     → retrieval context
+Exact file paths / entry points a future agent needs to find the code fast.
+
+## Verification   → label / acceptance
+How we know it's done (commands, checks, acceptance).
+```
+
+**Effort + sub-issue titles must be recognizable on the board:**
+
+- **Umbrella / parent issue:** **`[Effort] <number> · <Name>`** — the literal `[Effort]` tag, the
+  issue's own number, then the human name. e.g. `[Effort] 42 · Auth hardening`.
+- **Sub-issue:** **`[Effort <parent>] <N> · <Title>`** — the parent's number in the tag, then a
+  **numeric** sequence index `N` (1, 2, 3 — **never letters** like A/B/C), then the title.
+  e.g. `[Effort 42] 1 · Add rate limiting to /login`.
+
+The parent ref is mandatory; `N` is a plain number so subs sort and read predictably. `effort-new`
+applies both formats when it creates the parent + native sub-issues, so a sub is identifiable by
+name alone in any flat list.
+
+### Title rule, flow tags, relations, session-fit
+
+The board should be **legible at a glance** — a title says *what* an effort delivers and *which
+flow* it belongs to; the *chain* (who blocks whom) and the *session weight* are machine-readable.
+
+**Concise, jargon-free titles (lint-enforced).** The `<Name>` part of an effort/sub title is a short
+plain-language **outcome** with an optional leading `[Flow]` tag:
+
+- **Format:** `[Effort] N · [Flow] short name` (parent) · `[Effort N] M · short name` (sub).
+- **Banned in the name:** glyphs (`— ▾ ▸ → ✓ ✗ … •`), parentheses, ` — ` / ` · ` / ` / ` sub-clauses,
+  code identifiers (file names, paths, `snake_case`), internal jargon (`chrome`, `seam`, `contract`,
+  `rescue stash`, `refactor`, `wiring`, …), and **> 6 words**. Detail goes in the body.
+- **`effort_title_lint`** (`scripts/lib/effort.sh`) is the check; `effort-new` refuses a failing
+  title. Bad→good: `operator chrome — Settings ▾ dropdown + fixes` → **`[UI] operator navigation`**.
+
+**Flow tag (`[Flow]` + `flow:<flow>` label).** A **flow** is a named thread of efforts toward one
+outcome. Controlled vocabulary (`EFFORT_FLOWS` in `effort.sh`; a project overrides it). The title
+carries `[Flow]` so membership reads off the board; the `flow:<flow>` label makes it filterable.
+
+**Relations (the chain) — native edge + `## Relations` mirror.** Cross-effort dependencies are
+**both** a native GitHub dependency (`blocked_by` — the edge GitHub renders on the issue/board, set
+by `effort_set_blocked_by`) **and** a `## Relations` section in the parent body (the human-readable
+mirror): `Depends on #N` / `Blocks #N` / `Extends #N` / `Parallel-safe with #N`. This is the
+effort-level analogue of the PR-level `Depends on` in `branch-naming.md`.
+
+**Session-fit (`ctx:*` + `kit effort plan`).** Every effort carries a **`ctx:S|M|L|XL`** label —
+how much of one working session it consumes before the context window fills. Derived by
+`effort_ctx_bucket` (`scripts/lib/effort-metrics.sh`) from difficulty + sub count: S=1 · M=2 · L=4 ·
+XL=8 weight. **`kit effort plan`** (`scripts/lib/effort-plan.sh`) reads the open efforts, groups by
+flow, orders each flow by the `blocked_by` edges, and packs them into **session-sized batches** under
+a budget (`KIT_SESSION_BUDGET`, default 4). L/XL efforts are flagged **"→ delegate subs"**:
+delegating an effort's sub-issues to **sub-agents in their own worktrees** keeps the main session
+light (a sub-agent reads/writes in its own context; only a summary returns) — the lever that lets
+more efforts fit one session (`rules/agent-execution-routing.md`).
+
+Sub-issue bodies: a one-line description is enough (title is for humans, short desc not required).
+The parent carries the rich narrative; the **PR** carries the human-facing review write-up + a
+`## For agents` section.
+
+## Lifecycle (the commands — see the effort-* skills)
+
+| Step | What |
+|------|------|
+| `effort-new` | parent issue (template) + native sub-issues |
+| `effort-start <N>` | `effort/<N>` branch + worktree; board → In Progress |
+| orchestrate | sub-issues in own worktrees (file-disjoint) → merge into `effort/<N>`; each closes + board Done as it lands |
+| `effort-pr <N>` | ONE PR `effort/<N>` → main (rich body + `## For agents`) |
+| `effort-close <N>` | **snapshot sub-diffs pre-squash** → merge → close parent + subs → board Done(all) → GC prune → kit-sync drift check |
+
+Board + record state are correct **by construction** — the close op owns them. Never rely on a
+separate, skippable "mark done" step.
+
+## Plans are issues, not files
+
+The parent issue **is** the plan. Strategy / roadmap narrative lives in your knowledge base; the
+"where we stand" view is generated from GitHub issue data, never hand-authored. → `plan-output-format.md`.
+
+## Trace hard rules
+
+- Snapshot each sub-branch diff **before squash** (squash destroys per-sub-issue pairs) — `effort-close`
+  step (a) does this automatically, to a durable dir under the shared git-common-dir.
+- Scrub secrets from diffs/bodies before they enter an issue or any exported record.
+- Keep client/tenant data out of the dev-workflow record (it is not your development history).
+- Outcome labels: merged-clean = positive · abandoned/reverted = negative · a manual flag for exemplars.

package/templates/rules/knowledge-base.md

@@ -0,0 +1,41 @@
+# Knowledge base — governance
+
+The project's knowledge base lives in `knowledge/` (config: `knowledge.dir` in
+`.claude/kit.config.json`). It is the durable, agent-readable source of truth for product and
+project knowledge: brand, design system, decisions, research, reference docs.
+
+## Hard rules
+
+1. **If a file exists in `knowledge/`, it is current.** Superseded docs are **deleted** — git
+   history is the archive. Never keep a dead doc around "for reference"; never create an
+   `archive/` folder.
+2. **The latest decision wins.** When two docs conflict, the decision log + the `updated`
+   frontmatter date resolve it. Fix the loser in the same PR you notice it.
+3. **Every doc carries frontmatter** — required, lint-enforced:
+
+   ```yaml
+   ---
+   status: canonical | reference | historical
+   owner: <role>          # which agent/role maintains it
+   updated: YYYY-MM-DD    # last substantive change
+   ---
+   ```
+
+   `canonical` = source of truth for its topic · `reference` = consultable, not normative ·
+   `historical` = context only, decisions inside may be superseded.
+4. **`knowledge/INDEX.md` is the manifest** — one row per doc (file, topic, status, owner,
+   updated). Agents read INDEX first to find the canonical doc per topic. A new doc lands in
+   INDEX **in the same PR**, or the lint fails.
+5. **Research becomes knowledge or it evaporates.** A research session's durable output is a
+   `reference` doc in `knowledge/` + an INDEX row — not a chat transcript.
+6. **Plans are not knowledge.** Plans (deliverable contracts) live in the plans dir and complete
+   via `status:` flip — see `plan-output-format.md`. Knowledge docs describe what IS; plans
+   describe what's BEING BUILT.
+
+## Enforcement
+
+- `scripts/knowledge-lint.sh` validates all of the above (frontmatter, INDEX completeness, live
+  refs, plan Deliverables contract). Run it locally before a knowledge PR; wire it into CI on
+  PRs touching `knowledge/**` or the plans dir.
+- Project-specific extra checks go in `scripts/knowledge-lint.local.sh` (sourced by the kit
+  script; survives `/kit-update` refreshes).

package/templates/rules/mempalace.md

@@ -0,0 +1,110 @@
+# MemPalace — Persistent Memory Protocol
+
+> Optional. Active only because this project enabled memory at `/kit-init`.
+> Requires the MemPalace MCP server + `mempalace` CLI. If you don't use MemPalace,
+> delete this file and the `SessionStart`/`Stop`/`PreCompact`/`SessionEnd` hooks in `.claude/settings.local.json`.
+
+## Wing architecture
+
+One wing per project. This project uses **`{{WING}}`**. Never write to another project's wing.
+
+## Room map ({{WING}} wing)
+
+| Room           | What goes there                             |
+| -------------- | ------------------------------------------- |
+| `decisions`    | ADRs, product decisions, decision log       |
+| `architecture` | Design system, brand, screens, design brief |
+| `planning`     | Implementation plans, ops plans             |
+| `technical`    | API routes, schema, engineering sessions    |
+| `problems`     | Bug investigations, incident notes          |
+| `general`      | Everything else                             |
+
+## On session start
+
+1. Call `mempalace_status` — loads the overview
+2. Working on a topic: `mempalace_search "<topic>" wing={{WING}}` for past context
+
+## Before answering about past decisions / prior sessions / existing work
+
+- Call `mempalace_search` first — do not rely solely on the context window
+
+## After meaningful work (decisions, discoveries, conclusions)
+
+- `mempalace_add_drawer` — verbatim content, `wing={{WING}}`, pick a room above
+- `mempalace_kg_add` — entity triples (subject / predicate / object)
+
+## On session close
+
+When the user says to close or end the session ("close session", "cierra la sesión", "we're done"),
+write the session to memory **before** the closing summary — every time:
+
+1. `mempalace_diary_write` (own wing `agent-<name>`, topic = the session) — an AAAK summary: what was
+   done, the decisions, and what's still open.
+2. `mempalace_add_drawer` (`wing={{WING}}`, room `decisions`) — verbatim record of the key decisions.
+3. `mempalace_kg_add` — triples for any notable new entities/facts.
+4. **If there is unsynced local work** (dirty tree, unpushed commits, stashes), write a terse
+   "resume here" follow-up: `mempalace_add_drawer` (`wing={{WING}}`, room `planning`) with the branch,
+   what's uncommitted/unpushed, the next step, and any open PR/issue refs — so the next session resumes
+   cheaply instead of re-deriving context. Prefer committing/pushing the work; the drawer is for what
+   genuinely can't land yet.
+
+(The `Stop` hook files the raw transcript; the `SessionEnd` hook is the safety net that captures
+unsynced work if you forgot step 4 — this is the curated, decision-level summary.)
+
+## Specialist agent protocol
+
+Each agent has its own diary wing (`agent-<name>`) for session notes; all project content saves to `wing={{WING}}`.
+
+### On wake-up (every specialist agent)
+
+1. `mempalace_diary_read` (own wing) — recall last session
+2. `mempalace_search "<topic>"` in its room — pull relevant context
+
+### After significant work
+
+- `mempalace_diary_write` (own wing, topic = what was done)
+- `mempalace_add_drawer` (`wing={{WING}}`, relevant room)
+
+## CLI commands (`mempalace` 3.3.5)
+
+The MCP tools above are for in-session reads/writes. Use the **CLI** for bulk ingest, maintenance, and automation. Always preview destructive ops with `--dry-run` before `--apply`.
+
+| Task                                                       | Command                                                          |
+| ---------------------------------------------------------- | ---------------------------------------------------------------- |
+| Ingest this project's code/docs                            | `mempalace mine <dir> --wing {{WING}}`                           |
+| Ingest chat exports (Claude Code / ChatGPT / Slack)        | `mempalace mine <dir> --mode convos --wing {{WING}}`             |
+| Split concatenated transcript mega-files (before `mine`)   | `mempalace split <dir>`                                          |
+| Search from the shell                                      | `mempalace search "query" --wing {{WING}} --room <room> --results N` |
+| Load wake-up context (~600–900 tokens)                     | `mempalace wake-up --wing {{WING}}`                              |
+| Palace overview                                            | `mempalace status`                                               |
+| Prune drawers for deleted/moved/gitignored sources         | `mempalace sync --wing {{WING}} --dry-run` → `--apply`           |
+| Compress drawers via AAAK (~30×)                           | `mempalace compress --wing {{WING}} --dry-run`                   |
+| Show MCP setup command                                     | `mempalace mcp`                                                  |
+
+Correct-option notes:
+
+- `mine` defaults to `--mode projects`; pass `--mode convos` for chat exports. `--extract exchange` (default) or `--extract general` controls convo extraction. `--wing` defaults to the directory name — **always pass `--wing {{WING}}`** so this project's memory stays in one wing.
+- `search` (CLI) uses `--wing` / `--room` / `--results`; the MCP `mempalace_search` tool uses `wing` / `room` / `limit` instead.
+- `sync` is dry-run by default; `--apply` requires `--wing` (or a project root) as a guard against mass deletion.
+
+## MCP vs CLI — which to use
+
+| Case                                          | Use                                                        |
+| --------------------------------------------- | ---------------------------------------------------------- |
+| In-session granular **read**                  | MCP `mempalace_search` / `kg_query` / `traverse`           |
+| In-session granular **write**                 | MCP `mempalace_add_drawer` / `kg_add` / `diary_write`      |
+| Bulk ingest a directory or chat export        | CLI `mempalace mine`                                       |
+| Maintenance (prune, compress)                 | CLI `mempalace sync` / `compress`                          |
+| Automation (session start / stop / compaction)| Hooks → CLI (below)                                        |
+
+## Hooks (scaffolded into `.claude/settings.local.json`)
+
+- **SessionStart** → `mempalace wake-up --wing {{WING}}` — injects palace context at session start. Uses `wake-up --wing` (explicit) rather than `mempalace hook run --hook session-start`, which derives the wing implicitly and could file into the wrong wing.
+- **Stop** → files the finished session into `wing={{WING}}` (`mempalace mine … --mode convos`).
+- **PreCompact** → safety-net sweep before context compression.
+- **SessionEnd** → `mempal_followup.sh`: if the current branch has **unsynced work** (dirty tree or
+  unpushed commits), writes a terse "resume here" note and mines it into `wing={{WING}}` so an abrupt
+  close doesn't lose it. Silent no-op when the tree is fully synced. This is the safety net for the
+  agent-driven step 4 above.
+
+All four are safe no-ops when the `mempalace` CLI is not installed.