Project Setup

<!-- MEMORY-CONTRACT v1 -->

Memory contract

Standing contract for every invocable command. Rendered once per command

file into the per-tool envelope by config-export command mode. Expresses

cross-session persistence in tool-neutral prose — it issues NO tool-specific

call, so it passes the export STRIP guard verbatim.

This command persists its work across sessions through engram, registered as an MCP server in this tool. Use this tool's own engram memory tools to honor the contract below — do not assume any other persistence layer.

Recall before acting

When the first input is a continuation keyword ("listo", "dale", "seguimos", "ready", "where did we leave off", "qué sigue"), DO NOT start fresh. First search engram for prior work on this change — by the change name and by recent topic keys — then summarize what you found and continue from there. Skipping the search and asking "what can I help with?" means you ignored existing context.

Validate after saving

After any save, verify it actually persisted: search engram back for the key or a unique phrase you just wrote. A tool response of "saved" is NOT proof the row landed. If the verifying search does not return the row, retry once; if it still fails, tell the user the save failed — never report "saved" on the tool response alone.

Summarize at close

Before ending a session, write a session summary to engram (goal, what was done, decisions, next steps, relevant files) so the next session can recover context. Recovery is never automatic — every session must search engram to find prior state.

When engram is unreachable

If engram is not installed or not on PATH, memory operations cannot persist. When that happens, emit a visible warning to the user that engram was not found (not installed / not on PATH) and that this session's work will NOT survive. DO NOT report memory as saved, and DO NOT proceed silently as if persistence had occurred. See the install prerequisite in the onboarding docs to enable engram.

Partial port. This command covers the tool-portable core of project setup:

stack detection plus an initial instruction-file scaffold. The full project

bootstrap — the project memory layer, cross-session persistence, the dedicated

memory directory, and the interactive instruction-file wizard — is specific to a

Claude Code installation and is NOT done here; see "Not ported" at the end. A

scaffold from this command is a starting point, NOT a complete project setup.

Purpose

project-setup inspects the current project, infers its stack and conventions, and emits an initial AI instruction file for the tool it runs in — the single file that tool reads for project context. It is a starting scaffold: it gives a new project a first, accurate instruction file derived from real detected signals, which the user then refines. It does not deploy a memory layer or persist anything across sessions.

---

Process

Step 0 — Detect the tool and its instruction file

Identify the instruction file this command writes, by tool:

• GitHub Copilot: .github/copilot-instructions.md
• Gemini CLI: GEMINI.md
• Codex CLI: AGENTS.md

If an instruction file already exists for the active tool, STOP and ask the user to choose: (1) review the existing file, (2) overwrite it with a fresh scaffold (destructive), or (3) cancel. Only proceed past this point on an explicit overwrite or when no instruction file exists.

Step 1 — Detect the stack

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

Also infer, from the same files and the folder layout:

• Main language and version.
• Framework(s) in use.
• Test / lint / build commands (e.g. from package.json scripts, a Makefile, or

the language's standard tooling).

• Folder-structure style (feature-based, layer-based, monorepo).
• Naming conventions visible in the source (camelCase, snake_case, …).

If no stack indicator is found, say so plainly and scaffold a minimal instruction file with the sections present but the stack fields left for the user to fill.

Step 2 — Scaffold the instruction file

Produce a draft instruction file with these sections, filled from Step 1 detection:

# [Project Name]

## Stack

[Detected language + version, framework(s), database/ORM if detected]

## Architecture

[Detected folder-structure style and architectural pattern]

## Conventions

[Detected naming conventions and observed code patterns]

## Commands

[Install / dev / test / lint / build commands detected]

Show the rendered draft in full and ask for confirmation before writing (confirm / edit a section / cancel). On edit, ask which section, revise, and re-show. Write the file only on explicit confirmation. Drop any section that detection left empty rather than writing a hollow placeholder.

This step scaffolds a STARTING instruction file from detected signals. It does not generate the tool's full, exhaustive instruction content — refining and extending the file is the user's job after the scaffold lands.

Step 3 — Print the not-ported reminder

After writing, print a short reminder that this was a partial setup: the stack scaffold is in place, but the full project bootstrap (the project memory layer, cross-session persistence, the dedicated memory directory, and the interactive instruction-file wizard) is available only via the Claude Code project-setup. Run that from a Claude Code session to complete the setup.

---

Not ported

These parts of the full project setup have no analog in this tool and are NOT done by this command. They are specific to a Claude Code installation:

• Template resolution from the Claude config home — the full setup reads a

project instruction template from the Claude user configuration directory; this tool has no such shared template store.

• Cross-session memory persistence — the full setup records the project context

in the Claude persistent-memory layer so later sessions can recover it; this tool has no equivalent persistence backend.

• Project memory directory — the full setup initializes a dedicated project

memory directory of context files (stack, architecture, conventions, known issues, change history); this tool has no consumer for that directory.

• Interactive instruction-file wizard — the full setup offers a guided,

question-by-question wizard that produces the Claude project instruction file; this command emits a single non-interactive scaffold instead.

To get the full setup, run the Claude Code project-setup from a Claude Code session.

---

Rules

• Write exactly one file: the active tool's instruction file. Never touch any other

file.

• Never overwrite an existing instruction file without explicit user confirmation.
• Scaffold from REAL detected signals — never invent a stack, framework, or command

that the project does not show.

• Always print the not-ported reminder — a partial setup MUST declare what it did

not cover, so the user knows the scaffold is a starting point, not a complete setup.

• Keep the scaffold lean: drop empty sections rather than writing hollow placeholders.
• Recommend and scaffold only — do NOT attempt to render the tool's full instruction

content; that is a separate export concern.