SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsproject-setup

project-setup

Agents & models

View repository

Updated 10-15 21:41

About this skill

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:

  1. CLAUDE.md at the project root with real detected context
  2. ai-context/ with the 5 memory files initialized
  3. Engram project context for the SDD cycle
  4. 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

If CLAUDE.md already exists at CWD root, STOP and ask:

A CLAUDE.md already exists. Choose one:

  1. Audit the existing file with /config-audit (recommended).
  2. Overwrite with a fresh template (destructive).
  3. 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/... or ~/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)

y → write. edit → ask which section, loop back. n → 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.