/shaktra:init — Project Initialization

Prerequisites

• Must be run from the root of a project directory
• .shaktra/ directory must NOT already exist (prevents double-init)

Execution Steps

Step 0: Verify Prerequisites

Run python3 -c "import yaml" via Bash.

If the command fails (non-zero exit code), stop and report: "Shaktra requires PyYAML for its hook scripts. Install with: pip install pyyaml Then run /shaktra:init again."

Do not proceed to Step 1 until PyYAML is confirmed installed.

Step 1: Guard Against Double Initialization

Check if .shaktra/ directory exists in the current working directory.

• If it exists: stop immediately and report — "Shaktra is already initialized in this project. To reinitialize, remove the .shaktra/ directory first."
• If it does not exist: proceed.

Step 2: Gather Project Information

Ask the user for the following project details. Present these as a single prompt, offering sensible defaults where possible:

Inference rules for defaults:

• python → pytest, coverage.py, pip
• typescript / javascript → jest, istanbul/nyc, npm
• go → go test, go cover, go mod
• java → junit, jacoco, maven
• rust → cargo test, cargo-tarpaulin, cargo
• ruby → rspec, simplecov, bundler
• php → phpunit, phpunit, composer
• csharp → xunit, coverlet, dotnet

Step 3: Create Directory Structure

Create the following directories:

.shaktra/
.shaktra/memory/
.shaktra/stories/
.shaktra/designs/
.shaktra/analysis/

Step 4: Copy and Populate Templates

Read template files from ${CLAUDE_PLUGIN_ROOT}/templates/ and write them into .shaktra/:

All 7 template files must be copied. Read each from ${CLAUDE_PLUGIN_ROOT}/templates/ and write to .shaktra/:

1. templates/settings.yml → .shaktra/settings.yml — Replace empty project: fields with user's answers from Step 2
2. templates/principles.yml → .shaktra/memory/principles.yml — Copy as-is
3. templates/anti-patterns.yml → .shaktra/memory/anti-patterns.yml — Copy as-is
4. templates/procedures.yml → .shaktra/memory/procedures.yml — Copy as-is
5. templates/sprints.yml → .shaktra/sprints.yml — Copy as-is
6. templates/analysis-manifest.yml → .shaktra/analysis/manifest.yml — Copy as-is
7. templates/shaktra-CLAUDE.md → .shaktra/CLAUDE.md — Copy as-is (project state documentation — describes what .shaktra/ contains)

For settings.yml, populate the project: section with the gathered values:

project:
  name: "<user's project name>"
  type: "<greenfield or brownfield>"
  language: "<user's language>"
  architecture: "<user's architecture style, or empty>"
  test_framework: "<user's test framework>"
  coverage_tool: "<user's coverage tool>"
  package_manager: "<user's package manager>"

Architecture field notes:

• For greenfield: ask user to choose an architecture style. If unsure, leave blank — the architect agent will propose one in the first design doc and it gets recorded in principles.yml.
• For brownfield: leave blank at init. The /shaktra:analyze workflow detects the existing architecture (D1: structure.yml) and the user can populate this field after analysis.

All other sections (tdd, quality, analysis, sprints, memory) retain their template defaults.

Step 5: Handle Project CLAUDE.md

Read the project CLAUDE.md template from ${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md.

This template is a generic project documentation wireframe — no Shaktra-specific content. It includes:

• Project overview section with placeholders for name, purpose, technologies
• Development workflow and code style guidance
• Architecture section with component descriptions
• Quality standards and testing requirements
• Deployment and operations procedures
• Decision log
• Contributing guidelines

Note: A separate .shaktra/CLAUDE.md file is also created to document the .shaktra/ directory structure and how Shaktra agents use it.

If no CLAUDE.md exists in the project root:

• Create CLAUDE.md with the template content.

If CLAUDE.md already exists in the project root:

• Do NOT overwrite the existing file.
• Report to user: "CLAUDE.md already exists. Shaktra initialization complete. You can update CLAUDE.md with your project-specific information, or run /init CLAUDE.md to have Claude fill it in."

Step 5b: Handle Legacy Migration (Upgrade Path)

If .shaktra/memory/decisions.yml or .shaktra/memory/lessons.yml already exist (upgrading from a previous Shaktra version):

1. Inform the user: "Legacy memory files detected (decisions.yml, lessons.yml). These have been replaced by the new principles-based memory system."
2. Offer to run migration: "Run the migration script to convert existing decisions and lessons into principles? (recommended)"
3. If yes: execute python3 ${CLAUDE_PLUGIN_ROOT}/scripts/migrate_memory.py <project_root>
4. If no: inform user they can run it later manually

Step 6: Report Results

Display a summary of what was created:

Shaktra initialized successfully!

Project: <name> (<type>)
Language: <language>
Test Framework: <test_framework>
Coverage Tool: <coverage_tool>
Package Manager: <package_manager>

Created:
  .shaktra/CLAUDE.md                    # Project state documentation (.shaktra/ structure and contents)
  .shaktra/settings.yml
  .shaktra/sprints.yml
  .shaktra/memory/principles.yml
  .shaktra/memory/anti-patterns.yml
  .shaktra/memory/procedures.yml
  .shaktra/analysis/manifest.yml
  .shaktra/memory/
  .shaktra/stories/
  .shaktra/designs/
  .shaktra/analysis/
  CLAUDE.md (created | already exists)

Next steps:
  1. Update CLAUDE.md with your project-specific information
  2. Review .shaktra/settings.yml and adjust thresholds if needed
  3. For brownfield projects: run /shaktra:analyze to understand the existing codebase
  4. Run /shaktra:tpm to create design docs and stories
  5. Run /shaktra:help for available commands and workflows