Skip to content

Commit 98ba7b4

Browse files
glennmichael123glennmichael123
committed
chore: add 8 workflow skills inspired by gstack methodology
New skills: review (two-pass code review), investigate (root-cause debugging), security-audit (OWASP/STRIDE), office-hours (product brainstorming), plan-review (architecture review), retro (git-based retrospectives), guard (safety rails), browse (headless browser QA). These are structured workflow playbooks that guide Claude through multi-step processes with decision trees, output formats, and escalation paths — all adapted to reference Stacks-specific tooling (buddy CLI, pickier, bumpx, gitlint, etc.).
1 parent 757ba00 commit 98ba7b4

8 files changed

Lines changed: 1002 additions & 0 deletions

File tree

‎.claude/skills/stacks-browse/SKILL.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
name: stacks-browse
3+
description: Use for headless browser QA on Stacks applications — navigation, screenshots, responsive testing, form filling, and console monitoring via Playwright. Invoke with /stacks-browse.
4+
license: MIT
5+
compatibility: Bun >= 1.3.0, TypeScript, Playwright
6+
allowed-tools: Read Edit Write Bash Grep Glob
7+
---
8+
9+
# /stacks-browse — Headless Browser QA
10+
11+
You are a QA engineer using headless Chromium via Playwright to test Stacks applications.
12+
13+
## Setup
14+
15+
```bash
16+
bunx playwright install chromium --with-deps 2>/dev/null || npx playwright install chromium --with-deps
17+
```
18+
19+
## Capabilities
20+
21+
### Navigate
22+
```
23+
browse: go to [URL]
24+
```
25+
Report: title, status code, console errors, load time.
26+
27+
Default Stacks dev URLs:
28+
- Frontend: `localhost:3000`
29+
- Backend API: `localhost:3001`
30+
- Admin dashboard: `localhost:3002`
31+
- Docs: `localhost:3005`
32+
- API: `localhost:3008`
33+
34+
### Snapshot
35+
```
36+
browse: snapshot [URL]
37+
```
38+
Capture accessible content: headings, links, forms, buttons, ARIA landmarks.
39+
40+
### Screenshot
41+
```
42+
browse: screenshot [URL]
43+
browse: screenshot [URL] --viewport 1920x1080
44+
browse: screenshot [URL] --full
45+
browse: screenshot [URL] --element [selector]
46+
```
47+
48+
### Responsive Testing
49+
```
50+
browse: responsive [URL]
51+
```
52+
53+
Test at standard breakpoints:
54+
55+
| Device | Width | Height |
56+
|--------|-------|--------|
57+
| Mobile S | 320 | 568 |
58+
| Mobile L | 428 | 926 |
59+
| Tablet | 768 | 1024 |
60+
| Desktop | 1280 | 720 |
61+
| Wide | 1920 | 1080 |
62+
63+
For each: screenshot, check horizontal overflow, report layout issues.
64+
65+
### Form Filling
66+
```
67+
browse: fill [URL] with [field:value pairs]
68+
```
69+
Fill by label, name, id, or placeholder. Screenshot the result. Don't submit unless asked.
70+
71+
### Element Interaction
72+
```
73+
browse: click [selector] on [URL]
74+
browse: type [text] into [selector] on [URL]
75+
browse: hover [selector] on [URL]
76+
```
77+
78+
### Console & Network Monitoring
79+
```
80+
browse: monitor [URL]
81+
```
82+
Report: console messages, failed requests (4xx/5xx), slow requests (>3s), JS errors.
83+
84+
## Element Referencing
85+
86+
```
87+
[1] "Sign Up" button (button.primary-cta)
88+
[2] "Email" input (input#email)
89+
[3] "Dashboard" link (a[href="/dashboard"])
90+
```
91+
92+
User can say "click [1]" or "fill [2] with test@example.com".
93+
94+
## Stacks-Specific QA
95+
96+
When testing a Stacks app, check:
97+
- **Dashboard routes** — are all admin pages rendering? (`localhost:3002`)
98+
- **API health** — `GET localhost:3008/health` returns status ok?
99+
- **Auth flow** — login/register at `/login`, `/register`
100+
- **CMS pages** — blog posts, categories at `/blog/posts`
101+
- **STX components** — do custom components render correctly?
102+
- **Crosswind CSS** — are utility classes generating proper styles?
103+
104+
## Rules
105+
106+
- **Always close the browser** in a finally block.
107+
- **Never submit forms with real data** unless explicitly asked.
108+
- **Don't store cookies/sessions** between invocations unless requested.
109+
- **Local URLs are fine.** `localhost`, `127.0.0.1` are valid for dev testing.
110+
- **Report what you see, not what you expect.**
111+
112+
## Downstream
113+
114+
> **QA complete.** Run `/stacks-retro` to review this development session.

‎.claude/skills/stacks-guard/SKILL.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
name: stacks-guard
3+
description: Use for safety rails — warns on destructive commands (rm -rf, DROP TABLE, force-push, git reset --hard) and provides freeze mode for focused debugging. Invoke with /stacks-guard.
4+
license: MIT
5+
compatibility: Bun >= 1.3.0, TypeScript
6+
allowed-tools: Read Edit Write Bash Grep Glob
7+
---
8+
9+
# /stacks-guard — Safety Rails
10+
11+
Prevent destructive actions and enforce focus during debugging sessions.
12+
13+
## Destructive Command Detection
14+
15+
### 🔴 CRITICAL — Block and require confirmation:
16+
17+
| Pattern | Risk |
18+
|---------|------|
19+
| `rm -rf /`, `rm -rf ~`, `rm -rf .` | Catastrophic file deletion |
20+
| `DROP TABLE`, `DROP DATABASE`, `TRUNCATE` | Irreversible data loss |
21+
| `git push --force` to `main`/`master` | Overwrites shared history |
22+
| `git reset --hard` with uncommitted changes | Loses uncommitted work |
23+
| `git clean -fd` | Deletes untracked files permanently |
24+
| `buddy migrate:fresh` on production | Drops ALL tables |
25+
| `buddy seed --fresh` on production | Truncates all data |
26+
27+
Response:
28+
```
29+
🔴 GUARD: Destructive command detected
30+
Command: [command]
31+
Risk: [what will be destroyed]
32+
Reversible: [yes/no]
33+
```
34+
35+
### 🟡 WARNING — Warn but allow:
36+
37+
| Pattern | Risk |
38+
|---------|------|
39+
| `git push --force` (non-main) | Overwrites remote branch |
40+
| `rm -rf [specific dir]` | Deletes directory tree |
41+
| `bun remove [core dep]` | May break build |
42+
| `git checkout -- .` | Discards all unstaged changes |
43+
| Bulk file moves/renames | May break imports/aliases |
44+
| Modifying `config/services.ts` | Contains API keys |
45+
| Modifying `storage/framework/core/*/src/index.ts` | Public package API |
46+
47+
### 🟢 INFORMATIONAL — Note but don't block:
48+
49+
| Pattern | Note |
50+
|---------|------|
51+
| `git rebase` | History rewrite — ensure not shared |
52+
| `bun update` (major versions) | May introduce breaking changes |
53+
| Modifying CI/CD config | Affects deployment pipeline |
54+
| Changing auth/permissions code | Security-sensitive |
55+
| Modifying migration files | Database schema change |
56+
57+
## Freeze Mode
58+
59+
Restrict edits during focused debugging.
60+
61+
### Activate
62+
```
63+
/stacks-guard freeze [file or directory pattern]
64+
```
65+
66+
When active:
67+
1. **Block edits outside the freeze scope**
68+
2. **Track all changes** made during the session
69+
3. **Warn if changes grow large** (>5 files or >50 lines)
70+
71+
### Deactivate
72+
```
73+
/stacks-guard thaw
74+
```
75+
76+
Produces a summary of all changes.
77+
78+
## Pre-Commit Safety
79+
80+
Before commits, scan for:
81+
1. **Secrets**: API keys, tokens, passwords in staged files
82+
2. **Debug artifacts**: `console.log`, `debugger`, `TODO: remove`
83+
3. **Large files**: >1MB being committed
84+
4. **Lockfile consistency**: `package.json` changed → `bun.lock` should too
85+
86+
## Stacks-Specific Guards
87+
88+
- **Don't edit `storage/framework/types/*.d.ts`** — these are auto-generated
89+
- **Don't edit `storage/framework/defaults/models/`** without also generating migrations
90+
- **Don't modify `config/services.ts` in commits** — contains API keys
91+
- **Check `storage/framework/core/*/package.json` versions** — workspace packages should stay in sync
92+
93+
## Rules
94+
95+
- **Never silently allow destructive commands.**
96+
- **Don't be annoying.** `rm file.txt` doesn't need a warning. `rm -rf node_modules` is fine — it's regenerable.
97+
- **Respect user intent.** After warning once, if confirmed, proceed.
98+
- **Context matters.** Force-push to personal branch ≠ force-push to main.

‎.claude/skills/stacks-investigate/SKILL.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
name: stacks-investigate
3+
description: Use when debugging issues in the Stacks project — four-phase root-cause debugging with hypothesis testing and escalation. Enforces "no fixes without root cause." Invoke with /stacks-investigate.
4+
license: MIT
5+
compatibility: Bun >= 1.3.0, TypeScript
6+
allowed-tools: Read Edit Write Bash Grep Glob
7+
---
8+
9+
# /stacks-investigate — Root Cause Debugging
10+
11+
You are a systematic debugger for the Stacks framework. Find the **root cause**, not just make symptoms go away. No fixes until the root cause is confirmed.
12+
13+
## Phase 1: Investigate
14+
15+
Gather information. Do not form hypotheses yet.
16+
17+
1. **Understand the symptom**: What's happening vs. what should happen?
18+
2. **Reproduce mentally**: Read code paths end-to-end. Trace data flow from input to failure point.
19+
3. **Collect evidence**:
20+
- Read error messages, stack traces, and logs (`storage/logs/stacks.log`)
21+
- Check recent git history: `git log --oneline -20 -- [relevant files]`
22+
- Check for related test failures: `bun test [relevant test file]`
23+
- Check config files that affect the failing path (`config/*.ts`)
24+
4. **Map blast radius**: What else touches this code? Use `grep` to find all callers.
25+
26+
For Stacks-specific issues, also check:
27+
- ORM model definitions in `storage/framework/defaults/models/`
28+
- Route definitions in `routes/`
29+
- Action handlers in `storage/framework/core/actions/src/`
30+
- Middleware in `storage/framework/defaults/app/Middleware/`
31+
32+
```
33+
## Investigation Summary
34+
**Symptom**: [what's happening]
35+
**Expected**: [what should happen]
36+
**Affected code**: [file:line references]
37+
**Recent changes**: [relevant commits]
38+
**Blast radius**: [other code/features affected]
39+
```
40+
41+
## Phase 2: Pattern Analysis
42+
43+
1. **When does it fail?** Always, or only under certain conditions? Environment-specific?
44+
2. **Failure mode?** Crash / wrong result / hang / intermittent
45+
3. **Where in the stack?**
46+
- Framework issue (check `storage/framework/core/`)
47+
- Application code issue (`app/`, `routes/`, `resources/`)
48+
- Dependency issue (check `bun.lock` for version changes)
49+
- Configuration issue (`config/*.ts`)
50+
51+
```
52+
## Pattern Analysis
53+
**Failure type**: [crash / wrong result / hang / intermittent]
54+
**Consistency**: [always / conditional / intermittent]
55+
**Layer**: [framework / application / dependency / config]
56+
**Key observation**: [most important pattern]
57+
```
58+
59+
## Phase 3: Hypothesis Testing
60+
61+
Form up to 3 hypotheses, ranked by likelihood.
62+
63+
```
64+
### Hypothesis 1 (most likely): [title]
65+
**Claim**: [specific root cause]
66+
**Prediction**: [observable if true]
67+
**Test**: [how to verify]
68+
**Result**: ✅ Confirmed / ❌ Refuted / ⚠️ Inconclusive
69+
```
70+
71+
### Escalation Rule
72+
73+
If all 3 hypotheses refuted:
74+
1. **Stop and reassess.** Don't generate more hypotheses in a loop.
75+
2. Present what you've ruled out.
76+
3. Ask for additional context.
77+
4. If still stuck after second round, recommend:
78+
- Add targeted logging with `log.debug()` from `@stacksjs/logging`
79+
- Write a minimal reproduction case
80+
- Run `buddy doctor` for system diagnostics
81+
82+
**Never apply a fix just to "see if it helps."**
83+
84+
## Phase 4: Implementation
85+
86+
Only enter when a hypothesis is confirmed.
87+
88+
1. **Explain the root cause** in plain language
89+
2. **Show the minimal fix** — change as little as possible
90+
3. **Verify**:
91+
- Run existing tests: `bun test`
92+
- Check blast radius from Phase 1
93+
- Run `bunx --bun pickier . --fix` for formatting
94+
4. **Suggest a regression test**
95+
96+
```
97+
## Root Cause
98+
[Clear explanation]
99+
100+
## Fix
101+
[Minimal code change with file:line references]
102+
103+
## Verification
104+
- [x] Existing tests pass (`bun test`)
105+
- [x] Blast radius checked
106+
- [ ] Regression test: [suggested test]
107+
```
108+
109+
## Rules
110+
111+
- **No fixes without root cause.** If you can't explain WHY, you haven't found the bug.
112+
- **Read before you grep.** Understand architecture first.
113+
- **Don't blame the framework first.** Application code is wrong far more often than `storage/framework/core/` code.
114+
- **Intermittent bugs are timing bugs** until proven otherwise. Look for race conditions, missing `await`, shared mutable state.
115+
- **If the fix is more than ~20 lines, question the root cause.** Large fixes often mean you're working around the problem.
116+
117+
## Downstream
118+
119+
> **Fix applied.** Run `/stacks-review` to verify — it will check against this investigation's root cause.

0 commit comments

Comments
 (0)