im-shashanks /shaktra:help — Shaktra Guide
You are the Shaktra help system. When invoked, present the guide below verbatim. Do not add, omit, or rephrase sections. Use the markdown exactly as written. If the user appends a topic after the command (e.g., /shaktra:help tpm), present only the section most relevant to that topic.
Full Guide
Shaktra — Software Development Framework for Claude Code
Shaktra orchestrates 15 specialized AI agents through agile-inspired workflows. Every code change follows TDD, passes quality gates, and is reviewed before merge.
Core pillars: TDD-first | Multi-agent orchestration | Quality gates (P0-P3) | Sprint planning | Ceremony scaling
Commands
Workflow Commands
| Command | What It Does |
|---|---|
/shaktra:tpm |
Design docs, user stories, sprint planning, hotfixes. The starting point for new features. |
/shaktra:dev ST-### |
TDD implementation of a story — PLAN → RED → GREEN → QUALITY. |
/shaktra:review ST-### |
Story-level or PR-level code review across 13 quality dimensions. |
/shaktra:analyze |
Brownfield codebase analysis across 9 dimensions with parallel deep analysis. |
/shaktra:bugfix <desc> |
Bug diagnosis (5-step) followed by TDD remediation. |
/shaktra:incident <ref> |
Post-mortem, runbook, and detection gap analysis for completed bugfixes. |
/shaktra:general |
Domain expertise, architectural guidance, technical questions. |
Utility Commands
| Command | What It Does |
|---|---|
/shaktra:init |
Initialize .shaktra/ project structure — settings, memory, stories, designs. |
/shaktra:doctor |
Read-only health check — validates plugin structure, config, and constraints. |
/shaktra:workflow |
Natural language router — describe what you need, get dispatched to the right skill. |
/shaktra:help |
This guide. |
/shaktra:status-dash |
Project dashboard — version check, sprint health, quality overview. |
/shaktra-update |
Update Shaktra plugin — fetches latest, clears cache, reinstalls. |
Workflows
Greenfield Project
1. /shaktra:init → create project config
2. /shaktra:tpm → design doc → user stories → sprint plan
3. /shaktra:dev ST-001 → TDD: PLAN → RED → GREEN → QUALITY
4. /shaktra:review ST-001 → 13-dimension code review + verification tests
Brownfield Project
1. /shaktra:init → create project config (select brownfield)
2. /shaktra:analyze → 9-dimension codebase assessment
3. /shaktra:tpm → plan improvements informed by analysis
4. /shaktra:dev / review → implement and review as above
Hotfix (Fast Path)
/shaktra:tpm hotfix: users can't log in after the OAuth migration
Creates a trivial-tier story and routes directly to /shaktra:dev. Minimal ceremony, 70% coverage threshold.
Bug Fix
/shaktra:bugfix TypeError: Cannot read property 'id' of undefined in checkout flow
Runs 5-step diagnosis — triage → reproduce → root cause → blast radius → story creation — then TDD remediation.
Agent Architecture
Shaktra uses a layered system where skills orchestrate and agents execute:
User
│
├─ /shaktra:tpm ──────→ Architect, Scrummaster, Product Manager, TPM Quality
│
├─ /shaktra:dev ──────→ SW Engineer, Test Agent, Developer, SW Quality
│
├─ /shaktra:review ───→ CR Analyzer (4 parallel dimension groups)
│
├─ /shaktra:analyze ──→ CBA Analyzer (9 parallel dimensions)
│
├─ /shaktra:bugfix ───→ Bug Diagnostician → then reuses Dev pipeline
│
├─ /shaktra:incident ─→ Incident Analyst (post-mortem, runbook, gaps)
│
└─ /shaktra:general ──→ (no sub-agents — direct domain expertise)
Two-tier quality system:
- SW Quality — story-level checks during TDD. 36 checks per gate (PLAN/RED/GREEN).
- Code Reviewer — app-level review after completion. 13 dimensions + independent verification tests.
Severity taxonomy:
| Severity | Effect | Examples |
|---|---|---|
| P0 Critical | Merge blocker | Credentials in code, SQL injection, unbounded operations |
| P1 Significant | Threshold-based (default: max 2) | Missing error handling, over-mocking, placeholder code |
| P2 Quality | Logged, non-blocking | High complexity, poor naming, dead code |
| P3 Cosmetic | Logged, non-blocking | Style inconsistencies, formatting |
TDD Pipeline
Every story implementation follows this state machine:
PLAN ──→ RED ──→ GREEN ──→ QUALITY ──→ MEMORY ──→ COMPLETE
│ │ │ │
▼ ▼ ▼ ▼
SW SW SW SW
Quality Quality Quality Quality
gate gate gate (comprehensive)
- PLAN — SW Engineer creates implementation + test plan
- RED — Test Agent writes failing tests (behavioral, story-scoped)
- GREEN — Developer implements code to make tests pass and hit coverage
- QUALITY — SW Quality runs comprehensive 14-dimension review
- MEMORY — Memory Curator consolidates observations into principles, anti-patterns, and procedures
Story Tiers
Process ceremony scales with story complexity:
| Tier | Coverage | Design Doc | Quality Gates |
|---|---|---|---|
| Trivial (XS) | 70% | Skip | Minimal |
| Small (S) | 80% | Skip | Code gate only |
| Medium (M) | 90% | Required | All gates |
| Large (L) | 95% | Required | Thorough gates |
Tiers are assigned during story creation based on scope, file count, and cross-cutting concerns.
Configuration
All settings live in .shaktra/settings.yml — nothing is hardcoded.
| Setting | Default | What It Controls |
|---|---|---|
tdd.coverage_threshold |
90% | Minimum test coverage |
tdd.hotfix_threshold |
70% | Coverage for hotfix stories |
quality.p1_threshold |
2 | Max P1 findings before merge block |
review.min_verification_tests |
5 | Independent verification tests per review |
review.verification_test_persistence |
auto | Keep verification tests (auto/always/never/ask) |
sprints.sprint_duration_days |
14 | Sprint length |
Run /shaktra:doctor after changing settings to validate your configuration.
Hooks (Automated Enforcement)
Four blocking hooks enforce constraints without manual intervention:
| Hook | What It Blocks |
|---|---|
| block-main-branch | Git operations directly on main/master/prod |
| validate-story-scope | File changes outside the current story's scope |
| validate-schema | YAML files that don't match Shaktra schemas |
| check-p0-findings | Completion when unresolved P0 findings exist |
Hooks are all-or-nothing — they block or they don't exist. No warn-only mode.
Tips
- Start with
/shaktra:workflowif unsure which command to use — it routes based on natural language. - Run
/shaktra:doctorafter init to verify everything is configured correctly. - Story IDs matter —
/shaktra:dev ST-001knows exactly which story to implement. - Hotfixes are fast —
/shaktra:tpm hotfix: ...skips ceremony and routes straight to dev. - Memory persists — observations are consolidated into principles, anti-patterns, and procedures in
.shaktra/memory/and inform future work. - Ceremony scales — trivial stories skip design docs; large stories get full architecture review.
- Two quality reviewers — SW Quality checks during TDD, Code Reviewer checks after completion. They are intentionally separate.