# Shaktra Init

> Initialize the Shaktra framework in the current project. Creates the .shaktra/ directory structure, populates configuration from templates, and sets up the project CLAUDE.md.

- Skill: `im-shashanks/shaktra-init` (Agent Skill)
- Install (CLI): `npx skillmds@latest add im-shashanks/shaktra-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/im-shashanks/shaktra-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: im-shashanks (https://skillmd.com/u/im-shashanks)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/im-shashanks/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:

```yaml
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
```