---

name: project-init description: Initialize project with stack-specific configuration. Use when user wants to set up repository for a specific technology stack (Node.js, Python, Rust, Go). allowed-tools: "Read,Write,Edit,Bash(git:*),Glob,Grep" version: 1.0.0

Project Initialization

Transform the AI-native template repository into a customized project starter.

Overview

This skill initializes a new project from the template by:

1. Detecting the current project state (preventing re-initialization)
2. Interviewing you about your stack and project details
3. Scaffolding stack-specific configuration files
4. Replacing placeholders in documentation
5. Removing irrelevant hooks
6. Validating the initialization

Use This Skill When

• You've cloned this template repo and want to customize it for a new project
• You need to scaffold configuration files for Node.js, Python, Rust, or Go
• You want to automatically update documentation with your project details

Preconditions (When This Skill Will Exit)

This skill will abort and exit early if:

• Already initialized: README.md has no {{PROJECT_NAME}} placeholder (project already customized)
• Uncommitted changes: git status shows modified files (prevents data loss)
• Not a git repo: .git directory doesn't exist
• Wrong directory: Missing .claude/, docs/, or README.md (not the template repo)

Rationale: These checks prevent overwriting existing projects and ensure safe operation.

If the skill exits due to preconditions:

• Review the warning message for details
• Fix the precondition (commit changes, clone template again, etc.)
• Run /start again

---

Instructions

Phase 1: Pre-flight Validation

1. Check for already-initialized project

   • Look in README.md for placeholder {{PROJECT_NAME}}
   • If not found → Project appears already initialized → Exit

2. Check git status

   • Run: git status --porcelain
   • If uncommitted changes → Warn user, ask to proceed

3. Verify template structure

   • Check for: .claude/, docs/, README.md
   • If missing → Error and exit

Phase 2: Gather Project Information

Ask user for (in order):

Stack Selection - Choose: Node.js/TypeScript, Node.js/JavaScript, Python, Rust, Go

• Auto-detect if config file exists
• Confirm with user

Project Name - kebab-case format

• Validation: ^[a-z][a-z0-9-]*$, 3-50 chars, no consecutive hyphens

Project Description - One-line summary

Runtime Version - Stack-specific with smart defaults

• Node.js: 20 (default), 18, 21, or custom
• Python: 3.12 (default), 3.11, 3.10, or custom
• Rust/Go: Auto-detect latest

Author Name - Optional, defaults to git config user.name

Phase 3: Template Generation

1. Copy stack templates from .claude/skills/project-init/templates/{{STACK}}/

2. Replace all placeholders:

   • {{PROJECT_NAME}} → user input
   • {{PROJECT_DESCRIPTION}} → user input
   • {{RUNTIME_VERSION}} → detected/chosen version
   • {{AUTHOR_NAME}} → git config or user input

3. Handle stack-specific files:

   • Node.js: package.json, tsconfig.json, .eslintrc.json
   • Python: pyproject.toml, .python-version
   • Rust: Cargo.toml
   • Go: go.mod

Phase 4: Update .gitignore

Append stack-specific entries:

Copy# Node.js
node_modules/
dist/
.env

# Python
__pycache__/
*.pyc
.venv/
.pytest_cache/

# Rust
target/

# Go
vendor/

Phase 5: Hook Pruning

1. Read hook mappings from references/hook-mappings.md

2. Keep universal hooks (all stacks):

   • block-hardcoded-secrets
   • warn-debug-code

3. Keep stack-specific hooks:

   • Node.js/TypeScript: + warn-foreach, block-as-any
   • Python/Rust/Go: Universal only

4. Delete irrelevant hooks from .claude/hooks/

5. Update .claude/hooks/README.md to remove deleted entries

Phase 6: Documentation Updates

Update these files (replace placeholders):

README.md:

Copy# {{PROJECT_TITLE}}

{{PROJECT_DESCRIPTION}}

CLAUDE.md - Add Essential Commands section with:

• Install: {{INSTALL_COMMAND}}
• Dev: {{DEV_COMMAND}}
• Test: {{TEST_COMMAND}}
• Lint: {{LINT_COMMAND}}
• Build: {{BUILD_COMMAND}}

AGENTS.md:

CopyThis repository contains {{PROJECT_NAME}}: {{PROJECT_DESCRIPTION}}

docs/setup.md - Fill in TODOs:

• Runtime: {{RUNTIME_VERSION}}
• Package manager: {{PACKAGE_MANAGER}}
• Commands: Install, Run, Test, Lint

docs/architecture.md - Fill in TODOs:

• Summary: {{PROJECT_DESCRIPTION}}
• Stack: {{STACK}}

Phase 7: Cleanup

1. Delete .gitkeep files from src/, content/, tasks/
2. Remove "Using This As a Template" section from README.md

Phase 8: Validation

Run validation script:

Copypython .claude/skills/project-init/scripts/validate_config.py

Checks:

• No unreplaced {{VARIABLE}} placeholders
• JSON files valid (package.json, .eslintrc.json)
• TOML files valid (pyproject.toml, Cargo.toml)
• .gitignore updated with stack entries

If validation fails → Show errors and exit If validation passes → Continue to summary

Phase 9: Summary & Next Steps

Output:

Copy✅ Project Initialized: {{PROJECT_NAME}}

📋 Stack: {{STACK}}
📋 Runtime: {{RUNTIME_VERSION}}
📋 Package Manager: {{PACKAGE_MANAGER}}

📝 Files Created:
  - Stack-specific configs (package.json, pyproject.toml, etc.)
  - .env.example

📄 Files Updated:
  - README.md, CLAUDE.md, AGENTS.md
  - docs/setup.md, docs/architecture.md
  - .gitignore

🧹 Hooks Pruned:
  - warn-foreach (if not Node.js)
  - block-as-any (if not Node.js)
  [other stack-specific removals]

## Next Steps:

1. Review changes: git diff
2. Install dependencies: {{INSTALL_COMMAND}}
3. Run tests: {{TEST_COMMAND}}
4. Commit: git add -A && git commit -m "chore: initialize {{PROJECT_NAME}}"
5. Start coding with /task-planner and /git-commit

Happy coding! 🚀

---

References

• Placeholder Guide: references/placeholder-guide.md
• Hook Mappings: references/hook-mappings.md
• Stack Templates: templates/{stack}/
• Validation: scripts/validate_config.py

Rollback

If initialization fails:

Copygit restore .        # Undo all changes
git clean -fd        # Remove new files
git status           # Verify clean state