@jeiemgi/cckit 0.1.6

package/templates/rules/plan-output-format.md

@@ -0,0 +1,58 @@
+# Plan Output Format
+
+## Hard rule
+
+**When any agent is asked to produce a "plan", the deliverable is a file in `{{PLANS_DIR}}`** (format: `{{PLANS_FORMAT}}`).
+
+Applies to: implementation plans, architecture plans, design briefs, roadmaps, milestone
+breakdowns, audit reports, technical specs — anything labeled "plan" or "report".
+
+## File convention
+
+- Filename: `{{PROJECT_SLUG}}-<role>-<topic>.md` (or `.mdx` if your project renders MDX)
+- Lives in `{{PLANS_DIR}}`
+- Starts with YAML frontmatter:
+
+```yaml
+---
+title: '{{PROJECT_NAME}} — <description>'
+role: PM | Designer | Tech Lead | DevOps | Backend | Frontend | QA | Security | Research
+date: YYYY-MM-DD
+version: '1.0'
+status: Draft | In Review | Active | Complete
+subtitle: 'One-sentence description'
+issue: 12 # GitHub issue number (optional)
+tags: [tag1, tag2]
+---
+```
+
+## Deliverables section (required)
+
+Every plan must include a `## Deliverables` table listing the PRs that, when all merged, complete it:
+
+```md
+## Deliverables
+
+| PR  | Description        | Status  |
+| --- | ------------------ | ------- |
+| #28 | Scaffold feature X | ⬜ Open |
+| #29 | UI for feature X   | ⬜ Open |
+```
+
+This is the completion contract. When all PRs are merged → the plan flips `status:` to
+`Complete` and **stays visible** in `{{PLANS_DIR}}` — there is no archive folder.
+
+## Lifecycle
+
+```
+Draft → Active → Complete   (via the status: frontmatter field — file never moves)
+```
+
+`/kit-task-close` flips the status when closing the parent issue, once every Deliverables PR
+is merged.
+
+## Before writing a plan
+
+1. Check `{{PLANS_DIR}}` for an existing plan on the same topic
+2. Read project knowledge docs for background
+3. Use the frontmatter + Deliverables skeleton above

package/templates/rules/react-annotate.md

@@ -0,0 +1,69 @@
+# React UI Annotation — Agentation loop ({{PROJECT_NAME}})
+
+> Active because this project ran `/kit-annotate`. It wires the **Agentation** toolbar — an in-app,
+> dev-only React component — to Claude via the `agentation` MCP server. Agentation is third-party
+> (PolyForm Shield 1.0.0, source-available), installed as this project's own dev dependency; the kit
+> vendors none of its code. To remove: delete this file, run `claude mcp remove agentation`, and drop
+> the `<Agentation />` line from the app entry.
+
+## What it gives you
+
+Click any element in the **running dev app** (toolbar, bottom-right), leave a note with intent +
+severity, and Claude pulls a structured record — CSS selector, position, nearby text, the **React
+component tree**, and a **source file path** — then jumps to the code and fixes it.
+
+## Honest limits — state these, don't over-promise
+
+- **Dev-only.** The `<Agentation />` toolbar is gated behind a dev check and stripped from production
+  builds. Only annotate against the dev server.
+- **Identity is selector + source-path + component name, NOT live prop/state values.** Agentation does
+  not serialize prop/state values. To pin the exact code, use the selector / source path / component
+  name to **grep** the repo.
+- **React Server Components** render only on the server → a clicked server-rendered node degrades to a
+  CSS selector. Client components annotate fully.
+- The MCP payload Claude receives is lighter than the toolbar's **Copy** markdown. If a needed detail
+  is missing, ask the user to hit **Copy** in the toolbar and paste it.
+
+## The session loop
+
+**Default to a batch contract.** Open with: *"Annotate everything you want changed, then say 'done' —
+I'll pull the whole batch and apply the fixes."* Let the user mark up the whole screen and hand off a
+reviewed batch; don't lead with a silent live watch that picks notes up mid-thought.
+
+When the user says "done" / "go" / "I left notes" (or runs `/kit-annotate`):
+
+1. **Pull** the batch — `agentation_get_all_pending`. (Only use `agentation_watch_annotations`, which
+   blocks silently until new notes arrive, if the user **explicitly opts into** hands-free / "watch".)
+2. For **each** annotation:
+   - `agentation_acknowledge` — mark it seen (flips the note's state in the toolbar).
+   - **Locate the code:** use the source file path if present; otherwise grep the selector / class
+     names / component name / nearby text.
+   - Make the fix, following this project's build skills and conventions.
+   - `agentation_resolve` with a one-line summary of the change — or `agentation_dismiss` with a reason
+     if it isn't actionable, or `agentation_reply` to ask a clarifying question.
+3. In hands-free mode only, call `agentation_watch_annotations` again and continue until the user stops.
+
+**Set expectations** so the browser side isn't a black box: notes flip **acknowledged → resolved** in
+the toolbar as you work; fixes land via **HMR** — *refresh to see them*; each resolved note carries a
+one-line summary.
+
+**Preflight:** the MCP server runs the toolbar's HTTP receiver on **:4747**; it starts with Claude Code
+once registered. If the `agentation_*` tools are missing, restart Claude Code and verify with
+`npx agentation-mcp doctor`. If `agentation_list_sessions` shows **connected but 0 sessions** while the
+user is annotating, the wired `<Agentation endpoint="http://localhost:4747" />` is **missing its
+`endpoint` prop** (toolbar is writing only to `localStorage`) or the tab is stale — fix the wiring /
+reload before continuing.
+
+<!-- IF:MEMORY -->
+## On session close
+
+Before the closing summary, write a short record to MemPalace wing **`{{WING}}`** (room `problems` or
+`decisions`): which annotations were resolved, the components/files touched, and anything deferred.
+Keeps UI-fix history per project.
+<!-- /IF:MEMORY -->
+
+## Scope
+
+Wired for **Claude Code**. Other agents (Cursor, Codex, …) can read the same annotations through
+Agentation's own MCP/export — that is Agentation's surface, not the kit's; the kit neither wires nor
+maintains it.

package/templates/rules/risk-tiered-review.md

@@ -0,0 +1,62 @@
+# Risk-tiered review — spend human review only where it pays
+
+**Human review time is the scarce resource; spend it on risky changes only.** Once the automated
+gates are green, a `risk:low` PR has already passed everything a human reviewer would have checked —
+re-reviewing it by hand is waste. Complements `branch-naming.md` (auto-merge, merge order, risk
+labels); on a review-effort conflict, this rule wins.
+
+## The tiering
+
+| Tier            | Gate state                                         | Review                                                                                   |
+| --------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **`risk:low`**  | the project's gates green (build + typecheck/lint) | **auto-pass** — the pipeline caught what a human would; `pr-automerge` lands it (squash) |
+| **`risk:med`**  | gates green                                        | **human review required** — a person reads the diff before merge                         |
+| **`risk:high`** | gates green                                        | **human review required** — read + reason about blast radius before merge                |
+
+## Always-human (overrides the tier — never auto-pass)
+
+These floor to human review regardless of the `risk:*` label, per existing rules:
+
+- **CI / workflow changes** (`.github/workflows/**` and equivalents) — always `risk:high`; CI-token +
+  supply-chain blast radius.
+- **Security-touching diffs** — auth, CSP/CORS, secrets, dependency changes (a `security/*` branch is
+  always `risk:high`).
+- **Lockfile / dependency-graph changes** — the lockfile + package manifest (`branch-naming.md`
+  lockfile rule): one in flight at a time, human-reviewed.
+- **`risk:*` floors to the highest concern in a mixed PR** — never bury a risky change among trivial ones.
+
+## The gates (what "green" means)
+
+The gates are whatever the project runs to prove a change is sound — typically:
+
+- **A successful build** (the deploy / build step).
+- **Local `typecheck` + `lint`**, run before push.
+
+A `risk:low` auto-pass is valid **only** when the project's gates are green. A red gate = not eligible,
+no exceptions.
+
+## Why
+
+- An agent-driven swarm produces more PRs than a human can hand-review; uniform review is the bottleneck.
+- The pipeline (build + typecheck + lint) is a deterministic reviewer for mechanical correctness — let
+  it own the low-risk tier. Reserve human judgment for the changes where judgment is the actual value:
+  design decisions, data/graph shape, security, blast radius.
+- This is the merge-side counterpart to fanning work out across parallel agents — fan-out the work in,
+  tier the review out.
+
+## Enforcement
+
+- `pr-automerge` already encodes the mechanism: native squash auto-merge fires **only** on `risk:low`
+  PRs that aren't `blocked`/draft/`hold` (`branch-naming.md`). This rule is the **policy** that
+  blesses that behavior as the default, not an exception.
+- Stop an auto-pass you want a human on: add the **`hold`** label or mark the PR **draft**.
+- A `risk:med`/`risk:high` PR merged without a human read is a process violation — re-tier or review.
+
+## Scope — ad-hoc PRs, not approved-plan execution
+
+These tiers govern **ad-hoc** PRs (a one-off change a human is about to merge). They do **not** gate
+execution of an **already-approved plan**: when the captain (`kit-autopilot --plan`) drives an
+approved plan, it **merges each planned wave itself** and continues — a `risk:med` change the plan
+already blessed is not re-gated per-PR. The captain pings the human only on a **genuine blocker** (a
+surprise always-human change not implied by the plan — see the `kit-autopilot` skill,
+_Established-plan autonomy_). Don't cite these tiers to stall an approved plan.

package/templates/rules/skill-gaps.md

@@ -0,0 +1,48 @@
+# Smart skill-gap detection ({{PROJECT_NAME}})
+
+Surface a missing capability **before** starting work — but only when it's genuinely non-obvious, and
+without nagging. Prompt for the **special and new**; stay silent on the **routine**.
+
+## When to prompt (all must hold)
+
+1. The task plausibly needs a **specific skill** — a framework/tool workflow, a design system, a data
+   or automation capability — that is **not available** in this session and **not wired** to the agent
+   that would do the work.
+2. The need is **non-straightforward**: a special or new feature, not routine work you can already do
+   well with general ability plus the skills already wired.
+3. You have **not already asked** about this gap in this project (see anti-repeat).
+
+If a capable skill is already available/wired → just use it, don't ask. If the work is routine → don't
+ask. When unsure whether a gap is "obvious," lean toward **not** interrupting.
+
+## How to prompt (once, up front, before starting)
+
+State the gap in one line, then offer options via `AskUserQuestion`:
+
+- **Pick a skill** — list the relevant skills actually available (the session's skill list,
+  `~/.claude/skills/*`, installed plugin skills; discover with the `find-skills` skill) for the user to
+  wire or use.
+- **Provide one** — the user points to or supplies a skill / doc / MCP server.
+- **Proceed without** — continue with general ability.
+
+Route any wiring through **`/kit-customize`** (it attaches skills/tools to agents). Batch multiple gaps
+for one task into a **single** prompt at the start — never drip-feed interruptions mid-task.
+
+## Anti-repeat (don't nag)
+
+Record outcomes in `.claude/kit.config.json` under `skillPrompts`:
+
+```json
+"skillPrompts": { "asked": ["<gap-key>"], "declined": ["<gap-key>"], "wired": ["<skill-name>"] }
+```
+
+- Before prompting, check `skillPrompts`. If the gap is already in `asked`, `declined`, or covered by
+  `wired`, **do not ask again** — proceed silently.
+- A `gap-key` is a short, stable slug for the capability (e.g. `gsap-animation`, `stripe-billing`,
+  `playwright-e2e`).
+- Ask **at most once per gap per project**. A declined gap stays declined unless the user reopens it.
+
+## Principle
+
+One good question up front beats five mid-task interruptions. Detecting a real, non-obvious capability
+gap early — and remembering the answer — is the whole point.

package/templates/rules/task-management.md

@@ -0,0 +1,42 @@
+# Task Management
+
+## Source of truth
+
+- **GitHub issues** in `{{GH_REPO}}`<!-- IF:PROJECTS_V2 --> + the Projects v2 board (`https://github.com/users/{{GH_OWNER}}/projects/{{PROJECT_NUMBER}}`)<!-- /IF:PROJECTS_V2 -->
+- **Never** maintain task lists in markdown files. Use `gh issue` + the `task-*` skills so state stays in one place.
+- Always re-fetch from `gh` — never trust a stale session snapshot.
+
+## Roles
+
+Every issue carries a `role:` label. Active roles for this project: {{ROLES_HUMAN}}.
+
+The role determines which agent owns the work. Spawn that agent for the actual execution.
+
+## Kinds
+
+`task` · `plan` · `adr` · `scaffold` · `spike` — drives the branch prefix `<kind>/<N>-<slug>`.
+
+## Priorities
+
+`p1` (now / blocking) · `p2` (next) · `p3` (later).
+
+## Milestones
+
+{{MILESTONES_HUMAN}}
+
+## The loop
+
+1. `/kit-task-sync` — see the board, pick an unblocked issue
+2. `/kit-task-start <N>` — branch from main, mark In Progress
+3. Do the work (spawn the owning agent)
+4. `/kit-task-pr <N>` — commit, push, open PR
+5. `/kit-task-pr-merge` — squash-merge, back to main
+6. `/kit-task-close <N>` — close issue<!-- IF:PLANS -->, archive plan if all deliverables merged<!-- /IF:PLANS -->
+
+## Rules
+
+- One PR per issue — no monster PRs. **Exception: a coupled migration/DDL chain ships as ONE PR (and ideally one issue)** — don't fragment a sequenced migration set into a PR-per-file. Split only for genuinely independent migrations or a step needing its own review gate (data backfill, RLS behavior change).
+- PR title = issue title · body includes `Closes #N`
+- Labels + milestone inherited from the issue
+- Never file an issue without confirming title + role + priority with {{OWNER_NAME}}
+- Never create new label families on the fly — fail loudly if a kind/priority is unknown

package/templates/settings/settings.local.json.tmpl

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh issue *)",
+      "Bash(gh pr *)",
+      "Bash(gh label *)",
+      "Bash(gh api *)",
+      "Bash(gh repo *)",
+      "Bash(gh auth status)",
+      "Bash(git checkout *)",
+      "Bash(git switch *)",
+      "Bash(git branch *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(git fetch *)",
+      "Bash(git pull *)",
+      "Bash(git rebase *)",
+      "Bash(git status)",
+      "Bash(git log *)",
+      "Bash(./scripts/task-sync.sh *)",
+      "Bash(./scripts/setup-labels.sh)",
+      "Bash(./scripts/setup-milestones.sh)",
+      "Bash(./scripts/capture-project-ids.sh)"
+    ]
+  }
+}

package/templates/skills/NAMESPACED

@@ -0,0 +1,13 @@
+# Kit-namespaced skills — these take the project's `skillPrefix` (e.g. kit-) on scaffold/upgrade.
+# The kit-workflow skills only; content skills (morning-briefing, karpathy-guidelines, speckit,
+# feature-build-refine, supabase-patterns) are intentionally absent and stay bare.
+# One skill name per line; blank lines and #-comments ignored. See scripts/init.sh (_is_namespaced).
+#
+# v2 (#370 + #853): the task-* AND effort-* lifecycle skills are no longer SCAFFOLDED per-project —
+# the plugin provides them directly as `kit-task-*` / `kit-effort-*` under skills/, resolved via
+# ${CLAUDE_PLUGIN_ROOT}. No template ships for them, and no profile lists them, so /kit-init and
+# /kit-update never (re)scaffold a bare-name duplicate (idempotency: no /kit-update resurrection).
+# This file is now empty of workflow skills; it stays so the upgrade rename map
+# (kit.config upgrade.renamed) and _is_namespaced keep reading cleanly for projects that previously
+# scaffolded kit-task-* / kit-effort-* — their existing scaffolded copies are preserved, the
+# plugin-direct skills take over.

package/templates/skills/copywriting/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: copywriting
+description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," "CTA copy," "value proposition," "tagline," "subheadline," "hero section copy," "above the fold," "this copy is weak," "make this more compelling," or "help me describe my product." Use this whenever someone is working on website text that needs to persuade or convert. For email copy, see emails. For popup copy, see popups. For editing existing copy, see copy-editing.
+metadata:
+  version: 2.0.0
+---
+
+# Copywriting
+
+You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
+
+## Before Writing
+
+**Check for product marketing context first:**
+If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Page Purpose
+- What type of page? (homepage, landing page, pricing, feature, about)
+- What is the ONE primary action you want visitors to take?
+
+### 2. Audience
+- Who is the ideal customer?
+- What problem are they trying to solve?
+- What objections or hesitations do they have?
+- What language do they use to describe their problem?
+
+### 3. Product/Offer
+- What are you selling or offering?
+- What makes it different from alternatives?
+- What's the key transformation or outcome?
+- Any proof points (numbers, testimonials, case studies)?
+
+### 4. Context
+- Where is traffic coming from? (ads, organic, email)
+- What do visitors already know before arriving?
+
+---
+
+## Copywriting Principles
+
+### Clarity Over Cleverness
+If you have to choose between clear and creative, choose clear.
+
+### Benefits Over Features
+Features: What it does. Benefits: What that means for the customer.
+
+### Specificity Over Vagueness
+- Vague: "Save time on your workflow"
+- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
+
+### Customer Language Over Company Language
+Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.
+
+### One Idea Per Section
+Each section should advance one argument. Build a logical flow down the page.
+
+---
+
+## Writing Style Rules
+
+### Core Principles
+
+1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate"
+2. **Specific over vague** — Avoid "streamline," "optimize," "innovative"
+3. **Active over passive** — "We generate reports" not "Reports are generated"
+4. **Confident over qualified** — Remove "almost," "very," "really"
+5. **Show over tell** — Describe the outcome instead of using adverbs
+6. **Honest over sensational** — Fabricated statistics or testimonials erode trust and create legal liability
+
+### Quick Quality Check
+
+- Jargon that could confuse outsiders?
+- Sentences trying to do too much?
+- Passive voice constructions?
+- Exclamation points? (remove them)
+- Marketing buzzwords without substance?
+
+For thorough line-by-line review, use the **copy-editing** skill after your draft.
+
+---
+
+## Best Practices
+
+### Be Direct
+Get to the point. Don't bury the value in qualifications.
+
+❌ Slack lets you share files instantly, from documents to images, directly in your conversations
+
+✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
+
+### Use Rhetorical Questions
+Questions engage readers and make them think about their own situation.
+- "Hate returning stuff to Amazon?"
+- "Tired of chasing approvals?"
+
+### Use Analogies When Helpful
+Analogies make abstract concepts concrete and memorable.
+
+### Pepper in Humor (When Appropriate)
+Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.
+
+---
+
+## Page Structure Framework
+
+### Above the Fold
+
+**Headline**
+- Your single most important message
+- Communicate core value proposition
+- Specific > generic
+
+**Example formulas:**
+- "{Achieve outcome} without {pain point}"
+- "The {category} for {audience}"
+- "Never {unpleasant event} again"
+- "{Question highlighting main pain point}"
+
+**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md)
+
+**Subheadline**
+- Expands on headline
+- Adds specificity
+- 1-2 sentences max
+
+**Primary CTA**
+- Action-oriented button text
+- Communicate what they get: "Start Free Trial" > "Sign Up"
+
+### Core Sections
+
+| Section | Purpose |
+|---------|---------|
+| Social Proof | Build credibility (logos, stats, testimonials) |
+| Problem/Pain | Show you understand their situation |
+| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
+| How It Works | Reduce perceived complexity (3-4 steps) |
+| Objection Handling | FAQ, comparisons, guarantees |
+| Final CTA | Recap value, repeat CTA, risk reversal |
+
+**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md)
+
+---
+
+## CTA Copy Guidelines
+
+**Weak CTAs (avoid):**
+- Submit, Sign Up, Learn More, Click Here, Get Started
+
+**Strong CTAs (use):**
+- Start Free Trial
+- Get [Specific Thing]
+- See [Product] in Action
+- Create Your First [Thing]
+- Download the Guide
+
+**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed]
+
+Examples:
+- "Start My Free Trial"
+- "Get the Complete Checklist"
+- "See Pricing for My Team"
+
+---
+
+## Page-Specific Guidance
+
+### Homepage
+- Serve multiple audiences without being generic
+- Lead with broadest value proposition
+- Provide clear paths for different visitor intents
+
+### Landing Page
+- Single message, single CTA
+- Match headline to ad/traffic source
+- Complete argument on one page
+
+### Pricing Page
+- Help visitors choose the right plan
+- Address "which is right for me?" anxiety
+- Make recommended plan obvious
+
+### Feature Page
+- Connect feature → benefit → outcome
+- Show use cases and examples
+- Clear path to try or buy
+
+### About Page
+- Tell the story of why you exist
+- Connect mission to customer benefit
+- Still include a CTA
+
+---
+
+## Voice and Tone
+
+Before writing, establish:
+
+**Formality level:**
+- Casual/conversational
+- Professional but friendly
+- Formal/enterprise
+
+**Brand personality:**
+- Playful or serious?
+- Bold or understated?
+- Technical or accessible?
+
+Maintain consistency, but adjust intensity:
+- Headlines can be bolder
+- Body copy should be clearer
+- CTAs should be action-oriented
+
+---
+
+## Output Format
+
+When writing copy, provide:
+
+### Page Copy
+Organized by section:
+- Headline, Subheadline, CTA
+- Section headers and body copy
+- Secondary CTAs
+
+### Annotations
+For key elements, explain:
+- Why you made this choice
+- What principle it applies
+
+### Alternatives
+For headlines and CTAs, provide 2-3 options:
+- Option A: [copy] — [rationale]
+- Option B: [copy] — [rationale]
+
+### Meta Content (if relevant)
+- Page title (for SEO)
+- Meta description
+
+---
+
+## Related Skills
+
+- **copy-editing**: For polishing existing copy (use after your draft)
+- **cro**: If page structure/strategy needs work, not just copy
+- **emails**: For email copywriting
+- **popups**: For popup and modal copy
+- **ab-testing**: To test copy variations