# Project Initializer

> Use when starting a new development project — creates memory folder structure with project_state.md (including codePath), architecture scaffolding, and registers project. Accepts optional code_path argument.

- Skill: `camoa/project-initializer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add camoa/project-initializer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/camoa/project-initializer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: camoa (https://skillmd.com/u/camoa)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/camoa/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:
```bash
ls -la {chosen_path}
```

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

### 4. Create Structure

Use `Bash` to create folders:
```bash
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`:

```markdown
# {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:
```markdown
# {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:
```bash
mkdir -p ~/.claude/ai-dev-assistant
```

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

**Registry Schema:**
```json
{
  "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