tribunal-kit 2.4.5 → 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 (144) 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 +160 -0
  42. package/.agent/skills/api-patterns/SKILL.md +289 -257
  43. package/.agent/skills/api-security-auditor/SKILL.md +177 -0
  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 -58
  47. package/.agent/skills/architecture/SKILL.md +331 -200
  48. package/.agent/skills/authentication-best-practices/SKILL.md +173 -0
  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 +174 -0
  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 +134 -0
  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 +162 -0
  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/readme-builder/SKILL.md +42 -0
  84. package/.agent/skills/realtime-patterns/SKILL.md +304 -296
  85. package/.agent/skills/rust-pro/SKILL.md +701 -240
  86. package/.agent/skills/seo-fundamentals/SKILL.md +154 -181
  87. package/.agent/skills/server-management/SKILL.md +190 -212
  88. package/.agent/skills/shadcn-ui-expert/SKILL.md +206 -0
  89. package/.agent/skills/skill-creator/SKILL.md +68 -0
  90. package/.agent/skills/sql-pro/SKILL.md +633 -104
  91. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +78 -0
  92. package/.agent/skills/swiftui-expert/SKILL.md +176 -0
  93. package/.agent/skills/systematic-debugging/SKILL.md +118 -186
  94. package/.agent/skills/tailwind-patterns/SKILL.md +576 -232
  95. package/.agent/skills/tdd-workflow/SKILL.md +137 -209
  96. package/.agent/skills/testing-patterns/SKILL.md +573 -205
  97. package/.agent/skills/vue-expert/SKILL.md +964 -119
  98. package/.agent/skills/vulnerability-scanner/SKILL.md +269 -316
  99. package/.agent/skills/web-accessibility-auditor/SKILL.md +193 -0
  100. package/.agent/skills/webapp-testing/SKILL.md +145 -236
  101. package/.agent/workflows/api-tester.md +151 -279
  102. package/.agent/workflows/audit.md +138 -168
  103. package/.agent/workflows/brainstorm.md +110 -146
  104. package/.agent/workflows/changelog.md +112 -144
  105. package/.agent/workflows/create.md +124 -139
  106. package/.agent/workflows/debug.md +189 -196
  107. package/.agent/workflows/deploy.md +189 -153
  108. package/.agent/workflows/enhance.md +151 -139
  109. package/.agent/workflows/fix.md +135 -143
  110. package/.agent/workflows/generate.md +157 -164
  111. package/.agent/workflows/migrate.md +160 -163
  112. package/.agent/workflows/orchestrate.md +168 -151
  113. package/.agent/workflows/performance-benchmarker.md +123 -305
  114. package/.agent/workflows/plan.md +173 -151
  115. package/.agent/workflows/preview.md +80 -137
  116. package/.agent/workflows/refactor.md +183 -153
  117. package/.agent/workflows/review-ai.md +129 -140
  118. package/.agent/workflows/review.md +116 -155
  119. package/.agent/workflows/session.md +94 -154
  120. package/.agent/workflows/status.md +79 -125
  121. package/.agent/workflows/strengthen-skills.md +139 -99
  122. package/.agent/workflows/swarm.md +179 -194
  123. package/.agent/workflows/test.md +211 -166
  124. package/.agent/workflows/tribunal-backend.md +113 -111
  125. package/.agent/workflows/tribunal-database.md +115 -132
  126. package/.agent/workflows/tribunal-frontend.md +118 -115
  127. package/.agent/workflows/tribunal-full.md +133 -136
  128. package/.agent/workflows/tribunal-mobile.md +119 -123
  129. package/.agent/workflows/tribunal-performance.md +133 -152
  130. package/.agent/workflows/ui-ux-pro-max.md +143 -171
  131. package/README.md +11 -15
  132. package/package.json +1 -1
  133. package/.agent/skills/dotnet-core-expert/SKILL.md +0 -103
  134. package/.agent/skills/game-development/2d-games/SKILL.md +0 -119
  135. package/.agent/skills/game-development/3d-games/SKILL.md +0 -135
  136. package/.agent/skills/game-development/SKILL.md +0 -236
  137. package/.agent/skills/game-development/game-art/SKILL.md +0 -185
  138. package/.agent/skills/game-development/game-audio/SKILL.md +0 -190
  139. package/.agent/skills/game-development/game-design/SKILL.md +0 -129
  140. package/.agent/skills/game-development/mobile-games/SKILL.md +0 -108
  141. package/.agent/skills/game-development/multiplayer/SKILL.md +0 -132
  142. package/.agent/skills/game-development/pc-games/SKILL.md +0 -144
  143. package/.agent/skills/game-development/vr-ar/SKILL.md +0 -123
  144. package/.agent/skills/game-development/web-games/SKILL.md +0 -150
@@ -1,188 +1,118 @@
1
- ---
2
- name: plan-writing
3
- description: Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work.
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
- # Task Planning Standards
11
-
12
- > A plan is not a promise. It is a map.
13
- > Maps get updated when the terrain doesn't match them.
14
-
15
- ---
16
-
17
- ## When to Write a Plan
18
-
19
- Write a plan before implementation when:
20
- - The task touches more than 2 files in non-trivial ways
21
- - The task has dependencies (thing B can't start until thing A is done)
22
- - The task involves a risky operation (migration, data transformation, breaking change)
23
- - The team needs to review the approach before time is spent implementing it
24
-
25
- Skip the formal plan for: single-function fixes, typo corrections, config tweaks.
26
-
27
- ---
28
-
29
- ## Plan Structure
30
-
31
- ```markdown
32
- # Plan: [Feature or Task Name]
33
-
34
- ## Goal
35
- One sentence: what outcome does this achieve?
36
-
37
- ## Context
38
- - Why is this being done?
39
- - What problem does it solve or what requirement does it satisfy?
40
- - What exists today that this changes?
41
-
42
- ## Approach
43
- High-level strategy. Enough detail for someone unfamiliar with the code to understand the direction.
44
- Not implementation details those go in the tasks.
45
-
46
- ## Tasks
47
-
48
- ### Phase 1 — [Name] (prerequisite for Phase 2)
49
- - [ ] Task 1.1: Description
50
- - [ ] Task 1.2: Description (depends on 1.1)
51
-
52
- ### Phase 2 — [Name] (can run after Phase 1 is complete)
53
- - [ ] Task 2.1: Description
54
- - [ ] Task 2.2: Description
55
-
56
- ## Verification
57
- How will we know this is done and working?
58
- - [ ] Specific behavior that can be tested
59
- - [ ] Metric or log line that confirms success
60
- - [ ] Edge case that must not regress
61
-
62
- ## Risks and Open Questions
63
- - [Risk]: What might go wrong, and what's the mitigation?
64
- - [Open]: What decision hasn't been made yet that could change this plan?
65
-
66
- ## Files That Will Change
67
- - `path/to/file.ts` — what changes
68
- - `path/to/schema.sql` what changes
69
- ```
70
-
71
- ---
72
-
73
- ## Dependency Notation
74
-
75
- When tasks have a strict order, mark it:
76
-
77
- ```
78
- Task A (no dependencies, do first)
79
- Task B (requires A complete)
80
- Task C — (can run parallel with B)
81
- Task D — (requires B and C complete)
82
- ```
83
-
84
- This prevents teams from working on D while B is still broken.
85
-
86
- ---
87
-
88
- ## Task Granularity
89
-
90
- Each task should be:
91
- - Completable in one session by one person
92
- - Independently reviewable (a PR could represent one task)
93
- - Testable: there is a concrete way to know if it's done
94
-
95
- **Too vague:** "Implement the auth system"
96
- **Right size:** "Add `POST /api/auth/login` endpoint with JWT issuance and Zod validation"
97
-
98
- ---
99
-
100
- ## Updating the Plan
101
-
102
- Plans are living documents:
103
-
104
- - Mark tasks `[x]` when complete, not when started
105
- - Add `[!]` to blocked tasks with a note on what is blocking
106
- - When an assumption proves wrong, update the approach section — don't silently deviate from the plan
107
-
108
- ---
109
-
110
- ## Verification Criteria Rules
111
-
112
- Verification criteria are not optional. For each task:
113
-
114
- - At least one must be **observable** (you can see it, not just believe it)
115
- - At least one must cover a **failure mode** (what should NOT happen)
116
-
117
- ```
118
- ✅ Observable: `POST /api/users` returns 201 with a user ID in the response body
119
- ✅ Failure mode: `POST /api/users` with a duplicate email returns 409, not 500
120
- ```
121
-
122
- ---
123
-
124
- ## 🛑 Verification-Before-Completion (VBC) Protocol
125
-
126
- **CRITICAL:** Every plan must integrate a strict "evidence-based closeout" state machine for its tasks.
127
- - ❌ **Forbidden:** Writing vague verification steps like "Check that it looks right," "Ensure the code makes sense," or "Verify the logic."
128
- - ✅ **Required:** Verification criteria MUST demand **concrete terminal/compiler evidence** (e.g., test success logs, CLI execution outputs, compiler success states, or network trace results). Explicitly state that an agent CANNOT consider the task complete until it captures this hard evidence.
129
-
130
- ---
131
-
132
- ## Output Format
133
-
134
- When this skill produces a recommendation or design decision, structure your output as:
135
-
136
- ```
137
- ━━━ Plan Writing Recommendation ━━━━━━━━━━━━━━━━
138
- Decision: [what was chosen / proposed]
139
- Rationale: [why — one concise line]
140
- Trade-offs: [what is consciously accepted]
141
- Next action: [concrete next step for the user]
142
- ─────────────────────────────────────────────────
143
- Pre-Flight: ✅ All checks passed
144
- or ❌ [blocking item that must be resolved first]
145
- ```
146
-
147
-
148
-
149
- ---
150
-
151
- ## 🤖 LLM-Specific Traps
152
-
153
- AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
154
-
155
- 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
156
- 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
157
- 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
158
- 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
159
- 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
160
-
161
- ---
162
-
163
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
164
-
165
- **Slash command: `/review` or `/tribunal-full`**
166
- **Active reviewers: `logic-reviewer` · `security-auditor`**
167
-
168
- ### ❌ Forbidden AI Tropes
169
-
170
- 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
171
- 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
172
- 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
173
-
174
- ### ✅ Pre-Flight Self-Audit
175
-
176
- Review these questions before confirming output:
177
- ```
178
- ✅ Did I rely ONLY on real, verified tools and methods?
179
- ✅ Is this solution appropriately scoped to the user's constraints?
180
- ✅ Did I handle potential failure modes and edge cases?
181
- ✅ Have I avoided generic boilerplate that doesn't add value?
182
- ```
183
-
184
- ### 🛑 Verification-Before-Completion (VBC) Protocol
185
-
186
- **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
187
- - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
188
- - ✅ **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.
1
+ ---
2
+ name: plan-writing
3
+ description: Technical design and implementation planning mastery. Writing structured execution checklists, dependency mapping, establishing rollback protocols, segmenting monolithic tasks, writing ADRs (Architecture Decision Records), and defining verification criteria. Use when transitioning from ideation to coordinated execution.
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
+ # Plan Writing — Execution Blueprints Mastery
11
+
12
+ > A flawless execution of a terrible plan leads to catastrophic success.
13
+ > Write planes with dependencies explicitly mapped. Treat it like a topological sort.
14
+
15
+ ---
16
+
17
+ ## 1. The Implementation Plan Structure (ADR-Lite)
18
+
19
+ Before altering multiple files or introducing a new system architecture, a rigid `implementation_plan.md` MUST be generated and approved.
20
+
21
+ **Core Sections:**
22
+ 1. **Objective Context:** 2-sentence summary of the requested goal.
23
+ 2. **Architectural Handoff:** (What stack, what libraries, what constraints).
24
+ 3. **Dependency Tree Execution Order:** (Cannot build frontend UI until backend API exists).
25
+ 4. **File Blueprint:** Exact files expected to be touched (`[NEW] src/api/user.ts`, `[MODIFY] src/db/schema.prisma`).
26
+ 5. **Verification Protocol:** Exactly how the agent/human will prove the task is completed successfully.
27
+
28
+ ---
29
+
30
+ ## 2. Segmenting Monolithic Tasks (Chunking)
31
+
32
+ LLMs degrade significantly when asked to process >10 file alterations across multiple directories simultaneously. The Plan Writer must break work into logical, isolated "Waves."
33
+
34
+ ```markdown
35
+ ### Wave 1: Data Layer (The Foundation)
36
+ 1. Add `Subscription` model to Prisma schema.
37
+ 2. Generate migration (`npx prisma migrate dev`).
38
+ 3. Add mock seed data.
39
+
40
+ ### Wave 2: API Layer (The Bridge)
41
+ 1. Build `/api/subscriptions/route.ts` with explicit Zod validation.
42
+ 2. Write Vitest logic enforcing authorization roles.
43
+
44
+ ### Wave 3: UI Layer (The Implementation)
45
+ 1. Build `SubscriptionCard.tsx`.
46
+ 2. Connect to API using MSW mocked tests first.
47
+ 3. Integrate into main dashboard.
48
+ ```
49
+
50
+ *Crucial:* Each wave MUST be executable and testable independently. Do not begin Wave 2 until Wave 1 passes Verification Protocols.
51
+
52
+ ---
53
+
54
+ ## 3. Rollback & Contingency Planning
55
+
56
+ No plan survives first contact with the compiler. The plan must implicitly include safe-fail procedures.
57
+
58
+ - **Non-Destructive Defaults:** If a schema migration fails, how do we revert? (e.g., explicit instruction to backup SQLite DB locally before operations).
59
+ - **Graceful Feature Toggles:** Is the new feature walled behind an environment variable (`ENABLE_NEW_DASHBOARD=true`) so it can be disabled instantly if it crashes in production?
60
+
61
+ ---
62
+
63
+ ## 4. The `task.md` Execution Ledger
64
+
65
+ Unlike the high-level `implementation_plan.md`, the `task.md` serves as the live, mutating execution state.
66
+
67
+ ```markdown
68
+ # Current Objective: Upgrade Authentication
69
+
70
+ ## Pre-Flight
71
+ - [x] Dump existing environment variables locally
72
+ - [x] Verify current tests pass (Baseline health)
73
+
74
+ ## Wave 1 (OAuth Scaffold)
75
+ - [/] Install auth.js dependencies
76
+ - [ ] Connect Google Provider inside `[...nextauth].ts`
77
+
78
+ ## Wave 2 (Database Mappings)
79
+ - [ ] Update Users table to handle polymorphic OAuth links
80
+ ```
81
+
82
+ *Rules:*
83
+ - `[ ]` = Unstarted
84
+ - `[/]` = In Progress (Current Focus)
85
+ - `[x]` = Verified Complete
86
+
87
+ ---
88
+
89
+ ## 🤖 LLM-Specific Traps (Plan Writing)
90
+
91
+ 1. **Topological Chaos:** Recommending the creation of a frontend React component fetching an API endpoint that has not yet been scheduled for creation, resulting in immediate compilation/linting crashes.
92
+ 2. **Missing File Paths:** Writing "Update the configuration file" instead of explicitly declaring `[MODIFY] .github/workflows/deploy.yml`. Vague boundaries invite shotgun surgery.
93
+ 3. **Execution Masking:** The AI receives the instruction to "Write a plan," but decides to also write 450 lines of execution code spanning 6 files simultaneously in the same reply. Demarcate Planning from Execution permanently.
94
+ 4. **Over-Engineering the MVP:** Recommending a 4-wave, 12-step Kubernetes microservice deployment schedule for a localized "Add a 'Contact Us' form" user request.
95
+ 5. **No Verification Baseline:** Failing to establish a "Does the code currently work?" baseline constraint before beginning the sequence of alterations.
96
+ 6. **Task Blobbing:** Creating a massive, single 25-step list without breaking it up into isolated, independently testable Waves/Phases. If the list is monolithic, the failure debugging will be chaotic.
97
+ 7. **Silent Dependencies:** Failing to explicitly list new NPM packages or system libraries required by the plan (e.g., executing Prisma logic without adding a `npm install @prisma/client` step).
98
+ 8. **Assumption of Success:** Failing to establish Rollback protocols (e.g., `git reset --hard`) when planning risky, highly destructive file alterations.
99
+ 9. **Ignoring the Environment:** Planning major API changes without ensuring the required environment variables (`STRIPE_API_KEY`) are documented for addition.
100
+ 10. **Refusal to Update Ledger:** Operating as an autonomous executor but failing to edit the `task.md` tracking ledger synchronously, destroying the system's memory continuity upon suspension.
101
+
102
+ ---
103
+
104
+ ## 🏛️ Tribunal Integration
105
+
106
+ ### Pre-Flight Self-Audit
107
+ ```
108
+ ✅ Are execution sequences strictly ordered by Topological Dependencies (DB → API → UI)?
109
+ ✅ Are monolith tasks deliberately chunked into isolated, independently testable Waves?
110
+ Is the `task.md` execution ledger cleanly parameterized with exact file paths `[NEW], [MODIFY]`?
111
+ ✅ Have I explicitly separated the Planning Phase response from raw Code Generation?
112
+ Are verification protocols explicitly tied to terminal logs, test results, or manual checks?
113
+ ✅ Are required NPM package installations/dependency injections explicitly mapped in Wave 1?
114
+ Is there a defined Rollback/Snapshot strategy to recover from catastrophic compilation failure?
115
+ Are environmental secrets (.env variables) outlined as requirements before execution?
116
+ ✅ Has the complexity of the plan been correctly scaled to the simplicity of the user's objective?
117
+ ✅ Does the plan establish a baseline system health check before executing destructive mutations?
118
+ ```
@@ -1,135 +1,123 @@
1
- ---
2
- name: platform-engineer
3
- description: Senior platform engineer with deep expertise in building internal developer platforms, self-service infrastructure, and developer portals. Reduces cognitive load and accelerates software delivery.
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
- # Platform Engineer - Claude Code Sub-Agent
11
-
12
- You are a senior platform engineer with deep expertise in building internal developer platforms, self-service infrastructure, and developer portals. Your focus spans platform architecture, GitOps workflows, service catalogs, and developer experience optimization with emphasis on reducing cognitive load and accelerating software delivery.
13
-
14
- ## Configuration & Context Assessment
15
- When invoked:
16
- 1. Query context manager for existing platform capabilities and developer needs
17
- 2. Review current self-service offerings, golden paths, and adoption metrics
18
- 3. Analyze developer pain points, workflow bottlenecks, and platform gaps
19
- 4. Implement solutions maximizing developer productivity and platform adoption
20
-
21
- ---
22
-
23
- ## The Platform Excellence Checklist
24
- - Self-service rate exceeding 90%
25
- - Provisioning time under 5 minutes
26
- - Platform uptime 99.9%
27
- - API response time < 200ms
28
- - Documentation coverage 100%
29
- - Developer onboarding < 1 day
30
- - Golden paths established
31
- - Feedback loops active
32
-
33
- ---
34
-
35
- ## Core Architecture Decision Framework
36
-
37
- ### Platform Operations & GitOps Implementation
38
- * **Platform Architecture:** Multi-tenant platform design, Resource isolation strategies, Cost allocation tracking, Compliance automation.
39
- * **GitOps:** Repository structure design, PR automation workflows, Secret management, Multi-cluster synchronization.
40
- * **Infrastructure Abstraction:** Crossplane compositions, Terraform modules, Operator patterns, State reconciliation.
41
-
42
- ### Developer Experience & Self-Service
43
- * **Developer Experience:** Self-service portal design, Onboarding automation, IDE integration plugins, CLI tool development.
44
- * **Self-Service Capabilities:** Environment provisioning, Database creation, Service deployment, Access management.
45
- * **Service Catalog:** Backstage implementation, Software templates, Component registry, Tech radar maintenance.
46
-
47
- ### Golden Paths & Platform APIs
48
- * **Golden Paths:** Service scaffolding, CI/CD pipeline templates, Security scanning integration, Best practices enforcement.
49
- * **Platform APIs:** RESTful API design, Event streaming setup, Rate limiting implementation, SDK generation.
50
- * **Developer Enablement:** Documentation portals, Success tracking, Workshop delivery.
51
-
52
- ---
53
-
54
- ## Output Format
55
-
56
- When this skill produces a recommendation or design decision, structure your output as:
57
-
58
- ```
59
- ━━━ Platform Engineer Recommendation ━━━━━━━━━━━━━━━━
60
- Decision: [what was chosen / proposed]
61
- Rationale: [why — one concise line]
62
- Trade-offs: [what is consciously accepted]
63
- Next action: [concrete next step for the user]
64
- ─────────────────────────────────────────────────
65
- Pre-Flight: ✅ All checks passed
66
- or ❌ [blocking item that must be resolved first]
67
- ```
68
-
69
-
70
- ---
71
-
72
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
73
-
74
- **Slash command: `/tribunal-backend`**
75
- **Active reviewers: `logic` · `security`**
76
-
77
- ### ❌ Forbidden AI Tropes in Platform Engineering
78
- 1. **Platform Monoliths** never design internal platforms as tightly coupled monoliths; mandate decoupled, API-first self-service modules.
79
- 2. **Missing Golden Path Flexibility** — do not generate developer templates that lock teams into specific versions without an override mechanism (Golden Path vs. Golden Cage).
80
- 3. **Ticket-Ops Paradigms** — do not design processes that require Jira/ITSM ticket approvals for routine environment provisioning; push towards self-service automation.
81
- 4. **Ignoring Platform Docs** — never omit READMEs, interactive API docs, or Backstage catalog entries for newly created internal services.
82
- 5. **Over-Abstraction Without Need** — avoid wrapping standard tools (like native Kubernetes YAML or pure Terraform) in complex proprietary CLI abstractions unless developer cognitive load dictates it.
83
-
84
- ### ✅ Pre-Flight Self-Audit
85
-
86
- Review these questions before generating platform engineering architecture or IDPs:
87
- ```text
88
- Did I design the workflow as a true self-service process that eliminates manual hand-offs?
89
- ✅ Does the GitOps flow include automated checks for secrets and compliance before syncing?
90
- Are the Golden Path templates extensible and versioned?
91
- ✅ Have I properly isolated resources in the multi-tenant architecture proposal?
92
- ✅ Are there built-in mechanisms for cost-visibility and telemetry tracking on generated developer environments?
93
- ```
94
-
95
-
96
- ---
97
-
98
- ## 🤖 LLM-Specific Traps
99
-
100
- AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
101
-
102
- 1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
103
- 2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
104
- 3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
105
- 4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
106
- 5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
107
-
108
- ---
109
-
110
- ## 🏛️ Tribunal Integration (Anti-Hallucination)
111
-
112
- **Slash command: `/review` or `/tribunal-full`**
113
- **Active reviewers: `logic-reviewer` · `security-auditor`**
114
-
115
- ### Forbidden AI Tropes
116
-
117
- 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
118
- 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
119
- 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
120
-
121
- ### Pre-Flight Self-Audit
122
-
123
- Review these questions before confirming output:
124
- ```
125
- ✅ Did I rely ONLY on real, verified tools and methods?
126
- ✅ Is this solution appropriately scoped to the user's constraints?
127
- ✅ Did I handle potential failure modes and edge cases?
128
- ✅ Have I avoided generic boilerplate that doesn't add value?
129
- ```
130
-
131
- ### 🛑 Verification-Before-Completion (VBC) Protocol
132
-
133
- **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
134
- - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
135
- - ✅ **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.
1
+ ---
2
+ name: platform-engineer
3
+ description: Platform Engineering and Internal Developer Portal (IDP) mastery. Golden Paths, self-service infrastructure, cognitive load reduction, GitOps synchronization (ArgoCD/Flux), Terraform/OpenTofu architecture, and standardized service scaffolding. Use when designing system-wide development workflows or standardizing infrastructure processes.
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
+ # Platform Engineering Developer Experience Mastery
11
+
12
+ > DevOps is a culture. Platform Engineering is a product.
13
+ > The product's customer is the internal software engineer. The goal is removing friction and standardizing security.
14
+
15
+ ---
16
+
17
+ ## 1. The "Golden Path" Architecture
18
+
19
+ A developer should not have to write a Dockerfile, configure a CI pipeline, request AWS permissions, or setup Prometheus dashboards to launch a new microservice.
20
+
21
+ The Platform Engineer establishes **Golden Paths**: pre-approved, automated templates that bundle security and infrastructure out-of-the-box.
22
+
23
+ **Example: Local Service Scaffolding (Backstage / Cookiecutter)**
24
+ Instead of cloning complex repos, the developer runs:
25
+ `platform create my-service --stack node-express --db postgres`
26
+
27
+ This command:
28
+ 1. Generates the standard Node/Express repo.
29
+ 2. Applies the unified corporate CI/CD GitHub Action.
30
+ 3. Configures default Datadog/OpenTelemetry observability metrics.
31
+ 4. Generates a Terraform blueprint to provision the RDS Postgres instance.
32
+
33
+ ---
34
+
35
+ ## 2. GitOps (Declarative State Synchronization)
36
+
37
+ Platform Engineers do not log into AWS consoles to click buttons. They do not run `kubectl apply` from their laptops.
38
+
39
+ They push code to Git. A continuous reconciliation loop (e.g., ArgoCD) syncs the live infrastructure to match the Git repository mathematically.
40
+
41
+ ```yaml
42
+ # GitOps standard architecture (ArgoCD)
43
+ apiVersion: argoproj.io/v1alpha1
44
+ kind: Application
45
+ metadata:
46
+ name: auth-service
47
+ namespace: argocd
48
+ spec:
49
+ project: default
50
+ source:
51
+ repoURL: 'https://github.com/mycorp/infrastructure-ops'
52
+ path: k8s/auth-service
53
+ targetRevision: HEAD # Automatically deploys any merge to main
54
+ destination:
55
+ server: 'https://kubernetes.default.svc'
56
+ namespace: auth-prod
57
+ syncPolicy:
58
+ automated:
59
+ prune: true
60
+ selfHeal: true # If manual changes occur on cluster, force-reverts back to Git state
61
+ ```
62
+
63
+ ---
64
+
65
+ ## 3. Infrastructure as Code (IaC) Modules
66
+
67
+ Platform Engineers build reusable Terraform/Tofu modules, hiding extreme complexity from product developers.
68
+
69
+ ```hcl
70
+ # The Platform Engineer writes the complex module (e.g., VPC, Subnets, IAM, KMS Encryptions)
71
+ # The Product Developer simply consumes the module cleanly:
72
+
73
+ module "product_database" {
74
+ source = "github.com/mycorp/tf-modules/secure-rds"
75
+ version = "v1.2.0"
76
+
77
+ app_name = "checkout-service"
78
+ capacity = "medium" # Abstracts complex instance sizing
79
+ needs_replica = true # Abstracts failover architecture
80
+ }
81
+ ```
82
+
83
+ ---
84
+
85
+ ## 4. Reducing Cognitive Load
86
+
87
+ DevOps asked product developers to learn Kubernetes, Helm, Terraform, CI/CD, and AWS IAM. The load was too high.
88
+ Platform Engineering hides the Kubernetes complexity behind a portal (e.g., Backstage) or a declarative wrapper (e.g., Score).
89
+
90
+ Ensure your infrastructure proposals abstract away the YAML mechanics. Give the developer a simple SLA: *"Push to the `main` branch, and the platform guarantees deployment, logs, and metrics within 3 minutes."*
91
+
92
+ ---
93
+
94
+ ## 🤖 LLM-Specific Traps (Platform Engineering)
95
+
96
+ 1. **The Scripting Fallacy:** Handing product engineers a 4,000-line bash script to deploy their app instead of building a declarative CI/CD Golden Path framework.
97
+ 2. **Console Operations:** Recommending manual AWS/GCP console click permutations to configure a database. The entire infrastructure structure must be defined via formal IaC representations (Terraform/Pulumi).
98
+ 3. **Leaking Ops Complexity:** Generating a Helm Chart for an application developer that exposes 300 variables regarding node-affinity and tolerations. Hide ops mechanics; expose only application variables (CPU target, replica count).
99
+ 4. **Push-Based CD Risks:** Generating CI pipelines that use `kubectl apply` directly from GitHub Actions (Push-based) rather than deploying a Pull-based GitOps operator like ArgoCD, exposing production cluster credentials to the CI runner.
100
+ 5. **Non-Standardized Monitoring:** Failing to inject unified OpenTelemetry/Prometheus sidecars automatically into the standard deployment templates, forcing developers to reinvent telemetry for every microservice.
101
+ 6. **TicketOps Generation:** Building architectures where a developer must open a Jira ticket for an infrastructure admin to manually provision an S3 bucket. Emphasize self-service terraform modules.
102
+ 7. **Neglecting Ephemeral Environments:** Generating environments targeting *only* Staging and Production. Platform architecture must support spinning up isolated, ephemeral AWS/K8s environments instantly per-Pull-Request to isolate testing.
103
+ 8. **Hardcoding IAM Roles:** AI writes IaC where resources are given generic `AdminAccess` rather than aggressively enforcing the Principle of Least Privilege via OIDC (OpenID Connect) trust policies.
104
+ 9. **Missing the "Paved Road":** Ignoring the socio-technical aspect of the job. Forbidding developers from using experimental tech outright, instead of explaining the "Paved Road" (Supported) vs "Dirt Road" (You build it, you run it) philosophy.
105
+ 10. **State File Chaos:** Failing to explicitly define S3/GCS backend locking architecture for Terraform state, opening the company up to catastrophic infrastructure corruption when two developers run `terraform apply` concurrently.
106
+
107
+ ---
108
+
109
+ ## 🏛️ Tribunal Integration
110
+
111
+ ### ✅ Pre-Flight Self-Audit
112
+ ```
113
+ Are infrastructural patterns provided as automated, self-service "Golden Path" templates?
114
+ ✅ Has infrastructure been codified securely in declarative formats (Terraform, Tofu, Pulumi)?
115
+ Is the CI/CD pipeline architected specifically around Pull-based GitOps (e.g., ArgoCD/Flux)?
116
+ ✅ Were the complexities of Kubernetes/AWS deliberately abstracted away from the product developers?
117
+ Does the architectural plan integrate telemetry (logs/metrics) seamlessly by default?
118
+ Was the IaC environment actively secured by enforcing an S3/Remote backend state locking mechanism?
119
+ Are IAM and trust boundaries scoped to absolute Least Privilege methodologies?
120
+ ✅ Did I reject manual UI configuration (ClickOps) in favor of automated procedural representations?
121
+ Is the pipeline resilient enough to generate ephemeral environments isolated to specific Pull Requests?
122
+ ✅ Has the "Platform as a Product" mindset been established, prioritizing high developer UX?
123
+ ```