symfonia-ai-tools 1.4.2 → 1.5.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.
- package/README.md +289 -287
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,116 +1,117 @@
|
|
|
1
1
|
# symfonia-ai-tools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Interactive AI tooling configurator for projects. One `npx` — complete setup for Claude Code, GitHub Copilot, Cursor, Gemini, Junie, and GSD.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Required: Node.js 18+
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
npx symfonia-ai-tools@latest
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
You can also install globally:
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
npm install -g symfonia-ai-tools
|
|
17
17
|
symfonia-ai-tools
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
1.
|
|
22
|
-
2.
|
|
23
|
-
3.
|
|
24
|
-
4.
|
|
25
|
-
5.
|
|
26
|
-
6.
|
|
27
|
-
7.
|
|
20
|
+
The configurator guides you through:
|
|
21
|
+
1. Language selection (Polish / English)
|
|
22
|
+
2. Project type, description, tech stack
|
|
23
|
+
3. Instruction & skill packs (checkboxes)
|
|
24
|
+
4. AI tools to configure (checkboxes)
|
|
25
|
+
5. Skills to install (checkboxes — base + from selected packs)
|
|
26
|
+
6. Paths, commands, CI pipeline, JIRA prefix
|
|
27
|
+
7. MCP servers (checkboxes + tokens)
|
|
28
|
+
8. CLI installation (checkboxes)
|
|
28
29
|
|
|
29
|
-
|
|
30
|
+
The entire configurator uses arrow-key navigation — no typing numbers.
|
|
30
31
|
|
|
31
|
-
|
|
32
|
-
- **
|
|
33
|
-
- **
|
|
32
|
+
Finally, it automatically runs GSD:
|
|
33
|
+
- **New project** → `/gsd-new-project`
|
|
34
|
+
- **Existing project** → `/gsd-map-codebase` → `/gsd-new-project`
|
|
34
35
|
|
|
35
|
-
###
|
|
36
|
+
### Installation modes (existing project)
|
|
36
37
|
|
|
37
|
-
|
|
|
38
|
-
|
|
39
|
-
| **
|
|
40
|
-
| **
|
|
41
|
-
| **
|
|
38
|
+
| Mode | Description |
|
|
39
|
+
|------|-------------|
|
|
40
|
+
| **Overwrite everything** | Full reinstall — overwrites existing files |
|
|
41
|
+
| **Only new files** | Adds missing files, keeps existing ones |
|
|
42
|
+
| **MCP only** | Configures MCP servers without touching the rest |
|
|
42
43
|
|
|
43
44
|
---
|
|
44
45
|
|
|
45
|
-
##
|
|
46
|
+
## Architecture: Single Source of Truth
|
|
46
47
|
|
|
47
|
-
|
|
48
|
+
All AI tools read the same rules from one place:
|
|
48
49
|
|
|
49
50
|
```
|
|
50
|
-
.ai/guidelines.md ←
|
|
51
|
+
.ai/guidelines.md ← SINGLE SOURCE OF TRUTH
|
|
51
52
|
│
|
|
52
|
-
├── CLAUDE.md (
|
|
53
|
+
├── CLAUDE.md (reference)
|
|
53
54
|
├── .github/copilot-instructions.md (pointer)
|
|
54
55
|
├── .cursor/rules/global.mdc (pointer)
|
|
55
|
-
├── .gemini/settings.json (
|
|
56
|
+
├── .gemini/settings.json (reference)
|
|
56
57
|
└── .junie/guidelines.md (pointer)
|
|
57
58
|
```
|
|
58
59
|
|
|
59
|
-
|
|
60
|
+
Change `.ai/guidelines.md` — all agents will see it.
|
|
60
61
|
|
|
61
62
|
---
|
|
62
63
|
|
|
63
|
-
##
|
|
64
|
+
## Packs
|
|
64
65
|
|
|
65
|
-
|
|
66
|
+
Instead of choosing a single stack, you pick any combination of instruction & skill packs — with checkboxes. Each pack declares its instructions, skills, and required placeholders in `pack.json`.
|
|
66
67
|
|
|
67
|
-
###
|
|
68
|
+
### Available packs
|
|
68
69
|
|
|
69
|
-
|
|
|
70
|
-
|
|
71
|
-
| **Vue 3 + TypeScript** | 6
|
|
72
|
-
| **Vitest** | 1
|
|
73
|
-
| **Storybook** | 1
|
|
74
|
-
| **Laravel + PHP** | 4
|
|
75
|
-
| **Playwright** | 1
|
|
76
|
-
| **Docker** | 1
|
|
70
|
+
| Pack | Contents | Default |
|
|
71
|
+
|------|----------|---------|
|
|
72
|
+
| **Vue 3 + TypeScript** | 6 instructions, 3 skills | Yes |
|
|
73
|
+
| **Vitest** | 1 instruction | Yes |
|
|
74
|
+
| **Storybook** | 1 instruction | No |
|
|
75
|
+
| **Laravel + PHP** | 4 instructions, 7 skills | No |
|
|
76
|
+
| **Playwright E2E** | 1 instruction, 3 skills | No |
|
|
77
|
+
| **Docker** | 1 instruction | No |
|
|
77
78
|
|
|
78
|
-
|
|
79
|
+
Packs are independent — you can combine e.g. Vue 3 + Playwright + Docker.
|
|
79
80
|
|
|
80
81
|
---
|
|
81
82
|
|
|
82
|
-
##
|
|
83
|
+
## What it installs
|
|
83
84
|
|
|
84
|
-
###
|
|
85
|
+
### Per-tool files
|
|
85
86
|
|
|
86
|
-
|
|
|
87
|
-
|
|
87
|
+
| Tool | Files |
|
|
88
|
+
|------|-------|
|
|
88
89
|
| **Claude Code** | `CLAUDE.md`, `.claude/settings.local.json` (permissions + deny rules) |
|
|
89
90
|
| **GitHub Copilot** | `.github/copilot-instructions.md`, `.github/pull_request_template.md`, `.github/instructions/`, `.github/prompts/`, `.github/skills/` |
|
|
90
91
|
| **Cursor IDE** | `.cursor/rules/global.mdc`, `.cursor/mcp.json` |
|
|
91
92
|
| **Gemini** | `.gemini/settings.json` |
|
|
92
93
|
| **JetBrains Junie** | `.junie/guidelines.md` |
|
|
93
94
|
|
|
94
|
-
###
|
|
95
|
+
### Shared files
|
|
95
96
|
|
|
96
|
-
|
|
|
97
|
-
|
|
98
|
-
| `.ai/guidelines.md` |
|
|
99
|
-
| `.ai/instructions/` |
|
|
100
|
-
| `.ai/prompts/` | Reusable
|
|
101
|
-
| `.ai/skills/` |
|
|
102
|
-
| `.ai/context/` |
|
|
97
|
+
| File | Description |
|
|
98
|
+
|------|-------------|
|
|
99
|
+
| `.ai/guidelines.md` | Main project rules (source of truth) |
|
|
100
|
+
| `.ai/instructions/` | Contextual instructions per file type |
|
|
101
|
+
| `.ai/prompts/` | Reusable AI prompts |
|
|
102
|
+
| `.ai/skills/` | Skills — step-by-step workflows |
|
|
103
|
+
| `.ai/context/` | Project context (architecture, API spec, glossary) |
|
|
103
104
|
| `commit-instructions.md` | Commit conventions + branch naming |
|
|
104
|
-
| `.gitignore` | Pre-
|
|
105
|
-
| `.editorconfig` |
|
|
105
|
+
| `.gitignore` | Pre-configured (AI tokens, .env, IDE) |
|
|
106
|
+
| `.editorconfig` | Consistent formatting (utf-8, lf, spaces) |
|
|
106
107
|
|
|
107
108
|
---
|
|
108
109
|
|
|
109
|
-
## Instructions (
|
|
110
|
+
## Instructions (contextual instructions)
|
|
110
111
|
|
|
111
|
-
Instructions
|
|
112
|
+
Instructions are files with rules that AI applies automatically when working with matching files. Each instruction has an `applyTo` frontmatter with a glob pattern.
|
|
112
113
|
|
|
113
|
-
###
|
|
114
|
+
### How they work
|
|
114
115
|
|
|
115
116
|
```yaml
|
|
116
117
|
---
|
|
@@ -120,206 +121,206 @@ applyTo: "**/*.vue"
|
|
|
120
121
|
...
|
|
121
122
|
```
|
|
122
123
|
|
|
123
|
-
|
|
124
|
+
When AI opens/edits a file matching `applyTo`, it automatically loads those instructions as context.
|
|
124
125
|
|
|
125
|
-
### Vue 3 + TypeScript (6
|
|
126
|
+
### Vue 3 + TypeScript (6 instructions)
|
|
126
127
|
|
|
127
|
-
|
|
|
128
|
-
|
|
128
|
+
| Instruction | applyTo | What it teaches AI |
|
|
129
|
+
|-------------|---------|-------------------|
|
|
129
130
|
| `vue.instructions.md` | `**/*.vue` | Composition API, defineProps, withDefaults, template order |
|
|
130
|
-
| `store.instructions.md` | `**/*.store.ts, **/stores/**` | Pinia setup syntax, ref/computed,
|
|
131
|
-
| `api.instructions.md` | `**/*Service*.ts, **/api/**` | useApi singleton,
|
|
132
|
-
| `coding-conventions.instructions.md` | `**/*.vue, **/*.ts, **/*.scss` | Naming (camelCase/PascalCase), I/E/T
|
|
131
|
+
| `store.instructions.md` | `**/*.store.ts, **/stores/**` | Pinia setup syntax, ref/computed, async actions |
|
|
132
|
+
| `api.instructions.md` | `**/*Service*.ts, **/api/**` | useApi singleton, interceptors, error handling |
|
|
133
|
+
| `coding-conventions.instructions.md` | `**/*.vue, **/*.ts, **/*.scss` | Naming (camelCase/PascalCase), I/E/T prefixes, CSS single-dash |
|
|
133
134
|
| `composables.instructions.md` | `**/composables/**, **/use*.ts` | useAsyncDataLoader, form composable, filter composable |
|
|
134
135
|
| `forms.instructions.md` | `**/*Form*.vue, **/validation*` | ValidationBuilder, computed validation, 422 handling |
|
|
135
136
|
|
|
136
|
-
### Vitest (1
|
|
137
|
+
### Vitest (1 instruction)
|
|
137
138
|
|
|
138
|
-
|
|
|
139
|
-
|
|
140
|
-
| `vitest.instructions.md` | `**/*.test.ts, **/*.spec.ts` | mount, shallowMount, mocking, data-testid
|
|
139
|
+
| Instruction | applyTo | What it teaches AI |
|
|
140
|
+
|-------------|---------|-------------------|
|
|
141
|
+
| `vitest.instructions.md` | `**/*.test.ts, **/*.spec.ts` | mount, shallowMount, mocking, data-testid selectors |
|
|
141
142
|
|
|
142
|
-
### Storybook (1
|
|
143
|
+
### Storybook (1 instruction)
|
|
143
144
|
|
|
144
|
-
|
|
|
145
|
-
|
|
146
|
-
| `storybook.instructions.md` | `**/*.stories.ts` | Meta + StoryObj, autodocs, argTypes,
|
|
145
|
+
| Instruction | applyTo | What it teaches AI |
|
|
146
|
+
|-------------|---------|-------------------|
|
|
147
|
+
| `storybook.instructions.md` | `**/*.stories.ts` | Meta + StoryObj, autodocs, argTypes, variants |
|
|
147
148
|
|
|
148
|
-
### Laravel + PHP (4
|
|
149
|
+
### Laravel + PHP (4 instructions)
|
|
149
150
|
|
|
150
|
-
|
|
|
151
|
-
|
|
152
|
-
| `module.instructions.md` | `**/Modules/**` |
|
|
151
|
+
| Instruction | applyTo | What it teaches AI |
|
|
152
|
+
|-------------|---------|-------------------|
|
|
153
|
+
| `module.instructions.md` | `**/Modules/**` | Module structure, module.json, ServiceProvider |
|
|
153
154
|
| `service-repository.instructions.md` | `**/*Service*.php, **/*Repository*.php` | CQRS (Command/Query repos), readonly services, DTO |
|
|
154
|
-
| `api-resource.instructions.md` | `**/*Resource*.php, **/*Request*.php` | Resources
|
|
155
|
+
| `api-resource.instructions.md` | `**/*Resource*.php, **/*Request*.php` | Resources with whenLoaded(), Form Requests, Policies |
|
|
155
156
|
| `testing.instructions.md` | `**/*Test*.php, **/tests/**` | PHPUnit, data providers, factories, Laravel fakes |
|
|
156
157
|
|
|
157
|
-
### Playwright (1
|
|
158
|
+
### Playwright (1 instruction)
|
|
158
159
|
|
|
159
|
-
|
|
|
160
|
-
|
|
161
|
-
| `playwright.instructions.md` | `**/*.spec.ts (e2e)` | Page Object Model,
|
|
160
|
+
| Instruction | applyTo | What it teaches AI |
|
|
161
|
+
|-------------|---------|-------------------|
|
|
162
|
+
| `playwright.instructions.md` | `**/*.spec.ts (e2e)` | Page Object Model, selectors, waiting for elements |
|
|
162
163
|
|
|
163
|
-
### Docker (1
|
|
164
|
+
### Docker (1 instruction)
|
|
164
165
|
|
|
165
|
-
|
|
|
166
|
-
|
|
167
|
-
| `docker.instructions.md` | `**/Dockerfile, **/docker-compose*` | Artisan
|
|
166
|
+
| Instruction | applyTo | What it teaches AI |
|
|
167
|
+
|-------------|---------|-------------------|
|
|
168
|
+
| `docker.instructions.md` | `**/Dockerfile, **/docker-compose*` | Artisan in container, multi-stage build |
|
|
168
169
|
|
|
169
|
-
###
|
|
170
|
+
### Adding your own instruction
|
|
170
171
|
|
|
171
|
-
1.
|
|
172
|
+
1. Create a file in `.ai/instructions/`:
|
|
172
173
|
```markdown
|
|
173
174
|
---
|
|
174
175
|
applyTo: "**/*.graphql"
|
|
175
176
|
---
|
|
176
177
|
# GraphQL Instructions
|
|
177
|
-
|
|
178
|
+
Rules specific to GraphQL files...
|
|
178
179
|
```
|
|
179
|
-
2. Mirror
|
|
180
|
+
2. Mirror to `.github/instructions/` happens automatically if Copilot is selected
|
|
180
181
|
|
|
181
182
|
---
|
|
182
183
|
|
|
183
|
-
## Guidelines —
|
|
184
|
+
## Guidelines — what it contains
|
|
184
185
|
|
|
185
|
-
|
|
186
|
-
1. **Header** — project overview, tech stack,
|
|
187
|
-
2. **
|
|
186
|
+
The `.ai/guidelines.md` file is assembled automatically from:
|
|
187
|
+
1. **Header** — project overview, tech stack, commands, CI, commit rules, branch naming, Forbidden section, testing strategy
|
|
188
|
+
2. **Pack sections** — each selected pack appends its section (e.g. Vue 3 architecture, Laravel conventions)
|
|
188
189
|
|
|
189
|
-
###
|
|
190
|
+
### Sections in guidelines
|
|
190
191
|
|
|
191
|
-
|
|
|
192
|
-
|
|
193
|
-
| Project Overview |
|
|
192
|
+
| Section | Contents |
|
|
193
|
+
|---------|----------|
|
|
194
|
+
| Project Overview | Name, description, tech stack |
|
|
194
195
|
| Commands | test, build, lint, CI |
|
|
195
|
-
| Commits & Branches |
|
|
196
|
-
| CI Pipeline |
|
|
197
|
-
| Forbidden |
|
|
198
|
-
| Testing Strategy |
|
|
199
|
-
| Skills | Pointer
|
|
200
|
-
| Instructions | Pointer
|
|
201
|
-
| Context | Pointer
|
|
196
|
+
| Commits & Branches | Commit format, branch naming convention |
|
|
197
|
+
| CI Pipeline | Command that must pass before PR |
|
|
198
|
+
| Forbidden | What AI must NOT do without approval |
|
|
199
|
+
| Testing Strategy | When to use unit, integration, E2E, regression |
|
|
200
|
+
| Skills | Pointer to `.ai/skills/` |
|
|
201
|
+
| Instructions | Pointer to `.ai/instructions/` |
|
|
202
|
+
| Context | Pointer to `.ai/context/` |
|
|
202
203
|
|
|
203
204
|
---
|
|
204
205
|
|
|
205
|
-
## Skills (
|
|
206
|
+
## Skills (step-by-step workflows)
|
|
206
207
|
|
|
207
|
-
Skills
|
|
208
|
+
Skills are ready-made procedures that AI executes step by step. Each skill has a trigger, input, steps, and verification checklist.
|
|
208
209
|
|
|
209
|
-
###
|
|
210
|
+
### How to use
|
|
210
211
|
|
|
211
|
-
|
|
212
|
+
Tell the AI:
|
|
212
213
|
|
|
213
214
|
```
|
|
214
|
-
"
|
|
215
|
-
"
|
|
216
|
-
"
|
|
217
|
-
"wtf" —
|
|
215
|
+
"Using skill smf-new-module, create a users module"
|
|
216
|
+
"Run skill smf-debug for the TypeError in UserService"
|
|
217
|
+
"Follow skill smf-pr-prepare"
|
|
218
|
+
"wtf" — quick session status
|
|
218
219
|
```
|
|
219
220
|
|
|
220
|
-
AI
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
###
|
|
225
|
-
|
|
226
|
-
| Skill |
|
|
227
|
-
|
|
228
|
-
| `smf-debug` |
|
|
229
|
-
| `smf-refactor` |
|
|
230
|
-
| `smf-write-tests` |
|
|
231
|
-
| `smf-pr-prepare` |
|
|
232
|
-
| `smf-hotfix` |
|
|
233
|
-
| `smf-wtf` |
|
|
234
|
-
| `smf-babysit-prs` |
|
|
235
|
-
| `smf-my-prs` |
|
|
236
|
-
| `smf-pr-dashboard` |
|
|
237
|
-
| `smf-jira-task` |
|
|
238
|
-
| `smf-jira-explorer` |
|
|
239
|
-
| `smf-fill-worklogs` |
|
|
240
|
-
| `smf-grafana-logs` |
|
|
241
|
-
| `smf-aws-analysis` |
|
|
242
|
-
| `smf-figma-analysis` |
|
|
243
|
-
|
|
244
|
-
###
|
|
245
|
-
|
|
246
|
-
| Skill |
|
|
247
|
-
|
|
248
|
-
| `smf-new-module` |
|
|
249
|
-
| `smf-new-component` |
|
|
250
|
-
| `smf-api-integration` |
|
|
251
|
-
|
|
252
|
-
###
|
|
253
|
-
|
|
254
|
-
| Skill |
|
|
255
|
-
|
|
256
|
-
| `smf-new-module` |
|
|
257
|
-
| `smf-new-endpoint` |
|
|
258
|
-
| `smf-migration` |
|
|
259
|
-
| `smf-queued-job` | Job / Event / Listener | Job class → retry/backoff → failed handler →
|
|
260
|
-
| `smf-testing-feature` |
|
|
261
|
-
| `smf-testing-unit` |
|
|
262
|
-
| `smf-testing-manual` |
|
|
263
|
-
|
|
264
|
-
###
|
|
265
|
-
|
|
266
|
-
| Skill |
|
|
267
|
-
|
|
268
|
-
| `smf-playwright` |
|
|
269
|
-
| `smf-playwright-record` |
|
|
270
|
-
| `smf-playwright-codereview` |
|
|
271
|
-
|
|
272
|
-
###
|
|
273
|
-
|
|
274
|
-
1.
|
|
275
|
-
2.
|
|
276
|
-
3.
|
|
277
|
-
4.
|
|
221
|
+
AI reads `SKILL.md` and executes the steps sequentially.
|
|
222
|
+
|
|
223
|
+
All skills have the `smf-` prefix (Symfonia). The configurator lets you choose which skills to install with checkboxes.
|
|
224
|
+
|
|
225
|
+
### Base skills (15 skills)
|
|
226
|
+
|
|
227
|
+
| Skill | Purpose | When to use | Requires |
|
|
228
|
+
|-------|---------|-------------|----------|
|
|
229
|
+
| `smf-debug` | Systematic debugging | Bug, error, unexpected behavior | — |
|
|
230
|
+
| `smf-refactor` | Safe refactoring | Extracting, simplifying, moving code | — |
|
|
231
|
+
| `smf-write-tests` | Adding tests | Existing code without test coverage | — |
|
|
232
|
+
| `smf-pr-prepare` | PR preparation | Before push — self-review, cleanup, description | — |
|
|
233
|
+
| `smf-hotfix` | Quick production fix | Branch from main, minimal fix, regression test | — |
|
|
234
|
+
| `smf-wtf` | Quick session status | "Where was I?", resume after break | — |
|
|
235
|
+
| `smf-babysit-prs` | PR review monitoring | Periodic checking for new PRs to review | gh CLI |
|
|
236
|
+
| `smf-my-prs` | Own PR status | Check approvals, comments | gh CLI |
|
|
237
|
+
| `smf-pr-dashboard` | PR dashboard | Combo babysit-prs + my-prs with loop | gh CLI |
|
|
238
|
+
| `smf-jira-task` | Full Jira workflow | Ticket → branch → impl → PR → Jira update | Jira MCP + gh CLI |
|
|
239
|
+
| `smf-jira-explorer` | Browse Jira | Sprint, epic, backlog, search, statistics | Jira MCP |
|
|
240
|
+
| `smf-fill-worklogs` | Fill worklogs | Populate hours based on git commits | Jira MCP |
|
|
241
|
+
| `smf-grafana-logs` | Grafana logs | Production debugging — Loki queries, error analysis | Grafana MCP |
|
|
242
|
+
| `smf-aws-analysis` | AWS analysis | Service selection, architecture, costs | Context7 MCP |
|
|
243
|
+
| `smf-figma-analysis` | Figma mockup analysis | Figma selection link → UI specification | Figma MCP |
|
|
244
|
+
|
|
245
|
+
### Vue 3 + TypeScript skills (3 skills)
|
|
246
|
+
|
|
247
|
+
| Skill | Purpose | When to use |
|
|
248
|
+
|-------|---------|-------------|
|
|
249
|
+
| `smf-new-module` | New module from scratch | types → service → store → composables → views → routes → tests |
|
|
250
|
+
| `smf-new-component` | New component | Component + story + test + data-testid |
|
|
251
|
+
| `smf-api-integration` | API integration | types + mapper → service → store → composable → view |
|
|
252
|
+
|
|
253
|
+
### Laravel + PHP skills (7 skills)
|
|
254
|
+
|
|
255
|
+
| Skill | Purpose | When to use |
|
|
256
|
+
|-------|---------|-------------|
|
|
257
|
+
| `smf-new-module` | New module from scratch | model → migration → CQRS repos → service → DTO → controller → tests |
|
|
258
|
+
| `smf-new-endpoint` | New API endpoint | request → controller → DTO → service → resource → policy → route → tests |
|
|
259
|
+
| `smf-migration` | DB migration | create/modify table → rollback test → model update → factory |
|
|
260
|
+
| `smf-queued-job` | Job / Event / Listener | Job class → retry/backoff → failed handler → idempotency → tests |
|
|
261
|
+
| `smf-testing-feature` | Feature tests (HTTP/DB) | Feature test conventions, delta pattern, data resilience |
|
|
262
|
+
| `smf-testing-unit` | Unit tests | Isolated tests without DB, PHPUnit mocks, data providers |
|
|
263
|
+
| `smf-testing-manual` | Manual HTTP tests | JetBrains HTTP Client — `.http` files for interactive API testing |
|
|
264
|
+
|
|
265
|
+
### Playwright skills (3 skills)
|
|
266
|
+
|
|
267
|
+
| Skill | Purpose | When to use |
|
|
268
|
+
|-------|---------|-------------|
|
|
269
|
+
| `smf-playwright` | New E2E test | Page Object → scenario → assertions |
|
|
270
|
+
| `smf-playwright-record` | Record test | codegen → cleanup → Page Object |
|
|
271
|
+
| `smf-playwright-codereview` | E2E test review | Playwright test quality checklist |
|
|
272
|
+
|
|
273
|
+
### Creating your own skill
|
|
274
|
+
|
|
275
|
+
1. Create a directory in `.ai/skills/smf-your-skill/`
|
|
276
|
+
2. Copy the template: `cp .ai/skills/TEMPLATE.md .ai/skills/smf-your-skill/SKILL.md`
|
|
277
|
+
3. Fill in sections: Trigger, Input, Steps, Verification checklist
|
|
278
|
+
4. If using Copilot, copy to `.github/skills/`
|
|
278
279
|
|
|
279
280
|
---
|
|
280
281
|
|
|
281
|
-
## Prompts (reusable
|
|
282
|
+
## Prompts (reusable prompts)
|
|
282
283
|
|
|
283
|
-
|
|
284
|
+
Prompts are ready-made commands for AI to execute complex tasks in a single invocation.
|
|
284
285
|
|
|
285
|
-
###
|
|
286
|
+
### Available prompts
|
|
286
287
|
|
|
287
|
-
| Prompt |
|
|
288
|
-
|
|
289
|
-
| `codereview.prompt.md` |
|
|
290
|
-
| `security-review.prompt.md` |
|
|
291
|
-
| `duplicate-code-analysis.prompt.md` |
|
|
288
|
+
| Prompt | Purpose | How to use |
|
|
289
|
+
|--------|---------|------------|
|
|
290
|
+
| `codereview.prompt.md` | Comprehensive branch code review | "Run code review per `.ai/prompts/codereview.prompt.md`" |
|
|
291
|
+
| `security-review.prompt.md` | Security audit (OWASP Top 10) | "Run security review per `.ai/prompts/security-review.prompt.md`" |
|
|
292
|
+
| `duplicate-code-analysis.prompt.md` | Code duplication detection | "Find duplicates per `.ai/prompts/duplicate-code-analysis.prompt.md`" |
|
|
292
293
|
|
|
293
|
-
###
|
|
294
|
+
### Usage across tools
|
|
294
295
|
|
|
295
296
|
**Claude Code:**
|
|
296
297
|
```
|
|
297
|
-
|
|
298
|
+
Read .ai/prompts/codereview.prompt.md and review this branch
|
|
298
299
|
```
|
|
299
300
|
|
|
300
301
|
**GitHub Copilot Chat:**
|
|
301
302
|
```
|
|
302
|
-
@workspace
|
|
303
|
+
@workspace Run code review per .github/prompts/codereview.prompt.md
|
|
303
304
|
```
|
|
304
305
|
|
|
305
306
|
---
|
|
306
307
|
|
|
307
|
-
##
|
|
308
|
+
## MCP Servers
|
|
308
309
|
|
|
309
|
-
MCP (Model Context Protocol)
|
|
310
|
+
MCP (Model Context Protocol) allows AI to communicate with external systems.
|
|
310
311
|
|
|
311
|
-
|
|
|
312
|
-
|
|
313
|
-
| **Jira Cloud** |
|
|
314
|
-
| **Bitbucket Cloud** |
|
|
315
|
-
| **Figma** |
|
|
316
|
-
| **Grafana** |
|
|
317
|
-
| **Context7** |
|
|
312
|
+
| Server | Purpose | Requires token |
|
|
313
|
+
|--------|---------|----------------|
|
|
314
|
+
| **Jira Cloud** | Fetch tickets for AI context | Yes |
|
|
315
|
+
| **Bitbucket Cloud** | Repository integration | Yes |
|
|
316
|
+
| **Figma** | UI mockup analysis | Yes |
|
|
317
|
+
| **Grafana** | Application logs (Loki) | Yes |
|
|
318
|
+
| **Context7** | Library documentation | No |
|
|
318
319
|
|
|
319
|
-
###
|
|
320
|
+
### Where to generate tokens
|
|
320
321
|
|
|
321
|
-
|
|
|
322
|
-
|
|
322
|
+
| Service | Link |
|
|
323
|
+
|---------|------|
|
|
323
324
|
| Jira API Token | https://id.atlassian.com/manage-profile/security/api-tokens |
|
|
324
325
|
| Bitbucket App Password | https://bitbucket.org/account/settings/app-passwords/ |
|
|
325
326
|
| Figma Access Token | Figma → Settings → Personal access tokens |
|
|
@@ -327,10 +328,10 @@ MCP (Model Context Protocol) pozwala AI na komunikacje z zewnetrznymi systemami.
|
|
|
327
328
|
|
|
328
329
|
### MCP pre-selection
|
|
329
330
|
|
|
330
|
-
|
|
331
|
+
Skills declare required MCP servers. When you select e.g. `smf-jira-task`, Jira Cloud will be automatically checked in the MCP step with information about which skills require it.
|
|
331
332
|
|
|
332
|
-
| Skill |
|
|
333
|
-
|
|
333
|
+
| Skill | Requires MCP |
|
|
334
|
+
|-------|-------------|
|
|
334
335
|
| `smf-jira-task`, `smf-jira-explorer`, `smf-fill-worklogs` | Jira Cloud |
|
|
335
336
|
| `smf-grafana-logs` | Grafana |
|
|
336
337
|
| `smf-aws-analysis` | Context7 |
|
|
@@ -338,66 +339,66 @@ Skille deklaruja wymagane serwery MCP. Gdy wybierzesz np. `smf-jira-task`, Jira
|
|
|
338
339
|
|
|
339
340
|
### Auto-detect
|
|
340
341
|
|
|
341
|
-
|
|
342
|
-
- **
|
|
343
|
-
- **JIRA prefix** —
|
|
342
|
+
The configurator automatically detects from the git repository:
|
|
343
|
+
- **Platform** — GitHub / Bitbucket / GitLab (from `git remote`)
|
|
344
|
+
- **JIRA prefix** — from branch names (e.g. `feature/PROJ-123` → `PROJ`)
|
|
344
345
|
- **Base branch** — develop / main / master
|
|
345
346
|
|
|
346
|
-
|
|
347
|
+
Detected values are suggested as defaults — you can change them.
|
|
347
348
|
|
|
348
|
-
###
|
|
349
|
+
### Automatic configuration
|
|
349
350
|
|
|
350
|
-
|
|
351
|
-
-
|
|
352
|
-
-
|
|
353
|
-
-
|
|
351
|
+
The installer automatically:
|
|
352
|
+
- Saves config to `.claude/settings.local.json` and `.cursor/mcp.json`
|
|
353
|
+
- Registers servers in Claude CLI (`claude mcp add -s project`)
|
|
354
|
+
- Verification: `claude mcp list`
|
|
354
355
|
|
|
355
356
|
---
|
|
356
357
|
|
|
357
358
|
## GSD (Get Shit Done)
|
|
358
359
|
|
|
359
|
-
GSD
|
|
360
|
+
GSD is a system for structuring AI work — planning, execution, and verification in a repeatable process.
|
|
360
361
|
|
|
361
|
-
###
|
|
362
|
+
### Why it's required
|
|
362
363
|
|
|
363
|
-
-
|
|
364
|
-
-
|
|
365
|
-
-
|
|
364
|
+
- Prevents **context rot** (AI quality degradation during long sessions)
|
|
365
|
+
- Structures work into phases with checkpoints
|
|
366
|
+
- Automatically maps the codebase in existing projects
|
|
366
367
|
|
|
367
|
-
###
|
|
368
|
+
### Installation
|
|
368
369
|
|
|
369
370
|
```bash
|
|
370
371
|
npx get-shit-done-cc@latest
|
|
371
372
|
```
|
|
372
373
|
|
|
373
|
-
###
|
|
374
|
+
### Key commands
|
|
374
375
|
|
|
375
|
-
|
|
|
376
|
-
|
|
377
|
-
| `/gsd-new-project` |
|
|
378
|
-
| `/gsd-plan-phase` |
|
|
379
|
-
| `/gsd-execute-phase` |
|
|
380
|
-
| `/gsd-verify-work` |
|
|
381
|
-
| `/gsd-progress` | Status
|
|
382
|
-
| `/gsd-debug` |
|
|
383
|
-
| `/gsd-map-codebase` |
|
|
376
|
+
| Command | Purpose |
|
|
377
|
+
|---------|---------|
|
|
378
|
+
| `/gsd-new-project` | Project initialization |
|
|
379
|
+
| `/gsd-plan-phase` | Phase planning |
|
|
380
|
+
| `/gsd-execute-phase` | Execution |
|
|
381
|
+
| `/gsd-verify-work` | UAT verification |
|
|
382
|
+
| `/gsd-progress` | Status and next steps |
|
|
383
|
+
| `/gsd-debug` | Systematic debugging |
|
|
384
|
+
| `/gsd-map-codebase` | Existing code mapping |
|
|
384
385
|
|
|
385
386
|
---
|
|
386
387
|
|
|
387
|
-
##
|
|
388
|
+
## Installed file structure
|
|
388
389
|
|
|
389
390
|
```
|
|
390
|
-
|
|
391
|
+
project/
|
|
391
392
|
├── .ai/
|
|
392
|
-
│ ├── guidelines.md # Source of truth (header +
|
|
393
|
-
│ ├── instructions/ #
|
|
393
|
+
│ ├── guidelines.md # Source of truth (header + selected packs)
|
|
394
|
+
│ ├── instructions/ # Contextual instructions (applyTo)
|
|
394
395
|
│ │ ├── vue.instructions.md
|
|
395
396
|
│ │ └── ...
|
|
396
|
-
│ ├── prompts/ # Reusable
|
|
397
|
+
│ ├── prompts/ # Reusable prompts
|
|
397
398
|
│ │ ├── codereview.prompt.md
|
|
398
399
|
│ │ ├── security-review.prompt.md
|
|
399
400
|
│ │ └── duplicate-code-analysis.prompt.md
|
|
400
|
-
│ ├── skills/ # Workflow
|
|
401
|
+
│ ├── skills/ # Workflow skills
|
|
401
402
|
│ │ ├── smf-debug/SKILL.md
|
|
402
403
|
│ │ ├── smf-refactor/SKILL.md
|
|
403
404
|
│ │ ├── smf-write-tests/SKILL.md
|
|
@@ -414,16 +415,16 @@ projekt/
|
|
|
414
415
|
│ │ ├── smf-aws-analysis/SKILL.md
|
|
415
416
|
│ │ ├── smf-figma-analysis/SKILL.md
|
|
416
417
|
│ │ └── [smf-pack-specific]/SKILL.md
|
|
417
|
-
│ └── context/ #
|
|
418
|
-
│ └── README.md # (
|
|
418
|
+
│ └── context/ # Project context
|
|
419
|
+
│ └── README.md # (add architecture.md, api-spec.md, etc. here)
|
|
419
420
|
├── .claude/
|
|
420
421
|
│ └── settings.local.json # Permissions (allow/deny) + MCP servers
|
|
421
422
|
├── .github/
|
|
422
423
|
│ ├── copilot-instructions.md # Pointer → .ai/guidelines.md
|
|
423
|
-
│ ├── pull_request_template.md #
|
|
424
|
-
│ ├── instructions/ # Mirror
|
|
425
|
-
│ ├── prompts/ # Mirror
|
|
426
|
-
│ └── skills/ # Mirror
|
|
424
|
+
│ ├── pull_request_template.md # PR template
|
|
425
|
+
│ ├── instructions/ # Mirror from .ai/instructions/
|
|
426
|
+
│ ├── prompts/ # Mirror from .ai/prompts/
|
|
427
|
+
│ └── skills/ # Mirror from .ai/skills/
|
|
427
428
|
├── .cursor/
|
|
428
429
|
│ ├── rules/global.mdc # Pointer → .ai/guidelines.md
|
|
429
430
|
│ └── mcp.json # MCP servers
|
|
@@ -431,101 +432,102 @@ projekt/
|
|
|
431
432
|
│ └── settings.json # Pointer → .ai/guidelines.md
|
|
432
433
|
├── .junie/
|
|
433
434
|
│ └── guidelines.md # Pointer → .ai/guidelines.md
|
|
434
|
-
├── .editorconfig #
|
|
435
|
-
├── .gitignore # Pre-
|
|
435
|
+
├── .editorconfig # Formatting (utf-8, lf, spaces)
|
|
436
|
+
├── .gitignore # Pre-configured (AI tokens, .env)
|
|
436
437
|
├── CLAUDE.md # Claude Code entry point
|
|
437
438
|
└── commit-instructions.md # Commit conventions + branch naming
|
|
438
439
|
```
|
|
439
440
|
|
|
440
|
-
> **Mirror**: `.ai/instructions/`, `.ai/prompts
|
|
441
|
+
> **Mirror**: `.ai/instructions/`, `.ai/prompts/`, and `.ai/skills/` are automatically copied to `.github/` if GitHub Copilot is selected.
|
|
441
442
|
|
|
442
443
|
---
|
|
443
444
|
|
|
444
|
-
##
|
|
445
|
+
## Package development
|
|
445
446
|
|
|
446
|
-
###
|
|
447
|
+
### Adding a new pack
|
|
447
448
|
|
|
448
|
-
1.
|
|
449
|
-
2.
|
|
449
|
+
1. Create `templates/packs/pack-name/`
|
|
450
|
+
2. Add `pack.json`:
|
|
450
451
|
```json
|
|
451
452
|
{
|
|
452
|
-
"name": "
|
|
453
|
-
"description": "
|
|
453
|
+
"name": "Pack Name",
|
|
454
|
+
"description": "What it contains",
|
|
454
455
|
"default": false,
|
|
455
456
|
"placeholders": {
|
|
456
457
|
"MY_PLACEHOLDER": {
|
|
457
|
-
"question": "
|
|
458
|
-
"
|
|
458
|
+
"question": "Question displayed to user (Polish)",
|
|
459
|
+
"question_en": "Question displayed to user (English)",
|
|
460
|
+
"default": "default value"
|
|
459
461
|
}
|
|
460
462
|
}
|
|
461
463
|
}
|
|
462
464
|
```
|
|
463
|
-
3.
|
|
464
|
-
4.
|
|
465
|
-
5.
|
|
466
|
-
|
|
467
|
-
###
|
|
468
|
-
|
|
469
|
-
1.
|
|
470
|
-
2.
|
|
471
|
-
3.
|
|
472
|
-
|
|
473
|
-
###
|
|
474
|
-
|
|
475
|
-
| Placeholder |
|
|
476
|
-
|
|
477
|
-
| `{{PROJECT_NAME}}` |
|
|
478
|
-
| `{{PROJECT_DESCRIPTION}}` |
|
|
479
|
-
| `{{TECH_STACK}}` | Tech stack (
|
|
480
|
-
| `{{CI_COMMAND}}` |
|
|
481
|
-
| `{{MODULE_PATH}}` |
|
|
482
|
-
| `{{COMPONENT_LIB_PATH}}` |
|
|
483
|
-
| `{{COMPONENT_LIB_IMPORT}}` |
|
|
484
|
-
| `{{API_BASE_URL}}` |
|
|
485
|
-
| `{{TEST_COMMAND}}` |
|
|
486
|
-
| `{{BUILD_COMMAND}}` |
|
|
487
|
-
| `{{LINT_COMMAND}}` |
|
|
488
|
-
| `{{DOCKER_CONTAINER}}` |
|
|
489
|
-
| `{{JIRA_PREFIX}}` |
|
|
490
|
-
| `{{PLAYWRIGHT_DIR}}` |
|
|
491
|
-
| `{{BASE_URL}}` |
|
|
492
|
-
|
|
493
|
-
###
|
|
465
|
+
3. Add instructions in `_ai/instructions/` (with `applyTo` frontmatter)
|
|
466
|
+
4. Add skills in `_ai/skills/`
|
|
467
|
+
5. Optionally add `_guidelines.md` — section appended to guidelines.md
|
|
468
|
+
|
|
469
|
+
### Adding a new skill
|
|
470
|
+
|
|
471
|
+
1. Create `templates/[base|packs/pack]/_ai/skills/name/SKILL.md`
|
|
472
|
+
2. Use the structure: Trigger → Input → Steps → Verification checklist
|
|
473
|
+
3. Use `{{PLACEHOLDER}}` for values replaced during installation
|
|
474
|
+
|
|
475
|
+
### Available placeholders
|
|
476
|
+
|
|
477
|
+
| Placeholder | Description |
|
|
478
|
+
|-------------|-------------|
|
|
479
|
+
| `{{PROJECT_NAME}}` | Project name |
|
|
480
|
+
| `{{PROJECT_DESCRIPTION}}` | Short project description |
|
|
481
|
+
| `{{TECH_STACK}}` | Tech stack (free text) |
|
|
482
|
+
| `{{CI_COMMAND}}` | CI command (all checks) |
|
|
483
|
+
| `{{MODULE_PATH}}` | Modules path |
|
|
484
|
+
| `{{COMPONENT_LIB_PATH}}` | UI components path |
|
|
485
|
+
| `{{COMPONENT_LIB_IMPORT}}` | Components import path |
|
|
486
|
+
| `{{API_BASE_URL}}` | API base URL |
|
|
487
|
+
| `{{TEST_COMMAND}}` | Test command |
|
|
488
|
+
| `{{BUILD_COMMAND}}` | Build command |
|
|
489
|
+
| `{{LINT_COMMAND}}` | Lint command |
|
|
490
|
+
| `{{DOCKER_CONTAINER}}` | Docker container name |
|
|
491
|
+
| `{{JIRA_PREFIX}}` | JIRA task prefix |
|
|
492
|
+
| `{{PLAYWRIGHT_DIR}}` | Playwright directory |
|
|
493
|
+
| `{{BASE_URL}}` | Application base URL |
|
|
494
|
+
|
|
495
|
+
### Templates structure
|
|
494
496
|
|
|
495
497
|
```
|
|
496
498
|
templates/
|
|
497
|
-
├── base/ #
|
|
499
|
+
├── base/ # Shared across all packs
|
|
498
500
|
│ ├── CLAUDE.md
|
|
499
501
|
│ ├── commit-instructions.md
|
|
500
502
|
│ ├── _gitignore # → .gitignore
|
|
501
503
|
│ ├── _editorconfig # → .editorconfig
|
|
502
504
|
│ ├── _ai/ # → .ai/
|
|
503
|
-
│ │ ├── _guidelines_header.md #
|
|
504
|
-
│ │ ├── context/ #
|
|
505
|
-
│ │ ├── prompts/ # codereview, security-review,
|
|
506
|
-
│ │ └── skills/ # 15
|
|
505
|
+
│ │ ├── _guidelines_header.md # Guidelines header
|
|
506
|
+
│ │ ├── context/ # Project context
|
|
507
|
+
│ │ ├── prompts/ # codereview, security-review, duplicates
|
|
508
|
+
│ │ └── skills/ # 15 base skills (smf-*)
|
|
507
509
|
│ ├── _claude/ # → .claude/ (permissions + deny)
|
|
508
510
|
│ ├── _github/ # → .github/ (copilot pointer + PR template)
|
|
509
511
|
│ ├── _cursor/ # → .cursor/
|
|
510
512
|
│ ├── _gemini/ # → .gemini/
|
|
511
513
|
│ └── _junie/ # → .junie/
|
|
512
514
|
└── packs/
|
|
513
|
-
├── vue3/ # 6 instr. · 3
|
|
515
|
+
├── vue3/ # 6 instr. · 3 skills
|
|
514
516
|
│ ├── pack.json
|
|
515
|
-
│ ├── _guidelines.md #
|
|
517
|
+
│ ├── _guidelines.md # Section appended to guidelines
|
|
516
518
|
│ └── _ai/instructions/
|
|
517
519
|
├── vitest/ # 1 instr.
|
|
518
520
|
├── storybook/ # 1 instr.
|
|
519
|
-
├── laravel/ # 4 instr. · 7
|
|
520
|
-
├── playwright/ # 1 instr. · 3
|
|
521
|
+
├── laravel/ # 4 instr. · 7 skills
|
|
522
|
+
├── playwright/ # 1 instr. · 3 skills
|
|
521
523
|
└── docker/ # 1 instr.
|
|
522
524
|
```
|
|
523
525
|
|
|
524
|
-
>
|
|
525
|
-
>
|
|
526
|
+
> Directories with `_` prefix are converted to `.` during installation.
|
|
527
|
+
> Per-tool directories (`_claude/`, `_github/`, etc.) are only copied if the tool is selected.
|
|
526
528
|
|
|
527
529
|
---
|
|
528
530
|
|
|
529
|
-
##
|
|
531
|
+
## License
|
|
530
532
|
|
|
531
533
|
MIT
|