start-vibing-stacks 2.7.0 → 2.7.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +83 -135
  2. package/dist/setup.js +2 -2
  3. package/package.json +1 -1
  4. package/stacks/_shared/skills/hook-development/SKILL.md +2 -2
package/README.md CHANGED
@@ -1,183 +1,131 @@
1
1
  # Start Vibing Stacks
2
2
 
3
- **Multi-stack AI-powered development workflow for Claude Code & Cursor.**
4
-
5
- One command to set up agents, skills, hooks, security rules, and quality gates — tailored to your stack.
3
+ Multi-stack AI workflow for Claude Code & Cursor. One command installs agents, skills, hooks, and quality gates tailored to your stack.
6
4
 
7
5
  ```bash
8
6
  npx start-vibing-stacks
9
7
  ```
10
8
 
11
- ## What It Does
12
-
13
- Start Vibing Stacks transforms Claude Code into a stack-aware AI partner. Instead of a generic assistant, you get an AI that understands your framework, enforces your coding standards, and blocks insecure patterns — all before a single line of code is written.
9
+ ## What It Installs
14
10
 
15
- ```
16
- You run the CLI
17
- ↓
18
- Detects your stack (PHP/Node.js) from project files
19
- ↓
20
- Scans existing standards (.cursorrules, composer.json, tsconfig, eslint, .env)
21
- ↓
22
- Asks: adapt to YOUR standards or use defaults?
23
- ↓
24
- Copies 6 agents + 25-40 skills + hooks + security rules
25
- ↓
26
- Generates CLAUDE.md with architecture, rules, FORBIDDEN patterns
27
- ↓
28
- Launches Claude Code — fully configured
29
- ```
11
+ | Layer | Count | Purpose |
12
+ |---|---|---|
13
+ | Agents | 7 universal | research-web, documenter, domain-updater, commit-manager, tester, claude-md-compactor, **security-auditor** (VETO) |
14
+ | Skills | 13 shared + 5–13 stack-specific + 7–9 frontend | Versioned (`version:` frontmatter), upgradable via `migrate` |
15
+ | Hooks | `stop-validator`, `final-check`, `user-prompt-submit` | Block completion on git/docs/secrets/code-quality issues |
16
+ | Commands | `/feature`, `/fix`, `/research`, `/validate` | Slash commands |
17
+ | Workflows | `ci.yml` + `security.yml` per stack | Copied to `.github/workflows/` when target is empty |
30
18
 
31
19
  ## Supported Stacks
32
20
 
33
- ### PHP 8.3+
21
+ | Stack | Frameworks | Databases | Frontend |
22
+ |---|---|---|---|
23
+ | 🐘 **PHP 8.3+** | Laravel 12 + Octane, Laravel 12 | MariaDB/MySQL, PostgreSQL, SQLite | Inertia + React, Blade, Livewire, API only |
24
+ | 📦 **Node.js / TS** | Next.js, Nuxt, Astro, Express, Fastify, Vanilla | MongoDB, Postgres, MariaDB/MySQL, SQLite/Turso, Redis, None | React + Tailwind, Vue, Svelte, API only |
25
+ | 🐍 **Python 3.12+** | FastAPI, Django 5, Flask, Local Scripts | MariaDB/MySQL, Postgres, SQLite, MongoDB, None | React, HTMX + Jinja2, API/CLI only |
34
26
 
35
- | Option | Choices |
36
- |--------|---------|
37
- | **Frameworks** | Laravel 12 + Octane (RoadRunner) + Inertia.js, Laravel 12 (standard) |
38
- | **Databases** | MySQL / MariaDB, PostgreSQL, SQLite |
39
- | **Frontend** | React 19 + Inertia.js + TailwindCSS 4, Blade + TailwindCSS, Livewire + Alpine.js, API only |
40
- | **Skills** | 13 PHP-specific (Octane, PHPStan, PHPUnit, Eloquent, API Security, Inertia i18n, ...) |
27
+ ## Universal Skills (shared across stacks)
41
28
 
42
- ### Node.js / TypeScript
29
+ | Skill | Topic |
30
+ |---|---|
31
+ | `security-baseline` | OWASP Top 10 with stack-aware examples |
32
+ | `secrets-management` | `.env` hygiene, gitleaks, rotation playbook |
33
+ | `observability` | Structured logs, OpenTelemetry, Sentry, PII redaction |
34
+ | `error-handling` | Result types, error taxonomy, retry/backoff, circuit breaker |
35
+ | `database-migrations` | Parallel change, lock timeouts, chunked backfills |
36
+ | `accessibility-wcag22` | WCAG 2.2 AA + axe-core/Playwright |
37
+ | `ci-pipelines` | GitHub Actions discipline + ready-to-use templates |
38
+ | `quality-gate` · `final-check` · `git-workflow` · `docker-patterns` · `debugging-patterns` · `performance-patterns` · `playwright-automation` · `test-coverage` · `ui-ux-audit` · `codebase-knowledge` · `docs-tracker` · `research-cache` · `hook-development` | Workflow & tooling |
43
39
 
44
- | Option | Choices |
45
- |--------|---------|
46
- | **Frameworks** | Next.js (App Router), Nuxt, Astro, Express, Fastify, Vanilla Node.js |
47
- | **Databases** | MongoDB, PostgreSQL, MySQL, SQLite/Turso, Redis (Upstash), None |
48
- | **Frontend** | React 19 + TailwindCSS 4, Vue.js / Nuxt, Svelte / SvelteKit, API only |
49
- | **Skills** | 5 Node-specific (TypeScript strict, Next.js App Router, tRPC, Bun, Mongoose) + 9 frontend skills |
40
+ Plus stack-specific: `api-security-node`, `api-security-python`, `api-security` (PHP), `typescript-strict`, `nextjs-app-router`, `trpc-api`, `bun-runtime`, `mongoose-patterns`, `pydantic-validation`, `pytest-testing`, `python-patterns`, `python-performance`, `async-patterns`, `fastapi-patterns`, `django-patterns`, `scripting-automation`, `laravel-patterns`, `laravel-octane`, `phpstan-analysis`, `phpunit-testing`, `composer-workflow`, `mariadb-octane`, `external-api-patterns`, `inertia-react`, `laravel-inertia-i18n`, `security-scan-php`, `api-design`, `php-patterns`.
50
41
 
51
- ### Python (Coming Soon)
52
-
53
- Django, FastAPI, Flask support is planned.
54
-
55
- ## What Gets Installed
42
+ ## Layout in Your Project
56
43
 
57
44
  ```
58
45
  your-project/
59
- ├── CLAUDE.md # AI memory — architecture, rules, FORBIDDEN patterns
60
- └── .claude/
61
- ├── agents/ # 6 universal agents
62
- │ ├── research-web.md # Researches best practices before new features
63
- │ ├── documenter.md # Maps files to domains, tracks changes
64
- │ ├── domain-updater.md # Records problems, solutions, learnings
65
- │ ├── commit-manager.md # Conventional commits, merge workflow
66
- │ ├── tester.md # Creates tests (Vitest/PHPUnit/Playwright)
67
- │ └── claude-md-compactor.md # Compacts CLAUDE.md when > 40k chars
68
- ├── skills/ # 25-40 skills (stack + shared + frontend)
69
- │ ├── quality-gate/ # Typecheck, lint, test validation
70
- │ ├── security-scan/ # OWASP checks per language
71
- │ ├── git-workflow/ # Branch management, conventional commits
72
- │ ├── codebase-knowledge/ # Domain documentation system
73
- │ └── ... # Stack-specific skills
74
- ├── hooks/
75
- │ ├── stop-validator.ts # Blocks incomplete tasks (branch, git, docs)
76
- │ └── user-prompt-submit.ts # Injects workflow + standards context
77
- ├── commands/ # /feature, /fix, /research, /validate
78
- ├── config/
79
- │ ├── active-project.json # Stack, framework, database, skills
80
- │ ├── security-rules.json # OWASP checks + env exposure rules
81
- │ ├── standards-review.json # Imported project standards
82
- │ └── ... # Quality gates, testing, domain mapping
83
- └── settings.json # Claude Code permissions & model config
46
+ ├── CLAUDE.md # AI memory: architecture, rules, FORBIDDEN
47
+ ├── .claude/
48
+ │ ├── agents/ # 7 universal agents
49
+ │ ├── skills/ # versioned skill set (stack + shared + frontend)
50
+ │ ├── hooks/ # stop-validator, final-check, prompt-submit
51
+ │ ├── commands/ # /feature, /fix, /research, /validate
52
+ │ └── config/ # active-project, security-rules, ...
53
+ └── .github/workflows/ # ci.yml + security.yml (if dir was empty)
84
54
  ```
85
55
 
86
- ## Security Features
87
-
88
- ### Environment Variable Protection (Node.js)
56
+ ## CLI
89
57
 
90
- The tool enforces strict separation of server and client environment variables:
58
+ ```bash
59
+ npx start-vibing-stacks # setup or resume current project
60
+ npx start-vibing-stacks migrate # show outdated/missing skills
61
+ npx start-vibing-stacks migrate --apply # update outdated skills/agents
91
62
 
92
- - **Scanner**: Detects `NEXT_PUBLIC_` with sensitive words (SECRET, TOKEN, API_KEY) in `.env*` files
93
- - **CLAUDE.md**: FORBIDDEN rules prevent AI from exposing secrets in browser bundles
94
- - **Skills**: Teach API proxy patterns — external API calls must go through Route Handlers
95
- - **security-rules.json**: Automated detection patterns for security audits
63
+ # flags: --force --no-claude --no-mcp --no-install --help --version
64
+ ```
96
65
 
97
- ### PHP Security
66
+ Global install: `npm i -g start-vibing-stacks` → `svs` (alias).
98
67
 
99
- - OWASP Top 10 adapted for Laravel + Octane
100
- - Octane-safe patterns (no static state, no globals)
101
- - `env()` restriction (config files only)
102
- - Frontend secret isolation (Inertia props)
103
- - Rate limiting, CORS, CSP, encryption at rest
68
+ ## Hooks (block completion)
104
69
 
105
- ## Standards Review
70
+ | Hook | Blocks when |
71
+ |---|---|
72
+ | `stop-validator` | not on main, uncommitted changes, CLAUDE.md missing/stale, **secret pattern in diff** (gitleaks or regex) |
73
+ | `final-check` | hardcoded secret, `eval`, SQL string concat, `.skip`/`.only`, `any`, `console.log`, `var_dump` |
74
+ | `user-prompt-submit` | injects workflow + standards context |
106
75
 
107
- Before modifying anything, the CLI scans your project for existing patterns:
76
+ ## Workflow per Task
108
77
 
109
78
  ```
110
- Scans: .cursorrules, composer.json, package.json, tsconfig.json,
111
- eslint config, phpstan.neon, .env files, framework configs,
112
- lockfiles, deploy configs, quality tool configs
113
-
114
- Detects: 50+ npm packages, 17+ Composer packages, TypeScript strict mode,
115
- path aliases, ESLint config, PHPStan level, package manager,
116
- deploy targets, exposed secrets in NEXT_PUBLIC_*
117
-
118
- Result: "Adapt to your standards" or "Use plugin defaults"
119
- → Saved in standards-review.json
120
- → Injected into every Claude prompt via hook
79
+ 1. BRANCH feature/ | fix/ | refactor/ | test/
80
+ 2. RESEARCH research-web agent (new features)
81
+ 3. IMPLEMENT stack rules + strict types + security
82
+ 4. TEST tester agent (Vitest / pytest / PHPUnit / Playwright)
83
+ 5. SECURITY security-auditor agent — VETO on findings
84
+ 6. DOCUMENT documenter agent
85
+ 7. UPDATE CLAUDE.md "Last Change" section
86
+ 8. QUALITY typecheck → lint → test → build
87
+ 9. COMMIT conventional commit, merge to main
121
88
  ```
122
89
 
123
- ## CLI Options
124
-
125
- ```bash
126
- npx start-vibing-stacks [options]
127
-
128
- --force Overwrite existing configuration
129
- --no-claude Skip Claude Code launch
130
- --no-install Skip dependency installation
131
- --help, -h Show help
132
- --version, -v Show version
133
- ```
90
+ ## Security Features
134
91
 
135
- Or install globally:
92
+ - **Environment isolation**: scanner blocks `NEXT_PUBLIC_*SECRET|*TOKEN|*PRIVATE` patterns; teaches Route Handler / Server Action proxy patterns.
93
+ - **OWASP Top 10**: stack-aware skills cover A01–A10 (broken access control, injection, SSRF, etc.).
94
+ - **Secret scanning** in `stop-validator` — gitleaks if installed, regex fallback otherwise.
95
+ - **`security-auditor` agent** with VETO — runs after tester, before commit, blocks insecure code.
96
+ - **CI templates**: gitleaks, `npm audit` / `pip-audit` / `composer audit`, CodeQL/Bandit, weekly cron.
136
97
 
137
- ```bash
138
- npm install -g start-vibing-stacks
139
- svs # shortcut alias
140
- ```
98
+ ## Standards Review
141
99
 
142
- ## How the Workflow Works
100
+ CLI scans existing config (cursorrules, composer.json, tsconfig, eslint, phpstan, `.env*`, lockfiles) and asks **"adapt to your standards or use defaults?"** Imported standards are written to `standards-review.json` and injected into every prompt.
143
101
 
144
- Once configured, Claude Code follows this workflow on every task:
102
+ ## Migrate Existing Projects
145
103
 
104
+ ```bash
105
+ npx start-vibing-stacks migrate # report drift
106
+ npx start-vibing-stacks migrate --apply # apply updates
146
107
  ```
147
- 0. TODO LIST → Creates detailed task breakdown
148
- 1. BRANCH → Creates feature/ | fix/ | refactor/ | test/
149
- 2. RESEARCH → Runs research-web agent for new features
150
- 3. IMPLEMENT → Follows stack rules + strict types + security
151
- 4. TEST → Runs tester agent (PHPUnit / Vitest / Playwright)
152
- 5. DOCUMENT → Runs documenter agent for modified files
153
- 6. UPDATE → Updates CLAUDE.md with changes
154
- 7. QUALITY → Runs quality gates (typecheck, lint, test, build)
155
- 8. COMMIT → Conventional commits, merge to main
156
- ```
157
-
158
- The **stop-validator hook** blocks task completion if:
159
- - Not on `main` branch (work must be merged)
160
- - Uncommitted changes exist
161
- - CLAUDE.md wasn't updated
162
- - Source files lack documentation
163
108
 
164
- ## Cursor IDE Support
165
-
166
- If `.cursorrules` is detected, the rules are automatically imported into the Claude configuration. Both AI tools work with the same context.
109
+ Compares `version:` in your installed `SKILL.md` files against the bundled package. Missing → install. Outdated → upgrade. Ahead (you customized) → kept. Unversioned → flagged for manual review.
167
110
 
168
111
  ## Requirements
169
112
 
170
- | Stack | Requirements |
171
- |-------|-------------|
172
- | **PHP** | PHP >= 8.3, Composer >= 2.0, Node.js >= 18 |
173
- | **Node.js** | Node.js >= 18 (Bun optional) |
113
+ | Stack | Required |
114
+ |---|---|
115
+ | PHP | PHP ≥ 8.3, Composer ≥ 2.0, Node.js ≥ 18 |
116
+ | Node.js | Node.js ≥ 18 (Bun optional) |
117
+ | Python | Python ≥ 3.12, pip ≥ 23 |
174
118
 
175
119
  Missing dependencies are auto-installed via Homebrew on macOS.
176
120
 
121
+ ## Releases
122
+
123
+ GitHub Release → npm publish (workflow `publish.yml`).
124
+ Version bump in `package.json` on `main` → auto-creates the GitHub Release (workflow `auto-release.yml`). Add `[skip release]` to the commit to opt out.
125
+
177
126
  ## Credits
178
127
 
179
- Inspired by [start-vibing](https://www.npmjs.com/package/start-vibing).
180
- Built by [FantasyLake](https://github.com/f1sc4ll-ai).
128
+ Inspired by [start-vibing](https://www.npmjs.com/package/start-vibing). Built by [FantasyLake](https://github.com/f1sc4ll-ai).
181
129
 
182
130
  ## License
183
131
 
package/dist/setup.js CHANGED
@@ -217,7 +217,7 @@ export async function setupProject(projectDir, config, options = {}) {
217
217
  hooks: [
218
218
  {
219
219
  type: 'command',
220
- command: 'npx tsx .claude/hooks/user-prompt-submit.ts',
220
+ command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/user-prompt-submit.ts"',
221
221
  timeout: 10,
222
222
  },
223
223
  ],
@@ -228,7 +228,7 @@ export async function setupProject(projectDir, config, options = {}) {
228
228
  hooks: [
229
229
  {
230
230
  type: 'command',
231
- command: 'npx tsx .claude/hooks/stop-validator.ts',
231
+ command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"',
232
232
  timeout: 30,
233
233
  },
234
234
  ],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "start-vibing-stacks",
3
- "version": "2.7.0",
3
+ "version": "2.7.4",
4
4
  "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
5
5
  "type": "module",
6
6
  "bin": {
package/stacks/_shared/skills/hook-development/SKILL.md CHANGED
@@ -77,8 +77,8 @@ console.log(JSON.stringify(result));
77
77
  ```json
78
78
  {
79
79
  "hooks": {
80
- "Stop": [{ "hooks": [{ "type": "command", "command": "bash .claude/hooks/run-hook.sh stop-validator", "timeout": 30 }] }],
81
- "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash .claude/hooks/run-hook.sh user-prompt-submit", "timeout": 10 }] }]
80
+ "Stop": [{ "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" stop-validator", "timeout": 30 }] }],
81
+ "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" user-prompt-submit", "timeout": 10 }] }]
82
82
  }
83
83
  }
84
84
  ```