---
name: eck:new-project
version: "0.7.4"
description: Interview-driven project scaffolding with full Claude Code infrastructure deployment (hooks, primitives, context tiers, agents, skills, plugins).
disable-model-invocation: false
---

# New Project Workflow

Create a new project with complete Claude Code infrastructure: hooks, primitives, context tiers, agents, skills, and workflow documentation.

> **Do NOT enter plan mode.** This skill handles its own staging: interview first (Stages 1-3), then generate files (Stages 4-7). Execute all stages sequentially in a single pass. If the user provides answers inline, skip the interview questions and proceed directly to file generation.

---

## Visual Framework

Follow the visual framework defined in the `output:visual-framework` primitive.

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Task Registration

| Stage | Subject                    | Active Form             | Statusline      |
| ----- | -------------------------- | ----------------------- | --------------- |
| 1     | Stage 1: Pre-Flight        | Verifying prerequisites | Preflight (1/7) |
| 2     | Stage 2: Interview         | Conducting interview    | Interview (2/7) |
| 3     | Stage 3: Plan              | Creating plan           | Plan (3/7)      |
| 4     | Stage 4: Package Detection | Detecting packages      | Detect (4/7)    |
| 5     | Stage 5: File Generation   | Generating files        | Files (5/7)     |
| 6     | Stage 6: Git Setup         | Setting up git          | Git (6/7)       |
| 7     | Stage 7: Summary           | Generating summary      | Summary (7/7)   |

## Usage

```bash
/eck:new-project                    # Start new project setup
/eck:new-project <project-name>     # Start with name pre-filled
```

---

## Stage 1: Pre-Flight

### Inputs

- `$ECK_HOME/` templates directory
- `$ECK_HOME/user-preferences.json`
- `git` CLI availability
- `gh` CLI authentication status

### Activities

### Read Output Mode

Read the user's output style preference to adapt interview verbosity:

```bash
cat $ECK_HOME/user-preferences.json 2>/dev/null
```

- **guided**: Explain each question's purpose. Provide examples for every field.
- **standard**: Brief context for non-obvious questions.
- **concise**: Questions only, no explanations.

**Required:**

- Write permissions to target directory
- Templates at: `$ECK_HOME/` (installed via npm package)

**Optional:**

- `git` (for repository initialization)

**Verification:**

```bash
# Check templates exist
ls $ECK_HOME/CLAUDE.md.project.template
ls $ECK_HOME/.claude/hooks/
ls $ECK_HOME/.claude/primitives/

# Check git available
git --version
```

**If templates not found:** STOP with instructions: "Run `npx @evolvconsulting/evolv-coder-kit --global` to install templates."

### Standards Repository Check

1. Verify gh CLI is authenticated:

   ```bash
   gh auth status
   ```

2. If gh CLI is available: note for user that `/start-project` will pull fresh standards
3. If gh CLI unavailable: warn user, fallback defaults will be used until gh is configured

### Outputs

- Output mode preference; confirmed template availability; gh CLI status

### Exit Criteria

- Templates found; output mode resolved; skill may proceed

---

## Stage 2: Project Interview

### Inputs

- Pre-filled project name from `$ARGUMENTS` (if provided)
- Output mode from Stage 1 (controls interview verbosity)

### Activities

Conduct structured Q&A to gather project configuration using AskUserQuestion. Minimum 7 question groups.

### Q1: Project Identity

**Questions:**

1. What is the project display name? (e.g., "My SaaS App")
2. What short key (2-4 letters)? (e.g., MSA, RS)
3. Brief description? (1-2 sentences)
4. Target repository path? (absolute path)

**Context:** The project key is used for task tracker prefixes and branch names.

### Q2: Project Type

**Questions:**

1. What project type best describes this project? Present as AskUserQuestion with these 4 options:

| Option                | Levels | DEV_RIGOR | Description                                    |
| --------------------- | ------ | --------- | ---------------------------------------------- |
| 1 - Spike/PoC         | 1      | lite      | Prove technical feasibility                    |
| 2 - Prototype         | 2      | lite      | Explore UX/approach, get feedback              |
| 3 - MVP (Recommended) | 3      | standard  | Ship core value to real users                  |
| 4 - Production        | 4-5    | strict    | Pilot, preview, or full launch with compliance |

If user selects "Production", ask a follow-up: "Is this a pilot/preview (level 4) or full production with compliance (level 5)?"

**Context:** Controls the depth of `/start-project` interview and downstream workflow intensity. Stored as `<PROJECT_TYPE>` (1-5) in project-constants.md. Also determines `<DEV_RIGOR>` (lite|standard|strict) which calibrates quality gates, review depth, and testing enforcement across all workflow skills.

### Q3: Project Vision

**Questions:**

1. What problem does this project solve? (2-3 sentences)
2. Who are the target users? (2-3 sentences)
3. What are the primary goals? (2-3 sentences)

**Context:** Stored in project-constants.md. Reviewed during `/start-project` Stage 1 for refinement. Informs architecture decisions and feature prioritization.

### Q4: Task Tracker

**Questions:**

1. Which task tracker? (JIRA / GitHub Issues / Linear)
2. Project URL or organization?
3. Board ID? (JIRA/Linear only)
4. Default assignee name and ID?

**Context:** This configures plugin requirements (determined in Q7), task creation commands, and JIRA/Linear primitives.

### Q5: Documentation Platform

**Questions:**

1. Which documentation platform? (Confluence / Local markdown)
2. If Confluence:
   - Confluence base URL?
   - Space key?
   - Space ID?
   - Homepage ID?

**Context:** Determines whether Confluence primitives and confluence skill are deployed. sync-context is always deployed (supports both platforms). When "Local markdown" is selected, design-feature writes to `docs/features/` instead of Confluence.

### Q6: Hook Selection

**Questions:**

1. Enable all 14 non-safety hooks? (Y/n)
2. If no, select which categories:
   - Quality hooks (planning-guard, planning-bash-guard, planning-write-guard) - recommended for dev projects
     Note: Code formatting is configured inline in `settings.json` via PostToolUse event (ruff for .py, prettier for .ts/.tsx)
   - Observability hooks (audit-log, checkpoint-save, mcp-error-detect, error-detect) - recommended
   - Session hooks (stale-branch, context-recovery, pre-compact, session-end-reminder) - recommended
   - Learning hooks (heuristic-capture, heuristic-inject, session-auto-learn) — opt-in, enables passive pattern observation and session-end analysis
3. Enable safety hooks? (y/N) **Default: No**
   - Safety hooks: protect-files, detect-secrets, hitl-approval, security-gate
   - These prompt for manual approval on destructive operations even when "dangerously skip permissions" is active
   - Can be toggled anytime via `/eck:enable-protections` and `/eck:disable-protections`
   - When enabled, they are session-scoped by default (auto-revert on session end) or permanent with `--always-on`

**Context:** Hooks configure `settings.json`. Safety hooks are **off by default** — they are opt-in and can be enabled per-session or permanently.

### Q7: Plugin & Integration Setup

No questions asked — this step is fully automated based on Q4 (tracker) and Q5 (docs) answers.

**Logic:**

1. Determine required plugins from Q4/Q5 selections:
   - Q4 = JIRA → `atlassian` plugin required (covers JIRA + Confluence)
   - Q4 = Linear → `linear` plugin required
   - Q4 = GitHub Issues → `github` plugin required
   - Q5 = Confluence (and tracker is not JIRA) → `atlassian` plugin required

2. Determine recommended plugins from the project's detected tech stack (Stage 4):
   - TypeScript/JavaScript frontend → `typescript-lsp` recommended
   - Python backend → `pyright-lsp` recommended
   - Go → `gopls` recommended
   - Rust → `rust-analyzer` recommended

3. Read `~/.claude/settings.json` `enabledPlugins` array and check status of each required and recommended plugin.

4. Display plugin status to the user:

```
## Required Plugins for Your Configuration
[x] atlassian — installed and enabled (JIRA + Confluence)
[ ] linear — NOT installed
    Install: /plugin install linear@claude-plugins-official

## Recommended Plugins for Your Stack
[x] typescript-lsp — installed (TypeScript frontend)
[ ] pyright-lsp — not installed (Python backend)
    Install: /plugin install pyright-lsp@claude-plugins-official
```

**Validation warnings (non-blocking):**

- If a required plugin is missing: show a `[ ]` warning with install command — do not block setup. User can install before running `/start-project`.
- If no plugins are missing: show a brief confirmation line and continue.

**Outputs written to `project-constants.md`:**

- `TRACKER_BACKEND_OVERRIDE` — empty by default; user can override the detected tracker backend (e.g., to force `gh-cli` instead of plugin)
- `DOC_BACKEND_OVERRIDE` — empty by default; user can override the detected docs backend

**Reference:**

- `plugin-manifest.yaml` — canonical plugin dependency map for all tracker/docs integrations
- `core/ops:plugin-preflight` — plugin connectivity verification primitive (used at skill runtime, not here)

### Q8: Learning Autonomy

**Questions:**

1. What level of learning autonomy should the agent have?

| Level | Name                  | Description                                                                                  |
| ----- | --------------------- | -------------------------------------------------------------------------------------------- |
| 1     | Observer              | Passive observation only. Run /retrospective and /evolve manually.                           |
| 2     | Advisor (recommended) | Auto-analysis at session end. Summarizes findings, does not modify infrastructure.           |
| 3     | Autonomous            | Full auto-learning. Promotes high-confidence heuristics, regenerates guidance automatically. |

**Default:** Level 2 (Advisor)

**Context:** Controls `session-auto-learn.sh` Stop hook. Stored as `<LEARNING_AUTONOMY>` in project-constants.md.

### Outputs

- Complete project configuration from 8 question groups (Q1-Q8)

### Exit Criteria

- All required configuration gathered; plugin status assessed

---

## Stage 3: Plan Generation

### Inputs

- Project configuration from Stage 2 (all Q1-Q8 answers)

### Activities

After interview, display complete plan for approval via the Bash tool:

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Project Plan${RESET}"
echo ""
printf '%b\n' "${BOLD}Project:${RESET} {PROJECT_NAME} (${DIM}{PROJECT_KEY}${RESET})"
printf '%b\n' "${BOLD}Location:${RESET} {TARGET_PATH}"
echo ""
printf '%b\n' "${BOLD}Files to Create${RESET}"
echo ""
echo "  {TARGET_PATH}/"
echo "  ├── CLAUDE.md"
echo "  ├── development-workflow.md"
echo "  ├── workflow-quick-reference.md"
echo "  ├── workflow-diagrams.md"
echo "  ├── CONTRIBUTING.md"
echo "  ├── .claude/"
echo "  │   ├── settings.json"
echo "  │   ├── settings.local.json"
echo "  │   ├── project-constants.md"
echo "  │   ├── project-constitution.md"
echo "  │   ├── agents/ ({N} agents)"
echo "  │   ├── skills/ ({N} skills)"
echo "  │   ├── project-catalog.yaml"
echo "  │   ├── hooks/ ({N} hooks)"
echo "  │   ├── primitives/ ({N} namespaces)"
echo "  │   ├── context/"
echo "  │   │   ├── standards/ (3 files)"
echo "  │   │   └── project/.gitkeep"
echo "  │   └── handovers/.gitkeep"
echo "  └── docs/"
echo "      └── features/"
echo ""
printf '%b\n' "${ORANGE}${BOLD}Configuration Summary${RESET}"
echo ""
printf '%b\n' "Project Key: {PROJECT_KEY}"
printf '%b\n' "Project Type: {PROJECT_TYPE}"
printf '%b\n' "Tracker: {TRACKER_TYPE}"
printf '%b\n' "Docs: {DOC_PLATFORM}"
printf '%b\n' "Hooks: {HOOK_COUNT} enabled"
printf '%b\n' "Output Mode: {OUTPUT_MODE}"
echo ""
printf '%b\n' "${DIM}Placeholders to Replace: {COUNT}${RESET}"
echo ""
printf '%b\n' "${BOLD}Proceed with project creation? (Y/n)${RESET}"
```

**STOP:** Get explicit user approval before creating files.

### Outputs

- Deployment plan displayed; user explicit approval obtained

### Exit Criteria

- User has confirmed the plan; skill proceeds to file creation

---

## Stage 4: Package Manager Auto-Detection

### Inputs

- Target project directory (scanned for lock files and build artifacts)

### Activities

Scan the target directory for existing package manager lock files. Set tool commands accordingly so placeholders use the correct runner, test, and lint commands.

### Detection Matrix

Check for artifacts in priority order (most specific first). Stop at the first match per ecosystem.

| Artifact                            | Manager     | Run Cmd            | Test Cmd                     | Lint Cmd                            |
| ----------------------------------- | ----------- | ------------------ | ---------------------------- | ----------------------------------- |
| `bun.lockb`                         | Bun         | `bun run`          | `bun test`                   | `bun run lint`                      |
| `pnpm-lock.yaml`                    | pnpm        | `pnpm`             | `pnpm test`                  | `pnpm lint`                         |
| `yarn.lock`                         | Yarn        | `yarn`             | `yarn test`                  | `yarn lint`                         |
| `package-lock.json`                 | npm         | `npm run`          | `npm test`                   | `npm run lint`                      |
| `uv.lock`                           | uv          | `uv run`           | `uv run pytest`              | `uv run ruff check .`               |
| `pyproject.toml` [tool.poetry]      | Poetry      | `poetry run`       | `poetry run pytest`          | `poetry run ruff check .`           |
| `requirements.txt`                  | pip         | `python -m`        | `pytest`                     | `ruff check .`                      |
| `go.mod`                            | Go modules  | `go`               | `go test ./...`              | `golangci-lint run`                 |
| `Cargo.toml`                        | Cargo       | `cargo`            | `cargo test`                 | `cargo clippy`                      |
| `pom.xml`                           | Maven       | `mvn`              | `mvn test`                   | `mvn checkstyle:check`              |
| `build.gradle` / `build.gradle.kts` | Gradle      | `./gradlew`        | `./gradlew test`             | `./gradlew check`                   |
| `Gemfile`                           | Bundler     | `bundle exec`      | `bundle exec rspec`          | `bundle exec rubocop`               |
| `composer.json`                     | Composer    | `composer`         | `composer test`              | `composer lint`                     |
| `pubspec.yaml`                      | pub/Flutter | `dart` / `flutter` | `dart test` / `flutter test` | `dart analyze`                      |
| `Package.swift`                     | SPM         | `swift`            | `swift test`                 | `swiftlint`                         |
| `CMakeLists.txt`                    | CMake       | `cmake --build`    | `ctest`                      | `cppcheck`                          |
| `*.sln` / `*.csproj`                | dotnet      | `dotnet`           | `dotnet test`                | `dotnet format --verify-no-changes` |

### Detection Logic

1. **Scan**: Check if the target directory already contains any of the above artifacts
2. **Auto-fill**: Map detected manager to placeholder variables:
   - Frontend managers (Bun, pnpm, Yarn, npm) → `<BACKEND_RUN_CMD>`, `<TEST_COMMAND_FE>`, `<LINT_COMMAND_FE>`
   - Backend managers (uv, Poetry, pip, Go, Cargo, etc.) → `<BACKEND_RUN_CMD>`, `<TEST_COMMAND_BE>`, `<LINT_COMMAND_BE>`
3. **Confirm**: Present detected configuration via AskUserQuestion:

   ```
   Detected package manager: {MANAGER_NAME} (from {ARTIFACT})

   Commands to use:
   - Run: {RUN_CMD}
   - Test: {TEST_CMD}
   - Lint: {LINT_CMD}

   Accept these defaults? (Y/n)
   ```

4. **Fallback**: If no artifacts found, keep existing defaults (`uv run` / `npm run`)

**Note:** Multiple ecosystems can coexist (e.g., npm for frontend + uv for backend). Detect and configure both independently.

### Outputs

- Resolved package manager commands (`<RUN_CMD>`, `<TEST_CMD>`, `<LINT_CMD>`) for placeholder replacement

### Exit Criteria

- Package manager(s) detected and confirmed (or defaults accepted); commands resolved

---

## Stage 5: File Creation

### Inputs

- Project configuration from Stage 2
- Package manager commands from Stage 4
- `$ECK_HOME/` template source
- User approval from Stage 3

### Activities

### Step 1: Create Directory Structure

```bash
mkdir -p {TARGET_PATH}/.claude/agents
mkdir -p {TARGET_PATH}/.claude/skills
mkdir -p {TARGET_PATH}/.claude/hooks
mkdir -p {TARGET_PATH}/.claude/primitives
mkdir -p {TARGET_PATH}/.claude/context/standards
mkdir -p {TARGET_PATH}/.claude/context/project
mkdir -p {TARGET_PATH}/.claude/handovers
mkdir -p {TARGET_PATH}/.claude/heuristics
mkdir -p {TARGET_PATH}/.claude/output-modes
mkdir -p {TARGET_PATH}/docs/features
```

### Step 1b: Initialize Lifecycle and Feature Registry

**MUST** create both JSON files immediately after directory creation. These are required by `update-lifecycle.js` and `manage-features.js` for all subsequent lifecycle operations.

```bash
cat > {TARGET_PATH}/.claude/lifecycle-registry.json << 'EOF'
{
  "schema_version": 6,
  "migration_complete": true,
  "project_key": null,
  "next_id": 1,
  "features": {}
}
EOF

cat > {TARGET_PATH}/.claude/lifecycle-state.json << 'EOF'
{
  "schema_version": 6,
  "active_feature": null,
  "updated_at": null
}
EOF

cat > {TARGET_PATH}/.claude/features.json << 'EOF'
{
  "schema_version": 1,
  "features": {},
  "next_id": 1
}
EOF
```

### Step 2: Copy Root Templates

**MUST** copy from `$ECK_HOME/`. Do NOT skip any root template:

- `CLAUDE.md.project.template` -> `CLAUDE.md`

### Step 2b: Copy docs/ Skeleton

**MUST** copy the `docs/` directory from `$ECK_HOME/docs/`:

- `docs/INDEX.md`
- `docs/project/BACKLOG.md`
- `docs/guides/CONTRIBUTING.md`
- `docs/guides/development-workflow.md`
- `docs/guides/workflow-quick-reference.md`
- `docs/guides/workflow-diagrams.md`
- `docs/adrs/.gitkeep`

### Step 3: Copy .claude Configuration

Copy from `$ECK_HOME/.claude/`:

- `project-constants.md`
- `project-constitution.md`
- `settings.json.template` -> `settings.json` (strip `.template` suffix)
- `settings.local.json.template` -> `settings.local.json`
- `README.md`

### Step 3b: Clean Up .template Files

After copying, remove source `.template` files from the deployed project — they are not needed after setup:

```bash
rm -f "$PROJECT_DIR/.claude/settings.json.template" 2>/dev/null
rm -f "$PROJECT_DIR/.claude/settings.local.json.template" 2>/dev/null
rm -f "$PROJECT_DIR/CLAUDE.md.project.template" 2>/dev/null
```

### Step 4: Copy Agents

**MUST** copy ALL agents from `$ECK_HOME/.claude/agents/`. Do NOT skip agents or selectively omit any:

- `README.md`
- Backend (6): backend-architect, backend-designer, backend-developer, backend-qa, backend-reviewer, backend-test-developer
- Frontend (6): frontend-architect, frontend-designer, frontend-developer, frontend-qa, frontend-reviewer, frontend-test-developer
- Cross-cutting (5): database-specialist, devops-engineer, security-specialist, integration-qa, technical-writer
- Utility (2): code-simplifier, bot-developer
- Language-specific (10): java-developer, csharp-developer, cpp-developer, php-developer, go-developer, rust-developer, kotlin-developer, ruby-developer, dart-developer, swift-developer

**Note:** All 30 agents are deployed. The 10 language-specific agents are optional: `/start-project` keeps the one matching the selected backend/frontend stack — it becomes that prefix's dispatch target (see the stack-aware routing note in `dev-task` / `dev-sprint`) — and trims the rest. The default Python/FastAPI + React stack keeps `backend-developer` / `frontend-developer` and trims all 10.

### Step 5: Copy Skills

Copy skill directories from `$ECK_HOME/.claude/skills/`:

- **Always (51)**: start-project, design-feature, design-research, design-arch, design-solution, design-specs, design-discovery, design-qa, design-adr, design-document, design-risk, dev-plan, dev-feature, dev-feature-tdd, dev-sprint, dev-task, dev-test, dev-simplify, validate-code, validate-quality, validate-ci, validate-security, validate-uat, dev-branch, dev-commit, dev-push, dev-pr, validate-approval, validate-merge, deploy-promote, deploy-release, deploy-status, deploy-tracker, spec-scope, spec-research, spec-discovery, spec-criteria, spec-questions, spec-review, design-review, develop-review, validate-review, deploy-review, git-flow, git-status, learn, retrospective, sync-context, evolve, heuristic-status, orchestrate, refresh-project-catalog
- **If Confluence (Q5)**: confluence
- **If JIRA (Q4)**: jira
- **If GitHub Issues**: GitHub plugin tools are used directly (no separate skill needed)
- **Only deploy active skills** listed above — no others

### Step 6: Copy Hooks

Copy selected hooks from `$ECK_HOME/.claude/hooks/`:

- Based on Q6 selections
- **REQUIRED:** make all hooks executable with `chmod +x` — without this, every SessionStart hook fails at runtime with `exit_code: 126` (Permission denied). See dev #29.

### Step 7: Copy Primitives

Copy primitive namespaces from `$ECK_HOME/.claude/primitives/`:

- Always: git/, mode/, model/, review/, task/, agent/, codebase/, ops/, output/, planning/, traceability/, validation/, local-issues/
- If JIRA: jira-official/
- If GitHub Issues: gh-cli/
- If Linear: linear-official/, linear-cli/
- If Confluence: confluence-official/
- If Local docs: local-docs/
- If AWS: aws-cli/
- `README.md` (always)

### Step 8: Copy Context Files

Copy from `$ECK_HOME/.claude/context/`:

- `standards/core-standards.md`
- `standards/frontend-standards.md`
- `standards/backend-standards.md`
- `standards/database-standards.md`
- `standards/devops-standards.md`
- `standards/documentation-standards.md`
- `standards/ai-standards.md`
- `project/.gitkeep`

**Note:** All 7 fallback default standards are deployed. `/start-project` will pull fresh standards from `evolv-coder-standards` and compile them for the selected tech stack.

### Step 9: Copy Output Mode

1. Read `outputMode` from `$ECK_HOME/user-preferences.json` (default: `standard`)
2. Copy `$ECK_HOME/.claude/output-modes/{outputMode}.md` to `<TARGET_PATH>/.claude/output-modes/{outputMode}.md`
3. If the mode file doesn't exist, fall back to `standard.md`

### Step 10: Record Plugin Configuration

Write the plugin override placeholders from Q7 to `project-constants.md`:

- `TRACKER_BACKEND_OVERRIDE` — set to empty string (user can override later)
- `DOC_BACKEND_OVERRIDE` — set to empty string (user can override later)

If required plugins were found missing during Q7, append a visible notice at the bottom of the summary so the user is reminded before running `/start-project`:

```
[!] Required plugins not installed: {missing plugin list}
    Run /plugin install <name>@claude-plugins-official before using tracker/docs features.
```

### Step 11: Generate Deployed Catalog

**MUST** generate the initial deployed catalog at `<TARGET_PATH>/.claude/project-catalog.yaml`. Do NOT skip catalog generation:

1. Read the canonical catalog from `$ECK_HOME/global-catalog.yaml`
2. For each component that was deployed (based on selections in Stage 2):
   - Copy the entry from the canonical catalog
   - Set `status: synced`
   - Compute the deployed checksum (after placeholder replacement)
3. For conditional components that were NOT deployed (e.g., JIRA primitives when using GitHub Issues):
   - Omit from the deployed catalog entirely
4. Set metadata:
   - `deployed_at`: current date
   - `deployed_by`: `/eck:new-project`
   - `claude_code_standards_version`: from canonical catalog
   - `template_version`: from canonical catalog
   - `project_name`: `<PROJECT_NAME>`
   - `project_key`: `<PROJECT_KEY>`
5. Initialize `sync_history` with a single entry:

```yaml
sync_history:
  - date: "{DATE}"
    action: "initial-deploy"
    performed_by: "/eck:new-project"
    claude_code_standards_version: "{version}"
    template_version: "{version}"
    summary: "Initial project setup: {N} components deployed"
```

### Step 12: Replace Placeholders

Use the template engine to resolve all `<PLACEHOLDER>` tokens in deployed files.

**Step 12a: Populate project-constants.md**

Write interview answers into `<TARGET_PATH>/.claude/project-constants.md` by replacing self-referential values (e.g., `| PROJECT_NAME | <PROJECT_NAME> |`) with actual values from the interview. Update each table row's Value column:

| Placeholder              | Source                                                            | Example                       |
| ------------------------ | ----------------------------------------------------------------- | ----------------------------- |
| `PROJECT_NAME`           | Q1                                                                | My SaaS App                   |
| `PROJECT_KEY`            | Q1                                                                | MSA                           |
| `PROJECT_DESCRIPTION`    | Q1                                                                | A multi-tenant SaaS platform  |
| `PROJECT_TYPE`           | Q2                                                                | 3                             |
| `DEV_RIGOR`              | Q2 (derived: 1-2=lite, 3=standard, 4-5=strict)                    | standard                      |
| `TRACKER_TYPE`           | Q4                                                                | JIRA                          |
| `TRACKER_URL`            | Q4                                                                | https://company.atlassian.net |
| `BOARD_ID`               | Q4                                                                | 6                             |
| `BOARD_NAME`             | Q4                                                                | My Board                      |
| `ASSIGNEE_ID`            | Q4                                                                | abc123                        |
| `ASSIGNEE_NAME`          | Q4                                                                | John Developer                |
| `CONFLUENCE_ENABLED`     | Q5 (Confluence → true, Local markdown → false)                    | true                          |
| `CONFLUENCE_SPACE_KEY`   | Q5                                                                | MSA                           |
| `CONFLUENCE_SPACE_ID`    | Q5                                                                | 123456                        |
| `CONFLUENCE_SPACE_NAME`  | Q5                                                                | My Project                    |
| `CONFLUENCE_HOMEPAGE_ID` | Q5                                                                | 789012                        |
| `LABEL_PREFIX`           | Derived from PROJECT_KEY_LOWERCASE                                | msa                           |
| `LEARNING_AUTONOMY`      | Default: observer                                                 | observer                      |
| `STANDARDS_REPO_URL`     | Default: https://github.com/evolvconsulting/evolv-coder-standards | —                             |
| `STANDARDS_REPO_BRANCH`  | Default: main                                                     | main                          |

Also add these extra placeholders (used in scaffold files but not in the constants table) as additional rows or a temporary section so the template engine can resolve them:

| Placeholder                | Source                                | Default                            |
| -------------------------- | ------------------------------------- | ---------------------------------- |
| `PROJECT_KEY_LOWERCASE`    | Derived from PROJECT_KEY              | msa                                |
| `PROJECT_PROBLEM`          | Q3                                    | Users struggle to manage...        |
| `PROJECT_USERS`            | Q3                                    | Small business owners...           |
| `PROJECT_GOALS`            | Q3                                    | Simplify workflow...               |
| `CONFLUENCE_BASE_URL`      | Q5                                    | https://company.atlassian.net/wiki |
| `HOOK_COUNT`               | Q6                                    | 12                                 |
| `DOCS_REPO_PATH`           | Q1 (same as target)                   | /path/to/project                   |
| `DATE`                     | Current date (YYYY-MM-DD)             | 2026-02-28                         |
| `CONTRIBUTING_SETUP_NOTES` | Default setup text                    | Install project dependencies...    |
| `FRONTEND_PATH`            | Default (updated by `/start-project`) | frontend/                          |
| `BACKEND_PATH`             | Default (updated by `/start-project`) | backend/                           |
| `BACKEND_RUN_CMD`          | Default                               | uv run                             |
| `BACKEND_PORT`             | Default                               | 8000                               |
| `FRONTEND_PORT`            | Default                               | 3000                               |
| `MAIN_BRANCH`              | Default                               | main                               |
| `DEV_BRANCH`               | Default                               | dev                                |
| `FEATURE_PREFIX`           | Default                               | feat/                              |
| `TEST_COMMAND_FE`          | Default                               | npm test                           |
| `TEST_COMMAND_BE`          | Default                               | uv run pytest                      |
| `LINT_COMMAND_FE`          | Default                               | npm run lint                       |
| `LINT_COMMAND_BE`          | Default                               | uv run ruff check .                |
| `TYPECHECK_COMMAND_FE`     | Default                               | npm run typecheck                  |
| `TYPECHECK_COMMAND_BE`     | Default                               | uv run mypy .                      |
| `CODE_REVIEW_TOOL`         | Default                               | Manual                             |
| `MIN_REVIEW_SCORE`         | Default                               | 5/5                                |
| `PAGE_ID`                  | Default (empty string)                |                                    |

Update the `**Last Updated:**` line in project-constants.md to today's date.

**Step 12b: Resolve all files with the template engine**

Locate the template CLI. v0.8.0+ deploys it under `$HOME/.claude/evolv-coder-kit/bin/`; older installs may only expose it via the global npm root. The fallback chain below tries the deployed copy first, then the npm-global copy.

```bash
TCLI="$HOME/.claude/evolv-coder-kit/bin/template-cli.js"
if [ ! -f "$TCLI" ]; then
  TCLI="$(npm root -g 2>/dev/null)/@evolvconsulting/evolv-coder-kit/bin/template-cli.js"
fi
if [ ! -f "$TCLI" ]; then
  echo "ERROR: template-cli.js not found at \$HOME/.claude/evolv-coder-kit/bin/ or in npm global root" >&2
  echo "Reinstall with: evolv-coder-kit --global --overwrite" >&2
  exit 1
fi

node "$TCLI" \
  resolve-dir "{TARGET_PATH}/.claude" \
  --values "{TARGET_PATH}/.claude/project-constants.md" --quiet
```

Also resolve root-level template files:

```bash
node "$TCLI" \
  resolve-dir "{TARGET_PATH}/docs" \
  --values "{TARGET_PATH}/.claude/project-constants.md" --quiet
node "$TCLI" \
  resolve "{TARGET_PATH}/CLAUDE.md" \
  --values "{TARGET_PATH}/.claude/project-constants.md" \
  --output "{TARGET_PATH}/CLAUDE.md" --quiet
```

**Step 12c: Verify no unresolved placeholders remain**

```bash
node "$TCLI" \
  verify "{TARGET_PATH}/.claude" --format text
```

If the verify command reports unresolved tokens (exit code 2), report them to the user. Tokens listed in the default excludes (`project-constants.md`, `project-catalog.yaml`) are expected and safe to ignore.

> **Hard fail.** If `template-cli.js` is missing AND verify reports unresolved tokens in skill `name:` fields (e.g. `<PROJECT_KEY_LOWERCASE>:start-project`), do **not** improvise a sed fallback — those tokens appear in YAML frontmatter and a partial sed pass will silently leave skills unresolvable by Claude Code. Stop and instruct the user to reinstall the package globally.

### Step 13: Register Project in Registry

**MUST** register the new project in the global registry so `/eck:project-status` can track it immediately. Do NOT skip registry registration when registry exists.

**Reference:** `ops:registry-update` primitive for the canonical read-modify-write procedure.

1. Read `$ECK_HOME/registry.yaml`. If it does not exist, log a warning and skip registration (the installer creates the registry during `--global` install).

2. Before creating the registry entry, check for KEY_CONFLICT and PATH_CONFLICT per `ops:registry-update` primitive Step 1.5.

3. Add a new project entry under `projects.<PROJECT_KEY>`:

   ```yaml
   projects:
     { PROJECT_KEY }:
       project_name: "{PROJECT_NAME}"
       project_path: "{TARGET_PATH}"
       project_key: "{PROJECT_KEY}"
       state: "managed"
       audit_status: "pending"
       tracker_type: "{TRACKER_TYPE}"
       doc_platform: "local" # or "local+confluence" when CONFLUENCE_ENABLED is true (registry value convention, not the Q5 display label)
       divergence_policy: "standard"
       dev_rigor: "{DEV_RIGOR}"
       project_type: "{PROJECT_TYPE}"
       learning_autonomy: "{LEARNING_AUTONOMY}"
       deployment:
         initial_deploy_date: "{DATE}"
         deployed_by: "/eck:new-project"
         template_version: "{version from catalog}"
         has_deployed_catalog: true
         start_project_completed: false
       last_modified_at: "{DATE}"
       enrichment:
         tech_stack: null
         last_enriched: null
       last_audit:
         date: null
         report_path: null
         health_score: null
         health_grade: null
         synced: 0
         modified: 0
         outdated: 0
         missing: 0
         custom: 0
       pull_candidates: []
       sync_history:
         - date: "{DATE}"
           action: "initial-deploy"
           performed_by: "/eck:new-project"
           summary: "Project created with {N} components"
   ```

4. Recompute `project_summary` per the `ops:registry-update` primitive.

5. Atomic write: write to `registry.yaml.tmp`, then rename to `registry.yaml`.

### Outputs

- All project files created with placeholders replaced; `project-catalog.yaml` generated; project registered in `registry.yaml`

### Exit Criteria

- All files written without error; no unreplaced placeholders; catalog and registry updated

---

## Stage 6: Git Setup (Optional)

### Inputs

- User approval to initialize git (prompted at stage start)
- Target project path from Stage 5
- `<DEV_BRANCH>` value from Stage 2 (default: `dev`)

### Activities

**Ask:** Initialize git repository? (Y/n)

If yes:

### Step 1: Initialize Repository

```bash
cd {TARGET_PATH}
git init
```

### Step 2: Create .gitignore

```gitignore
# Dependencies
node_modules/
__pycache__/
.venv/
venv/

# Build
.next/
dist/
build/

# Environment
.env
.env.local
.env*.local

# IDE
.idea/
.vscode/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Test coverage
coverage/
htmlcov/
.coverage

# Claude Code runtime (not committed)
.claude/audit.log
.claude/audit.log.1
.claude/session-errors.jsonl
.claude/error-history.jsonl
.checkpoint
.planning-session
.claude/handovers/HANDOVER-*.md
```

### Step 3: Initial Commit

```bash
git add .
git commit -m "Initial project setup with Claude Code workflow"
```

### Step 4: Create Dev Branch

```bash
git checkout -b {DEV_BRANCH}
```

### Outputs

- Initialized git repository with initial commit and dev branch (if user accepted)
- `.gitignore` file at project root

### Exit Criteria

- Git repository initialized and initial commit created, or user declined git setup

---

## Stage 7: Summary

### Inputs

- Project name and path from Stage 2
- Component counts from Stage 5 (agents, skills, hooks, primitives)
- Git initialization status from Stage 6
- Plugin status from Stage 2 Q7

### Activities

Output completion summary via the Bash tool:

```bash
source $ECK_HOME/colors.sh

echo ""
printf '%b\n' "${ORANGE}${BOLD}Project Created${RESET}"
echo ""
printf '%b\n' "Project: {PROJECT_NAME}"
printf '%b\n' "Location: {TARGET_PATH}"
printf '%b\n' "Files: {TOTAL} total"
echo ""

printf '%b\n' "${GREEN}[x]${RESET} Root docs: 6"
printf '%b\n' "${GREEN}[x]${RESET} Config: 4"
printf '%b\n' "${GREEN}[x]${RESET} Agents: {N}"
printf '%b\n' "${GREEN}[x]${RESET} Skills: {N}"
printf '%b\n' "${GREEN}[x]${RESET} Hooks: {N}"
printf '%b\n' "${GREEN}[x]${RESET} Primitives: {N} namespaces"
printf '%b\n' "${GREEN}[x]${RESET} Context: 8"
printf '%b\n' "${GREEN}[x]${RESET} Output Mode: 1"
echo ""

printf '%b\n' "${BOLD}Plugin Status${RESET}"
printf '%b\n' "${DIM}  Required plugins checked — see Q7 output above for any missing installs.${RESET}"
printf '%b\n' "${DIM}  Install missing plugins with: /plugin install <name>@claude-plugins-official${RESET}"
echo ""

printf '%b\n' "${BOLD}Next Steps${RESET}"
printf '%b\n' "${DIM}  1. cd {TARGET_PATH} && claude${RESET}"
printf '%b\n' "${DIM}  2. /start-project${RESET}"
```

### Post-Setup Checklist

Verify these items before proceeding to `/start-project`:

```bash
# Core files exist
test -f "$TARGET/.claude/project-constants.md" && echo "[x] project-constants.md" || echo "[!] project-constants.md MISSING"
test -f "$TARGET/.claude/project-constitution.md" && echo "[x] project-constitution.md" || echo "[!] project-constitution.md MISSING"
test -f "$TARGET/.claude/settings.json" && echo "[x] settings.json" || echo "[!] settings.json MISSING"
test -f "$TARGET/CLAUDE.md" && echo "[x] CLAUDE.md" || echo "[!] CLAUDE.md MISSING"
test -f "$TARGET/docs/INDEX.md" && echo "[x] docs/INDEX.md" || echo "[!] docs/INDEX.md MISSING"

# No stale .template files
test ! -f "$TARGET/CLAUDE.md.project.template" && echo "[x] No stale templates" || echo "[!] .template file not cleaned up"

# No unreplaced placeholders in key files
grep -q "{PROJECT_NAME}" "$TARGET/.claude/project-constants.md" && echo "[!] Unreplaced placeholders in constants" || echo "[x] Placeholders replaced"
```

### Outputs

- Completion summary displayed to user with component counts and next steps
- Post-setup checklist verified

### Exit Criteria

- Summary displayed; checklist passed; statusline reset; skill complete

---

## Placeholder Reference

Complete list of placeholders used in templates. Placeholders marked with `*` are filled with sensible defaults by new-project and updated with real values by `/start-project`.

| Placeholder                  | Description                             | Filled By                        | Example                                                  |
| ---------------------------- | --------------------------------------- | -------------------------------- | -------------------------------------------------------- |
| `<PROJECT_NAME>`             | Display name                            | new-project Q1                   | My SaaS App                                              |
| `<PROJECT_KEY>`              | Short identifier                        | new-project Q1                   | MSA                                                      |
| `<PROJECT_DESCRIPTION>`      | Brief description                       | new-project Q1                   | A multi-tenant SaaS platform                             |
| `<PROJECT_TYPE>`             | Project type level (1-5)                | new-project Q2                   | 3                                                        |
| `<DEV_RIGOR>`                | Development rigor                       | new-project Q2 (derived)         | standard                                                 |
| `<PROJECT_PROBLEM>`          | Problem statement                       | new-project Q3                   | Users struggle to...                                     |
| `<PROJECT_USERS>`            | Target users                            | new-project Q3                   | Small business owners...                                 |
| `<PROJECT_GOALS>`            | Primary goals                           | new-project Q3                   | Simplify workflow...                                     |
| `<TRACKER_TYPE>`             | Task tracker                            | new-project Q4                   | JIRA                                                     |
| `<TRACKER_URL>`              | Tracker URL                             | new-project Q4                   | https://company.atlassian.net                            |
| `<BOARD_ID>`                 | Agile board ID                          | new-project Q4                   | 6                                                        |
| `<ASSIGNEE_ID>`              | Default assignee ID                     | new-project Q4                   | abc123                                                   |
| `<ASSIGNEE_NAME>`            | Default assignee name                   | new-project Q4                   | John Developer                                           |
| `<CONFLUENCE_ENABLED>`       | Enable Confluence publishing            | new-project Q5                   | true                                                     |
| `<CONFLUENCE_BASE_URL>`      | Confluence URL                          | new-project Q5                   | https://company.atlassian.net/wiki                       |
| `<CONFLUENCE_SPACE_KEY>`     | Space key                               | new-project Q5                   | MSA                                                      |
| `<CONFLUENCE_SPACE_ID>`      | Space ID                                | new-project Q5                   | 123456                                                   |
| `<CONFLUENCE_HOMEPAGE_ID>`   | Homepage page ID                        | new-project Q5                   | 789012                                                   |
| `<HOOK_COUNT>`               | Enabled hooks count                     | new-project Q6                   | 12                                                       |
| `<TRACKER_BACKEND_OVERRIDE>` | Tracker backend override (empty = auto) | new-project Q7                   | (empty)                                                  |
| `<DOC_BACKEND_OVERRIDE>`     | Docs backend override (empty = auto)    | new-project Q7                   | (empty)                                                  |
| `<LEARNING_AUTONOMY>`        | Learning autonomy level                 | new-project Q8                   | advisor                                                  |
| `<CONTRIBUTING_SETUP_NOTES>` | Setup instructions                      | Default: generic setup text      | Install project dependencies...                          |
| `<FRONTEND_PATH>`            | Frontend directory \*                   | Default: frontend/               | frontend/                                                |
| `<BACKEND_PATH>`             | Backend directory \*                    | Default: backend/                | backend/                                                 |
| `<MAIN_BRANCH>`              | Production branch \*                    | Default: main                    | main                                                     |
| `<DEV_BRANCH>`               | Integration branch \*                   | Default: dev                     | dev                                                      |
| `<FEATURE_PREFIX>`           | Feature branch prefix \*                | Default: feat/                   | feat/                                                    |
| `<CODE_REVIEW_TOOL>`         | Review tool \*                          | Default: Manual                  | Greptile                                                 |
| `<MIN_REVIEW_SCORE>`         | Required score \*                       | Default: 5/5                     | 5/5                                                      |
| `<TEST_COMMAND_FE>`          | Frontend tests \*                       | Default: npm test                | npm test                                                 |
| `<TEST_COMMAND_BE>`          | Backend tests \*                        | Default: uv run pytest           | uv run pytest                                            |
| `<LINT_COMMAND_FE>`          | Frontend lint \*                        | Default: npm run lint            | npm run lint                                             |
| `<LINT_COMMAND_BE>`          | Backend lint \*                         | Default: uv run ruff check .     | uv run ruff check .                                      |
| `<TYPECHECK_COMMAND_FE>`     | Frontend typecheck \*                   | Default: npm run typecheck       | npm run typecheck                                        |
| `<TYPECHECK_COMMAND_BE>`     | Backend typecheck \*                    | Default: uv run mypy .           | uv run mypy .                                            |
| `<BACKEND_PORT>`             | API port \*                             | Default: 8000                    | 8000                                                     |
| `<FRONTEND_PORT>`            | Web port \*                             | Default: 3000                    | 3000                                                     |
| `<BACKEND_RUN_CMD>`          | Python runner \*                        | Default: uv run                  | uv run                                                   |
| `<LABEL_PREFIX>`             | Confluence label prefix \*              | Default: <PROJECT_KEY_LOWERCASE> | msa                                                      |
| `<STANDARDS_REPO_URL>`       | Standards repo URL                      | Constant                         | https://github.com/evolvconsulting/evolv-coder-standards |
| `<STANDARDS_REPO_BRANCH>`    | Standards repo branch                   | Constant                         | main                                                     |

---

## Context Recovery

If interrupted mid-setup:

### Check Current State

1. **Target path exists?**

   ```bash
   ls {TARGET_PATH}
   ```

2. **Partial files created?**

   ```bash
   ls {TARGET_PATH}/.claude/
   ```

3. **Placeholders remaining?**
   ```bash
   grep -r "{PROJECT" {TARGET_PATH}/ | head -5
   ```

### Resume Points

| State                         | Resume At                               |
| ----------------------------- | --------------------------------------- |
| No target directory           | Stage 2 (Interview)                     |
| Directory exists, no files    | Stage 5 (File Creation)                 |
| Files exist with placeholders | Stage 5, Step 12 (Replace Placeholders) |
| Files exist, no placeholders  | Stage 6 (Git Setup)                     |
| Git initialized               | Stage 7 (Summary)                       |

---

## Error Handling

### Template Not Found

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} Templates not found at $ECK_HOME/"
printf '%b\n' "    ${DIM}Run: npx @evolvconsulting/evolv-coder-kit --global${RESET}"
```

### Permission Denied

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${RED}[!]${RESET} Cannot write to {TARGET_PATH}"
printf '%b\n' "    ${DIM}Check directory permissions or try a different path.${RESET}"
```

### Placeholder Replacement Failed

```bash
source $ECK_HOME/colors.sh
printf '%b\n' "${YELLOW}[>]${RESET} Some placeholders not replaced"
printf '%b\n' "    ${DIM}Run: grep -r \"{[A-Z_]*}\" {TARGET_PATH}/ --include=\"*.md\" --include=\"*.json\"${RESET}"
```

---

## Related Documents

- [evolv Coder Kit Templates]($ECK_HOME/README.md)
- [/eck:audit-unmanaged-project skill](../audit-unmanaged-project/SKILL.md) - Audit project infrastructure
- [/eck:pull-from-global-catalog skill](../pull-from-global-catalog/SKILL.md) - Pull catalog updates into projects
- [/eck:push-to-user-catalog skill](../push-to-user-catalog/SKILL.md) - Push improvements back to catalog
- [/eck:migrate-project skill](../migrate-project/SKILL.md) - Onboard existing unmanaged projects
