Init Project Action

Initialize a complete new project with directory structure, build configuration, testing setup, CI/CD pipeline, and development tooling appropriate for the chosen framework and language.

When to Use This Command

Run this command when...

• You are starting a brand new project and need the full scaffolding from directory structure through CI pipeline
• A new microservice needs to be initialized with all standard project conventions and tooling
• You want to bootstrap a project with pre-configured linting, formatting, testing, and build scripts
• The project needs a git repository initialized with proper .gitignore, branch protection, and initial commit
• You are creating a project that must follow organizational standards for structure, tooling, and configuration

Quick Start

Copy
# .claude/commands/init-project-action.md
---
name: Init Project Action
description: Initialize complete project with structure, tooling, and CI/CD
command: true
---
Initialize project: $ARGUMENTS

1. Determine project type, framework, and language
2. Create directory structure with standard conventions
3. Initialize git, package manager, and build system
4. Configure linting, formatting, and testing
5. Set up CI/CD pipeline and deployment configuration

Copy
# Invoke the command
claude "/init-project-action TypeScript Express API with PostgreSQL"

# Expected output
# > Initializing: TypeScript Express API
# > Creating directory structure...
# >   src/controllers/ | src/services/ | src/models/
# >   src/middleware/ | src/routes/ | src/config/
# >   tests/unit/ | tests/integration/
# > Configuring tooling...
# >   TypeScript: tsconfig.json (strict mode)
# >   ESLint: .eslintrc.js (typescript-eslint)
# >   Prettier: .prettierrc
# >   Jest: jest.config.ts (ts-jest preset)
# > Initializing package.json...
# >   Dependencies: express, pg, zod, helmet, cors
# >   Dev deps: typescript, ts-node-dev, jest, eslint, prettier
# > Setting up database...
# >   Created: src/config/database.ts (connection pool)
# >   Created: migrations/ directory with initial migration
# > Git initialized with .gitignore (Node + TypeScript template)
# > CI/CD: .github/workflows/ci.yml (lint, test, build)
# > Project ready. Run: npm run dev

Core Concepts

Concept	Description
Framework Detection	Determines the optimal project structure based on the specified framework and language
Convention Templates	Applies industry-standard conventions for directory layout, naming, and configuration
Toolchain Setup	Installs and configures the complete development toolchain: linter, formatter, test runner
CI Pipeline	Generates CI/CD workflow files for GitHub Actions, GitLab CI, or other platforms
Security Baseline	Configures security headers, .gitignore for secrets, and dependency audit scripts

Project Initialization Layers
===============================

  [Structure]    src/ | tests/ | config/ | docs/
       |
  [Dependencies] Runtime + Dev + Type definitions
       |
  [Configuration] tsconfig | eslint | prettier | jest
       |
  [Git Setup]    .gitignore | initial commit | branch rules
       |
  [CI/CD]        Workflow file | lint | test | build | deploy
       |
  [Dev Scripts]  dev | build | test | lint | format | migrate

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Project type, framework, and technology stack	none	"TypeScript Express API"	Yes
package_manager	Package manager to use	npm	"pnpm", "yarn"	No
ci_platform	CI/CD platform for pipeline config	github-actions	"gitlab-ci", "circleci"	No
database	Database to configure	none	"postgresql", "mongodb"	No
docker	Include Docker and docker-compose setup	false	true	No

Best Practices

1. Specify the full technology stack upfront -- "TypeScript Express API with PostgreSQL and Redis" gives the initializer complete context to configure all integrations correctly.

2. Choose strict TypeScript settings -- The initializer uses strict mode by default. Keep it enabled for new projects to catch type errors early rather than retrofitting strictness later.

3. Review generated CI pipeline -- The default CI workflow covers lint, test, and build stages. Add deployment stages, environment secrets, and approval gates specific to your organization.

4. Add organizational standards after initialization -- Layer on team-specific conventions (shared ESLint configs, commit hooks, PR templates) after the base project is initialized.

5. Make the first commit meaningful -- The initializer creates the project structure. Review all generated files, make any adjustments, then commit with a descriptive message like "Initialize TypeScript Express API project."

Common Issues

Package manager version conflicts: The initializer may generate lock files for a different package manager version than installed locally. Ensure your global package manager version matches the project configuration.

CI pipeline references unavailable secrets: Generated CI workflows may reference environment variables (DATABASE_URL, API_KEY) that are not configured in your CI platform. Add required secrets before the first pipeline run.

Framework version mismatches: The initializer uses current stable versions. If your organization requires specific versions, update package.json after initialization and re-install dependencies.