@anhth2/spec-driven-dev-plugin 0.5.0

package/modules/react/stack-profile.yaml

@@ -0,0 +1,63 @@
+build:
+  compile: "npm run build"
+  test: "npm test"
+  run: "npm run dev"
+  lint: "npm run lint"
+
+architecture:
+  style: "Feature-based (components → hooks → queries → store)"
+  key_rules:
+    - "Business logic lives in custom hooks, not in components"
+    - "Server state managed by React Query (useQuery / useMutation)"
+    - "Client-only UI state managed by Zustand or useState"
+    - "Components must be pure functions — no direct API calls inside JSX"
+    - "Shared UI primitives in components/ui/, feature logic in features/{name}/"
+    - "Never fetch data directly in a component — use a custom hook"
+  folder_structure: |
+    src/
+    ├── api/              ← axios instance, interceptors
+    ├── components/
+    │   └── ui/           ← reusable primitives (Button, Modal, Table...)
+    ├── features/
+    │   └── {domain}/
+    │       ├── components/   ← feature-specific UI
+    │       ├── hooks/        ← useOrderList, useCreateOrder...
+    │       ├── queries/      ← React Query definitions
+    │       ├── store/        ← Zustand slice (if needed)
+    │       └── types.ts
+    ├── pages/            ← route-level page components
+    └── lib/              ← utilities, formatters, constants
+
+coding_standards:
+  naming:
+    components: "PascalCase (e.g., OrderList, CreateOrderModal)"
+    hooks: "camelCase with 'use' prefix (e.g., useOrderList, useCreateOrder)"
+    query_keys: "SCREAMING_SNAKE_CASE array (e.g., ['ORDER_LIST', customerId])"
+    stores: "camelCase + Store suffix (e.g., useCartStore)"
+    files:
+      component: "{Feature}.tsx"
+      hook: "use{Feature}.ts"
+      query: "{feature}.queries.ts"
+      store: "{feature}.store.ts"
+      types: "{feature}.types.ts"
+  patterns:
+    data_fetching: "React Query (TanStack Query v5)"
+    global_state: "Zustand slices"
+    forms: "React Hook Form + Zod validation"
+    api_client: "Axios with interceptors for auth + error handling"
+    error_boundary: "React ErrorBoundary wraps each feature route"
+
+testing:
+  unit: "Vitest + React Testing Library"
+  e2e: "Playwright or Cypress"
+  patterns:
+    - "Test behavior, not implementation — query by role/label, not className"
+    - "Mock React Query with a QueryClient wrapper in test setup"
+    - "Use MSW (Mock Service Worker) to mock API calls in tests"
+    - "renderWithProviders() helper wraps component with QueryClient + Router"
+
+trace_tags:
+  implements: "// @trace.implements={UC-ID}-SC{N}"
+  source: "// @trace.source=specs/bdd/{domain}/{UC-ID}.feature"
+  verifies: "// @trace.verifies={UC-ID}"
+  test_type: "// @trace.test_type=unit|integration"

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@anhth2/spec-driven-dev-plugin",
+  "version": "0.5.0",
+  "description": "AI-First Spec-Driven Development workflow plugin for Claude Code",
+  "bin": {
+    "spec-driven-dev": "./bin/index.js"
+  },
+  "scripts": {
+    "build": "node bin/build.js",
+    "prepublishOnly": "node bin/build.js",
+    "pub": "npm publish --access=public",
+    "dev": "node bin/build.js && node bin/index.js --init",
+    "prepack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync(f)) fs.renameSync(f,'__'+f); });\"",
+    "postpack": "node -e \"const fs=require('fs'); ['README.md','PUBLISHING.md','SETUP_GUIDE.md'].forEach(f=>{ if(fs.existsSync('__'+f)) fs.renameSync('__'+f,f); });\""
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "core/",
+    "hooks/",
+    "modules/",
+    "rules/",
+    "scripts/",
+    "skills/",
+    "steps/",
+    "templates/",
+    "ARCHITECTURE.md"
+  ],
+  "keywords": ["claude-code", "spec-driven", "ai-first", "bdd", "traceability", "workflow"],
+  "author": "Edupia Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TranHongAnh2k/spec-driven-dev"
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/data-protection.md

@@ -0,0 +1,80 @@
+# Data Protection Rules
+
+> These rules are loaded by `steps/context-loader.md` at the start of every command.
+> AI agents MUST follow these rules without exception.
+
+---
+
+## NEVER Read — Sensitive Files
+
+The following file patterns contain credentials, secrets, or private keys.
+**Do NOT read, display, log, or reference their contents under any circumstance.**
+
+### Environment & Secrets
+- `.env`
+- `.env.*` (e.g., `.env.local`, `.env.production`, `.env.staging`)
+- `*.secret`
+- `secrets/` (entire directory)
+- `.secrets/` (entire directory)
+- `*credentials*`
+
+### Cryptographic Keys & Certificates
+- `*.key`
+- `*.pem`
+- `*.p12`
+- `*.pfx`
+- `*.jks`
+- `*.keystore`
+- `*.crt` / `*.cert`
+
+### Framework-Specific Config Files (may contain DB passwords, API keys)
+- `application-prod.yml` / `application-prod.properties`
+- `application-production.yml`
+- `appsettings.Production.json`
+- `appsettings.Staging.json`
+- `database.yml` (Rails)
+- `config/master.key` (Rails)
+- `storage/oauth-private.key`
+
+### Files Matching Dangerous Keywords
+Any file whose name contains (case-insensitive):
+- `password`
+- `passwd`
+- `secret`
+- `private_key`
+- `api_key`
+- `access_token`
+- `auth_token`
+
+---
+
+## NEVER Write or Modify
+
+- Any file listed above
+- `*.lock` files that are not package lock files (e.g., `*.lock` outside of `package-lock.json`, `yarn.lock`, `composer.lock`)
+
+---
+
+## NEVER Execute via Bash
+
+- Commands that print secrets: `printenv`, `env | grep -i secret`, `cat .env`
+- Commands that expose credentials: `docker inspect`, `kubectl get secret -o yaml`
+- Git commands that may expose history of secrets: `git show`, `git log -p` on config files
+
+---
+
+## Safe Alternatives
+
+If context about environment configuration is needed:
+
+1. Ask the user to describe the configuration **without sharing actual values**.
+2. Reference the **structure** of config (keys, not values): "I see you use `DATABASE_URL` — I'll generate code that reads from that variable."
+3. Use placeholder values in generated code: `process.env.DATABASE_URL` or `${DATABASE_URL}`.
+
+---
+
+## If a Sensitive File is Accidentally Accessed
+
+1. Do NOT display or repeat any content from the file.
+2. Immediately stop and notify the user: "I've detected a sensitive file. I will not read or use its contents."
+3. Ask the user what they actually need (usually it's the structure, not the values).

package/rules/workflow.md

@@ -0,0 +1,44 @@
+# Workflow Rules
+
+> General AI behavior rules for all spec-driven-dev commands.
+> Loaded by `steps/context-loader.md` at the start of every command.
+
+---
+
+## Checkpoints
+
+- **Always** show a CHECKPOINT before making significant changes.
+- A CHECKPOINT must include: what will be done, which files will be created/modified, estimated scope.
+- Wait for explicit "Y" or user confirmation before proceeding.
+- Exception: read-only analysis commands (`/review-code`, `/validate-traces`, `/debug`) may skip CHECKPOINT.
+
+## Scope Control
+
+- Work only within the scope explicitly confirmed at CHECKPOINT.
+- Do NOT create files outside the directories specified in `project-context.yaml → paths`.
+- If new scope is discovered mid-command, STOP and ask: "I found additional scope [{description}]. Should I include it? (Y/N)"
+
+## Code Generation
+
+- Never generate code for files not backed by a `.feature` spec (unless `/fix-bug` or `/debug`).
+- Always add `@trace.implements` tags on controller-level methods.
+- Never overwrite existing business logic without explicit confirmation.
+- Build must pass before committing: run `{conventions.build_command}` and fix errors (max 3 retries).
+
+## File Operations
+
+- Prefer **editing** existing files over replacing them entirely.
+- When creating new files, check if a similar file already exists first.
+- Never delete files unless explicitly instructed.
+
+## Communication
+
+- Report in the language the user writes in (Vietnamese if user uses Vietnamese, English otherwise).
+- Keep reports structured: status, artifacts created, next recommended command.
+- If unsure about business intent, ask — do not guess and generate wrong spec.
+
+## Error Handling
+
+- If a tool call fails (file not found, build error, etc.), report the specific error clearly.
+- Do NOT silently skip errors or pretend success.
+- Suggest a concrete fix, not just "please check the error".

package/scripts/init.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# init.sh — First-time setup of Spec-Driven Dev framework in a consumer project.
+#
+# Usage:
+#   bash scripts/init.sh
+#   bash scripts/init.sh --module java-spring
+#   bash scripts/init.sh --module java-spring --hooks
+#
+# What it does:
+#   1. Copies framework files to .agent/ (commands, steps, hooks, rules, templates, modules)
+#   2. Creates lightweight shortcut files in .claude/commands/ that delegate to .agent/
+#   3. Writes .agent/FRAMEWORK_VERSION for upgrade.sh to track installed version
+#
+# After init:
+#   - Commit .agent/ to git so the entire team shares the framework
+#   - Run /setup-ai-first in Claude Code to complete project setup
+#   - To upgrade later: bash scripts/upgrade.sh
+
+set -euo pipefail
+
+echo ""
+echo "╔══════════════════════════════════════════╗"
+echo "║   Spec-Driven Dev — Project Init         ║"
+echo "╚══════════════════════════════════════════╝"
+echo ""
+
+# ── Prerequisite check ────────────────────────────────────────────────────────
+
+if ! command -v node &> /dev/null; then
+  echo "❌ Node.js is required. Install from https://nodejs.org"
+  exit 1
+fi
+
+# ── Run installer via npx ─────────────────────────────────────────────────────
+
+echo "Running: npx @anhth2/spec-driven-dev --init $*"
+echo ""
+
+npx -y @anhth2/spec-driven-dev --init "$@"
+
+echo ""
+echo "✅ Init complete!"
+echo ""
+echo "Recommended next steps:"
+echo "  git add .agent/ .claude/commands/"
+echo "  git commit -m 'chore: init spec-driven-dev framework'"
+echo ""
+echo "Then open Claude Code and run: /setup-ai-first"
+echo ""

package/scripts/upgrade.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# upgrade.sh — Upgrade Spec-Driven Dev framework in an existing project.
+#
+# Usage:
+#   bash scripts/upgrade.sh
+#   bash scripts/upgrade.sh --module java-spring   # also upgrade a stack module
+#
+# What it does:
+#   1. Reads current installed version from .agent/FRAMEWORK_VERSION
+#   2. Checks npm registry for the latest published version
+#   3. If newer: runs npx @anhth2/spec-driven-dev@latest --init to update .agent/
+#   4. Reports what changed so you can review before committing
+#
+# Requirements:
+#   - Project was set up with init.sh (or npx ... --init)
+#   - .agent/FRAMEWORK_VERSION exists
+
+set -euo pipefail
+
+AGENT_DIR=".agent"
+VERSION_FILE="${AGENT_DIR}/FRAMEWORK_VERSION"
+
+echo ""
+echo "╔══════════════════════════════════════════╗"
+echo "║   Spec-Driven Dev — Upgrade              ║"
+echo "╚══════════════════════════════════════════╝"
+echo ""
+
+# ── Prerequisite checks ───────────────────────────────────────────────────────
+
+if ! command -v node &> /dev/null; then
+  echo "❌ Node.js is required. Install from https://nodejs.org"
+  exit 1
+fi
+
+if ! command -v npm &> /dev/null; then
+  echo "❌ npm is required. Install Node.js from https://nodejs.org"
+  exit 1
+fi
+
+if [ ! -f "$VERSION_FILE" ]; then
+  echo "❌ .agent/FRAMEWORK_VERSION not found."
+  echo ""
+  echo "   This project was not set up with --init."
+  echo "   To set up the new structure:"
+  echo ""
+  echo "     bash scripts/init.sh"
+  echo "   or:"
+  echo "     npx @anhth2/spec-driven-dev --init"
+  echo ""
+  exit 1
+fi
+
+# ── Version comparison ────────────────────────────────────────────────────────
+
+CURRENT=$(cat "$VERSION_FILE" | tr -d '[:space:]')
+echo "Checking npm registry ..."
+
+LATEST=$(npm view @anhth2/spec-driven-dev version 2>/dev/null || echo "unknown")
+
+echo ""
+echo "  Installed : v${CURRENT}"
+echo "  Latest    : v${LATEST}"
+echo ""
+
+if [ "$LATEST" = "unknown" ]; then
+  echo "⚠️  Could not reach npm registry. Check your internet connection."
+  exit 1
+fi
+
+if [ "$CURRENT" = "$LATEST" ]; then
+  echo "✅ Already up to date (v${CURRENT}). Nothing to do."
+  echo ""
+  exit 0
+fi
+
+# ── Upgrade ───────────────────────────────────────────────────────────────────
+
+echo "Upgrading v${CURRENT} → v${LATEST} ..."
+echo ""
+
+npx -y @anhth2/spec-driven-dev@latest --init "$@"
+
+# ── Post-upgrade guidance ─────────────────────────────────────────────────────
+
+echo ""
+echo "✅ Upgraded to v${LATEST}!"
+echo ""
+echo "Review what changed in .agent/ before committing:"
+echo ""
+echo "  git diff .agent/"
+echo "  git add .agent/"
+echo "  git commit -m 'chore: upgrade spec-driven-dev v${CURRENT} → v${LATEST}'"
+echo ""