Shaktra init

/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:

Field	Prompt	Default	Valid Values
name	Project name?	Current directory name	Any string
type	Greenfield or brownfield?	greenfield	greenfield, brownfield
language	Primary language?	(none)	python, typescript, javascript, go, java, rust, ruby, php, csharp, other
architecture	Architecture style?	(none)	layered, hexagonal, clean, mvc, feature-based, event-driven, or blank
test_framework	Test framework?	Infer from language	pytest, jest, vitest, mocha, go test, junit, rspec, phpunit, xunit, or custom
coverage_tool	Coverage tool?	Infer from language	coverage.py, istanbul/nyc, c8, go cover, jacoco, simplecov, phpunit, coverlet, or custom
package_manager	Package manager?	Infer from language	pip, poetry, uv, npm, yarn, pnpm, go mod, maven, gradle, cargo, bundler, composer, dotnet, or custom

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