Project Initializer

Project Initializer

Create a new project with memory structure for the 3-phase workflow.

Activation

Activate when you detect:

• "Start new project" or "Initialize project X"
• /ai-dev-assistant:new command
• Beginning development work that needs tracking

Workflow

1. Get Project Name

Ask:

What should this project be called?
(lowercase, letters, numbers, underscores only)

Validate the name matches pattern ^[a-z][a-z0-9_]*$. If invalid, ask again.

2. Get Storage Location

Read the registry at ~/.claude/ai-dev-assistant/active_projects.json. Check if projectsBase is set.

If projectsBase exists — use it as default:

Where should project files be stored?

Default: {projectsBase}/{project_name}/

Options:
1. Accept default
2. Enter custom path

Your choice:

If projectsBase is NOT set (first-time setup) — ask:

Where do you keep your project memory files?
This folder will store architecture docs, task files, and project state.

Enter the base path (all projects will be created as subfolders here):

Save the chosen base path as projectsBase in the registry (see Step 7).

Convert relative paths to absolute. Store the full path.

3. Check Path

Use Bash to check if folder exists:

ls -la {chosen_path}

If exists, ask: "Folder exists. Overwrite, use different name, or cancel?"

4. Create Structure

Use Bash to create folders:

mkdir -p {path}/{project_name}/architecture
mkdir -p {path}/{project_name}/implementation_process/in_progress
mkdir -p {path}/{project_name}/implementation_process/completed

5. Create project_state.md

Use Write tool to create {path}/{project_name}/project_state.md:

# {Project Name}

**Created:** {YYYY-MM-DD}
**Status:** Initializing
**Path:** {full_path_to_project_folder}
**Code path:** {absolute_code_path OR (docs-only) OR omit-entirely-if-caller-did-not-provide}
**Frameworks:** {when code path is known: name the stack with the cascade in `references/framework-resolution.md` (facts from `bash "${CLAUDE_PLUGIN_ROOT}/scripts/framework-evidence.sh" "<code_path>"`, then `bash "${CLAUDE_PLUGIN_ROOT}/scripts/framework-support.sh" "<slug>"` per framework named, for what the catalogs carry) and write the slugs comma-joined (e.g. `drupal, nextjs, claude-code-plugins`); omit this line entirely when code path is unknown or the cascade names no framework}
**Run Mode:** interactive
**Review Required:** true
**Worktree By Default:** false

## Overview
{To be filled during requirements gathering}

## Scope
This project includes:
- {To be defined}

## Requirements
{Populated by requirements-gatherer}

## Current Implementation Task
Working on: None - define tasks after requirements are gathered
File: -

## Up Next
Queued: {candidate first tasks once requirements surface them; see step 10(c)}

## Completed Implementation Tasks
{Empty initially}

## Key Decisions
{Empty initially}

## Current Focus
Initial setup - gathering requirements

Notes:

• Always write **Review Required:** true. When the line is absent, /complete falls back to the pre-4.1.0 posture and never requires a review — so a project created without it silently opts out of the thing the framework exists to do, and nobody chose that. Measured on a real project: ten days old, the field unset, review not required. A new project starts with the promise on; turning it off is a decision someone makes, not a default nobody sees.
• Never write an empty or placeholder **Frameworks:** line. The reader treats absence as []. Only write the line when the cascade named at least one framework.
• The project does NOT have a phase. Each TASK has its own phase (Research → Architecture → Implementation)
• Multiple tasks can be in implementation_process/in_progress/ simultaneously
• Task files in in_progress/ contain the task's current phase and progress
• Move completed task files to implementation_process/completed/

6. Create Empty architecture/main.md

Use Write tool:

# {Project Name} Architecture

{To be designed in Phase 2}

7. Register Project

Add project to the registry at ~/.claude/ai-dev-assistant/active_projects.json.

First, ensure the directory exists:

mkdir -p ~/.claude/ai-dev-assistant

Then read existing registry (or create new if doesn't exist) and add the project:

Registry Schema:

{
  "version": "1.1",
  "projectsBase": "{user's chosen base path for all projects}",
  "projects": [
    {
      "name": "{project_name}",
      "path": "{full_path_to_project}",
      "codePath": "{absolute path to code OR null}",
      "created": "{YYYY-MM-DD}",
      "lastAccessed": "{YYYY-MM-DD}",
      "status": "active"
    }
  ]
}

• projectsBase — set once on first project creation, reused as default for all future projects
• path — always the full absolute path to the specific project folder (memory folder)
• codePath — (added v3.11.0) absolute path to the code being worked on. null for docs-only projects. Optional; pre-v3.11.0 entries without it treated as "unknown" and trigger the first-use detect+confirm flow when a feature needs code. Source of truth is project_state.md; this is the cache.
• No phase field — phase is tracked per-task in task files, not per-project

Use Read to load existing registry, then Write to save updated version with new project appended.

If registry doesn't exist, create it with projectsBase and this project.

8. Invoke Requirements Gatherer

After structure is created, invoke requirements-gatherer skill to populate requirements.

9. Confirm

Show user:

Project initialized at: {full_path}

Created:
- project_state.md
- architecture/main.md
- implementation_process/in_progress/
- implementation_process/completed/

Next: Answer requirements questions to complete Phase 1 setup.

10. After Requirements Gathered

Once requirements-gatherer completes and user confirms, show — in order:

(a) Recipe-adoption sweep — resolve the stack's phase methods once, now. When **Frameworks:** is non-empty, run the sweep documented at commands/upgrade-project.md step 4b and in references/recipe-adoption-sweep.md: drive process-recipe-loader once per applicable phase (research, design, implement, review, e2e-setup, visual-regression), record each source= decision in the **Process Recipes:** block, and print the coverage map. Recording and visibility only — it never reads or follows a recipe body, never pre-caches, never approves an unverified recipe, and never prompts; every miss is simply "no recipe yet". Skip silently when frameworks are empty.

This sweep already existed and ran only in /upgrade-project, which meant a project retrofitted from an older version got its phase methods mapped in one pass while a project created today discovered them one at a time, per phase, per task, forever — and never saw which phases have no method at all. Creation is where that map is worth having, because it is what shapes every later phase.

Report the gaps as gaps. A phase with no recipe is not a failure and must not read as one, but it must be visible: name the uncovered phases in the printed map so the user knows where the framework has no stack-specific method and can decide whether to write one. Do not offer to author a recipe here and do not hand off — this step records and shows, nothing more.

(b) Playbook-config nudge (v4.2.2+ — single source of truth). Print one line before the /next hint:

💡 Optional next step: configure your playbook before the first task.
   /ai-dev-assistant:set-playbook-sets — choose opinion-set(s) (default: <framework>/best-practices/<author>)
   /ai-dev-assistant:set-user-playbook — point at a project-local playbook.md
   Playbook loads at every phase entry; configuring now means your first task gets the active opinion-set
   from the start. Skip if you want plain dev-guides only — /next will re-surface this nudge.

This nudge is the canonical surface for new-project playbook discoverability — /new and /next (inline-create path) both invoke this skill, so the nudge fires for every caller. Do NOT duplicate this text in caller commands.

(b2) Task-rule offer — put the rule where a session reads it as an instruction.

Offer once, right after the playbook nudge, when **Code path:** is known:

💡 Optional: write the "work here goes through a task" rule into <codePath>/CLAUDE.md.
   A session-start message is context; CLAUDE.md is an instruction the harness says to follow.
   It does not force a task on small work — it stops the choice being made silently.
   Install it? [y/N]

On [y] invoke /ai-dev-assistant:install-task-rule. On [n] record **Task Rule:** (none) in project_state.md so it is never re-offered — a decline is an answer, not a deferred yes. Skip silently when there is no code path. Never write to the user's repository without the answer.

(c) Final handoff — offer the candidate tasks, and enter at scope.

Requirements gathering usually surfaces one or more candidate first tasks, and by this point you have often written one into ## Current Focus in prose. Offer them. Do not create them — a task folder is the user's decision, and a project that creates its own backlog has decided for them.

Record the candidates in ## Up Next (that field exists for exactly this, and must not be left holding its {...} placeholder) and print:

Requirements gathering complete.

Candidate first tasks:
  - <task-name> — <one line on what it settles>
  - <task-name> — <one line on what it settles>

Say which one to start and I'll open it with `/ai-dev-assistant:scope <task-name>`,
or run `/ai-dev-assistant:next` to see the full picture first.

A task that does not exist yet starts at Phase 0 scope, not Phase 1 research. This is a rule about what you do, not a phrase to print. When the user picks a candidate, run /ai-dev-assistant:scope <task> — never /ai-dev-assistant:research <task>, and never offer research as the entry point. Phase 0 writes the four-field contract (Goal / Expected result / Success criteria / Non-goals) that Phase 4 later checks the change against; /research on a new task stops and authors that contract anyway, so naming research first either detours through scope or reads to the user as though scope were optional. /next routes new tasks the same way (commands/next.md, "Scope contract for brand-new tasks"), so the two agree.

When requirements surfaced no clear candidate, drop the list and hand off to /next alone. Do not invent a task to fill the slot.

Beyond /scope and /next, do not list further commands like /design or /implement — /next routes those.

Stop Points

STOP and wait for user response:

• After asking for project name
• After asking for storage location
• Before creating folders if path exists
• After showing confirmation