project-setup

Deploys the complete SDD architecture with engram persistence and ai-context/ memory layer in the current project.

Triggers:

/project-setup

/project-setup --interactive

, initialize project, setup sdd, configure claude project, new sdd project, bootstrap claude, create project CLAUDE.md

What this skill does

When the user runs

/project-setup

, I analyze the current project and generate:

```
CLAUDE.md
```
at the project root with real detected context
```
ai-context/
```
with the 5 memory files initialized
Engram project context for the SDD cycle
Registry of relevant skills based on the detected stack

Process

Step 0 — Mode select

project-setup

runs in one of two modes:

Automatic (default) — zero-question full deploy. Detect the stack and generate
```
CLAUDE.md
```
+ the five
```
ai-context/
```
files + engram context. This is the behavior when the user runs
```
/project-setup
```
with no mode flag. Proceed to Step 1.
Interactive — a guided wizard that produces ONLY a project
```
CLAUDE.md
```
(no
```
ai-context/
```
deploy), with stop-between-question confirmation. Triggered when the user runs
```
/project-setup --interactive
```
,
```
/project-setup wizard
```
, or explicitly asks to be walked through CLAUDE.md creation. Jump to Interactive mode below and do NOT run Steps 1-5.

Pick the mode from the invocation. If ambiguous, ask once which mode the user wants, then proceed. The two modes never run in the same invocation.

Interactive mode

A guided, confirmation-gated wizard that creates exactly one file: the project

CLAUDE.md

. Runs ONLY the steps below — it never falls through to the automatic Steps 1-5.

I0 — Refuse to run in the wrong context

This mode is for projects OTHER than the

claude-config

repo. Refuse and stop if any of these is true:

CWD basename is
```
claude-config
```
or
```
agent-config
```
.
CWD contains both
```
install.sh
```
and
```
skills/_shared/
```
.

Print:

This mode is for external projects. The claude-config repo edits its own CLAUDE.md directly.

and stop.

I1 — Check for existing

CLAUDE.md

CLAUDE.md

already exists at CWD root, STOP and ask:

A
CLAUDE.md
already exists. Choose one:
Audit the existing file with
/config-audit
(recommended).
Overwrite with a fresh template (destructive).

Cancel.

Wait for the answer. Only proceed if the user explicitly picks overwrite.

I2 — Locate the template

Read

~/.claude/docs/templates/project-claude-template.md

. If missing, fall back to the repo path if the user has the

claude-config

repo cloned locally (

~/agent-config/docs/templates/...

~/claude-config/docs/...

If neither path resolves, STOP and tell the user to run

install.sh

from

claude-config

on this machine first.

I3 — Detect stack signals

Scan the project root (one level deep) for stack indicators:

File present	Stack hint
`package.json`	Node.js. Read `dependencies` to refine: next, react, vue, svelte, express, fastify, nest.
`pyproject.toml` / `requirements.txt`	Python.
`go.mod`	Go.
`Cargo.toml`	Rust.
`pom.xml` / `build.gradle`	Java/Kotlin.
`Gemfile`	Ruby.
`composer.json`	PHP.
`mix.exs`	Elixir.

Also detect test/lint/build commands. Cache the detected signals — they prefill answers in I4 but do NOT bypass user confirmation.

I4 — Ask the 5 wizard questions

Ask one at a time. STOP after each.

Q1 — Stack description: one-line stack description (prefilled from detection — confirm or edit).

Q2 — Conventions: what conventions does this project enforce that the global layer does not cover? 1-5 bullets, or "none".

Q3 — Commands: Install / Dev / Test / Lint / Type check / Build (prefilled from

package.json

scripts where available; leave blank to skip).

Q4 — Domain glossary: non-obvious domain terms that affect code reading (e.g. "Wallet", "Reconciliation", "Tenant"). 0-10 terms with one-line definitions, or "none".

Q5 — Overrides global: any global rule to override for this project? Name the rule and the reason, or "none" — overrides should be rare and deliberate.

I5 — Render preview

Use the template skeleton. Fill placeholders with the answers. Drop any section answered "none" or blank. Show the rendered file in a fenced code block. Ask:

Confirm to write
CLAUDE.md
at the project root? (y / edit / n)

→ write.

edit

→ ask which section, loop back.

→ abort.

I6 — Write

Write

CLAUDE.md

at CWD root. Do NOT touch any other file. Keep the file under 60 lines — empty sections are dropped, not preserved.

I7 — Post-write checklist

Print:

Created: CLAUDE.md (<N> lines).

Recommended next steps:
  1. Review the file.
  2. Run /config-audit from this directory to check cross-layer duplication.
  3. Commit the file.

Reminders:
  - This file is the project layer. The global layer (from claude-config)
    still applies in every session.
  - Do not restate global rules here. Use the "Overrides global" section to
    deviate.

I8 — Save to engram

Call

mem_save

title:

Initialized CLAUDE.md for <project name>

type:
```
config
```
topic_key:
```
project-init/<project-name>
```
content: structured What/Why/Where/Learned with the 5 wizard answers.

Interactive mode ends here. Do NOT continue to Step 1.

Step 1 — Project detection

I read and analyze:

package.json

pyproject.toml

go.mod

Cargo.toml

pom.xml

Folder structure (src/, app/, lib/, tests/, etc.)
Configuration files (tsconfig, eslint, prettier, etc.)
README.md if it exists
Existing docs folders
```
.git/
```
to confirm it is a repository

I infer:

Main language and version
Framework(s) in use
Database / ORM
Testing tools
Build / bundler tools
Detected naming conventions (camelCase, snake_case, etc.)
Folder structure (feature-based, layer-based, monorepo, etc.)

Step 2 — Generate the neutral instruction source (

AGENTS.md

+ Claude shim)

The source-of-truth is the provider-neutral AGENTS.md
(the cross-tool standard read natively by Copilot, Cursor, Gemini, Codex — see

core/PORTABILITY.md

§ Audience/source). I create

AGENTS.md

at the root using the "Project instruction skeleton (Step 2)" section of

AI_CONTEXT_TEMPLATES.md

. Fill every placeholder with real detected context — never ship a placeholder unresolved.

Claude reconciliation (mandatory): Claude Code reads

CLAUDE.md

, not

AGENTS.md

. So I ALSO write a 1-line

CLAUDE.md

shim whose only content is the import directive:

@AGENTS.md

This keeps

AGENTS.md

the single hand-authored truth while Claude Code loads it via import. (Symlink is an alternative but needs Admin/Developer Mode on Windows — the import shim is the cross-platform default.) If a legacy

CLAUDE.md

already holds real content, I migrate its content into

AGENTS.md

and replace it with the shim — I never leave two divergent sources.

Step 3 — Initialize ai-context/

I create the 5 files with real content based on what was detected, using the "
ai-context/
files (Step 3)" section of

AI_CONTEXT_TEMPLATES.md

stack.md

architecture.md

conventions.md

known-issues.md

changelog-ai.md

. Each template's placeholders are filled from Step 1 detection;

[date]

is today's date.

Step 4 — Persist project context to engram

Check if Engram MCP is reachable (call

mem_context

If reachable: save project context to engram via
```
mem_save
```
with
```
topic_key: project-setup/{project-name}
```
. Log
```
INFO: Engram detected — project context persisted to engram
```
. (Distinct from
```
sdd-init/{project-name}
```
, which
```
sdd-init
```
owns — using a separate key prevents an upsert collision where one skill overwrites the other's project-context pointer.)

If not reachable: log

WARNING: Engram not available — project context not persisted. SDD artifacts will be ephemeral.

Step 5 — Final report

I present to the user:

✅ Project configured: [name]

Detected stack:
  - [language + version]
  - [framework + version]
  - [testing framework]

Files created:
  - CLAUDE.md
  - ai-context/stack.md
  - ai-context/architecture.md
  - ai-context/conventions.md
  - ai-context/known-issues.md
  - ai-context/changelog-ai.md

Next steps:
  1. Review and adjust CLAUDE.md with details I could not detect
  2. To start a change: /sdd-explore <topic> or /sdd-propose <change-name>
  3. To create project-specific skills: /skill-create <name>

Rules

NEVER overwrite existing files without warning and asking for confirmation
If
```
CLAUDE.md
```
already exists, I offer an intelligent merge or creating a backup
If
```
ai-context/
```
already exists, I offer to update only what is missing
I always read real code — I never invent the stack
If I cannot determine something with certainty, I mark it as
```
[To confirm]
```
NEVER create a
```
.claude/commands/
```
directory — commands/ is a legacy mechanism;
```
.claude/skills/
```
is the only supported extensibility path for new projects.

Interactive mode rules

NEVER run interactive mode in the
```
claude-config
```
/
```
agent-config
```
repo. That repo edits its own
```
CLAUDE.md
```
directly.
NEVER overwrite an existing
```
CLAUDE.md
```
without explicit user confirmation.
Interactive mode writes exactly one file:
```
<cwd>/CLAUDE.md
```
. Never write outside CWD in this mode, and never deploy
```
ai-context/
```
from interactive mode.
NEVER restate global rules in the generated file. If the user offers global rules during the wizard (response format, verification, engram), refuse and point to the global layer.
Stop after every wizard question. Never bundle. Never default silently.
Keep the generated file under 60 lines. Empty sections are dropped.
Do not commit and do not run any audit automatically — those are the user's decisions.

project-setup

NPX Install

Tags

SKILL.md Content

project-setup

What this skill does

Process

Step 0 — Mode select

Interactive mode

I0 — Refuse to run in the wrong context

I1 — Check for existing
`CLAUDE.md`

I2 — Locate the template

I3 — Detect stack signals

I4 — Ask the 5 wizard questions

I5 — Render preview

I6 — Write

I7 — Post-write checklist

I8 — Save to engram

Step 1 — Project detection

Step 2 — Generate the neutral instruction source (
`AGENTS.md`
+ Claude shim)

Step 3 — Initialize ai-context/

Step 4 — Persist project context to engram

Step 5 — Final report

Rules

Interactive mode rules

project-setup

NPX Install

Tags

SKILL.md Content

project-setup

What this skill does

Process

Step 0 — Mode select

Interactive mode

I0 — Refuse to run in the wrong context

I1 — Check for existing CLAUDE.md

I2 — Locate the template

I3 — Detect stack signals

I4 — Ask the 5 wizard questions

I5 — Render preview

I6 — Write

I7 — Post-write checklist

I8 — Save to engram

Step 1 — Project detection

Step 2 — Generate the neutral instruction source (AGENTS.md + Claude shim)

Step 3 — Initialize ai-context/

Step 4 — Persist project context to engram

Step 5 — Final report

Rules

Interactive mode rules

I1 — Check for existing
`CLAUDE.md`

Step 2 — Generate the neutral instruction source (
`AGENTS.md`
+ Claude shim)