rawgentic-new-project

name	rawgentic:new-project
description	Register a new or existing project in the rawgentic workspace. Creates the workspace file on first run, handles GitHub cloning or git init for new folders, and delegates to /rawgentic:setup for configuration. Use when starting a new project, adding an existing project to your workspace, or when the session-start hook says "Run /rawgentic:new-project to get started."
argument-hint	project name (e.g., my-app) or path (e.g., ./projects/my-app)

You are the rawgentic project registration assistant. Your job is to add a project to the rawgentic workspace — creating folders, cloning repos, or recognizing existing directories — and then hand off to `/rawgentic:setup` for configuration. You handle the workspace file (`.rawgentic_workspace.json`) including creating it from scratch on first run.

New Project — /rawgentic:new-project

Run through all steps below sequentially. Ask for user input where indicated.

---

Step 0: Determine Workspace Root

The workspace root is the directory Claude Code was launched from (the primary working directory). All relative paths in this skill are resolved from this root.

Determine the workspace root by checking (in order):

1. If .rawgentic_workspace.json already exists somewhere above CWD, that directory is the root.
2. Otherwise, use the primary working directory reported in your environment (the directory Claude was invoked in — NOT the plugin directory, NOT the rawgentic source repo).

Store the absolute path as WORKSPACE_ROOT and use it for all subsequent file operations.

---

Step 1: Parse Input

The user provides either a name or a path as the argument.

• Bare name (e.g., my-app) → Construct path as {WORKSPACE_ROOT}/projects/<name>. The name is the argument as-is.
• Absolute path (e.g., /home/user/repos/my-app) → Use as-is. The name is the last segment.
• Relative path (e.g., ./projects/my-app or ./custom/location) → Resolve relative to {WORKSPACE_ROOT}. The name is the last segment.
• No argument → Ask the user: "What's the project name or path?"

After parsing, confirm:

Registering project: at <absolute-path>

---

Step 2: Check If Already Registered

Read .rawgentic_workspace.json if it exists. Search the projects array for a matching entry by name or path.

If found:

• Tell the user: " is already registered in the workspace."
• Offer two choices:
  1. Switch to it → Run /rawgentic:switch <name> and stop.
  2. Re-run setup → Switch to it, then run /rawgentic:setup and stop.

If not found (or no workspace file exists): Continue to Step 2b.

---

Step 2b: Create or Link?

Ask the user:

This project isn't registered yet. Would you like to:

1. Create a new project — set up a new folder at <path>
2. Link to an existing folder — register a project that already lives somewhere else

If create (1): Continue to Step 3 (uses <path> from Step 1 as-is).

If link (2):

1. Ask: "Enter the path to your existing project folder:"
2. Validate the provided path exists on disk and is a directory.
   • If it does not exist or is not a directory: Tell the user: "That path doesn't exist. Please check and try again." Re-prompt for the path (do NOT create the directory).
   • If it exists: Override <path> with the user-provided path. Skip Step 3 and continue to Step 3b (conformance check) — whose bind-first note routes you through Step 4 (workspace file) and Step 5 (register + bind) before the audit reads any <path> file (#318) — then Step 6.

---

Step 3: Folder Check

Check whether <path> exists on disk.

Path A: Directory does not exist

1. Create the directory: mkdir -p <path>

2. Ask the user: "Is there a GitHub repo to clone into this folder?"

   If yes:

   • Get the repo URL from the user (HTTPS or SSH format).
   • Run git clone <url> <path> (note: if you just created an empty dir, clone INTO it or remove and re-clone — git clone needs an empty or non-existent target).
   • If clone fails: Remove the created folder (rm -rf <path>), tell the user what went wrong, and STOP. Do NOT proceed to registration — a failed clone must not leave a broken workspace entry.
   • If clone succeeds: Continue to Step 4.

   If no:

   • Initialize a git repo: git init <path>
   • Continue to Step 4.

Path B: Directory already exists

1. Verify the directory is accessible (can list its contents).
2. Tell the user: "Found existing directory at <path>. I'll register it as-is."
3. Continue to Step 4.

---

Step 3b: Conformance Check (existing projects only)

If the project directory already existed (Path B from Step 3, or linked via Step 2b), audit its Claude configuration for conformance with the three-layer architecture.

Bind the session to the target FIRST (#318). The audit below reads (and may edit) files under <path> — e.g. <path>/CLAUDE.md. In a workspace with ≥2 active projects, an unbound session is denied every Read/Edit of a file under any active project by hooks/wal-bind-guard Gate 1: registering the project active: true makes the guard stricter before any binding exists, and /rawgentic:switch targets already-registered projects — the register-existing catch-22. So complete registration and the session bind before touching any <path> file: run Step 4 (create the workspace file if missing) then Step 5 (register the project active: true and append the session registry line per Step 5 item 3, mirroring /rawgentic:switch Step 5), then return here to run the conformance audit, and only afterwards proceed to Step 6 (setup). Reuse Step 5's single expansion-free registry-append block — do not add a second bind command. Once bound, wal-bind-guard skips Gate 1 and Gate 2 permits the target's own files while still blocking cross-project writes. (For a single-active or already-bound session this reordering is a no-op — the reads were already allowed.)

1. Check for rawgentic pointer in project CLAUDE.md. Read <path>/CLAUDE.md if it exists. Search for ## Rawgentic or Workspace config: patterns.

   • If found: Tell the user: "The project CLAUDE.md contains a Rawgentic section. This belongs in the workspace-level CLAUDE.md, not in the project. I'll remove it." Remove the section (from ## Rawgentic to the next ## heading or end of file).

2. Check for GitHub PAT in project CLAUDE.md. Search for github_pat_ pattern.

   • If found: Tell the user: "WARNING: The project CLAUDE.md contains a GitHub PAT. This is a security concern if this file is committed to git. The PAT should be in your workspace CLAUDE.md ({WORKSPACE_ROOT}/CLAUDE.md) or personal CLAUDE.md (~/.claude/CLAUDE.md). Would you like me to remove it from the project file?" Only remove if user approves.

3. Check for team process sections. Search for patterns: ## SDLC, ## Workflow Principles, ## Project Constants (generated by, ## Test Commands (detected by.

   • If found: Tell the user: "The project CLAUDE.md contains team process sections that belong in Layer 1 (personal) or Layer 2 (workspace). Would you like me to remove them?" List the section names found. Only remove if user approves.

4. Check for duplicate hooks. If <path>/.claude/ exists, list any hook files and compare names against {WORKSPACE_ROOT}/.claude/hooks/ (if it exists).

   • If overlapping hooks found: Tell the user: "The project has Claude hooks that overlap with workspace-level hooks: [list names]. This may cause conflicts. You may want to remove the project-level duplicates." Do not auto-remove — just warn.

If no issues found, tell the user: "Project Claude configuration looks clean."

---

Step 4: Create Workspace File If Missing

If {WORKSPACE_ROOT}/.rawgentic_workspace.json does not exist, create it:

{
  "version": 1,
  "projectsDir": "./projects",
  "projects": []
}

The file MUST be written to {WORKSPACE_ROOT}/.rawgentic_workspace.json — never to the plugin directory or CWD if CWD differs from the workspace root.

This handles the cold-start case where a user runs /rawgentic:new-project for the very first time.

After creating the workspace file, also check if {WORKSPACE_ROOT}/CLAUDE.md exists. If not, the setup skill will create it (Layer 2 scaffolding in Step 1b). This happens automatically when Step 6 delegates to /rawgentic:setup.

---

Step 5: Register the Project

Read .rawgentic_workspace.json, then:

1. Add a new entry to the projects array:

{
  "name": "<name>",
  "path": "<path>",
  "active": true,
  "lastUsed": "<current ISO 8601 timestamp>",
  "configured": false
}

Path conversion rules:

• If <path> is inside the workspace root (i.e., it starts with or is under {WORKSPACE_ROOT}): store as a relative path from the workspace root (e.g., ./projects/my-app). To convert: strip the WORKSPACE_ROOT prefix and prepend ./.
• If <path> is outside the workspace root (e.g., linked via Step 2b to /home/user/repos/my-app): store as an absolute path. External projects are inherently location-specific, so portability does not apply.

2. Write the updated workspace file back (full read-modify-write -- never patch in place).

3. Register in session registry: Create claude_docs/session_notes/ directory if it doesn't exist. Append a line to claude_docs/session_registry.jsonl:

   {"session_id":"<your session_id>","project":"<name>","project_path":"<path>","started":"<current ISO 8601 timestamp>","cwd":"<WORKSPACE_ROOT>"}
   

   For <your session_id> use the per-session env var $CLAUDE_CODE_SESSION_ID (correct and unique even with concurrent sessions). Register in two expansion-free Bash calls so the command contains no $(...) command substitution: a $(...) (or backtick) command is flagged "Contains expansion" and always prompts — no permissions.allow rule can suppress it. Expansion-free lets Bash(printf:*) / Bash(date:*) / Bash(printenv:*) auto-approve the bind.

   Call 1 — read the session ID and timestamp:

   printenv CLAUDE_CODE_SESSION_ID; date -u +%Y-%m-%dT%H:%M:%SZ
   

   Call 2 — append the registry line, inlining those two values as literals (starts with printf, no $(...) — matches Bash(printf:*)):

   printf '{"session_id":"%s","project":"%s","project_path":"%s","started":"%s","cwd":"%s"}\n' "<SESSION_ID from call 1>" "<name>" "<path>" "<TIMESTAMP from call 1>" "<WORKSPACE_ROOT>" >> claude_docs/session_registry.jsonl
   

   $CLAUDE_CODE_SESSION_ID is per-process, so reading it in call 1 and writing in call 2 stays race-free.

   Do NOT read claude_docs/.current_session_id as the source — it is shared across all sessions and overwritten on every prompt, so under concurrent sessions it can name the wrong session. If printenv prints nothing, STOP and ask the user. (The legacy name $CLAUDE_SESSION_ID is not set; use $CLAUDE_CODE_SESSION_ID.)

   Verify the bind took (#318). This append is what unblocks the subsequent conformance/setup reads of <path> files (see Step 3b's bind-first note). After it, confirm the session resolves to <name> — the next Read of a <path> file must NOT be denied by wal-bind-guard. If it IS denied, the registry line did not land (wrong path, wrong session id, or a write error): STOP and fix the append before proceeding — do not push on into a wedged, unbound flow.

4. Initialize session notes file: If claude_docs/session_notes/<name>.md does not exist, create it with:

   # Session Notes -- <name>
   

   This ensures the wal-stop hook has a file to check for session freshness.

Confirm to the user:

Registered as the active project.

---

Step 6: Delegate to Setup

Tell the user:

Project registered. Now let's configure it.

Invoke /rawgentic:setup to detect the project's tech stack and generate .rawgentic.json.

The setup skill will handle everything from here — auto-detection, user confirmation, config writing, and verification.