tribunal-kit 2.4.6 → 3.0.0

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 (142) hide show
  1. package/.agent/agents/accessibility-reviewer.md +220 -134
  2. package/.agent/agents/ai-code-reviewer.md +233 -129
  3. package/.agent/agents/backend-specialist.md +238 -178
  4. package/.agent/agents/code-archaeologist.md +181 -119
  5. package/.agent/agents/database-architect.md +207 -164
  6. package/.agent/agents/debugger.md +218 -151
  7. package/.agent/agents/dependency-reviewer.md +136 -55
  8. package/.agent/agents/devops-engineer.md +238 -175
  9. package/.agent/agents/documentation-writer.md +221 -137
  10. package/.agent/agents/explorer-agent.md +180 -142
  11. package/.agent/agents/frontend-reviewer.md +194 -80
  12. package/.agent/agents/frontend-specialist.md +237 -188
  13. package/.agent/agents/game-developer.md +52 -184
  14. package/.agent/agents/logic-reviewer.md +149 -78
  15. package/.agent/agents/mobile-developer.md +223 -152
  16. package/.agent/agents/mobile-reviewer.md +195 -79
  17. package/.agent/agents/orchestrator.md +211 -170
  18. package/.agent/agents/penetration-tester.md +174 -131
  19. package/.agent/agents/performance-optimizer.md +203 -139
  20. package/.agent/agents/performance-reviewer.md +211 -108
  21. package/.agent/agents/product-manager.md +162 -108
  22. package/.agent/agents/project-planner.md +162 -142
  23. package/.agent/agents/qa-automation-engineer.md +242 -138
  24. package/.agent/agents/security-auditor.md +194 -170
  25. package/.agent/agents/seo-specialist.md +213 -132
  26. package/.agent/agents/sql-reviewer.md +194 -73
  27. package/.agent/agents/supervisor-agent.md +203 -156
  28. package/.agent/agents/test-coverage-reviewer.md +193 -81
  29. package/.agent/agents/type-safety-reviewer.md +208 -65
  30. package/.agent/scripts/__pycache__/auto_preview.cpython-311.pyc +0 -0
  31. package/.agent/scripts/__pycache__/bundle_analyzer.cpython-311.pyc +0 -0
  32. package/.agent/scripts/__pycache__/checklist.cpython-311.pyc +0 -0
  33. package/.agent/scripts/__pycache__/dependency_analyzer.cpython-311.pyc +0 -0
  34. package/.agent/scripts/__pycache__/security_scan.cpython-311.pyc +0 -0
  35. package/.agent/scripts/__pycache__/session_manager.cpython-311.pyc +0 -0
  36. package/.agent/scripts/__pycache__/skill_integrator.cpython-311.pyc +0 -0
  37. package/.agent/scripts/__pycache__/swarm_dispatcher.cpython-311.pyc +0 -0
  38. package/.agent/scripts/__pycache__/test_runner.cpython-311.pyc +0 -0
  39. package/.agent/scripts/__pycache__/verify_all.cpython-311.pyc +0 -0
  40. package/.agent/skills/agent-organizer/SKILL.md +126 -132
  41. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +155 -66
  42. package/.agent/skills/api-patterns/SKILL.md +289 -257
  43. package/.agent/skills/api-security-auditor/SKILL.md +172 -70
  44. package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +1 -1
  45. package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +1 -1
  46. package/.agent/skills/appflow-wireframe/SKILL.md +107 -100
  47. package/.agent/skills/architecture/SKILL.md +331 -200
  48. package/.agent/skills/authentication-best-practices/SKILL.md +168 -67
  49. package/.agent/skills/bash-linux/SKILL.md +154 -215
  50. package/.agent/skills/brainstorming/SKILL.md +104 -210
  51. package/.agent/skills/building-native-ui/SKILL.md +169 -70
  52. package/.agent/skills/clean-code/SKILL.md +360 -206
  53. package/.agent/skills/config-validator/SKILL.md +141 -165
  54. package/.agent/skills/csharp-developer/SKILL.md +528 -107
  55. package/.agent/skills/database-design/SKILL.md +455 -275
  56. package/.agent/skills/deployment-procedures/SKILL.md +145 -188
  57. package/.agent/skills/devops-engineer/SKILL.md +332 -134
  58. package/.agent/skills/devops-incident-responder/SKILL.md +113 -98
  59. package/.agent/skills/edge-computing/SKILL.md +157 -213
  60. package/.agent/skills/extract-design-system/SKILL.md +129 -69
  61. package/.agent/skills/framer-motion-expert/SKILL.md +939 -0
  62. package/.agent/skills/game-design-expert/SKILL.md +105 -0
  63. package/.agent/skills/game-engineering-expert/SKILL.md +122 -0
  64. package/.agent/skills/geo-fundamentals/SKILL.md +124 -215
  65. package/.agent/skills/github-operations/SKILL.md +314 -354
  66. package/.agent/skills/gsap-expert/SKILL.md +901 -0
  67. package/.agent/skills/i18n-localization/SKILL.md +138 -216
  68. package/.agent/skills/intelligent-routing/SKILL.md +127 -139
  69. package/.agent/skills/llm-engineering/SKILL.md +357 -258
  70. package/.agent/skills/local-first/SKILL.md +154 -203
  71. package/.agent/skills/mcp-builder/SKILL.md +118 -224
  72. package/.agent/skills/nextjs-react-expert/SKILL.md +783 -203
  73. package/.agent/skills/nodejs-best-practices/SKILL.md +559 -280
  74. package/.agent/skills/observability/SKILL.md +330 -285
  75. package/.agent/skills/parallel-agents/SKILL.md +122 -181
  76. package/.agent/skills/performance-profiling/SKILL.md +254 -197
  77. package/.agent/skills/plan-writing/SKILL.md +118 -188
  78. package/.agent/skills/platform-engineer/SKILL.md +123 -135
  79. package/.agent/skills/playwright-best-practices/SKILL.md +157 -76
  80. package/.agent/skills/powershell-windows/SKILL.md +146 -230
  81. package/.agent/skills/python-pro/SKILL.md +879 -114
  82. package/.agent/skills/react-specialist/SKILL.md +931 -108
  83. package/.agent/skills/realtime-patterns/SKILL.md +304 -296
  84. package/.agent/skills/rust-pro/SKILL.md +701 -240
  85. package/.agent/skills/seo-fundamentals/SKILL.md +154 -181
  86. package/.agent/skills/server-management/SKILL.md +190 -212
  87. package/.agent/skills/shadcn-ui-expert/SKILL.md +201 -68
  88. package/.agent/skills/sql-pro/SKILL.md +633 -104
  89. package/.agent/skills/swiftui-expert/SKILL.md +171 -70
  90. package/.agent/skills/systematic-debugging/SKILL.md +118 -186
  91. package/.agent/skills/tailwind-patterns/SKILL.md +576 -232
  92. package/.agent/skills/tdd-workflow/SKILL.md +137 -209
  93. package/.agent/skills/testing-patterns/SKILL.md +573 -205
  94. package/.agent/skills/vue-expert/SKILL.md +964 -119
  95. package/.agent/skills/vulnerability-scanner/SKILL.md +269 -316
  96. package/.agent/skills/web-accessibility-auditor/SKILL.md +188 -71
  97. package/.agent/skills/webapp-testing/SKILL.md +145 -236
  98. package/.agent/workflows/api-tester.md +151 -279
  99. package/.agent/workflows/audit.md +138 -168
  100. package/.agent/workflows/brainstorm.md +110 -146
  101. package/.agent/workflows/changelog.md +112 -144
  102. package/.agent/workflows/create.md +124 -139
  103. package/.agent/workflows/debug.md +189 -196
  104. package/.agent/workflows/deploy.md +189 -153
  105. package/.agent/workflows/enhance.md +151 -139
  106. package/.agent/workflows/fix.md +135 -143
  107. package/.agent/workflows/generate.md +157 -164
  108. package/.agent/workflows/migrate.md +160 -163
  109. package/.agent/workflows/orchestrate.md +168 -151
  110. package/.agent/workflows/performance-benchmarker.md +123 -305
  111. package/.agent/workflows/plan.md +173 -151
  112. package/.agent/workflows/preview.md +80 -137
  113. package/.agent/workflows/refactor.md +183 -153
  114. package/.agent/workflows/review-ai.md +129 -140
  115. package/.agent/workflows/review.md +116 -155
  116. package/.agent/workflows/session.md +94 -154
  117. package/.agent/workflows/status.md +79 -125
  118. package/.agent/workflows/strengthen-skills.md +139 -99
  119. package/.agent/workflows/swarm.md +179 -194
  120. package/.agent/workflows/test.md +211 -166
  121. package/.agent/workflows/tribunal-backend.md +113 -111
  122. package/.agent/workflows/tribunal-database.md +115 -132
  123. package/.agent/workflows/tribunal-frontend.md +118 -115
  124. package/.agent/workflows/tribunal-full.md +133 -136
  125. package/.agent/workflows/tribunal-mobile.md +119 -123
  126. package/.agent/workflows/tribunal-performance.md +133 -152
  127. package/.agent/workflows/ui-ux-pro-max.md +143 -171
  128. package/README.md +11 -15
  129. package/package.json +1 -1
  130. package/.agent/skills/dotnet-core-expert/SKILL.md +0 -103
  131. package/.agent/skills/framer-motion-animations/SKILL.md +0 -74
  132. package/.agent/skills/game-development/2d-games/SKILL.md +0 -119
  133. package/.agent/skills/game-development/3d-games/SKILL.md +0 -135
  134. package/.agent/skills/game-development/SKILL.md +0 -236
  135. package/.agent/skills/game-development/game-art/SKILL.md +0 -185
  136. package/.agent/skills/game-development/game-audio/SKILL.md +0 -190
  137. package/.agent/skills/game-development/game-design/SKILL.md +0 -129
  138. package/.agent/skills/game-development/mobile-games/SKILL.md +0 -108
  139. package/.agent/skills/game-development/multiplayer/SKILL.md +0 -132
  140. package/.agent/skills/game-development/pc-games/SKILL.md +0 -144
  141. package/.agent/skills/game-development/vr-ar/SKILL.md +0 -123
  142. package/.agent/skills/game-development/web-games/SKILL.md +0 -150
@@ -1,72 +1,173 @@
1
1
  ---
2
2
  name: authentication-best-practices
3
- description: Authentication and Identity Management expert. Specializes in JWTs, OIDC, HTTP-Only Cookies, and secure password hashing.
3
+ description: Authentication and Authorization mastery. Best practices for OAuth2, OpenID Connect, JWT (JSON Web Tokens), session management, password hashing, MFA (Multi-Factor Authentication), RBAC/ABAC, SSO, and secure credential storage. Use when auditing or implementing login flows, identity systems, or access control.
4
4
  allowed-tools: Read, Write, Edit, Glob, Grep
5
- version: 1.0.0
6
- last-updated: 2026-03-30
7
- applies-to-model: claude-3-7-sonnet, gemini-2.5-pro
5
+ version: 2.0.0
6
+ last-updated: 2026-04-02
7
+ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
8
  ---
9
9
 
10
- # Authentication & Session Best Practices
11
-
12
- You are an Identity and Access Management (IAM) Specialist. You are strictly forbidden from writing custom cryptography or insecure authentication flows.
13
-
14
- ## Core Directives
15
-
16
- 1. **Token Storage & JWTs:**
17
- - Never store JWTs or session tokens in `localStorage` or `sessionStorage` where they are vulnerable to XSS.
18
- - Always issue access tokens as `Secure, HttpOnly, SameSite=Strict/Lax` browser cookies.
19
- - When verifying JWTs, always explicitly define the `algorithms` array (e.g., `['HS256']`) to prevent algorithm confusion attacks where the attacker sets `alg: none`.
20
-
21
- 2. **Password Hashing:**
22
- - Never write a custom hashing algorithm.
23
- - If managing raw passwords, use `Argon2id` or `Bcrypt` with a sufficient work factor (e.g., 10-12 rounds salt).
24
- - Never log passwords, tokens, or PII to the standard `stdout` or custom loggers.
25
-
26
- 3. **Session Revocation:**
27
- - JWTs scale well but cannot be instantly revoked without a denylist. If instant revocation or device management is required, default to opaque, stateful session tokens backed by Redis or an equivalent fast KV store.
28
-
29
- ## Execution
30
- Review identity handling mechanisms forcefully. If you catch an agent or a user attempting to place a secret in client-side code, throw a high-level alert and immediately rewrite the architecture to utilize backend-for-frontend (BFF) proxying or HttpOnly cookes.
31
-
32
-
33
- ---
34
-
35
- ## 🤖 LLM-Specific Traps
36
-
37
- AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
38
-
39
- 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
40
- 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
41
- 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
42
- 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
43
- 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
44
-
45
- ---
46
-
47
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
48
-
49
- **Slash command: `/review` or `/tribunal-full`**
50
- **Active reviewers: `logic-reviewer` · `security-auditor`**
51
-
52
- ### Forbidden AI Tropes
53
-
54
- 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
55
- 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
56
- 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
57
-
58
- ### Pre-Flight Self-Audit
59
-
60
- Review these questions before confirming output:
61
- ```
62
- Did I rely ONLY on real, verified tools and methods?
63
- ✅ Is this solution appropriately scoped to the user's constraints?
64
- Did I handle potential failure modes and edge cases?
65
- ✅ Have I avoided generic boilerplate that doesn't add value?
66
- ```
67
-
68
- ### 🛑 Verification-Before-Completion (VBC) Protocol
69
-
70
- **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
71
- - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
72
- - **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
10
+ # Authentication & Authorization Identity Mastery
11
+
12
+ > Identity is the perimeter. If authentication is flawed, the entire system is breached.
13
+ > Never roll your own crypto. Never store plaintext passwords. Secure tokens are not optional.
14
+
15
+ ---
16
+
17
+ ## Passwords & Hashing
18
+
19
+ ```typescript
20
+ // ❌ BAD: md5, sha1, sha256 (too fast, vulnerable to brute force/rainbow tables)
21
+ const hash = crypto.createHash('sha256').update(password).digest('hex');
22
+
23
+ // GOOD: Argon2 (memory-hard, ASIC resistant) or bcrypt
24
+ import * as argon2 from "argon2";
25
+
26
+ async function hashPassword(password: string): Promise<string> {
27
+ // Argon2 hashes include the salt inherently in the resulting string
28
+ return await argon2.hash(password, {
29
+ type: argon2.argon2id, // recommended variant
30
+ memoryCost: 2 ** 16, // 64 MB
31
+ timeCost: 3, // iterations
32
+ parallelism: 1, // threads
33
+ });
34
+ }
35
+
36
+ async function verifyPassword(hash: string, password: string): Promise<boolean> {
37
+ return await argon2.verify(hash, password);
38
+ }
39
+ ```
40
+
41
+ ### Password Policies
42
+ - **Length over complexity**: Require minimum 12 characters. Stop requiring arbitrary symbols (e.g., `!@#`).
43
+ - **Check against breaches**: Use HaveIBeenPwned API or similar to reject compromised passwords during signup.
44
+ - **Never expire passwords arbitrarily**: Only force resets if there is evidence of a breach.
45
+
46
+ ---
47
+
48
+ ## Session Management vs. JWT
49
+
50
+ ### 1. Stateful Sessions (Cookies)
51
+ **Best for**: Monolithic web apps, SSR apps (Next.js, Remix).
52
+ - Server stores session ID mapped to user data in Redis/DB.
53
+ - Client stores session ID in an `HttpOnly`, `Secure`, `SameSite=Lax/Strict` cookie.
54
+ - **Pros**: Immediate revocation, server-side truth, invisible to XSS.
55
+ - **Cons**: Requires DB lookup per request.
56
+
57
+ ### 2. Stateless JWT (JSON Web Tokens)
58
+ **Best for**: Distributed APIs, Microservices, Native mobile apps.
59
+ - Server signs a token containing user claims.
60
+ - Client passes it in `Authorization: Bearer <token>` header.
61
+ - **Pros**: No DB lookup needed, easy cross-origin sharing.
62
+ - **Cons**: Cannot be easily revoked before expiration.
63
+
64
+ ### The JWT "Refresh Token" Pattern
65
+ ```typescript
66
+ // Scenario: API authentication
67
+ // 1. Access Token (Short-lived: 15 mins)
68
+ const accessToken = jwt.sign({ userId: user.id }, JWT_SECRET, {
69
+ expiresIn: "15m",
70
+ algorithm: "HS256" // ALWAYS explicitly specify
71
+ });
72
+ // 2. Refresh Token (Long-lived: 7 days, opaque string in DB)
73
+ const refreshToken = crypto.randomBytes(40).toString('hex');
74
+ await db.refreshTokens.create({ token: refreshToken, userId: user.id, expires: addDays(7) });
75
+
76
+ // Client flow:
77
+ // - Access token kept in memory (JS variable) to prevent XSS theft.
78
+ // - Refresh token kept in HttpOnly cookie.
79
+ // - When Access Token expires, endpoint reads cookie, validates DB, issues new Access Token.
80
+ ```
81
+
82
+ ---
83
+
84
+ ## OAuth2 & OIDC (OpenID Connect)
85
+
86
+ ```
87
+ Roles:
88
+ 1. Resource Owner (User)
89
+ 2. Client (Your App)
90
+ 3. Authorization Server (Google/GitHub/Auth0)
91
+ 4. Resource Server (API)
92
+
93
+ Flow (Authorization Code + PKCE):
94
+ 1. User clicks "Login with Google".
95
+ 2. App generates `code_verifier` and `code_challenge`.
96
+ 3. App redirects user to Google with `code_challenge`.
97
+ 4. User logs in, Google redirects back to App with an authorization `code`.
98
+ 5. App sends `code` + `code_verifier` to Google backend.
99
+ 6. Google returns `id_token` (OIDC identity) and `access_token` (OAuth permissions).
100
+
101
+ // ❌ HALLUCINATION TRAP: Implicit Flow is deprecated.
102
+ // Never use Implicit Flow (response_type=token) where the token is returned in the URL hash.
103
+ // Always use Authorization Code Flow with PKCE, even for Single Page Apps (SPAs).
104
+ ```
105
+
106
+ ---
107
+
108
+ ## Multi-Factor Authentication (MFA)
109
+
110
+ - **SMS**: Deprecated by NIST due to SIM swapping vulnerabilities. (Better than nothing, but avoid as primary MFA).
111
+ - **TOTP (Authenticator Apps)**: Standard implementations use HMAC-SHA1. Keep the secret key heavily encrypted at rest.
112
+ - **WebAuthn / Passkeys**: The modern gold standard. Replaces passwords entirely using hardware enclaves (FaceID, TouchID, YubiKey).
113
+
114
+ ---
115
+
116
+ ## Authorization Models
117
+
118
+ ### RBAC (Role-Based Access Control)
119
+ - Users have Roles (`admin`, `editor`, `viewer`).
120
+ - Roles have Permissions (`create:post`, `delete:user`).
121
+
122
+ ```typescript
123
+ // ✅ Check permissions, not roles directly (more flexible)
124
+ if (!user.permissions.includes("delete:user")) {
125
+ throw new ForbiddenError();
126
+ }
127
+ ```
128
+
129
+ ### ABAC (Attribute-Based Access Control)
130
+ - Access based on context (e.g., "User can edit Document if Document.department == User.department").
131
+
132
+ ```typescript
133
+ // Example Policy
134
+ function canEditPost(user: User, post: Post): boolean {
135
+ if (user.role === "admin") return true;
136
+ if (post.authorId === user.id) return true;
137
+ if (post.status === "draft" && user.department === "content") return true;
138
+ return false;
139
+ }
140
+ ```
141
+
142
+ ---
143
+
144
+ ## 🤖 LLM-Specific Traps (Authentication)
145
+
146
+ 1. **Building Custom Crypto:** AI often tries to invent hashing algorithms or token generators. Never allow custom crypto. Use established standard libraries.
147
+ 2. **`jwt.verify` without `algorithms`:** AI frequently omits the `algorithms: ["HS256"]` array, leaving the app vulnerable to "None" algorithm bypass attacks.
148
+ 3. **Storing JWTs in `localStorage`:** Exposes tokens to XSS. Access tokens go in memory, refresh tokens go in `HttpOnly` cookies.
149
+ 4. **Using MD5/SHA256 for Passwords:** Hash functions must be slow. Enforce Argon2id or bcrypt.
150
+ 5. **Implicit OAuth Flow:** AI trained on legacy code will suggest implicit flow for SPAs. Demand PKCE.
151
+ 6. **Stateless Revocation Illusion:** AI will claim you can revoke a JWT without a database. You cannot. Blacklisting requires state.
152
+ 7. **Authorization after Logic:** Perm checks must happen *before* database mutations, not after.
153
+ 8. **Logging Passwords:** AI error handlers might log the raw `req.body` during a login failure, exposing plaintext passwords to Datadog/CloudWatch.
154
+ 9. **Missing Rate Limiting:** Login endpoints without aggressive rate limiting invite brute force attacks.
155
+ 10. **Constant Time String Comparison:** Using `a === b` for token/password comparison allows timing attacks. Always use `crypto.timingSafeEqual`.
156
+
157
+ ---
158
+
159
+ ## 🏛️ Tribunal Integration
160
+
161
+ ### ✅ Pre-Flight Self-Audit
162
+ ```
163
+ ✅ Are passwords hashed using Argon2 or bcrypt?
164
+ ✅ Are session cookies marked HttpOnly, Secure, and SameSite?
165
+ ✅ Does jwt.verify explicitly specify the allowed algorithms?
166
+ ✅ Is token comparison using timingSafeEqual?
167
+ ✅ Are we avoiding localStorage for sensitive tokens?
168
+ ✅ Is the OAuth implementation using Authorization Code + PKCE?
169
+ ✅ Is there aggressive rate limiting on the login/password-reset endpoints?
170
+ ✅ Are auth checks performed BEFORE any business logic/DB operations?
171
+ ✅ Is req.body explicitly filtered in logs to avoid exposing passwords?
172
+ ✅ Did I rely on vetted libraries instead of writing custom auth logic?
173
+ ```
@@ -1,215 +1,154 @@
1
- ---
2
- name: bash-linux
3
- description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
4
- allowed-tools: Read, Write, Edit, Glob, Grep
5
- version: 1.0.0
6
- last-updated: 2026-03-12
7
- applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
- ---
9
-
10
- # Bash & Linux Shell Patterns
11
-
12
- > The terminal is a tool, not a magic box. Understand what a command does before you run it with elevated privileges.
13
-
14
- ---
15
-
16
- ## Ground Rules
17
-
18
- 1. **Never suggest `sudo` without explaining why it's necessary**
19
- 2. **Test destructive commands with `--dry-run` or `echo` first**
20
- 3. **`rm -rf` on a variable that might be empty = disaster** — guard it
21
- 4. **Pipe chains fail silently unless you use `set -euo pipefail`**
22
-
23
- ---
24
-
25
- ## Essential Patterns
26
-
27
- ### Safe Script Header
28
-
29
- Every shell script should start with:
30
-
31
- ```bash
32
- #!/usr/bin/env bash
33
- set -euo pipefail
34
- IFS=$'\n\t'
35
- ```
36
-
37
- - `set -e` — exit on any error
38
- - `set -u` exit on undefined variable
39
- - `set -o pipefail` — fail if any command in a pipe fails
40
- - `IFS` safer word splitting
41
-
42
- ### Variable Safety
43
-
44
- ```bash
45
- # Unsafe if DIR is empty, this deletes /
46
- rm -rf "$DIR/"
47
-
48
- # ✅ Safe — guard before destructive operation
49
- if [[ -z "$DIR" ]]; then
50
- echo "Error: DIR is not set" >&2
51
- exit 1
52
- fi
53
- rm -rf "$DIR/"
54
- ```
55
-
56
- ### Testing Conditions
57
-
58
- ```bash
59
- # File/directory checks
60
- [[ -f "$file" ]] # exists and is a regular file
61
- [[ -d "$dir" ]] # exists and is a directory
62
- [[ -z "$var" ]] # string is empty
63
- [[ -n "$var" ]] # string is not empty
64
-
65
- # Numeric comparison (use (( )) for integers)
66
- (( count > 0 ))
67
- (( $? == 0 ))
68
- ```
69
-
70
- ### Error Handling
71
-
72
- ```bash
73
- # Trap errors and print context
74
- trap 'echo "Error on line $LINENO" >&2' ERR
75
-
76
- # Run a command and handle failure explicitly
77
- if ! command_that_might_fail; then
78
- echo "Command failed aborting" >&2
79
- exit 1
80
- fi
81
-
82
- # Or with ||
83
- do_something || { echo "Failed"; exit 1; }
84
- ```
85
-
86
- ---
87
-
88
- ## Common Operations
89
-
90
- ### Find Files
91
-
92
- ```bash
93
- # Files modified in last 24h
94
- find . -mtime -1 -type f
95
-
96
- # Files matching pattern, excluding directories
97
- find . -name "*.log" -not -path "*/node_modules/*"
98
-
99
- # Search contents
100
- grep -r "pattern" . --include="*.ts" -l # list files
101
- grep -r "pattern" . --include="*.ts" -n # with line numbers
102
- ```
103
-
104
- ### Process & Resource Management
105
-
106
- ```bash
107
- # Find process using a port
108
- lsof -i :3000
109
- ss -tlnp | grep :3000 # on Linux
110
-
111
- # Kill by port
112
- kill -9 $(lsof -ti :3000)
113
-
114
- # Background + disown
115
- long_running_command &
116
- disown $!
117
- ```
118
-
119
- ### Text Processing Pipeline
120
-
121
- ```bash
122
- # Count occurrences
123
- cat file.log | grep "ERROR" | wc -l
124
-
125
- # Extract column from CSV
126
- cut -d',' -f2 data.csv
127
-
128
- # Unique sorted values
129
- sort file.txt | uniq -c | sort -rn
130
- ```
131
-
132
- ---
133
-
134
- ## Script Structure Template
135
-
136
- ```bash
137
- #!/usr/bin/env bash
138
- set -euo pipefail
139
-
140
- # ── Config ──────────────────────────────
141
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
142
- TARGET="${1:-}"
143
-
144
- # ── Validate ────────────────────────────
145
- if [[ -z "$TARGET" ]]; then
146
- echo "Usage: $(basename "$0") <target>" >&2
147
- exit 1
148
- fi
149
-
150
- # ── Main ────────────────────────────────
151
- main() {
152
- echo "Processing: $TARGET"
153
- # ... logic here
154
- }
155
-
156
- main "$@"
157
- ```
158
-
159
- ---
160
-
161
- ## Platform Notes
162
-
163
- - `date` syntax differs between macOS BSD and Linux GNU — use `python3 -c "..."` for portable date math
164
- - `sed -i` needs an empty string argument on macOS: `sed -i '' 's/old/new/' file`
165
- - Prefer `#!/usr/bin/env bash` over `#!/bin/bash` for portability
166
-
167
- ---
168
-
169
- ## Output Format
170
-
171
- When this skill produces or reviews code, structure your output as follows:
172
-
173
- ```
174
- ━━━ Bash Linux Report ━━━━━━━━━━━━━━━━━━━━━━━━
175
- Skill: Bash Linux
176
- Language: [detected language / framework]
177
- Scope: [N files · N functions]
178
- ─────────────────────────────────────────────────
179
- ✅ Passed: [checks that passed, or "All clean"]
180
- ⚠️ Warnings: [non-blocking issues, or "None"]
181
- ❌ Blocked: [blocking issues requiring fix, or "None"]
182
- ─────────────────────────────────────────────────
183
- VBC status: PENDING → VERIFIED
184
- Evidence: [test output / lint pass / compile success]
185
- ```
186
-
187
- **VBC (Verification-Before-Completion) is mandatory.**
188
- Do not mark status as VERIFIED until concrete terminal evidence is provided.
189
-
190
-
191
- ---
192
-
193
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
194
-
195
- **Slash command: `/audit` or `/review`**
196
- **Active reviewers: `logic` · `security` · `devops`**
197
-
198
- ### ❌ Forbidden AI Tropes in Bash/Linux
199
-
200
- 1. **Unjustified `sudo`** — hallucinating `sudo` for scripts or directories owned by the local user.
201
- 2. **Unquoted variables** — using `$CMD` instead of `"$CMD"`, leading to word splitting and globbing disasters.
202
- 3. **Unguarded `rm -rf`** — deleting variables without checking if they are empty first (`[[ -z "$DIR" ]]`).
203
- 4. **Pipe chains without `pipefail`** — writing `cat file | grep X | cut -d` without `set -o pipefail`, hiding failures.
204
- 5. **Parsing `ls`** — scraping `ls` output instead of using `find` or globbing.
205
-
206
- ### ✅ Pre-Flight Self-Audit
207
-
208
- Review these questions before generating Bash scripts or commands:
209
- ```
210
- ✅ Does the script start with `set -euo pipefail`?
211
- ✅ Are all variable expansions wrapped in double quotes to prevent splitting?
212
- ✅ Did I verify that `sudo` is absolutely required for this operation?
213
- ✅ Are destructive operations (`rm`, `mv`) properly guarded with condition checks?
214
- ✅ Did I use the most robust tool (e.g., `find` instead of `ls`) for the job?
215
- ```
1
+ ---
2
+ name: bash-linux
3
+ description: Bash/Linux terminal mastery. Shell scripting, piping, stream redirection, process substitution, strict mode (set -euo pipefail), AWK, ripgrep parsing, and robust error handling. Use when writing CI scripts, debugging POSIX environments, or manipulating text pipelines.
4
+ allowed-tools: Read, Write, Edit, Glob, Grep
5
+ version: 2.0.0
6
+ last-updated: 2026-04-02
7
+ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
8
+ ---
9
+
10
+ # Bash & Linux Shell Scripting Mastery
11
+
12
+ > Bash is powerful but fragile by default.
13
+ > An unchecked failure in a shell script will happily cascade into deleting production.
14
+
15
+ ---
16
+
17
+ ## 1. Bash Strict Mode (Mandatory)
18
+
19
+ Always start every single bash script with strict compilation flags.
20
+
21
+ ```bash
22
+ #!/usr/bin/env bash
23
+
24
+ # ❌ BAD: Default bash execution
25
+ # - Undefined variables evaluate to empty strings
26
+ # - Failed commands are ignored, execution continues blindly
27
+ # - Piped failures are hidden (only last command exit code matters)
28
+
29
+ # GOOD: Strict Mode
30
+ set -euo pipefail
31
+ IFS=$'\n\t'
32
+
33
+ # -e: Exit immediately if a command exits with a non-zero status.
34
+ # -u: Treat unset variables as an error and exit immediately.
35
+ # -o pipefail: Pipeline returns the status of the rightmost command to exit with a non-zero status.
36
+ # IFS: Only split on newlines and tabs, not spaces (prevents terrifying globbing/array bugs).
37
+
38
+ # Example: Catching potential disasters
39
+ unset MY_VAR
40
+ rm -rf "/some/path/${MY_VAR}" # With 'set -u', this throws an error instead of running 'rm -rf /some/path/'
41
+ ```
42
+
43
+ ---
44
+
45
+ ## 2. Advanced Stream Manipulation
46
+
47
+ Piping allows passing stdout from one program into stdin of another.
48
+
49
+ ```bash
50
+ # ❌ VULNERABLE: Useless Use of Cat (UUOC)
51
+ cat file.txt | grep "error"
52
+
53
+ # EFFICIENT: Direct parsing
54
+ grep "error" file.txt
55
+ # Or modern ripgrep for huge repositories:
56
+ rg "error" file.txt
57
+
58
+ # Process Substitution: Treating tool outputs as if they were files
59
+ # Compare two remote JSON responses without writing to disk
60
+ diff <(curl -s api.com/v1) <(curl -s api.com/v2)
61
+
62
+ # Redirection Mastery
63
+ # 1> stdout, 2> stderr
64
+ command > output.txt 2> error.txt # Split streams
65
+ command > all.txt 2>&1 # Combine streams (POSIX)
66
+ command &> all.txt # Combine streams (Bash shortcut)
67
+ command >/dev/null 2>&1 # Subdue all output cleanly
68
+ ```
69
+
70
+ ---
71
+
72
+ ## 3. AWK and Stream Formatting
73
+
74
+ AWK is a complete programming language designed for text processing.
75
+
76
+ ```bash
77
+ # Example: We have a ps aux output and we want the PIDs (column 2) of all Node processes
78
+ ps aux | grep node | awk '{print $2}'
79
+
80
+ # Example: Summing numbers in column 3 from a CSV
81
+ cat data.csv | awk -F ',' '{sum+=$3} END {print sum}'
82
+
83
+ # Extracting specific lines (e.g. line 5 to 10)
84
+ sed -n '5,10p' file.txt
85
+ ```
86
+
87
+ ---
88
+
89
+ ## 4. Modern CLI Alternatives (The 2026 Stack)
90
+
91
+ Standard POSIX tools are reliable but slow. Use modern Rust-based alternatives when available in CI/CD.
92
+
93
+ | Task | Legacy POSIX | Modern Alternative | Why? |
94
+ |:---|:---|:---|:---|
95
+ | Find files | `find . -name "*.ts"` | `fd -e ts` | Context-aware, respects `.gitignore`, 10x faster. |
96
+ | Search text | `grep -r "auth"` | `rg "auth"` | Ripgrep uses multi-threading and SIMD instructions. |
97
+ | Inspect JSON | `grep / awk` | `jq '.users[].id'` | `jq` explicitly parses and filters valid JSON arrays/objects. |
98
+ | Process monitoring | `top` | `htop` / `btm` | Interactive metrics. |
99
+ | Check curl | `curl -i` | `httpie` / `xh` | Colorized, structured JSON networking. |
100
+
101
+ ---
102
+
103
+ ## 5. File System Traps & Quoting
104
+
105
+ If a filename contains a space and you didn't quote your variable, your script will crash or delete the wrong files.
106
+
107
+ ```bash
108
+ # Let FILE="my backup.tar"
109
+
110
+ # ❌ BAD: Evaluates as `rm my` AND `backup.tar` -> Two different files!
111
+ rm $FILE
112
+
113
+ # ✅ GOOD: Always quote string variables
114
+ rm "$FILE"
115
+
116
+ # ✅ GOOD: Array iteration (Using quotes specifically formatted with @)
117
+ FILES=("file 1.txt" "file 2.txt")
118
+ for file in "${FILES[@]}"; do
119
+ echo "Processing: $file"
120
+ done
121
+ ```
122
+
123
+ ---
124
+
125
+ ## 🤖 LLM-Specific Traps (Bash/Linux)
126
+
127
+ 1. **Forgetting Strict Mode:** AI commonly forgets `set -euo pipefail`, creating fragile, dangerous scripts that cascade failures.
128
+ 2. **Missing Quotes:** AI writes `echo $USER_INPUT` instead of `echo "$USER_INPUT"`, leading to glob-splitting exploits and file deletion errors.
129
+ 3. **Useless Cat:** `cat file.txt | awk ...` instead of `awk ... file.txt`.
130
+ 4. **Regex in Grep:** AI attempts complex regex in standard `grep` which often fails due to dialect differences (BSD vs GNU). Use `grep -E` (Extended) or modern `rg`.
131
+ 5. **Awkward JSON parsing:** AI writing labyrinthine `sed`/`grep` chains to extract a field from JSON. Always use `jq`.
132
+ 6. **Hardcoded Paths:** Using `/home/user/script` instead of dynamic resolutions like `$(dirname "$0")` to find files relative to the script location.
133
+ 7. **Dangerous Globbing:** `rm *.txt` will fail if there are too many files ("Arg list too long"). AI fails to use `find . -name "*.txt" -delete` for large ops.
134
+ 8. **Silent Failures in Pipes:** AI assumes `command1 | command2` throws an error if `command1` fails. It doesn't, unless `set -o pipefail` is active.
135
+ 9. **Environment Pollution:** Executing exports globally (`export VAR=1`) inside utility scripts. Changes pollute the user's active shell.
136
+ 10. **Blind Sudo Execution:** Suggesting users pipe curled scripts directly into `sudo bash` (`curl api.com/setup | sudo bash`). Always inspect scripts first.
137
+
138
+ ---
139
+
140
+ ## 🏛️ Tribunal Integration
141
+
142
+ ### ✅ Pre-Flight Self-Audit
143
+ ```
144
+ Does the script begin with `set -euo pipefail`?
145
+ Are all variable expansions wrapped in double quotes `"$VAR"`?
146
+ Am I using `jq` for handling JSON responses rather than `sed`/`grep`?
147
+ Is the script executing locally relative paths using `$(dirname "$0")`?
148
+ ✅ Have I avoided "Useless Use of Cat" (`cat X | Y`)?
149
+ ✅ Did I properly manage stderr and stdout streams (`2>&1`)?
150
+ Have I avoided executing destructive wildcard globs (`rm -rf *`)?
151
+ Is my text searching leveraging `-E` for extended regex if I use lookaheads?
152
+ Did I use array expansion strictly as `"${ARRAY[@]}"`?
153
+ If suggesting installation, did I avoid `curl | sudo bash`?
154
+ ```