Hot Set

An installable agentic development template for Codex, Claude Code, GitHub Copilot, Gemini, Kimi, and Cursor-powered repositories.

Hot Set is designed as one installable package that lets multiple agent harnesses share the same project context, graph tooling, skills, hooks, and delegation rules side by side.

Published on npm as hot-set.

Overview

Modern AI-assisted development works best when the AI has deep, persistent context about your project. Most teams lose that context every session — explaining architecture, recalling past decisions, and re-discovering what works and what doesn't.

This template solves that problem. At its core is a living knowledge base (copilot-instructions.md) that Copilot reads at the start of every session and updates at the end. Lessons learned, known issues, project status, and next steps are tracked automatically across sessions, so context is never lost.

On top of the knowledge base, the template provides an agent and skill ecosystem — specialized agents (architecture, frontend, backend, QA, DBA, and more) and composable skills. These give Copilot domain-specific expertise on demand.

The result is a workspace where your AI assistant starts every session informed, uses expert-level skills for specific tasks, and leaves behind a richer knowledge base for next time.

✨ Features

🧠 Self-Updating Knowledge Base

A multi-section copilot-instructions.md that Copilot reads and writes every session. You fill in your architecture and conventions once; Copilot auto-maintains lessons learned, known issues, current status, and next steps.

🤖 Specialized AI Agents

Purpose-built agents for architecture, frontend, backend, security, QA, database administration, CI/CD, and advanced problem-solving. Each agent file (.agent.md) encapsulates expert-level system prompts and tool configurations.

🛠️ Composable Skills

Reusable skill modules organized into Development, Quality, Performance, Security, Decision-Making, and Web Automation. Skills can be invoked individually or orchestrated together.

🕸️ Knowledge Graph Layer

A two-tier code knowledge graph so your AI answers structure, call-path, and blast-radius questions instantly instead of grepping the tree every session. codegraph keeps an always-on, auto-syncing, 100% local code graph (MCP codegraph_explore); graphify builds an on-demand multimodal graph over code + docs + PDFs + media with an interactive visualization. The codebase-cartographer agent and an upgraded codenavi skill query the graph before grepping. Wired across Claude Code, Copilot, Gemini, Codex, and Kimi. See § 3.5 · Knowledge Graph Layer in the knowledge base.

🔁 Cross-Agent Operating Model

docs/agent-operating-model.md defines how agents delegate, what context they pass, how graph findings move between specialists, and how delegated work reports back to the orchestrator.

✅ Agent Asset Guardrails

scripts/validate-agent-assets.mjs checks agent and skill metadata, mirrored skills, operating-model links, and local graph setup state. .githooks/pre-commit runs the validator locally.

📋 Structured Onboarding

A placeholder-driven setup guide (instructions.md) walks you through configuring the template for your project. Ask Copilot to help — it reads the guide and knows every placeholder.

Prerequisites

| Requirement | Purpose | |-------------|---------| | Node.js 18+ + npm | Run the Next.js Web App and Convex backend | | GitHub Copilot | Agent and skill ecosystem | | Supabase CLI (Optional) | Local Supabase development |

Quick Start

Install from npm

Install the agent template into any repository with:

npx hot-set@latest install .

The installer skips existing files by default. Preview or overwrite with:

npx hot-set@latest install . --dry-run
npx hot-set@latest install . --force

Then enable local hooks:

git config core.hooksPath .githooks

The pre-commit hook validates assets; the post-commit hook refreshes the knowledge graphs in the background.

Install from GitHub source

Use the GitHub source directly when testing unreleased changes:

npx github:stacflow/hot-set install .

What the installer does

• Copies agent instructions, skills, MCP config, hooks, and validation scripts into the target repo.
• Installs every supported harness surface in one pass: Codex, Claude Code, GitHub Copilot, Gemini, Kimi, Cursor, shared MCP config, and shared git hooks.
• Skips existing files by default so it does not overwrite local project context.
• Supports --dry-run to preview and --force to overwrite.
• Leaves generated knowledge graph artifacts out of git.
• Leaves knowledge-base sections empty because this is a template; target repos fill them during their own sessions.

Agent harness compatibility

| Harness | Installed files | |---------|-----------------| | Codex / AGENTS-aware CLIs | AGENTS.md, .codex/config.toml | | Claude Code | CLAUDE.md, .claude/commands/, .mcp.json | | GitHub Copilot | .github/copilot-instructions.md, .github/instructions.md, .github/agents/, .github/skills/ | | Gemini CLI | .gemini/GEMINI.md | | Kimi | .kimi/mcp.json, .kimi-code/skills/, AGENTS.md | | Cursor | .cursor/rules/hot-set-template.mdc | | Shared automation | .githooks/, scripts/validate-agent-assets.mjs, scripts/graphify-mcp.mjs, scripts/refresh-graphs.mjs |

npm test installs the package into a temporary repository and verifies these files are present together, so future releases stay safe for multi-agent use.

1. Copy this template into your workspace

cp -r ./* <your-workspace>

2. Create your local dev configuration

cp local-dev-config.json.example local-dev-config.json

Edit local-dev-config.json with your project values.

3. Fill in the knowledge base placeholders

Open .github/copilot-instructions.md and replace all {{PLACEHOLDER}} markers:

| Placeholder | What to Fill In | Example | |-------------|-----------------|---------| | {{PROJECT_NAME}} | Full project name | Inventory Tracker | | {{PROJECT_SHORT_NAME}} | Short abbreviation | IT | | {{WORKSPACE_DIR}} | Workspace folder name | inventory-tracker | | {{WA_REPO_NAME}} | Next.js repo folder | inventory-tracker-web | | {{SUPABASE_URL}} | Deployed Supabase URL | https://xxxx.supabase.co | | {{CONVEX_URL}} | Deployed Convex URL | https://xxxx.convex.cloud | | {{DOMAIN_DESCRIPTION}} | One-line domain description | tracking warehouse inventory and shipments |

Tip: Ask Copilot to help — it reads .github/instructions.md and knows how to walk you through the setup.

4. Clone your repo and start developing

git clone <wa-repo-url> my-project-web

cd my-project-web
npm install
npm run dev     # Start Next.js and Convex locally

5. (Optional) Enable the knowledge graph

# Fast, always-on local code graph
codegraph install && codegraph init

# On-demand multimodal/visual knowledge graph
uv tool install 'graphifyy[mcp]' && graphify install && /graphify .
# The MCP config uses scripts/graphify-mcp.mjs so the graph path resolves from repo root.

MCP config templates ship in the repo: .mcp.json (Claude Code), .codex/config.toml (Codex), .kimi/mcp.json (Kimi). Shared agent instructions live in AGENTS.md (Codex + Kimi).

6. Enable local agent guardrails

git config core.hooksPath .githooks
node scripts/validate-agent-assets.mjs

The pre-commit hook runs the validator and markdownlint (when installed). The post-commit hook refreshes the knowledge graphs in the background so they stay current.

Architecture

┌───────┐     ┌──────────────────────┐     ┌──────────────────────────┐
│Browser │────▶│  Next.js Web App     │────▶│  Convex (Realtime DB)    │
│       │     │  (localhost:3000)     │     │  (localhost:3001)        │
└───────┘     └──────────────────────┘     └────────┬─────────────────┘
                                                │
                                           ┌────▼─────────────────┐
                                           │ Supabase (PostgreSQL)│
                                           │ (Auth / Storage / DB)│
                                           └──────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│              Multi-Agent Ecosystem (Claude / Copilot / Kimi / etc.)     │
│                                                                         │
│  copilot-instructions.md / CLAUDE.md / AGENTS.md / GEMINI.md           │
│    ├── §1–§3, §9  ◀── You fill in once                                  │
│    └── §5–§8      ◀── Auto-updated every session                        │
│                                                                         │
│  .github/agents/   → Specialized agents (.agent.md)                     │
│  .github/skills/   → Composable skills (SKILL.md)                       │
│  .kimi-code/skills/→ Kimi skills (SKILL.md)                             │
│  .claude/commands/ → Claude slash commands                              │
│  .cursor/rules/    → Cursor glob-scoped rules (.mdc)                    │
└─────────────────────────────────────────────────────────────────────────┘

Workspace Layout

workspace-root/
├── .github/
│   ├── copilot-instructions.md      ← Living knowledge base
│   ├── instructions.md              ← Setup guide with placeholders
│   ├── agents/                      ← Specialized AI agents
│   ├── skills/                      ← Composable skills (multiple categories)
│   └── workflows/                   ← CI checks
├── .kimi-code/skills/               ← Kimi skills (SKILL.md)
├── .claude/commands/                ← Claude slash commands
├── .cursor/rules/                   ← Cursor glob-scoped rules
├── .gemini/GEMINI.md                ← Gemini CLI knowledge base
├── <wa-repo>/                       ← Next.js + Convex app (own git repo)
├── local-dev-config.json            ← Local dev configuration
└── README.md

🤖 Agents Reference

All agent definitions live in .github/agents/. Each .agent.md file provides a system prompt and tool configuration for a specialized role.

Delegation rules and handoff packet formats live in docs/agent-operating-model.md.

| Agent | Purpose | File | |-------|---------|------| | Next.js & React Expert | Next.js 16 + React 19.2 — App Router, Server/Client Components, hooks, Actions, TypeScript | nextjs-react-expert.agent.md | | Convex Expert | Convex database development — schema, queries, mutations, Better Auth | convex-expert.agent.md | | Supabase Expert | Supabase storage and auth — buckets, uploads, signed URLs, RLS, Better Auth | supabase-expert.agent.md | | Fullstack Architect | Architecture expertise for Next.js, Convex, and Supabase | fullstack-architect.agent.md | | PostgreSQL DBA | PostgreSQL database administration (Supabase) | postgresql-dba.agent.md | | QA Subagent | Test planning, bug hunting, edge-case analysis | qa-subagent.agent.md | | Repo Architect | Bootstrap and validate agentic project structures | repo-architect.agent.md | | Transparent Thinking Mode | Step-by-step transparent reasoning with full cognitive visibility | Advanced-Reasoning.agent.md | | Codebase Cartographer | Builds, queries, and maintains the knowledge graph (codegraph + graphify); answers architecture/impact questions from the graph first | codebase-cartographer.agent.md |

🛠️ Skills Reference

All skill definitions live in .github/skills/, organized by category. Each SKILL.md provides trigger phrases, workflow instructions, and domain-specific rules.

Development

| Skill | Purpose | Triggers | |-------|---------|----------| | convex-db | Convex schema, CRUD, queries, mutations, Better Auth integration | convex schema, convex crud, add query, protect with auth | | supabase-storage-auth | Supabase storage and auth — buckets, uploads, RLS, OAuth | supabase bucket, supabase upload, supabase auth, storage rls | | wa-next-repo-dev | Next.js/Convex web app development — pages, components, CRUD | create page, add component, CRUD, frontend | | spec-driven | Spec-driven development in 4 adaptive phases | specify feature, design, tasks, implement | | code-navigation | Codebase pathfinding with persistent .notebook/ knowledge base | how does this work, investigate this flow | | git-commit | Conventional commit generation | commit changes, /commit | | codebase-cartographer | Build/query/maintain the knowledge graph; architecture & blast-radius answers | map the codebase, impact of changing, what calls this | | code-navigation (codenavi) | Graph-first pathfinder for bugs/features/refactors; .notebook/ knowledge base | fix this, how does this work, investigate this flow |

Kimi Skills (.kimi-code/skills/)

Kimi loads skills from .kimi-code/skills/. In addition to the graph-native skills above, the following Kimi-specific skills are available:

| Skill | Purpose | Triggers | |-------|---------|----------| | git-commit | Conventional commit generation and intelligent staging | commit changes, /commit | | spec-driven | Adaptive project/feature planning with persistent memory | specify feature, design, tasks, implement | | docs-writer | Write, review, and edit documentation | write documentation, review this doc, improve this README |

(Additional skills exist in Quality, Performance, Security, Decision-Making, and Web Automation folders under .github/skills/).

🧠 Knowledge Base

The self-updating knowledge base lives at .github/copilot-instructions.md. It has 9 sections with a clear division of responsibility:

Section Ownership

| Section | Purpose | Maintained By | |---------|---------|---------------| | § 1 · Project Identity & Architecture | Tech stack, workspace layout | You (once during setup) | | § 2 · Sub-Repo Instruction References | Links to sub-repo Copilot instructions | You (once during setup) | | § 3 · Cross-Repo Conventions | Domain model, API contracts, env vars | You (once during setup) | | § 4 · Self-Update Protocol | Rules governing Copilot's auto-updates | Never modified (built-in) | | § 5 · Lessons Learned | What works, what doesn't, gotchas | Copilot (every session) | | § 6 · Known Issues | Bug tracking with investigation status | Copilot (every session) | | § 7 · Current Status | What was accomplished this session | Copilot (every session) | | § 8 · Next Steps | Prioritized task list | Copilot (every session) | | § 9 · Quick Reference | Commands, DB tables, URLs | You (as needed) |

Self-Update Protocol

At the end of every coding session, Copilot overwrites §7 (Current Status) and §8 (Next Steps) with the latest state, appends to §5 (Lessons Learned) and §6 (Known Issues), and never deletes section headers or protocol rules.

⚙️ Configuration Reference

local-dev-config.json

| Field | Required | Description | |-------|----------|-------------| | projectName | No | Display name for your project | | waRepoPath | Yes | Web App repo folder name (relative to workspace root) |

Agent validation

node scripts/validate-agent-assets.mjs
node scripts/refresh-graphs.mjs

The validator checks GitHub agents, GitHub skills, Kimi skills, Claude command headers, mirrored graph-native skills, links to docs/agent-operating-model.md, and that the template knowledge-base sections are still empty.

refresh-graphs.mjs re-syncs codegraph and rebuilds graphify after structural changes. The .githooks/post-commit hook runs it in the background automatically when hooks are enabled.

NPM package scripts

npm run build
npm run lint
npm test

build validates the agent assets and verifies the npm package contents with npm pack --dry-run. lint runs the validator plus markdownlint. test installs the template into a temporary directory and validates the installed copy.

Publishing to npm

The package is published as hot-set. For a new release:

npm whoami
npm run build
npm run lint
npm test
npm version patch
npm publish --access public

Publishing requires an authenticated npm session. npm may open a browser-based authentication flow during publish. The prepublishOnly script runs npm run build && npm test automatically as a final safety check.

🔧 Customization

Adding a New Agent

Create a file in .github/agents/ with the .agent.md extension:

---
name: my-custom-agent
description: One-line description for agent discovery
tools: [list, of, tools]
---

# System Prompt

Your detailed agent instructions here...

Adding a New Skill

Create a SKILL.md file in the appropriate category folder under .github/skills/.

License

MIT License. See LICENSE.