From archkit
Initialize a new archkit project. Walks the user through picking an archetype (saas/internal/content/ecommerce/ai/mobile/realtime/data/_generic), choosing a deployment mode (managed or self-hosted), confirming category-by-category defaults, resolving current package versions via WebSearch, and writing the `.arch/` seed (SYSTEM.md, BOUNDARIES.md, INDEX.md, decisions/0001-foundation.md). Use this skill whenever the user runs `/archkit-init`, says "set up archkit" / "initialize archkit" / "scaffold a new project", or has just installed archkit and is asking how to start. Do not skip this skill in favor of writing files directly — the wizard's job is the deliberation, not just the file output.
How this skill is triggered — by the user, by Claude, or both
Slash command
/archkit:archkit-initThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **You are reading this file because you (the agent) were asked to set up archkit, or because you read this skill at the user's request. Reading this file IS how the wizard runs.** You do not need a slash command, a CLI runner, or any external trigger. You execute the wizard yourself by following the steps below: ask the user the questions the steps name, perform the file writes the steps name...
You are reading this file because you (the agent) were asked to set up archkit, or because you read this skill at the user's request. Reading this file IS how the wizard runs. You do not need a slash command, a CLI runner, or any external trigger. You execute the wizard yourself by following the steps below: ask the user the questions the steps name, perform the file writes the steps name, and call the MCP tools the steps name. Use AskUserQuestion for choice prompts, plain chat for clarifying questions, Read for additional context (especially the archetype skeletons), Write/Edit for the
.arch/seed files, WebSearch for version resolution, andarchkit_log_decisionfor the foundation ADR. There is no other invocation mechanism — you ARE the runtime.
This skill is the entry point to archkit. Your job is to help the user pick the right architectural foundation for their project and write a .arch/ seed they can grow into. The output is intentionally a seed, not a complete spec — stickiness comes from accumulated additions over time, not the initial scaffold.
The eight canonical archetype skeletons live at ${CLAUDE_PLUGIN_ROOT}/skills/archkit-init/skeletons/<archetype>.md (plugin install) or at <this-skill-file's-directory>/skeletons/<archetype>.md (npm install — derive from the file path you used to read this SKILL.md). Each skeleton is the source of truth for that archetype's defaults — read the relevant one in full before writing files.
Before anything else, call the archkit_prd_check MCP tool. It scans common locations (PRD.md, docs/PRD.md, BRIEF.md, SPEC.md, REQUIREMENTS.md, etc.) and returns a structured signal payload.
If prdFound: true:
prdPath. The keyword heuristic returns a useful signal but does not capture nuance — the model needs the actual text to reason well.recommendedArchetype and signals.deploymentMode. These are the heuristic's best guesses based on keyword density. They're inputs to the user's choice in steps 1 and 3, not substitutes for it.<path>. Based on its contents I'd recommend the <recommendedArchetype> archetype" — then walk through the rest of the wizard with the PRD as context. When you reach step 1 (archetype pick), present recommendedArchetype as the suggested default but let the user pick differently.findings includes an archetype_mismatch (only happens when .arch/SYSTEM.md already exists), surface it before the pre-flight overwrite question — the user may be re-running the wizard because the PRD has shifted and that should be acknowledged explicitly.If prdFound: false, proceed normally — the wizard works fine without a PRD; the user will describe the product in step 1.
Do not skip this step even if the user did not mention a PRD. Many vibe-coders do have one (or generated one with an LLM earlier) and forgot to mention it. The tool returns quickly when no PRD is present.
After the PRD check:
.arch/SYSTEM.md already exists in the user's project root..arch/ directory. Are you re-initializing (start over and overwrite), augmenting (skip writing files I'd overwrite), or did you mean to do something else?".arch/.If the user is genuinely starting fresh, proceed.
The eight canonical archetypes plus _generic:
Use the AskUserQuestion tool (or a numbered chat list) to let the user pick. For each option, show a one-line description from above. If the user is unsure, ask 2-3 clarifying questions about what they're building before steering them.
If step 0 returned a recommendedArchetype from a PRD, present it as the suggested default: "Based on your PRD, <archetype> looks right (<top matched keywords>). Accept that, or pick differently?" Most users will accept; trust the heuristic when the score is high (5+ matches).
If the user describes a hybrid (e.g. "a SaaS with an AI chatbot inside it"), pick the dominant archetype and treat the secondary as a feature inside it. SaaS-with-AI-feature is saas, not ai. Internal-tool-with-embedded-charts is internal, not data. Only pick _generic when no single archetype dominates.
Read the full file at ${CLAUDE_PLUGIN_ROOT}/skills/archkit-init/skeletons/<archetype>.md. Everything you need for the rest of the wizard is in there:
useWhen and redFlags — confirm the user is in the right archetypedeploymentModes — the next decisionstack, hosting, auth, networking, ui, jobs, observability, testing) — each has primary[] (some entries tagged with mode:), why, tradeoffsboundariesRef and recommendedSkills — used when writing BOUNDARIES.md and INDEX.mdDo not summarize the skeleton to the user. Use it to inform what you say next.
From the skeleton's deploymentModes block, present each mode (id, label, why paragraph). Ask the user to pick. Both modes are first-class — do not steer toward managed by default. The why paragraphs explain when each is right; let them speak.
If the user is unsure, ask:
Use answers to recommend a mode but let the user pick.
If step 0 returned a signals.deploymentMode, surface it: "Your PRD mentions <keywords like 'self-hosted', 'Kubernetes', 'data residency' OR 'Vercel', 'Supabase', 'Clerk'> which suggests <mode>. Confirm or override?" Only recommend strongly when the PRD's mode signal is unambiguous.
For each of stack, hosting, auth, networking, ui, jobs, observability, testing (in that order):
primary[] list by the chosen mode — entries with no mode tag apply in both modes; entries with mode: managed only apply if the user picked managed; same for selfHosted.role text. Show as a short bulleted list.why paragraph verbatim (it's the thought-layer voiceover the user is paying for).alt line (the documented alternatives)alt, name something else entirely, or drop the entrytradeoffs unless the user pushes back on the defaults. The tradeoffs paragraph is "when to override" content — surface it when override is on the table.Keep this phase fast. Eight categories × forty seconds is five minutes; eight categories × five minutes of debate is forty minutes and the user bounces. If the user accepts defaults the first time, accept them.
Per the no-version-strings-in-skeletons rule, the skeleton names packages but does not pin versions. Before writing SYSTEM.md, resolve each named package/framework to its current latest stable version using WebSearch.
Process:
primary[] after filtering and overrides, across all eight categories)."<package name> latest stable version" or visit the package's documentation/npm page.npm install [email protected], pip install dagster==1.10.0).Do not skip this step. Versions in SYSTEM.md should reflect what's current today, not what was current at training cutoff.
Create .arch/ and write four files. Use the templates in the appendix below. Fill in placeholders from the resolved choices in steps 3-5.
.arch/SYSTEM.mdThe foundation document. Narrative + bullets. See the SYSTEM.md template in the appendix. Replace {placeholders} with the user's resolved choices, including current versions from step 5.
.arch/BOUNDARIES.mdHard prohibitions — non-negotiable rules the AI must never violate. See the BOUNDARIES.md template in the appendix. The universal section is constant; the archetype-specific section should be derived from the chosen archetype's redFlags field plus the "concerns that dominate" section in the skeleton's markdown body. Translate each concern into a NEVER ... rule in active voice.
.arch/INDEX.mdTable of contents pointing to expandable directories. See the INDEX.md template in the appendix. Initial Skills → entries should be drawn from the skeleton's recommendedSkills list. Other sections start mostly empty and grow over time as the user adds clusters, APIs, and gotchas.
.arch/decisions/0001-foundation.md — via the MCP tool, not by writing the file directlyThis is the most important step. Call the archkit_log_decision MCP tool with the foundation decision. The tool writes the file in the canonical ADR format and assigns the 0001 number.
Call it like this:
archkit_log_decision({
title: "Foundation: <archetype> architecture in <mode> mode",
context: "<3-5 sentences explaining what the project is and the constraints we considered>",
decision: "<bulleted summary of the resolved stack across all 8 categories, with versions>",
consequences: "<3-5 sentences on what this commits us to, what becomes easier, what becomes harder>",
status: "accepted",
tags: ["foundation", "<archetype>", "<mode>"]
})
After the tool returns, tell the user about the precedent it sets: from this point forward, every non-trivial architectural decision (changing a database, adopting a new library, moving to a new auth provider) should be logged via archkit_log_decision. The .arch/decisions/ directory is the project's institutional memory across LLM context resets — it's how future sessions know why we made the choices we did.
If archkit_log_decision is not available (e.g. the user has installed only the CLI without the MCP server), fall back to writing the file directly using the template in the appendix.
Ask: "I can append a short archkit session protocol to your CLAUDE.md so every Claude Code session starts by warming up archkit context. Recommended but optional. Append?"
If yes, append the block from the CLAUDE.md augmentation template in the appendix. If CLAUDE.md doesn't exist yet, create it with just that block. If it exists, append at the bottom with a leading --- separator.
Do not modify other parts of an existing CLAUDE.md.
Tell the user what was written:
.arch/SYSTEM.md (the living foundation).arch/BOUNDARIES.md (immutable safety net).arch/INDEX.md (table of contents — grows over time).arch/decisions/0001-foundation.md (first ADR — sets the precedent)CLAUDE.md augmentation (if accepted)Then explain the loop they're now in:
archkit_resolve_scaffold for a checklistarchkit_resolve_preflight firstarchkit_gotcha_proposearchkit_log_decisionarchkit_review_stagedSuggest restarting Claude Code so the SessionStart hook picks up the new .arch/SYSTEM.md and starts injecting the archkit session protocol on every future session.
# SYSTEM.md
## App: {project-name}
## Type: {Archetype displayName}
## Mode: {managed | selfHosted}
## Stack: {one-line summary of resolved stack picks with versions}
## Pattern: {primary architecture pattern, e.g. "Layered (Cont→Ser→Repo) + Modular Monolith" for saas}
## Resolved choices
### Stack
{bulleted list — name @ version, role}
### Hosting
{bulleted list — name, role}
### Auth
{bulleted list — name, role}
### Networking
{bulleted list — name, role}
### UI
{bulleted list — name, role}
### Jobs
{bulleted list — name, role}
### Observability
{bulleted list — name, role}
### Testing
{bulleted list — name, role}
## Rules
{archetype-specific rules derived from the skeleton's body — e.g. for saas: "All DB queries include $tenant. RLS is the safety net, not the primary filter." Pull these from the relevant archetype's prose body, especially the "patterns that matter" section.}
## Reserved Words
{archetype-specific symbols — e.g. for saas: "$tenant, $auth, $err, $bus, $cache, $db, $zod, $rls, $queue". Define each.}
## Naming
Files: kebab-case | Types: PascalCase | Funcs: camelCase | Tables: snake_case | Env: SCREAMING_SNAKE
## On Generate
Before writing any file:
1. State the file path you intend to write to.
2. State which layer this code belongs to (controller / service / repo / etc.).
3. Reference $symbols for all dependencies.
4. Throw archetype-typed errors on failure paths.
5. Write the corresponding test.
## Session Protocol
- BEFORE any code generation in a new session: call `archkit_resolve_warmup`.
- If warmup returns blockers: FIX THEM before writing any code.
- BEFORE generating code for an existing feature: call `archkit_resolve_preflight <feature> <layer>`.
- BEFORE generating a new feature: call `archkit_resolve_scaffold <featureId>`.
- WHENEVER a non-trivial architectural choice is made: call `archkit_log_decision`.
- BEFORE each commit: call `archkit_review_staged`.
- WHEN you discover a pattern the AI gets wrong: call `archkit_gotcha_propose`.
# BOUNDARIES.md
> Hard prohibitions. The AI must NEVER violate these rules.
> These are non-negotiable constraints, not suggestions.
## Universal Boundaries
- NEVER commit secrets, API keys, or credentials to code. Use environment variables.
- NEVER use `any` type in TypeScript without a written justification comment.
- NEVER catch errors silently. Log or re-throw with context.
- NEVER use string concatenation for SQL queries. Use parameterized queries.
- NEVER trust client-side input. Validate at every untrusted edge with Zod (or equivalent).
- NEVER store passwords in plain text. Use bcrypt/argon2 with salt, or use a managed auth provider.
- NEVER disable CORS in production. Configure allowed origins explicitly.
- NEVER return stack traces or internal errors to the client in production.
- NEVER make a non-trivial architectural decision without calling `archkit_log_decision`.
## {Archetype}-Specific Boundaries
{Derive these from the chosen skeleton's `redFlags` and the "concerns that dominate" section of the skeleton body. Translate each concern into a NEVER rule in active voice. Example for saas:}
{- NEVER query the database without tenant scoping. Every query includes the tenant ID.}
{- NEVER use Row-Level Security as the primary filter. RLS is the safety net underneath explicit scoping.}
{- NEVER put business logic in controllers. Controllers validate, delegate, respond.}
{- NEVER access the database directly from controllers. Go through service → repository.}
{- NEVER create a new database client per request in serverless. Use a singleton.}
{etc.}
# INDEX.md
## Conv: {convention for feature file paths, derived from archetype}
## Shared: src/shared/{name}/index.ts | Jobs: src/jobs/{name}.ts (if applicable)
## Keywords → Skills
{For each entry in the skeleton's `recommendedSkills`, write one line:}
{<package-keywords> → $<package-name>}
## Skills → Files
{For each entry in the skeleton's `recommendedSkills`, write one line:}
{$<package-name> → .arch/skills/<package-name>.skill}
## Nodes → Clusters → Files
{Empty initially — grows as the user adds features.}
## Cross-Refs
{Empty initially — grows as the user adds inter-feature dependencies.}
## archkit Session Protocol (NON-NEGOTIABLE)
This project is managed by archkit. Before answering any question about project structure, conventions, or where code should go, call the archkit MCP tools — reading `.arch/*.md` directly returns raw markdown and partial context.
- **Session start**: call `archkit_resolve_warmup`. Fix any blockers before writing code.
- **New feature**: call `archkit_resolve_scaffold <featureId>` for the checklist.
- **Editing an existing feature**: call `archkit_resolve_preflight <feature> <layer>` before changes.
- **Non-trivial architectural decision**: call `archkit_log_decision` to record the ADR.
- **Bad pattern discovered**: call `archkit_gotcha_propose`.
- **Before commit**: call `archkit_review_staged`.
The `.arch/` directory holds this project's architecture spec. `.arch/decisions/` is the institutional memory across LLM context resets — when in doubt about why we made a choice, read the relevant ADR there.
archkit_log_decision MCP tool is not available)# 0001. Foundation: {Archetype displayName} architecture in {mode} mode
- **Date**: {YYYY-MM-DD}
- **Status**: Accepted
- **Tags**: foundation, {archetype}, {mode}
## Context
{3-5 sentences explaining what the project is and the constraints we considered.}
## Decision
{Bulleted summary of the resolved stack across all 8 categories, with versions.}
## Consequences
{3-5 sentences on what this commits us to, what becomes easier, what becomes harder.}
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub kenandrewmiranda/archkit --plugin archkit